morph-l2 · curryxbo · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
@@ -4,17 +4,43 @@ lang: en-US
 ---
 The performance of a full node will degrade when the storage size reaches a high volume. We suggest that the fullnode always keep light storage by pruning the storage.
 
-### How to Prune
-
-1. Stop the node, including the consensus client(morphnode) and the execution client(geth)
-2. Run ```nohup geth snapshot prune-zk-state --datadir "$GETH_DB_DIR" > prune.log &```. It will take 5~7 hours to finish.
-3. Start the node once it is done. 
+:::note
+To prune a Geth node at least 200 GB of free disk space is recommended. This means pruning cannot be used to save a hard drive that has been completely filled. A good rule of thumb is to prune before the node fills ~80% of the available disk space.
+:::
 
 The hardware is important, **make sure the SSD meets: solid-state drive(SSD), 8k IOPS, 500 MB/S throughput, read latency < 1ms.**
 
+### MPT Nodes (post-Jade Fork)
+
+After the [Jade Fork](./upgrade-node/0-jade-fork-overview.md), nodes run with `--morph-mpt` and use standard MPT state storage. Use the standard prune command:
+
 :::note
-To prune a Geth node at least 200 GB of free disk space is recommended. This means pruning cannot be used to save a hard drive that has been completely filled. A good rule of thumb is to prune before the node fills ~80% of the available disk space.
+After switching to MPT storage, pruning is only supported after the node has synced **at least 128 blocks**. Do not attempt to prune immediately after migration.
 :::
 
+1. Stop the node, including the consensus client (`morphnode`) and the execution client (`geth`).
+2. Run the prune command:
+   ```bash
+   nohup geth snapshot prune-state --datadir "$GETH_DB_DIR" > prune.log &
+   ```
+   It will take several hours to finish.
+3. Start the node once it is done.
+
+### zkTrie Nodes (pre-Jade Fork)
+
+:::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 [Jade Fork Overview](./upgrade-node/0-jade-fork-overview.md) for details.
+:::
+
+For nodes still running with zkTrie state storage, use the zkTrie-specific prune command:
+
+1. Stop the node, including the consensus client (`morphnode`) and the execution client (`geth`).
+2. Run the prune command:
+   ```bash
+   nohup geth snapshot prune-zk-state --datadir "$GETH_DB_DIR" > prune.log &
+   ```
+   It will take 5~7 hours to finish.
+3. Start the node once it is done.
+
 
 
@@ -1,173 +1,169 @@
 ---
-title: Run a full node with docker
+title: Run a full node
 lang: en-US
 ---
 
