Node Upgrade Guide

Migrate your Base node to base-reth-node and base-consensus for Azul.

Azul activated on mainnet on May 28, 2026 18:00 UTC (1779991200). See the required software versions and full activation timestamps on the Azul overview.

Only base-reth-node (EL) and base-consensus (CL) support Azul. Nodes running op-node, op-geth, op-reth, nethermind, or kona must be migrated using the instructions below.

Both clients are now published from the base/base repository, which hosts the root docker-compose.yml and the .env.mainnet / .env.sepolia templates that operators previously pulled from base/node. Most configuration is preconfigured and can be overridden via environment variables — see those .env files for the full list of options.

docker compose up pulls the published ghcr.io/base/node image; pass --build to compile the current tree, or set NODE_TAG=vX.Y.Z to pin a specific released image without a source build.

Migrating Execution Layer

Migrating from OP Reth

If you are already running OP Reth via the operator compose setup, update to the latest version and your node will automatically use base-reth-node. Your existing ./reth-data directory is fully compatible — no re-sync or snapshot restore is needed.

1. Stop your node:

   docker compose down
   

2. Switch to base/base (the operator node is no longer published from base/node) and update to the latest version:

   # If you previously cloned base/node, clone base/base alongside it and copy over your .env file:
   git clone https://github.com/base/base.git
   cp ../node/.env.mainnet ./base/.env.mainnet   # or .env.sepolia
   
   # If you already track base/base:
   git pull origin main
   

3. Start your node:

   docker compose up
   

4. Verify client version: web3_clientVersion should include base in the version string (e.g. reth/v1.11.3-.../base/v0.9.0)

Migrating from another client

op-geth and nethermind are no longer supported. You will need to start fresh with base-reth-node.

1. Stop your node:

   docker compose down
   

2. Clone or update base/base:

   git clone https://github.com/base/base.git
   # or, if already cloned:
   git pull origin main
   

3. Remove your old data directory (e.g. ./geth-data or ./nethermind-data).

4. Edit the .env.mainnet or .env.sepolia file to match your preferences.

5. Bootstrap from a Reth snapshot to avoid a full sync.

6. Start your node:

   docker compose up
   

Migrating Consensus Layer

Replace op-node with base-consensus by updating your environment variables.

1. Set USE_BASE_CONSENSUS=true in your .env file.

2. Update your .env file with the new BASE_NODE_* environment variables (see tables below).

3. Restart your node:

   docker compose up
   

4. Verify:

   • Check consensus logs: docker compose logs -f node
   • Confirm sync status: optimism_syncStatus continues to work

Environment Variable Mapping

Most variables are already set in the base/base .env.mainnet and .env.sepolia templates. If you are migrating a custom op-node setup, use the table below to map your op-node environment variables to base-consensus. Most are optional. Run base-consensus node --help for the full list.

op-node	base-consensus
OP_NODE_NETWORK	BASE_NODE_NETWORK
OP_NODE_ROLLUP_CONFIG	BASE_NODE_ROLLUP_CONFIG
—	BASE_NODE_LOG_VERBOSITY
—	BASE_NODE_LOG_FORMAT
OP_NODE_L1_ETH_RPC	BASE_NODE_L1_ETH_RPC
OP_NODE_L1_BEACON	BASE_NODE_L1_BEACON
OP_NODE_L1_TRUST_RPC	BASE_NODE_L1_TRUST_RPC
OP_NODE_L2_ENGINE_RPC	BASE_NODE_L2_ENGINE_RPC
OP_NODE_L2_ENGINE_AUTH	BASE_NODE_L2_ENGINE_AUTH
—	BASE_NODE_L2_ENGINE_AUTH_ENCODED
OP_NODE_P2P_BOOTNODES	BASE_NODE_P2P_BOOTNODES
OP_NODE_P2P_LISTEN_IP	BASE_NODE_P2P_LISTEN_IP
OP_NODE_P2P_LISTEN_TCP_PORT	BASE_NODE_P2P_LISTEN_TCP_PORT
OP_NODE_P2P_LISTEN_UDP_PORT	BASE_NODE_P2P_LISTEN_UDP_PORT
OP_NODE_P2P_ADVERTISE_IP	BASE_NODE_P2P_ADVERTISE_IP
OP_NODE_P2P_ADVERTISE_TCP	BASE_NODE_P2P_ADVERTISE_TCP_PORT
OP_NODE_P2P_ADVERTISE_UDP	BASE_NODE_P2P_ADVERTISE_UDP_PORT
OP_NODE_P2P_PRIV_PATH	BASE_NODE_P2P_PRIV_PATH
OP_NODE_P2P_PEER_SCORING	BASE_NODE_P2P_SCORING
OP_NODE_P2P_PEER_BANNING	BASE_NODE_P2P_BAN_PEERS
OP_NODE_P2P_PEER_BANNING_THRESHOLD	BASE_NODE_P2P_BAN_THRESHOLD
OP_NODE_P2P_PEER_BANNING_DURATION	BASE_NODE_P2P_BAN_DURATION
OP_NODE_METRICS_ENABLED	BASE_NODE_METRICS_ENABLED
OP_NODE_METRICS_ADDR	BASE_NODE_METRICS_ADDR
OP_NODE_METRICS_PORT	BASE_NODE_METRICS_PORT
OP_NODE_RPC_ADDR	BASE_NODE_RPC_ADDR
OP_NODE_RPC_PORT	BASE_NODE_RPC_PORT
OP_NODE_RPC_ENABLE_ADMIN	BASE_NODE_RPC_ENABLE_ADMIN
OP_NODE_RPC_ADMIN_STATE	BASE_NODE_RPC_ADMIN_STATE
OP_NODE_SAFEDB_PATH	BASE_NODE_SAFEDB_PATH
OP_NODE_SYNCMODE	—
OP_NODE_VERIFIER_L1_CONFS	—
OP_NODE_L2_ENGINE_KIND	—
OP_NODE_L1_RPC_KIND	—
OP_NODE_L1_BEACON_FETCH_ALL_SIDECARS	—
OP_NODE_L1_BEACON_FALLBACKS	—
OP_NODE_ROLLUP_LOAD_PROTOCOL_VERSIONS	—
OP_NODE_P2P_STATIC	—
OP_NODE_P2P_DISABLE	—
OP_NODE_P2P_NAT	—

FAQ

• Do I need to re-sync? Not if you are already running OP Reth. Existing data is compatible.
• What if I’m on op-geth or nethermind? You need to switch to base-reth-node. Use a Reth snapshot to bootstrap.
• Do OP namespace RPCs still work? Yes, all existing RPCs are supported.