GRPC Documentation - BlockchainAPI
Top
Package blockchain_api defines the gRPC service interface for blockchain operations.
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
optionMinedSet
bool
Option to mark block as mined
optionSubtreesSet
bool
Option to mark subtrees as set
optionInvalid
bool
Option to invalidate block when adding
optionID
uint64
Optional block ID
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 represents a request to retrieve a block at a specific height.
Field
Type
Label
Description
height
uint32
Block height to retrieve
GetChainTipsResponse contains information about all known tips in the block tree.
Field
Type
Label
Description
tips
model.ChainTip
repeated
List of chain tips
GetBlockExistsResponse indicates whether a block exists.
Field
Type
Label
Description
exists
bool
True if the block exists
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
Serialized block header
id
uint32
Block identifier
height
uint32
Block height
tx_count
uint64
Transaction count
size_in_bytes
uint64
Block size
miner
string
Miner identifier
peer_id
string
Peer identifier
block_time
uint32
Block timestamp
timestamp
uint32
Processing timestamp
chain_work
bytes
Accumulated chain work
mined_set
bool
Mined status
subtrees_set
bool
Subtrees status
invalid
bool
Validity status
processed_at
google.protobuf.Timestamp
Timestamp when block was processed
GetLatestBlockHeaderFromBlockLocatorRequest
GetLatestBlockHeaderFromBlockLocatorRequest retrieves the latest block header using a block locator.
Field
Type
Label
Description
bestBlockHash
bytes
Best block hash
blockLocatorHashes
bytes
repeated
Block locator hashes
GetBlockHeadersFromOldestRequest
GetBlockHeadersFromOldestRequest retrieves block headers starting from the oldest block.
Field
Type
Label
Description
chainTipHash
bytes
Chain tip hash
targetHash
bytes
Target block hash
numberOfHeaders
uint64
Maximum number of hashes to return
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
Field
Type
Label
Description
locator
bytes
repeated
GetBlockRequest represents a request to retrieve a block by its hash.
Field
Type
Label
Description
hash
bytes
Hash of the block to retrieve
swagger:model GetBlockResponse
Field
Type
Label
Description
header
bytes
Block header bytes
height
uint32
Block height
coinbase_tx
bytes
Coinbase transaction bytes
transaction_count
uint64
Total number of transactions
subtree_hashes
bytes
repeated
Merkle tree subtree hashes
size_in_bytes
uint64
Total block size in bytes
id
uint32
Block identifier
GetBlocksMinedNotSetResponse
swagger:model GetBlocksMinedNotSetResponse
Field
Type
Label
Description
blockBytes
bytes
repeated
GetBlocksRequest represents a request to retrieve multiple blocks.
Field
Type
Label
Description
hash
bytes
Starting block hash
count
uint32
Number of blocks to retrieve
swagger:model GetBlocksResponse
Field
Type
Label
Description
blocks
bytes
repeated
GetBlocksSubtreesNotSetResponse
swagger:model GetBlocksSubtreesNotSetResponse
Field
Type
Label
Description
blockBytes
bytes
repeated
swagger:model GetFSMStateResponse
Field
Type
Label
Description
full_block_bytes
bytes
GetHashOfAncestorBlockRequest
swagger:model GetHashOfAncestorBlockRequest
GetHashOfAncestorBlockResponse
swagger:model GetHashOfAncestorBlockResponse
Field
Type
Label
Description
hash
bytes
swagger:model GetLastNBlocksRequest
Field
Type
Label
Description
numberOfBlocks
int64
includeOrphans
bool
fromHeight
uint32
swagger:model GetLastNBlocksResponse
GetMedianTimeRequest requests median time calculation for a block.
Field
Type
Label
Description
blockHash
bytes
Hash of the block
swagger:model GetMedianTimeResponse
Field
Type
Label
Description
block_header_time
uint32
repeated
This will return the nTimes of the last 11 (+1) blocks
GetNextBlockIDResponse represents the response containing the next available block ID.
Field
Type
Label
Description
next_block_id
uint64
Next available block ID
GetNextWorkRequiredRequest
swagger:model GGetNextWorkRequiredRequest
Field
Type
Label
Description
previousBlockHash
bytes
Reference block hash
currentBlockTime
int64
Current block time is only used for emergency difficulty adjustment on testnet-type networks
GetNextWorkRequiredResponse
swagger:model GGetNextWorkRequiredResponse
Field
Type
Label
Description
bits
bytes
swagger:model StateRequest
Field
Type
Label
Description
key
string
swagger:model GetSuitableBlockRequest
Field
Type
Label
Description
hash
bytes
swagger:model GetSuitableBlockResponse
HealthResponse represents the health status of the blockchain service.
swagger:model InvalidateBlockRequest
Field
Type
Label
Description
blockHash
bytes
Hash of the block to invalidate
InvalidateBlockResponse contains the result of block invalidation.
Field
Type
Label
Description
invalidatedBlocks
bytes
repeated
List of invalidated block hashes
LocateBlockHeadersRequest
Field
Type
Label
Description
locator
bytes
repeated
hash_stop
bytes
max_hashes
uint32
LocateBlockHeadersResponse
Field
Type
Label
Description
block_headers
bytes
repeated
swagger:model Notification
swagger:model NotificationMetadata
Field
Type
Label
Description
metadata
map<string, string>
Key-value pairs of metadata
swagger:model RevalidateBlockRequest
Field
Type
Label
Description
blockHash
bytes
swagger:model SendFSMEventRequest
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
swagger:model SetStateRequest
swagger:model StateResponse
Field
Type
Label
Description
data
bytes
swagger:model SubscribeRequest
Field
Type
Label
Description
source
string
WaitFSMToTransitionRequest
swagger:model WaitFSMToTransitionRequest
GetBlockHeadersFromCommonAncestorRequest
GetBlockHeadersFromCommonAncestorRequest retrieves headers from a common ancestor to a target block.
Field
Type
Label
Description
targetHash
bytes
Target block hash
blockLocatorHashes
bytes
repeated
Block locator hashes
maxHeaders
uint32
Maximum number of headers to retrieve
GetBlocksByHeightRequest requests full blocks between two heights.
Field
Type
Label
Description
startHeight
uint32
Starting height
endHeight
uint32
Ending height
GetBlocksByHeightResponse
GetBlocksByHeightResponse contains full blocks between heights.
Field
Type
Label
Description
blocks
bytes
repeated
List of serialized full blocks
FindBlocksContainingSubtreeRequest
FindBlocksContainingSubtreeRequest specifies a subtree hash to search for.
Field
Type
Label
Description
subtree_hash
bytes
Subtree hash to find
max_blocks
uint32
Maximum number of blocks to return (0 = no limit)
FindBlocksContainingSubtreeResponse
FindBlocksContainingSubtreeResponse contains blocks that contain the subtree.
Field
Type
Label
Description
blocks
bytes
repeated
List of serialized full blocks containing the subtree
ReportPeerFailureRequest reports a peer download failure to the blockchain service.
Field
Type
Label
Description
hash
bytes
Hash of the block/subtree being processed
peer_id
string
Identifier of the failing peer
failure_type
string
Type of failure (e.g., "catchup", "subtree", "block")
reason
string
Description of the failure
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
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 defines possible states of the blockchain FSM.
Name
Number
Description
IDLE
0
Service is idle
RUNNING
1
Service is running normally
CATCHINGBLOCKS
2
Service is catching up blocks
LEGACYSYNCING
3
Service is in legacy sync mode
BlockchainAPI service provides comprehensive blockchain management functionality.
.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)