From b0ab100f77d785cd6e7048e75b3164476b19a74a Mon Sep 17 00:00:00 2001 From: Erhnysr Date: Mon, 6 Apr 2026 22:47:00 +0300 Subject: [PATCH 1/4] docs: add RPC usage clarification note Adds a clarification note about using the correct RPC endpoint when building on Base. --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index d3d19bbbb..52dd475ce 100644 --- a/README.md +++ b/README.md @@ -164,3 +164,6 @@ The core team will review opened PRs. The SLA is 2 weeks, generally on a first-c ## Storybook for UI components See `storybook/README.md` for details on local Storybook and component docs. +## Additional Note + +When building on Base, always ensure that you are using the correct RPC endpoint for the intended network (mainnet or testnet). Misconfiguration can lead to failed transactions or unexpected behavior. From c9ee43302749f95022e11e02b08b5205cf3ec15f Mon Sep 17 00:00:00 2001 From: Erhnysr Date: Fri, 22 May 2026 22:48:20 +0300 Subject: [PATCH 2/4] docs(azul): add BASE_NODE_L2_ENGINE_AUTH_RAW to env mapping table and FAQ BASE_NODE_L2_ENGINE_AUTH_RAW was missing from the op-node to base-consensus environment variable mapping table, and there was no guidance in the FAQ about setting a secure JWT secret. Operators migrating from op-node need to know that: - BASE_NODE_L2_ENGINE_AUTH_RAW must be explicitly set - The default placeholder value is insecure for nodes using host networking or custom port mappings - A secure value can be generated with: openssl rand -hex 32 Related to base/node#1087 --- docs/base-chain/specs/upgrades/azul/node-upgrade.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx b/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx index a16c3f575..680d6bcc6 100644 --- a/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx +++ b/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx @@ -107,6 +107,7 @@ If you use [base/node](https://github.com/base/node), most variables are already | `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_RAW` | | — | `BASE_NODE_L2_ENGINE_AUTH_ENCODED` | | `OP_NODE_P2P_BOOTNODES` | `BASE_NODE_P2P_BOOTNODES` | | `OP_NODE_P2P_LISTEN_IP` | `BASE_NODE_P2P_LISTEN_IP` | @@ -141,6 +142,7 @@ If you use [base/node](https://github.com/base/node), most variables are already ## FAQ +- **Do I need to set `BASE_NODE_L2_ENGINE_AUTH_RAW`?** Yes — this must be set to a secure random hex string shared between the execution and consensus containers. Generate one with `openssl rand -hex 32`. Nodes using host networking or custom port mappings that rely on the default placeholder value are exposed to unauthenticated Engine API access. - **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. From 877eb600d447dfe2e3248979a3a73250fa2a8a69 Mon Sep 17 00:00:00 2001 From: Erhnysr Date: Thu, 4 Jun 2026 23:48:15 +0300 Subject: [PATCH 3/4] revert: remove generic README note, keep only engine-auth-raw fix --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 52dd475ce..d3d19bbbb 100644 --- a/README.md +++ b/README.md @@ -164,6 +164,3 @@ The core team will review opened PRs. The SLA is 2 weeks, generally on a first-c ## Storybook for UI components See `storybook/README.md` for details on local Storybook and component docs. -## Additional Note - -When building on Base, always ensure that you are using the correct RPC endpoint for the intended network (mainnet or testnet). Misconfiguration can lead to failed transactions or unexpected behavior. From ba7aa3ff2cc7c7de6211d5f7fc67c0c8b53027de Mon Sep 17 00:00:00 2001 From: Erhnysr Date: Thu, 4 Jun 2026 23:53:33 +0300 Subject: [PATCH 4/4] docs(azul): add health check, rollback, troubleshooting sections and verify commands --- .../specs/upgrades/azul/node-upgrade.mdx | 130 +++++++++++++++--- 1 file changed, 111 insertions(+), 19 deletions(-) diff --git a/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx b/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx index 680d6bcc6..6dedb8a69 100644 --- a/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx +++ b/docs/base-chain/specs/upgrades/azul/node-upgrade.mdx @@ -29,23 +29,29 @@ If you are already running OP Reth via [base/node](https://github.com/base/node) 1. Stop your node: - ```bash +```bash docker compose down - ``` +``` 2. Update to the latest version of [base/node](https://github.com/base/node): - ```bash +```bash git pull origin main - ``` +``` 3. Start your node: - ```bash +```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.9.0`) +4. Verify client version: `web3_clientVersion` should include `base` in the version string (e.g. `reth/v1.11.3-.../base/v0.9.0`): + +```bash + curl -s -X POST http://localhost:8545 \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' +``` ### Migrating from another client @@ -53,15 +59,15 @@ If you are already running OP Reth via [base/node](https://github.com/base/node) 1. Stop your node: - ```bash +```bash docker compose down - ``` +``` 2. Update to the latest version of [base/node](https://github.com/base/node): - ```bash +```bash git pull origin main - ``` +``` 3. Remove your old data directory (e.g. `./geth-data` or `./nethermind-data`). @@ -71,9 +77,9 @@ If you are already running OP Reth via [base/node](https://github.com/base/node) 6. Start your node: - ```bash +```bash docker compose up - ``` +``` ## Migrating Consensus Layer @@ -85,19 +91,28 @@ Replace `op-node` with `base-consensus` by updating your environment variables. 3. Restart your node: - ```bash +```bash docker compose up - ``` +``` + +4. Verify sync status: -4. Verify: - - Check consensus logs: `docker compose logs -f node` - - Confirm sync status: `optimism_syncStatus` continues to work +```bash + # Check consensus logs + docker compose logs -f node + + # Confirm sync status via RPC + curl -s -X POST http://localhost:7545 \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' +``` ### 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` | @@ -140,9 +155,86 @@ If you use [base/node](https://github.com/base/node), most variables are already | `OP_NODE_P2P_DISABLE` | — | | `OP_NODE_P2P_NAT` | — | +## Post-Upgrade Health Check + +After migrating, confirm your node is operating correctly: + +```bash +# 1. Check both containers are running +docker compose ps + +# 2. Verify EL client version includes 'base' +curl -s -X POST http://localhost:8545 \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' \ + | jq '.result' + +# 3. Check sync status (unsafe_l2 block number should be advancing) +curl -s -X POST http://localhost:7545 \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' \ + | jq '{unsafe: .result.unsafe_l2.number, safe: .result.safe_l2.number}' + +# 4. Check peer count (should be > 0) +curl -s -X POST http://localhost:8545 \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' \ + | jq '.result' +``` + +## Rollback + +If you need to revert to your previous setup before activation: + +```bash +# 1. Stop the node +docker compose down + +# 2. Roll back to previous git state +git checkout + +# 3. Restart +docker compose up +``` + + +Rollback is only possible **before** the Azul activation timestamp. After activation, nodes running pre-Azul clients will not follow the canonical chain. + + +## Troubleshooting + +**Node fails to start after update** + +Check logs for configuration errors: +```bash +docker compose logs node | tail -50 +``` +Ensure `USE_BASE_CONSENSUS=true` is set and all required `BASE_NODE_*` variables are present in your `.env` file. + +**`web3_clientVersion` does not include `base`** + +You may still be running `op-reth`. Confirm `git pull origin main` completed cleanly and re-run `docker compose up --build`. + +**Sync stalled or `unsafe_l2` not advancing** + +Check L1 RPC connectivity and confirm `BASE_NODE_L1_ETH_RPC` is reachable. A peer count of 0 suggests a network or firewall issue on your P2P port. + +**`BASE_NODE_L2_ENGINE_AUTH_RAW` not set** + +Generate a secure value and add it to your `.env` file: +```bash +echo "BASE_NODE_L2_ENGINE_AUTH_RAW=$(openssl rand -hex 32)" >> .env +``` + +**`optimism_syncStatus` returns an error** + +Confirm the consensus RPC port (default `7545`) is exposed and `BASE_NODE_RPC_PORT` matches your configuration. + ## FAQ - **Do I need to set `BASE_NODE_L2_ENGINE_AUTH_RAW`?** Yes — this must be set to a secure random hex string shared between the execution and consensus containers. Generate one with `openssl rand -hex 32`. Nodes using host networking or custom port mappings that rely on the default placeholder value are exposed to unauthenticated Engine API access. - **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. +- **Can I run `base-reth-node` and `op-node` together temporarily?** No. `op-node` will not support Azul. Both layers must be migrated together before activation. +- **Where do I get help?** Join the [Base Discord](https://discord.gg/buildonbase) and post in `🛠｜node-operators`, or open an issue on [base/node](https://github.com/base/node/issues). \ No newline at end of file