Run Flashblocks-aware RPC Nodes

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.

Quick Start

Prerequisites

• Docker and Docker Compose
• Minimum hardware requirements (see node README)
• Access to a Flashblocks WebSocket endpoint (public endpoints provided in the repo)

Clone and Configure

# Clone the repository
git clone https://github.com/base/node.git
cd node

Start the Node

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.

---

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:

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

For code examples, see the App Integration guide.

---

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 — Hardware requirements and configuration
• Flashblocks Overview — Architecture and how the system works
• App Integration — RPC examples and library integrations
• Flashblocks Deep Dive — Engineering blog with implementation details