diff --git a/docs/base-chain/api-reference/flashblocks-api/flashblocks-api-overview.mdx b/docs/base-chain/api-reference/flashblocks-api/flashblocks-api-overview.mdx index 40648d001..12d9252a5 100644 --- a/docs/base-chain/api-reference/flashblocks-api/flashblocks-api-overview.mdx +++ b/docs/base-chain/api-reference/flashblocks-api/flashblocks-api-overview.mdx @@ -1,7 +1,7 @@ --- title: 'Overview' sidebarTitle: 'Overview' -description: 'Flashblocks-specific RPC methods, WebSocket subscriptions, and the infrastructure stream schema for Base pre-confirmations.' +description: 'Flashblocks-specific RPC methods and WebSocket subscriptions for Base pre-confirmations.' --- All Base public endpoints (`mainnet.base.org` / `sepolia.base.org`) are Flashblocks-enabled, exposing all standard Ethereum JSON-RPC methods plus a set of pre-confirmation-specific additions. These let you read state, simulate transactions, and stream events against sequencer-ordered data up to ~1.8 seconds before a block seals. @@ -27,164 +27,3 @@ On a Flashblocks WSS endpoint, `eth_subscribe` with `newHeads` emits a new event | [pendingLogs](/base-chain/api-reference/flashblocks-api/pendingLogs) | Stream filtered event logs from pre-confirmed transactions | | [newFlashblocks](/base-chain/api-reference/flashblocks-api/newFlashblocks) | Stream full Flashblock payload objects from the sequencer | -## Infrastructure Stream - -The raw Flashblocks infrastructure stream is the upstream WebSocket feed consumed by Flashblocks-aware RPC nodes. It emits a new message approximately every 200ms as the sequencer pre-confirms transactions. - - -**Applications should not connect directly to the infrastructure stream.** These endpoints are for node operators only. App developers should use the [WebSocket subscription methods](#websocket-subscriptions) above via a Flashblocks-aware RPC provider. - - -| Network | Raw stream 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 Flashblocks within a single full block. - - - -Flashblock index within the current block. Starts at 0 (system transactions only). User transactions begin at index 1. Typically reaches 9–10 per block, but [may exceed 10](/base-chain/flashblocks/faq#why-can-the-flashblock-index-exceed-10) during sequencer timing drift. - - - -Block header properties. **Only present when `index` is `0`.** See [Base Object](#base-object). - - - -Incremental block state changes for this Flashblock. Present in every message. See [Diff Object](#diff-object). - - - -Supplemental data. **Unstable — fields may change without notice.** See [Metadata Object](#metadata-object). - - - -### Base Object - -Contains full block header properties. **Only present in the `index: 0` message** (the first Flashblock of each full block). - - -Hash of the parent block. -Address receiving transaction fees (coinbase). -Block number in hex. -Maximum gas allowed in this block (hex). -Unix timestamp of block creation (hex). -EIP-1559 base fee per gas (hex). -Previous RANDAO value used for on-chain randomness. -Arbitrary data field set by the sequencer. -Root of the parent beacon block (EIP-4788). - - -### Diff Object - -Contains the incremental 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 partial block at this Flashblock index. Changes with each Flashblock as more transactions are pre-confirmed. -Cumulative gas used up to and including this Flashblock (hex). -Cumulative blob gas used (EIP-4844, hex). -Array of RLP-encoded transactions included in this Flashblock. -Validator withdrawals (always empty on Base L2). -Merkle root of transaction receipts. -Bloom filter for logs in this Flashblock. -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 standard RPC instead. - - -As of v0.8.0, `new_account_balances` and `receipts` are no longer present in the `metadata` object. `block_number` remains. The `access_list` field is present but always empty. - - -Block number as a decimal integer. - - -### Receipt Object - - -`metadata.receipts` was removed in v0.8.0. This schema is preserved for reference for older node versions. On v0.8.0+, use [`eth_getTransactionReceipt`](/base-chain/api-reference/ethereum-json-rpc-api/eth_getTransactionReceipt) for polling-based receipt data, or subscribe to [`newFlashblockTransactions`](/base-chain/api-reference/flashblocks-api/newFlashblockTransactions) with `full: true` for a real-time stream of pre-confirmed transaction data including logs. - - - -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. Topic 0 is typically the event signature hash. -ABI-encoded non-indexed event parameters. -Hash of the block containing this log. -Block number in hex. -Unix timestamp of the block as a hex string. Base L2 extension to the standard Ethereum log schema. -Hash of the transaction that emitted this log. -Index of the transaction in the block (hex). -Log's index position within the block (hex). -`true` if the log was removed due to a chain reorg. - - -### Complete Examples - -**Index 0** — includes the `base` object (block header): - -```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", - "parent_beacon_block_root": "0x15b9e7c8ac4cbe92dafc849ed30a23e91624bbe5cbe199c0ccea3f7de7fc6d49" - }, - "diff": { - "state_root": "0x208fd63edc0681161105f27d03daf9f8c726d8c94e584a3c0696c98291c24333", - "block_hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8", - "gas_used": "0xab3f", - "transactions": ["0x7ef8f8a0b4afc0b7ce10e150801bbaf08ac33fecb0f38311793abccb022120d321c6d276..."], - "withdrawals": [] - }, - "metadata": { - "block_number": 22585577 - } -} -``` - -**Index 1–N (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 - } -} -``` diff --git a/docs/base-chain/api-reference/flashblocks-api/newFlashblocks.mdx b/docs/base-chain/api-reference/flashblocks-api/newFlashblocks.mdx index 1eea35ba8..5ddda558a 100644 --- a/docs/base-chain/api-reference/flashblocks-api/newFlashblocks.mdx +++ b/docs/base-chain/api-reference/flashblocks-api/newFlashblocks.mdx @@ -1,13 +1,13 @@ --- title: 'newFlashblocks' sidebarTitle: 'newFlashblocks' -description: 'Subscribe to receive full Flashblock payload stream as each pre-confirmed block is built. Only available on Flashblocks WebSocket endpoints.' +description: 'Subscribe to receive full Flashblock payload stream as each pre-confirmed block is built. Requires a Flashblocks-aware WebSocket RPC endpoint.' --- Subscribe via `eth_subscribe` to receive full block state updates as each Flashblock is built. Each message contains the accumulated pre-confirmed state for the block in progress. -Only available on Flashblocks WebSocket endpoints: `wss://mainnet-preconf.base.org` and `wss://sepolia-preconf.base.org`. +This subscription requires a WebSocket-enabled RPC endpoint with Flashblocks support. The public Base endpoints (`mainnet.base.org`, `sepolia.base.org`) are HTTP only. Use a [node provider](/base-chain/node-operators/node-providers) such as Alchemy or QuickNode that offers WebSocket support for Base. @@ -27,7 +27,7 @@ Each subscription emits **one Flashblock Object per WebSocket message**. Events ## Returns - Hex-encoded subscription ID. Each event notification delivers a **Flashblock Object** — not a standard block object. The payload contains `payload_id`, `index`, `diff`, and (on index 0) `base`. See the [Infrastructure Stream schema](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview#flashblock-object) for the full structure. + Hex-encoded subscription ID. Each event notification delivers a **Flashblock Object** — not a standard block object. The payload contains `payload_id`, `index`, `diff`, and (on index 0) `base`. See the [Infrastructure Stream schema](/base-chain/node-operators/run-a-base-node#flashblock-object) for the full structure. ## Example @@ -44,8 +44,8 @@ Each subscription emits **one Flashblock Object per WebSocket message**. Events ```javascript JavaScript import WebSocket from 'ws'; -// Use a Flashblocks-enabled provider WSS endpoint in production -const ws = new WebSocket('wss://mainnet-preconf.base.org'); +// Use a Flashblocks-enabled provider WSS endpoint (e.g. from Alchemy or QuickNode) +const ws = new WebSocket('wss://'); ws.on('open', () => { ws.send(JSON.stringify({ diff --git a/docs/base-chain/api-reference/flashblocks-api/pendingLogs.mdx b/docs/base-chain/api-reference/flashblocks-api/pendingLogs.mdx index b17e9c4a3..0c597399e 100644 --- a/docs/base-chain/api-reference/flashblocks-api/pendingLogs.mdx +++ b/docs/base-chain/api-reference/flashblocks-api/pendingLogs.mdx @@ -1,13 +1,13 @@ --- title: 'pendingLogs' sidebarTitle: 'pendingLogs' -description: 'Subscribe to logs from pre-confirmed transactions matching an optional filter. Only available on Flashblocks WebSocket endpoints.' +description: 'Subscribe to logs from pre-confirmed transactions matching an optional filter. Requires a Flashblocks-aware WebSocket RPC endpoint.' --- Subscribe via `eth_subscribe` to receive logs from pre-confirmed transactions matching an optional filter. Useful for monitoring contract events with sub-block latency. -Only available on Flashblocks WebSocket endpoints: `wss://mainnet-preconf.base.org` / `wss://sepolia-preconf.base.org`. +This subscription requires a WebSocket-enabled RPC endpoint with Flashblocks support. The public Base endpoints (`mainnet.base.org`, `sepolia.base.org`) are HTTP only. Use a [node provider](/base-chain/node-operators/node-providers) such as Alchemy or QuickNode that offers WebSocket support for Base. diff --git a/docs/base-chain/flashblocks/app-integration.mdx b/docs/base-chain/flashblocks/app-integration.mdx index d7b417fe8..42cf2f951 100644 --- a/docs/base-chain/flashblocks/app-integration.mdx +++ b/docs/base-chain/flashblocks/app-integration.mdx @@ -18,7 +18,7 @@ Applications should avoid hard dependencies on the WebSocket stream. RPCs provid ## RPC Endpoints -For HTTP and WebSocket endpoint URLs, see the [Flashblocks API Reference](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview). Public endpoints are rate-limited. For production use, connect through a Flashblocks-enabled node provider such as Alchemy, QuickNode, or dRPC. +For HTTP endpoint URLs, see the [RPC Overview](/base-chain/api-reference/rpc-overview). The public Base endpoints are HTTP only — for WebSocket support, use a [node provider](/base-chain/node-operators/node-providers) such as Alchemy, QuickNode, or dRPC. Public endpoints are rate-limited and not suitable for production traffic. ## Performance Characteristics diff --git a/docs/base-chain/flashblocks/architecture.mdx b/docs/base-chain/flashblocks/architecture.mdx index f1b24eda5..d70be2e42 100644 --- a/docs/base-chain/flashblocks/architecture.mdx +++ b/docs/base-chain/flashblocks/architecture.mdx @@ -35,5 +35,6 @@ Flashblocks introduce several new infrastructure components: - [Flashblocks Overview](/base-chain/flashblocks/overview) — Key concepts and transaction lifecycle - [Enable Flashblocks](/base-chain/node-operators/run-a-base-node#enable-flashblocks) — Run your own Flashblocks-aware RPC node -- [API Reference](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview) — RPC methods, WebSocket subscriptions, and infrastructure stream schema +- [API Reference](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview) — RPC methods and WebSocket subscriptions +- [Infrastructure Stream Schema](/base-chain/node-operators/run-a-base-node#infrastructure-stream-schema) — Message format for node operators - [Flashblocks Deep Dive](https://blog.base.dev/flashblocks-deep-dive) — Engineering blog post with implementation details diff --git a/docs/base-chain/flashblocks/faq.mdx b/docs/base-chain/flashblocks/faq.mdx index c07f4264c..4a82793e1 100644 --- a/docs/base-chain/flashblocks/faq.mdx +++ b/docs/base-chain/flashblocks/faq.mdx @@ -102,7 +102,7 @@ For a comprehensive introduction to how Flashblocks work, see the [Flashblocks O - Transaction data in the [`diff.transactions`](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview#diff-object) array is Recursive Length Prefix (RLP) encoded. + Transaction data in the [`diff.transactions`](/base-chain/node-operators/run-a-base-node#diff-object) array is Recursive Length Prefix (RLP) encoded. diff --git a/docs/base-chain/flashblocks/overview.mdx b/docs/base-chain/flashblocks/overview.mdx index 21f2c7cc7..b25dd690e 100644 --- a/docs/base-chain/flashblocks/overview.mdx +++ b/docs/base-chain/flashblocks/overview.mdx @@ -75,7 +75,7 @@ FOR each flashblock j FROM 0 TO 10: Once a transaction is included in a Flashblock, it's streamed to the websocket-proxy, which RPC nodes listen to. When you call a Flashblocks-aware RPC method (like `eth_getTransactionReceipt`), the node retrieves the preconfirmed data from its cache. -For the complete infrastructure stream schema, see the [Flashblocks API Overview](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview) reference: [Flashblock](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview#flashblock-object), [Diff](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview#diff-object), [Metadata](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview#metadata-object), [Receipt](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview#receipt-object). +For the complete infrastructure stream schema, see the [Run a Node](/base-chain/node-operators/run-a-base-node#infrastructure-stream-schema) reference: [Flashblock](/base-chain/node-operators/run-a-base-node#flashblock-object), [Diff](/base-chain/node-operators/run-a-base-node#diff-object), [Metadata](/base-chain/node-operators/run-a-base-node#metadata-object), [Receipt](/base-chain/node-operators/run-a-base-node#receipt-object). ## Further Reading diff --git a/docs/base-chain/node-operators/run-a-base-node.mdx b/docs/base-chain/node-operators/run-a-base-node.mdx index 4d36be28e..76b908938 100644 --- a/docs/base-chain/node-operators/run-a-base-node.mdx +++ b/docs/base-chain/node-operators/run-a-base-node.mdx @@ -131,9 +131,160 @@ Applications should not connect directly to `wss://mainnet.flashblocks.base.org/ -The [base](https://github.com/base/base) binary listens to the Flashblocks WebSocket stream and caches preconfirmation data. When Flashblocks-aware RPC methods are called, it returns data from this cache. For the full message schema and payload structure, see [Flashblocks API Overview](/base-chain/api-reference/flashblocks-api/flashblocks-api-overview). +The [base](https://github.com/base/base) binary listens to the Flashblocks WebSocket stream and caches preconfirmation data. When Flashblocks-aware RPC methods are called, it returns data from this cache. +### Infrastructure Stream Schema + +Each message emitted by the infrastructure stream is a Flashblock object with the following structure. + +#### Flashblock Object + + + +Unique identifier for the block being built. Remains consistent across all Flashblocks within a single full block. + + + +Flashblock index within the current block. Starts at 0 (system transactions only). User transactions begin at index 1. Typically reaches 9–10 per block, but [may exceed 10](/base-chain/flashblocks/faq#why-can-the-flashblock-index-exceed-10) during sequencer timing drift. + + + +Block header properties. **Only present when `index` is `0`.** See [Base Object](#base-object). + + + +Incremental block state changes for this Flashblock. Present in every message. See [Diff Object](#diff-object). + + + +Supplemental data. **Unstable — fields may change without notice.** See [Metadata Object](#metadata-object). + + + +#### Base Object + +Contains full block header properties. **Only present in the `index: 0` message** (the first Flashblock of each full block). + + +Hash of the parent block. +Address receiving transaction fees (coinbase). +Block number in hex. +Maximum gas allowed in this block (hex). +Unix timestamp of block creation (hex). +EIP-1559 base fee per gas (hex). +Previous RANDAO value used for on-chain randomness. +Arbitrary data field set by the sequencer. +Root of the parent beacon block (EIP-4788). + + +#### Diff Object + +Contains the incremental 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 partial block at this Flashblock index. Changes with each Flashblock as more transactions are pre-confirmed. +Cumulative gas used up to and including this Flashblock (hex). +Cumulative blob gas used (EIP-4844, hex). +Array of RLP-encoded transactions included in this Flashblock. +Validator withdrawals (always empty on Base L2). +Merkle root of transaction receipts. +Bloom filter for logs in this Flashblock. +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 standard RPC instead. + + +As of v0.8.0, `new_account_balances` and `receipts` are no longer present in the `metadata` object. `block_number` remains. The `access_list` field is present but always empty. + + +Block number as a decimal integer. + + +#### Receipt Object + + +`metadata.receipts` was removed in v0.8.0. This schema is preserved for reference for older node versions. On v0.8.0+, use [`eth_getTransactionReceipt`](/base-chain/api-reference/ethereum-json-rpc-api/eth_getTransactionReceipt) for polling-based receipt data, or subscribe to [`newFlashblockTransactions`](/base-chain/api-reference/flashblocks-api/newFlashblockTransactions) with `full: true` for a real-time stream of pre-confirmed transaction data including logs. + + + +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. Topic 0 is typically the event signature hash. +ABI-encoded non-indexed event parameters. +Hash of the block containing this log. +Block number in hex. +Unix timestamp of the block as a hex string. Base L2 extension to the standard Ethereum log schema. +Hash of the transaction that emitted this log. +Index of the transaction in the block (hex). +Log's index position within the block (hex). +`true` if the log was removed due to a chain reorg. + + +#### Complete Examples + +**Index 0** — includes the `base` object (block header): + +```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", + "parent_beacon_block_root": "0x15b9e7c8ac4cbe92dafc849ed30a23e91624bbe5cbe199c0ccea3f7de7fc6d49" + }, + "diff": { + "state_root": "0x208fd63edc0681161105f27d03daf9f8c726d8c94e584a3c0696c98291c24333", + "block_hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8", + "gas_used": "0xab3f", + "transactions": ["0x7ef8f8a0b4afc0b7ce10e150801bbaf08ac33fecb0f38311793abccb022120d321c6d276..."], + "withdrawals": [] + }, + "metadata": { + "block_number": 22585577 + } +} +``` + +**Index 1–N (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 + } +} +``` + ### Verify Flashblocks Functionality Test that your node is properly serving Flashblocks by querying a pending block: