Mainnet and Testnet Configurations in Base: A Complete Technical Guide

The primary difference between mainnet and testnet configurations in Base lies in the environment variables that define chain identifiers, sequencer endpoints, and L1 RPC requirements, all managed through separate .env.mainnet and .env.sepolia files.

The base/node repository provides Docker infrastructure for running an Optimism-compatible L2 node on the Base network. Whether connecting to the live production chain or the Sepolia testing environment, the node relies on environment-specific configuration files to establish correct network parameters, consensus rules, and data sources.

Core Configuration Files

Base nodes use two distinct environment files located in the repository root to separate network concerns:

• .env.mainnet – Defines parameters for the Base Mainnet production environment
• .env.sepolia – Defines parameters for the Base Sepolia Testnet environment

Both files follow identical structural patterns but specify different values for chain identification, endpoints, and network flags. The docker-compose.yml file reads these variables through the NETWORK_ENV environment variable, defaulting to .env.mainnet when unspecified.

Chain and Network Identification

Chain Identifier Configuration

The execution client uses the RETH_CHAIN variable to determine which blockchain data to serve and validate.

In .env.mainnet:

RETH_CHAIN=base

In .env.sepolia:

RETH_CHAIN=base-sepolia

OP Stack Network Parameters

The consensus layer requires explicit network declarations to load the correct rollup configuration and validate blocks against the appropriate L2 contracts.

Mainnet configuration:

OP_NODE_NETWORK=base-mainnet
OP_GETH_OP_NETWORK=base-mainnet

Testnet configuration:

OP_NODE_NETWORK=base-sepolia
OP_GETH_OP_NETWORK=base-sepolia

These variables ensure the OP-node validates state roots against the correct set of rollup contracts deployed on either mainnet or Sepolia Ethereum.

Sequencer and RPC Endpoints

Sequencer HTTP Configuration

The sequencer provides the source of L2 block data. Using the wrong endpoint results in invalid or empty data ingestion.

Mainnet endpoints:

RETH_SEQUENCER_HTTP=https://mainnet-sequencer.base.org
OP_SEQUENCER_HTTP=https://mainnet-sequencer.base.org

Testnet endpoints:

RETH_SEQUENCER_HTTP=https://sepolia-sequencer.base.org
OP_SEQUENCER_HTTP=https://sepolia-sequencer.base.org

L1 RPC Requirements

The OP_NODE_L1_ETH_RPC variable must point to an Ethereum L1 endpoint that matches the target L2 network. For Mainnet configurations, this must be a mainnet Ethereum RPC (e.g., https://mainnet.infura.io). For Testnet configurations, it must point to a Sepolia Ethereum RPC (e.g., https://sepolia.infura.io).

Mismatched L1 RPC endpoints break block verification because finality proofs and state roots derive from L1 data specific to each chain.

Optional Features and Shared Components

Flashblocks and Network-Specific Services

Optional features like Flashblocks reference network-specific service URLs. While the variable names remain identical across both files, the values change based on the target environment:

# Mainnet

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

# Testnet

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

Engine RPC and Bootnode Configuration

Several components remain identical between networks:

• Engine RPC: OP_NODE_L2_ENGINE_RPC=ws://execution:8551 remains constant, though the underlying execution client (reth, geth, or nethermind) connects to different data sources based on the chain identifier
• P2P Bootstrap Nodes: The list of ENR bootnode addresses is structurally identical, but the embedded network identifiers inside each ENR differ to prevent cross-network peer connections

How to Switch Between Mainnet and Testnet

Switching networks requires selecting the appropriate environment file and ensuring your L1 RPC endpoint matches the target chain.

Launching Mainnet (Default)

docker compose up --build

This command automatically sources .env.mainnet as the default configuration.

Launching Testnet (Sepolia)

NETWORK_ENV=.env.sepolia docker compose up --build

The NETWORK_ENV variable instructs Docker Compose to source the testnet configuration instead of the default mainnet file.

Overriding L1 RPC Endpoints

Override the L1 RPC endpoint at runtime to point to your specific infrastructure provider:

Mainnet with custom RPC:

NETWORK_ENV=.env.mainnet OP_NODE_L1_ETH_RPC=https://mainnet.infura.io/v3/PROJECT_ID \
docker compose up --build

Testnet with custom RPC:

NETWORK_ENV=.env.sepolia OP_NODE_L1_ETH_RPC=https://sepolia.infura.io/v3/PROJECT_ID \
docker compose up --build

Enabling Flashblocks on Testnet

NETWORK_ENV=.env.sepolia RETH_FB_WEBSOCKET_URL=wss://sepolia.flashblocks.base.org/ws \
docker compose up --build

Summary

• Environment Files: Base separates mainnet and testnet configurations through .env.mainnet and .env.sepolia, accessed via the NETWORK_ENV variable
• Chain Identification: RETH_CHAIN and OP_NODE_NETWORK values differ (base vs base-sepolia, base-mainnet vs base-sepolia)
• Endpoint Isolation: Sequencer URLs and L1 RPC endpoints must match the target network to ensure valid block verification and data ingestion
• Infrastructure Consistency: Engine RPC settings, bootnode lists, and Docker Compose infrastructure remain structurally identical between networks

Frequently Asked Questions

What files control mainnet and testnet configurations in Base?

The base/node repository uses two primary environment files: .env.mainnet for production Mainnet settings and .env.sepolia for Sepolia Testnet settings. These files reside in the repository root and define all network-specific variables including chain identifiers, sequencer endpoints, and optional feature URLs.

Can I use the same L1 RPC endpoint for both Base Mainnet and Base Testnet?

No, the L1 RPC endpoint must match the target L2 network. Mainnet configurations require a mainnet Ethereum RPC endpoint, while testnet configurations require a Sepolia Ethereum RPC endpoint. Mismatched endpoints will cause block verification failures because the OP-node cannot validate finality proofs against the wrong L1 chain state.

How do I enable Flashblocks when running a Base Testnet node?

Set the RETH_FB_WEBSOCKET_URL environment variable to the Sepolia-specific Flashblocks endpoint when launching the container: wss://sepolia.flashblocks.base.org/ws. You can pass this directly in the Docker Compose command or modify the .env.sepolia file before startup.

Are the P2P bootstrap nodes different between Mainnet and Testnet?

The list of bootstrap node ENRs (Ethereum Node Records) is structurally identical in both configuration files, but the underlying network identifiers embedded within each ENR differ. This design prevents mainnet nodes from accidentally peering with testnet nodes while maintaining operational consistency in the configuration syntax.

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