Skip to main content
This tutorial will walk you through setting up your own Base Node.

​
Objectives

By the end of this tutorial you should be able to:
  • Deploy and sync a Base node
  • Enable Flashblocks for 200ms preconfirmations

​
Prerequisites

Running a node is time consuming, resource expensive, and potentially costly. If you don’t already know why you want to run your own node, you probably don’t need to.If you’re just getting started and need an RPC URL, you can use our free endpoints:
  • Mainnet: https://mainnet.base.org
  • Testnet (Sepolia): https://sepolia.base.org
Note: Our RPCs are rate-limited, they are not suitable for production apps.If you’re looking to harden your app and avoid rate-limiting for your users, please consider using an endpoint from one of our partners.

​
Hardware requirements

We recommend you have this configuration to run a node:
  • 8-Core CPU
  • at least 16 GB RAM
  • a locally attached NVMe SSD drive
  • Adequate storage capacity:
    • Minimum: (2 × chain_size) + snapshot_size + 20% buffer
    • Accounts for snapshot restoration (if applicable) and chain data
If utilizing Amazon Elastic Block Store (EBS), ensure timing buffered disk reads are fast enough in order to avoid latency issues alongside the rate of new blocks added to Base during the initial synchronization process; io2 block express is recommended.

​
Networking

Ensure the following ports are accessible (not blocked by firewall) for peer discovery and sync:
PortProtocolPurpose
30303TCP/UDPP2P Discovery (discv4) & RLPx
9222TCP/UDPReth Discovery v5 (discv5)
Port 9222 is critical for Reth peer discovery. If this port is blocked, your node may have difficulty finding peers and syncing.

​
Docker

This tutorial assumes you are familiar with Docker and have it running on your machine.

​
L1 RPC URL

You’ll need your own L1 RPC URL. This can be one that you run yourself, or via a third-party provider, such as our partners.

​
Running a Node

  1. Clone the repo.
  2. Ensure you have an Ethereum L1 full node RPC available (not Base), and set OP_NODE_L1_ETH_RPC & OP_NODE_L1_BEACON (in the .env.* file if using docker-compose). If running your own L1 node, it needs to be synced before Base will be able to fully sync.
  3. Uncomment the line relevant to your network (.env.sepolia, or .env.mainnet) under the 2 env_file keys in docker-compose.yml.
  4. Run docker compose up. Confirm you get a response from:
Terminal
curl -d '{"id":0,"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest",false]}' \
  -H "Content-Type: application/json" http://localhost:8545
Syncing your node may take days and will consume a vast amount of your requests quota. Be sure to monitor usage and up your plan if needed.

​
Snapshots

If you’re a Base Node operator and would like to save significant time on the initial sync, you may restore from a snapshot. The snapshots are updated every week.

​
Syncing

You can monitor the progress of your sync with:
Terminal
echo Latest synced block behind by: $((($(date +%s)-$( \
  curl -d '{"id":0,"jsonrpc":"2.0","method":"optimism_syncStatus"}' \
  -H "Content-Type: application/json" http://localhost:7545 | \
  jq -r .result.unsafe_l2.timestamp))/60)) minutes
You’ll also know that the sync hasn’t completed if you get Error: nonce has already been used if you try to deploy using your node.

​
Enable Flashblocks

Once your node is synced, you can enable Flashblocks to serve 200ms preconfirmations to your applications.

​
Configuration

To enable Flashblocks, start your node with the following environment variables: 
NODE_TYPE=base CLIENT=reth RETH_FB_WEBSOCKET_URL="wss://mainnet.flashblocks.base.org/ws" docker-compose up
VariableDescriptionValues
NODE_TYPEEnables base reth node with Flashblocksbase
CLIENTExecution clientreth
RETH_FB_WEBSOCKET_URLFlashblocks WebSocket endpointSee below

​
WebSocket Endpoints

NetworkURL
Mainnetwss://mainnet.flashblocks.base.org/ws
Sepoliawss://sepolia.flashblocks.base.org/ws
These WebSocket endpoints are for node infrastructure only.Applications should not connect directly to wss://mainnet.flashblocks.base.org/ws. Instead, apps should query your RPC node for Flashblocks data. See the App Integration guide for details.
The base binary listens to the Flashblocks WebSocket stream and caches preconfirmation data. When Flashblocks-aware RPC methods are called, it returns data from this cache. For the full message schema and payload structure, see Flashblocks API Overview.

​
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 Flashblocks-specific methods and WebSocket subscriptions. See the Flashblocks API Reference for the full list, including code examples and parameter details.

​
Enable Historical Proofs RPCs

To serve methods like eth_getProof, debug_executionWitness and debug_executePayload efficiently, you’ll need to set up the historical proofs execution extension (ExEx). This ExEx manages a separate database with data required to serve these methods. This database can add hundreds of GB of additional storage and requires a machine with higher I/O throughput. Most people do not need these RPCs to be available. In order to run the historical proofs ExEx, you simply need to set this environment variable:
Terminal
RETH_HISTORICAL_PROOFS=true
When the node starts up for the first time, it will backfill existing state to the new proofs database in <datadir>/proofs. This process can take a while (24-48 hours for mainnet). To skip the backfill, snapshots of the proofs database are available. See the Snapshots page for download instructions.
The block at which the ExEx first starts will be the earliest block for which these RPCs are available. The flag --rpc.eth-proof-window is ignored when the proofs ExEx is enabled.By default, the ExEx saves 28 days of blocks, but you can customize this by setting RETH_PROOFS_HISTORY_WINDOW=<num_blocks>.

​
Improving Performance

The proofs ExEx performs best when it is within 1024 blocks of the chain tip. This means when syncing up to tip, performance can be degraded. During initial sync on Base Mainnet, the ExEx may fall too far behind to catch up on its own. To fix this, you can run base-consensus in follow mode so it stays within 512 blocks of the proofs ExEx.
Terminal
BASE_NODE_SOURCE_L2_RPC=<trusted_rpc>
BASE_NODE_PROOFS=true
You can verify that the proofs ExEx is syncing efficiently by checking that the state root and execution durations are 0. The ExEx is not executing blocks in this case; instead it’s just writing data from executed blocks to disk.