From 42e41a937094ca020f42531bbb94a3ef61df7c91 Mon Sep 17 00:00:00 2001 From: Gigi Date: Sat, 20 Dec 2025 09:03:06 +0100 Subject: [PATCH] docs: add reth JSON-RPC namespace documentation (#20522) --- docs/vocs/docs/pages/jsonrpc/intro.mdx | 2 +- docs/vocs/docs/pages/jsonrpc/reth.mdx | 89 ++++++++++++++++++++++++++ 2 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 docs/vocs/docs/pages/jsonrpc/reth.mdx diff --git a/docs/vocs/docs/pages/jsonrpc/intro.mdx b/docs/vocs/docs/pages/jsonrpc/intro.mdx index 703809f5c9..89a9fa7ef5 100644 --- a/docs/vocs/docs/pages/jsonrpc/intro.mdx +++ b/docs/vocs/docs/pages/jsonrpc/intro.mdx @@ -26,7 +26,7 @@ The methods are grouped into namespaces, which are listed below: | [`trace`](/jsonrpc/trace) | The `trace` API provides several methods to inspect the Ethereum state, including Parity-style traces. | No | | [`admin`](/jsonrpc/admin) | The `admin` API allows you to configure your node. | **Yes** | | [`rpc`](/jsonrpc/rpc) | The `rpc` API provides information about the RPC server and its modules. | No | -| `reth` | The `reth` API provides reth-specific methods like balance changes and chain notifications. | No | +| [`reth`](/jsonrpc/reth) | The `reth` API provides reth-specific methods like balance changes and chain notifications. | No | | `ots` | The `ots` API provides Otterscan-compatible methods for block exploration. | No | | `flashbots` | The `flashbots` API provides block submission validation methods for builders. | No | | `miner` | The `miner` API allows you to configure miner/builder settings like extra data and gas limits. | **Yes** | diff --git a/docs/vocs/docs/pages/jsonrpc/reth.mdx b/docs/vocs/docs/pages/jsonrpc/reth.mdx new file mode 100644 index 0000000000..4a7f7d48f5 --- /dev/null +++ b/docs/vocs/docs/pages/jsonrpc/reth.mdx @@ -0,0 +1,89 @@ +--- +description: Reth-specific API for balance changes and chain notifications. +--- + +# `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. + +| Client | Method invocation | +| ------ | -------------------------------------------------------------- | +| RPC | `{"method": "reth_getBalanceChangesInBlock", "params": [block]}` | + +### Example + +```js +// > {"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_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. + +| Client | Method invocation | +| ------ | -------------------------------------------------------------------------- | +| RPC | `{"method": "reth_subscribeChainNotifications", "params": []}` | +| RPC | `{"method": "reth_unsubscribeChainNotifications", "params": [subscription_id]}` | + +### Event Types + +The subscription emits events with the following structure: + +```json +{ + "jsonrpc": "2.0", + "method": "reth_subscription", + "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 + +```js +// > {"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 +{"jsonrpc":"2.0","method":"reth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"Commit":{"new":{"blocks":[...],"receipts":[...],"first_block":1000,"last_block":1000}}}}} + +// Unsubscribe +// > {"jsonrpc":"2.0","id":2,"method":"reth_unsubscribeChainNotifications","params":["0xcd0c3e8af590364c09d0fa6a1210faf5"]} +{"jsonrpc":"2.0","id":2,"result":true} +``` + +:::note +This subscription is only available over WebSocket and IPC transports, as HTTP does not support server-initiated messages. +:::