Flow Access API Specification
The Access API is implemented as a gRPC service.
A language-agnostic specification for this API is defined using Protocol Buffers, which can be used to generate client libraries in a variety of programming languages.
Flow Access Node Endpointsβ
Network | GRPC | Web GRPC | REST |
---|---|---|---|
Mainnet | access.mainnet.nodes.onflow.org:9000 | mainnet.onflow.org | rest-mainnet.onflow.org |
Testnet | access.devnet.nodes.onflow.org:9000 | testnet.onflow.org | rest-testnet.onflow.org |
Pingβ
Ping
will return a successful response if the Access API is ready and available.
_10rpc Ping(PingRequest) returns (PingResponse)
If a ping request returns an error or times out, it can be assumed that the Access API is unavailable.
Requestβ
_10message PingRequest {}
Responseβ
_10message PingResponse {}
Block Headersβ
The following methods query information about block headers.
GetLatestBlockHeaderβ
GetLatestBlockHeader
gets the latest sealed or unsealed block header.
_10rpc GetLatestBlockHeader (GetLatestBlockHeaderRequest) returns (BlockHeaderResponse)
Requestβ
_10message GetLatestBlockHeaderRequest {_10 bool is_sealed = 1;_10}
Responseβ
_10message BlockHeaderResponse {_10 entities.BlockHeader block = 1;_10 entities.BlockStatus block_status = 2;_10 entities.Metadata metadata = 3;_10}
GetBlockHeaderByIDβ
GetBlockHeaderByID
gets a block header by ID.
_10rpc GetBlockHeaderByID (GetBlockHeaderByIDRequest) returns (BlockHeaderResponse)
Requestβ
_10message GetBlockHeaderByIDRequest {_10 bytes id = 1;_10}
Responseβ
_10message BlockHeaderResponse {_10 entities.BlockHeader block = 1;_10 entities.BlockStatus block_status = 2;_10 entities.Metadata metadata = 3;_10}
GetBlockHeaderByHeightβ
GetBlockHeaderByHeight
gets a block header by height.
_10rpc GetBlockHeaderByHeight (GetBlockHeaderByHeightRequest) returns (BlockHeaderResponse)
Requestβ
_10message GetBlockHeaderByHeightRequest {_10 uint64 height = 1;_10}
Responseβ
_10message BlockHeaderResponse {_10 entities.BlockHeader block = 1;_10 entities.BlockStatus block_status = 2;_10 entities.Metadata metadata = 3;_10}
Blocksβ
The following methods query information about full blocks.
GetLatestBlockβ
GetLatestBlock
gets the full payload of the latest sealed or unsealed block.
_10rpc GetLatestBlock (GetLatestBlockRequest) returns (BlockResponse)
Requestβ
_10message GetLatestBlockRequest {_10 bool is_sealed = 1;_10 bool full_block_response = 2;_10}
Responseβ
_10message BlockResponse {_10 entities.Block block = 1;_10 entities.BlockStatus block_status = 2;_10 entities.Metadata metadata = 3;_10}
GetBlockByIDβ
GetBlockByID
gets a full block by ID.
_10rpc GetBlockByID (GetBlockByIDRequest) returns (BlockResponse)
Requestβ
_10message GetBlockByIDRequest {_10 bytes id = 1;_10 bool full_block_response = 2;_10}
Responseβ
_10message BlockResponse {_10 entities.Block block = 1;_10 entities.BlockStatus block_status = 2;_10 entities.Metadata metadata = 3;_10}
GetBlockByHeightβ
GetBlockByHeight
gets a full block by height.
_10rpc GetBlockByHeight (GetBlockByHeightRequest) returns (BlockResponse)
Requestβ
_10message GetBlockByHeightRequest {_10 uint64 height = 1;_10 bool full_block_response = 2;_10}
Responseβ
_10message BlockResponse {_10 entities.Block block = 1;_10 entities.BlockStatus block_status = 2;_10 entities.Metadata metadata = 3;_10}
Collectionsβ
The following methods query information about collections.
GetCollectionByIDβ
GetCollectionByID
gets a collection by ID.
_10rpc GetCollectionByID (GetCollectionByIDRequest) returns (CollectionResponse)
Requestβ
_10message GetCollectionByIDRequest {_10 bytes id = 1;_10}
Responseβ
_10message CollectionResponse {_10 entities.Collection collection = 1;_10 entities.Metadata metadata = 2;_10}
GetFullCollectionByIDβ
GetFullCollectionByID
gets a collection by ID, which contains a set of transactions.
_10rpc GetFullCollectionByID(GetFullCollectionByIDRequest) returns (FullCollectionResponse);
Requestβ
_10message GetFullCollectionByIDRequest {_10 bytes id = 1;_10}
Responseβ
_10message FullCollectionResponse {_10 repeated entities.Transaction transactions = 1;_10 entities.Metadata metadata = 2;_10}
Transactionsβ
The following methods can be used to submit transactions and fetch their results.
SendTransactionβ
SendTransaction
submits a transaction to the network.
_10rpc SendTransaction (SendTransactionRequest) returns (SendTransactionResponse)
SendTransaction
determines the correct cluster of collection nodes that is responsible for collecting the transaction based on the hash of the transaction and forwards the transaction to that cluster.
Requestβ
SendTransactionRequest
message contains the transaction that is being request to be executed.
_10message SendTransactionRequest {_10 entities.Transaction transaction = 1;_10}
Responseβ
SendTransactionResponse
message contains the ID of the submitted transaction.
_10message SendTransactionResponse {_10 bytes id = 1;_10 entities.Metadata metadata = 2;_10}
GetTransactionβ
GetTransaction
gets a transaction by ID.
If the transaction is not found in the access node cache, the request is forwarded to a collection node.
Currently, only transactions within the current epoch can be queried.
_10rpc GetTransaction (GetTransactionRequest) returns (TransactionResponse)
Requestβ
GetTransactionRequest
contains the ID of the transaction that is being queried.
_10message GetTransactionRequest {_10 bytes id = 1;_10 bytes block_id = 2;_10 bytes collection_id = 3;_10 entities.EventEncodingVersion event_encoding_version = 4;_10}
Responseβ
TransactionResponse
contains the basic information about a transaction, but does not include post-execution results.
_10message TransactionResponse {_10 entities.Transaction transaction = 1;_10 entities.Metadata metadata = 2;_10}
GetTransactionsByBlockIDβ
GetTransactionsByBlockID
gets all the transactions for a specified block.
_10rpc GetTransactionsByBlockID(GetTransactionsByBlockIDRequest) returns (TransactionsResponse);
Requestβ
_10message GetTransactionsByBlockIDRequest {_10 bytes block_id = 1;_10 entities.EventEncodingVersion event_encoding_version = 2;_10}
Responseβ
_10message TransactionsResponse {_10 repeated entities.Transaction transactions = 1;_10 entities.Metadata metadata = 2;_10}
GetTransactionResultβ
GetTransactionResult
gets the execution result of a transaction.
_10rpc GetTransactionResult (GetTransactionRequest) returns (TransactionResultResponse)
Requestβ
_10message GetTransactionRequest {_10 bytes id = 1;_10 bytes block_id = 2;_10 bytes collection_id = 3;_10 entities.EventEncodingVersion event_encoding_version = 4;_10}
Responseβ
_12message TransactionResultResponse {_12 entities.TransactionStatus status = 1;_12 uint32 status_code = 2;_12 string error_message = 3;_12 repeated entities.Event events = 4;_12 bytes block_id = 5;_12 bytes transaction_id = 6;_12 bytes collection_id = 7;_12 uint64 block_height = 8;_12 entities.Metadata metadata = 9;_12 uint64 computation_usage = 10;_12}
GetTransactionResultByIndexβ
GetTransactionResultByIndex
gets the execution result of a transaction at a specified block and index.
_10rpc GetTransactionResultByIndex(GetTransactionByIndexRequest) returns (TransactionResultResponse);
Requestβ
_10message GetTransactionByIndexRequest {_10 bytes block_id = 1;_10 uint32 index = 2;_10 entities.EventEncodingVersion event_encoding_version = 3;_10}
Responseβ
_12message TransactionResultResponse {_12 entities.TransactionStatus status = 1;_12 uint32 status_code = 2;_12 string error_message = 3;_12 repeated entities.Event events = 4;_12 bytes block_id = 5;_12 bytes transaction_id = 6;_12 bytes collection_id = 7;_12 uint64 block_height = 8;_12 entities.Metadata metadata = 9;_12 uint64 computation_usage = 10;_12}
GetTransactionResultsByBlockIDβ
GetTransactionResultsByBlockID
gets all the transaction results for a specified block.
_10rpc GetTransactionResultsByBlockID(GetTransactionsByBlockIDRequest) returns (TransactionResultsResponse);
Requestβ
_10message GetTransactionsByBlockIDRequest {_10 bytes block_id = 1;_10 entities.EventEncodingVersion event_encoding_version = 2;_10}
Responseβ
_10message TransactionResultsResponse {_10 repeated TransactionResultResponse transaction_results = 1;_10 entities.Metadata metadata = 2;_10}
GetSystemTransactionβ
GetSystemTransaction
gets the system transaction for a block.
_10rpc GetSystemTransaction(GetSystemTransactionRequest) returns (TransactionResponse);
Requestβ
_10message GetSystemTransactionRequest {_10 bytes block_id = 1;_10}
Responseβ
_10message TransactionResponse {_10 entities.Transaction transaction = 1;_10 entities.Metadata metadata = 2;_10}
GetSystemTransactionResultβ
GetSystemTransactionResult
gets the system transaction result for a block.
_10rpc GetSystemTransactionResult(GetSystemTransactionResultRequest) returns (TransactionResultResponse);
Requestβ
_10message GetSystemTransactionResultRequest {_10 bytes block_id = 1;_10 entities.EventEncodingVersion event_encoding_version = 2;_10}
Responseβ
_12message TransactionResultResponse {_12 entities.TransactionStatus status = 1;_12 uint32 status_code = 2;_12 string error_message = 3;_12 repeated entities.Event events = 4;_12 bytes block_id = 5;_12 bytes transaction_id = 6;_12 bytes collection_id = 7;_12 uint64 block_height = 8;_12 entities.Metadata metadata = 9;_12 uint64 computation_usage = 10;_12}
Accountsβ
GetAccountβ
GetAccount
gets an account by address at the latest sealed block.
β οΈ Warning: this function is deprecated. It behaves identically to GetAccountAtLatestBlock
and will be removed in a future version.
_10rpc GetAccount(GetAccountRequest) returns (GetAccountResponse)
Requestβ
_10message GetAccountRequest {_10 bytes address = 1;_10}
Responseβ
_10message GetAccountResponse {_10 entities.Account account = 1;_10 entities.Metadata metadata = 2;_10}
GetAccountAtLatestBlockβ
GetAccountAtLatestBlock
gets an account by address.
The access node queries an execution node for the account details, which are stored as part of the sealed execution state.
_10rpc GetAccountAtLatestBlock(GetAccountAtLatestBlockRequest) returns (AccountResponse)
Requestβ
_10message GetAccountAtLatestBlockRequest {_10 bytes address = 1;_10}
Responseβ
_10message AccountResponse {_10 entities.Account account = 1;_10 entities.Metadata metadata = 2;_10}
GetAccountAtBlockHeightβ
GetAccountAtBlockHeight
gets an account by address at the given block height.
The access node queries an execution node for the account details, which are stored as part of the execution state.
_10rpc GetAccountAtBlockHeight(GetAccountAtBlockHeightRequest) returns (AccountResponse)
Requestβ
_10message GetAccountAtBlockHeightRequest {_10 bytes address = 1;_10 uint64 block_height = 2;_10}
Responseβ
_10message AccountResponse {_10 entities.Account account = 1;_10 entities.Metadata metadata = 2;_10}
GetAccountBalanceAtLatestBlockβ
GetAccountBalanceAtLatestBlock
gets an account's balance by address from the latest sealed block.
_10rpc GetAccountBalanceAtLatestBlock(GetAccountBalanceAtLatestBlockRequest) returns (AccountBalanceResponse);
Requestβ
_10message GetAccountBalanceAtLatestBlockRequest {_10 bytes address = 1_10}
Responseβ
_10message AccountBalanceResponse {_10 uint64 balance = 1;_10 entities.Metadata metadata = 2;_10}
GetAccountBalanceAtBlockHeightβ
GetAccountBalanceAtBlockHeight
gets an account's balance by address at the given block height.
_10rpc GetAccountBalanceAtBlockHeight(GetAccountBalanceAtBlockHeightRequest) returns (AccountBalanceResponse);
Requestβ
_10message GetAccountBalanceAtBlockHeightRequest {_10 bytes address = 1;_10 uint64 block_height = 2;_10}
Responseβ
_10message AccountBalanceResponse {_10 uint64 balance = 1;_10 entities.Metadata metadata = 2;_10}
GetAccountKeyAtLatestBlockβ
GetAccountKeyAtLatestBlock
gets an account's public key by address and key index from the latest sealed block.
_10rpc GetAccountKeyAtLatestBlock(GetAccountKeyAtLatestBlockRequest) returns (AccountKeyResponse);
Requestβ
_10message GetAccountKeyAtLatestBlockRequest {_10 // address of account_10 bytes address = 1;_10 // index of key to return_10 uint32 index = 2;_10}
Responseβ
_10message AccountKeyResponse {_10 entities.AccountKey account_key = 1;_10 entities.Metadata metadata = 2;_10}
GetAccountKeyAtBlockHeightβ
GetAccountKeyAtBlockHeight
gets an account's public key by address and key index at the given block height.
_10rpc GetAccountKeyAtBlockHeight(GetAccountKeyAtBlockHeightRequest) returns (AccountKeyResponse);
Requestβ
_10message GetAccountKeyAtBlockHeightRequest {_10 // address of account_10 bytes address = 1;_10 // height of the block_10 uint64 block_height = 2;_10 // index of key to return_10 uint32 index = 3;_10}
Responseβ
_10message AccountKeyResponse {_10 entities.AccountKey account_key = 1;_10 entities.Metadata metadata = 2;_10}
GetAccountKeysAtLatestBlockβ
GetAccountKeysAtLatestBlock
gets an account's public keys by address from the latest sealed block.
_10rpc GetAccountKeysAtLatestBlock(GetAccountKeysAtLatestBlockRequest) returns (AccountKeysResponse);
Requestβ
_10message GetAccountKeysAtLatestBlockRequest {_10 // address of account_10 bytes address = 1;_10}
Responseβ
_10message AccountKeysResponse {_10 repeated entities.AccountKey account_keys = 1;_10 entities.Metadata metadata = 2;_10}
GetAccountKeysAtBlockHeightβ
GetAccountKeysAtBlockHeight
gets an account's public keys by address at the given block height.
_10rpc GetAccountKeysAtBlockHeight(GetAccountKeysAtBlockHeightRequest) returns (AccountKeysResponse);
Requestβ
_10message GetAccountKeysAtBlockHeightRequest {_10 // address of account_10 bytes address = 1;_10 uint64 block_height = 2;_10}
Responseβ
_10message AccountKeysResponse {_10 repeated entities.AccountKey account_keys = 1;_10 entities.Metadata metadata = 2;_10}
Scriptsβ
ExecuteScriptAtLatestBlockβ
ExecuteScriptAtLatestBlock
executes a read-only Cadence script against the latest sealed execution state.
This method can be used to read execution state from the blockchain. The script is executed on an execution node and the return value is encoded using the JSON-Cadence data interchange format.
_10rpc ExecuteScriptAtLatestBlock (ExecuteScriptAtLatestBlockRequest) returns (ExecuteScriptResponse)
This method is a shortcut for the following:
_10header = GetLatestBlockHeader()_10value = ExecuteScriptAtBlockID(header.ID, script)
Requestβ
_10message ExecuteScriptAtLatestBlockRequest {_10 bytes script = 1;_10 repeated bytes arguments = 2;_10}
Responseβ
_10message ExecuteScriptResponse {_10 bytes value = 1;_10 entities.Metadata metadata = 2;_10 uint64 computation_usage = 3;_10}
ExecuteScriptAtBlockIDβ
ExecuteScriptAtBlockID
executes a ready-only Cadence script against the execution state at the block with the given ID.
This method can be used to read account state from the blockchain. The script is executed on an execution node and the return value is encoded using the JSON-Cadence data interchange format.
_10rpc ExecuteScriptAtBlockID (ExecuteScriptAtBlockIDRequest) returns (ExecuteScriptResponse)
Requestβ
_10message ExecuteScriptAtBlockIDRequest {_10 bytes block_id = 1;_10 bytes script = 2;_10 repeated bytes arguments = 3;_10}
Responseβ
_10message ExecuteScriptResponse {_10 bytes value = 1;_10 entities.Metadata metadata = 2;_10 uint64 computation_usage = 3;_10}
ExecuteScriptAtBlockHeightβ
ExecuteScriptAtBlockHeight
executes a ready-only Cadence script against the execution state at the given block height.
This method can be used to read account state from the blockchain. The script is executed on an execution node and the return value is encoded using the JSON-Cadence data interchange format.
_10rpc ExecuteScriptAtBlockHeight (ExecuteScriptAtBlockHeightRequest) returns (ExecuteScriptResponse)
Requestβ
_10message ExecuteScriptAtBlockHeightRequest {_10 uint64 block_height = 1;_10 bytes script = 2;_10 repeated bytes arguments = 3;_10}
Responseβ
_10message ExecuteScriptResponse {_10 bytes value = 1;_10 entities.Metadata metadata = 2;_10 uint64 computation_usage = 3;_10}
Eventsβ
The following methods can be used to query for on-chain events.
GetEventsForHeightRangeβ
GetEventsForHeightRange
retrieves events emitted within the specified block range.
_10rpc GetEventsForHeightRange(GetEventsForHeightRangeRequest) returns (GetEventsForHeightRangeResponse)
Events can be requested for a specific sealed block range via the start_height
and end_height
(inclusive) fields and further filtered by event type via the type
field.
If start_height
is greater than the current sealed chain height, then this method will return an error.
If end_height
is greater than the current sealed chain height, then this method will return events up to and including the latest sealed block.
The event results are grouped by block, with each group specifying a block ID, height and block timestamp.
Event types are name-spaced with the address of the account and contract in which they are declared.
Requestβ
_10message GetEventsForHeightRangeRequest {_10 string type_10 uint64 start_height = 2;_10 uint64 end_height = 3;_10 entities.EventEncodingVersion event_encoding_version = 4;_10}
Responseβ
_10message EventsResponse {_10 message Result {_10 bytes block_id = 1;_10 uint64 block_height = 2;_10 repeated entities.Event events = 3;_10 google.protobuf.Timestamp block_timestamp = 4;_10 }_10 repeated Result results = 1;_10 entities.Metadata metadata = 2;_10}
GetEventsForBlockIDsβ
GetEventsForBlockIDs
retrieves events for the specified block IDs and event type.
_10rpc GetEventsForBlockIDs(GetEventsForBlockIDsRequest) returns (GetEventsForBlockIDsResponse)
Events can be requested for a list of block IDs via the block_ids
field and further filtered by event type via the type
field.
The event results are grouped by block, with each group specifying a block ID, height and block timestamp.
Requestβ
_10message GetEventsForBlockIDsRequest {_10 string type = 1;_10 repeated bytes block_ids = 2;_10 entities.EventEncodingVersion event_encoding_version = 3;_10}
Responseβ
_10message EventsResponse {_10 message Result {_10 bytes block_id = 1;_10 uint64 block_height = 2;_10 repeated entities.Event events = 3;_10 google.protobuf.Timestamp block_timestamp = 4;_10 }_10 repeated Result results = 1;_10 entities.Metadata metadata = 2;_10}
Network Parametersβ
Network parameters provide information about the Flow network. Currently, it only includes the chain ID. The following method can be used to query for network parameters.
GetNetworkParametersβ
GetNetworkParameters
retrieves the network parameters.
_10rpc GetNetworkParameters (GetNetworkParametersRequest) returns (GetNetworkParametersResponse)
Requestβ
_10message GetNetworkParametersRequest {}
Responseβ
_10message GetNetworkParametersResponse {_10 string chain_id = 1;_10}
Field | Description |
---|---|
chain_id | Chain ID helps identify the Flow network. It can be one of flow-mainnet , flow-testnet or flow-emulator |
GetNodeVersionInfoβ
GetNodeVersionInfo
gets information about a node's current versions.
_10rpc GetNodeVersionInfo (GetNodeVersionInfoRequest) returns (GetNodeVersionInfoResponse);
Requestβ
_10message GetNodeVersionInfoRequest {}
Responseβ
_10message GetNodeVersionInfoResponse {_10 entities.NodeVersionInfo info = 1;_10}
Protocol state snapshotβ
The following method can be used to query the latest protocol state snapshot.
GetLatestProtocolStateSnapshotβ
GetLatestProtocolStateSnapshot
retrieves the latest Protocol state snapshot serialized as a byte array.
It is used by Flow nodes joining the network to bootstrap a space-efficient local state.
_10rpc GetLatestProtocolStateSnapshot (GetLatestProtocolStateSnapshotRequest) returns (ProtocolStateSnapshotResponse);
Requestβ
_10message GetLatestProtocolStateSnapshotRequest {}
Responseβ
_10message ProtocolStateSnapshotResponse {_10 bytes serializedSnapshot = 1;_10 entities.Metadata metadata = 2;_10}
GetProtocolStateSnapshotByBlockIDβ
GetProtocolStateSnapshotByBlockID
retrieves the latest sealed protocol state snapshot by block ID.
Used by Flow nodes joining the network to bootstrap a space-efficient local state.
_10rpc GetProtocolStateSnapshotByBlockID(GetProtocolStateSnapshotByBlockIDRequest) returns (ProtocolStateSnapshotResponse);
Requestβ
_10message GetProtocolStateSnapshotByBlockIDRequest {_10 bytes block_id = 1;_10}
Responseβ
_10message ProtocolStateSnapshotResponse {_10 bytes serializedSnapshot = 1;_10 entities.Metadata metadata = 2;_10}
GetProtocolStateSnapshotByHeightβ
GetProtocolStateSnapshotByHeight
retrieves the latest sealed protocol state snapshot by block height.
Used by Flow nodes joining the network to bootstrap a space-efficient local state.
_10rpc GetProtocolStateSnapshotByHeight(GetProtocolStateSnapshotByHeightRequest) returns (ProtocolStateSnapshotResponse);
Requestβ
_10message GetProtocolStateSnapshotByHeightRequest {_10 uint64 block_height = 1;_10}
Responseβ
_10message ProtocolStateSnapshotResponse {_10 bytes serializedSnapshot = 1;_10 entities.Metadata metadata = 2;_10}
Execution resultsβ
The following method can be used to query the for execution results for a given block.
GetExecutionResultForBlockIDβ
GetExecutionResultForBlockID
retrieves execution result for given block. It is different from Transaction Results,
and contain data about chunks/collection level execution results rather than particular transactions.
Particularly, it contains EventsCollection
hash for every chunk which can be used to verify the events for a block.
_10rpc GetExecutionResultForBlockID(GetExecutionResultForBlockIDRequest) returns (ExecutionResultForBlockIDResponse);
Requestβ
_10message GetExecutionResultForBlockIDRequest {_10 bytes block_id = 1;_10}
Responseβ
_10message ExecutionResultForBlockIDResponse {_10 flow.ExecutionResult execution_result = 1;_10 entities.Metadata metadata = 2;_10}
GetExecutionResultByIDβ
GetExecutionResultByID
returns Execution Result by its ID. It is different from Transaction Results,
and contain data about chunks/collection level execution results rather than particular transactions.
Particularly, it contains EventsCollection
hash for every chunk which can be used to verify the events for a block.
_10rpc GetExecutionResultByID(GetExecutionResultByIDRequest) returns (ExecutionResultByIDResponse);
Requestβ
_10message GetExecutionResultByIDRequest {_10 bytes id = 1;_10}
Responseβ
_10message ExecutionResultByIDResponse {_10 flow.ExecutionResult execution_result = 1;_10 entities.Metadata metadata = 2;_10}
Entitiesβ
Below are in-depth descriptions of each of the data entities returned or accepted by the Access API.
Blockβ
_13message Block {_13 bytes id = 1;_13 bytes parent_id = 2;_13 uint64 height = 3;_13 google.protobuf.Timestamp timestamp = 4;_13 repeated CollectionGuarantee collection_guarantees = 5;_13 repeated BlockSeal block_seals = 6;_13 repeated bytes signatures = 7;_13 repeated ExecutionReceiptMeta execution_receipt_metaList = 8;_13 repeated ExecutionResult execution_result_list = 9;_13 BlockHeader block_header = 10;_13 bytes protocol_state_id = 11;_13}
Field | Description |
---|---|
id | SHA3-256 hash of the entire block payload |
height | Height of the block in the chain |
parent_id | ID of the previous block in the chain |
timestamp | Timestamp of when the proposer claims it constructed the block. NOTE: It is included by the proposer, there are no guarantees on how much the time stamp can deviate from the true time the block was published. Consider observing blocks' status changes yourself to get a more reliable value |
collection_guarantees | List of collection guarantees |
block_seals | List of block seals |
signatures | BLS signatures of consensus nodes |
execution_receipt_metaList | List of execution-receipt-meta |
execution_result_list | List of execution results |
block_header | A summary of a block |
protocol_state_id | The root hash of protocol state. |
The detailed semantics of block formation are covered in the block formation guide.
Block Headerβ
A block header is a summary of a block and contains only the block ID, height, and parent block ID.
_16message BlockHeader {_16 bytes id = 1;_16 bytes parent_id = 2;_16 uint64 height = 3;_16 google.protobuf.Timestamp timestamp = 4;_16 bytes payload_hash = 5;_16 uint64 view = 6;_16 repeated bytes parent_voter_ids = 7;_16 bytes parent_voter_sig_data = 8;_16 bytes proposer_id = 9;_16 bytes proposer_sig_data = 10;_16 string chain_id = 11;_16 bytes parent_voter_indices = 12;_16 TimeoutCertificate last_view_tc = 13;_16 uint64 parent_view = 14;_16}
Field | Description |
---|---|
id | SHA3-256 hash of the entire block payload |
parent_id | ID of the previous block in the chain |
height | Height of the block in the chain |
timestamp | The time at which this block was proposed |
payload_hash | A hash of the payload of this block |
view | Number at which this block was proposed. |
parent_voter_ids | An array that represents all the voters ids for the parent block |
parent_voter_sig_data | An aggregated signature over the parent block |
chain_id | Chain ID helps identify the Flow network. It can be one of flow-mainnet , flow-testnet or flow-emulator |
parent_voter_indices | A bitvector that represents all the voters for the parent block |
last_view_tc | A timeout certificate for previous view, it can be nil. It has to be present if previous round ended with timeout |
parent_view | A number at which parent block was proposed |
Block Sealβ
A block seal is an attestation that the execution result of a specific block has been verified and approved by a quorum of verification nodes.
_10message BlockSeal {_10 bytes block_id = 1;_10 bytes execution_receipt_id = 2;_10 repeated bytes execution_receipt_signatures = 3;_10 repeated bytes result_approval_signatures = 4;_10}
Field | Description |
---|---|
block_id | ID of the block being sealed |
execution_receipt_id | ID execution receipt being sealed |
execution_receipt_signatures | BLS signatures of verification nodes on the execution receipt contents |
result_approval_signatures | BLS signatures of verification nodes on the result approval contents |
Block Statusβ
_10enum BlockStatus {_10 UNKNOWN = 0;_10 FINALIZED = 1;_10 SEALED = 2;_10}
Value | Description |
---|---|
UNKNOWN | The block status is not known |
FINALIZED | The consensus nodes have finalized the block |
SEALED | The verification nodes have verified the block |
Collectionβ
A collection is a batch of transactions that have been included in a block. Collections are used to improve consensus throughput by increasing the number of transactions per block.
_10message Collection {_10 bytes id = 1;_10 repeated bytes transaction_ids = 2;_10}
Field | Description |
---|---|
id | SHA3-256 hash of the collection contents |
transaction_ids | Ordered list of transaction IDs in the collection |
Collection Guaranteeβ
A collection guarantee is a signed attestation that specifies the collection nodes that have guaranteed to store and respond to queries about a collection.
_10message CollectionGuarantee {_10 bytes collection_id = 1;_10 repeated bytes signatures = 2;_10 bytes reference_block_id = 3;_10 bytes signature = 4;_10 repeated bytes signer_ids = 5; // deprecated!! value will be empty. replaced by signer_indices_10 bytes signer_indices = 6;_10}
Field | Description |
---|---|
collection_id | SHA3-256 hash of the collection contents |
signatures | BLS signatures of the collection nodes guaranteeing the collection |
reference_block_id | Defines expiry of the collection |
signature | Guarantor signatures |
signer_ids | An array that represents all the signer ids |
signer_indices | Encoded indices of the signers |
Transactionβ
A transaction represents a unit of computation that is submitted to the Flow network.
_23message Transaction {_23 bytes script = 1;_23 repeated bytes arguments = 2;_23 bytes reference_block_id = 3;_23 uint64 gas_limit = 4;_23 ProposalKey proposal_key = 5;_23 bytes payer = 6;_23 repeated bytes authorizers = 7;_23 repeated Signature payload_signatures = 8;_23 repeated Signature envelope_signatures = 9;_23}_23_23message TransactionProposalKey {_23 bytes address = 1;_23 uint32 key_id = 2;_23 uint64 sequence_number = 3;_23}_23_23message TransactionSignature {_23 bytes address = 1;_23 uint32 key_id = 2;_23 bytes signature = 3;_23}
Field | Description |
---|---|
script | Raw source code for a Cadence script, encoded as UTF-8 bytes |
arguments | Arguments passed to the Cadence script, encoded as JSON-Cadence bytes |
reference_block_id | Block ID used to determine transaction expiry |
proposal_key | Account key used to propose the transaction |
payer | Address of the payer account |
authorizers | Addresses of the transaction authorizers |
signatures | Signatures from all signer accounts |
The detailed semantics of transaction creation, signing and submission are covered in the transaction submission guide.
Proposal Keyβ
The proposal key is used to specify a sequence number for the transaction. Sequence numbers are covered in more detail here.
Field | Description |
---|---|
address | Address of proposer account |
key_id | ID of proposal key on the proposal account |
sequence_number | Sequence number for the proposal key |
Transaction Signatureβ
Field | Description |
---|---|
address | Address of the account for this signature |
key_id | ID of the account key |
signature | Raw signature byte data |
Transaction Statusβ
_10enum TransactionStatus {_10 UNKNOWN = 0;_10 PENDING = 1;_10 FINALIZED = 2;_10 EXECUTED = 3;_10 SEALED = 4;_10 EXPIRED = 5;_10}
Value | Description |
---|---|
UNKNOWN | The transaction status is not known. |
PENDING | The transaction has been received by a collector but not yet finalized in a block. |
FINALIZED | The consensus nodes have finalized the block that the transaction is included in |
EXECUTED | The execution nodes have produced a result for the transaction |
SEALED | The verification nodes have verified the transaction (the block in which the transaction is) and the seal is included in the latest block |
EXPIRED | The transaction was submitted past its expiration block height. |
Accountβ
An account is a user's identity on Flow. It contains a unique address, a balance, a list of public keys and the code that has been deployed to the account.
_10message Account {_10 bytes address = 1;_10 uint64 balance = 2;_10 bytes code = 3;_10 repeated AccountKey keys = 4;_10 map<string, bytes> contracts = 5;_10}
Field | Description |
---|---|
address | A unique account identifier |
balance | The account balance |
code | The code deployed to this account (deprecated, use contracts instead) |
keys | A list of keys configured on this account |
contracts | A map of contracts or contract interfaces deployed on this account |
The code
and contracts
fields contain the raw Cadence source code, encoded as UTF-8 bytes.
More information on accounts can be found here.
Account Keyβ
An account key is a reference to a public key associated with a Flow account. Accounts can be configured with zero or more public keys, each of which can be used for signature verification when authorizing a transaction.
_10message AccountKey {_10 uint32 index = 1;_10 bytes public_key = 2;_10 uint32 sign_algo = 3;_10 uint32 hash_algo = 4;_10 uint32 weight = 5;_10 uint32 sequence_number = 6;_10 bool revoked = 7;_10}
Field | Description |
---|---|
id | Index of the key within the account, used as a unique identifier |
public_key | Public key encoded as bytes |
sign_algo | Signature algorithm |
hash_algo | Hash algorithm |
weight | Weight assigned to the key |
sequence_number | Sequence number for the key |
revoked | Flag indicating whether or not the key has been revoked |
More information on account keys, key weights and sequence numbers can be found here.
Eventβ
An event is emitted as the result of a transaction execution. Events are either user-defined events originating from a Cadence smart contract, or built-in Flow system events.
_10message Event {_10 string type = 1;_10 bytes transaction_id = 2;_10 uint32 transaction_index = 3;_10 uint32 event_index = 4;_10 bytes payload = 5;_10}
Field | Description |
---|---|
type | Fully-qualified unique type identifier for the event |
transaction_id | ID of the transaction the event was emitted from |
transaction_index | Zero-based index of the transaction within the block |
event_index | Zero-based index of the event within the transaction |
payload | Event fields encoded as JSON-Cadence values |
Execution Resultβ
Execution result for a particular block.
_10message ExecutionResult {_10 bytes previous_result_id = 1;_10 bytes block_id = 2;_10 repeated Chunk chunks = 3;_10 repeated ServiceEvent service_events = 4;_10}
Field | Description |
---|---|
previous_result_id | Identifier of parent block execution result |
block_id | ID of the block this execution result corresponds to |
chunks | Zero or more chunks |
service_events | Zero or more service events |
Execution Receipt Metaβ
ExecutionReceiptMeta contains the fields from the Execution Receipts that vary from one executor to another (assuming they commit to the same result).
_10message ExecutionReceiptMeta {_10 bytes executor_id = 1;_10 bytes result_id = 2;_10 repeated bytes spocks = 3;_10 bytes executor_signature = 4;_10}
Field | Description |
---|---|
executor_id | Identifier of the executor node |
result_id | Identifier of block execution result |
spocks | SPoCK |
executor_signature | Signature of the executor |
Chunkβ
Chunk described execution information for given collection in a block
_12message Chunk {_12 uint32 CollectionIndex = 1;_12 bytes start_state = 2;_12 bytes event_collection = 3;_12 bytes block_id = 4;_12 uint64 total_computation_used = 5;_12 uint32 number_of_transactions = 6;_12 uint64 index = 7;_12 bytes end_state = 8;_12 bytes execution_data_id = 9;_12 bytes state_delta_commitment = 10;_12}
Field | Description |
---|---|
CollectionIndex | Identifier of a collection |
start_state | State commitment at start of the chunk |
event_collection | Hash of events emitted by transactions in this chunk |
block_id | Identifier of a block |
total_computation_used | Total computation used by transactions in this chunk |
number_of_transactions | Number of transactions in a chunk |
index | Index of chunk inside a block (zero-based) |
end_state | State commitment after executing chunk |
execution_data_id | Identifier of a execution data |
state_delta_commitment | A commitment over sorted list of register changes |
Service Eventβ
Special type of events emitted in system chunk used for controlling Flow system.
_10message ServiceEvent {_10 string type = 1;_10 bytes payload = 2;_10}
Field | Description |
---|---|
type | Type of an event |
payload | JSON-serialized content of an event |
Subscriptionsβ
SubscribeEventsβ
SubscribeEvents
streams events for all blocks starting at the requested start block, up until the latest available block. Once the latest is
reached, the stream will remain open and responses are sent for each new block as it becomes available.
Events within each block are filtered by the provided EventFilter, and only those events that match the filter are returned. If no filter is provided, all events are returned.
Responses are returned for each block containing at least one event that matches the filter. Additionally, heatbeat responses (SubscribeEventsResponse with no events) are returned periodically to allow clients to track which blocks were searched. Clients can use this information to determine which block to start from when reconnecting.
_10rpc SubscribeEvents(SubscribeEventsRequest) returns (stream SubscribeEventsResponse)
Requestβ
_10message SubscribeEventsRequest {_10 bytes start_block_id = 1;_10 uint64 start_block_height = 2;_10 EventFilter filter = 3;_10 uint64 heartbeat_interval = 4;_10 entities.EventEncodingVersion event_encoding_version = 5;_10}
Field | Description |
---|---|
start_block_id | The first block to search for events. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
start_block_height | Block height of the first block to search for events. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
filter | Filter to apply to events for each block searched. If no filter is provided, all events are returned |
heartbeat_interval | Interval in block heights at which the server should return a heartbeat message to the client |
event_encoding_version | Preferred event encoding version of the block events payload. Possible variants: CCF, JSON-CDC |
Responseβ
_10message SubscribeEventsResponse {_10 bytes block_id = 1;_10 uint64 block_height = 2;_10 repeated entities.Event events = 3;_10 google.protobuf.Timestamp block_timestamp = 4;_10 uint64 message_index = 5;_10}
SubscribeExecutionDataβ
SubscribeExecutionData
streams execution data for all blocks starting at the requested start block, up until the latest available block. Once the latest is reached, the stream will remain open and responses are sent for each new execution data as it becomes available.
_10rpc SubscribeExecutionData(SubscribeExecutionDataRequest) returns (stream SubscribeExecutionDataResponse)
Requestβ
_10message SubscribeExecutionDataRequest {_10 bytes start_block_id = 1;_10 uint64 start_block_height = 2;_10 entities.EventEncodingVersion event_encoding_version = 3;_10}
Field | Description |
---|---|
start_block_id | The first block to get execution data for. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
start_block_height | Block height of the first block to get execution data for. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
event_encoding_version | Preferred event encoding version of the block events payload. Possible variants: CCF, JSON-CDC |
Responseβ
_10message SubscribeExecutionDataResponse {_10 uint64 block_height = 1;_10 entities.BlockExecutionData block_execution_data = 2;_10 google.protobuf.Timestamp block_timestamp = 3;_10}
Execution dataβ
EventFilterβ
EventFilter
defines the filter to apply to block events. Filters are applied as an OR operation, i.e. any event matching any of the filters is returned.
If no filters are provided, all events are returned. If there are any invalid filters, the API will return an InvalidArgument error.
_10message EventFilter {_10 repeated string event_type = 1;_10 repeated string contract = 2;_10 repeated string address = 3;_10}
Field | Description |
---|---|
event_type | A list of full event types to include. Event types have 2 formats: _ Protocol events: flow.[event name] _ Smart contract events: A.[contract address].[contract name].[event name] |
contract | A list of contracts who's events should be included. Contracts have the following name formats: _ Protocol events: flow _ Smart contract events: A.[contract address].[contract name] This filter matches on the full contract including its address, not just the contract's name |
address | A list of addresses who's events should be included. Addresses must be Flow account addresses in hex format and valid for the network the node is connected to. i.e. only a mainnet address is valid for a mainnet node. Addresses may optionally include the 0x prefix |
Execution data streaming APIβ
Execution Data APIβ
The ExecutionDataAPI
provides access to block execution data over gRPC, including transactions, events, and register data (account state). Itβs an optional API, which makes use of the Execution Sync protocol to trustlessly download data from peers on the network.
The API is disabled by default. To enable it, specify a listener address with the cli flag
--state-stream-addr
.
Below is a list of the available CLI flags to control the behavior of the API
Flag | Type | Description |
---|---|---|
state-stream-addr | string | Listener address for API. e.g. 0.0.0.0:9003. If no value is provided, the API is disabled. Default is disabled. |
execution-data-cache-size | uint32 | Number of block execution data objects to store in the cache. Default is 100. |
state-stream-global-max-streams | uint32 | Global maximum number of concurrent streams. Default is 1000. |
state-stream-max-message-size | uint | Maximum size for a gRPC response message containing block execution data. Default is 2010241024 (20MB). |
state-stream-event-filter-limits | string | Event filter limits for ExecutionData SubscribeEvents API. These define the max number of filters for each type. e.g. EventTypes=100,Addresses=20,Contracts=50. Default is 1000 for each. |
state-stream-send-timeout | duration | Maximum wait before timing out while sending a response to a streaming client. Default is 30s. |
state-stream-send-buffer-size | uint | Maximum number of unsent responses to buffer for a stream. Default is 10. |
state-stream-response-limit | float64 | Max number of responses per second to send over streaming endpoints. This effectively applies a rate limit to responses to help manage resources consumed by each client. This is mostly used when clients are querying data past data. e.g. 3 or 0.5. Default is 0 which means no limit. |