Node Upgrade Guide

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.

​

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.

​

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.