From 83f5c30a5e93f0fa3feacd64b2d97ceed3b42155 Mon Sep 17 00:00:00 2001 From: Danyal Prout Date: Tue, 7 Apr 2026 11:19:20 -0500 Subject: [PATCH 1/2] chore: add base v1 migration docs --- .../node-operators/base-v1-upgrade.mdx | 156 ++++++++++++++++++ docs/docs.json | 1 + 2 files changed, 157 insertions(+) create mode 100644 docs/base-chain/node-operators/base-v1-upgrade.mdx diff --git a/docs/base-chain/node-operators/base-v1-upgrade.mdx b/docs/base-chain/node-operators/base-v1-upgrade.mdx new file mode 100644 index 000000000..50bc35713 --- /dev/null +++ b/docs/base-chain/node-operators/base-v1-upgrade.mdx @@ -0,0 +1,156 @@ +--- +title: "Base V1 Upgrade" +description: "Migrate your Base node to base-reth-node and base-consensus for V1." +--- + + +Base V1 is an upgrade that introduces Osaka features on Base and TEE/ZK proof systems. It requires migrating to Base-native clients. + + +Only `base-reth-node` (EL) and `base-consensus` (CL) support V1. **Nodes running `op-node`, `op-geth`, `op-reth`, `nethermind`, or `kona` will not support the network upgrade and must be migrated before activation.** + +For full details on what's included, see the [V1 specification](https://specs.base.org/upgrades/v1/overview). + +## Activation Timeline + +| Network | Date | Timestamp | +|---------|------|-----------| +| Sepolia | April 20, 2026 18:00 UTC | `1776708000` | +| Mainnet | Early May 2026 | TBD | + +## Required Software + +| Layer | Software | Version | +|-------|----------|---------| +| Execution (EL) | [`base-reth-node`](https://github.com/base/node/releases) | v0.7.0+ | +| Consensus (CL) | [`base-consensus`](https://github.com/base/node/releases) | v0.7.0+ | + + +Both clients are available from the [base/node](https://github.com/base/node/releases) repository, where most configuration is preconfigured and can be overridden via environment variables. See the `.env.mainnet` and `.env.sepolia` files for the full list of configurable options. + +If you build from the [base/base](https://github.com/base/base/releases) repository directly, you will need to update your `base-consensus` configuration to use the new `BASE_NODE_*` environment variables. For `base-reth-node`, you can continue to use all existing Reth tooling and configuration as before. + + +## Migrating Execution Layer + +### Migrating from OP Reth + +If you are already running OP Reth via [base/node](https://github.com/base/node), 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: + + ```bash + docker compose down + ``` + +2. Update to the latest version of [base/node](https://github.com/base/node): + + ```bash + git pull origin main + ``` + +3. Start your node: + + ```bash + docker compose up + ``` + +4. Verify client version: `web3_clientVersion` should include `base` in the version string (e.g. `reth/v1.11.3-.../base/v0.7.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: + + ```bash + docker compose down + ``` + +2. Update to the latest version of [base/node](https://github.com/base/node): + + ```bash + 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](/base-chain/node-operators/snapshots) to avoid a full sync. + +6. Start your node: + + ```bash + 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: + + ```bash + docker compose up + ``` + +4. Verify: + - Check consensus logs: `docker compose logs -f node` + - Confirm sync status: `optimism_syncStatus` continues to work + +### Environment Variable Mapping + +If you use [base/node](https://github.com/base/node), most variables are already set in `.env.mainnet` and `.env.sepolia`. If you build from [base/base](https://github.com/base/base), 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](/base-chain/node-operators/snapshots) to bootstrap. +- **Do OP namespace RPCs still work?** Yes, all existing RPCs are supported. diff --git a/docs/docs.json b/docs/docs.json index 24de1a340..9b8b57f53 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -141,6 +141,7 @@ { "group": "Node Operators", "pages": [ + "base-chain/node-operators/base-v1-upgrade", "base-chain/node-operators/run-a-base-node", "base-chain/node-operators/performance-tuning", "base-chain/node-operators/snapshots", From 347abe60f5e0855e05d630afc57da53e5a67397b Mon Sep 17 00:00:00 2001 From: Danyal Prout Date: Wed, 8 Apr 2026 11:01:51 -0500 Subject: [PATCH 2/2] chore: update binary links to base/base v0.7.0 release --- docs/base-chain/node-operators/base-v1-upgrade.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/base-chain/node-operators/base-v1-upgrade.mdx b/docs/base-chain/node-operators/base-v1-upgrade.mdx index 50bc35713..2bd6444a2 100644 --- a/docs/base-chain/node-operators/base-v1-upgrade.mdx +++ b/docs/base-chain/node-operators/base-v1-upgrade.mdx @@ -22,8 +22,8 @@ For full details on what's included, see the [V1 specification](https://specs.ba | Layer | Software | Version | |-------|----------|---------| -| Execution (EL) | [`base-reth-node`](https://github.com/base/node/releases) | v0.7.0+ | -| Consensus (CL) | [`base-consensus`](https://github.com/base/node/releases) | v0.7.0+ | +| Execution (EL) | [`base-reth-node`](https://github.com/base/base/releases/tag/v0.7.0) | v0.7.0+ | +| Consensus (CL) | [`base-consensus`](https://github.com/base/base/releases/tag/v0.7.0) | v0.7.0+ | Both clients are available from the [base/node](https://github.com/base/node/releases) repository, where most configuration is preconfigured and can be overridden via environment variables. See the `.env.mainnet` and `.env.sepolia` files for the full list of configurable options.