From 2047cd81f31e37bc15eac910e97843ad7379919f Mon Sep 17 00:00:00 2001 From: roethke Date: Tue, 3 Mar 2026 08:34:05 -0800 Subject: [PATCH 1/4] update api reference for base/base v0.5.0 --- docs/base-chain/flashblocks/api-reference.mdx | 19 ++- docs/base-chain/reference/json-rpc-api.mdx | 132 ++++++++++++++++++ 2 files changed, 148 insertions(+), 3 deletions(-) diff --git a/docs/base-chain/flashblocks/api-reference.mdx b/docs/base-chain/flashblocks/api-reference.mdx index 2ff1577f7..13720e384 100644 --- a/docs/base-chain/flashblocks/api-reference.mdx +++ b/docs/base-chain/flashblocks/api-reference.mdx @@ -45,7 +45,12 @@ When called with `"pending"`, returns the current Flashblock — the block activ #### Returns - A block object reflecting the current preconfirmed state. See [eth_getBlockByNumber](/base-chain/reference/json-rpc-api#eth_getblockbynumber) for full field descriptions. + A block object reflecting the current preconfirmed state. See [eth_getBlockByNumber](/base-chain/reference/json-rpc-api#eth_getblockbynumber) for full field descriptions. Flashblocks-specific fields: + + - `withdrawals` — Always `[]` for Base (no L2 withdrawals in pending blocks). + - `parentBeaconBlockRoot` — Beacon block root passed from the builder; present on all pending blocks. + - `requestsHash` — Always the empty requests hash (`0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`). + - `blobGasUsed` — Accurately reflects blob gas consumed by preconfirmed transactions (not zero-padded). @@ -63,7 +68,12 @@ curl https://sepolia-preconf.base.org \ "result": { "number": "0x1234", "hash": "0x...", - "transactions": [...] + "parentHash": "0x...", + "parentBeaconBlockRoot": "0xa4b2c8e1f3d5b7a9c2e4f6d8b0a2c4e6f8d0b2a4c6e8f0d2b4a6c8e0f2d4b6a8", + "withdrawals": [], + "requestsHash": "0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", + "blobGasUsed": "0x0", + "transactions": ["0x..."] } } ``` @@ -85,6 +95,8 @@ Returns the receipt for a preconfirmed transaction before it is included in a fi A transaction receipt object for the preconfirmed transaction, or `null` if not found. See [eth_getTransactionReceipt](/base-chain/reference/json-rpc-api#eth_gettransactionreceipt) for full field descriptions. + + - `blobGasUsed` — Accurately reflects blob gas used by the transaction. Previously returned `0x0` for all preconfirmed transactions; now correctly propagated from the Flashblock. @@ -102,7 +114,8 @@ curl https://sepolia-preconf.base.org \ "result": { "transactionHash": "0x...", "blockNumber": "0x1234", - "status": "0x1" + "status": "0x1", + "blobGasUsed": "0x0" } } ``` diff --git a/docs/base-chain/reference/json-rpc-api.mdx b/docs/base-chain/reference/json-rpc-api.mdx index 99074ede9..6126c66d1 100644 --- a/docs/base-chain/reference/json-rpc-api.mdx +++ b/docs/base-chain/reference/json-rpc-api.mdx @@ -1834,6 +1834,138 @@ Replays all transactions in a block identified by its number and returns an exec ``` +## Rollup Node Methods + +These methods are specific to the OP Stack consensus layer (op-node). They are served by the rollup node on a separate RPC port (typically port `9545`) rather than the execution engine's standard port. Node operators and infrastructure providers use these methods to query rollup-specific state. + + +These methods are not available on public execution RPC endpoints like `https://mainnet.base.org`. They require direct access to a Base node's rollup (op-node) API port. + + +### optimism_syncStatus + +Returns the current synchronization status of the rollup node, including detailed L1 and L2 block references. Use this to understand the node's view of the canonical chain, safe head, and finalized head. + +**Parameters** + +This method takes no parameters. + +**Returns** + + + The rollup sync status object. + + + + The L1 block the sequencer is currently processing. + + + The latest finalized L1 block known to the node. + + + The latest L1 block the node is aware of. + + + The latest safe L1 block. + + + The latest finalized L1 block. + + + The latest unsafe (preconfirmed) L2 block. Contains `hash`, `number`, `parentHash`, `timestamp`, `l1origin` (hash + number), and `sequenceNumber`. + + + The latest safe L2 block — derived from finalized L1 data. + + + The latest finalized L2 block. + + + The pending safe L2 block (ahead of `safe_l2` but not yet finalized). + + + The queued unsafe L2 block (sequencer tip when ahead of L1 processing). + + + + + +```json Request +{ + "jsonrpc": "2.0", + "method": "optimism_syncStatus", + "params": [], + "id": 1 +} +``` + +```json Response +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "current_l1": { + "hash": "0xff3b3253058411b727ac662f4c9ae1698918179e02ecebd304beb1a1ae8fc4fd", + "number": 4427350, + "parentHash": "0xb26586390c3f04678706dde13abfb5c6e6bb545e59c22774e651db224b16cd48", + "timestamp": 1696478784 + }, + "head_l1": { + "hash": "0x6110a8e6ed4c4aaab20477a3eac81bf99e505bf6370cd4d2e3c6d34aa5f4059a", + "number": 4706863, + "parentHash": "0xee8a9cba5d93481f11145c24890fd8f536384f3c3c043f40006650538fbdcb56", + "timestamp": 1700161272 + }, + "safe_l1": { + "hash": "0x8407c9968ce278ab435eeaced18ba8f2f94670ad9d3bdd170560932cf46e2804", + "number": 4706811, + "parentHash": "0x6593cccab3e772776418ff691f6e4e75597af18505373522480fdd97219c06ef", + "timestamp": 1700160480 + }, + "finalized_l1": { + "hash": "0x7157f91b8ae21ef869c604e5b268e392de5aa69a9f44466b9b0f838d56426541", + "number": 4706784, + "parentHash": "0x1ac2612a500b9facd650950b8755d97cf2470818da2d88552dea7cd563e86a17", + "timestamp": 1700160084 + }, + "unsafe_l2": { + "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4", + "number": 2338094, + "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53", + "timestamp": 1696478728, + "l1origin": { + "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf", + "number": 4427339 + }, + "sequenceNumber": 3 + }, + "safe_l2": { + "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4", + "number": 2338094, + "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53", + "timestamp": 1696478728, + "l1origin": { + "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf", + "number": 4427339 + }, + "sequenceNumber": 3 + }, + "finalized_l2": { + "hash": "0x285b03afb46faad747be1ca7ab6ef50ef0ff1fe04e4eeabafc54f129d180fad2", + "number": 2337942, + "parentHash": "0x7e7f36cba1fd1ccdcdaa81577a1732776a01c0108ab5f98986cf997724eb48ac", + "timestamp": 1696478424, + "l1origin": { + "hash": "0x983309dadf7e0ab8447f3050f2a85b179e9acde1cd884f883fb331908c356412", + "number": 4427314 + }, + "sequenceNumber": 7 + } + } +} +``` + + ## WebSocket Methods WebSocket methods are only available over WebSocket (WSS) connections. All HTTP methods are also available over WebSocket. Connect using your provider's WSS endpoint and send JSON-RPC messages as UTF-8 text frames. From 183f965c66400bb0af3f6b604f173eab44df7804 Mon Sep 17 00:00:00 2001 From: roethke Date: Wed, 4 Mar 2026 12:38:15 -0800 Subject: [PATCH 2/4] remove non-public rpc methods --- docs/base-chain/reference/json-rpc-api.mdx | 132 --------------------- 1 file changed, 132 deletions(-) diff --git a/docs/base-chain/reference/json-rpc-api.mdx b/docs/base-chain/reference/json-rpc-api.mdx index 6126c66d1..99074ede9 100644 --- a/docs/base-chain/reference/json-rpc-api.mdx +++ b/docs/base-chain/reference/json-rpc-api.mdx @@ -1834,138 +1834,6 @@ Replays all transactions in a block identified by its number and returns an exec ``` -## Rollup Node Methods - -These methods are specific to the OP Stack consensus layer (op-node). They are served by the rollup node on a separate RPC port (typically port `9545`) rather than the execution engine's standard port. Node operators and infrastructure providers use these methods to query rollup-specific state. - - -These methods are not available on public execution RPC endpoints like `https://mainnet.base.org`. They require direct access to a Base node's rollup (op-node) API port. - - -### optimism_syncStatus - -Returns the current synchronization status of the rollup node, including detailed L1 and L2 block references. Use this to understand the node's view of the canonical chain, safe head, and finalized head. - -**Parameters** - -This method takes no parameters. - -**Returns** - - - The rollup sync status object. - - - - The L1 block the sequencer is currently processing. - - - The latest finalized L1 block known to the node. - - - The latest L1 block the node is aware of. - - - The latest safe L1 block. - - - The latest finalized L1 block. - - - The latest unsafe (preconfirmed) L2 block. Contains `hash`, `number`, `parentHash`, `timestamp`, `l1origin` (hash + number), and `sequenceNumber`. - - - The latest safe L2 block — derived from finalized L1 data. - - - The latest finalized L2 block. - - - The pending safe L2 block (ahead of `safe_l2` but not yet finalized). - - - The queued unsafe L2 block (sequencer tip when ahead of L1 processing). - - - - - -```json Request -{ - "jsonrpc": "2.0", - "method": "optimism_syncStatus", - "params": [], - "id": 1 -} -``` - -```json Response -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "current_l1": { - "hash": "0xff3b3253058411b727ac662f4c9ae1698918179e02ecebd304beb1a1ae8fc4fd", - "number": 4427350, - "parentHash": "0xb26586390c3f04678706dde13abfb5c6e6bb545e59c22774e651db224b16cd48", - "timestamp": 1696478784 - }, - "head_l1": { - "hash": "0x6110a8e6ed4c4aaab20477a3eac81bf99e505bf6370cd4d2e3c6d34aa5f4059a", - "number": 4706863, - "parentHash": "0xee8a9cba5d93481f11145c24890fd8f536384f3c3c043f40006650538fbdcb56", - "timestamp": 1700161272 - }, - "safe_l1": { - "hash": "0x8407c9968ce278ab435eeaced18ba8f2f94670ad9d3bdd170560932cf46e2804", - "number": 4706811, - "parentHash": "0x6593cccab3e772776418ff691f6e4e75597af18505373522480fdd97219c06ef", - "timestamp": 1700160480 - }, - "finalized_l1": { - "hash": "0x7157f91b8ae21ef869c604e5b268e392de5aa69a9f44466b9b0f838d56426541", - "number": 4706784, - "parentHash": "0x1ac2612a500b9facd650950b8755d97cf2470818da2d88552dea7cd563e86a17", - "timestamp": 1700160084 - }, - "unsafe_l2": { - "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4", - "number": 2338094, - "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53", - "timestamp": 1696478728, - "l1origin": { - "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf", - "number": 4427339 - }, - "sequenceNumber": 3 - }, - "safe_l2": { - "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4", - "number": 2338094, - "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53", - "timestamp": 1696478728, - "l1origin": { - "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf", - "number": 4427339 - }, - "sequenceNumber": 3 - }, - "finalized_l2": { - "hash": "0x285b03afb46faad747be1ca7ab6ef50ef0ff1fe04e4eeabafc54f129d180fad2", - "number": 2337942, - "parentHash": "0x7e7f36cba1fd1ccdcdaa81577a1732776a01c0108ab5f98986cf997724eb48ac", - "timestamp": 1696478424, - "l1origin": { - "hash": "0x983309dadf7e0ab8447f3050f2a85b179e9acde1cd884f883fb331908c356412", - "number": 4427314 - }, - "sequenceNumber": 7 - } - } -} -``` - - ## WebSocket Methods WebSocket methods are only available over WebSocket (WSS) connections. All HTTP methods are also available over WebSocket. Connect using your provider's WSS endpoint and send JSON-RPC messages as UTF-8 text frames. From 2d4eca0a7d23b48a119bcff12a36e80212688d5b Mon Sep 17 00:00:00 2001 From: roethke Date: Thu, 12 Mar 2026 12:47:44 -0700 Subject: [PATCH 3/4] pull changes from master --- docs/base-chain/flashblocks/api-reference.mdx | 550 ++++++------------ 1 file changed, 186 insertions(+), 364 deletions(-) diff --git a/docs/base-chain/flashblocks/api-reference.mdx b/docs/base-chain/flashblocks/api-reference.mdx index 13720e384..fae7ddad2 100644 --- a/docs/base-chain/flashblocks/api-reference.mdx +++ b/docs/base-chain/flashblocks/api-reference.mdx @@ -1,12 +1,12 @@ --- title: 'Flashblocks API Reference' -description: 'Complete reference for Flashblocks-aware RPC methods and real-time WebSocket subscription types for sub-200ms preconfirmed transaction data.' +description: 'Reference for Flashblocks-specific RPC methods, WebSocket subscriptions, and the infrastructure stream schema.' --- -Flashblocks-aware nodes extend the standard Ethereum JSON-RPC API with support for preconfirmed block state and Flashblocks-specific real-time subscriptions. All [standard JSON-RPC methods](/base-chain/reference/json-rpc-api) remain fully supported. +This page covers what is unique to Flashblocks: the preconf endpoints, Flashblocks-only methods, real-time WebSocket subscriptions, and the infrastructure stream schema. -See [Flashblocks](/base-chain/flashblocks/apps) for an overview of Flashblocks and how to integrate it into your app. For the standard Base node RPC reference, see the [JSON-RPC API Reference](/base-chain/reference/json-rpc-api). +All [standard JSON-RPC methods](/base-chain/reference/json-rpc-api) work as-is against a Flashblocks endpoint — use the `"pending"` block tag to read preconfirmed state. ## Endpoints @@ -22,367 +22,6 @@ Connect to a Flashblocks-aware endpoint to access preconfirmed data: The public endpoints above are rate-limited and not suitable for production traffic. For production use, connect through a Flashblocks-enabled node provider such as Alchemy, QuickNode, or dRPC. ---- - -## Standard Methods with Flashblocks Behavior - -The following standard JSON-RPC methods return preconfirmed data when called with the `"pending"` block tag against a Flashblocks-aware endpoint. This gives your application real-time state up to 200ms before the next full block is sealed. - -### eth_getBlockByNumber - -When called with `"pending"`, returns the current Flashblock — the block actively being built with preconfirmed transactions. - -#### Parameters - - - Use `"pending"` to retrieve the latest Flashblock. Also accepts `"latest"`, `"safe"`, `"finalized"`, or a specific block number. - - - - If `true`, returns full transaction objects. If `false`, returns only transaction hashes. - - -#### Returns - - - A block object reflecting the current preconfirmed state. See [eth_getBlockByNumber](/base-chain/reference/json-rpc-api#eth_getblockbynumber) for full field descriptions. Flashblocks-specific fields: - - - `withdrawals` — Always `[]` for Base (no L2 withdrawals in pending blocks). - - `parentBeaconBlockRoot` — Beacon block root passed from the builder; present on all pending blocks. - - `requestsHash` — Always the empty requests hash (`0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`). - - `blobGasUsed` — Accurately reflects blob gas consumed by preconfirmed transactions (not zero-padded). - - - -```bash cURL -curl https://sepolia-preconf.base.org \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending",true],"id":1}' -``` - -```json Response -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "number": "0x1234", - "hash": "0x...", - "parentHash": "0x...", - "parentBeaconBlockRoot": "0xa4b2c8e1f3d5b7a9c2e4f6d8b0a2c4e6f8d0b2a4c6e8f0d2b4a6c8e0f2d4b6a8", - "withdrawals": [], - "requestsHash": "0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", - "blobGasUsed": "0x0", - "transactions": ["0x..."] - } -} -``` - - ---- - -### eth_getTransactionReceipt - -Returns the receipt for a preconfirmed transaction before it is included in a finalized block. - -#### Parameters - - - The 32-byte transaction hash. - - -#### Returns - - - A transaction receipt object for the preconfirmed transaction, or `null` if not found. See [eth_getTransactionReceipt](/base-chain/reference/json-rpc-api#eth_gettransactionreceipt) for full field descriptions. - - - `blobGasUsed` — Accurately reflects blob gas used by the transaction. Previously returned `0x0` for all preconfirmed transactions; now correctly propagated from the Flashblock. - - - -```bash cURL -curl https://sepolia-preconf.base.org \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}' -``` - -```json Response -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "transactionHash": "0x...", - "blockNumber": "0x1234", - "status": "0x1", - "blobGasUsed": "0x0" - } -} -``` - - ---- - -### eth_getBalance - -Returns the ETH balance of an address in the latest preconfirmed Flashblock state. - -#### Parameters - - - The 20-byte address to query. - - - - Use `"pending"` to query preconfirmed state. - - -#### Returns - - - The balance in wei as a hexadecimal string. - - - -```bash cURL -curl https://sepolia-preconf.base.org \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x...","pending"],"id":1}' -``` - -```json Response -{ - "jsonrpc": "2.0", - "id": 1, - "result": "0x0234c00000" -} -``` - - ---- - -### eth_getTransactionCount - -Returns the account nonce in the latest preconfirmed Flashblock state. Use `"pending"` to account for transactions that are preconfirmed but not yet in a sealed block. - -#### Parameters - - - The 20-byte account address. - - - - Use `"pending"` to include preconfirmed transactions in the nonce count. - - -#### Returns - - - The transaction count (nonce) as a hexadecimal integer. - - - -```bash cURL -curl https://sepolia-preconf.base.org \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0x...","pending"],"id":1}' -``` - -```json Response -{ - "jsonrpc": "2.0", - "id": 1, - "result": "0x1b" -} -``` - - ---- - -### eth_getTransactionByHash - -Returns a preconfirmed transaction before it is included in a finalized block. - -#### Parameters - - - The 32-byte transaction hash. - - -#### Returns - - - A transaction object, or `null` if not found. See [eth_getTransactionByHash](/base-chain/reference/json-rpc-api#eth_gettransactionbyhash) for full field descriptions. - - - -```bash cURL -curl https://sepolia-preconf.base.org \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x..."],"id":1}' -``` - -```json Response -{ - "jsonrpc": "2.0", - "id": 1, - "result": { - "type": "0x2", - "chainId": "0x14a34", - "nonce": "0x1b", - "hash": "0x...", - "from": "0x...", - "to": "0x..." - } -} -``` - - ---- - -### eth_call - -Executes a contract call against the latest preconfirmed Flashblock state. - -#### Parameters - - - The transaction call object. See [eth_call](/base-chain/reference/json-rpc-api#eth_call) for field details. - - - - Use `"pending"` to execute the call against preconfirmed state. - - -#### Returns - - - Hex-encoded return data from the contract call. - - - -```bash cURL -curl https://sepolia-preconf.base.org \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x...","data":"0x..."},"pending"],"id":1}' -``` - -```json Response -{ - "jsonrpc": "2.0", - "id": 1, - "result": "0x0000000000000000000000000000000000000000000000000000000000000001" -} -``` - - ---- - -### eth_estimateGas - -Estimates gas for a transaction against the latest preconfirmed Flashblock state. - -#### Parameters - - - The transaction object. See [eth_estimateGas](/base-chain/reference/json-rpc-api#eth_estimategas) for field details. - - - - Use `"pending"` to estimate against preconfirmed state. - - -#### Returns - - - Estimated gas as a hexadecimal integer. - - - -```bash cURL -curl https://sepolia-preconf.base.org \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"to":"0x...","data":"0x..."},"pending"],"id":1}' -``` - -```json Response -{ - "jsonrpc": "2.0", - "id": 1, - "result": "0x5208" -} -``` - - ---- - -### eth_getLogs - -Returns logs from preconfirmed Flashblock data by setting `"toBlock"` to `"pending"`. - -#### Parameters - - - The log filter object. - - - - Start of the block range. Use `"latest"` for the most recent mined block. - - - Use `"pending"` to include logs from the current Flashblock. - - - A single contract address or array of addresses to filter by. Optional. - - - Array of topic filters. Same format as in `eth_getLogs`. Optional. - - - - -#### Returns - - - An array of log objects. See [eth_getLogs](/base-chain/reference/json-rpc-api#eth_getlogs) for full field descriptions. - - - -```bash cURL -curl https://sepolia-preconf.base.org \ - -X POST \ - -H "Content-Type: application/json" \ - -d '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"latest","toBlock":"pending","address":"0x...","topics":["0x..."]}],"id":1}' -``` - -```json Response -{ - "jsonrpc": "2.0", - "id": 1, - "result": [ - { - "address": "0x...", - "topics": ["0x..."], - "data": "0x...", - "blockNumber": "0x1234", - "transactionHash": "0x...", - "transactionIndex": "0x0", - "blockHash": "0x...", - "logIndex": "0x0", - "removed": false - } - ] -} -``` - - ---- - ## Flashblocks-Specific Methods ### eth_simulateV1 @@ -759,3 +398,186 @@ Cancels a Flashblocks subscription. Works identically to the [standard eth_unsub {"jsonrpc": "2.0", "id": 1, "result": true} ``` + +--- + +## Infrastructure Stream + +The raw Flashblocks infrastructure stream is the upstream source that Flashblocks-aware RPC nodes consume. + + +**Applications should not connect directly to the infrastructure stream.** These endpoints are for node infrastructure only. App developers should use the [WebSocket subscription methods](#websocket-subscription-methods) above via a Flashblocks-aware RPC provider. + + +| Network | URL | +|---------|-----| +| Mainnet | `wss://mainnet.flashblocks.base.org/ws` | +| Sepolia | `wss://sepolia.flashblocks.base.org/ws` | + +### Flashblock Object + +The root structure of each infrastructure stream message. + + + +Unique identifier for the block being built. Remains consistent across all 10 Flashblocks within a single full block. + + + +Flashblock index within the current block (0–10). Index 0 contains system transactions only; indexes 1–10 contain user transactions. + + + +Block header properties. **Only present when `index` is 0.** See [Base Object](#base-object). + + + +Block differences/updates for this Flashblock. See [Diff Object](#diff-object). + + + +Additional data including balance updates and transaction receipts. **Not stable — may change without notice.** See [Metadata Object](#metadata-object). + + + +### Base Object + +Contains full block header properties. **Only present in Index 0** (the first Flashblock of each full block). + + +Hash of the parent block. +Address receiving transaction fees (coinbase). +Block number in hex format. +Maximum gas allowed in this block (hex). +Unix timestamp of block creation (hex). +Base fee per gas unit (hex, EIP-1559). +Previous RANDAO value for randomness. +Arbitrary data included by the block builder. + + +### Diff Object + +Contains the block state changes for this specific Flashblock. Present in every message. + + +Merkle root of the state trie after applying this Flashblock's transactions. +Hash of the block at this Flashblock index. Changes with each Flashblock as more transactions are added. +Cumulative gas used up to and including this Flashblock (hex). +Cumulative blob gas used (hex, EIP-4844). +Array of RLP-encoded transaction data included in this Flashblock. +Validator withdrawals included in this Flashblock (typically empty on L2). +Merkle root of transaction receipts. +Bloom filter for quick log searching. +Merkle root of withdrawals. + + +### Metadata Object + + +**The `metadata` object is not stable.** + +Fields may be added, modified, or removed without prior notice. Do not build production dependencies on it — use the [`diff`](#diff-object) object or query finalized block data via RPC instead. + + + +Block number as a decimal integer. +Map of addresses to their updated ETH balances (hex). Only includes accounts whose balances changed in this Flashblock. +Map of transaction hashes to their [Receipt](#receipt-object) objects. + + +### Receipt Object + +Transaction execution result. + +Check which `type` is present to determine the transaction type: `Legacy`, `Access List`, `EIP-1559`, `Custom/Experimental (Deposit)` + + +Transaction type: `0x0` Legacy, `0x1` Access List, `0x2` EIP-1559, `0x7e` Deposit (L1→L2). +Transaction status: `0x1` for success, `0x0` for failure. +Total gas used in the block up to and including this transaction (hex). +Array of event logs emitted by the transaction. See [Log Object](#log-object). +Bloom filter for the logs in this receipt. +Index of the transaction within the block (hex). + + +### Log Object + + +Contract address that emitted the event. +Array of indexed event parameters. The first topic is typically the event signature hash. +ABI-encoded non-indexed event parameters. + + +### Complete Examples + +**Index 0 (initial)** — includes the `base` object: + +```json +{ + "payload_id": "0x03997352d799c31a", + "index": 0, + "base": { + "parent_hash": "0x9edc29b8b0a1e31d28616e40c16132ad0d58faa8bb952595b557526bdb9a960a", + "fee_recipient": "0x4200000000000000000000000000000000000011", + "block_number": "0x158a0e9", + "gas_limit": "0x3938700", + "timestamp": "0x67bf8332", + "base_fee_per_gas": "0xfa" + }, + "diff": { + "state_root": "0x208fd63edc0681161105f27d03daf9f8c726d8c94e584a3c0696c98291c24333", + "block_hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8", + "gas_used": "0xab3f", + "transactions": ["0x7ef8f8a0b4afc0b7ce10e150801bbaf08ac33fecb0f38311793abccb022120d321c6d276..."], + "withdrawals": [] + }, + "metadata": { + "block_number": 22585577, + "new_account_balances": { + "0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0" + }, + "receipts": { + "0x07d7f06b06fea714c1d1d446efa2790c6970aa74ee006186a32b5b7dd8ca2d82": { + "type": "0x7e", + "status": "0x1", + "cumulativeGasUsed": "0xab3f", + "logs": [], + "logsBloom": "0x00000000...", + "transactionIndex": "0x0" + } + } + } +} +``` + +**Index 1–10 (diff only)** — no `base` object: + +```json +{ + "payload_id": "0x03997352d799c31a", + "index": 4, + "diff": { + "state_root": "0x7a8f45038665072f382730e689f4a1561835c9987fca8942fa95872fb9367eaa", + "block_hash": "0x9b32f7a14cbd1efc8c2c5cad5eb718ec9e0c5da92c3ba7080f8d4c49d660c332", + "gas_used": "0x1234f", + "transactions": ["0x02f90133...", "0x02f90196..."], + "withdrawals": [] + }, + "metadata": { + "block_number": 22585577, + "new_account_balances": { + "0x4200000000000000000000000000000000000015": "0x1234" + }, + "receipts": { + "0x7c69632dc315f13a...": { + "type": "0x2", + "status": "0x1", + "cumulativeGasUsed": "0x1234f", + "logs": [], + "logsBloom": "0x00000000...", + "transactionIndex": "0x1" + } + } + } +} +``` From 6f44168ee19b2244d998063554e81f2055a63890 Mon Sep 17 00:00:00 2001 From: roethke Date: Thu, 12 Mar 2026 12:53:12 -0700 Subject: [PATCH 4/4] update response fields, tx types --- docs/base-chain/reference/json-rpc-api.mdx | 26 ++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/base-chain/reference/json-rpc-api.mdx b/docs/base-chain/reference/json-rpc-api.mdx index 99074ede9..83aee2bf7 100644 --- a/docs/base-chain/reference/json-rpc-api.mdx +++ b/docs/base-chain/reference/json-rpc-api.mdx @@ -434,11 +434,23 @@ Returns information about a block by its block number. Base fee per gas in this block (EIP-1559). - Array of validator withdrawals included in the block (EIP-4895). + Array of validator withdrawals included in the block (EIP-4895). Always `[]` on Base — L2 does not process validator withdrawals. 32-byte root of the withdrawals trie (EIP-4895). + + 32-byte beacon block root of the parent block (EIP-4788). Present on all Base blocks. + + + Hash of the requests list (EIP-7685). Always the empty requests hash (`0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`) on Base. + + + Total blob gas consumed by blob-carrying transactions in this block (EIP-4844). Accurately reflects blob gas in both finalized and preconfirmed (Flashblocks) blocks. + + + Cumulative excess blob gas used to calculate the blob base fee (EIP-4844). + @@ -737,7 +749,7 @@ Returns transaction information for a given transaction hash. ABI-encoded call data sent with the transaction. `"0x"` for plain ETH transfers. - Transaction type: `"0x0"` (legacy), `"0x1"` (EIP-2930 access list), `"0x2"` (EIP-1559), `"0x7e"` (deposit transaction on Base). + Transaction type: `"0x0"` (Legacy), `"0x1"` (EIP-2930/Access List), `"0x2"` (EIP-1559), `"0x7e"` (Deposit). Chain ID the transaction is valid for. `"0x2105"` for Base Mainnet, `"0x14a34"` for Base Sepolia. @@ -908,7 +920,7 @@ Returns transaction information for a given block number and transaction index p Returns the receipt for a mined transaction. Receipts are only available after the transaction has been included in a block. -For preconfirmed transaction receipts before a block is sealed, use a [Flashblocks-aware endpoint](/base-chain/flashblocks/api-reference#eth_gettransactionreceipt). +For preconfirmed transaction receipts before a block is sealed, use a [Flashblocks-aware endpoint](/base-chain/flashblocks/api-reference#endpoints). **Parameters** @@ -963,7 +975,13 @@ For preconfirmed transaction receipts before a block is sealed, use a [Flashbloc `"0x1"` for a successful transaction, `"0x0"` for a failed (reverted) transaction. - Transaction type: `"0x0"` (legacy), `"0x1"` (EIP-2930), `"0x2"` (EIP-1559). + Transaction type: `"0x0"` (Legacy), `"0x1"` (EIP-2930/Access List), `"0x2"` (EIP-1559), `"0x7e"` (Deposit). + + + Blob gas consumed by this transaction (EIP-4844). `"0x0"` for non-blob transactions. When querying via a [Flashblocks-aware endpoint](/base-chain/flashblocks/api-reference#endpoints), this is accurately propagated from the preconfirmed block state. + + + Blob gas price at the time of the transaction (EIP-4844).