github/reth
1
1
Fork 0
mirror of https://github.com/paradigmxyz/reth.git synced 2026-01-08 23:08:19 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs: add reth JSON-RPC namespace documentation (#20522)

Browse Source
This commit is contained in:
Gigi
2025-12-20 09:03:06 +01:00
committed by GitHub
parent a66dcce834
commit 42e41a9370
2 changed files with 90 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/vocs/docs/pages/jsonrpc/intro.mdx
View File

@@ -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** |

89
docs/vocs/docs/pages/jsonrpc/reth.mdx Normal file
View File

@@ -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.
:::