diff --git a/docs/public-networks/reference/api/debug/getters.md b/docs/public-networks/reference/api/debug/getters.md index 81d37af33c..24b772833e 100644 --- a/docs/public-networks/reference/api/debug/getters.md +++ b/docs/public-networks/reference/api/debug/getters.md @@ -9,7 +9,8 @@ toc_max_heading_level: 2 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -These methods retrieve bad blocks and raw, RLP-encoded blocks, headers, receipts, and transactions. +These methods retrieve bad blocks and raw, RLP-encoded blocks, block access lists, headers, +receipts, and transactions. ## `debug_getBadBlocks` @@ -456,6 +457,84 @@ curl -X POST http://127.0.0.1:8545/ \ --- +## `debug_getRawBlockAccessList` + +Returns the [RLP encoding](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) +of the +[Ethereum Improvement Proposal 7928 (EIP-7928)](https://eips.ethereum.org/EIPS/eip-7928) +block access list (BAL) for the specified block. + +Use [`eth_getBlockAccessList`](../eth/block.md#eth_getblockaccesslist) for the decoded JSON +representation. + +### Parameters + +- `blockNumber` or `blockHash`: _string_ - Hexadecimal integer representing a block number, + 32-byte block hash, 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). + +### Returns + +- Hex-encoded RLP block access list, or `null` when the block parameter is `pending`. + +:::note +Returns a JSON-RPC error (`Resource not found`) when the block is not found or doesn't include +an EIP-7928 BAL, and (`Pruned history unavailable`) when the BAL is missing from local storage. +::: + +### Example + + + + + +```bash +curl -X POST http://127.0.0.1:8545/ \ + -H "Content-Type: application/json" \ + --data '{ + "jsonrpc": "2.0", + "method": "debug_getRawBlockAccessList", + "params": [ + "0x1" + ], + "id": 1 + }' +``` + + + + + +```json +{ + "jsonrpc": "2.0", + "method": "debug_getRawBlockAccessList", + "params": [ + "0x1" + ], + "id": 1 +} +``` + + + + + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": "0xf8e2de9400000961ef480eb55e80d19ad83579a64c007002c0c480010203c0c0c0de94000014574a74c805590aff9499fc7a690f008282c0c480010203c0c0c0de940000884d2aa32eaa155f59a2f24efa73d9008282c0c480010203c0c0c0de940000bbddc7ce488642fb579f8b00f3a590007251c0c480010203c0c0c0f840940000f90827f1c53a10cb7a02335b175320002935e6e580e3e280a0e4e54508f0865fe3ebc1b5ac710c1fd696b2a2ce797d4111120e0378c0b1cd81c0c0c0c0e394000f3df6d732807ef1319fb7b8bb8522d0beac02c6c501c3c28001c3822000c0c0c0" +} +``` + + + + + +--- + ## `debug_getRawHeader` Returns the [RLP encoding](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/) of the header of specified block. diff --git a/docs/public-networks/reference/api/debug/index.md b/docs/public-networks/reference/api/debug/index.md index 63e4bc7bf9..9c9b117382 100644 --- a/docs/public-networks/reference/api/debug/index.md +++ b/docs/public-networks/reference/api/debug/index.md @@ -50,6 +50,7 @@ Retrieve block and transaction information. - `debug_getBadBlocks` - `debug_getRawBlock` +- `debug_getRawBlockAccessList` - `debug_getRawHeader` - `debug_getRawReceipts` - `debug_getRawTransaction` diff --git a/docs/public-networks/reference/api/eth/block.md b/docs/public-networks/reference/api/eth/block.md index 0da22225ad..dd3aac1459 100644 --- a/docs/public-networks/reference/api/eth/block.md +++ b/docs/public-networks/reference/api/eth/block.md @@ -9,7 +9,181 @@ toc_max_heading_level: 2 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -These methods query blocks and their contents, including block details, transaction counts, receipts, and uncles. +These methods query blocks and their contents, including block details, block access lists, +transaction counts, receipts, and uncles. + +## `eth_getBlockAccessList` + +Returns the +[Ethereum Improvement Proposal 7928 (EIP-7928)](https://eips.ethereum.org/EIPS/eip-7928) +block access list (BAL) for the specified block. +The BAL records the accounts and storage locations accessed during block execution, along with +post-execution values. + +Returns data only for blocks that include an EIP-7928 BAL. + +### Parameters + +- `blockNumber` or `blockHash`: _string_ - Hexadecimal integer representing a block number, + 32-byte block hash, 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). + + :::note + `pending` returns `null`. + ::: + +### Returns + +- Array of account change objects for the block access list, or `null` when the block is not + found. + + + + - `address`: _data, 20 bytes_ - Account address. + + - `storageChanges`: _array_ - Storage slots written during block execution. + + + + - `key`: _data, 32 bytes_ - Storage slot key. + + - `changes`: _array_ - Post-execution storage values for the slot. + + + + - `index`: _quantity_ - Block access index for the change. + `0` is pre-execution, `1` through `n` are transactions, and `n+1` is post-execution. + + - `value`: _data, 32 bytes_ - Post-execution storage value. + + + + + + - `storageReads`: _array of data, 32 bytes_ - Storage slot keys read during block execution + without a corresponding write. + + - `balanceChanges`: _array_ - Post-execution balance updates for the account. + + + + - `index`: _quantity_ - Block access index for the change. + + - `value`: _quantity_ - Post-execution balance, in Wei. + + + + - `nonceChanges`: _array_ - Post-execution nonce updates for the account. + + + + - `index`: _quantity_ - Block access index for the change. + + - `value`: _quantity_ - Post-execution nonce. + + + + - `codeChanges`: _array_ - Post-execution code updates for the account. + + + + - `index`: _quantity_ - Block access index for the change. + + - `code`: _data_ - Post-execution contract bytecode. + + + + + +:::note +Returns a JSON-RPC error (`Resource not found`) for blocks that don't include an EIP-7928 BAL, +and (`Pruned history unavailable`) when the BAL is missing from local storage. +::: + +### Example + + + + + +```bash +curl -X POST http://127.0.0.1:8545/ \ + -H "Content-Type: application/json" \ + --data '{ + "jsonrpc": "2.0", + "method": "eth_getBlockAccessList", + "params": [ + "0x1" + ], + "id": 1 + }' +``` + + + + + +```json +{ + "jsonrpc": "2.0", + "method": "eth_getBlockAccessList", + "params": [ + "0x1" + ], + "id": 1 +} +``` + + + + + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "address": "0x00000961ef480eb55e80d19ad83579a64c007002", + "storageChanges": [], + "storageReads": [ + "0x0000000000000000000000000000000000000000000000000000000000000000", + "0x0000000000000000000000000000000000000000000000000000000000000001", + "0x0000000000000000000000000000000000000000000000000000000000000002", + "0x0000000000000000000000000000000000000000000000000000000000000003" + ], + "balanceChanges": [], + "nonceChanges": [], + "codeChanges": [] + }, + { + "address": "0x0000f90827f1c53a10cb7a02335b175320002935", + "storageChanges": [ + { + "key": "0x0000000000000000000000000000000000000000000000000000000000000000", + "changes": [ + { + "index": "0x0", + "value": "0xe4e54508f0865fe3ebc1b5ac710c1fd696b2a2ce797d4111120e0378c0b1cd81" + } + ] + } + ], + "storageReads": [], + "balanceChanges": [], + "nonceChanges": [], + "codeChanges": [] + } + ] +} +``` + + + + + +--- ## `eth_getBlockByHash` diff --git a/docs/public-networks/reference/api/eth/index.md b/docs/public-networks/reference/api/eth/index.md index 4d26a83ba7..7843588fed 100644 --- a/docs/public-networks/reference/api/eth/index.md +++ b/docs/public-networks/reference/api/eth/index.md @@ -46,6 +46,7 @@ Query client and network information. Query blocks and their contents. +- `eth_getBlockAccessList` - `eth_getBlockByHash` - `eth_getBlockByNumber` - `eth_getBlockReceipts`