GRPC Documentation - BlockchainAPI

Table of Contents

• blockchain_api.proto

  • AddBlockRequest
  • CheckBlockIsCurrentChainRequest
  • CheckBlockIsCurrentChainResponse
  • GetBestHeightAndTimeResponse
  • GetBlockByHeightRequest
  • GetBlockByIDRequest
  • GetBlockExistsResponse
  • GetBlockGraphDataRequest
  • GetBlockHeaderIDsResponse
  • GetBlockHeaderRequest
  • GetBlockHeaderResponse
  • GetBlockHeadersByHeightRequest
  • GetBlockHeadersByHeightResponse
  • GetBlockHeadersFromHeightRequest
  • GetBlockHeadersFromHeightResponse
  • GetBlockHeadersFromTillRequest
  • GetBlockHeadersRequest
  • GetBlockHeadersResponse
  • GetBlockHeadersToCommonAncestorRequest
  • GetBlockInChainByHeightHashRequest
  • GetBlockIsMinedRequest
  • GetBlockIsMinedResponse
  • GetBlockLocatorRequest
  • GetBlockLocatorResponse
  • GetBlockRequest
  • GetBlockResponse
  • GetBlocksMinedNotSetResponse
  • GetBlocksRequest
  • GetBlocksResponse
  • GetLastNInvalidBlocksRequest
  • GetLastNInvalidBlocksResponse
  • GetBlocksSubtreesNotSetResponse
  • GetFSMStateResponse
  • GetFullBlockResponse
  • GetHashOfAncestorBlockRequest
  • GetHashOfAncestorBlockResponse
  • GetLastNBlocksRequest
  • GetLastNBlocksResponse
  • GetMedianTimeRequest
  • GetMedianTimeResponse
  • GetNextWorkRequiredRequest
  • GetNextWorkRequiredResponse
  • GetStateRequest
  • GetSuitableBlockRequest
  • GetSuitableBlockResponse
  • HealthResponse
  • InvalidateBlockRequest
  • LocateBlockHeadersRequest
  • LocateBlockHeadersResponse
  • Notification
  • NotificationMetadata
  • NotificationMetadata.MetadataEntry
  • RevalidateBlockRequest
  • SendFSMEventRequest
  • SetBlockMinedSetRequest
  • SetBlockProcessedAtRequest
  • SetBlockSubtreesSetRequest
  • SetStateRequest
  • StateResponse
  • SubscribeRequest

  • WaitFSMToTransitionRequest

  • FSMEventType

  • FSMStateType

  • BlockchainAPI

• Scalar Value Types

Top

blockchain_api.proto

Package blockchain_api defines the gRPC service interface for blockchain operations.

AddBlockRequest

AddBlockRequest contains data for adding a new block to the blockchain.

Field	Type	Label	Description
header	bytes		Block header
subtree_hashes	bytes	repeated	Merkle tree hashes
coinbase_tx	bytes		Coinbase transaction
transaction_count	uint64		Number of transactions
size_in_bytes	uint64		Block size
external	bool		External block flag
peer_id	string		Peer identifier

CheckBlockIsCurrentChainRequest

CheckBlockIsCurrentChainRequest checks if blocks are in the main chain.

Field	Type	Label	Description
blockIDs	uint32	repeated	List of block IDs to check

CheckBlockIsCurrentChainResponse

CheckBlockIsCurrentChainResponse indicates if blocks are in the main chain.

Field	Type	Label	Description
isPartOfCurrentChain	bool		True if blocks are in main chain

GetBestHeightAndTimeResponse

GetBestHeightAndTimeResponse contains chain tip information.

Field	Type	Label	Description
height	uint32		Current best height
time	uint32		Current median time

GetBlockByHeightRequest

GetBlockByHeightRequest represents a request to retrieve a block at a specific height.

Field	Type	Label	Description
height	uint32		Block height to retrieve

GetBlockExistsResponse

GetBlockExistsResponse indicates whether a block exists.

Field	Type	Label	Description
exists	bool		True if the block exists

GetBlockGraphDataRequest

GetBlockGraphDataRequest specifies parameters for retrieving blockchain visualization data.

Field	Type	Label	Description
period_millis	uint64		Time period in milliseconds

GetBlockHeaderIDsResponse

GetBlockHeaderIDsResponse contains block header identifiers.

Field	Type	Label	Description
ids	uint32	repeated	List of block header IDs

GetBlockHeaderRequest

GetBlockHeaderRequest requests a specific block header.

Field	Type	Label	Description
blockHash	bytes		Hash of the block

GetBlockHeaderResponse

