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

State and node methods

These methods inspect account and world state, and manage node operations such as metrics, resyncing, and replaying blocks.

debug_accountAt​

Returns account information at the specified index of the specified block.

Parameters​

  • blockHashOrNumber: string - Block hash or number at which to retrieve account information.

  • txIndex: number - Transaction index at which to retrieve account information.

  • address: string - Contract or account address for which to retrieve information.

Returns​

  • Account details object.

    • code: data - Code for the account. Displays 0x0 if the address is an externally owned account.

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

    • balance: quantity - Balance of the account in wei.

    • codehash: data - Code hash for the account.

Example​

This example uses an externally owned account address for the address parameter.

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

This example uses a contract address for the address parameter.

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

debug_accountRange​

Retesteth uses debug_accountRange to implement debugging.

Returns the accounts for a specified block.

Parameters​

  • blockHashOrNumber: string - Block hash or number at which to retrieve account information.

  • txIndex: number - Transaction index at which to retrieve account information.

  • address: string - Address hash from which to start.

  • limit: integer - Maximum number of account entries to return.

Returns​

  • Account details object.

    • addressMap: map of strings to strings - Map of address hashes and account addresses.

    • nextKey: string - Hash of the next address if any addresses remain in the state, otherwise zero.

Example​

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

debug_batchSendRawTransaction​

Sends a list of signed transactions. This is used to quickly load a network with a lot of transactions. This does the same thing as calling eth_sendRawTransaction multiple times.

Parameters​

  • data: string - Signed transaction data array.

Returns​

  • Object returned for each transaction.

    • index: string - Index of the transaction in the request parameters array.

    • success: boolean - Indicates whether or not the transaction has been added to the transaction pool.

    • errorMessage: string - (Optional) Error message.

Example​

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

debug_metrics​

Returns metrics providing information on the internal operation of Besu.

The available metrics might change over time. The JVM metrics might vary based on the JVM implementation used.

The metric types are:

  • Timer
  • Counter
  • Gauge

Parameters​

  • None

Returns​

  • Metrics object.

Example​

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

debug_replayBlock​

Re-imports the block matching the specified block number, by rolling the head of the local chain back to the block right before the specified block, then importing 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​

  • Success or error.

Example​

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

debug_resyncWorldState​

Triggers a re-synchronization of the world state while retaining imported blocks. This is useful if there are world state database inconsistencies (for example, Bonsai database issues).

Parameters​

  • None

Returns​

  • Success or error.

Example​

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

debug_setHead​

Sets the local chain head to the specified block. Optionally, moves the bonsai world state to that block when the shouldMoveWorldstate parameter is set to true.

Moving the world state allows expensive operations like debug_traceBlock to run on historical blocks without replaying all intermediate states. This is helpful to avoid out of memory errors when executing RPC calls on historical states.

warning

Do not use this method when a consensus client is directing Besu, or while the node is actively importing or proposing blocks as this will likely corrupt the database.

Additionally, if you move the chain head by a large number of blocks (for example, more than 5,000), the RPC call might time out even though Besu continues the operation in the background.

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.

  • shouldMoveWorldstate: boolean - (Optional) If true, moves the bonsai world state to the specified block. The default is false.

Returns​

  • Success or error.

Example​

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

debug_storageRangeAt​

Remix uses debug_storageRangeAt to implement debugging. Use the Debugger tab in Remix instead of calling debug_storageRangeAt directly.

Returns the contract storage for the specified range.

Parameters​

  • blockHash: string - Block hash.

  • txIndex: number - Transaction index from which to start.

  • address: string - Contract address.

  • startKey: string - Start key.

  • limit: number - Number of storage entries to return.

Returns​

  • Range object.

    • storage: object - Key hash and value. Pre-image key is null if it falls outside the cache.

    • nextKey: hash - Hash of next key if further storage in range. Otherwise, not included.

Example​

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