diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40a4127272..57dff0a2f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,8 @@ The contribution process is designed to be straightforward and collaborative. He Note: Previews are built for each Git branch by Vercel workflow. -For additional assistance or integration support, feel free to request help in the `#devex-builders` [Discord channel](https://discord.com/channels/613813861610684416/1123314820763111465) on the [Flow Discord](https://discord.gg/flowblockchain) server. +For additional assistance or integration support, feel free to request help in the `#devex-builders` channel on the [Flow Discord](https://discord.gg/flow) server. + ## Updating Existing Content diff --git a/docs/build/advanced-concepts/randomness.md b/docs/build/advanced-concepts/randomness.md index 542ca5b2e2..13eedc275b 100644 --- a/docs/build/advanced-concepts/randomness.md +++ b/docs/build/advanced-concepts/randomness.md @@ -1,6 +1,6 @@ --- -title: Flow On-chain Randomness -sidebar_label: VRF (Randomness) +title: Flow On-chain Randomness in Cadence +sidebar_label: VRF (Randomness) in Cadence --- # Randomness on FLOW @@ -199,4 +199,4 @@ If you’d like to dive deeper into Flow’s onchain randomness, here’s a list - These documents provide a more in-depth technical understanding of the updates and enhancements to the Flow blockchain. - **[FLIP 120: Update unsafeRandom function](https://github.com/onflow/flips/blob/main/cadence/20230713-random-function.md#flip-120-update-unsaferandom-function)** - **[FLIP 123: On-chain Random beacon history for commit-reveal schemes](https://github.com/onflow/flips/blob/main/protocol/20230728-commit-reveal.md#flip-123-on-chain-random-beacon-history-for-commit-reveal-schemes)** -- To see working Cadence code, explore the [coin toss example on GitHub](https://github.com/onflow/random-coin-toss/tree/update-prg-impl). +- To see working Cadence code, explore the [coin toss example on GitHub](https://github.com/onflow/random-coin-toss). diff --git a/docs/build/basics/accounts.md b/docs/build/basics/accounts.md index 48b33da17f..8185c9b6e6 100644 --- a/docs/build/basics/accounts.md +++ b/docs/build/basics/accounts.md @@ -24,27 +24,54 @@ A simple representation of an account: ![Screenshot 2023-08-16 at 16.43.07.png](_accounts_images/Screenshot_2023-08-16_at_16.43.07.png) -**Address** +## Address A Flow address is represented as 16 hex-encoded characters (usually prefixed with `0x` to indicate hex encoding). Unlike Bitcoin and Ethereum, Flow addresses are not derived from cryptographic public keys. Instead, each Flow address is assigned by the Flow protocol using an on-chain deterministic sequence. The sequence uses an error detection code to guarantee that all addresses differ with at least 2 hex characters. This makes typos resulting in accidental loss of assets not possible. This decoupling is a unique advantage of Flow, allowing for multiple public keys to be associated with one account, or for a single public key to be used across several accounts. -**Balance** +## Balance Each Flow account created on Mainnet will by default [hold a Flow vault that holds a balance and is part of the FungibleToken standard](./flow-token.md). This balance is used to pay for [transaction fees and storage fees](./fees.md). More on that in the fees document. - +:::warning + The minimum amount of FLOW an account can have is **0.001**. - + +::: This minimum storage fee is provided by the account creator and covers the cost of storing up to 100kB of data in perpetuity. This fee is applied only once and can be "topped up" to add additional storage to an account. The minimum account reservation ensures that most accounts won't run out of storage capacity if anyone deposits anything (like an NFT) to the account. -**Contracts** + +### Maximum available balance + +Due to the storage restrictions, there is a maximum available balance that user can withdraw from the wallet. The core contract [`FlowStorageFees`](../core-contracts/05-flow-fees.md#flowstoragefees) provides a function to retrieve that value: + +```cadence +import "FlowStorageFees" + +access(all) fun main(accountAddress: Address): UFix64 { + return FlowStorageFees.defaultTokenAvailableBalance(accountAddress) +} +``` + +Alternatively developers can use `availableBalance` property of the `Account` + +```cadence +access(all) fun main(address: Address): UFix64 { + let acc = getAccount(address) + let balance = acc.availableBalance + + return balance +} + +``` + +## Contracts An account can optionally store multiple [Cadence contracts](https://cadence-lang.org/docs/language/contracts). The code is stored as a human-readable UTF-8 encoded string which makes it easy for anyone to inspect the contents. -**Storage** +## Storage Each Flow account has an associated storage and capacity. The account's storage used is the byte size of all the data stored in the account's storage. An account's [storage capacity is directly tied to the balance of Flow tokens](./fees.md#storage) an account has. An account can, without any additional cost, use any amount of storage up to its storage capacity. If a transaction puts an account over storage capacity or drops an account's balance below the minimum 0.001 Flow tokens, that transaction fails and is reverted. @@ -56,9 +83,11 @@ During account creation, public keys can be provided which will be used when int Each account key has a weight that determines the signing power it holds. - +:::warning + A transaction is not authorized to access an account unless it has a total signature weight greater than or equal to **1000**, the weight threshold. - + +::: For example, an account might contain 3 keys, each with 500 weight: @@ -104,10 +133,11 @@ An account on Flow doesn’t require keys in order to exist, but this makes the You can achieve keyless accounts by either removing an existing public key from an account signing with that same key and repeating that action until an account has no keys left, or you can create a new account that has no keys assigned. With account linking you can also have a child account that has no keys but is controlled by the parent. - +:::danger + Be careful when removing keys from an existing account, because once an account’s total key weights sum to less than 1000, it can no longer be modified. - +::: ### **Multi-Sig Accounts** @@ -143,10 +173,11 @@ For development purposes, [you can use Flow CLI to easily create emulator, testn Keys should be generated in a secure manner. Depending on the purpose of the keys different levels of caution need to be taken. - +:::warning + Anyone obtaining access to a private key can modify the account the key is associated with (assuming it has enough weight). Be very careful how you store the keys. - +::: For secure production keys, we suggest using key management services such as [Google key management](https://cloud.google.com/security-key-management) or [Amazon KMS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Encryption.Keys.html), which are also supported by our CLI and SDKs. Those services are mostly great when integrated into your application. However, for personal use, you can securely use any [existing wallets](../../ecosystem/wallets.md) as well as a [hardware Ledger wallet](../../ecosystem/wallets.md). diff --git a/docs/build/basics/fees.md b/docs/build/basics/fees.md index 60ca8e5c9f..8cd11713e3 100644 --- a/docs/build/basics/fees.md +++ b/docs/build/basics/fees.md @@ -77,19 +77,21 @@ Flow's approach to storage capacity is a bit similar to some banks' pricing mode Each Flow account has associated storage used. The account's storage used is the byte size of all the data stored in the account's storage. Accounts also have a storage capacity, which is directly tied to the amount of Flow tokens an account has. The account can, without any additional cost, use any amount of storage up to its storage capacity.  - +:::warning + If a transaction puts an account over storage capacity, that transaction fails and is reverted. Likewise, if a transaction would drop an account's balance below 0.001 Flow tokens, which is the minimum an account can have, the transaction would also fail. - +::: **Storage Capacity** The storage capacity of an account is dictated by the amount of FLOW it has.  - +:::danger + The **minimum amount of FLOW an account can have is 0.001**. This minimum is provided by the account creator at account creation. - +::: The minimum account reservation ensures that most accounts won't run out of storage capacity if anyone deposits anything (like an NFT) to the account. @@ -119,6 +121,29 @@ Adding additional keys, smart contracts, capabilities, resources, etc. to the ac Data stored on the Flow blockchain is stored in a key-value ledger. Each item’s key contains the address that owns the item and the path to the item. An account can have many keys, therefore flow considers the account key items are stored with. This means that the storage used by each item is the byte length of the item plus the byte length of the item’s key. +### Maximum available balance + +Due to the storage restrictions, there is a maximum available balance that user can withdraw from the wallet. The core contract [`FlowStorageFees`](../core-contracts/05-flow-fees.md#flowstoragefees) provides a function to retrieve that value: + +```cadence +import "FlowStorageFees" + +access(all) fun main(accountAddress: Address): UFix64 { + return FlowStorageFees.defaultTokenAvailableBalance(accountAddress) +} +``` + +Alternatively developers can use `availableBalance` property of the `Account` + +```cadence +access(all) fun main(address: Address): UFix64 { + let acc = getAccount(address) + let balance = acc.availableBalance + + return balance +} + +``` ## Practical Understanding of Fees diff --git a/docs/build/core-contracts/05-flow-fees.md b/docs/build/core-contracts/05-flow-fees.md index 50a4364637..c0dcc73804 100644 --- a/docs/build/core-contracts/05-flow-fees.md +++ b/docs/build/core-contracts/05-flow-fees.md @@ -4,7 +4,7 @@ sidebar_position: 5 sidebar_label: Flow Fees --- -# FlowFees +## FlowFees The `FlowFees` contract is where all the collected flow fees are gathered. @@ -17,7 +17,7 @@ Source: [FlowFees.cdc](https://github.com/onflow/flow-core-contracts/blob/master | Testnet | `0x912d5440f7e3769e` | | Mainnet | `0xf919ee77447b7497` | -## Events +### Events Important events for `FlowFees` are: @@ -35,7 +35,7 @@ access(all) event FeesDeducted(amount: UFix64, inclusionEffort: UFix64, executio access(all) event FeeParametersChanged(surgeFactor: UFix64, inclusionEffortCost: UFix64, executionEffortCost: UFix64) ``` -# FlowStorageFees +## FlowStorageFees The `FlowStorageFees` contract defines the parameters and utility methods for storage fees. @@ -48,7 +48,7 @@ Source: [FlowStorageFees.cdc](https://github.com/onflow/flow-core-contracts/blob | Testnet | `0x8c5303eaa26202d6` | | Mainnet | `0xe467b9dd11fa00df` | -## Events +### Events Important events for `FlowStorageFees` are: diff --git a/docs/build/guides/flow-app-quickstart.md b/docs/build/guides/flow-app-quickstart.md index 630f770115..c2c0634924 100644 --- a/docs/build/guides/flow-app-quickstart.md +++ b/docs/build/guides/flow-app-quickstart.md @@ -40,7 +40,7 @@ This guide assumes a good understanding of React. The concepts are easy to under - [Query the Blockchain](#query-the-blockchain) - [Mutate the Blockchain](#mutate-the-blockchain) -For more help, [Discord](https://discord.gg/flowblockchain). See links at the end of this article for diving deeper into building on Flow. +For more help, [Discord](https://discord.com/invite/J6fFnh2xx6). See links at the end of this article for diving deeper into building on Flow. ## Installation diff --git a/docs/evm/about.md b/docs/evm/about.md index ec73759811..02bba4591f 100644 --- a/docs/evm/about.md +++ b/docs/evm/about.md @@ -40,7 +40,7 @@ The MEV Resilient design on Flow offers DeFi builders improved market efficiency ## Join the Community -Are you interested in launching an EVM project on Flow or partnering with us? Visit our weekly Flow [office hours](https://calendar.google.com/calendar/ical/c_47978f5cd9da636cadc6b8473102b5092c1a865dd010558393ecb7f9fd0c9ad0%40group.calendar.google.com/public/basic.ics) for discussions on project development and other opportunities for collaboration. You can also chat with us in the Flow [Discord](https://discord.com/channels/613813861610684416/1167476806333513800). +Are you interested in launching an EVM project on Flow or partnering with us? Visit our weekly Flow [office hours](https://calendar.google.com/calendar/ical/c_47978f5cd9da636cadc6b8473102b5092c1a865dd010558393ecb7f9fd0c9ad0%40group.calendar.google.com/public/basic.ics) for discussions on project development and other opportunities for collaboration. You can also chat with us developers-chat in the Flow [Discord](https://discord.gg/flow). ## Further Reading and Discussions diff --git a/docs/evm/cadence/interacting-with-coa.md b/docs/evm/cadence/interacting-with-coa.md index 5881eebeb0..75d03a656c 100644 --- a/docs/evm/cadence/interacting-with-coa.md +++ b/docs/evm/cadence/interacting-with-coa.md @@ -136,7 +136,7 @@ import "EVM" access(all) fun main(address: Address): EVM.EVMAddress { // Get the desired Flow account holding the COA in storage - let account: = getAuthAccount(address) + let account = getAuthAccount(address) // Borrow a reference to the COA from the storage location we saved it to let coa = account.storage.borrow<&EVM.CadenceOwnedAccount>( @@ -168,7 +168,7 @@ import "EVM" access(all) fun main(address: Address): EVM.Balance { // Get the desired Flow account holding the COA in storage - let account: = getAuthAccount(address) + let account = getAuthAccount(address) // Borrow a reference to the COA from the storage location we saved it to let coa = account.storage.borrow<&EVM.CadenceOwnedAccount>( @@ -217,9 +217,8 @@ transaction(amount: UFix64) { prepare(signer: auth(BorrowValue) &Account) { // Borrow the public capability to the COA from the desired account // This script could be modified to deposit into any account with a `EVM.CadenceOwnedAccount` capability - self.coa = signer.capabilities.borrow<&EVM.CadenceOwnedAccount>( - from: /public/evm - ) ?? panic("Could not borrow reference to the COA") + self.coa = signer.capabilities.borrow<&EVM.CadenceOwnedAccount>(/public/evm) + ?? panic("Could not borrow reference to the COA") // Withdraw the balance from the COA, we will use this later to deposit into the receiving account let vaultRef = signer.storage.borrow( @@ -230,7 +229,7 @@ transaction(amount: UFix64) { execute { // Deposit the withdrawn tokens into the COA - coa.deposit(from: <-self.sentVault) + self.coa.deposit(from: <-self.sentVault) } } ``` @@ -276,7 +275,7 @@ transaction(amount: UFix64) { execute { // Deposit the withdrawn tokens into the receiving vault - receiver.deposit(from: <-self.sentVault) + self.receiver.deposit(from: <-self.sentVault) } } ``` @@ -294,7 +293,7 @@ This transaction will use the signer's COA to call a contract method with the de ```cadence import "EVM" -transaction(evmContractHex: String, signature: String, args: [AnyStruct], gasLimit: UInt64, value: UFix64) { +transaction(evmContractHex: String, signature: String, args: [AnyStruct], gasLimit: UInt64, flowValue: UFix64) { let coa: auth(EVM.Call) &EVM.CadenceOwnedAccount prepare(signer: auth(BorrowValue) &Account) { @@ -314,11 +313,11 @@ transaction(evmContractHex: String, signature: String, args: [AnyStruct], gasLim ) // Define the value as EVM.Balance struct let value = EVM.Balance(attoflow: 0) - value.setFLOW(flow: value) + value.setFLOW(flow: flowValue) // Call the contract at the given EVM address with the given data, gas limit, and value // These values could be configured through the transaction arguments or other means // however, for simplicity, we will hardcode them here - let result: EVM.Result = coa.call( + let result: EVM.Result = self.coa.call( to: contractAddress, data: calldata, gasLimit: gasLimit, diff --git a/docs/networks/flow-port/index.md b/docs/networks/flow-port/index.md index b97bfd4c36..6446009de1 100644 --- a/docs/networks/flow-port/index.md +++ b/docs/networks/flow-port/index.md @@ -154,4 +154,4 @@ Please see a list [here](https://github.com/onflow/flow/blob/master/nodeoperator 6. I am clicking 'submit' to execute a transaction, but nothing is happening. How can I unblock myself? - - a.) Please disable any pop-up blockers and ad blockers you have and refresh the page. If you are still experiencing issues, please reach out via [Discord](https://discord.gg/4yGnMzkZxr) in the appropriate channel. + - a.) Please disable any pop-up blockers and ad blockers you have and refresh the page. If you are still experiencing issues, please reach out via [Discord](https://discord.gg/flow) in the appropriate channel. diff --git a/docs/networks/node-ops/access-onchain-data/access-nodes/access-node-setup.mdx b/docs/networks/node-ops/access-onchain-data/access-nodes/access-node-setup.mdx index 4e326467a2..0bf907bd51 100644 --- a/docs/networks/node-ops/access-onchain-data/access-nodes/access-node-setup.mdx +++ b/docs/networks/node-ops/access-onchain-data/access-nodes/access-node-setup.mdx @@ -78,7 +78,7 @@ tar -xvf boot-tools.tar ```shell CheckSHA256 sha256sum ./boot-tools/bootstrap -315f4ff5cf85a20a05fe1c37aaa1beaad7733b488ca80605a8f7ef00f797d445 ./boot-tools/bootstrap +460cfcfeb52b40d8b8b0c4641bc4e423bcc90f82068e95f4267803ed32c26d60 ./boot-tools/bootstrap ``` > If you have downloaded the bootstrapping kit previously, ensure the SHA256 hash for it still matches. If not, re-download to ensure you are using the most up-to-date version. diff --git a/docs/networks/node-ops/access-onchain-data/access-nodes/accessing-data/access-api.md b/docs/networks/node-ops/access-onchain-data/access-nodes/accessing-data/access-api.md index 3dcb0147be..25cc2d4b2e 100644 --- a/docs/networks/node-ops/access-onchain-data/access-nodes/accessing-data/access-api.md +++ b/docs/networks/node-ops/access-onchain-data/access-nodes/accessing-data/access-api.md @@ -59,7 +59,7 @@ rpc GetLatestBlockHeader (GetLatestBlockHeaderRequest) returns (BlockHeaderRespo ```proto message GetLatestBlockHeaderRequest { - bool is_sealed + bool is_sealed = 1; } ``` @@ -67,8 +67,9 @@ message GetLatestBlockHeaderRequest { ```proto message BlockHeaderResponse { - flow.BlockHeader block - flow.BlockStatus block_status + entities.BlockHeader block = 1; + entities.BlockStatus block_status = 2; + entities.Metadata metadata = 3; } ``` @@ -84,7 +85,7 @@ rpc GetBlockHeaderByID (GetBlockHeaderByIDRequest) returns (BlockHeaderResponse) ```proto message GetBlockHeaderByIDRequest { - bytes id + bytes id = 1; } ``` @@ -92,8 +93,9 @@ message GetBlockHeaderByIDRequest { ```proto message BlockHeaderResponse { - flow.BlockHeader block - flow.BlockStatus block_status + entities.BlockHeader block = 1; + entities.BlockStatus block_status = 2; + entities.Metadata metadata = 3; } ``` @@ -109,7 +111,7 @@ rpc GetBlockHeaderByHeight (GetBlockHeaderByHeightRequest) returns (BlockHeaderR ```proto message GetBlockHeaderByHeightRequest { - uint64 height + uint64 height = 1; } ``` @@ -117,8 +119,9 @@ message GetBlockHeaderByHeightRequest { ```proto message BlockHeaderResponse { - flow.BlockHeader block - flow.BlockStatus block_status + entities.BlockHeader block = 1; + entities.BlockStatus block_status = 2; + entities.Metadata metadata = 3; } ``` @@ -140,7 +143,8 @@ rpc GetLatestBlock (GetLatestBlockRequest) returns (BlockResponse) ```proto message GetLatestBlockRequest { - bool is_sealed + bool is_sealed = 1; + bool full_block_response = 2; } ``` @@ -148,8 +152,9 @@ message GetLatestBlockRequest { ```proto message BlockResponse { - flow.Block block - flow.BlockStatus block_status + entities.Block block = 1; + entities.BlockStatus block_status = 2; + entities.Metadata metadata = 3; } ``` @@ -165,7 +170,8 @@ rpc GetBlockByID (GetBlockByIDRequest) returns (BlockResponse) ```proto message GetBlockByIDRequest { - bytes id + bytes id = 1; + bool full_block_response = 2; } ``` @@ -173,8 +179,9 @@ message GetBlockByIDRequest { ```proto message BlockResponse { - flow.Block block - flow.BlockStatus block_status + entities.Block block = 1; + entities.BlockStatus block_status = 2; + entities.Metadata metadata = 3; } ``` @@ -190,7 +197,8 @@ rpc GetBlockByHeight (GetBlockByHeightRequest) returns (BlockResponse) ```proto message GetBlockByHeightRequest { - uint64 height + uint64 height = 1; + bool full_block_response = 2; } ``` @@ -198,8 +206,9 @@ message GetBlockByHeightRequest { ```proto message BlockResponse { - flow.Block block - flow.BlockStatus block_status + entities.Block block = 1; + entities.BlockStatus block_status = 2; + entities.Metadata metadata = 3; } ``` @@ -221,7 +230,7 @@ rpc GetCollectionByID (GetCollectionByIDRequest) returns (CollectionResponse) ```proto message GetCollectionByIDRequest { - bytes id + bytes id = 1; } ``` @@ -229,7 +238,35 @@ message GetCollectionByIDRequest { ```proto message CollectionResponse { - flow.Collection collection + entities.Collection collection = 1; + entities.Metadata metadata = 2; +} +``` + +--- + +### GetFullCollectionByID + +`GetFullCollectionByID` gets a collection by ID, which contains a set of [transactions](#transaction). + +```proto +rpc GetFullCollectionByID(GetFullCollectionByIDRequest) returns (FullCollectionResponse); +``` + +#### Request + +```proto +message GetFullCollectionByIDRequest { + bytes id = 1; +} +``` + +#### Response + +```proto +message FullCollectionResponse { + repeated entities.Transaction transactions = 1; + entities.Metadata metadata = 2; } ``` @@ -255,7 +292,7 @@ rpc SendTransaction (SendTransactionRequest) returns (SendTransactionResponse) ```proto message SendTransactionRequest { - flow.Transaction transaction + entities.Transaction transaction = 1; } ``` @@ -265,7 +302,8 @@ message SendTransactionRequest { ```proto message SendTransactionResponse { - bytes id + bytes id = 1; + entities.Metadata metadata = 2; } ``` @@ -287,7 +325,10 @@ rpc GetTransaction (GetTransactionRequest) returns (TransactionResponse) ```proto message GetTransactionRequest { - bytes id + bytes id = 1; + bytes block_id = 2; + bytes collection_id = 3; + entities.EventEncodingVersion event_encoding_version = 4; } ``` @@ -297,7 +338,34 @@ message GetTransactionRequest { ```proto message TransactionResponse { - flow.Transaction transaction + entities.Transaction transaction = 1; + entities.Metadata metadata = 2; +} +``` + +### GetTransactionsByBlockID + +`GetTransactionsByBlockID` gets all the [transactions](#transaction) for a specified block. + +```proto +rpc GetTransactionsByBlockID(GetTransactionsByBlockIDRequest) returns (TransactionsResponse); +``` + +#### Request + +```proto +message GetTransactionsByBlockIDRequest { + bytes block_id = 1; + entities.EventEncodingVersion event_encoding_version = 2; +} +``` + +#### Response + +```proto +message TransactionsResponse { + repeated entities.Transaction transactions = 1; + entities.Metadata metadata = 2; } ``` @@ -313,7 +381,129 @@ rpc GetTransactionResult (GetTransactionRequest) returns (TransactionResultRespo ```proto message GetTransactionRequest { - bytes id + bytes id = 1; + bytes block_id = 2; + bytes collection_id = 3; + entities.EventEncodingVersion event_encoding_version = 4; +} +``` + +#### Response + +```proto +message TransactionResultResponse { + entities.TransactionStatus status = 1; + uint32 status_code = 2; + string error_message = 3; + repeated entities.Event events = 4; + bytes block_id = 5; + bytes transaction_id = 6; + bytes collection_id = 7; + uint64 block_height = 8; + entities.Metadata metadata = 9; + uint64 computation_usage = 10; +} +``` +### GetTransactionResultByIndex + +`GetTransactionResultByIndex` gets a transaction's result at a specified block and index. + +```proto +rpc GetTransactionResultByIndex(GetTransactionByIndexRequest) returns (TransactionResultResponse); +``` + +#### Request + +```proto +message GetTransactionByIndexRequest { + bytes block_id = 1; + uint32 index = 2; + entities.EventEncodingVersion event_encoding_version = 3; +} +``` + +#### Response + +```proto +message TransactionResultResponse { + entities.TransactionStatus status = 1; + uint32 status_code = 2; + string error_message = 3; + repeated entities.Event events = 4; + bytes block_id = 5; + bytes transaction_id = 6; + bytes collection_id = 7; + uint64 block_height = 8; + entities.Metadata metadata = 9; + uint64 computation_usage = 10; +} +``` + +### GetTransactionResultsByBlockID + +`GetTransactionResultsByBlockID` gets all the transaction results for a specified block. + +```proto +rpc GetTransactionResultsByBlockID(GetTransactionsByBlockIDRequest) returns (TransactionResultsResponse); +``` + +#### Request + +```proto +message GetTransactionsByBlockIDRequest { + bytes block_id = 1; + entities.EventEncodingVersion event_encoding_version = 2; +} +``` + +#### Response + +```proto +message TransactionResultsResponse { + repeated TransactionResultResponse transaction_results = 1; + entities.Metadata metadata = 2; +} +``` + +### GetSystemTransaction + +`GetSystemTransaction` gets the system transaction for a block. + +```proto +rpc GetSystemTransaction(GetSystemTransactionRequest) returns (TransactionResponse); +``` + +#### Request + +```proto +message GetSystemTransactionRequest { + bytes block_id = 1; +} +``` + +#### Response + +```proto +message TransactionResponse { + entities.Transaction transaction = 1; + entities.Metadata metadata = 2; +} +``` + +### GetSystemTransactionResult + +`GetSystemTransactionResult` gets the system transaction result for a block. + +```proto +rpc GetSystemTransactionResult(GetSystemTransactionResultRequest) returns (TransactionResultResponse); +``` + +#### Request + +```proto +message GetSystemTransactionResultRequest { + bytes block_id = 1; + entities.EventEncodingVersion event_encoding_version = 2; } ``` @@ -321,10 +511,16 @@ message GetTransactionRequest { ```proto message TransactionResultResponse { - flow.TransactionStatus status - uint32 status_code - string error_message - repeated flow.Event events + entities.TransactionStatus status = 1; + uint32 status_code = 2; + string error_message = 3; + repeated entities.Event events = 4; + bytes block_id = 5; + bytes transaction_id = 6; + bytes collection_id = 7; + uint64 block_height = 8; + entities.Metadata metadata = 9; + uint64 computation_usage = 10; } ``` @@ -346,7 +542,7 @@ rpc GetAccount(GetAccountRequest) returns (GetAccountResponse) ```proto message GetAccountRequest { - bytes address + bytes address = 1; } ``` @@ -354,7 +550,8 @@ message GetAccountRequest { ```proto message GetAccountResponse { - Account account + entities.Account account = 1; + entities.Metadata metadata = 2; } ``` @@ -372,7 +569,7 @@ rpc GetAccountAtLatestBlock(GetAccountAtLatestBlockRequest) returns (AccountResp ```proto message GetAccountAtLatestBlockRequest { - bytes address + bytes address = 1; } ``` @@ -380,7 +577,8 @@ message GetAccountAtLatestBlockRequest { ```proto message AccountResponse { - Account account + entities.Account account = 1; + entities.Metadata metadata = 2; } ``` @@ -398,8 +596,8 @@ rpc GetAccountAtBlockHeight(GetAccountAtBlockHeightRequest) returns (AccountResp ```proto message GetAccountAtBlockHeightRequest { - bytes address - uint64 block_height + bytes address = 1; + uint64 block_height = 2; } ``` @@ -407,7 +605,170 @@ message GetAccountAtBlockHeightRequest { ```proto message AccountResponse { - Account account + entities.Account account = 1; + entities.Metadata metadata = 2; +} +``` + +### GetAccountBalanceAtLatestBlock + +`GetAccountBalanceAtLatestBlock` gets an account's balance by address from the latest sealed block. + +```proto +rpc GetAccountBalanceAtLatestBlock(GetAccountBalanceAtLatestBlockRequest) returns (AccountBalanceResponse); +``` + +#### Request + +```proto +message GetAccountBalanceAtLatestBlockRequest { + bytes address = 1 +} +``` + +#### Response + +```proto +message AccountBalanceResponse { + uint64 balance = 1; + entities.Metadata metadata = 2; +} +``` + +### GetAccountBalanceAtBlockHeight + +`GetAccountBalanceAtBlockHeight` gets an account's balance by address at the given block height. + +```proto +rpc GetAccountBalanceAtBlockHeight(GetAccountBalanceAtBlockHeightRequest) returns (AccountBalanceResponse); +``` + +#### Request + +```proto +message GetAccountBalanceAtBlockHeightRequest { + bytes address = 1; + uint64 block_height = 2; +} +``` + +#### Response + +```proto +message AccountBalanceResponse { + uint64 balance = 1; + entities.Metadata metadata = 2; +} +``` + +### GetAccountKeyAtLatestBlock + +`GetAccountKeyAtLatestBlock` gets an account's public key by address and key index from the latest sealed block. + +```proto +rpc GetAccountKeyAtLatestBlock(GetAccountKeyAtLatestBlockRequest) returns (AccountKeyResponse); +``` + +#### Request + +```proto +message GetAccountKeyAtLatestBlockRequest { + // address of account + bytes address = 1; + // index of key to return + uint32 index = 2; +} +``` + +#### Response + +```proto +message AccountKeyResponse { + entities.AccountKey account_key = 1; + entities.Metadata metadata = 2; +} +``` + +### GetAccountKeyAtBlockHeight + +`GetAccountKeyAtBlockHeight` gets an account's public key by address and key index at the given block height. + +```proto +rpc GetAccountKeyAtBlockHeight(GetAccountKeyAtBlockHeightRequest) returns (AccountKeyResponse); +``` + +#### Request + +```proto +message GetAccountKeyAtBlockHeightRequest { + // address of account + bytes address = 1; + // height of the block + uint64 block_height = 2; + // index of key to return + uint32 index = 3; +} +``` + +#### Response + +```proto +message AccountKeyResponse { + entities.AccountKey account_key = 1; + entities.Metadata metadata = 2; +} +``` + +### GetAccountKeysAtLatestBlock + +`GetAccountKeysAtLatestBlock` gets an account's public keys by address from the latest sealed block. + +```proto +rpc GetAccountKeysAtLatestBlock(GetAccountKeysAtLatestBlockRequest) returns (AccountKeysResponse); +``` + +#### Request + +```proto +message GetAccountKeysAtLatestBlockRequest { + // address of account + bytes address = 1; +} +``` + +#### Response + +```proto +message AccountKeysResponse { + repeated entities.AccountKey account_keys = 1; + entities.Metadata metadata = 2; +} +``` + +### GetAccountKeysAtBlockHeight + +`GetAccountKeysAtBlockHeight` gets an account's public keys by address at the given block height. + +```proto +rpc GetAccountKeysAtBlockHeight(GetAccountKeysAtBlockHeightRequest) returns (AccountKeysResponse); +``` + +#### Request + +```proto +message GetAccountKeysAtBlockHeightRequest { + // address of account + bytes address = 1; + uint64 block_height = 2; +} +``` + +#### Response + +```proto +message AccountKeysResponse { + repeated entities.AccountKey account_keys = 1; + entities.Metadata metadata = 2; } ``` @@ -436,7 +797,8 @@ value = ExecuteScriptAtBlockID(header.ID, script) ```proto message ExecuteScriptAtLatestBlockRequest { - bytes script + bytes script = 1; + repeated bytes arguments = 2; } ``` @@ -444,7 +806,9 @@ message ExecuteScriptAtLatestBlockRequest { ```proto message ExecuteScriptResponse { - bytes value + bytes value = 1; + entities.Metadata metadata = 2; + uint64 computation_usage = 3; } ``` @@ -462,8 +826,9 @@ rpc ExecuteScriptAtBlockID (ExecuteScriptAtBlockIDRequest) returns (ExecuteScrip ```proto message ExecuteScriptAtBlockIDRequest { - bytes block_id - bytes script + bytes block_id = 1; + bytes script = 2; + repeated bytes arguments = 3; } ``` @@ -471,7 +836,9 @@ message ExecuteScriptAtBlockIDRequest { ```proto message ExecuteScriptResponse { - bytes value + bytes value = 1; + entities.Metadata metadata = 2; + uint64 computation_usage = 3; } ``` @@ -489,8 +856,9 @@ rpc ExecuteScriptAtBlockHeight (ExecuteScriptAtBlockHeightRequest) returns (Exec ```proto message ExecuteScriptAtBlockHeightRequest { - uint64 block_height - bytes script + uint64 block_height = 1; + bytes script = 2; + repeated bytes arguments = 3; } ``` @@ -498,7 +866,9 @@ message ExecuteScriptAtBlockHeightRequest { ```proto message ExecuteScriptResponse { - bytes value + bytes value = 1; + entities.Metadata metadata = 2; + uint64 computation_usage = 3; } ``` @@ -533,6 +903,7 @@ message GetEventsForHeightRangeRequest { string type uint64 start_height = 2; uint64 end_height = 3; + entities.EventEncodingVersion event_encoding_version = 4; } ``` @@ -547,6 +918,7 @@ message EventsResponse { google.protobuf.Timestamp block_timestamp = 4; } repeated Result results = 1; + entities.Metadata metadata = 2; } ``` @@ -568,6 +940,7 @@ The event results are grouped by block, with each group specifying a block ID, h message GetEventsForBlockIDsRequest { string type = 1; repeated bytes block_ids = 2; + entities.EventEncodingVersion event_encoding_version = 3; } ``` @@ -582,6 +955,7 @@ message EventsResponse { google.protobuf.Timestamp block_timestamp = 4; } repeated Result results = 1; + entities.Metadata metadata = 2; } ``` @@ -620,13 +994,37 @@ message GetNetworkParametersResponse { --- +### GetNodeVersionInfo + +`GetNodeVersionInfo` gets information about a node's current versions. + +```proto +rpc GetNodeVersionInfo (GetNodeVersionInfoRequest) returns (GetNodeVersionInfoResponse); +``` + +#### Request + +```proto +message GetNodeVersionInfoRequest {} +``` + +#### Response + +```proto +message GetNodeVersionInfoResponse { + entities.NodeVersionInfo info = 1; +} +``` + +--- + ## Protocol state snapshot The following method can be used to query the latest protocol state [snapshot](https://github.com/onflow/flow-go/blob/master/state/protocol/snapshot.go). -### GetLatestProtocolStateSnapshotRequest +### GetLatestProtocolStateSnapshot -`GetLatestProtocolStateSnapshotRequest` retrieves the latest Protocol state snapshot serialized as a byte array. +`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. ```proto @@ -644,6 +1042,59 @@ message GetLatestProtocolStateSnapshotRequest {} ```proto message ProtocolStateSnapshotResponse { bytes serializedSnapshot = 1; + entities.Metadata metadata = 2; +} +``` + +### 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. + +```proto +rpc GetProtocolStateSnapshotByBlockID(GetProtocolStateSnapshotByBlockIDRequest) returns (ProtocolStateSnapshotResponse); +``` + +#### Request + +```proto +message GetProtocolStateSnapshotByBlockIDRequest { + bytes block_id = 1; +} +``` + +#### Response + +```proto +message ProtocolStateSnapshotResponse { + bytes serializedSnapshot = 1; + entities.Metadata metadata = 2; +} +``` + +### 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. + +```proto +rpc GetProtocolStateSnapshotByHeight(GetProtocolStateSnapshotByHeightRequest) returns (ProtocolStateSnapshotResponse); +``` + +#### Request + +```proto +message GetProtocolStateSnapshotByHeightRequest { + uint64 block_height = 1; +} +``` + +#### Response + +```proto +message ProtocolStateSnapshotResponse { + bytes serializedSnapshot = 1; + entities.Metadata metadata = 2; } ``` @@ -674,9 +1125,38 @@ message GetExecutionResultForBlockIDRequest { ```proto message ExecutionResultForBlockIDResponse { flow.ExecutionResult execution_result = 1; + entities.Metadata metadata = 2; +} +``` + +### 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. + +```proto +rpc GetExecutionResultByID(GetExecutionResultByIDRequest) returns (ExecutionResultByIDResponse); +``` + +#### Request + +```proto +message GetExecutionResultByIDRequest { + bytes id = 1; +} +``` + +#### Response + +```proto +message ExecutionResultByIDResponse { + flow.ExecutionResult execution_result = 1; + entities.Metadata metadata = 2; } ``` + ## Entities Below are in-depth descriptions of each of the data entities returned or accepted by the Access API. @@ -685,25 +1165,33 @@ Below are in-depth descriptions of each of the data entities returned or accepte ```proto message Block { - bytes id - bytes parent_id - uint64 height - google.protobuf.Timestamp timestamp - repeated CollectionGuarantee collection_guarantees - repeated BlockSeal block_seals - repeated bytes signatures -} -``` - -| 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](#collection-guarantee) | -| block_seals | List of [block seals](#block-seal) | -| signatures | BLS signatures of consensus nodes | + bytes id = 1; + bytes parent_id = 2; + uint64 height = 3; + google.protobuf.Timestamp timestamp = 4; + repeated CollectionGuarantee collection_guarantees = 5; + repeated BlockSeal block_seals = 6; + repeated bytes signatures = 7; + repeated ExecutionReceiptMeta execution_receipt_metaList = 8; + repeated ExecutionResult execution_result_list = 9; + BlockHeader block_header = 10; + bytes protocol_state_id = 11; +} +``` + +| 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](#collection-guarantee) | +| block_seals | List of [block seals](#block-seal) | +| signatures | BLS signatures of consensus nodes | +| execution_receipt_metaList | List of [execution-receipt-meta](#execution-receipt-meta) | +| execution_result_list | List of [execution results](#execution-result) | +| block_header | A summary of a [block](#block-header) | +| protocol_state_id | The root hash of protocol state. | The detailed semantics of block formation are covered in the [block formation guide](../../../../../build/basics/blocks.md). @@ -713,17 +1201,37 @@ A block header is a summary of a [block](#block) and contains only the block ID, ```proto message BlockHeader { - bytes id - bytes parent_id - uint64 height + bytes id = 1; + bytes parent_id = 2; + uint64 height = 3; + google.protobuf.Timestamp timestamp = 4; + bytes payload_hash = 5; + uint64 view = 6; + repeated bytes parent_voter_ids = 7; + bytes parent_voter_sig_data = 8; + bytes proposer_id = 9; + bytes proposer_sig_data = 10; + string chain_id = 11; + bytes parent_voter_indices = 12; + TimeoutCertificate last_view_tc = 13; + uint64 parent_view = 14; } ``` -| 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 | +| 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 | View number during 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 @@ -731,10 +1239,10 @@ A block seal is an attestation that the execution result of a specific [block](# ```proto message BlockSeal { - bytes block_id - bytes execution_receipt_id - repeated bytes execution_receipt_signatures - repeated bytes result_approval_signatures + bytes block_id = 1; + bytes execution_receipt_id = 2; + repeated bytes execution_receipt_signatures = 3; + repeated bytes result_approval_signatures = 4; } ``` @@ -755,11 +1263,11 @@ enum BlockStatus { } ``` -| 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 | +| 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 @@ -767,15 +1275,15 @@ A collection is a batch of [transactions](#transaction) that have been included ```proto message Collection { - bytes id - repeated bytes transaction_ids + bytes id = 1; + repeated bytes transaction_ids = 2; } ``` -| Field | Description | -| --------------- | ------------------------------------------------- | -| id | SHA3-256 hash of the collection contents | -| transaction_ids | Ordered list of transaction IDs in the collection | +| Field | Description | +|------------------|---------------------------------------------------| +| id | SHA3-256 hash of the collection contents | +| transaction_ids | Ordered list of transaction IDs in the collection | ### Collection Guarantee @@ -783,15 +1291,23 @@ A collection guarantee is a signed attestation that specifies the collection nod ```proto message CollectionGuarantee { - bytes collection_id - repeated bytes signatures + bytes collection_id = 1; + repeated bytes signatures = 2; + bytes reference_block_id = 3; + bytes signature = 4; + repeated bytes signer_ids = 5; // deprecated!! value will be empty. replaced by signer_indices + bytes signer_indices = 6; } ``` -| Field | Description | -| ------------- | ------------------------------------------------------------------ | -| collection_id | SHA3-256 hash of the collection contents | -| signatures | BLS signatures of the collection nodes guaranteeing the collection | +| 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 @@ -799,27 +1315,27 @@ A transaction represents a unit of computation that is submitted to the Flow net ```proto message Transaction { - bytes script - repeated bytes arguments - bytes reference_block_id - uint64 gas_limit - TransactionProposalKey proposal_key - bytes payer - repeated bytes authorizers - repeated TransactionSignature payload_signatures - repeated TransactionSignature envelope_signatures + bytes script = 1; + repeated bytes arguments = 2; + bytes reference_block_id = 3; + uint64 gas_limit = 4; + ProposalKey proposal_key = 5; + bytes payer = 6; + repeated bytes authorizers = 7; + repeated Signature payload_signatures = 8; + repeated Signature envelope_signatures = 9; } message TransactionProposalKey { - bytes address - uint32 key_id - uint64 sequence_number + bytes address = 1; + uint32 key_id = 2; + uint64 sequence_number = 3; } message TransactionSignature { - bytes address - uint32 key_id - bytes signature + bytes address = 1; + uint32 key_id = 2; + bytes signature = 3; } ``` @@ -881,11 +1397,11 @@ An account is a user's identity on Flow. It contains a unique address, a balance ```proto message Account { - bytes address - uint64 balance - bytes code - repeated AccountKey keys - map contracts + bytes address = 1; + uint64 balance = 2; + bytes code = 3; + repeated AccountKey keys = 4; + map contracts = 5; } ``` @@ -907,13 +1423,13 @@ An account key is a reference to a public key associated with a Flow account. Ac ```proto message AccountKey { - uint32 id - bytes public_key - uint32 sign_algo - uint32 hash_algo - uint32 weight - uint32 sequence_number - bool revoked + uint32 index = 1; + bytes public_key = 2; + uint32 sign_algo = 3; + uint32 hash_algo = 4; + uint32 weight = 5; + uint32 sequence_number = 6; + bool revoked = 7; } ``` @@ -935,11 +1451,11 @@ An event is emitted as the result of a [transaction](#transaction) execution. Ev ```proto message Event { - string type - bytes transaction_id - uint32 transaction_index - uint32 event_index - bytes payload + string type = 1; + bytes transaction_id = 2; + uint32 transaction_index = 3; + uint32 event_index = 4; + bytes payload = 5; } ``` @@ -957,10 +1473,10 @@ Execution result for a particular block. ```proto message ExecutionResult { - bytes previous_result_id - bytes block_id - repeated Chunk chunks - repeated ServiceEvent service_events + bytes previous_result_id = 1; + bytes block_id = 2; + repeated Chunk chunks = 3; + repeated ServiceEvent service_events = 4; } ``` @@ -971,31 +1487,57 @@ message ExecutionResult { | 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 + +```proto +message ExecutionReceiptMeta { + bytes executor_id = 1; + bytes result_id = 2; + repeated bytes spocks = 3; + bytes executor_signature = 4; +} +``` + +| 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 ```proto message Chunk { - bytes start_state - bytes event_collection - bytes block_id - uint64 total_computation_used - uint64 number_of_transactions - uint64 index - bytes end_state -} -``` - -| Field | Description | -| ---------------------- | ---------------------------------------------------- | -| 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 | + uint32 CollectionIndex = 1; + bytes start_state = 2; + bytes event_collection = 3; + bytes block_id = 4; + uint64 total_computation_used = 5; + uint32 number_of_transactions = 6; + uint64 index = 7; + bytes end_state = 8; + bytes execution_data_id = 9; + bytes state_delta_commitment = 10; +} +``` + +| 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 @@ -1003,8 +1545,8 @@ Special type of events emitted in system chunk used for controlling Flow system. ```proto message ServiceEvent { - string type; - bytes payload; + string type = 1; + bytes payload = 2; } ``` @@ -1028,18 +1570,18 @@ with no events) are returned periodically to allow clients to track which blocks which block to start from when reconnecting. ```proto - rpc SubscribeEvents(SubscribeEventsRequest) returns (stream SubscribeEventsResponse) +rpc SubscribeEvents(SubscribeEventsRequest) returns (stream SubscribeEventsResponse) ``` #### Request ```proto message SubscribeEventsRequest { - bytes start_block_id - uint64 start_block_height - EventFilter filter - uint64 heartbeat_interval - entities.EventEncodingVersion event_encoding_version + bytes start_block_id = 1; + uint64 start_block_height = 2; + EventFilter filter = 3; + uint64 heartbeat_interval = 4; + entities.EventEncodingVersion event_encoding_version = 5; } ``` @@ -1055,10 +1597,11 @@ message SubscribeEventsRequest { ```proto message SubscribeEventsResponse { - bytes block_id - uint64 block_height - repeated entities.Event events - google.protobuf.Timestamp block_timestamp + bytes block_id = 1; + uint64 block_height = 2; + repeated entities.Event events = 3; + google.protobuf.Timestamp block_timestamp = 4; + uint64 message_index = 5; } ``` @@ -1067,16 +1610,16 @@ message SubscribeEventsResponse { `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. ```proto - rpc SubscribeExecutionData(SubscribeExecutionDataRequest) returns (stream SubscribeExecutionDataResponse) +rpc SubscribeExecutionData(SubscribeExecutionDataRequest) returns (stream SubscribeExecutionDataResponse) ``` #### Request ```proto message SubscribeExecutionDataRequest { - bytes start_block_id - uint64 start_block_height - entities.EventEncodingVersion event_encoding_version + bytes start_block_id = 1; + uint64 start_block_height = 2; + entities.EventEncodingVersion event_encoding_version = 3; } ``` @@ -1090,9 +1633,9 @@ message SubscribeExecutionDataRequest { ```proto message SubscribeExecutionDataResponse { - uint64 block_height - entities.BlockExecutionData block_execution_data - google.protobuf.Timestamp block_timestamp + uint64 block_height = 1; + entities.BlockExecutionData block_execution_data = 2; + google.protobuf.Timestamp block_timestamp = 3; } ``` @@ -1105,9 +1648,9 @@ If no filters are provided, all events are returned. If there are any invalid fi ```proto message EventFilter { - repeated string event_type - repeated string contract - repeated string address + repeated string event_type = 1; + repeated string contract = 2; + repeated string address = 3; } ``` @@ -1137,16 +1680,16 @@ The `ExecutionDataAPI` provides access to block execution data over gRPC, includ 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 20*1024*1024 (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. | +| 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 20*1024*1024 (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. |