For AI agents: a documentation index is available at /llms.txt. Markdown versions of pages are available by appending .md to any documentation URL.
Skip to main content

Getters

These methods retrieve bad blocks and raw, RLP-encoded blocks, block access lists, headers, receipts, transactions, and execution witnesses.

debug_getBadBlocks​

Returns a list of invalid blocks. This is used to detect and analyze consensus flaws.

Parameters​

  • None

Returns​

  • List of block objects.

    • number: quantity, integer - Block number. null when block is pending.

    • hash: data, 32 bytes - Hash of the block. null when block is pending.

    • mixHash: data, 32 bytes - For pre-merge blocks, the hash used to verify the proof of work. For post-merge blocks, the prevRandao value supplied by the consensus layer.

    • parentHash: data, 32 bytes - Hash of the parent block.

    • nonce: data, 8 bytes - Hash of the generated proof of work. null when block is pending.

    • sha3Uncles: data, 32 bytes - SHA3 of the uncle's data in the block.

    • logsBloom: data, 256 bytes - Bloom filter for the block logs. null when block is pending.

    • transactionsRoot: data, 32 bytes - Root of the transaction trie for the block.

    • stateRoot: data, 32 bytes - Root of the final state trie for the block.

    • receiptsRoot: data, 32 bytes - Root of the receipts trie for the block.

    • miner: data, 20 bytes - Address to pay mining rewards to.

    • difficulty: quantity, integer - Difficulty for this block.

    • extraData: data - Extra data field for this block. The first 32 bytes is vanity data you can set using the --miner-extra-data command line option. Stores extra data when used with IBFT.

    • size: quantity, integer - Size of block in bytes.

    • gasLimit: quantity - Maximum gas allowed in this block.

    • gasUsed: quantity - Total gas used by all transactions in this block.

    • timestamp: quantity - Hex-encoded Unix timestamp (in seconds) for block assembly.

    • transactions: array - Array of transaction objects, or 32 byte transaction hashes depending on the specified boolean parameter.

      • accessList: array - (Optional) List of addresses and storage keys the transaction plans to access. Used in ACCESS_LIST transactions and may be used in EIP1559 transactions.

      • blockHash: data, 32 bytes - Hash of the block containing this transaction. null when transaction is pending.

      • blockNumber: quantity - Block number of the block containing this transaction. null when transaction is pending.

      • blockTimestamp: quantity - Hex-encoded Unix timestamp (in seconds) of the block containing this transaction. null when transaction is pending.

      • chainId: quantity - Chain ID.

      • from: data, 20 bytes - Address of the sender.

      • gas: quantity - Gas provided by the sender.

      • gasPrice: quantity - (Optional) Gas price, in Wei, provided by the sender. Used only in non-EIP1559 transactions.

      • maxPriorityFeePerGas: quantity, integer - (Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in EIP1559 transactions.

      • maxFeePerGas: quantity, integer - (Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in EIP1559 transactions.

      • hash: data, 32 bytes - Hash of the transaction.

      • input: data - Data sent with the transaction to create or invoke a contract.

      • nonce: quantity - Number of transactions made by the sender before this one.

      • to: data, 20 bytes - Address of the receiver. null if a contract creation transaction.

      • transactionIndex: quantity, integer - Index position of the transaction in the block. null when transaction is pending.

      • transactionType: string - Transaction type.

      • value: quantity - Value transferred, in Wei.

      • v: quantity - ECDSA Recovery ID.

      • r: data, 32 bytes - ECDSA signature r.

      • s: data, 32 bytes - ECDSA signature s.

    • uncles: array - Array of uncle hashes.

    • baseFeePerGas: quantity - The block's base fee per gas. Only present for blocks created after EIP-1559.

    • withdrawalsRoot: data, 32 bytes - Root of the withdrawals trie for the block. Only present for blocks created after EIP-4895 (Shanghai).

    • withdrawals: array - Array of validator withdrawal objects included in the block. Only present for blocks created after EIP-4895 (Shanghai).

      • index: quantity - Index of the withdrawal.

      • validatorIndex: quantity - Index of the validator that initiated the withdrawal.

      • address: data, 20 bytes - Address the withdrawal was sent to.

      • amount: quantity - Amount withdrawn, in Gwei.

    • blobGasUsed: quantity - Total blob gas used by the transactions in this block. Only present for blocks created after EIP-4844 (Cancun).

    • excessBlobGas: quantity - Running total of excess blob gas used to calculate the blob base fee for subsequent blocks. Only present for blocks created after EIP-4844 (Cancun).

    • parentBeaconBlockRoot: data, 32 bytes - Root of the parent beacon block, which exposes beacon chain state to the EVM. Only present for blocks created after EIP-4788 (Cancun).

    • requestsHash: data, 32 bytes - Hash of the general purpose execution layer requests (for example, deposits, withdrawals, and consolidations) included in the block. Only present for blocks created after EIP-7685 (Prague).

Example​

curl -X POST http://127.0.0.1:8545/ \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "debug_getBadBlocks",
"params": [],
"id": 1
}'

debug_getRawBlock​

Returns the RLP encoding of the specified block.

Parameters​

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

Returns​

  • Hex-encoded RLP of the block.
note

Returns a JSON-RPC error (Block not found) when the block does not exist.

Example​

curl -X POST http://127.0.0.1:8545/ \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "debug_getRawBlock",
"params": [
"0x32026E"
],
"id": 1
}'

