# Flashblocks Mode for Reth on Base: How to Configure Pending Block Access

> Discover Flashblocks mode for Reth on Base. Learn to configure pending block access by setting the RETH_FB_WEBSOCKET_URL environment variable for your node.

- Repository: [Base/node](https://github.com/base/node)
- Tags: how-to-guide
- Published: 2026-03-03

---

**Flashblocks mode enables Reth nodes to stream pending block data via websocket, activated by setting the `RETH_FB_WEBSOCKET_URL` environment variable in your Base node configuration.**

Flashblocks mode allows Reth execution clients to access pending block information without maintaining a full mempool. When configured on Base, this mode connects your node directly to the Flashblocks websocket endpoint, exposing pending block RPC methods that are otherwise unavailable in standard configurations.

## What Is Flashblocks Mode for Reth?

Flashblocks mode is an optional operational configuration for the Reth execution client that establishes a websocket connection to a Flashblocks endpoint. Instead of computing pending blocks locally through transaction gossip, the node receives pre-built pending block data directly from the Flashblocks infrastructure. This gives operators access to time-critical pending block RPC methods—specifically `eth_getBlockByNumber` with the `"pending"` tag—without the resource overhead of processing pending transactions locally.

The implementation in `base/node` treats Flashblocks as a **drop-in enhancement** rather than a requirement. If the websocket URL is absent, the entrypoint script automatically falls back to vanilla mode, ensuring the node remains fully operational for confirmed blocks only.

## How Flashblocks Configuration Works in base/node

The Base node repository uses an environment-driven activation pattern. The container startup sequence detects your intent based on environment variables and modifies the Reth command-line arguments accordingly.

### Environment Variable Detection

When the container initializes, the `reth/reth-entrypoint` script inspects the environment for `RETH_FB_WEBSOCKET_URL`. Lines 24–27 of the entrypoint contain the detection logic:

```bash
if [[ -n "${RETH_FB_WEBSOCKET_URL:-}" ]]; then
    ADDITIONAL_ARGS="$ADDITIONAL_ARGS --websocket-url=$RETH_FB_WEBSOCKET_URL"
    echo "Enabling Flashblocks support with endpoint: $RETH_FB_WEBSOCKET_URL"
else
    echo "Running in vanilla node mode (no Flashblocks URL provided)"
fi

```

If the variable exists, the script appends the `--websocket-url` flag to the `ADDITIONAL_ARGS` variable. Lines 38–39 then inject these arguments into the final `reth node` command, establishing the websocket connection at startup.

### Docker Compose Integration

The [`docker-compose.yml`](https://github.com/base/node/blob/main/docker-compose.yml) file mounts environment files into the execution container using the `env_file:` directive. By default, it loads `.env.mainnet`, though operators can switch to `.env.sepolia` for testnet deployments. This design keeps sensitive configuration—like websocket endpoints—separate from the container image while ensuring the entrypoint has access to the variables at runtime.

### RPC Method Exposure

Once the `--websocket-url` flag is passed to the Reth binary, the client registers Flashblocks-specific RPC handlers. Regular JSON-RPC calls to `eth_getBlockByNumber` with the `"pending"` parameter are then forwarded to the Flashblocks websocket rather than returning a null response or an error. If the websocket connection fails or the variable is undefined, the node simply omits these pending methods and continues serving confirmed block data normally.

## Configuring Flashblocks on Base

Enabling Flashblocks requires editing your environment file and restarting the stack. No changes to the Docker image or Dockerfile are necessary.

### Step 1: Configure the Environment Variable

Locate the environment file for your target network—`.env.mainnet` for Base mainnet or `.env.sepolia` for testnet. Around line 97, uncomment or add the `RETH_FB_WEBSOCKET_URL` variable:

```dotenv

# .env.mainnet

RETH_FB_WEBSOCKET_URL=wss://mainnet.flashblocks.base.org/ws

```

For testnet deployments, use the appropriate Sepolia endpoint instead. The variable must contain a valid `wss://` URL for the entrypoint to activate Flashblocks mode.

### Step 2: Start the Node with Flashblocks

Use Docker Compose to launch the execution client with the updated environment:

```bash
CLIENT=reth docker-compose up -d

```

Verify the mode by checking the container logs:

```bash
docker logs $(docker-compose ps -q reth)

```

Look for the startup message: `Enabling Flashblocks support with endpoint: wss://mainnet.flashblocks.base.org/ws`. If you see `Running in vanilla node mode (no Flashblocks URL provided)`, check that your `.env` file is properly mounted and the variable is uncommented.

### Step 3: Query Pending Blocks via RPC

With Flashblocks active, test the pending block endpoint:

```bash
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["pending",false],"id":1}'

```

A successful response contains the pending block header and transaction list. In vanilla mode, this same request would return an error or empty result because the node lacks pending block state.

## Summary

- **Flashblocks mode** provides Reth nodes with streaming pending block data via websocket, eliminating the need for local mempool processing to serve pending RPC calls.
- **Activation** is controlled entirely by the `RETH_FB_WEBSOCKET_URL` environment variable in `reth/reth-entrypoint`, which conditionally appends the `--websocket-url` flag to the Reth binary.
- **Configuration** occurs in `.env.mainnet` or `.env.sepolia`, mounted into the container via [`docker-compose.yml`](https://github.com/base/node/blob/main/docker-compose.yml), requiring no image rebuilds.
- **Fail-safe design** ensures that missing or invalid websocket configurations result in standard vanilla operation rather than startup failures.

## Frequently Asked Questions

### What is the difference between Flashblocks mode and vanilla Reth on Base?

Vanilla Reth processes only confirmed blocks and cannot serve pending block data through standard RPC methods. Flashblocks mode establishes a websocket connection to the Flashblocks infrastructure, allowing the node to proxy pending block queries (`eth_getBlockByNumber("pending")`) to that service. According to the `base/node` source code, vanilla mode runs automatically when `RETH_FB_WEBSOCKET_URL` is unset, while Flashblocks mode activates immediately when the variable is present.

### Which RPC methods are available when Flashblocks mode is enabled?

When Flashblocks mode is active, the node supports pending block queries that are otherwise unavailable. The primary method is `eth_getBlockByNumber` with the `"pending"` tag, which returns the current pending block constructed by the Flashblocks sequencer. Standard confirmed block methods remain unchanged and continue to be served from the node's local database.

### Is Flashblocks mode required to run a Base node?

No. Flashblocks mode is entirely optional. The `reth/reth-entrypoint` script explicitly handles the absence of `RETH_FB_WEBSOCKET_URL` by printing `Running in vanilla node mode` and starting Reth without the websocket flag. Your node will sync and validate base chain data normally; you simply won't have access to pending block RPC endpoints.

### How do I verify that Flashblocks mode is active?

Check the container logs immediately after startup. The entrypoint script outputs `Enabling Flashblocks support with endpoint: <url>` when the mode is active. Alternatively, query the pending block endpoint: if you receive valid block data rather than a null response or error, Flashblocks is functioning correctly. If you see `Running in vanilla node mode`, verify that your `.env` file contains the uncommented `RETH_FB_WEBSOCKET_URL` and that Docker Compose is loading the correct environment file.