reth Namespace

The reth API provides reth-specific methods that are not part of the standard Ethereum JSON-RPC specification. These methods offer additional functionality for monitoring balance changes and subscribing to chain state notifications.

reth_getBalanceChangesInBlock

Returns all ETH balance changes that occurred in a specific block.

This method is useful for tracking value transfers, mining rewards, and other balance modifications without having to trace every transaction in a block.

The method accepts a block identifier (number, hash, or tag like latest) and returns a map of addresses to their new balances.

Example

// > {"jsonrpc":"2.0","id":1,"method":"reth_getBalanceChangesInBlock","params":["latest"]}
{"jsonrpc":"2.0","id":1,"result":{"0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5":"0x1bc16d674ec80000","0x388c818ca8b9251b393131c08a736a67ccb19297":"0x0"}}

The result is a mapping of addresses to their new balance after the block was executed. Only addresses whose balance changed during block execution are included.

reth_getBlockExecutionOutcome

Re-executes a block and returns its execution outcome: the bundle of state changes, the receipts and the EIP-7685 requests.

If count is provided, up to count consecutive available blocks starting at the given block are re-executed and the merged execution outcome is returned. count must be between 1 and 128.

Returns null if the block is unknown. The genesis block yields an empty outcome because it has no parent state to execute against.

Example

// > {"jsonrpc":"2.0","id":1,"method":"reth_getBlockExecutionOutcome","params":["latest"]}
{"jsonrpc":"2.0","id":1,"result":{"bundle":{"state":{"0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5":{"info":{"balance":"0x1bc16d674ec80000","nonce":0,"code_hash":"0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470","code":null},"original_info":{"balance":"0x0","nonce":0,"code_hash":"0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470","code":null},"storage":{},"status":"Changed"}},"contracts":{},"reverts":[[["0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5",{"account":{"RevertTo":{"balance":"0x0","nonce":0,"code_hash":"0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470","code":null}},"storage":{},"previous_status":"Loaded","wipe_storage":false}]]],"state_size":1,"reverts_size":1},"receipts":[[]],"first_block":21000000,"requests":[[]]}}

The result contains the bundle of account and storage changes (including the reverts required to undo them), one list of receipts per executed block, the number of the first_block of the executed range and the requests (EIP-7685) of each block.

reth_jit

Controls the JIT compilation backend of the EVM, if the node was built with one. The method is a no-op when no JIT backend is configured.

The action is one of enable, disable, pause, unpause or clear. The clear action clears resident and persisted JIT artifacts.

Example

// > {"jsonrpc":"2.0","id":1,"method":"reth_jit","params":["pause"]}
{"jsonrpc":"2.0","id":1,"result":null}

reth_subscribeChainNotifications, reth_unsubscribeChainNotifications

Subscribe to canonical chain state notifications. This creates a subscription that emits notifications whenever the canonical chain state changes.

Like other subscription methods, this returns the ID of the subscription, which is then used in all events subsequently.

To unsubscribe from chain notifications, call reth_unsubscribeChainNotifications with the subscription ID.

Event Types

The subscription emits events with the following structure:

{
    "jsonrpc": "2.0",
    "method": "reth_subscribeChainNotifications",
    "params": {
        "subscription": "0xcd0c3e8af590364c09d0fa6a1210faf5",
        "result": {
            "Commit": { // or "Reorg"
                "new": {
                    // Chain segment with blocks, receipts, etc.
                },
                "old": {
                    // Only present for "Reorg": chain segment that was reverted
                }
            }
        }
    }
}

• Commit: New blocks are added to the canonical chain. Contains only new with the committed chain segment.
• Reorg: Chain reorganization occurred. Contains both old (reverted blocks) and new (replacement blocks).

This is particularly useful for applications that need to react immediately to chain state changes, such as indexers, monitoring tools, or ExEx (Execution Extensions).

Example