debug_getRawBlockAccessList​

Returns the RLP encoding of the Ethereum Improvement Proposal 7928 (EIP-7928) block access list (BAL) for the specified block.

Use 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.

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​

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
}'

debug_getRawHeader​

Returns the RLP encoding of the header of specified block.

Parameters​

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

Returns​

  • Hex-encoded RLP of the block header.
note

Returns a JSON-RPC error (Block not found) when the block does not exist.

Example​

curl -X POST http://127.0.0.1:8545/ \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "debug_getRawHeader",
"params": [
"0x32026E"
],
"id": 1
}'

debug_getRawReceipts​

Returns the RLP encoding of the transaction receipts of the specified block.

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.

    note

    pending returns the same value as latest.

Returns​

  • Array of hex-encoded RLP transaction receipts, or null when the block is not found.

Example​

curl -X POST http://127.0.0.1:8545/ \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "debug_getRawReceipts",
"params": [
"0x32026E"
],
"id": 1
}'

debug_getRawTransaction​

Returns the RLP encoding of the specified transaction.

Parameters​

  • transaction: string - 32-byte transaction hash.

Returns​

  • Hex-encoded RLP of the transaction, or null when the transaction is not found.

Example​

curl -X POST http://127.0.0.1:8545/ \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "debug_getRawTransaction",
"params": [
"0x3a2fd1a5ea9ffee477f449be53a49398533d2c006a5815023920d1c397298df3"
],
"id": 1
}'

debug_executionWitness​

Returns the EIP-8025 execution witness for an imported block.

Besu rebuilds the witness by re-executing the block against its parent state. The witness contains the trie nodes, contract bytecodes, and ancestor headers needed to re-execute the block without the full state.

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.

    note

    pending returns the same value as latest.

Returns​

  • Object with the following fields:

    • state: array of data - RLP-encoded account and storage trie nodes for the block, sorted.

    • codes: array of data - Pre-state contract bytecodes for accounts the EIP-7928 block access list reports as touched, sorted. Empty code is omitted. Besu includes the bytecode of every touched account that had code before the block, including accounts the block did not call. A balance read or an access-list entry is enough to touch an account.

    • headers: array of data - RLP-encoded ancestor block headers, in ascending block number order. The list ends at the parent of the requested block. It does not include that block's header.

note

This method returns:

  • null when the block does not exist.
  • A JSON-RPC error (Block not found) for the genesis block (earliest or block 0), which has no parent state to re-execute against.
  • A JSON-RPC error (Internal error) when your node is not using Bonsai Tries, the block's trie log has been pruned, or re-execution fails. See Reduce storage for Bonsai Tries for how trie log pruning works.

Example​

curl -X POST http://127.0.0.1:8545/ \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "debug_executionWitness",
"params": [
"latest"
],
"id": 1
}'