diff --git a/docs/public-networks/how-to/use-besu-api/json-rpc.md b/docs/public-networks/how-to/use-besu-api/json-rpc.md index 9790e8151e1..efc700a1353 100644 --- a/docs/public-networks/how-to/use-besu-api/json-rpc.md +++ b/docs/public-networks/how-to/use-besu-api/json-rpc.md @@ -263,15 +263,31 @@ parameter specifies the block. Methods such as [`eth_getTransactionByBlockNumberAndIndex`](../../reference/api/index.md#eth_gettransactionbyblocknumberandindex) have a block parameter. -The block parameter can have the following values: +The block parameter can have one of the following values: -* `blockNumber` : `quantity` - The block number, specified in hexadecimal or decimal. 0 represents +* `blockNumber` : *quantity* - The block number, specified in hexadecimal or decimal. 0 represents the genesis block. -* `earliest` : `tag` - The earliest (genesis) block. -* `latest` : `tag` - The last block mined. -* `pending` : `tag` - The last block mined plus pending transactions. Use only with +* `blockHash` : *string* or *object* - 32-byte block hash or JSON object specifying the block hash. + If using a JSON object, you can specify `requireCanonical` to indicate whether the block must be a + canonical block. + See [this example](https://github.com/hyperledger/besu/blob/a2dedb0b2c7980cdc35db8eb4c094f2eb0dc7deb/ethereum/api/src/test/resources/org/hyperledger/besu/ethereum/api/jsonrpc/eth/eth_getBalance_blockHashObjectCanonical.json). + + !!! note + + Only the following methods support the `blockHash` parameter: + + * [`eth_call`](../../reference/api/index.md#eth_call) + * [`eth_getBalance`](../../reference/api/index.md#eth_getbalance) + * [`eth_getCode`](../../reference/api/index.md#eth_getcode) + * [`eth_getProof`](../../reference/api/index.md#eth_getproof) + * [`eth_getStorageAt`](../../reference/api/index.md#eth_getstorageat) + * [`eth_getTransactionCount`](../../reference/api/index.md#eth_gettransactioncount) + +* `earliest` : *tag* - The earliest (genesis) block. +* `latest` : *tag* - The last block mined. +* `pending` : *tag* - The last block mined plus pending transactions. Use only with [`eth_getTransactionCount`](../../reference/api/index.md#eth_gettransactioncount). -* `finalized` : `tag` - The most recent crypto-economically secure block. +* `finalized` : *tag* - The most recent crypto-economically secure block. It cannot be reorganized outside manual intervention driven by community coordination. -* `safe` : `tag` - The most recent block that is safe from reorganization under +* `safe` : *tag* - The most recent block that is safe from reorganization under honest majority and certain synchronicity assumptions. diff --git a/docs/public-networks/reference/api/index.md b/docs/public-networks/reference/api/index.md index 8b26339d8a9..fe15d4e74ba 100644 --- a/docs/public-networks/reference/api/index.md +++ b/docs/public-networks/reference/api/index.md @@ -212,11 +212,11 @@ Removes cache files for the specified range of blocks. * `fromBlock`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) * `toBlock`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) You can skip a parameter by using an empty string, `""`. If you specify: @@ -994,7 +994,7 @@ back to the block right before the specified block, then importing the specified `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -1032,7 +1032,7 @@ Sets the current head of the local chain to the block matching the specified blo `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -1401,7 +1401,7 @@ Returns full trace of all invoked opcodes of all transactions included in the bl * `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) * `options`: *object* - request options object with the following fields (all optional and default to `false`): @@ -1591,9 +1591,9 @@ the `eth_call` error response includes the [revert reason](../../../private-netw `call`: *object* - [transaction call object](objects.md#transaction-call-object) -`blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, -`earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +`blockNumber` or `blockHash`: *string* - integer representing a block number, block hash, or one of +the string tags `latest`, `earliest`, or `pending`, as described in +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) !!! note @@ -1893,7 +1893,7 @@ If blocks in the specified block range are not available, then only the fee hist * `newestBlock`: *string* - Integer representing the highest number block of the requested range or one of the string tags `latest`, `earliest`, or `pending`, as described in - [Block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). + [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). #### Returns @@ -2006,9 +2006,9 @@ Returns the account balance of the specified address. * `address`: *string* - 20-byte account address from which to retrieve the balance -* `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, -`earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +* `blockNumber` or `blockHash`: *string* - integer representing a block number, block hash, or one +of the string tags `latest`, `earliest`, or `pending`, as described in +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -2201,7 +2201,7 @@ Returns information about the block matching the specified block number. * `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, `pending`, `finalized`, or `safe` as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) * `verbose`: *boolean* - if `true`, returns the full [transaction objects](objects.md#transaction-object); if `false`, returns only the hashes of the transactions. @@ -2419,7 +2419,7 @@ Returns the number of transactions in a block matching the specified block numbe `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -2487,9 +2487,9 @@ Besu stores compiled smart contract code as a hexadecimal value. `address`: *string* - 20-byte contract address -`blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, -`earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +`blockNumber` or `blockHash`: *string* - integer representing a block number, block hash, or one of +the string tags `latest`, `earliest`, or `pending`, as described in +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -2899,7 +2899,7 @@ Returns miner data for the specified block. `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -2957,9 +2957,9 @@ from untrusted sources, by using a trusted block hash. `keys`: *array* of *strings* - list of 32-byte storage keys to generate proofs for -`blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, -`earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +`blockNumber` or `blockHash`: *string* - integer representing a block number, block hash, or one of +the string tags `latest`, `earliest`, or `pending`, as described in +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -3042,9 +3042,9 @@ Returns the value of a storage position at a specified address. `index`: *string* - integer index of the storage position -`blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, -`earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +`blockNumber` or `blockHash`: *string* - integer representing a block number, block hash, or one of +the string tags `latest`, `earliest`, or `pending`, as described in +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -3205,7 +3205,7 @@ Returns transaction information for the specified block number and transaction i `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) `index`: *string* - transaction index position @@ -3414,9 +3414,9 @@ next account nonce not used by any pending transactions. `address`: *string* - 20-byte account address -`blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, -`earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +`blockNumber` or `blockHash`: *string* - integer representing a block number, block hash, or one of +the string tags `latest`, `earliest`, or `pending`, as described in +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -3720,7 +3720,7 @@ Returns uncle specified by block number and index. * `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) * `uncleIndex`: *string* - index of the uncle @@ -3891,7 +3891,7 @@ Returns the number of uncles in a block matching the specified block number. `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -5011,7 +5011,7 @@ Provides transaction processing of [type `trace`](../trace-types.md#trace) for t `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -5114,7 +5114,7 @@ Executes the given call and returns a number of possible traces for it. * `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) * `options`: *array* of *strings* - list of tracing options; tracing options are [`trace`, `vmTrace`, and `stateDiff`](../trace-types.md). Specify any @@ -5188,7 +5188,7 @@ Performs multiple call traces on top of the same block. You can trace dependent * `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in - [Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) + [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) #### Returns @@ -5493,7 +5493,7 @@ Provides transaction processing tracing per block. * `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in -[Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) +[block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter) * `options`: *array* of *strings* - list of tracing options; tracing options are [`trace`, `vmTrace`, and `stateDiff`](../trace-types.md). Specify any diff --git a/docs/public-networks/reference/api/objects.md b/docs/public-networks/reference/api/objects.md index 1ce418fbc40..8394fc58058 100644 --- a/docs/public-networks/reference/api/objects.md +++ b/docs/public-networks/reference/api/objects.md @@ -61,8 +61,8 @@ Used to [`filter logs`](../../how-to/use-besu-api/access-logs.md). | Key | Type | Required/Optional | Value | |-----|:----:|:-----------------:|-------| -| `fromBlock` | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). Default is `latest`. | -| `toBlock` | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). Default is `latest`. | +| `fromBlock` | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). Default is `latest`. | +| `toBlock` | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [block parameter](../../how-to/use-besu-api/json-rpc.md#block-parameter). Default is `latest`. | | `address` | Data | Array | Optional | Contract address or array of addresses from which [logs](../../concepts/events-and-logs.md) originate. | | `topics` | Array of Data, 32 bytes each | Optional | Array of topics by which to [filter logs](../../concepts/events-and-logs.md#topic-filters). |