// > {"jsonrpc":"2.0","id":1,"method":"reth_subscribeChainNotifications","params":[]}
// responds with subscription ID
{"jsonrpc":"2.0","id":1,"result":"0xcd0c3e8af590364c09d0fa6a1210faf5"}
 
// Example notification when new blocks are committed (nested values abbreviated)
{"jsonrpc":"2.0","method":"reth_subscribeChainNotifications","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"Commit":{"new":{"blocks":{"1000":...},"execution_outcome":{"bundle":...,"receipts":[...],"first_block":1000,"requests":[...]},"trie_data":{}}}}}}
 
// Unsubscribe
// > {"jsonrpc":"2.0","id":2,"method":"reth_unsubscribeChainNotifications","params":["0xcd0c3e8af590364c09d0fa6a1210faf5"]}
{"jsonrpc":"2.0","id":2,"result":true}

reth_subscribePersistedBlock, reth_unsubscribePersistedBlock

Subscribe to persisted block notifications. This creates a subscription that emits a notification with the block number and hash when a new block is persisted to disk.

Like other subscription methods, this returns the ID of the subscription, which is then used in all events subsequently.

To unsubscribe from persisted block notifications, call reth_unsubscribePersistedBlock with the subscription ID.

Example

// > {"jsonrpc":"2.0","id":1,"method":"reth_subscribePersistedBlock","params":[]}
// responds with subscription ID
{"jsonrpc":"2.0","id":1,"result":"0xab1c2d3e4f590364c09d0fa6a1210faf5"}
 
// Example notification when a block is persisted
{"jsonrpc":"2.0","method":"reth_subscribePersistedBlock","params":{"subscription":"0xab1c2d3e4f590364c09d0fa6a1210faf5","result":{"number":"0x1a2b3c","hash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"}}}
 
// Unsubscribe
// > {"jsonrpc":"2.0","id":2,"method":"reth_unsubscribePersistedBlock","params":["0xab1c2d3e4f590364c09d0fa6a1210faf5"]}
{"jsonrpc":"2.0","id":2,"result":true}

reth_subscribeFinalizedChainNotifications, reth_unsubscribeFinalizedChainNotifications

Subscribe to finalized chain notifications. Committed chain notifications are buffered and emitted once a new finalized block is received; each notification contains a list of buffered chain segments whose last block is at or below the finalized block. Each segment uses the same format as reth_subscribeChainNotifications. Segments that extend beyond the finalized block remain buffered until their last block is finalized.

Blocks that were reverted by a reorg before they were finalized are dropped from the buffer, so subscribers only ever see the finalized chain.

Like other subscription methods, this returns the ID of the subscription, which is then used in all events subsequently.

To unsubscribe from finalized chain notifications, call reth_unsubscribeFinalizedChainNotifications with the subscription ID.

Example

// > {"jsonrpc":"2.0","id":1,"method":"reth_subscribeFinalizedChainNotifications","params":[]}
// responds with subscription ID
{"jsonrpc":"2.0","id":1,"result":"0xcd2e3f4a5b6c7d8e9f0a1b2c3d4e5f60"}
 
// Example notification once a new finalized block is known (nested values abbreviated)
{"jsonrpc":"2.0","method":"reth_subscribeFinalizedChainNotifications","params":{"subscription":"0xcd2e3f4a5b6c7d8e9f0a1b2c3d4e5f60","result":[{"Commit":{"new":{"blocks":{"1000":...,"1001":...,"1002":...},"execution_outcome":{"bundle":...,"receipts":[...],"first_block":1000,"requests":[...]},"trie_data":{}}}}]}}
 
// Unsubscribe
// > {"jsonrpc":"2.0","id":2,"method":"reth_unsubscribeFinalizedChainNotifications","params":["0xcd2e3f4a5b6c7d8e9f0a1b2c3d4e5f60"]}
{"jsonrpc":"2.0","id":2,"result":true}