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 3b06b375..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 @@ -8,8 +8,8 @@ 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). -:::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. +:::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. ::: ## Hardware Requirements @@ -179,6 +179,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/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..10ccb9f2 --- /dev/null +++ b/docs/build-on-morph/developer-resources/node-operation/upgrade-node/0-centralized-sequencer-upgrade.md @@ -0,0 +1,60 @@ +--- +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. +- **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 + +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 | 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 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. +::: + +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 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 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** — 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 stop-node && make run-node # mainnet (Docker) + make stop-node && make run-hoodi-node # Hoodi (Docker) + ``` +5. **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/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/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..cc6bf1a0 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', ], }, { @@ -182,7 +181,7 @@ 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/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', ],