Skip to content

docs (flashblocks): add overview page and improve structure #869

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
roethke wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs (flashblocks): add overview page and improve structure #869

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a24680e
add overview page and improve documentation structure
roethke Jan 21, 2026
ac9d1a1
update content, add callout for subscriptions, remove ethers
roethke Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 17 additions & 38 deletions docs/base-chain/flashblocks/apps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<Info>
New to Flashblocks? Start with the [Flashblocks Overview](/base-chain/flashblocks/overview) to understand the architecture and how transactions flow through the system.
</Info>

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))

<Tip>
For most apps, the RPC API is recommended. WebSocket is best for traders and infrastructure providers who need the absolute lowest latency.
</Tip>

<Warning>
**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.
</Warning>

### RPC API

Expand Down Expand Up @@ -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: "<SOME ADDRESS>",
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
Expand Down
108 changes: 68 additions & 40 deletions docs/base-chain/flashblocks/docs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<Info>
For a comprehensive introduction to how Flashblocks work, see the [Flashblocks Overview](/base-chain/flashblocks/overview).
</Info>

### 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.
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.
120 changes: 88 additions & 32 deletions docs/base-chain/flashblocks/node-providers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,117 @@
---
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.

<Info>
For background on how Flashblocks work and the node-reth component, see the [Flashblocks Overview](/base-chain/flashblocks/overview#architecture).
</Info>

## 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
```

<Note>
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.
</Note>

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
<Warning>
Public WebSocket endpoints are rate-limited. For production deployments with high traffic, consider connecting directly to your own WebSocket proxy or using infrastructure providers.
</Warning>

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 \
--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

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 |
<Tip>
Applications should avoid hard dependencies on the WebSocket stream. RPCs provide stable behavior and automatic failover to regular blocks if Flashblocks are unavailable.
</Tip>

### 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**
```
Expand Down Expand Up @@ -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

Loading