From 2047cd81f31e37bc15eac910e97843ad7379919f Mon Sep 17 00:00:00 2001 From: roethke Date: Tue, 3 Mar 2026 08:34:05 -0800 Subject: [PATCH 1/2] 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/2] 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.