diff --git a/docs/base-chain/flashblocks/apps.mdx b/docs/base-chain/flashblocks/apps.mdx index a96c26d57..4cbbf4482 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 + +New to Flashblocks? Start with the [Flashblocks Overview](/base-chain/flashblocks/overview) to understand the architecture and how transactions flow through the system. + -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. +## Integration Methods -## Integrating Flashblocks +There are two ways to integrate with Flashblocks: -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. +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. + + + +**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 @@ -303,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/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..15dfeb029 --- /dev/null +++ b/docs/base-chain/flashblocks/overview.mdx @@ -0,0 +1,175 @@ +--- +title: Flashblocks Overview +sidebarTitle: Overview +description: Understand the sequencer architecture, block building algorithm, and integration options for Flashblocks on Base. +--- + +## What are Flashblocks? + +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. + + +### 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"