swagger:model GetBlockHeaderResponse

Field	Type	Label	Description
blockHeader	bytes
height	uint32
tx_count	uint64
size_in_bytes	uint64
miner	string
block_time	uint32
timestamp	uint32

GetBlockHeadersByHeightRequest

swagger:model GetBlockHeadersByHeightRequest

Field	Type	Label	Description
startHeight	uint32
endHeight	uint32

GetBlockHeadersByHeightResponse

swagger:model GetBlockHeadersByHeightResponse

Field	Type	Label	Description
blockHeaders	bytes	repeated
metas	bytes	repeated

GetBlockHeadersFromHeightRequest

swagger:model GetBlockHeadersFromHeightRequest

Field	Type	Label	Description
startHeight	uint32
limit	uint32

GetBlockHeadersFromHeightResponse

swagger:model GetBlockHeadersFromHeightResponse

Field	Type	Label	Description
blockHeaders	bytes	repeated
metas	bytes	repeated

GetBlockHeadersRequest

swagger:model GetBlockHeadersRequest

Field	Type	Label	Description
startHash	bytes
numberOfHeaders	uint64

GetBlockHeadersResponse

swagger:model GetBlockHeadersResponse

Field	Type	Label	Description
blockHeaders	bytes	repeated
metas	bytes	repeated

GetBlockLocatorRequest

Field	Type	Label	Description
hash	bytes
height	uint32

GetBlockLocatorResponse

Field	Type	Label	Description
locator	bytes	repeated

GetBlockRequest

GetBlockRequest represents a request to retrieve a block by its hash.

Field	Type	Label	Description
hash	bytes		Hash of the block to retrieve

GetBlockResponse

swagger:model GetBlockResponse

Field	Type	Label	Description
header	bytes
height	uint32
coinbase_tx	bytes
transaction_count	uint64
subtree_hashes	bytes	repeated
size_in_bytes	uint64

GetBlocksMinedNotSetResponse

swagger:model GetBlocksMinedNotSetResponse

Field	Type	Label	Description
blockBytes	bytes	repeated

GetBlocksRequest

GetBlocksRequest represents a request to retrieve multiple blocks.

Field	Type	Label	Description
hash	bytes		Starting block hash
count	uint32		Number of blocks to retrieve

GetBlocksResponse

swagger:model GetBlocksResponse

Field	Type	Label	Description
blocks	bytes	repeated

GetBlocksSubtreesNotSetResponse

swagger:model GetBlocksSubtreesNotSetResponse

Field	Type	Label	Description
blockBytes	bytes	repeated

GetFSMStateResponse

swagger:model GetFSMStateResponse

Field	Type	Label	Description
state	FSMStateType

GetFullBlockResponse

Field	Type	Label	Description
full_block_bytes	bytes

GetHashOfAncestorBlockRequest

swagger:model GetHashOfAncestorBlockRequest

Field	Type	Label	Description
hash	bytes
depth	uint32

GetHashOfAncestorBlockResponse

swagger:model GetHashOfAncestorBlockResponse

Field	Type	Label	Description
hash	bytes

GetLastNBlocksRequest

swagger:model GetLastNBlocksRequest

Field	Type	Label	Description
numberOfBlocks	int64
includeOrphans	bool
fromHeight	uint32

GetLastNBlocksResponse

swagger:model GetLastNBlocksResponse

Field	Type	Label	Description
blocks	model.BlockInfo	repeated

GetMedianTimeRequest

GetMedianTimeRequest requests median time calculation for a block.

Field	Type	Label	Description
blockHash	bytes		Hash of the block

GetMedianTimeResponse

swagger:model GetMedianTimeResponse

Field	Type	Label	Description
block_header_time	uint32	repeated	This will return the nTimes of the last 11 (+1) blocks

GetNextWorkRequiredRequest

swagger:model GGetNextWorkRequiredRequest

Field	Type	Label	Description
blockHash	bytes

GetNextWorkRequiredResponse

swagger:model GGetNextWorkRequiredResponse

Field	Type	Label	Description
bits	bytes

GetStateRequest

swagger:model StateRequest

Field	Type	Label	Description
key	string

GetSuitableBlockRequest

swagger:model GetSuitableBlockRequest

Field	Type	Label	Description
hash	bytes

GetSuitableBlockResponse

swagger:model GetSuitableBlockResponse

Field	Type	Label	Description
block	model.SuitableBlock

HealthResponse

HealthResponse represents the health status of the blockchain service.

Field	Type	Label	Description
ok	bool		Overall health status
details	string		Detailed health information
timestamp	google.protobuf.Timestamp		Timestamp of the health check

