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

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:

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

# .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:

CLIENT=reth docker-compose up -d

Verify the mode by checking the container logs:

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:

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}