From a24680e56418c8e957d4efd44c70be74f911abe4 Mon Sep 17 00:00:00 2001 From: roethke Date: Wed, 21 Jan 2026 11:00:04 -0800 Subject: [PATCH 01/11] add overview page and improve documentation structure --- docs/base-chain/flashblocks/apps.mdx | 21 ++- docs/base-chain/flashblocks/docs.mdx | 108 +++++++---- .../base-chain/flashblocks/node-providers.mdx | 120 ++++++++---- docs/base-chain/flashblocks/overview.mdx | 173 ++++++++++++++++++ .../network-information/block-building.mdx | 28 +-- docs/docs.json | 1 + 6 files changed, 363 insertions(+), 88 deletions(-) create mode 100644 docs/base-chain/flashblocks/overview.mdx diff --git a/docs/base-chain/flashblocks/apps.mdx b/docs/base-chain/flashblocks/apps.mdx index a96c26d57..bdaa52afb 100644 --- a/docs/base-chain/flashblocks/apps.mdx +++ b/docs/base-chain/flashblocks/apps.mdx @@ -1,16 +1,27 @@ --- -title: Flashblocks +title: App Integration sidebarTitle: Apps -description: Experience lightning-fast transaction confirmations of Base by using Flashblocks. Preconfirmations happen in just 200 milliseconds—designed for real-time apps, games, and seamless UX. +description: Integrate Flashblocks into your app for 200ms transaction confirmations using RPC APIs and popular libraries like Wagmi and Viem. --- ## Overview -Flashblocks enable up to 200 millisecond transaction confirmations on Base by leveraging preconfirmations, ultra-fast signals that arrive before the next block is sealed. Built for developers who demand instant UX, it's ideal for high-frequency apps, games, and real-time interactions where waiting even a few seconds is too long. By integrating directly within Base's infrastructure, Flashblocks enables, seamless, ultrafast and snappy user experiences without compromising security. +Flashblocks enable **200 millisecond** transaction confirmations on Base through preconfirmations—ultra-fast signals that arrive before the full 2-second block is sealed. -## Integrating Flashblocks + +New to Flashblocks? Start with the [Flashblocks Overview](/base-chain/flashblocks/overview) to understand the architecture and how transactions flow through the system. + -Flashblocks is enabled for developers on Base. There are two ways you can integrate with Flashblocks data. You can either use the WebSocket API to stream real-time block updates, or use the RPC API to query the Flashblocks-aware RPC endpoint. +## Integration Methods + +There are two ways to integrate with Flashblocks: + +1. **RPC API** — Query Flashblocks-aware endpoints using familiar JSON-RPC methods with the `pending` tag +2. **WebSocket API** — Stream real-time Flashblock data for lowest latency (see [Node Providers](/base-chain/flashblocks/node-providers#websocket-api)) + + +For most apps, the RPC API is recommended. WebSocket is best for traders and infrastructure providers who need the absolute lowest latency. + ### RPC API diff --git a/docs/base-chain/flashblocks/docs.mdx b/docs/base-chain/flashblocks/docs.mdx index 6aed7392b..c15930186 100644 --- a/docs/base-chain/flashblocks/docs.mdx +++ b/docs/base-chain/flashblocks/docs.mdx @@ -1,76 +1,104 @@ --- -title: "Flashblocks FAQ" +title: Flashblocks FAQ +sidebarTitle: FAQ +description: Frequently asked questions about Flashblocks, including block building, WebSocket data, RPC usage, and node setup. --- -## Flashblocks Block Building + +For a comprehensive introduction to how Flashblocks work, see the [Flashblocks Overview](/base-chain/flashblocks/overview). + -### Are flashblocks optional? +## Block Building -All Base blocks are built by the Flashblocks builder, meaning Flashblocks are always live. However, apps may choose not to rely on preconfirmations and are welcome to continue to have an integration that does not rely on Flashblocks. +### Are Flashblocks optional? -### Is there any difference in tx inclusion for flashblocks vs. 2s block? +All Base blocks are built by the Flashblocks builder, meaning **Flashblocks are always live**. However, apps may choose not to rely on preconfirmations and can continue using standard RPCs without any Flashblocks integration. -No particular differences except more frequent timing, both still pick txs based on tx fees ordering. You can read more about it here (https://docs.base.org/base-chain/network-information/block-building#flashblocks). +### Is there any difference in transaction inclusion for Flashblocks vs. 2-second blocks? -### Is it possible for the sequencer to stop publishing flashblocks, if so what happens? +No significant differences—both order transactions by fee. The main difference is timing: Flashblocks occur every 200ms instead of every 2 seconds. See [Block Building](/base-chain/network-information/block-building#flashblocks) for details. -The sequencer will not stop publishing flashblocks, unless an extreme circumstance arises, that causes running flashblocks to be unsafe. If this happens, the preconfirmation is disabled across the network and confirmation falls back to 2s blocks. +### Can the sequencer stop publishing Flashblocks? -### Why is my tx having trouble getting included now? +The sequencer will not stop publishing Flashblocks unless an extreme circumstance makes running them unsafe. If this happens, preconfirmations are disabled network-wide and confirmations fall back to standard 2-second blocks. The sequencer continues operating normally. -It's possible that larger txs (> 15m gas limit) will have a harder time to land. This is due to how the builder allocates gas, it incrementally adds 1/10th of the total block gas limit to each flashblock. You can read more about it here (https://docs.base.org/base-chain/network-information/block-building#flashblocks). +### Why is my transaction having trouble getting included? -### How do I ensure my TX is in the first flashblock? +Transactions with large gas limits (> 14M gas) may have longer inclusion times. This is because the builder allocates gas incrementally—each Flashblock `j` can only use `j/10` of the total block gas limit. Large transactions must wait for later Flashblocks with sufficient capacity. -Unfortunately there's no way to guarantee which flashblock a transaction lands in, similar to how it cannot be guaranteed that a transaction lands in a specific block. To ensure quick inclusion, you may set a higher priority fee on your transaction. +See [Gas Allocation](/base-chain/flashblocks/overview#gas-allocation) for the full breakdown. -### How frequently do flashblocks reorg happen? +### How do I ensure my transaction is in the first Flashblock? -Flashblocks reorgs on Base Mainnet is currently effectively zero, with only rare exceptions. We are committed to maintaining a reorg rate below 0.01% going forward. You can check the latest metrics in the Flashblocks section at https://base.org/stats +There's no way to guarantee which Flashblock a transaction lands in, similar to how you can't guarantee a specific block. To improve chances of quick inclusion: -### What does it mean when a flashblock is reorged? +- Set a higher priority fee +- Keep gas limits below 14M (1/10 of block limit) to be eligible for Flashblock 1 -It means when a flashblock was streamed out as preconfirmation but it didn't end up getting included in that particular block. Currently applications building with flashblocks should have this expectation in mind but we are actively working on reducing reorgs to 0. +### How frequently do Flashblock reorgs happen? -## Flashblocks Websockets +Flashblock reorgs on Base Mainnet are effectively **zero**, with only rare exceptions. Base maintains a reorg rate below **0.01%**. Check current metrics at [base.org/stats](https://base.org/stats). -### Why are there 11 flashblocks? +### What does it mean when a Flashblock is reorged? -Index 0 only contains the system txs but doesn't use any gas limit, thus index 1-10 are the actual flashblocks that take pending txs from the txpool to build blocks. +A reorg means a Flashblock was streamed as a preconfirmation but wasn't included in the final block. This is rare due to architectural improvements in rollup-boost that prevent tail Flashblock reorgs. Apps should handle this possibility gracefully, but occurrences are minimal. -### Why sometimes there are less than 10 flashblocks? +--- + +## WebSocket + +### Why are there 11 Flashblocks? + +Index 0 contains only system transactions and doesn't use any gas limit. Indexes 1-10 are the actual Flashblocks that pull pending transactions from the txpool. -This is expected for now, it happens when the previous block takes too long to build the system then compensates by having less time to build the next block, resulting in less flashblocks. +### Why are there sometimes fewer than 10 Flashblocks? -### What encoding format is the data in transactions? +This is expected. When the previous block takes longer to build, the system compensates by allocating less time to the next block, resulting in fewer Flashblocks. -Those data are RLP encoded. +### What encoding format is the transaction data in? -### Why am I getting rate limited? +Transaction data is RLP encoded. -We currently set the maximum number of connections to our public websocket. We are aiming to have websocket supported on the RPC nodes soon, thus will soon encourage everyone to connect to the RPC for websocket stream rather than connecting to the websocket proxy directly. +### Why am I getting rate limited on the WebSocket? + +The public WebSocket has a maximum connection limit. For production use, we recommend: + +1. Running your own [Flashblocks-aware RPC node](/base-chain/flashblocks/node-providers) +2. Using a third-party node provider with Flashblocks support + +--- ## RPC ### Why am I getting rate limited using mainnet-preconf.base.org? -We set explicit rate limiting on the public endpoint. In order to not get rate limited, we strongly encourage utilizing third party node providers, most of which already support flashblocks aware RPCs on Base today. +The public endpoint has explicit rate limiting. For production use: + +- Use a third-party node provider with Flashblocks support (Alchemy, Infura, QuickNode, dRPC) +- Run your own [Flashblocks-aware RPC node](/base-chain/flashblocks/node-providers) + +### What RPC methods support Flashblocks? -### What RPC methods do you currently support that have flashblocks enabled? +The following methods are Flashblocks-enabled: -Currently the ones that have flashblocks enabled are: -- eth_getBlockByNumber (with pending tag) -- eth_getBalance (with pending tag) -- eth_getTransactionReceipt -- eth_getTransactionByHash (with pending tag) -- eth_getTransactionCount (with pending tag) -- eth_call (with pending tag) -- eth_simulateV1 (with pending tag) -- eth_estimateGas (with pending tag) -- eth_getLogs (with pending tag) +| Method | Usage | +|--------|-------| +| `eth_getBlockByNumber` | Use `pending` tag | +| `eth_getBalance` | Use `pending` tag | +| `eth_getTransactionReceipt` | Returns preconfirmed receipts | +| `eth_getTransactionByHash` | Use `pending` tag | +| `eth_getTransactionCount` | Use `pending` tag | +| `eth_call` | Use `pending` tag | +| `eth_simulateV1` | Use `pending` tag | +| `eth_estimateGas` | Use `pending` tag | +| `eth_getLogs` | Use `pending` for `toBlock` | + +See [App Integration](/base-chain/flashblocks/apps#rpc-api) for full examples. + +--- -## Node +## Node Setup -### How can I set up a RPC node that's flashblocks-aware? +### How do I set up a Flashblocks-aware RPC node? -In order to set up a node that's flashblocks-aware you must use the reth binary that we provide under https://github.com/base/node/tree/main/reth. \ No newline at end of file +Use the Reth binary from the [Base node repository](https://github.com/base/node/tree/main/reth). See the [Node Providers guide](/base-chain/flashblocks/node-providers) for complete setup instructions. \ No newline at end of file diff --git a/docs/base-chain/flashblocks/node-providers.mdx b/docs/base-chain/flashblocks/node-providers.mdx index 0e297752f..38b27739a 100644 --- a/docs/base-chain/flashblocks/node-providers.mdx +++ b/docs/base-chain/flashblocks/node-providers.mdx @@ -1,41 +1,68 @@ --- -title: How to host Flashblocks-aware RPC nodes +title: Run Flashblocks-aware RPC Nodes sidebarTitle: Node Providers +description: Host your own Flashblocks-aware RPC node to provide preconfirmation data to your applications with full control over rate limits and latency. --- +This guide covers how to run a Flashblocks-aware RPC node using node-reth, which converts streamed Flashblocks into familiar JSON-RPC methods. + + +For background on how Flashblocks work and the node-reth component, see the [Flashblocks Overview](/base-chain/flashblocks/overview#architecture). + + ## Quick Start -1. **Prerequisites**: - - Docker and Docker Compose - - Minimum hardware requirements (see [node README](https://github.com/base/node?tab=readme-ov-file#hardware-requirements)) - - Access to a Flashblocks websocket endpoint, we provide public endpoints in the env files in the repo +### Prerequisites + +- Docker and Docker Compose +- Minimum hardware requirements (see [node README](https://github.com/base/node?tab=readme-ov-file#hardware-requirements)) +- Access to a Flashblocks WebSocket endpoint (public endpoints provided in the repo) + +### Clone and Configure + +```sh +# Clone the repository +git clone https://github.com/base/node.git +cd node +``` + +### Start the Node + +```sh +NODE_TYPE=base CLIENT=reth RETH_FB_WEBSOCKET_URL="wss://mainnet.flashblocks.base.org/ws" docker-compose up +``` + + +The node-reth binary listens to the Flashblocks WebSocket stream and caches preconfirmation data. When Flashblocks-aware RPC methods are called, it returns data from this cache. + -2. **Set Up Environment**: +--- - ```sh - # Clone the repository - git clone https://github.com/base/node.git - cd node - ``` +## Configuration -3. **Start the Node with Flashblocks Support**: +| Variable | Description | Values | +|----------|-------------|--------| +| `NODE_TYPE` | Enables base reth node with Flashblocks | `base` | +| `CLIENT` | Execution client | `reth` | +| `NETWORK_ENV` | Network configuration file | `.env.mainnet` or `.env.sepolia` | +| `RETH_FB_WEBSOCKET_URL` | Flashblocks WebSocket endpoint | See below | - ```sh - NODE_TYPE=base CLIENT=reth RETH_FB_WEBSOCKET_URL="wss://mainnet.flashblocks.base.org/ws" docker-compose up - ``` +### WebSocket Endpoints -## Configuration Options +| Network | URL | +|---------|-----| +| Mainnet | `wss://mainnet.flashblocks.base.org/ws` | +| Sepolia | `wss://sepolia.flashblocks.base.org/ws` | -- Node Type: Use `NODE_TYPE=base` to enable base reth node with Flashblocks functionality -- Network: Use `NETWORK_ENV=.env.mainnet` for mainnet or `NETWORK_ENV=.env.sepolia` for testnet + +Public WebSocket endpoints are rate-limited. For production deployments with high traffic, consider connecting directly to your own WebSocket proxy or using infrastructure providers. + -Ensure the RETH_FB_WEBSOCKET_URL is set. Base offers the following public rate limited RPC's: -- For Mainnet: `RETH_FB_WEBSOCKET_URL=wss://mainnet.flashblocks.base.org/ws` -- For Sepolia: `RETH_FB_WEBSOCKET_URL=wss://sepolia.flashblocks.base.org/ws` +--- -## Verifying Flashblocks Functionality +## Verify Flashblocks Functionality -Test that your node is properly supporting Flashblocks by querying a pending block: +Test that your node is properly serving Flashblocks by querying a pending block: ```sh curl -X POST \ @@ -43,24 +70,48 @@ curl -X POST \ http://localhost:8545 ``` +A successful response will include block data from the latest Flashblock. If Flashblocks are temporarily unavailable, the node falls back to returning the latest finalized block. + ## Available RPC Methods -Flashblocks-aware nodes provide all standard Ethereum JSON-RPC methods plus specialized Flashblocks endpoints. For more details, see the [Flashblocks RPC API documentation](/base-chain/flashblocks/apps#rpc-api). +Your Flashblocks-aware node supports all standard Ethereum JSON-RPC methods, plus these Flashblocks-enabled endpoints: + +| Method | Flashblocks Usage | +|--------|------------------| +| `eth_getBlockByNumber` | Use `pending` tag | +| `eth_getBalance` | Use `pending` tag | +| `eth_getTransactionReceipt` | Returns preconfirmed receipts | +| `eth_getTransactionByHash` | Use `pending` tag | +| `eth_getTransactionCount` | Use `pending` tag | +| `eth_call` | Use `pending` tag | +| `eth_simulateV1` | Use `pending` tag | +| `eth_estimateGas` | Use `pending` tag | +| `eth_getLogs` | Use `pending` for `toBlock` | + +For code examples, see the [App Integration guide](/base-chain/flashblocks/apps#rpc-api). + +--- ## WebSocket API -The websocket API is intended to stream Flashblock data to nodes, so they can expose it via their RPC APIs. The endpoints are available at: +The WebSocket API streams Flashblock data directly to nodes, enabling them to expose preconfirmations via their RPC APIs. This is the low-latency backbone for traders and infrastructure providers. + +| Network | URL | +|---------|-----| +| Mainnet | `wss://mainnet.flashblocks.base.org/ws` | +| Sepolia | `wss://sepolia.flashblocks.base.org/ws` | - | Network | URL | - | :----------------- | :------------------------------------ | - | Mainnet | wss://mainnet.flashblocks.base.org/ws | - | Sepolia | wss://sepolia.flashblocks.base.org/ws | + +Applications should avoid hard dependencies on the WebSocket stream. RPCs provide stable behavior and automatic failover to regular blocks if Flashblocks are unavailable. + +### Data Format -#### Interpreting the data +To minimize bandwidth, each Flashblock only includes **diff data** from the previous Flashblock: -To minimize the amount of data sent to nodes, each Flashblock only includes the diff data from the previous block. The initial Flashblock (when index is zero) includes the block properties (e.g. number, gas limit) and the subsequent Flashblocks only include the diff data (e.g. transactions that are present in that Flashblock). +- **Index 0** (initial): Contains full block properties (number, gas limit, timestamp, etc.) plus the first diff +- **Index 1-10** (subsequent): Contains only diff data (new transactions, updated state root, gas used) **Example Initial Response** ``` @@ -139,7 +190,12 @@ To minimize the amount of data sent to nodes, each Flashblock only includes the } ``` +--- + ## Further Resources -For detailed information about node setup, including hardware requirements and additional configuration options, refer to the [Reth node README](https://github.com/base/node/tree/main/reth#readme). +- [Reth node README](https://github.com/base/node/tree/main/reth#readme) — Hardware requirements and configuration +- [Flashblocks Overview](/base-chain/flashblocks/overview) — Architecture and how the system works +- [App Integration](/base-chain/flashblocks/apps) — RPC examples and library integrations +- [Flashblocks Deep Dive](https://blog.base.dev/flashblocks-deep-dive) — Engineering blog with implementation details diff --git a/docs/base-chain/flashblocks/overview.mdx b/docs/base-chain/flashblocks/overview.mdx new file mode 100644 index 000000000..9791b3646 --- /dev/null +++ b/docs/base-chain/flashblocks/overview.mdx @@ -0,0 +1,173 @@ +--- +title: Flashblocks Overview +sidebarTitle: Overview +description: Understand the sequencer architecture, block building algorithm, and integration options for Flashblocks on Base. +--- + +## What are Flashblocks? + +Flashblocks reduce effective block times on Base from 2 seconds to just **200 milliseconds**, making transactions feel instant. Built in collaboration with [Flashbots](https://www.flashbots.net/), Flashblocks stream sub-blocks during each 2-second window, providing sub-second preconfirmations. + + +Flashblocks are always live on Base. All blocks are built by the Flashblocks builder. Apps can choose whether to consume preconfirmations or wait for standard 2-second block finality. + + +### Key Concepts + +| Term | Definition | +|------|------------| +| **Flashblock** | A 200ms sub-block containing a portion of the full block's transactions | +| **Preconfirmation** | An ultra-fast signal that a transaction will be included, before the full block is sealed | +| **Full Block** | A series of 10 Flashblocks combined to form the complete 2-second block | + +There are **10 Flashblocks per block**. Each Flashblock (`flashblock_i`) can contain up to `i/10` of the full block's total gas budget. The Flashblocks are combined to recreate the complete block. + +--- + +## Architecture + +### Before Flashblocks + +Base operates a high-availability sequencer system with five sequencer instances: + +| Component | Role | +|-----------|------| +| **op-node** | Standard OP Stack consensus layer (CL) | +| **op-geth** | Standard OP Stack execution layer (EL) | +| **op-conductor** | High availability controller with Raft consensus for leader election | + +One sequencer instance acts as the **leader**, responsible for building blocks and propagating them via P2P. The remaining four act as **followers** that sync the chain. Leadership transfers if the current leader stops producing blocks. + +### With Flashblocks + +Flashblocks introduce several new infrastructure components: + +| Component | Purpose | What It Unlocks | +|-----------|---------|-----------------| +| **rollup-boost** | CL↔EL Engine API proxy | Enables sharing Flashblocks with the EL without modifying the CL. Provides a stable seam for future block-building evolutions (multi-builder, etc.) | +| **op-rbuilder** | Out-of-protocol builder at 200ms cadence | Produces the sub-second Flashblocks, decoupled from the EL. Enables pluggable builder mechanisms | +| **websocket-proxy** | Flashblocks stream fan-out | Broadcast layer so many consumers can read the stream without overwhelming the builder | +| **node-reth** | RPC surface exposing preconfirmations | Converts streamed Flashblocks into familiar RPCs so apps and wallets can consume preconfirmation state | + +Both [rollup-boost](https://github.com/flashbots/rollup-boost) and [op-rbuilder](https://github.com/flashbots/op-rbuilder) are built and maintained by Flashbots, while Base maintains the websocket-proxy and node-reth components. + +--- + +## Transaction Lifecycle + +When you send a transaction to Base, here's what happens: + +### 1. Submission +``` +User → DNS (mainnet.base.org) → Load Balancer → Proxyd → Mempool +``` + +The transaction reaches the private mempool and is inserted into the txpool as pending. + +### 2. Distribution +The mempool maintains P2P connections with execution layers (op-geth, op-rbuilder), ensuring all pending transactions are synced for block building. + +### 3. Block Building +During each 200ms block building loop, op-rbuilder selects transactions based on: + +1. **Transaction fee** — transactions are ordered by fee (highest first) +2. **Gas limit and remaining capacity** — each Flashblock `j` can use up to `j/10` of the total block gas limit + +### 4. Block Building Algorithm + +The builder follows this process for each 2-second block: + +``` +FOR each flashblock j FROM 0 TO 10: + 1. Wait until next 200ms window + 2. Calculate available gas: (j / 10) × total_block_gas_limit + 3. Sort pending transactions by fee (descending) + 4. Select top transactions that fit within available gas + 5. Execute transactions and update state + 6. Stream flashblock to websocket-proxy +``` + + +**Index 0** contains only system transactions and doesn't use any gas limit. **Indexes 1-10** are the actual Flashblocks that pull pending transactions from the txpool. + + +### 5. Preconfirmation Delivery +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. + +--- + +## Gas Allocation + +Each Flashblock has an incrementally increasing gas budget: + +| Flashblock | Available Gas | +|------------|---------------| +| 1 | 1/10 of block limit (~14M gas) | +| 2 | 2/10 of block limit (~28M gas) | +| 3 | 3/10 of block limit (~42M gas) | +| ... | ... | +| 10 | Full block limit (~140M gas) | + +**Implications for large transactions:** +- Transactions with gas limits > 1/10 of block limit (currently ~14M gas) cannot fit in Flashblock 1 +- These transactions must wait for later Flashblocks with sufficient capacity +- If your app creates large transactions, monitor for changes in inclusion latency + +--- + +## Reliability + +### Reorg Rate + +Flashblocks reorgs on Base Mainnet are effectively **zero**. Base maintains a reorg rate below **0.01%**. + +A reorg means a Flashblock was streamed as a preconfirmation but wasn't included in the final block. This is rare due to architectural improvements where rollup-boost stores Flashblocks in a `best_payload` variable and only returns the final payload on `get_payload`, preventing tail Flashblock reorgs. + +Check current metrics at [base.org/stats](https://base.org/stats). + +### Builder Failover + +The op-conductor verifies builder health by checking if the builder remains synced with the tip of the chain. If a builder falls behind, leadership transfers automatically. This ensures high availability—Flashblocks won't experience extended outages due to unhealthy builders. + +### Fallback Behavior + +If an extreme circumstance makes running Flashblocks unsafe, preconfirmations are disabled network-wide and confirmation falls back to standard 2-second blocks. The sequencer continues operating normally. + +--- + +## Performance Characteristics + +| Metric | Value | +|--------|-------| +| Flashblock build time (P50) | ~10ms | +| Preconfirmation latency | ~200ms | +| Full block time | 2 seconds | +| Flashblocks per block | 10 | +| Reorg rate | < 0.01% | + +--- + +## Integration Paths + +Choose the integration method that fits your use case: + +| Use Case | Recommended Approach | Documentation | +|----------|---------------------|---------------| +| **Apps needing instant UX** | Flashblocks-aware RPC with `pending` tag | [App Integration](/base-chain/flashblocks/apps) | +| **Traders & low-latency apps** | WebSocket stream | [WebSocket API](/base-chain/flashblocks/node-providers#websocket-api) | +| **Infrastructure providers** | Host Flashblocks-aware RPC nodes | [Node Providers](/base-chain/flashblocks/node-providers) | +| **Standard apps** | Continue using regular RPCs | No changes needed | + + +Applications should avoid hard dependencies on the WebSocket stream. RPCs provide stable behavior and automatic failover to regular blocks if Flashblocks go down. + + +--- + +## Further Reading + +- [App Integration Guide](/base-chain/flashblocks/apps) — RPC methods, code examples, and library integrations +- [Node Provider Guide](/base-chain/flashblocks/node-providers) — Run your own Flashblocks-aware RPC node +- [FAQ](/base-chain/flashblocks/docs) — Common questions about Flashblocks +- [Block Building](/base-chain/network-information/block-building) — Detailed block ordering configuration +- [Flashblocks Deep Dive](https://blog.base.dev/flashblocks-deep-dive) — Engineering blog post with implementation details diff --git a/docs/base-chain/network-information/block-building.mdx b/docs/base-chain/network-information/block-building.mdx index df98d467e..b05db948e 100644 --- a/docs/base-chain/network-information/block-building.mdx +++ b/docs/base-chain/network-information/block-building.mdx @@ -21,24 +21,30 @@ See the [Configuration Changelog](/base-chain/network-information/configuration- ## Configurations ### Flashblocks -Currently, blocks are built using [op-rbuilder](https://github.com/flashbots/op-rbuilder) and priority fee auctions occur -every 200ms. There are two changes from the vanilla ordering to be aware of: -##### Timing +Blocks are built using [op-rbuilder](https://github.com/flashbots/op-rbuilder) with priority fee auctions occurring every **200ms**. This reduces effective block times from 2 seconds to 200 milliseconds through preconfirmations. -Flashblocks are built every 200ms, each ordering a portion of the block. Unlike the current system where later-arriving transactions with higher priority fees can be placed at the top of the block, Flashblocks creates a time-based constraint. Once a Flashblock is built and broadcast, its transaction ordering is locked even if a transaction with a higher priority fee arrives later, it cannot be included in earlier, already built Flashblocks. + +For a comprehensive technical deep dive into Flashblocks architecture, see the [Flashblocks Overview](/base-chain/flashblocks/overview). + -##### High Gas Limits +*There are two key differences from vanilla ordering:* -If your app creates transactions with large gas limits, we recommend monitoring to detect any changes in inclusion latency. Transactions with gas limits over 1/10 of the current block gas limit (currently 14 million gas), face additional constraints: +1. **Timing** — Flashblocks are built every 200ms, each ordering a portion of the block. Once built and broadcast, transaction ordering is locked. Later-arriving transactions with higher priority fees cannot be included in earlier Flashblocks. -* Each Flashblock can only use a portion of the block's total gas limit -* Flashblock 1: up to 1/10 of the total gas -* Flashblock 2: up to 2/10 of the total gas +2. **Gas Allocation** — Each Flashblock has an incrementally increasing gas budget. Flashblock 1 can use 1/10 of the block gas limit, Flashblock 2 can use 2/10, and so on until Flashblock 10 has access to the full limit. -And so on for subsequent Flashblocks + | Flashblock | Available Gas | + |------------|---------------| + | 1 | ~14M gas (1/10) | + | 2 | ~28M gas (2/10) | + | 3 | ~42M gas (3/10) | + | ... | ... | + | 10 | ~140M gas (full) | -Consequently, transactions with large gas requirements must wait for later Flashblocks with sufficient gas capacity. For example, a transaction exceeding 1/10 of the block's gas limit cannot be included in Flashblock 1 and must wait for Flashblock 2 or later. + + Transactions exceeding 14M gas cannot fit in Flashblock 1 and must wait for later Flashblocks. Monitor inclusion latency if your app creates large transactions. + ### Per-Transaction Gas Maximum diff --git a/docs/docs.json b/docs/docs.json index 1a189ef6c..a28c059b1 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -105,6 +105,7 @@ { "group": "Flashblocks", "pages": [ + "base-chain/flashblocks/overview", "base-chain/flashblocks/apps", "base-chain/flashblocks/node-providers", "base-chain/flashblocks/docs" From ac9d1a1cf88025958b6bc0fcca55afcd993eb7ed Mon Sep 17 00:00:00 2001 From: roethke Date: Wed, 21 Jan 2026 16:54:22 -0800 Subject: [PATCH 02/11] update content, add callout for subscriptions, remove ethers --- docs/base-chain/flashblocks/apps.mdx | 40 +++--------------------- docs/base-chain/flashblocks/overview.mdx | 4 ++- 2 files changed, 7 insertions(+), 37 deletions(-) diff --git a/docs/base-chain/flashblocks/apps.mdx b/docs/base-chain/flashblocks/apps.mdx index bdaa52afb..4cbbf4482 100644 --- a/docs/base-chain/flashblocks/apps.mdx +++ b/docs/base-chain/flashblocks/apps.mdx @@ -4,10 +4,6 @@ sidebarTitle: Apps description: Integrate Flashblocks into your app for 200ms transaction confirmations using RPC APIs and popular libraries like Wagmi and Viem. --- -## Overview - -Flashblocks enable **200 millisecond** transaction confirmations on Base through preconfirmations—ultra-fast signals that arrive before the full 2-second block is sealed. - New to Flashblocks? Start with the [Flashblocks Overview](/base-chain/flashblocks/overview) to understand the architecture and how transactions flow through the system. @@ -23,6 +19,10 @@ There are two ways to integrate with Flashblocks: For most apps, the RPC API is recommended. WebSocket is best for traders and infrastructure providers who need the absolute lowest latency. + +**Frontend developers using `eth_subscribe`**: With Flashblocks, subscriptions emit events every 200ms instead of every 2 seconds. If your UI performs heavy rendering on each event, consider throttling or debouncing updates to avoid jitter. + + ### RPC API Base offers the following public Flashblocks aware RPC endpoints. These are rate limited and may not be suitable for production use - we recommend using a node provider that runs Flashblocks integrated nodes. @@ -314,38 +314,6 @@ console.log(`Transaction included at: ${confirmTime.toISOString()}`); console.log(`Time difference: ${confirmTime - submissionTime}ms`); ``` -#### [Ethers](https://github.com/ethers-io/ethers.js) - -```jsx - const providerA = new ethers.JsonRpcProvider( - "https://sepolia-preconf.base.org" - ); - - const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, providerA); - - try { - // Create a simple transaction (sending 0.001 ETH to a random address) - const tx = { - to: "", - value: ethers.parseEther("0.0000001"), - }; - - // Submit transaction - const submissionTime = new Date(); - const transaction = await wallet.sendTransaction(tx); - - console.log(`Submitting transaction at: ${submissionTime.toISOString()}`); - console.log(`Transaction hash: ${transaction.hash}`); - - await transaction.wait(0); // Make sure to set the confirmation count to 0 - - console.log("Transaction confirmed"); - const confirmationTime = new Date(); - console.log(`Transaction confirmed at: ${confirmationTime.toISOString()}`); - console.log(`Time difference: ${confirmationTime - submissionTime}ms`); - } -``` - You should see the confirmation time significantly lower than the standard RPC endpoint. ## Support diff --git a/docs/base-chain/flashblocks/overview.mdx b/docs/base-chain/flashblocks/overview.mdx index 9791b3646..15dfeb029 100644 --- a/docs/base-chain/flashblocks/overview.mdx +++ b/docs/base-chain/flashblocks/overview.mdx @@ -6,7 +6,9 @@ description: Understand the sequencer architecture, block building algorithm, an ## What are Flashblocks? -Flashblocks reduce effective block times on Base from 2 seconds to just **200 milliseconds**, making transactions feel instant. Built in collaboration with [Flashbots](https://www.flashbots.net/), Flashblocks stream sub-blocks during each 2-second window, providing sub-second preconfirmations. +Flashblocks introduce **200ms** incremental state updates to Base, significantly reducing perceived latency for users. + +Built in collaboration with [Flashbots](https://www.flashbots.net/), this mechanism streams sub-blocks within the standard 2-second block interval, providing near-instant sequencer preconfirmations, allowing applications to reflect state changes long before the full block is gossiped to the rest of the network. Flashblocks are always live on Base. All blocks are built by the Flashblocks builder. Apps can choose whether to consume preconfirmations or wait for standard 2-second block finality. From d2f8b21863145cef1131fc1f9b4d1d785345c37a Mon Sep 17 00:00:00 2001 From: Jon Roethke Date: Mon, 26 Jan 2026 16:01:39 -0800 Subject: [PATCH 03/11] Update docs/base-chain/flashblocks/overview.mdx Co-authored-by: cody-wang-cb --- docs/base-chain/flashblocks/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/flashblocks/overview.mdx b/docs/base-chain/flashblocks/overview.mdx index 15dfeb029..b84df86ac 100644 --- a/docs/base-chain/flashblocks/overview.mdx +++ b/docs/base-chain/flashblocks/overview.mdx @@ -67,7 +67,7 @@ User → DNS (mainnet.base.org) → Load Balancer → Proxyd → Mempool The transaction reaches the private mempool and is inserted into the txpool as pending. ### 2. Distribution -The mempool maintains P2P connections with execution layers (op-geth, op-rbuilder), ensuring all pending transactions are synced for block building. +The mempool maintains P2P connections with execution layers (op-reth, op-rbuilder), ensuring all pending transactions are synced for block building. ### 3. Block Building During each 200ms block building loop, op-rbuilder selects transactions based on: From 842c18f271f49e32b484e96c080975bd7fdc21d1 Mon Sep 17 00:00:00 2001 From: Jon Roethke Date: Mon, 26 Jan 2026 16:02:06 -0800 Subject: [PATCH 04/11] Update docs/base-chain/flashblocks/overview.mdx Co-authored-by: cody-wang-cb --- docs/base-chain/flashblocks/overview.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/base-chain/flashblocks/overview.mdx b/docs/base-chain/flashblocks/overview.mdx index b84df86ac..e75e6301b 100644 --- a/docs/base-chain/flashblocks/overview.mdx +++ b/docs/base-chain/flashblocks/overview.mdx @@ -111,8 +111,8 @@ Each Flashblock has an incrementally increasing gas budget: | 10 | Full block limit (~140M gas) | **Implications for large transactions:** -- Transactions with gas limits > 1/10 of block limit (currently ~14M gas) cannot fit in Flashblock 1 -- These transactions must wait for later Flashblocks with sufficient capacity +- Transactions with gas limits > 1/10 of block limit (currently ~18.75M gas) will never fit in a Flashblock +- It's more common for larger transaction to wait until later Flashblocks with sufficient capacity - If your app creates large transactions, monitor for changes in inclusion latency --- From 20ba27fb6b23ac7ca7dc762599bae4d7e964173e Mon Sep 17 00:00:00 2001 From: roethke Date: Mon, 26 Jan 2026 16:05:21 -0800 Subject: [PATCH 05/11] update gas numbers for greater exactness --- docs/base-chain/flashblocks/overview.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/base-chain/flashblocks/overview.mdx b/docs/base-chain/flashblocks/overview.mdx index e75e6301b..4ee68e968 100644 --- a/docs/base-chain/flashblocks/overview.mdx +++ b/docs/base-chain/flashblocks/overview.mdx @@ -104,11 +104,11 @@ Each Flashblock has an incrementally increasing gas budget: | Flashblock | Available Gas | |------------|---------------| -| 1 | 1/10 of block limit (~14M gas) | -| 2 | 2/10 of block limit (~28M gas) | -| 3 | 3/10 of block limit (~42M gas) | +| 1 | 1/10 of block limit (~18.75M gas) | +| 2 | 2/10 of block limit (~37.5M gas) | +| 3 | 3/10 of block limit (~56.25M gas) | | ... | ... | -| 10 | Full block limit (~140M gas) | +| 10 | Full block limit (~187.5M gas) | **Implications for large transactions:** - Transactions with gas limits > 1/10 of block limit (currently ~18.75M gas) will never fit in a Flashblock From cbfb0dc4cc6abaf6b5a91ed75652b3a687137fd6 Mon Sep 17 00:00:00 2001 From: roethke Date: Mon, 9 Feb 2026 13:13:08 -0800 Subject: [PATCH 06/11] add architecture section, rpc methods, alphabetize sidebar --- docs/base-chain/flashblocks/architecture.mdx | 38 +++++++++++++++++++ .../base-chain/flashblocks/node-providers.mdx | 8 ++-- docs/base-chain/flashblocks/overview.mdx | 25 +----------- docs/docs.json | 5 ++- 4 files changed, 47 insertions(+), 29 deletions(-) create mode 100644 docs/base-chain/flashblocks/architecture.mdx diff --git a/docs/base-chain/flashblocks/architecture.mdx b/docs/base-chain/flashblocks/architecture.mdx new file mode 100644 index 000000000..bcacef8cd --- /dev/null +++ b/docs/base-chain/flashblocks/architecture.mdx @@ -0,0 +1,38 @@ +--- +title: Flashblocks Architecture +sidebarTitle: Architecture +description: Understand the sequencer architecture and infrastructure components that power Flashblocks on Base. +--- + +## Before Flashblocks + +Base operates a high-availability sequencer system with five sequencer instances: + +| Component | Role | +|-----------|------| +| **op-node** | Standard OP Stack consensus layer (CL) | +| **op-geth** | Standard OP Stack execution layer (EL) | +| **op-conductor** | High availability controller with Raft consensus for leader election | + +One sequencer instance acts as the **leader**, responsible for building blocks and propagating them via P2P. The remaining four act as **followers** that sync the chain. Leadership transfers if the current leader stops producing blocks. + +## With Flashblocks + +Flashblocks introduce several new infrastructure components: + +| Component | Purpose | What It Unlocks | +|-----------|---------|-----------------| +| **rollup-boost** | CL↔EL Engine API proxy | Enables sharing Flashblocks with the EL without modifying the CL. Provides a stable seam for future block-building evolutions (multi-builder, etc.) | +| **op-rbuilder** | Out-of-protocol builder at 200ms cadence | Produces the sub-second Flashblocks, decoupled from the EL. Enables pluggable builder mechanisms | +| **websocket-proxy** | Flashblocks stream fan-out | Broadcast layer so many consumers can read the stream without overwhelming the builder | +| **[base](https://github.com/base/base)** | RPC surface exposing preconfirmations | Converts streamed Flashblocks into familiar RPCs so apps and wallets can consume preconfirmation state | + +Both [rollup-boost](https://github.com/flashbots/rollup-boost) and [op-rbuilder](https://github.com/flashbots/op-rbuilder) are built and maintained by Flashbots, while Base maintains the websocket-proxy and [base](https://github.com/base/base) components. + +--- + +## Further Reading + +- [Flashblocks Overview](/base-chain/flashblocks/overview) — Key concepts and transaction lifecycle +- [Node Provider Guide](/base-chain/flashblocks/node-providers) — Run your own Flashblocks-aware RPC node +- [Flashblocks Deep Dive](https://blog.base.dev/flashblocks-deep-dive) — Engineering blog post with implementation details diff --git a/docs/base-chain/flashblocks/node-providers.mdx b/docs/base-chain/flashblocks/node-providers.mdx index 38b27739a..2afb83687 100644 --- a/docs/base-chain/flashblocks/node-providers.mdx +++ b/docs/base-chain/flashblocks/node-providers.mdx @@ -4,10 +4,10 @@ sidebarTitle: Node Providers description: Host your own Flashblocks-aware RPC node to provide preconfirmation data to your applications with full control over rate limits and latency. --- -This guide covers how to run a Flashblocks-aware RPC node using node-reth, which converts streamed Flashblocks into familiar JSON-RPC methods. +This guide covers how to run a Flashblocks-aware RPC node using [base](https://github.com/base/base), which converts streamed Flashblocks into familiar JSON-RPC methods. -For background on how Flashblocks work and the node-reth component, see the [Flashblocks Overview](/base-chain/flashblocks/overview#architecture). +For background on how Flashblocks work and the [base](https://github.com/base/base) component, see the [Flashblocks Architecture](/base-chain/flashblocks/architecture). ## Quick Start @@ -33,7 +33,7 @@ NODE_TYPE=base CLIENT=reth RETH_FB_WEBSOCKET_URL="wss://mainnet.flashblocks.base ``` -The node-reth binary listens to the Flashblocks WebSocket stream and caches preconfirmation data. When Flashblocks-aware RPC methods are called, it returns data from this cache. +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. --- @@ -87,6 +87,8 @@ Your Flashblocks-aware node supports all standard Ethereum JSON-RPC methods, plu | `eth_simulateV1` | Use `pending` tag | | `eth_estimateGas` | Use `pending` tag | | `eth_getLogs` | Use `pending` for `toBlock` | +| `eth_subscribe` | Stream Flashblock data in real-time (Beta) | +| `base_transactionStatus` | Check if transaction is in mempool (Beta) | For code examples, see the [App Integration guide](/base-chain/flashblocks/apps#rpc-api). diff --git a/docs/base-chain/flashblocks/overview.mdx b/docs/base-chain/flashblocks/overview.mdx index 4ee68e968..a6c730a52 100644 --- a/docs/base-chain/flashblocks/overview.mdx +++ b/docs/base-chain/flashblocks/overview.mdx @@ -28,30 +28,7 @@ There are **10 Flashblocks per block**. Each Flashblock (`flashblock_i`) can con ## Architecture -### Before Flashblocks - -Base operates a high-availability sequencer system with five sequencer instances: - -| Component | Role | -|-----------|------| -| **op-node** | Standard OP Stack consensus layer (CL) | -| **op-geth** | Standard OP Stack execution layer (EL) | -| **op-conductor** | High availability controller with Raft consensus for leader election | - -One sequencer instance acts as the **leader**, responsible for building blocks and propagating them via P2P. The remaining four act as **followers** that sync the chain. Leadership transfers if the current leader stops producing blocks. - -### With Flashblocks - -Flashblocks introduce several new infrastructure components: - -| Component | Purpose | What It Unlocks | -|-----------|---------|-----------------| -| **rollup-boost** | CL↔EL Engine API proxy | Enables sharing Flashblocks with the EL without modifying the CL. Provides a stable seam for future block-building evolutions (multi-builder, etc.) | -| **op-rbuilder** | Out-of-protocol builder at 200ms cadence | Produces the sub-second Flashblocks, decoupled from the EL. Enables pluggable builder mechanisms | -| **websocket-proxy** | Flashblocks stream fan-out | Broadcast layer so many consumers can read the stream without overwhelming the builder | -| **node-reth** | RPC surface exposing preconfirmations | Converts streamed Flashblocks into familiar RPCs so apps and wallets can consume preconfirmation state | - -Both [rollup-boost](https://github.com/flashbots/rollup-boost) and [op-rbuilder](https://github.com/flashbots/op-rbuilder) are built and maintained by Flashbots, while Base maintains the websocket-proxy and node-reth components. +For details on the sequencer system and Flashblocks infrastructure components (rollup-boost, op-rbuilder, websocket-proxy, and base), see the [Architecture](/base-chain/flashblocks/architecture) page. --- diff --git a/docs/docs.json b/docs/docs.json index 744206d3c..2764b0a42 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -105,10 +105,11 @@ { "group": "Flashblocks", "pages": [ - "base-chain/flashblocks/overview", "base-chain/flashblocks/apps", + "base-chain/flashblocks/architecture", + "base-chain/flashblocks/docs", "base-chain/flashblocks/node-providers", - "base-chain/flashblocks/docs" + "base-chain/flashblocks/overview" ] }, { From 0f05fbc5f97fd30a7cee430e10b217e6630a6bab Mon Sep 17 00:00:00 2001 From: roethke Date: Mon, 9 Feb 2026 16:43:23 -0800 Subject: [PATCH 07/11] refactor for clarity, readability, add object references, rename files --- docs/base-chain/flashblocks/apps.mdx | 251 +++++++++- docs/base-chain/flashblocks/architecture.mdx | 3 +- .../flashblocks/{docs.mdx => faq.mdx} | 24 +- .../base-chain/flashblocks/node-providers.mdx | 203 -------- docs/base-chain/flashblocks/overview.mdx | 43 +- .../flashblocks/websocket-reference.mdx | 438 ++++++++++++++++++ .../network-information/network-fees.mdx | 4 +- .../node-operators/run-a-base-node.mdx | 70 ++- docs/docs.json | 34 +- 9 files changed, 812 insertions(+), 258 deletions(-) rename docs/base-chain/flashblocks/{docs.mdx => faq.mdx} (71%) delete mode 100644 docs/base-chain/flashblocks/node-providers.mdx create mode 100644 docs/base-chain/flashblocks/websocket-reference.mdx diff --git a/docs/base-chain/flashblocks/apps.mdx b/docs/base-chain/flashblocks/apps.mdx index 4cbbf4482..dde1aa6ee 100644 --- a/docs/base-chain/flashblocks/apps.mdx +++ b/docs/base-chain/flashblocks/apps.mdx @@ -1,40 +1,79 @@ --- -title: App Integration +title: Flashblocks Integration sidebarTitle: Apps -description: Integrate Flashblocks into your app for 200ms transaction confirmations using RPC APIs and popular libraries like Wagmi and Viem. +description: Integrate Flashblocks into your app for 200ms transaction confirmations using RPC APIs and popular libraries like Ethers, Wagmi and Viem. --- - -New to Flashblocks? Start with the [Flashblocks Overview](/base-chain/flashblocks/overview) to understand the architecture and how transactions flow through the system. - +Get **200ms transaction confirmations** on Base—10x faster than the standard 2-second block time. -## Integration Methods +## Endpoints -There are two ways to integrate with Flashblocks: - -1. **RPC API** — Query Flashblocks-aware endpoints using familiar JSON-RPC methods with the `pending` tag -2. **WebSocket API** — Stream real-time Flashblock data for lowest latency (see [Node Providers](/base-chain/flashblocks/node-providers#websocket-api)) +| Network | RPC URL | Status | +|---------|---------|--------| +| **Mainnet** | `https://mainnet-preconf.base.org` | ✅ Live | +| **Sepolia** | `https://sepolia-preconf.base.org` | ✅ Live | -For most apps, the RPC API is recommended. WebSocket is best for traders and infrastructure providers who need the absolute lowest latency. +**Already using a node provider?** Alchemy, Infura, QuickNode, and dRPC all support Flashblocks—just use the `pending` tag with your existing endpoint. - -**Frontend developers using `eth_subscribe`**: With Flashblocks, subscriptions emit events every 200ms instead of every 2 seconds. If your UI performs heavy rendering on each event, consider throttling or debouncing updates to avoid jitter. - + +Public endpoints are rate-limited. For production, use a [node provider with Flashblocks support](/base-chain/tools/node-providers) or [run your own node](/base-chain/node-operators/run-a-base-node#enable-flashblocks). + + +--- + +## Quick Start + +Use the `pending` tag with any supported RPC method: + +```bash +curl https://mainnet-preconf.base.org -X POST \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending",false],"id":1}' +``` + +That's it—your app now receives 200ms preconfirmations instead of waiting 2 seconds. + +--- + +## Use Cases -### RPC API +Flashblocks is ideal for: -Base offers the following public Flashblocks aware RPC endpoints. These are rate limited and may not be suitable for production use - we recommend using a node provider that runs Flashblocks integrated nodes. -Major node providers such as Alchemy, Infura, QuickNode and dRPC have Flashblocks-aware RPCs that can be leveraged +- **Decentralized exchanges** — Near-instant trade confirmations +- **Onchain games** — Real-time state updates for responsive gameplay +- **Trading bots** — Faster feedback loops for automated strategies +- **Live dashboards** — Real-time balance and transaction monitoring +- **Any app requiring instant feedback** — Improved UX across the board - | Network | URL | - | :----------------- | :------------------------------- | - | Mainnet | https://mainnet-preconf.base.org | - | Sepolia | https://sepolia-preconf.base.org | +--- +## Supported RPC Methods + +| Method | Description | +|--------|-------------| +| `eth_getBlockByNumber` | With `pending`, returns the most recent Flashblock | +| `eth_getBalance` | With `pending`, reflects balances from the latest Flashblock | +| `eth_getTransactionReceipt` | Returns receipts for preconfirmed transactions | +| `eth_getTransactionByHash` | Returns preconfirmed transaction details | +| `eth_getTransactionCount` | With `pending`, returns the updated nonce from Flashblocks | +| `eth_call` | With `pending`, executes against the latest Flashblock state | +| `eth_estimateGas` | With `pending`, estimates gas against the latest Flashblock | +| `eth_getLogs` | With `pending`, returns logs from the latest Flashblock | +| `eth_simulateV1` | Simulates transactions against the latest Flashblock state | +| `eth_subscribe` | Stream Flashblock data in real-time (Beta) | +| `base_transactionStatus` | Check if a transaction is in the mempool (Beta) | -The following RPC methods can return Flashblocks specific data. All standard Ethereum JSON-RPC methods are still supported as usual. + +**WebSocket Note:** Do not connect directly to `wss://mainnet.flashblocks.base.org/ws`. This endpoint is reserved for infrastructure-to-node data syncing. For real-time streaming, use `eth_subscribe` via your RPC node or node provider's WebSocket. + + +--- + +## RPC API Reference + +Detailed documentation for each Flashblocks-enabled RPC method. #### eth_getBlockByNumber @@ -211,6 +250,142 @@ curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json } ``` +#### eth_subscribe Beta + +Flashblocks-aware nodes support specialized `eth_subscribe` methods for real-time streaming of Flashblock data. + +Requires [base/base](https://github.com/base/base) minimum client version v0.3.1 + + +**Connect to your RPC node or node provider's WebSocket**, not the raw Flashblocks stream (`wss://mainnet.flashblocks.base.org/ws`). The raw stream is reserved for infrastructure-to-node syncing. + + + +Each subscription returns **one item per WebSocket message** and emits events every 200ms. If your application performs heavy processing on each event, consider throttling or debouncing to avoid performance issues. + + +**Subscription Types:** + +| Subscription | Description | Response | +|--------------|-------------|----------| +| `newFlashblockTransactions` | Stream transactions as they're included | One transaction per message | +| `pendingLogs` | Stream [logs](/base-chain/flashblocks/websocket-reference#log-object) matching a filter | One log per message | +| `newFlashblocks` | Stream [Flashblock](/base-chain/flashblocks/websocket-reference#flashblock-object) state updates | Full Flashblock per message | + + +For detailed response schema documentation (Flashblock, Diff, Metadata, Receipt, Log objects), see the [WebSocket Reference](/base-chain/flashblocks/websocket-reference#schema). + + +--- + +**newFlashblockTransactions** + +```json +{"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions"]} +``` + +Optional `full` parameter for enriched transaction and log data: +```json +{"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions", {"full": true}]} +``` + +--- + +**pendingLogs** + +Filter logs by address and topics: +```json +{"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["pendingLogs", {"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}]} +``` + +--- + +**newFlashblocks** + +```json +{"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblocks"]} +``` + +--- + +**JavaScript Example:** + +```javascript +import WebSocket from 'ws'; +import { createHash } from 'crypto'; + +// `ws` should be a WebSocket RPC URL, not from the Flashblock WebSocket Stream +const ws = new WebSocket('wss://my-node.node-provider.com/ws'); + +ws.on('open', () => { + console.log('Connected to Flashblocks WebSocket'); + // Subscribe to new Flashblocks + ws.send(JSON.stringify({ + jsonrpc: "2.0", + method: "eth_subscribe", + params: ["newFlashblockTransactions"], + id: 1 + })); +}); + +ws.on('message', (data: WebSocket.Data) => { + try { + if (Buffer.isBuffer(data)) { + if (data.length >= 37) { + const txHash = '0x' + data.slice(5, 37).toString('hex'); + console.log(txHash); + } + } else { + const response = JSON.parse(data.toString()); + if (response.id === 1) { + console.log('✓ Subscribed'); + } + } + } catch (error) { + // Handle error + } +}); + +ws.on('error', (error) => { + console.error('WebSocket error:', error); +}); + +ws.on('close', () => { + console.log('WebSocket connection closed'); +}); +``` + +#### base_transactionStatus Beta + +Check whether a transaction is present in the mempool: + +Requires [base/base](https://github.com/base/base) minimum client version v0.3.0 +``` +curl https://sepolia-preconf.base.org -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"base_transactionStatus","params":["0x..."],"id":1}' +``` + +**Transaction Known** +``` +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "status": "Known" + } +} +``` + +**Transaction Unknown** +``` +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "status": "Unknown" + } +} +``` + ### Libraries You will need to use a Flashblocks-aware RPC endpoint to use Flashblocks with the following libraries: @@ -314,6 +489,38 @@ console.log(`Transaction included at: ${confirmTime.toISOString()}`); console.log(`Time difference: ${confirmTime - submissionTime}ms`); ``` +#### [Ethers](https://github.com/ethers-io/ethers.js) + +```jsx + const providerA = new ethers.JsonRpcProvider( + "https://sepolia-preconf.base.org" + ); + + const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, providerA); + + try { + // Create a simple transaction (sending 0.001 ETH to a random address) + const tx = { + to: "", + value: ethers.parseEther("0.0000001"), + }; + + // Submit transaction + const submissionTime = new Date(); + const transaction = await wallet.sendTransaction(tx); + + console.log(`Submitting transaction at: ${submissionTime.toISOString()}`); + console.log(`Transaction hash: ${transaction.hash}`); + + await transaction.wait(0); // Make sure to set the confirmation count to 0 + + console.log("Transaction confirmed"); + const confirmationTime = new Date(); + console.log(`Transaction confirmed at: ${confirmationTime.toISOString()}`); + console.log(`Time difference: ${confirmationTime - submissionTime}ms`); + } +``` + You should see the confirmation time significantly lower than the standard RPC endpoint. ## Support diff --git a/docs/base-chain/flashblocks/architecture.mdx b/docs/base-chain/flashblocks/architecture.mdx index bcacef8cd..da113d605 100644 --- a/docs/base-chain/flashblocks/architecture.mdx +++ b/docs/base-chain/flashblocks/architecture.mdx @@ -34,5 +34,6 @@ Both [rollup-boost](https://github.com/flashbots/rollup-boost) and [op-rbuilder] ## Further Reading - [Flashblocks Overview](/base-chain/flashblocks/overview) — Key concepts and transaction lifecycle -- [Node Provider Guide](/base-chain/flashblocks/node-providers) — Run your own Flashblocks-aware RPC node +- [Enable Flashblocks](/base-chain/node-operators/run-a-base-node#enable-flashblocks) — Run your own Flashblocks-aware RPC node +- [WebSocket Reference](/base-chain/flashblocks/websocket-reference) — Technical reference for infrastructure-to-node data syncing - [Flashblocks Deep Dive](https://blog.base.dev/flashblocks-deep-dive) — Engineering blog post with implementation details diff --git a/docs/base-chain/flashblocks/docs.mdx b/docs/base-chain/flashblocks/faq.mdx similarity index 71% rename from docs/base-chain/flashblocks/docs.mdx rename to docs/base-chain/flashblocks/faq.mdx index c15930186..0d70f6651 100644 --- a/docs/base-chain/flashblocks/docs.mdx +++ b/docs/base-chain/flashblocks/faq.mdx @@ -37,7 +37,7 @@ There's no way to guarantee which Flashblock a transaction lands in, similar to ### How frequently do Flashblock reorgs happen? -Flashblock reorgs on Base Mainnet are effectively **zero**, with only rare exceptions. Base maintains a reorg rate below **0.01%**. Check current metrics at [base.org/stats](https://base.org/stats). +Base targets a Flashblock reorg rate SLO of **99.9%** (< 0.1% reorgs). While reorgs are rare, applications should implement fallback logic for critical operations. Check current metrics at [base.org/stats](https://base.org/stats). ### What does it mean when a Flashblock is reorged? @@ -47,6 +47,16 @@ A reorg means a Flashblock was streamed as a preconfirmation but wasn't included ## WebSocket +### Can I connect directly to the Flashblocks WebSocket stream? + +**No.** The raw Flashblocks WebSocket (`wss://mainnet.flashblocks.base.org/ws`) is reserved for infrastructure-to-node data syncing. Applications should not connect to it directly. + +Instead, query your RPC node or node provider (e.g., QuickNode, Alchemy, Infura, dRPC) for Flashblocks data via: +- **RPC API**: Standard JSON-RPC methods with the `pending` tag +- **WebSocket subscriptions**: Use `eth_subscribe` via your node provider's WebSocket endpoint + +See [App Integration](/base-chain/flashblocks/apps) for implementation details. + ### Why are there 11 Flashblocks? Index 0 contains only system transactions and doesn't use any gas limit. Indexes 1-10 are the actual Flashblocks that pull pending transactions from the txpool. @@ -57,13 +67,13 @@ This is expected. When the previous block takes longer to build, the system comp ### What encoding format is the transaction data in? -Transaction data is RLP encoded. +Transaction data in the [`diff.transactions`](/base-chain/flashblocks/websocket-reference#diff-object) array is Recursive Length Prefix (RLP) encoded. ### Why am I getting rate limited on the WebSocket? The public WebSocket has a maximum connection limit. For production use, we recommend: -1. Running your own [Flashblocks-aware RPC node](/base-chain/flashblocks/node-providers) +1. Running your own [Flashblocks-aware RPC node](/base-chain/node-operators/run-a-base-node#enable-flashblocks) 2. Using a third-party node provider with Flashblocks support --- @@ -75,7 +85,7 @@ The public WebSocket has a maximum connection limit. For production use, we reco The public endpoint has explicit rate limiting. For production use: - Use a third-party node provider with Flashblocks support (Alchemy, Infura, QuickNode, dRPC) -- Run your own [Flashblocks-aware RPC node](/base-chain/flashblocks/node-providers) +- Run your own [Flashblocks-aware RPC node](/base-chain/node-operators/run-a-base-node#enable-flashblocks) ### What RPC methods support Flashblocks? @@ -92,8 +102,10 @@ The following methods are Flashblocks-enabled: | `eth_simulateV1` | Use `pending` tag | | `eth_estimateGas` | Use `pending` tag | | `eth_getLogs` | Use `pending` for `toBlock` | +| `eth_subscribe` | Stream Flashblock data in real-time (Beta) | +| `base_transactionStatus` | Check if transaction is in mempool (Beta) | -See [App Integration](/base-chain/flashblocks/apps#rpc-api) for full examples. +See [App Integration](/base-chain/flashblocks/apps#rpc-api-reference) for full examples. --- @@ -101,4 +113,4 @@ See [App Integration](/base-chain/flashblocks/apps#rpc-api) for full examples. ### How do I set up a Flashblocks-aware RPC node? -Use the Reth binary from the [Base node repository](https://github.com/base/node/tree/main/reth). See the [Node Providers guide](/base-chain/flashblocks/node-providers) for complete setup instructions. \ No newline at end of file +Use the Reth binary from the [Base node repository](https://github.com/base/node/tree/main/reth). See the [Enable Flashblocks guide](/base-chain/node-operators/run-a-base-node#enable-flashblocks) for complete setup instructions. \ No newline at end of file diff --git a/docs/base-chain/flashblocks/node-providers.mdx b/docs/base-chain/flashblocks/node-providers.mdx deleted file mode 100644 index 2afb83687..000000000 --- a/docs/base-chain/flashblocks/node-providers.mdx +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: Run Flashblocks-aware RPC Nodes -sidebarTitle: Node Providers -description: Host your own Flashblocks-aware RPC node to provide preconfirmation data to your applications with full control over rate limits and latency. ---- - -This guide covers how to run a Flashblocks-aware RPC node using [base](https://github.com/base/base), which converts streamed Flashblocks into familiar JSON-RPC methods. - - -For background on how Flashblocks work and the [base](https://github.com/base/base) component, see the [Flashblocks Architecture](/base-chain/flashblocks/architecture). - - -## Quick Start - -### Prerequisites - -- Docker and Docker Compose -- Minimum hardware requirements (see [node README](https://github.com/base/node?tab=readme-ov-file#hardware-requirements)) -- Access to a Flashblocks WebSocket endpoint (public endpoints provided in the repo) - -### Clone and Configure - -```sh -# Clone the repository -git clone https://github.com/base/node.git -cd node -``` - -### Start the Node - -```sh -NODE_TYPE=base CLIENT=reth RETH_FB_WEBSOCKET_URL="wss://mainnet.flashblocks.base.org/ws" docker-compose up -``` - - -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. - - ---- - -## Configuration - -| Variable | Description | Values | -|----------|-------------|--------| -| `NODE_TYPE` | Enables base reth node with Flashblocks | `base` | -| `CLIENT` | Execution client | `reth` | -| `NETWORK_ENV` | Network configuration file | `.env.mainnet` or `.env.sepolia` | -| `RETH_FB_WEBSOCKET_URL` | Flashblocks WebSocket endpoint | See below | - -### WebSocket Endpoints - -| Network | URL | -|---------|-----| -| Mainnet | `wss://mainnet.flashblocks.base.org/ws` | -| Sepolia | `wss://sepolia.flashblocks.base.org/ws` | - - -Public WebSocket endpoints are rate-limited. For production deployments with high traffic, consider connecting directly to your own WebSocket proxy or using infrastructure providers. - - ---- - -## Verify Flashblocks Functionality - -Test that your node is properly serving Flashblocks by querying a pending block: - -```sh -curl -X POST \ - --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending", false],"id":1}' \ - http://localhost:8545 -``` - -A successful response will include block data from the latest Flashblock. If Flashblocks are temporarily unavailable, the node falls back to returning the latest finalized block. - -## Available RPC Methods - -Your Flashblocks-aware node supports all standard Ethereum JSON-RPC methods, plus these Flashblocks-enabled endpoints: - -| Method | Flashblocks Usage | -|--------|------------------| -| `eth_getBlockByNumber` | Use `pending` tag | -| `eth_getBalance` | Use `pending` tag | -| `eth_getTransactionReceipt` | Returns preconfirmed receipts | -| `eth_getTransactionByHash` | Use `pending` tag | -| `eth_getTransactionCount` | Use `pending` tag | -| `eth_call` | Use `pending` tag | -| `eth_simulateV1` | Use `pending` tag | -| `eth_estimateGas` | Use `pending` tag | -| `eth_getLogs` | Use `pending` for `toBlock` | -| `eth_subscribe` | Stream Flashblock data in real-time (Beta) | -| `base_transactionStatus` | Check if transaction is in mempool (Beta) | - -For code examples, see the [App Integration guide](/base-chain/flashblocks/apps#rpc-api). - ---- - - -## WebSocket API - -The WebSocket API streams Flashblock data directly to nodes, enabling them to expose preconfirmations via their RPC APIs. This is the low-latency backbone for traders and infrastructure providers. - -| Network | URL | -|---------|-----| -| Mainnet | `wss://mainnet.flashblocks.base.org/ws` | -| Sepolia | `wss://sepolia.flashblocks.base.org/ws` | - - -Applications should avoid hard dependencies on the WebSocket stream. RPCs provide stable behavior and automatic failover to regular blocks if Flashblocks are unavailable. - - -### Data Format - -To minimize bandwidth, each Flashblock only includes **diff data** from the previous Flashblock: - -- **Index 0** (initial): Contains full block properties (number, gas limit, timestamp, etc.) plus the first diff -- **Index 1-10** (subsequent): Contains only diff data (new transactions, updated state root, gas used) - -**Example Initial Response** -``` -{ - "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" - // ... other base fields ... - }, - "diff": { - "state_root": "0x208fd63edc0681161105f27d03daf9f8c726d8c94e584a3c0696c98291c24333", - "block_hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8", - "gas_used": "0xab3f", - "transactions": [ - "0x7ef8f8a0b4afc0b7ce10e150801bbaf08ac33fecb0f38311793abccb022120d321c6d276..." - ], - "withdrawals": [] - // ... other diff fields ... - }, - "metadata": { - "block_number": 22585577, - "new_account_balances": { - "0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0", - // ... other balances ... - }, - "receipts": { - "0x07d7f06b06fea714c1d1d446efa2790c6970aa74ee006186a32b5b7dd8ca2d82": { - "Deposit": { - "status": "0x1", - "depositNonce": "0x158a0ea" - // ... other receipt fields ... - } - } - } - } -} -``` - -**Example Diff Response** -``` -{ - "payload_id": "0x03e303378749418d", - "index": 4, - "diff": { - "state_root": "0x7a8f45038665072f382730e689f4a1561835c9987fca8942fa95872fb9367eaa", - "block_hash": "0x9b32f7a14cbd1efc8c2c5cad5eb718ec9e0c5da92c3ba7080f8d4c49d660c332", - "gas_used": "0x1234f", - "transactions": [ - "0x7ef8f8a0b4afc0b7ce10e150801bbaf08ac33fecb0f38311793abccb022120d321c6d276..." - ], - "withdrawals": [] - // ... other diff fields ... - }, - "metadata": { - "block_number": 22585577, - "new_account_balances": { - "0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0", - "0x4200000000000000000000000000000000000015": "0x1234" - // ... other balances ... - }, - "receipts": { - "0x07d7f06b06fea714c1d1d446efa2790c6970aa74ee006186a32b5b7dd8ca2d82": { - "status": "0x1", - "gasUsed": "0x1234f", - "logs": [] - // ... other receipt fields ... - } - } - } -} -``` - ---- - -## Further Resources - -- [Reth node README](https://github.com/base/node/tree/main/reth#readme) — Hardware requirements and configuration -- [Flashblocks Overview](/base-chain/flashblocks/overview) — Architecture and how the system works -- [App Integration](/base-chain/flashblocks/apps) — RPC examples and library integrations -- [Flashblocks Deep Dive](https://blog.base.dev/flashblocks-deep-dive) — Engineering blog with implementation details - diff --git a/docs/base-chain/flashblocks/overview.mdx b/docs/base-chain/flashblocks/overview.mdx index a6c730a52..534f9e217 100644 --- a/docs/base-chain/flashblocks/overview.mdx +++ b/docs/base-chain/flashblocks/overview.mdx @@ -22,16 +22,13 @@ Flashblocks are always live on Base. All blocks are built by the Flashblocks bui | **Preconfirmation** | An ultra-fast signal that a transaction will be included, before the full block is sealed | | **Full Block** | A series of 10 Flashblocks combined to form the complete 2-second block | -There are **10 Flashblocks per block**. Each Flashblock (`flashblock_i`) can contain up to `i/10` of the full block's total gas budget. The Flashblocks are combined to recreate the complete block. +Each block contains **10 Flashblocks** (indexes 1-10), each arriving every 200ms. Index 0 exists but only contains system transactions. See [Gas Allocation](#gas-allocation) for how gas budgets work. ---- ## Architecture For details on the sequencer system and Flashblocks infrastructure components (rollup-boost, op-rbuilder, websocket-proxy, and base), see the [Architecture](/base-chain/flashblocks/architecture) page. ---- - ## Transaction Lifecycle When you send a transaction to Base, here's what happens: @@ -52,6 +49,10 @@ During each 200ms block building loop, op-rbuilder selects transactions based on 1. **Transaction fee** — transactions are ordered by fee (highest first) 2. **Gas limit and remaining capacity** — each Flashblock `j` can use up to `j/10` of the total block gas limit + +**Dynamic Mempool:** The builder uses a dynamic mempool that continuously accepts new transactions while building. This minimizes inclusion latency but means a late-arriving high-fee transaction may appear after an already-committed lower-fee transaction within the same Flashblock. This is expected behavior, not a violation of fee priority—transactions are ordered by fee *at the time they're selected*. + + ### 4. Block Building Algorithm The builder follows this process for each 2-second block: @@ -73,23 +74,31 @@ FOR each flashblock j FROM 0 TO 10: ### 5. Preconfirmation Delivery 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 WebSocket message schema, see the [WebSocket Reference](/base-chain/flashblocks/websocket-reference#schema): [Flashblock](/base-chain/flashblocks/websocket-reference#flashblock-object), [Diff](/base-chain/flashblocks/websocket-reference#diff-object), [Metadata](/base-chain/flashblocks/websocket-reference#metadata-object), [Receipt](/base-chain/flashblocks/websocket-reference#receipt-object). + + --- ## Gas Allocation -Each Flashblock has an incrementally increasing gas budget: +The gas budget is **cumulative**, not per-Flashblock. Each Flashblock unlocks an additional 1/10 of the total block gas: -| Flashblock | Available Gas | -|------------|---------------| +| Flashblock | Cumulative Gas Available | +|------------|--------------------------| | 1 | 1/10 of block limit (~18.75M gas) | | 2 | 2/10 of block limit (~37.5M gas) | | 3 | 3/10 of block limit (~56.25M gas) | | ... | ... | | 10 | Full block limit (~187.5M gas) | + +**Unused gas carries forward.** If Flashblock 1 only uses 0.3/10 of gas, Flashblock 2 can use up to 1.7/10 (the cumulative 2/10 limit minus what's already been used). + + **Implications for large transactions:** -- Transactions with gas limits > 1/10 of block limit (currently ~18.75M gas) will never fit in a Flashblock -- It's more common for larger transaction to wait until later Flashblocks with sufficient capacity +- Transactions requiring > 1/10 of block gas (~18.75M) must wait for later Flashblocks +- Large transactions may have longer inclusion times as they wait for sufficient capacity - If your app creates large transactions, monitor for changes in inclusion latency --- @@ -98,11 +107,13 @@ Each Flashblock has an incrementally increasing gas budget: ### Reorg Rate -Flashblocks reorgs on Base Mainnet are effectively **zero**. Base maintains a reorg rate below **0.01%**. +Base targets a < 0.1% Flashblock reorg rate. A reorg means a Flashblock was streamed as a preconfirmation but wasn't included in the final block. A reorg means a Flashblock was streamed as a preconfirmation but wasn't included in the final block. This is rare due to architectural improvements where rollup-boost stores Flashblocks in a `best_payload` variable and only returns the final payload on `get_payload`, preventing tail Flashblock reorgs. -Check current metrics at [base.org/stats](https://base.org/stats). + +**Implement fallback logic.** While reorg rates are low, applications should handle the possibility of preconfirmation reorgs by falling back to full block data for critical operations. Check current metrics at [base.org/stats](https://base.org/stats). + ### Builder Failover @@ -122,7 +133,7 @@ If an extreme circumstance makes running Flashblocks unsafe, preconfirmations ar | Preconfirmation latency | ~200ms | | Full block time | 2 seconds | | Flashblocks per block | 10 | -| Reorg rate | < 0.01% | +| Reorg rate | < 0.1% | --- @@ -133,8 +144,7 @@ Choose the integration method that fits your use case: | Use Case | Recommended Approach | Documentation | |----------|---------------------|---------------| | **Apps needing instant UX** | Flashblocks-aware RPC with `pending` tag | [App Integration](/base-chain/flashblocks/apps) | -| **Traders & low-latency apps** | WebSocket stream | [WebSocket API](/base-chain/flashblocks/node-providers#websocket-api) | -| **Infrastructure providers** | Host Flashblocks-aware RPC nodes | [Node Providers](/base-chain/flashblocks/node-providers) | +| **Infrastructure providers** | Host Flashblocks-aware RPC nodes | [Enable Flashblocks](/base-chain/node-operators/run-a-base-node#enable-flashblocks) | | **Standard apps** | Continue using regular RPCs | No changes needed | @@ -146,7 +156,8 @@ Applications should avoid hard dependencies on the WebSocket stream. RPCs provid ## Further Reading - [App Integration Guide](/base-chain/flashblocks/apps) — RPC methods, code examples, and library integrations -- [Node Provider Guide](/base-chain/flashblocks/node-providers) — Run your own Flashblocks-aware RPC node -- [FAQ](/base-chain/flashblocks/docs) — Common questions about Flashblocks +- [Enable Flashblocks](/base-chain/node-operators/run-a-base-node#enable-flashblocks) — Run your own Flashblocks-aware RPC node +- [WebSocket Reference](/base-chain/flashblocks/websocket-reference) — Technical reference for infrastructure-to-node data syncing +- [FAQ](/base-chain/flashblocks/faq) — Common questions about Flashblocks - [Block Building](/base-chain/network-information/block-building) — Detailed block ordering configuration - [Flashblocks Deep Dive](https://blog.base.dev/flashblocks-deep-dive) — Engineering blog post with implementation details diff --git a/docs/base-chain/flashblocks/websocket-reference.mdx b/docs/base-chain/flashblocks/websocket-reference.mdx new file mode 100644 index 000000000..6cc7e6cfc --- /dev/null +++ b/docs/base-chain/flashblocks/websocket-reference.mdx @@ -0,0 +1,438 @@ +--- +title: Flashblocks WebSocket Reference +sidebarTitle: WebSocket Reference +description: Technical reference for the Flashblocks WebSocket API, data formats, and response schemas used for infrastructure-to-node data syncing. +--- + +This page documents the Flashblocks WebSocket API used for **infrastructure-to-node data syncing**. + + +**Applications should not connect directly to `wss://mainnet.flashblocks.base.org/ws`**. This endpoint is reserved for node infrastructure. Apps should query their RPC node or node provider (e.g., QuickNode, Alchemy) for Flashblocks data instead. See the [App Integration guide](/base-chain/flashblocks/apps) for implementation details. + + + +For background on how Flashblocks work and the [base](https://github.com/base/base) component, see the [Flashblocks Architecture](/base-chain/flashblocks/architecture). + + +--- + +## WebSocket Endpoints + +| Network | URL | +|---------|-----| +| Mainnet | `wss://mainnet.flashblocks.base.org/ws` | +| Sepolia | `wss://sepolia.flashblocks.base.org/ws` | + + +These endpoints are rate-limited (max 10 connections per IP). + + + +Applications should avoid hard dependencies on the WebSocket stream. RPCs provide stable behavior and automatic failover to regular blocks if Flashblocks are unavailable. + + + +--- + +## Message Format + +Messages are delivered as **Brotli-compressed binary** data. Decompress before parsing as JSON. + +To minimize bandwidth, each Flashblock only includes **diff data** from the previous Flashblock: + +- **[Index 0](#flashblock-object)** (initial): Contains the [`base`](#base-object) object with full block properties, plus the first [`diff`](#diff-object) +- **[Index 1-10](#flashblock-object)** (subsequent): Contains only [`diff`](#diff-object) data (new transactions, updated state root, gas used) + +--- + +## Schema + +### Flashblock Object + +The root structure of each WebSocket 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. See [Metadata Object](#metadata-object). + + + +Example: +```json flashblock.json +{ + "payload_id": "0x03997352d799c31a", + "index": 0, + "base": { ... }, + "diff": { ... }, + "metadata": { ... } +} +``` + +--- + +### 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. + + + +Example: +```json base.json +{ + "parent_hash": "0x9edc29b8b0a1e31d28616e40c16132ad0d58faa8bb952595b557526bdb9a960a", + "fee_recipient": "0x4200000000000000000000000000000000000011", + "block_number": "0x158a0e9", + "gas_limit": "0x3938700", + "timestamp": "0x67bf8332", + "base_fee_per_gas": "0xfa", + "prev_randao": "0x0000000000000000000000000000000000000000000000000000000000000000", + "extra_data": "0x" +} +``` + +--- + +### 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. + + + +Example: +```json diff.json +{ + "state_root": "0x208fd63edc0681161105f27d03daf9f8c726d8c94e584a3c0696c98291c24333", + "block_hash": "0x5c330e55a190f82ea486b61e5b12e27dfb4fb3cecfc5746886ef38ca1281bce8", + "gas_used": "0xab3f", + "blob_gas_used": "0x0", + "transactions": [ + "0x02f90133..." + ], + "withdrawals": [], + "receipts_root": "0xa83fdcff1e433d49", + "logs_bloom": "0x00000000...", + "withdrawals_root": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421" +} +``` + +--- + +### Metadata Object + +Contains additional block metadata, including balance updates and transaction receipts. This is where the most useful data for trading applications lives. + + + +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. Contains execution results for transactions in this Flashblock. + + + +Example: +```json metadata.json +{ + "block_number": 22585577, + "new_account_balances": { + "0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0", + "0x4200000000000000000000000000000000000015": "0x1234" + }, + "receipts": { + "0x07d7f06b06fea714c1d1d446efa2790c6970aa74ee006186a32b5b7dd8ca2d82": { ... } + } +} +``` + +--- + +### Receipt Object + +Transaction execution result. Receipts come in two formats: **EIP-1559** (modern) or **Legacy**. Check which field is present to determine the type. + + + +Receipt data for EIP-1559 transactions. See [ReceiptData](#receiptdata-object). + + + +Receipt data for legacy transactions. See [ReceiptData](#receiptdata-object). + + + +Receipt data for L1→L2 deposit transactions. See [ReceiptData](#receiptdata-object). + + + +Example: +```json receipt.json +{ + "Eip1559": { + "status": "0x1", + "cumulativeGasUsed": "0x1234f", + "logs": [] + } +} +``` + +--- + +### ReceiptData Object + +The actual receipt information, regardless of transaction type. + + + +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). + + + +Nonce for deposit transactions (L1→L2 only). + + + +Example: +```json receiptdata.json +{ + "status": "0x1", + "cumulativeGasUsed": "0x1234f", + "logs": [ + { + "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", + "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"], + "data": "0x0000000000000000000000000000000000000000000000000000000000001234" + } + ] +} +``` + +--- + +### Log Object + +Event log emitted by a smart contract. Crucial for detecting swaps, transfers, and other contract events. + + + +Contract address that emitted the event. + + + +Array of indexed event parameters. The first topic is typically the event signature hash (e.g., `Transfer(address,address,uint256)`). + + + +ABI-encoded non-indexed event parameters. + + + +Example: +```json log.json +{ + "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", + "topics": [ + "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", + "0x000000000000000000000000abc123...", + "0x000000000000000000000000def456..." + ], + "data": "0x0000000000000000000000000000000000000000000000000000000000001234" +} +``` + + + + + +--- + +## Complete Example + +### Index 0 Response (Initial) + +The first Flashblock of each full block includes the `base` object: + +Example: +```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": { + "Deposit": { + "status": "0x1", + "cumulativeGasUsed": "0xab3f", + "logs": [], + "depositNonce": "0x158a0ea" + } + } + } + } +} +``` + +### Index 1-10 Response (Diff Only) + +Subsequent Flashblocks only include the `diff` (no `base` object): + +Example: +```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": { + "0x000f3df6d732807ef1319fb7b8bb8522d0beac02": "0x0", + "0x4200000000000000000000000000000000000015": "0x1234" + }, + "receipts": { + "0x7c69632dc315f13a...": { + "Eip1559": { + "status": "0x1", + "cumulativeGasUsed": "0x1234f", + "logs": [] + } + } + } + } +} +``` + +--- + +## Further Resources + +- [How To Build a Base Flashblocks Listener](https://docs.getblock.io/guides/how-to-build-a-base-flashblocks-listener) — Step-by-step Go tutorial +- [Flashblocks Overview](/base-chain/flashblocks/overview) — Key concepts and transaction lifecycle +- [App Integration](/base-chain/flashblocks/apps) — RPC examples and library integrations +- [Reth node README](https://github.com/base/node/tree/main/reth#readme) — Hardware requirements and configuration +- [Flashblocks Deep Dive](https://blog.base.dev/flashblocks-deep-dive) — Engineering blog with implementation details diff --git a/docs/base-chain/network-information/network-fees.mdx b/docs/base-chain/network-information/network-fees.mdx index 9f5465fad..15a21399b 100644 --- a/docs/base-chain/network-information/network-fees.mdx +++ b/docs/base-chain/network-information/network-fees.mdx @@ -30,7 +30,7 @@ documentation](https://docs.optimism.io/stack/transactions/fees). As part of the [Jovian upgrade], Base introduced a minimum base fee. This feature sets a floor for the L2 base fee, preventing it from dropping to extremely low levels during periods of low network activity. -The minimum base fee for Base Mainnet is 500,000 wei (0.0005 gwei). This value may be periodically adjusted as we gather data on how it affects the chain. For reference, a minimum base fee of 0.0005 gwei results in a cost of approximately 0.015 cents for a typical transaction at an ETH price of $3000. +The minimum base fee for Base Mainnet is 2,000,000 wei (0.002 gwei). This value may be periodically adjusted as we gather data on how it affects the chain. For reference, a minimum base fee of 0.002 gwei results in a cost of approximately $0.001 for a typical 200,000 gas transaction at an ETH price of $2500. ### Benefits @@ -42,7 +42,7 @@ The minimum base fee for Base Mainnet is 500,000 wei (0.0005 gwei). This value m | Network | Minimum Base Fee | |--------------|------------------| -| Base Mainnet | 500,000 wei (0.0005 gwei) | +| Base Mainnet | 2,000,000 wei (0.002 gwei) | | Base Sepolia | 200,000 wei (0.0002 gwei) | See the [Configuration Changelog](/base-chain/network-information/configuration-changelog) for a history of changes to the minimum base fee and other network parameters. 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 8cb92e696..4d26727dd 100644 --- a/docs/base-chain/node-operators/run-a-base-node.mdx +++ b/docs/base-chain/node-operators/run-a-base-node.mdx @@ -1,5 +1,5 @@ --- -title: 'Getting Started' +title: Run a Node description: A tutorial that teaches how to set up and run a Base Node. --- @@ -10,6 +10,7 @@ This tutorial will walk you through setting up your own [Base Node](https://gith By the end of this tutorial you should be able to: - Deploy and sync a Base node +- Enable Flashblocks for 200ms preconfirmations ## Prerequisites @@ -100,3 +101,70 @@ echo Latest synced block behind by: $((($(date +%s)-$( \ ``` You'll also know that the sync hasn't completed if you get `Error: nonce has already been used` if you try to deploy using your node. + +--- + +## Enable Flashblocks + +Once your node is synced, you can enable Flashblocks to serve 200ms preconfirmations to your applications. + +### Configuration + +To enable Flashblocks, start your node with the following environment variables: + +```sh +NODE_TYPE=base CLIENT=reth RETH_FB_WEBSOCKET_URL="wss://mainnet.flashblocks.base.org/ws" docker-compose up +``` + +| Variable | Description | Values | +|----------|-------------|--------| +| `NODE_TYPE` | Enables base reth node with Flashblocks | `base` | +| `CLIENT` | Execution client | `reth` | +| `RETH_FB_WEBSOCKET_URL` | Flashblocks WebSocket endpoint | See below | + +### WebSocket Endpoints + +| Network | URL | +|---------|-----| +| Mainnet | `wss://mainnet.flashblocks.base.org/ws` | +| Sepolia | `wss://sepolia.flashblocks.base.org/ws` | + + +**These WebSocket endpoints are for node infrastructure only.** Applications should not connect directly to `wss://mainnet.flashblocks.base.org/ws`. Instead, apps should query your RPC node for Flashblocks data. See the [App Integration guide](/base-chain/flashblocks/apps) for details. + + + +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. + + +### Verify Flashblocks Functionality + +Test that your node is properly serving Flashblocks by querying a pending block: + +```sh +curl -X POST \ + --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending", false],"id":1}' \ + http://localhost:8545 +``` + +A successful response will include block data from the latest Flashblock. If Flashblocks are temporarily unavailable, the node falls back to returning the latest finalized block. + +### Available RPC Methods + +Your Flashblocks-aware node supports all standard Ethereum JSON-RPC methods, plus these Flashblocks-enabled endpoints: + +| Method | Flashblocks Usage | +|--------|------------------| +| [`eth_getBlockByNumber`](/base-chain/flashblocks/apps#eth_getblockbynumber) | Use `pending` tag | +| [`eth_getBalance`](/base-chain/flashblocks/apps#eth_getbalance) | Use `pending` tag | +| [`eth_getTransactionReceipt`](/base-chain/flashblocks/apps#eth_gettransactionreceipt) | Returns preconfirmed receipts | +| [`eth_getTransactionByHash`](/base-chain/flashblocks/apps#eth_gettransactionbyhash) | Use `pending` tag | +| [`eth_getTransactionCount`](/base-chain/flashblocks/apps#eth_gettransactioncount) | Use `pending` tag | +| [`eth_call`](/base-chain/flashblocks/apps#eth_call) | Use `pending` tag | +| [`eth_simulateV1`](/base-chain/flashblocks/apps#eth_simulatev1) | Use `pending` tag | +| [`eth_estimateGas`](/base-chain/flashblocks/apps#eth_estimategas) | Use `pending` tag | +| [`eth_getLogs`](/base-chain/flashblocks/apps#eth_getlogs) | Use `pending` for `toBlock` | +| [`eth_subscribe`](/base-chain/flashblocks/apps#eth_subscribe-beta) | Stream Flashblock data in real-time (Beta) | +| [`base_transactionStatus`](/base-chain/flashblocks/apps#base_transactionstatus-beta) | Check if transaction is in mempool (Beta) | + +For code examples, see the [App Integration guide](/base-chain/flashblocks/apps#rpc-api). diff --git a/docs/docs.json b/docs/docs.json index 2764b0a42..29c6c199b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -47,7 +47,7 @@ }, { "group": "Build with AI", - "pages": ["get-started/ai-prompting", "get-started/prompt-library"] + "pages": ["get-started/docs-mcp", "get-started/docs-llms", "get-started/prompt-library"] } ], "global": { @@ -85,8 +85,7 @@ "base-chain/quickstart/deploy-on-base", "base-chain/quickstart/connecting-to-base", "base-chain/quickstart/bridge-token", - "base-chain/quickstart/base-solana-bridge", - "base-chain/quickstart/builder-codes" + "base-chain/quickstart/base-solana-bridge" ] }, { @@ -106,10 +105,10 @@ "group": "Flashblocks", "pages": [ "base-chain/flashblocks/apps", + "base-chain/flashblocks/overview", + "base-chain/flashblocks/faq", "base-chain/flashblocks/architecture", - "base-chain/flashblocks/docs", - "base-chain/flashblocks/node-providers", - "base-chain/flashblocks/overview" + "base-chain/flashblocks/websocket-reference" ] }, { @@ -121,6 +120,13 @@ "base-chain/node-operators/troubleshooting" ] }, + { + "group": "Builder Codes", + "pages": [ + "base-chain/builder-codes/builder-codes", + "base-chain/builder-codes/builder-codes-faq" + ] + }, { "group": "Tools", "pages": [ @@ -235,6 +241,7 @@ }, "base-account/framework-integrations/cdp", "base-account/framework-integrations/rainbowkit", + "base-account/framework-integrations/reown", "base-account/framework-integrations/thirdweb" ] }, @@ -1007,7 +1014,8 @@ "cookbook/defi-your-app", "cookbook/go-gasless", "cookbook/base-app-coins", - "cookbook/testing-onchain-apps" + "cookbook/testing-onchain-apps", + "cookbook/deploy-openclaw-on-aws" ] }, { @@ -1510,6 +1518,18 @@ ] }, "redirects": [ + { + "source": "/base-chain/quickstart/builder-codes", + "destination": "/base-chain/builder-codes/builder-codes" + }, + { + "source": "/get-started/ai-prompting", + "destination": "/get-started/docs-mcp" + }, + { + "source": "/base-chain/network-information/bridges-mainnet", + "destination": "/base-chain/network-information/bridges" + }, { "source": "base-app/agents/getting-featured", "destination": "base-app/agents/building-quality-agents" From 680a54b681cf2add9caf18370f4f347ed8b46a69 Mon Sep 17 00:00:00 2001 From: roethke Date: Tue, 10 Feb 2026 08:11:26 -0800 Subject: [PATCH 08/11] update large tx implication language --- docs/base-chain/flashblocks/overview.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/base-chain/flashblocks/overview.mdx b/docs/base-chain/flashblocks/overview.mdx index 534f9e217..a3bd1d21f 100644 --- a/docs/base-chain/flashblocks/overview.mdx +++ b/docs/base-chain/flashblocks/overview.mdx @@ -97,9 +97,9 @@ The gas budget is **cumulative**, not per-Flashblock. Each Flashblock unlocks an **Implications for large transactions:** -- Transactions requiring > 1/10 of block gas (~18.75M) must wait for later Flashblocks -- Large transactions may have longer inclusion times as they wait for sufficient capacity -- If your app creates large transactions, monitor for changes in inclusion latency +- Transactions exceeding 1/10 of block gas (~18.75M) can be included once enough cumulative capacity exists. For example, a 20M gas transaction can be included in the 2nd Flashblock if the 1st Flashblock leaves at least 1.25M gas unused (since 2/10 = 37.5M cumulative, minus 20M needed = 17.5M already consumed is acceptable). +- There is a separate **max gas limit per transaction** on Base, which is distinct from Flashblock capacity. +- Large transactions may experience slightly longer inclusion times while waiting for sufficient cumulative capacity. --- From 53fb8ae027da57bb20f112241180ad5534312eb8 Mon Sep 17 00:00:00 2001 From: roethke Date: Tue, 10 Feb 2026 09:07:19 -0800 Subject: [PATCH 09/11] add accordion layout to faq, audit content for consistency --- docs/base-chain/flashblocks/faq.mdx | 160 ++++++++++-------- .../flashblocks/websocket-reference.mdx | 4 - 2 files changed, 86 insertions(+), 78 deletions(-) diff --git a/docs/base-chain/flashblocks/faq.mdx b/docs/base-chain/flashblocks/faq.mdx index 0d70f6651..82546b41a 100644 --- a/docs/base-chain/flashblocks/faq.mdx +++ b/docs/base-chain/flashblocks/faq.mdx @@ -10,107 +10,119 @@ For a comprehensive introduction to how Flashblocks work, see the [Flashblocks O ## Block Building -### Are Flashblocks optional? + + + All Base blocks are built by the Flashblocks builder, meaning **Flashblocks are always live**. However, apps may choose not to rely on preconfirmations and can continue using standard RPCs without any Flashblocks integration. + -All Base blocks are built by the Flashblocks builder, meaning **Flashblocks are always live**. However, apps may choose not to rely on preconfirmations and can continue using standard RPCs without any Flashblocks integration. + + No significant differences—both order transactions by fee. The main difference is timing: Flashblocks occur every 200ms instead of every 2 seconds. + + See [Block Building](/base-chain/network-information/block-building#flashblocks) for details. + -### Is there any difference in transaction inclusion for Flashblocks vs. 2-second blocks? + + The sequencer will not stop publishing Flashblocks unless an extreme circumstance makes running them unsafe. If this happens, preconfirmations are disabled network-wide and confirmations fall back to standard 2-second blocks. The sequencer continues operating normally. + -No significant differences—both order transactions by fee. The main difference is timing: Flashblocks occur every 200ms instead of every 2 seconds. See [Block Building](/base-chain/network-information/block-building#flashblocks) for details. + + Transactions with large gas limits (> ~18.75M gas, which is 1/10 of the ~187.5M block limit) may have longer inclusion times. This is because the builder allocates gas cumulatively—each Flashblock `j` can use up to `j/10` of the total block gas limit. Large transactions can be included once enough cumulative capacity exists. -### Can the sequencer stop publishing Flashblocks? + See [Gas Allocation](/base-chain/flashblocks/overview#gas-allocation) for the full breakdown. + -The sequencer will not stop publishing Flashblocks unless an extreme circumstance makes running them unsafe. If this happens, preconfirmations are disabled network-wide and confirmations fall back to standard 2-second blocks. The sequencer continues operating normally. + + There's no way to guarantee which Flashblock a transaction lands in, similar to how you can't guarantee a specific block. To improve chances of quick inclusion: -### Why is my transaction having trouble getting included? + - Set a higher priority fee + - Keep gas limits below ~18.75M (1/10 of block limit) to be eligible for Flashblock 1 + -Transactions with large gas limits (> 14M gas) may have longer inclusion times. This is because the builder allocates gas incrementally—each Flashblock `j` can only use `j/10` of the total block gas limit. Large transactions must wait for later Flashblocks with sufficient capacity. + + Base targets a Flashblock reorg rate of < 0.1%. While reorgs are rare, applications should implement fallback logic for critical operations. + + Check current metrics at [base.org/stats](https://base.org/stats). + -See [Gas Allocation](/base-chain/flashblocks/overview#gas-allocation) for the full breakdown. - -### How do I ensure my transaction is in the first Flashblock? - -There's no way to guarantee which Flashblock a transaction lands in, similar to how you can't guarantee a specific block. To improve chances of quick inclusion: - -- Set a higher priority fee -- Keep gas limits below 14M (1/10 of block limit) to be eligible for Flashblock 1 - -### How frequently do Flashblock reorgs happen? - -Base targets a Flashblock reorg rate SLO of **99.9%** (< 0.1% reorgs). While reorgs are rare, applications should implement fallback logic for critical operations. Check current metrics at [base.org/stats](https://base.org/stats). - -### What does it mean when a Flashblock is reorged? - -A reorg means a Flashblock was streamed as a preconfirmation but wasn't included in the final block. This is rare due to architectural improvements in rollup-boost that prevent tail Flashblock reorgs. Apps should handle this possibility gracefully, but occurrences are minimal. + + A reorg means a Flashblock was streamed as a preconfirmation but wasn't included in the final block. This is rare due to architectural improvements in rollup-boost that prevent tail Flashblock reorgs. Apps should handle this possibility gracefully, but occurrences are minimal. + + --- ## WebSocket -### Can I connect directly to the Flashblocks WebSocket stream? - -**No.** The raw Flashblocks WebSocket (`wss://mainnet.flashblocks.base.org/ws`) is reserved for infrastructure-to-node data syncing. Applications should not connect to it directly. - -Instead, query your RPC node or node provider (e.g., QuickNode, Alchemy, Infura, dRPC) for Flashblocks data via: -- **RPC API**: Standard JSON-RPC methods with the `pending` tag -- **WebSocket subscriptions**: Use `eth_subscribe` via your node provider's WebSocket endpoint - -See [App Integration](/base-chain/flashblocks/apps) for implementation details. + + + **No.** The raw Flashblocks WebSocket (`wss://mainnet.flashblocks.base.org/ws`) is reserved for infrastructure-to-node data syncing. Applications should not connect to it directly. -### Why are there 11 Flashblocks? + Instead, query your RPC node or node provider (e.g., QuickNode, Alchemy, Infura, dRPC) for Flashblocks data via: + - **RPC API**: Standard JSON-RPC methods with the `pending` tag + - **WebSocket subscriptions**: Use `eth_subscribe` via your node provider's WebSocket endpoint -Index 0 contains only system transactions and doesn't use any gas limit. Indexes 1-10 are the actual Flashblocks that pull pending transactions from the txpool. + See [App Integration](/base-chain/flashblocks/apps) for implementation details. + -### Why are there sometimes fewer than 10 Flashblocks? + + Index 0 contains only system transactions and doesn't use any gas limit. Indexes 1-10 are the actual Flashblocks that pull pending transactions from the txpool. + -This is expected. When the previous block takes longer to build, the system compensates by allocating less time to the next block, resulting in fewer Flashblocks. + + This is expected. When the previous block takes longer to build, the system compensates by allocating less time to the next block, resulting in fewer Flashblocks. + -### What encoding format is the transaction data in? + + Transaction data in the [`diff.transactions`](/base-chain/flashblocks/websocket-reference#diff-object) array is Recursive Length Prefix (RLP) encoded. + -Transaction data in the [`diff.transactions`](/base-chain/flashblocks/websocket-reference#diff-object) array is Recursive Length Prefix (RLP) encoded. + + The public WebSocket has a maximum connection limit. For production use, we recommend: -### Why am I getting rate limited on the WebSocket? - -The public WebSocket has a maximum connection limit. For production use, we recommend: - -1. Running your own [Flashblocks-aware RPC node](/base-chain/node-operators/run-a-base-node#enable-flashblocks) -2. Using a third-party node provider with Flashblocks support + 1. Running your own [Flashblocks-aware RPC node](/base-chain/node-operators/run-a-base-node#enable-flashblocks) + 2. Using a third-party node provider with Flashblocks support + + --- ## RPC -### Why am I getting rate limited using mainnet-preconf.base.org? - -The public endpoint has explicit rate limiting. For production use: - -- Use a third-party node provider with Flashblocks support (Alchemy, Infura, QuickNode, dRPC) -- Run your own [Flashblocks-aware RPC node](/base-chain/node-operators/run-a-base-node#enable-flashblocks) - -### What RPC methods support Flashblocks? - -The following methods are Flashblocks-enabled: - -| Method | Usage | -|--------|-------| -| `eth_getBlockByNumber` | Use `pending` tag | -| `eth_getBalance` | Use `pending` tag | -| `eth_getTransactionReceipt` | Returns preconfirmed receipts | -| `eth_getTransactionByHash` | Use `pending` tag | -| `eth_getTransactionCount` | Use `pending` tag | -| `eth_call` | Use `pending` tag | -| `eth_simulateV1` | Use `pending` tag | -| `eth_estimateGas` | Use `pending` tag | -| `eth_getLogs` | Use `pending` for `toBlock` | -| `eth_subscribe` | Stream Flashblock data in real-time (Beta) | -| `base_transactionStatus` | Check if transaction is in mempool (Beta) | - -See [App Integration](/base-chain/flashblocks/apps#rpc-api-reference) for full examples. + + + The public endpoint has explicit rate limiting. For production use: + + - Use a third-party node provider with Flashblocks support (Alchemy, Infura, QuickNode, dRPC) + - Run your own [Flashblocks-aware RPC node](/base-chain/node-operators/run-a-base-node#enable-flashblocks) + + + + The following methods are Flashblocks-enabled: + + | Method | Usage | + |--------|-------| + | `eth_getBlockByNumber` | Use `pending` tag | + | `eth_getBalance` | Use `pending` tag | + | `eth_getTransactionReceipt` | Returns preconfirmed receipts | + | `eth_getTransactionByHash` | Use `pending` tag | + | `eth_getTransactionCount` | Use `pending` tag | + | `eth_call` | Use `pending` tag | + | `eth_simulateV1` | Use `pending` tag | + | `eth_estimateGas` | Use `pending` tag | + | `eth_getLogs` | Use `pending` for `toBlock` | + | `eth_subscribe` | Stream Flashblock data in real-time (Beta) | + | `base_transactionStatus` | Check if transaction is in mempool (Beta) | + + See [App Integration](/base-chain/flashblocks/apps#rpc-api-reference) for full examples. + + --- ## Node Setup -### How do I set up a Flashblocks-aware RPC node? - -Use the Reth binary from the [Base node repository](https://github.com/base/node/tree/main/reth). See the [Enable Flashblocks guide](/base-chain/node-operators/run-a-base-node#enable-flashblocks) for complete setup instructions. \ No newline at end of file + + + Use the Reth binary from the [Base node repository](https://github.com/base/node/tree/main/reth). See the [Enable Flashblocks guide](/base-chain/node-operators/run-a-base-node#enable-flashblocks) for complete setup instructions. + + \ No newline at end of file diff --git a/docs/base-chain/flashblocks/websocket-reference.mdx b/docs/base-chain/flashblocks/websocket-reference.mdx index 6cc7e6cfc..9711e53a6 100644 --- a/docs/base-chain/flashblocks/websocket-reference.mdx +++ b/docs/base-chain/flashblocks/websocket-reference.mdx @@ -336,10 +336,6 @@ Example: } ``` - - - - --- ## Complete Example From 43b6c05584b326f8d7b1fc01e2eb99bab974d5d4 Mon Sep 17 00:00:00 2001 From: roethke Date: Tue, 10 Feb 2026 13:23:24 -0800 Subject: [PATCH 10/11] add escape dollar signs --- docs/base-chain/network-information/network-fees.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/network-information/network-fees.mdx b/docs/base-chain/network-information/network-fees.mdx index c07b45e6a..7fab7638d 100644 --- a/docs/base-chain/network-information/network-fees.mdx +++ b/docs/base-chain/network-information/network-fees.mdx @@ -30,7 +30,7 @@ documentation](https://docs.optimism.io/stack/transactions/fees). As part of the [Jovian upgrade], Base introduced a minimum base fee. This feature sets a floor for the L2 base fee, preventing it from dropping to extremely low levels during periods of low network activity. -The minimum base fee for Base Mainnet is 2,000,000 wei (0.002 gwei). This value may be periodically adjusted as we gather data on how it affects the chain. For reference, a minimum base fee of 0.002 gwei results in a cost of approximately $0.001 for a typical 200,000 gas transaction at an ETH price of $2500. +The minimum base fee for Base Mainnet is 2,000,000 wei (0.002 gwei). This value may be periodically adjusted as we gather data on how it affects the chain. For reference, a minimum base fee of 0.002 gwei results in a cost of approximately \$0.001 for a typical 200,000 gas transaction at an ETH price of \$2500. ### Benefits From 2dec131a0b52bd01680d80f8488b03a605ba75c9 Mon Sep 17 00:00:00 2001 From: roethke Date: Tue, 10 Feb 2026 13:41:03 -0800 Subject: [PATCH 11/11] add dynamic mempool for fb block building, update faq --- docs/base-chain/flashblocks/faq.mdx | 15 +++++++++++++++ .../network-information/block-building.mdx | 8 +++++++- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/base-chain/flashblocks/faq.mdx b/docs/base-chain/flashblocks/faq.mdx index 82546b41a..5fdcf49c5 100644 --- a/docs/base-chain/flashblocks/faq.mdx +++ b/docs/base-chain/flashblocks/faq.mdx @@ -38,6 +38,21 @@ For a comprehensive introduction to how Flashblocks work, see the [Flashblocks O - Keep gas limits below ~18.75M (1/10 of block limit) to be eligible for Flashblock 1 + + The Flashblock builder uses a **dynamic mempool** that continuously accepts new transactions while building. This design prioritizes **low inclusion latency** over strict fee ordering. + + **What this means:** + - Transactions are ordered by fee *at the time they're selected* for inclusion + - If a high-fee transaction arrives after a lower-fee transaction has already been committed to the current Flashblock, the high-fee transaction will appear after it (or in the next Flashblock) + - This is expected behavior, not a bug—the builder doesn't "reorder" already-committed transactions + + **Why this tradeoff?** + + A "snapshot" mempool (freezing the transaction pool at the start of each block) would guarantee strict fee ordering but increase inclusion latency. The dynamic approach gets transactions included faster at the cost of occasionally "breaking" the expected priority gas auction (PGA) order. + + **For traders and bots:** If strict fee-based ordering is critical for your use case, be aware that arrival timing matters as much as fee amount within a 200ms Flashblock window. + + Base targets a Flashblock reorg rate of < 0.1%. While reorgs are rare, applications should implement fallback logic for critical operations. diff --git a/docs/base-chain/network-information/block-building.mdx b/docs/base-chain/network-information/block-building.mdx index b05db948e..12eb9d12f 100644 --- a/docs/base-chain/network-information/block-building.mdx +++ b/docs/base-chain/network-information/block-building.mdx @@ -28,7 +28,7 @@ Blocks are built using [op-rbuilder](https://github.com/flashbots/op-rbuilder) w For a comprehensive technical deep dive into Flashblocks architecture, see the [Flashblocks Overview](/base-chain/flashblocks/overview). -*There are two key differences from vanilla ordering:* +*There are three key differences from vanilla ordering:* 1. **Timing** — Flashblocks are built every 200ms, each ordering a portion of the block. Once built and broadcast, transaction ordering is locked. Later-arriving transactions with higher priority fees cannot be included in earlier Flashblocks. @@ -46,6 +46,12 @@ For a comprehensive technical deep dive into Flashblocks architecture, see the [ Transactions exceeding 14M gas cannot fit in Flashblock 1 and must wait for later Flashblocks. Monitor inclusion latency if your app creates large transactions. +3. **Dynamic Mempool** — The builder continuously accepts new transactions while building each Flashblock. This minimizes inclusion latency but means transactions are ordered by fee *at the time of selection*, not globally across all transactions that arrive during the 200ms window. A late-arriving high-fee transaction may appear after an already-committed lower-fee transaction. + + + This is a deliberate tradeoff: faster inclusion at the cost of occasionally "breaking" expected priority gas auction (PGA) ordering within a Flashblock. See the [Flashblocks FAQ](/base-chain/flashblocks/faq) for more details. + + ### Per-Transaction Gas Maximum Base enforces a per-transaction gas maximum of **25,000,000 gas**. Transactions that specify a gas limit above this value are **rejected by the mempool before inclusion**. `eth_sendTransaction` or `eth_sendRawTransaction` will return a JSON-RPC error (for example: `exceeds maximum per-transaction gas limit`). This cap does **not** change the block gas limit or the block validity conditions.