InvalidateBlockRequest

swagger:model InvalidateBlockRequest

Field	Type	Label	Description
blockHash	bytes

LocateBlockHeadersRequest

Field	Type	Label	Description
locator	bytes	repeated
hash_stop	bytes
max_hashes	uint32

LocateBlockHeadersResponse

Field	Type	Label	Description
block_headers	bytes	repeated

Notification

swagger:model Notification

Field	Type	Label	Description
type	model.NotificationType
hash	bytes
base_URL	string
metadata	NotificationMetadata

NotificationMetadata

swagger:model NotificationMetadata

Field	Type	Label	Description
metadata	NotificationMetadata.MetadataEntry	repeated	define a map of string to string

NotificationMetadata.MetadataEntry

Field	Type	Label	Description
key	string
value	string

RevalidateBlockRequest

swagger:model RevalidateBlockRequest

Field	Type	Label	Description
blockHash	bytes

SendFSMEventRequest

swagger:model SendFSMEventRequest

Field	Type	Label	Description
event	FSMEventType

SetBlockMinedSetRequest

SetBlockMinedSetRequest marks a block as mined.

Field	Type	Label	Description
blockHash	bytes		Hash of the block to mark as mined

SetBlockProcessedAtRequest

SetBlockProcessedAtRequest defines parameters for setting or clearing a block's processed_at timestamp.

Field	Type	Label	Description
block_hash	bytes		Hash of the block
clear	bool		Whether to clear the timestamp

SetBlockSubtreesSetRequest

swagger:model SetBlockSubtreesSetRequest

Field	Type	Label	Description
blockHash	bytes

SetStateRequest

swagger:model SetStateRequest

Field	Type	Label	Description
key	string
data	bytes

StateResponse

swagger:model StateResponse

Field	Type	Label	Description
data	bytes

SubscribeRequest

swagger:model SubscribeRequest

Field	Type	Label	Description
source	string

WaitFSMToTransitionRequest

swagger:model WaitFSMToTransitionRequest

Field	Type	Label	Description
state	FSMStateType

GetBlockByIDRequest

GetBlockByIDRequest represents a request to retrieve a block by its ID.

Field	Type	Label	Description
id	uint64		Block ID to retrieve

GetBlockInChainByHeightHashRequest

GetBlockInChainByHeightHashRequest represents a request to retrieve a block by height in a specific chain.

Field	Type	Label	Description
height	uint32		Target block height
start_hash	bytes		Starting block hash defining the chain

FSMEventType

swagger:enum FSMEventType

Name	Number	Description
STOP	0	Stop the blockchain service
RUN	1	Run the blockchain service
CATCHUPBLOCKS	2	Start catching up blocks
LEGACYSYNC	3	Start legacy synchronization

FSMStateType

FSMStateType defines possible states of the blockchain FSM.

Name	Number	Description
IDLE	0	Service is idle
RUNNING	1	Service is running
CATCHINGBLOCKS	2	Service is catching up blocks
LEGACYSYNCING	3	Service is performing legacy sync

BlockchainAPI

BlockchainAPI service provides comprehensive blockchain management functionality.

Method Name	Request Type	Response Type	Description
HealthGRPC	.google.protobuf.Empty	HealthResponse	Checks the health status of the blockchain service.
AddBlock	AddBlockRequest	.google.protobuf.Empty	Adds a new block to the blockchain. Called by BlockValidator to add validated blocks.
GetBlock	GetBlockRequest	GetBlockResponse	Retrieves a block by its hash.
GetBlocks	GetBlocksRequest	GetBlocksResponse	Retrieves multiple blocks starting from a specific hash.
GetBlockByHeight	GetBlockByHeightRequest	GetBlockResponse	Retrieves a block at a specific height.
GetBlockByID	GetBlockByIDRequest	GetBlockResponse	Retrieves a block by its id.
GetBlockStats	.google.protobuf.Empty	.model.BlockStats	Retrieves statistical information about the blockchain.
GetBlockGraphData	GetBlockGraphDataRequest	.model.BlockDataPoints	Retrieves data points for blockchain visualization.
GetLastNBlocks	GetLastNBlocksRequest	GetLastNBlocksResponse	Retrieves the most recent N blocks from the blockchain.
GetLastNInvalidBlocks	GetLastNInvalidBlocksRequest	GetLastNInvalidBlocksResponse	Retrieves the most recent N blocks that have been marked as invalid.
GetSuitableBlock	GetSuitableBlockRequest	GetSuitableBlockResponse	Finds a suitable block for mining purposes.
GetHashOfAncestorBlock	GetHashOfAncestorBlockRequest	GetHashOfAncestorBlockResponse	Retrieves the hash of an ancestor block at a specified depth.
GetNextWorkRequired	GetNextWorkRequiredRequest	GetNextWorkRequiredResponse	Calculates the required proof of work for the next block.
GetBlockExists	GetBlockRequest	GetBlockExistsResponse	Checks if a block exists in the blockchain.
GetBlockHeaders	GetBlockHeadersRequest	GetBlockHeadersResponse	Retrieves headers for multiple blocks.
GetBlockHeadersToCommonAncestor	GetBlockHeadersToCommonAncestorRequest	GetBlockHeadersResponse	Retrieves block headers up to a common ancestor point between chains.
GetBlockHeadersFromTill	GetBlockHeadersFromTillRequest	GetBlockHeadersResponse	Retrieves block headers between two specified blocks.
GetBlockHeadersFromHeight	GetBlockHeadersFromHeightRequest	GetBlockHeadersFromHeightResponse	Retrieves block headers starting from a specific height.
GetBlockHeadersByHeight	GetBlockHeadersByHeightRequest	GetBlockHeadersByHeightResponse	Retrieves block headers between two specified heights.
GetBlockHeaderIDs	GetBlockHeadersRequest	GetBlockHeaderIDsResponse	Retrieves block header IDs for a range of blocks.
GetBestBlockHeader	.google.protobuf.Empty	GetBlockHeaderResponse	Retrieves the header of the current best block.
CheckBlockIsInCurrentChain	CheckBlockIsCurrentChainRequest	CheckBlockIsCurrentChainResponse	Verifies if specified blocks are in the main chain.
GetBlockHeader	GetBlockHeaderRequest	GetBlockHeaderResponse	Retrieves the header of a specific block.
InvalidateBlock	InvalidateBlockRequest	.google.protobuf.Empty	Marks a block as invalid in the blockchain.
RevalidateBlock	RevalidateBlockRequest	.google.protobuf.Empty	Restores a previously invalidated block.
Subscribe	SubscribeRequest	stream Notification	Creates a subscription for blockchain notifications.
SendNotification	Notification	.google.protobuf.Empty	Broadcasts a notification to subscribers.
GetState	GetStateRequest	StateResponse	Retrieves state data by key.
SetState	SetStateRequest	.google.protobuf.Empty	Stores state data with a key.
GetBlockIsMined	GetBlockIsMinedRequest	GetBlockIsMinedResponse	Checks if a block is marked as mined.
SetBlockMinedSet	SetBlockMinedSetRequest	.google.protobuf.Empty	Marks a block as mined.
SetBlockProcessedAt	SetBlockProcessedAtRequest	.google.protobuf.Empty	Sets or clears the processed_at timestamp for a block.
GetBlocksMinedNotSet	.google.protobuf.Empty	GetBlocksMinedNotSetResponse	Retrieves blocks not marked as mined.
SetBlockSubtreesSet	SetBlockSubtreesSetRequest	.google.protobuf.Empty	Marks a block's subtrees as set.
GetBlocksSubtreesNotSet	.google.protobuf.Empty	GetBlocksSubtreesNotSetResponse	Retrieves blocks with unset subtrees.
SendFSMEvent	SendFSMEventRequest	GetFSMStateResponse	Sends an event to the blockchain FSM.
GetFSMCurrentState	.google.protobuf.Empty	GetFSMStateResponse	Retrieves the current state of the FSM.
WaitFSMToTransitionToGivenState	WaitFSMToTransitionRequest	.google.protobuf.Empty	Waits for FSM to reach a specific state.
WaitUntilFSMTransitionFromIdleState	.google.protobuf.Empty	.google.protobuf.Empty	Waits for FSM to transition from IDLE state.
Run	.google.protobuf.Empty	.google.protobuf.Empty	Transitions the blockchain service to running state.
CatchUpBlocks	.google.protobuf.Empty	.google.protobuf.Empty	Initiates block catch-up process.
LegacySync	.google.protobuf.Empty	.google.protobuf.Empty	Initiates legacy synchronization process.
Idle	.google.protobuf.Empty	.google.protobuf.Empty	Marks the service as idle.
GetBlockLocator	GetBlockLocatorRequest	GetBlockLocatorResponse	Retrieves a block locator for chain synchronization.
LocateBlockHeaders	LocateBlockHeadersRequest	LocateBlockHeadersResponse	Finds block headers using a locator.
GetBestHeightAndTime	.google.protobuf.Empty	GetBestHeightAndTimeResponse	Retrieves the current best height and median time.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)

---