Skip to main content

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​

NetworkGRPCWeb GRPCREST
Mainnetaccess.mainnet.nodes.onflow.org:9000mainnet.onflow.orgrest-mainnet.onflow.org
Testnetaccess.devnet.nodes.onflow.org:9000testnet.onflow.orgrest-testnet.onflow.org

Ping​

Ping will return a successful response if the Access API is ready and available.


_10
rpc 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​


_10
message PingRequest {}

Response​


_10
message PingResponse {}

Block Headers​

The following methods query information about block headers.

GetLatestBlockHeader​

GetLatestBlockHeader gets the latest sealed or unsealed block header.


_10
rpc GetLatestBlockHeader (GetLatestBlockHeaderRequest) returns (BlockHeaderResponse)

Request​


_10
message GetLatestBlockHeaderRequest {
_10
bool is_sealed = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetBlockHeaderByID (GetBlockHeaderByIDRequest) returns (BlockHeaderResponse)

Request​


_10
message GetBlockHeaderByIDRequest {
_10
bytes id = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetBlockHeaderByHeight (GetBlockHeaderByHeightRequest) returns (BlockHeaderResponse)

Request​


_10
message GetBlockHeaderByHeightRequest {
_10
uint64 height = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetLatestBlock (GetLatestBlockRequest) returns (BlockResponse)

Request​


_10
message GetLatestBlockRequest {
_10
bool is_sealed = 1;
_10
bool full_block_response = 2;
_10
}

Response​


_10
message 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.


_10
rpc GetBlockByID (GetBlockByIDRequest) returns (BlockResponse)

Request​


_10
message GetBlockByIDRequest {
_10
bytes id = 1;
_10
bool full_block_response = 2;
_10
}

Response​


_10
message 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.


_10
rpc GetBlockByHeight (GetBlockByHeightRequest) returns (BlockResponse)

Request​


_10
message GetBlockByHeightRequest {
_10
uint64 height = 1;
_10
bool full_block_response = 2;
_10
}

Response​


_10
message 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.


_10
rpc GetCollectionByID (GetCollectionByIDRequest) returns (CollectionResponse)

Request​


_10
message GetCollectionByIDRequest {
_10
bytes id = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetFullCollectionByID(GetFullCollectionByIDRequest) returns (FullCollectionResponse);

Request​


_10
message GetFullCollectionByIDRequest {
_10
bytes id = 1;
_10
}

Response​


_10
message 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.


_10
rpc 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.


_10
message SendTransactionRequest {
_10
entities.Transaction transaction = 1;
_10
}

Response​

SendTransactionResponse message contains the ID of the submitted transaction.


_10
message 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.


_10
rpc GetTransaction (GetTransactionRequest) returns (TransactionResponse)

Request​

GetTransactionRequest contains the ID of the transaction that is being queried.


_10
message 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.


_10
message TransactionResponse {
_10
entities.Transaction transaction = 1;
_10
entities.Metadata metadata = 2;
_10
}

GetTransactionsByBlockID​

GetTransactionsByBlockID gets all the transactions for a specified block.


_10
rpc GetTransactionsByBlockID(GetTransactionsByBlockIDRequest) returns (TransactionsResponse);

Request​


_10
message GetTransactionsByBlockIDRequest {
_10
bytes block_id = 1;
_10
entities.EventEncodingVersion event_encoding_version = 2;
_10
}

Response​


_10
message TransactionsResponse {
_10
repeated entities.Transaction transactions = 1;
_10
entities.Metadata metadata = 2;
_10
}

GetTransactionResult​

GetTransactionResult gets the execution result of a transaction.


_10
rpc GetTransactionResult (GetTransactionRequest) returns (TransactionResultResponse)

Request​


_10
message GetTransactionRequest {
_10
bytes id = 1;
_10
bytes block_id = 2;
_10
bytes collection_id = 3;
_10
entities.EventEncodingVersion event_encoding_version = 4;
_10
}

Response​


_12
message 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 a transaction's result at a specified block and index.


_10
rpc GetTransactionResultByIndex(GetTransactionByIndexRequest) returns (TransactionResultResponse);

Request​


_10
message GetTransactionByIndexRequest {
_10
bytes block_id = 1;
_10
uint32 index = 2;
_10
entities.EventEncodingVersion event_encoding_version = 3;
_10
}

Response​


_12
message 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.


_10
rpc GetTransactionResultsByBlockID(GetTransactionsByBlockIDRequest) returns (TransactionResultsResponse);

Request​


_10
message GetTransactionsByBlockIDRequest {
_10
bytes block_id = 1;
_10
entities.EventEncodingVersion event_encoding_version = 2;
_10
}

Response​


_10
message TransactionResultsResponse {
_10
repeated TransactionResultResponse transaction_results = 1;
_10
entities.Metadata metadata = 2;
_10
}

GetSystemTransaction​

GetSystemTransaction gets the system transaction for a block.


_10
rpc GetSystemTransaction(GetSystemTransactionRequest) returns (TransactionResponse);

Request​


_10
message GetSystemTransactionRequest {
_10
bytes block_id = 1;
_10
}

Response​


_10
message TransactionResponse {
_10
entities.Transaction transaction = 1;
_10
entities.Metadata metadata = 2;
_10
}

GetSystemTransactionResult​

GetSystemTransactionResult gets the system transaction result for a block.


_10
rpc GetSystemTransactionResult(GetSystemTransactionResultRequest) returns (TransactionResultResponse);

Request​


_10
message GetSystemTransactionResultRequest {
_10
bytes block_id = 1;
_10
entities.EventEncodingVersion event_encoding_version = 2;
_10
}

Response​


_12
message 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.


_10
rpc GetAccount(GetAccountRequest) returns (GetAccountResponse)

Request​


_10
message GetAccountRequest {
_10
bytes address = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetAccountAtLatestBlock(GetAccountAtLatestBlockRequest) returns (AccountResponse)

Request​


_10
message GetAccountAtLatestBlockRequest {
_10
bytes address = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetAccountAtBlockHeight(GetAccountAtBlockHeightRequest) returns (AccountResponse)

Request​


_10
message GetAccountAtBlockHeightRequest {
_10
bytes address = 1;
_10
uint64 block_height = 2;
_10
}

Response​


_10
message 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.


_10
rpc GetAccountBalanceAtLatestBlock(GetAccountBalanceAtLatestBlockRequest) returns (AccountBalanceResponse);

Request​


_10
message GetAccountBalanceAtLatestBlockRequest {
_10
bytes address = 1
_10
}

Response​


_10
message 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.


_10
rpc GetAccountBalanceAtBlockHeight(GetAccountBalanceAtBlockHeightRequest) returns (AccountBalanceResponse);

Request​


_10
message GetAccountBalanceAtBlockHeightRequest {
_10
bytes address = 1;
_10
uint64 block_height = 2;
_10
}

Response​


_10
message 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.


_10
rpc GetAccountKeyAtLatestBlock(GetAccountKeyAtLatestBlockRequest) returns (AccountKeyResponse);

Request​


_10
message GetAccountKeyAtLatestBlockRequest {
_10
// address of account
_10
bytes address = 1;
_10
// index of key to return
_10
uint32 index = 2;
_10
}

Response​


_10
message 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.


_10
rpc GetAccountKeyAtBlockHeight(GetAccountKeyAtBlockHeightRequest) returns (AccountKeyResponse);

Request​


_10
message 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​


_10
message 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.


_10
rpc GetAccountKeysAtLatestBlock(GetAccountKeysAtLatestBlockRequest) returns (AccountKeysResponse);

Request​


_10
message GetAccountKeysAtLatestBlockRequest {
_10
// address of account
_10
bytes address = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetAccountKeysAtBlockHeight(GetAccountKeysAtBlockHeightRequest) returns (AccountKeysResponse);

Request​


_10
message GetAccountKeysAtBlockHeightRequest {
_10
// address of account
_10
bytes address = 1;
_10
uint64 block_height = 2;
_10
}

Response​


_10
message 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.


_10
rpc ExecuteScriptAtLatestBlock (ExecuteScriptAtLatestBlockRequest) returns (ExecuteScriptResponse)

This method is a shortcut for the following:


_10
header = GetLatestBlockHeader()
_10
value = ExecuteScriptAtBlockID(header.ID, script)

Request​


_10
message ExecuteScriptAtLatestBlockRequest {
_10
bytes script = 1;
_10
repeated bytes arguments = 2;
_10
}

Response​


_10
message 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.


_10
rpc ExecuteScriptAtBlockID (ExecuteScriptAtBlockIDRequest) returns (ExecuteScriptResponse)

Request​


_10
message ExecuteScriptAtBlockIDRequest {
_10
bytes block_id = 1;
_10
bytes script = 2;
_10
repeated bytes arguments = 3;
_10
}

Response​


_10
message 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.


_10
rpc ExecuteScriptAtBlockHeight (ExecuteScriptAtBlockHeightRequest) returns (ExecuteScriptResponse)

Request​


_10
message ExecuteScriptAtBlockHeightRequest {
_10
uint64 block_height = 1;
_10
bytes script = 2;
_10
repeated bytes arguments = 3;
_10
}

Response​


_10
message 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.


_10
rpc 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​


_10
message GetEventsForHeightRangeRequest {
_10
string type
_10
uint64 start_height = 2;
_10
uint64 end_height = 3;
_10
entities.EventEncodingVersion event_encoding_version = 4;
_10
}

Response​


_10
message 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.


_10
rpc 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​


_10
message GetEventsForBlockIDsRequest {
_10
string type = 1;
_10
repeated bytes block_ids = 2;
_10
entities.EventEncodingVersion event_encoding_version = 3;
_10
}

Response​


_10
message 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.


_10
rpc GetNetworkParameters (GetNetworkParametersRequest) returns (GetNetworkParametersResponse)

Request​


_10
message GetNetworkParametersRequest {}

Response​


_10
message GetNetworkParametersResponse {
_10
string chain_id = 1;
_10
}

FieldDescription
chain_idChain 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.


_10
rpc GetNodeVersionInfo (GetNodeVersionInfoRequest) returns (GetNodeVersionInfoResponse);

Request​


_10
message GetNodeVersionInfoRequest {}

Response​


_10
message 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.


_10
rpc GetLatestProtocolStateSnapshot (GetLatestProtocolStateSnapshotRequest) returns (ProtocolStateSnapshotResponse);

Request​


_10
message GetLatestProtocolStateSnapshotRequest {}

Response​


_10
message 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.


_10
rpc GetProtocolStateSnapshotByBlockID(GetProtocolStateSnapshotByBlockIDRequest) returns (ProtocolStateSnapshotResponse);

Request​


_10
message GetProtocolStateSnapshotByBlockIDRequest {
_10
bytes block_id = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetProtocolStateSnapshotByHeight(GetProtocolStateSnapshotByHeightRequest) returns (ProtocolStateSnapshotResponse);

Request​


_10
message GetProtocolStateSnapshotByHeightRequest {
_10
uint64 block_height = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetExecutionResultForBlockID(GetExecutionResultForBlockIDRequest) returns (ExecutionResultForBlockIDResponse);

Request​


_10
message GetExecutionResultForBlockIDRequest {
_10
bytes block_id = 1;
_10
}

Response​


_10
message 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.


_10
rpc GetExecutionResultByID(GetExecutionResultByIDRequest) returns (ExecutionResultByIDResponse);

Request​


_10
message GetExecutionResultByIDRequest {
_10
bytes id = 1;
_10
}

Response​


_10
message 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​


_13
message 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
}

FieldDescription
idSHA3-256 hash of the entire block payload
heightHeight of the block in the chain
parent_idID of the previous block in the chain
timestampTimestamp 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_guaranteesList of collection guarantees
block_sealsList of block seals
signaturesBLS signatures of consensus nodes
execution_receipt_metaListList of execution-receipt-meta
execution_result_listList of execution results
block_headerA summary of a block
protocol_state_idThe 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.


_16
message 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
}

FieldDescription
idSHA3-256 hash of the entire block payload
parent_idID of the previous block in the chain
heightHeight of the block in the chain
timestampThe time at which this block was proposed
payload_hashA hash of the payload of this block
viewView number during which this block was proposed.
parent_voter_idsAn array that represents all the voters ids for the parent block
parent_voter_sig_dataAn aggregated signature over the parent block
chain_idChain ID helps identify the Flow network. It can be one of flow-mainnet, flow-testnet or flow-emulator
parent_voter_indicesA bitvector that represents all the voters for the parent block
last_view_tcA timeout certificate for previous view, it can be nil. It has to be present if previous round ended with timeout
parent_viewA 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.


_10
message 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
}

FieldDescription
block_idID of the block being sealed
execution_receipt_idID execution receipt being sealed
execution_receipt_signaturesBLS signatures of verification nodes on the execution receipt contents
result_approval_signaturesBLS signatures of verification nodes on the result approval contents

Block Status​


_10
enum BlockStatus {
_10
UNKNOWN = 0;
_10
FINALIZED = 1;
_10
SEALED = 2;
_10
}

ValueDescription
UNKNOWNThe block status is not known
FINALIZEDThe consensus nodes have finalized the block
SEALEDThe 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.


_10
message Collection {
_10
bytes id = 1;
_10
repeated bytes transaction_ids = 2;
_10
}

FieldDescription
idSHA3-256 hash of the collection contents
transaction_idsOrdered 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.


_10
message 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
}

FieldDescription
collection_idSHA3-256 hash of the collection contents
signaturesBLS signatures of the collection nodes guaranteeing the collection
reference_block_idDefines expiry of the collection
signatureGuarantor signatures
signer_idsAn array that represents all the signer ids
signer_indicesEncoded indices of the signers

Transaction​

A transaction represents a unit of computation that is submitted to the Flow network.


_23
message 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
_23
message TransactionProposalKey {
_23
bytes address = 1;
_23
uint32 key_id = 2;
_23
uint64 sequence_number = 3;
_23
}
_23
_23
message TransactionSignature {
_23
bytes address = 1;
_23
uint32 key_id = 2;
_23
bytes signature = 3;
_23
}

FieldDescription
scriptRaw source code for a Cadence script, encoded as UTF-8 bytes
argumentsArguments passed to the Cadence script, encoded as JSON-Cadence bytes
reference_block_idBlock ID used to determine transaction expiry
proposal_keyAccount key used to propose the transaction
payerAddress of the payer account
authorizersAddresses of the transaction authorizers
signaturesSignatures 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.

FieldDescription
addressAddress of proposer account
key_idID of proposal key on the proposal account
sequence_numberSequence number for the proposal key

Transaction Signature​

FieldDescription
addressAddress of the account for this signature
key_idID of the account key
signatureRaw signature byte data

Transaction Status​


_10
enum TransactionStatus {
_10
UNKNOWN = 0;
_10
PENDING = 1;
_10
FINALIZED = 2;
_10
EXECUTED = 3;
_10
SEALED = 4;
_10
EXPIRED = 5;
_10
}

ValueDescription
UNKNOWNThe transaction status is not known.
PENDINGThe transaction has been received by a collector but not yet finalized in a block.
FINALIZEDThe consensus nodes have finalized the block that the transaction is included in
EXECUTEDThe execution nodes have produced a result for the transaction
SEALEDThe verification nodes have verified the transaction (the block in which the transaction is) and the seal is included in the latest block
EXPIREDThe 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.


_10
message 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
}

FieldDescription
addressA unique account identifier
balanceThe account balance
codeThe code deployed to this account (deprecated, use contracts instead)
keysA list of keys configured on this account
contractsA 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.


_10
message 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
}

FieldDescription
idIndex of the key within the account, used as a unique identifier
public_keyPublic key encoded as bytes
sign_algoSignature algorithm
hash_algoHash algorithm
weightWeight assigned to the key
sequence_numberSequence number for the key
revokedFlag 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.


_10
message 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
}

FieldDescription
typeFully-qualified unique type identifier for the event
transaction_idID of the transaction the event was emitted from
transaction_indexZero-based index of the transaction within the block
event_indexZero-based index of the event within the transaction
payloadEvent fields encoded as JSON-Cadence values

Execution Result​

Execution result for a particular block.


_10
message ExecutionResult {
_10
bytes previous_result_id = 1;
_10
bytes block_id = 2;
_10
repeated Chunk chunks = 3;
_10
repeated ServiceEvent service_events = 4;
_10
}

FieldDescription
previous_result_idIdentifier of parent block execution result
block_idID of the block this execution result corresponds to
chunksZero or more chunks
service_eventsZero or more service events

Execution Receipt Meta​

ExecutionReceiptMeta contains the fields from the Execution Receipts that vary from one executor to another


_10
message ExecutionReceiptMeta {
_10
bytes executor_id = 1;
_10
bytes result_id = 2;
_10
repeated bytes spocks = 3;
_10
bytes executor_signature = 4;
_10
}

FieldDescription
executor_idIdentifier of the executor node
result_idIdentifier of block execution result
spocksSPoCK
executor_signatureSignature of the executor

Chunk​

Chunk described execution information for given collection in a block


_12
message 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
}

FieldDescription
CollectionIndexIdentifier of a collection
start_stateState commitment at start of the chunk
event_collectionHash of events emitted by transactions in this chunk
block_idIdentifier of a block
total_computation_usedTotal computation used by transactions in this chunk
number_of_transactionsNumber of transactions in a chunk
indexIndex of chunk inside a block (zero-based)
end_stateState commitment after executing chunk
execution_data_idIdentifier of a execution data
state_delta_commitmentA commitment over sorted list of register changes

Service Event​

Special type of events emitted in system chunk used for controlling Flow system.


_10
message ServiceEvent {
_10
string type = 1;
_10
bytes payload = 2;
_10
}

FieldDescription
typeType of an event
payloadJSON-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.


_10
rpc SubscribeEvents(SubscribeEventsRequest) returns (stream SubscribeEventsResponse)

Request​


_10
message 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
}

FieldDescription
start_block_idThe 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_heightBlock 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
filterFilter to apply to events for each block searched. If no filter is provided, all events are returned
heartbeat_intervalInterval in block heights at which the server should return a heartbeat message to the client
event_encoding_versionPreferred event encoding version of the block events payload. Possible variants: CCF, JSON-CDC

Response​


_10
message 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.


_10
rpc SubscribeExecutionData(SubscribeExecutionDataRequest) returns (stream SubscribeExecutionDataResponse)

Request​


_10
message SubscribeExecutionDataRequest {
_10
bytes start_block_id = 1;
_10
uint64 start_block_height = 2;
_10
entities.EventEncodingVersion event_encoding_version = 3;
_10
}

FieldDescription
start_block_idThe 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_heightBlock 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_versionPreferred event encoding version of the block events payload. Possible variants: CCF, JSON-CDC

Response​


_10
message 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.


_10
message EventFilter {
_10
repeated string event_type = 1;
_10
repeated string contract = 2;
_10
repeated string address = 3;
_10
}

FieldDescription
event_typeA 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]
contractA 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
addressA 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.

execution data protobuf file

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

FlagTypeDescription
state-stream-addrstringListener 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-sizeuint32Number of block execution data objects to store in the cache. Default is 100.
state-stream-global-max-streamsuint32Global maximum number of concurrent streams. Default is 1000.
state-stream-max-message-sizeuintMaximum size for a gRPC response message containing block execution data. Default is 2010241024 (20MB).
state-stream-event-filter-limitsstringEvent 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-timeoutdurationMaximum wait before timing out while sending a response to a streaming client. Default is 30s.
state-stream-send-buffer-sizeuintMaximum number of unsent responses to buffer for a stream. Default is 10.
state-stream-response-limitfloat64Max 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.