From d69e73c4b8adf5cd440e1fdd57e13026654f6e07 Mon Sep 17 00:00:00 2001 From: corey Date: Fri, 12 Jun 2026 11:22:23 +0800 Subject: [PATCH 1/4] docs(node-operation): single node type + DERIVATION_VERIFY_MODE (morph-l2/morph#988) - Remove the separate "validator node" page; there is one node type now. - Document DERIVATION_VERIFY_MODE on the node page: local (default, rebuild + compare versioned hashes vs L1) vs layer1 (pull beacon blob + derive via engine, equivalent to the former validator). Remind operators to set layer1 for the old validator-like L1-derivation behavior. - Drop the now-removed `make run-validator` commands from the docker upgrade guide. - Remove validator-node entry from the node-operators sidebar. Ref morph-l2/morph#966 (Feat: Sequencer Final PR) for the verify-mode behavior. --- .../full-node/1-run-in-docker.md | 23 +++ .../upgrade-node/2-upgrade-node-docker.md | 6 - .../validator-node/1-run-in-docker.md | 168 ------------------ sidebars.js | 1 - 4 files changed, 23 insertions(+), 175 deletions(-) delete mode 100644 docs/build-on-morph/developer-resources/node-operation/validator-node/1-run-in-docker.md diff --git a/docs/build-on-morph/developer-resources/node-operation/full-node/1-run-in-docker.md b/docs/build-on-morph/developer-resources/node-operation/full-node/1-run-in-docker.md index 3b06b375..e8636dd6 100644 --- a/docs/build-on-morph/developer-resources/node-operation/full-node/1-run-in-docker.md +++ b/docs/build-on-morph/developer-resources/node-operation/full-node/1-run-in-docker.md @@ -8,6 +8,10 @@ import TabItem from '@theme/TabItem'; This guide will help you start a full node using [run-morph-node](https://github.com/morph-l2/run-morph-node). +:::info Single node type +There is no longer a separate "validator node" to run. Every node verifies the chain against L1; the verification method is selected by `DERIVATION_VERIFY_MODE`. If you want a node that derives blocks from L1 like the former validator, set it to `layer1` — see [Batch verification mode](#batch-verification-mode) below. +::: + :::tip Already running a node? If you are upgrading an existing **zkTrie node**, do **not** redeploy from scratch. Follow the [zkTrie -> MPT migration](../upgrade-node/0-zktrie-to-mpt-migration.md) guide instead. ::: @@ -179,6 +183,25 @@ curl http://localhost:26657/status When `catching_up` is `false`, the node has finished syncing. +### Batch verification mode + +Every node verifies batches against L1. The method is controlled by `DERIVATION_VERIFY_MODE` in `morph-node/.env` / `.env_hoodi`: + +| Mode | Behavior | +|------|----------| +| `local` (default) | Rebuilds blob bytes from local L2 blocks and compares versioned hashes against L1. No beacon-blob fetch on the happy path — lighter weight. | +| `layer1` | Pulls the L1 beacon blob, decodes it, and derives blocks via the engine. This is equivalent to the **former validator node** that derives from L1. | + +:::tip Want the old validator behavior? +If you want a node that derives from L1 the way the previous validator node did, set `DERIVATION_VERIFY_MODE=layer1` in your env file. The default (`local`) is sufficient for most operators. +::: + +If a node detects a mismatch between the sequencer's submission and its own verification, it logs a line such as: + +``` +root hash or withdrawal hash is not equal originStateRootHash=0x... deriveStateRootHash=0x... +``` + ## Advanced Usage ### Customizing the data directory diff --git a/docs/build-on-morph/developer-resources/node-operation/upgrade-node/2-upgrade-node-docker.md b/docs/build-on-morph/developer-resources/node-operation/upgrade-node/2-upgrade-node-docker.md index 6819c0a2..de1cf782 100644 --- a/docs/build-on-morph/developer-resources/node-operation/upgrade-node/2-upgrade-node-docker.md +++ b/docs/build-on-morph/developer-resources/node-operation/upgrade-node/2-upgrade-node-docker.md @@ -56,12 +56,6 @@ make stop-node make run-node ``` -If you are running a **validator**, use these commands instead: -```bash -make stop-validator -make run-validator -``` - :::note Ensure that the startup parameters for the Docker container remain consistent with your previous configuration. If you previously used a custom setup, verify that the configuration and directory paths match your earlier setup. For details, please refer to [**Advanced Usage**](../full-node/1-run-in-docker.md#advanced-usage) ::: diff --git a/docs/build-on-morph/developer-resources/node-operation/validator-node/1-run-in-docker.md b/docs/build-on-morph/developer-resources/node-operation/validator-node/1-run-in-docker.md deleted file mode 100644 index 124e4baf..00000000 --- a/docs/build-on-morph/developer-resources/node-operation/validator-node/1-run-in-docker.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Run a validator node -lang: en-US ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -This guide covers running a Morph validator node using [run-morph-node](https://github.com/morph-l2/run-morph-node). If you are unfamiliar with validator duties, refer to the [optimistic zkEVM](../../../../how-morph-works/3-optimistic-zkevm.md) design overview. - -## Quick Start - -### 1. Clone the repository - - - - -```bash -git clone https://github.com/morph-l2/run-morph-node.git -cd run-morph-node/morph-node -``` - - - - -```bash -git clone --recurse-submodules https://github.com/morph-l2/run-morph-node.git -cd run-morph-node/morph-node -make build -``` - - - - -### 2. Configure L1 RPC endpoints - -A validator requires L1 access to fetch rollup data. Set the following in `morph-node/.env` (mainnet) or `morph-node/.env_hoodi` (Hoodi): - -```bash -L1_ETH_RPC= -L1_BEACON_CHAIN_RPC= -``` - -### 3. Select a snapshot version (optional) - -The default snapshot is pre-configured in `morph-node/.env` / `morph-node/.env_hoodi`. To use a different version, update the following variables in the env file before downloading: - -```bash -# Snapshot name (find available versions in the repo README) -MAINNET_MPT_SNAPSHOT_NAME=mpt-snapshot-YYYYMMDD-N # mainnet -HOODI_MPT_SNAPSHOT_NAME=mpt-snapshot-YYYYMMDD-N # Hoodi - -# Heights must match your snapshot — find the correct values in the repo README -DERIVATION_START_HEIGHT= -L1_MSG_START_HEIGHT= -MORPH_NODE_DERIVATION_BASE_HEIGHT= -``` - -See [Snapshot Information](https://github.com/morph-l2/run-morph-node?tab=readme-ov-file#snapshot-information) for available snapshots and their corresponding height values. - -### 4. Download the snapshot - - - - -```bash -make download-and-decompress-mainnet-snapshot -``` - - - - -```bash -make download-and-decompress-hoodi-snapshot -``` - - - - -### 5. Set up the snapshot data - - - - -```bash -mv ./mpt-snapshot-*/geth ../mainnet/geth-data -mkdir -p ../mainnet/node-data/data -mv ./mpt-snapshot-*/data/* ../mainnet/node-data/data -``` - - - - -```bash -mv ./mpt-snapshot-*/geth ../hoodi/geth-data -mkdir -p ../hoodi/node-data/data -mv ./mpt-snapshot-*/data/* ../hoodi/node-data/data -``` - - - - -### 6. Run the validator - - - - -```bash -make run-validator - -# To stop: -make stop-validator - -# To remove containers: -make rm-validator -``` - - - - -```bash -make run-hoodi-validator - -# To stop: -make stop-validator - -# To remove containers: -make rm-validator -``` - - - - -```bash -make run-validator-binary - -# To stop: -make stop-binary -``` - - - - -```bash -make run-hoodi-validator-binary - -# To stop: -make stop-binary -``` - - - - -## Verify the Node - -```bash -# Check sync status -curl http://localhost:26657/status -``` - -When `catching_up` is `false`, the node is in sync. If the validator detects a state root mismatch, you will see a log line like: - -``` -root hash or withdrawal hash is not equal originStateRootHash=0x... deriveStateRootHash=0x... -``` - -This means the validator found an inconsistency between the sequencer submission and its own derivation. - diff --git a/sidebars.js b/sidebars.js index a500c21a..67bf9584 100644 --- a/sidebars.js +++ b/sidebars.js @@ -174,7 +174,6 @@ const NodeOperatorsSidebar = [ collapsed: false, items: [ 'build-on-morph/developer-resources/node-operation/full-node/run-in-docker', - 'build-on-morph/developer-resources/node-operation/validator-node/run-in-docker', ], }, { From bfcf72dbeeb1c4b8bdbfa50f35b9cd56be7bc212 Mon Sep 17 00:00:00 2001 From: corey Date: Mon, 15 Jun 2026 14:29:27 +0800 Subject: [PATCH 2/4] docs(node-operation): remove deprecated zkTrie->MPT migration guide Mainnet/Hoodi have been on MPT for a long time; the migration guide is no longer needed. Remove the page, its sidebar entry, and the inbound links from the full-node page (tip) and prune-state (caution). --- .../node-operation/1-prune-state.md | 2 +- .../full-node/1-run-in-docker.md | 4 -- .../upgrade-node/0-zktrie-to-mpt-migration.md | 49 ------------------- sidebars.js | 1 - 4 files changed, 1 insertion(+), 55 deletions(-) delete mode 100644 docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-zktrie-to-mpt-migration.md diff --git a/docs/build-on-morph/developer-resources/node-operation/1-prune-state.md b/docs/build-on-morph/developer-resources/node-operation/1-prune-state.md index 7c51cc49..98d7dc38 100644 --- a/docs/build-on-morph/developer-resources/node-operation/1-prune-state.md +++ b/docs/build-on-morph/developer-resources/node-operation/1-prune-state.md @@ -29,7 +29,7 @@ After switching to MPT storage, pruning is only supported after the node has syn ### zkTrie Nodes (legacy) :::caution -This section only applies to nodes still running with zkTrie state storage **before** migrating to MPT. Once you switch to an MPT node, the zkTrie prune command is no longer supported. See the [zkTrie -> MPT migration guide](./upgrade-node/0-zktrie-to-mpt-migration.md) for details. +This section only applies to nodes still running with zkTrie state storage **before** migrating to MPT. Once you switch to an MPT node, the zkTrie prune command is no longer supported. ::: For nodes still running with zkTrie state storage, use the zkTrie-specific prune command: diff --git a/docs/build-on-morph/developer-resources/node-operation/full-node/1-run-in-docker.md b/docs/build-on-morph/developer-resources/node-operation/full-node/1-run-in-docker.md index e8636dd6..11517f82 100644 --- a/docs/build-on-morph/developer-resources/node-operation/full-node/1-run-in-docker.md +++ b/docs/build-on-morph/developer-resources/node-operation/full-node/1-run-in-docker.md @@ -12,10 +12,6 @@ This guide will help you start a full node using [run-morph-node](https://github There is no longer a separate "validator node" to run. Every node verifies the chain against L1; the verification method is selected by `DERIVATION_VERIFY_MODE`. If you want a node that derives blocks from L1 like the former validator, set it to `layer1` — see [Batch verification mode](#batch-verification-mode) below. ::: -:::tip Already running a node? -If you are upgrading an existing **zkTrie node**, do **not** redeploy from scratch. Follow the [zkTrie -> MPT migration](../upgrade-node/0-zktrie-to-mpt-migration.md) guide instead. -::: - ## Hardware Requirements | Resource | Minimum | diff --git a/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-zktrie-to-mpt-migration.md b/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-zktrie-to-mpt-migration.md deleted file mode 100644 index 9f61df45..00000000 --- a/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-zktrie-to-mpt-migration.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "zkTrie -> MPT Migration" -lang: en-US ---- - -This page focuses on one task: migrating a node from **zkTrie** state storage to **MPT**. - -## What changes with MPT - -- **State format changes** from zkTrie to MPT. -- **Data is not reusable** across formats. -- **Migration is one-way** for data directories. - -::::danger -Do **not** reuse an existing zkTrie data directory for an MPT node. Prepare a fresh MPT data directory or restore from an MPT snapshot. -:::: - -## Pick your path - -### 1) Fresh deployment - -If you are deploying a new node, use the full node guide directly (MPT is the default path): - -- [Run a full node](../full-node/1-run-in-docker.md) - -### 2) Existing zkTrie node, binary update only - -If you want to keep zkTrie storage for now, update binaries and restart using the same startup command. - -- **Host:** [Upgrade node running on the host](./1-upgrade-node-host.md) -- **Docker:** [Upgrade node running from docker](./2-upgrade-node-docker.md) - -### 3) Existing zkTrie node, migrate to MPT - -If you want to switch storage to MPT: - -1. Stop the current node. -2. Prepare a fresh MPT data directory (or restore an MPT snapshot). -3. Start the node with MPT configuration. - -For setup details, follow: - -- [Run a full node](../full-node/1-run-in-docker.md) - -## Quick checks - -- **Can I reuse zkTrie data?** No. -- **Can I roll back MPT data to zkTrie?** No, there is no supported data rollback path. -- **Where are snapshot versions and matching heights?** See [Snapshot Information](https://github.com/morph-l2/run-morph-node?tab=readme-ov-file#snapshot-information). diff --git a/sidebars.js b/sidebars.js index 67bf9584..9c9f6918 100644 --- a/sidebars.js +++ b/sidebars.js @@ -181,7 +181,6 @@ const NodeOperatorsSidebar = [ label: 'Upgrade Node', collapsed: false, items: [ - 'build-on-morph/developer-resources/node-operation/upgrade-node/zktrie-to-mpt-migration', 'build-on-morph/developer-resources/node-operation/upgrade-node/upgrade-node-host', 'build-on-morph/developer-resources/node-operation/upgrade-node/upgrade-node-docker', ], From 15b0bbac4fa43091f5db0b4c7ebea341acc9c8de Mon Sep 17 00:00:00 2001 From: corey Date: Mon, 15 Jun 2026 15:09:44 +0800 Subject: [PATCH 3/4] docs(node-operation): add centralized sequencer upgrade guide New Upgrade Node page for operators with an already-running node: in-place upgrade steps, env vars now required for all nodes, DERIVATION_VERIFY_MODE (local default / layer1 = former validator), and a caution to upgrade before the consensus switch height. --- .../0-centralized-sequencer-upgrade.md | 80 +++++++++++++++++++ sidebars.js | 1 + 2 files changed, 81 insertions(+) create mode 100644 docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-centralized-sequencer-upgrade.md diff --git a/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-centralized-sequencer-upgrade.md b/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-centralized-sequencer-upgrade.md new file mode 100644 index 00000000..4d93f45c --- /dev/null +++ b/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-centralized-sequencer-upgrade.md @@ -0,0 +1,80 @@ +--- +title: Upgrade to the centralized sequencer +lang: en-US +--- + +Morph has moved node operation to a **centralized sequencer** architecture. This page summarizes what changed for node operators and how to upgrade an existing node. + +:::tip +If you are setting up a node from scratch, just follow [Run a full node](../full-node/1-run-in-docker.md) — it already reflects the centralized-sequencer setup. This page is for operators upgrading an existing node. +::: + +## What changed + +- **Single node type.** There is no longer a separate *validator node*. Every node runs the same way (`make run-node`) and verifies the chain against L1. The `validator` Docker Compose service and the `make run-validator` / `stop-validator` / `*-validator-binary` targets have been removed. +- **Batch verification is now configurable** via `DERIVATION_VERIFY_MODE` (see below). The previous validator behavior — deriving from L1 — is now an opt-in mode rather than a separate node. +- **Some environment variables are now required for every node** (previously only the validator set them). + +## Environment variables + +### New + +| Variable | Default | Purpose | +|----------|---------|---------| +| `DERIVATION_VERIFY_MODE` | `local` | Batch verification mode. `local` rebuilds the blob from local L2 blocks and compares versioned hashes against L1 (no beacon fetch on the happy path). `layer1` pulls the L1 beacon blob, decodes it, and derives blocks via the engine — **equivalent to the former validator node**. Leave empty for the default. | + +:::tip Want the old validator behavior? +If you previously ran a validator node to derive from L1, set `DERIVATION_VERIFY_MODE=layer1` in your env file. Otherwise the default (`local`) is sufficient for most operators. +::: + +### Now required for all nodes + +These were only needed by the validator before; every node needs them now: + +| Variable | Purpose | +|----------|---------| +| `L1_BEACON_CHAIN_RPC` | L1 beacon chain RPC endpoint. | +| `L1MESSAGEQUEUE_CONTRACT` | Deposit (L1 message queue) contract address. | +| `DERIVATION_START_HEIGHT` | Must match your snapshot (see the run-morph-node README). | +| `L2_BASE_HEIGHT` | Must match your snapshot. | + +### Not operator configuration + +Do **not** set `L1_SEQUENCER_CONTRACT` or `CONSENSUS_SWITCH_HEIGHT`. These use per-network hard-coded defaults in the binary. Setting them (especially `CONSENSUS_SWITCH_HEIGHT=-1`) would override the built-in consensus-switch activation height. + +## If your node is already running + +This is an **in-place upgrade** — your existing MPT data is preserved, so there is no need to re-download a snapshot or resync from scratch. You swap the node image/binary, adjust the env file, and restart. + +:::caution Upgrade before the consensus switch height +The network switches consensus from the Tendermint validator set to the centralized sequencer at a fixed L2 block height that is built into the new release. A node still running the **old** binary when the chain reaches that height will stop following the chain correctly. **Upgrade before the network reaches the switch height** to avoid downtime. +::: + +Steps: + +1. **Pull the updated node image / binary** that includes the centralized-sequencer changes — bump the `node` image tag in `morph-node/docker-compose.yml` (Docker), or pull the new source and `make build` (binary). +2. **Stop your current node:** + + ```bash + make stop-node # Docker + # or: make stop-binary (binary mode) + ``` + + If you were running a validator, stop it — there is no separate validator service anymore; you will start a single node. +3. **Update your env file** (`morph-node/.env` or `.env_hoodi`) to include the variables now required for all nodes (`L1_BEACON_CHAIN_RPC`, `L1MESSAGEQUEUE_CONTRACT`, `DERIVATION_START_HEIGHT`, `L2_BASE_HEIGHT`). If you previously ran a plain full node without `L1_BEACON_CHAIN_RPC`, add it now. +4. **(Optional) choose a verification mode.** Set `DERIVATION_VERIFY_MODE=layer1` to keep the former validator's L1-derivation behavior; otherwise leave it unset for the default (`local`). +5. **Restart the node** (it resumes from your existing data): + + ```bash + make run-node # mainnet + make run-hoodi-node # Hoodi + ``` +6. **Confirm it is following the chain** — see [Verify](#verify) below. + +## Verify + +Check sync status as usual (see [Run a full node → Verify the Node](../full-node/1-run-in-docker.md#verify-the-node)). Every node verifies batches against L1; if it detects a mismatch you will see a log line such as: + +``` +root hash or withdrawal hash is not equal originStateRootHash=0x... deriveStateRootHash=0x... +``` diff --git a/sidebars.js b/sidebars.js index 9c9f6918..cc6bf1a0 100644 --- a/sidebars.js +++ b/sidebars.js @@ -181,6 +181,7 @@ const NodeOperatorsSidebar = [ label: 'Upgrade Node', collapsed: false, items: [ + 'build-on-morph/developer-resources/node-operation/upgrade-node/centralized-sequencer-upgrade', 'build-on-morph/developer-resources/node-operation/upgrade-node/upgrade-node-host', 'build-on-morph/developer-resources/node-operation/upgrade-node/upgrade-node-docker', ], From 1ca5cd4ae008ce69e01717d70746f65fa603a9fe Mon Sep 17 00:00:00 2001 From: corey Date: Mon, 15 Jun 2026 15:15:44 +0800 Subject: [PATCH 4/4] =?UTF-8?q?docs:=20refine=20centralized-sequencer=20up?= =?UTF-8?q?grade=20=E2=80=94=20only=20L1=5FBEACON=5FCHAIN=5FRPC=20is=20new?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Confirmed against morph node/derivation/config.go: BeaconRpc is the only required field (errors if empty); rollup/deposit/heights use per-network defaults. So upgrading the binary is enough; former validators just add DERIVATION_VERIFY_MODE=layer1. --- .../0-centralized-sequencer-upgrade.md | 56 ++++++------------- 1 file changed, 18 insertions(+), 38 deletions(-) diff --git a/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-centralized-sequencer-upgrade.md b/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-centralized-sequencer-upgrade.md index 4d93f45c..10ccb9f2 100644 --- a/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-centralized-sequencer-upgrade.md +++ b/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-centralized-sequencer-upgrade.md @@ -13,63 +13,43 @@ If you are setting up a node from scratch, just follow [Run a full node](../full - **Single node type.** There is no longer a separate *validator node*. Every node runs the same way (`make run-node`) and verifies the chain against L1. The `validator` Docker Compose service and the `make run-validator` / `stop-validator` / `*-validator-binary` targets have been removed. - **Batch verification is now configurable** via `DERIVATION_VERIFY_MODE` (see below). The previous validator behavior — deriving from L1 — is now an opt-in mode rather than a separate node. -- **Some environment variables are now required for every node** (previously only the validator set them). +- **Almost no new configuration.** Everything except the L1 beacon RPC endpoint uses per-network defaults baked into the binary, so for most operators upgrading the binary is enough. ## Environment variables -### New +For most operators the **only** variable you may need to add is `L1_BEACON_CHAIN_RPC`. Everything else (rollup / deposit contract addresses, derivation heights) uses per-network defaults selected by the network flag — you don't need to set them. -| Variable | Default | Purpose | -|----------|---------|---------| -| `DERIVATION_VERIFY_MODE` | `local` | Batch verification mode. `local` rebuilds the blob from local L2 blocks and compares versioned hashes against L1 (no beacon fetch on the happy path). `layer1` pulls the L1 beacon blob, decodes it, and derives blocks via the engine — **equivalent to the former validator node**. Leave empty for the default. | +| Variable | Required? | Notes | +|----------|-----------|-------| +| `L1_BEACON_CHAIN_RPC` | **Yes** | L1 beacon chain RPC endpoint. The node exits at startup without it — add it if your node doesn't already have one. | +| `DERIVATION_VERIFY_MODE` | Optional | Batch verification mode. Default `local` (rebuild blob from local L2 blocks and compare versioned hashes against L1). Set `layer1` to pull the L1 beacon blob and derive via the engine — **equivalent to the former validator node**. | -:::tip Want the old validator behavior? -If you previously ran a validator node to derive from L1, set `DERIVATION_VERIFY_MODE=layer1` in your env file. Otherwise the default (`local`) is sufficient for most operators. +:::tip Were you running a validator? +A validator was simply a node that derives from L1. To keep that behavior, add a single variable — `DERIVATION_VERIFY_MODE=layer1`. Nothing else changes. ::: -### Now required for all nodes - -These were only needed by the validator before; every node needs them now: - -| Variable | Purpose | -|----------|---------| -| `L1_BEACON_CHAIN_RPC` | L1 beacon chain RPC endpoint. | -| `L1MESSAGEQUEUE_CONTRACT` | Deposit (L1 message queue) contract address. | -| `DERIVATION_START_HEIGHT` | Must match your snapshot (see the run-morph-node README). | -| `L2_BASE_HEIGHT` | Must match your snapshot. | - -### Not operator configuration - -Do **not** set `L1_SEQUENCER_CONTRACT` or `CONSENSUS_SWITCH_HEIGHT`. These use per-network hard-coded defaults in the binary. Setting them (especially `CONSENSUS_SWITCH_HEIGHT=-1`) would override the built-in consensus-switch activation height. +Do **not** set `L1_SEQUENCER_CONTRACT` or `CONSENSUS_SWITCH_HEIGHT` — they use per-network hard-coded defaults; setting them (especially `CONSENSUS_SWITCH_HEIGHT=-1`) would override the built-in consensus-switch activation height. ## If your node is already running -This is an **in-place upgrade** — your existing MPT data is preserved, so there is no need to re-download a snapshot or resync from scratch. You swap the node image/binary, adjust the env file, and restart. +This is an **in-place upgrade** — your existing data is preserved, so there is no need to re-download a snapshot or resync. In most cases you simply swap the binary/image and restart. :::caution Upgrade before the consensus switch height -The network switches consensus from the Tendermint validator set to the centralized sequencer at a fixed L2 block height that is built into the new release. A node still running the **old** binary when the chain reaches that height will stop following the chain correctly. **Upgrade before the network reaches the switch height** to avoid downtime. +The network switches consensus from the Tendermint validator set to the centralized sequencer at a fixed L2 block height built into the new release. Upgrade in good time, before the chain reaches that height, so your node follows the switch without interruption. ::: Steps: -1. **Pull the updated node image / binary** that includes the centralized-sequencer changes — bump the `node` image tag in `morph-node/docker-compose.yml` (Docker), or pull the new source and `make build` (binary). -2. **Stop your current node:** - - ```bash - make stop-node # Docker - # or: make stop-binary (binary mode) - ``` - - If you were running a validator, stop it — there is no separate validator service anymore; you will start a single node. -3. **Update your env file** (`morph-node/.env` or `.env_hoodi`) to include the variables now required for all nodes (`L1_BEACON_CHAIN_RPC`, `L1MESSAGEQUEUE_CONTRACT`, `DERIVATION_START_HEIGHT`, `L2_BASE_HEIGHT`). If you previously ran a plain full node without `L1_BEACON_CHAIN_RPC`, add it now. -4. **(Optional) choose a verification mode.** Set `DERIVATION_VERIFY_MODE=layer1` to keep the former validator's L1-derivation behavior; otherwise leave it unset for the default (`local`). -5. **Restart the node** (it resumes from your existing data): +1. **Pull the updated node image / binary** — bump the `node` image tag in `morph-node/docker-compose.yml` (Docker), or pull the new source and `make build` (binary). +2. **Make sure `L1_BEACON_CHAIN_RPC` is set** in your env file (`morph-node/.env` or `.env_hoodi`). A former validator already has it; a plain full node that ran without it must add it now. No other variables need changing. +3. **Former validators only:** add `DERIVATION_VERIFY_MODE=layer1` to keep deriving from L1. Otherwise the default (`local`) applies — nothing to set. +4. **Restart the node** (it resumes from your existing data): ```bash - make run-node # mainnet - make run-hoodi-node # Hoodi + make stop-node && make run-node # mainnet (Docker) + make stop-node && make run-hoodi-node # Hoodi (Docker) ``` -6. **Confirm it is following the chain** — see [Verify](#verify) below. +5. **Confirm it is following the chain** — see [Verify](#verify) below. ## Verify