-This guide will help you start a full node running in the docker container using [run-morph-node](https://github.com/morph-l2/run-morph-node)
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
-## Quick Start
+This guide will help you start a full node using [run-morph-node](https://github.com/morph-l2/run-morph-node).
 
-:::note
-The instructions outlined below detail the procedure for running a full node on the mainnet. To set up and operate a **Hoodi node**, you need to follow the tutorial on [`sync node from snapshot`](#sync-node-from-snapshot).
+:::tip Already running a node?
+If you are upgrading an existing **zkTrie node**, do **not** redeploy from scratch. Follow the [Upgrade & Forks](../upgrade-node/0-jade-fork-overview.md) guide instead.
 :::
 
-1. Clone the dockerfile repository
+## Hardware Requirements
+
+| Resource | Minimum |
+|----------|---------|
+| CPU | 4+ cores |
+| RAM | 32 GB |
+| Disk | 1 TB SSD |
+| Network | 25+ Mbit/s download |
+
+## Quick Start
+
+### 1. Clone the repository
+
+<Tabs>
+<TabItem value="docker" label="Docker">
 
 ```bash
 git clone https://github.com/morph-l2/run-morph-node.git
+cd run-morph-node/morph-node
 ```
-2. Run the following command
+
+</TabItem>
+<TabItem value="binary" label="Binary">
 
 ```bash
-cd morph-node
-make run-node
+git clone --recurse-submodules https://github.com/morph-l2/run-morph-node.git
+cd run-morph-node/morph-node
+make build
 ```
 
-The command `make run-node` takes the `../mainnet` as your node's **Home** directory by default. There will be two folders in the **Home** directory named `geth-data` and `node-data`, serving as data directories for the execution client and consensus client of the Morph node, respectively.
+Building `geth` requires a C compiler (gcc / clang).
 
-This command will also generate the `secret-jwt.txt` file under **Home** directory for the authentication during RPC calls between the execution client and consensus client.
+</TabItem>
+</Tabs>
 
-## Advanced Usage
+### 2. Download the snapshot
 
-With the [Quick Start](#quick-start) guide above, you can quickly start a node using the default configuration files. However, we also support customizing the node's data directory and parameter settings.
+<Tabs>
+<TabItem value="mainnet" label="Mainnet">
 
-### Customizing Data Directory
-The host directory paths that are mounted by the Docker container are specified in the ```morph-node/.env``` file.
+```bash
+make download-and-decompress-mainnet-snapshot
+```
 
-```js title="morph-node/.env"
-// HOME folder for morph node
-MORPH_HOME=../mainnet
-// Flag indicates the network for execution client.
-MORPH_FLAG=morph
-// Location of the jwt file for the authentication between clients
-JWT_SECRET_FILE=${MORPH_HOME}/jwt-secret.txt
-// The entrypoint shell script for start execution client  
-GETH_ENTRYPOINT_FILE=./entrypoint-geth.sh
-// The snapshot name for Morph node 
-MAINNET_SNAPSHOT_NAME=snapshot-20241218-1
+</TabItem>
+<TabItem value="hoodi" label="Hoodi">
 
-......
+```bash
+make download-and-decompress-hoodi-snapshot
 ```
 
-You have the flexibility to customize the directory paths as per your requirements. 
+</TabItem>
+</Tabs>
 
-Please note that if you have customized the **HOME** directory of your node, you need to copy the necessary configuration files to this directory. Specifically, you should copy the `node-data` and `geth-data` from `./mainnet` to your **HOME** directory.
+### 3. Set up the snapshot data
 
-:::note
-For running a testnet node, the ```morph-node/.env_hoodi``` file should be used instead of the ```morph-node/.env``` file.
-:::
+<Tabs>
+<TabItem value="mainnet" label="Mainnet">
 
-### Customizing parameters
-
-The default configuration required for mainnet node startup is located in the `./mainnet` directory, while the files under `./hoodi` directory is used for testnet node startup. 
-
-```javascript
-└── mainnet
-    ├── geth-data
-    │   └── static-nodes.json
-    └── node-data
-        ├── config
-        │   ├── config.toml
-        │   └── genesis.json
-        └── data
-
-// for testnet nodes
-└── hoodi
-    ├── geth-data
-    │   └── static-nodes.json
-    └── node-data
-        ├── config
-        │   ├── config.toml
-        │   └── genesis.json
-        └── data
+```bash
+mv ./mpt-snapshot-*/geth ../mainnet/geth-data
+mkdir -p ../mainnet/node-data/data
+mv ./mpt-snapshot-*/data/* ../mainnet/node-data/data
 ```
 
-If you wish to modify the Geth startup command, you can do so by editing the ```./morph-node/entrypoint-geth.sh``` file. For adjustments to the Tendermint-related configuration parameters, you should modify the `node-data/config/config.toml` file.
+</TabItem>
+<TabItem value="hoodi" label="Hoodi">
+
+```bash
+mv ./mpt-snapshot-*/geth ../hoodi/geth-data
+mkdir -p ../hoodi/node-data/data
+mv ./mpt-snapshot-*/data/* ../hoodi/node-data/data
+```
 
-## Sync node from snapshot
+</TabItem>
+</Tabs>
 
-We suggest starting your node sync from a snapshot to speed up the process of syncing your node to the latest state. 
+### 4. Run the node
 
-### Clone the dockerfile repository
+<Tabs>
+<TabItem value="docker" label="Docker — Mainnet">
 
 ```bash
-git clone https://github.com/morph-l2/run-morph-node.git
+make run-node
 ```
 
-### Acquire the snapshot you need
+</TabItem>
+<TabItem value="docker-hoodi" label="Docker — Hoodi">
 
-The `morph-node/.env` configuration file in the repository you just cloned is designed for setting up the Morph node on the mainnet. By default, it is pre-configured to use the latest snapshot.
+```bash
+make run-hoodi-node
+```
 
-If you need a historical snapshot, you must manually update the **SNAPSHOT_NAME** in the `morph-node/.env` file. (Note: For the **testnet**, the corresponding file is `morph-node/.env_hoodi`.)
+</TabItem>
+<TabItem value="binary" label="Binary — Mainnet">
 
-- **Fetch historical snapshot(Optional)**:
-    
-    The historical snapshots are recorded in [snapshot-information](https://github.com/morph-l2/run-morph-node?tab=readme-ov-file#snapshot-information)
+```bash
+make run-node-binary
+```
 
-    ```js
-    // ...
+</TabItem>
+<TabItem value="binary-hoodi" label="Binary — Hoodi">
 
-    MAINNET_SNAPSHOT_NAME={your expected snapshot name} 
+```bash
+make run-hoodi-node-binary
+```
 
-    // ...
-    ```
+</TabItem>
+</Tabs>
 
-- **Execute download and decompress the snapshot for your network**:
-
-    Run the following command to download and decompress the snapshot for your network:
+To stop a binary-mode node:
 
-    **For mainnet**:
+```bash
+make stop-binary
+```
 
-    ```
-    cd ./morph-node
-    make download-and-decompress-mainnet-snapshot
-    ```
+:::info Running a ZK (legacy) node?
+Use `make run-zk-node` (Docker) or `make run-zk-node-binary` (Binary) instead.
+:::
 
-    **For testnet**:
+## Verify the Node
 
-    ```
-    cd ./morph-node
-    make download-and-decompress-hoodi-snapshot
-    ```
+```bash
+# Check geth peer connections
+curl -X POST -H 'Content-Type: application/json' \
+  --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":74}' \
+  localhost:8545
 
-    The command will assist you in downloading and decompressing the snapshot archive.
+# Check consensus client sync status
+curl http://localhost:26657/status
+```
 
-### Set up the snapshot data
+When `catching_up` is `false`, the node has finished syncing.
 
-After downloading, locate the snapshot by placing the decompressed data files in the correct directory specified by the **MORPH_HOME** path in your `.env` file. Ensure the data files align with the node's expected structure to allow seamless synchronization.
+## Advanced Usage
 
-For example, if the snapshot folder is named ```snapshot-20241218-1```, 
-- move the directory ```snapshot-20241218-1/geth``` to the ```${MORPH_HOME}/geth-data``` directory 
-- move the contents from ```snapshot-20241218-1/data``` to the ```${NODE_DATA_DIR}/data``` directory.
+### Customizing the data directory
 
-```
-mv ./morph-node/snapshot-20241218-1/geth ${MORPH_HOME}/geth-data
-mv ./morph-node/snapshot-20241218-1/data/* ${MORPH_HOME}/node-data/data
-```
+By default, data is stored under `../mainnet` or `../hoodi`. To use a different path, set `MORPH_HOME` in the env file:
 
-The folder structure will be like 
-
-```javascript
-└── ${MORPH_HOME}
-    ├── geth-data // data directory for geth
-    │   └── static-nodes.json
-    │   └── geth // directory from snapshot/geth   
-    └── node-data // data directory for node
-        ├── config
-        │   ├── config.toml
-        │   └── genesis.json
-        └── data // data directory from snapshot/node
+```bash
+MORPH_HOME=/your/custom/path
 ```
 
-### 4. Run the Node
-With the snapshot and configuration files ready, navigate to the `morph-node` folder under your cloned repository, and start the node using the provided command
+### Customizing geth flags
 
-```
-make run-node
-```
+Edit `morph-node/entrypoint-geth.sh` to change geth startup flags.
 
-For testnet, run
+:::tip
+`entrypoint-geth.sh` sets `--gcmode=archive` by default. Remove or change it to run a pruned node. Geth's default (without the flag) is full node mode.
+:::
 
-```
-make run-hoodi-node
-```
+### Sync from genesis
+
+You can skip the snapshot steps and run the node directly. This is much slower and **not recommended** for most operators.