From 08de43f8700a0dbbbf57feaa730d1f84c077fa32 Mon Sep 17 00:00:00 2001 From: jsvisa Date: Thu, 6 Nov 2025 15:55:36 +0800 Subject: [PATCH 1/9] docs(node): restructed snap sync page --- .../guides/management/snap-sync.mdx | 144 +++++++----------- 1 file changed, 55 insertions(+), 89 deletions(-) diff --git a/node-operators/guides/management/snap-sync.mdx b/node-operators/guides/management/snap-sync.mdx index bffaa3edd..4b73241b0 100644 --- a/node-operators/guides/management/snap-sync.mdx +++ b/node-operators/guides/management/snap-sync.mdx @@ -16,110 +16,76 @@ This means that performing a Snap Sync is significantly faster than performing a ## Enable snap sync for your node -For snap sync, all `op-geth` nodes should expose port `30303` TCP and `30303` UDP to easily find other op-geth nodes to sync from. - * If you set the port with [`--discovery.port`](/node-operators/guides/execution-config#discoveryport), then you must open the port specified for UDP. +For snap sync, all `op-geth` nodes should expose port `30303` TCP and `30303` UDP to easily find other op-geth nodes to sync from. + * If you set the port with [`--discovery.port`](/node-operators/guides/execution-config#discoveryport), then you must open the port specified for UDP. * If you set [`--port`](/node-operators/guides/execution-config#port), then you must open the port specified for TCP. * The only exception is for sequencers and transaction ingress nodes. -Choose one of the following options to enable snap sync: - -* **Option 1:** Snap sync, no required datadir on OP Mainnet. This is the recommended option because `op-node` tells `op-geth` to snap sync and then `op-geth` downloads the state at tip and once complete switches to inserting blocks one by one. - - - - ```shell - --syncmode=execution-layer (not default) - ``` - - - - ```shell - --syncmode=snap (default) - ``` - - - - ```shell - --config op-mainnet - --Sync.SnapSync=true - ``` - - - A single restart of `Nethermind` during Snap Sync may extend the sync time by up to 2 hours because `Nethermind` has to rebuild the caches by reading millions of values from the database. - - - - -* **Option 2:** Archive sync with required [datadir](/operators/node-operators/management/snapshots) for OP Mainnet, but no required datadir for other OP Stack networks. - This option is faster for archive nodes than other options because `--syncmode=full` means `op-geth` executes every block in the chain. - - - - ```shell - --syncmode=execution-layer (not default) - ``` - - - - ```shell - --syncmode=full (not default) - --gcmode=archive (not default) - ``` - - - - Archive sync can be enabled by using the archive configuration for your network (configurations with `_archive` suffix): - ```shell - --config op-mainnet_archive - ``` - - - -* **Option 3:** Continue using current sync approach (before Ecotone) where `op-node` reads from L1 and inserts blocks into the execution client. - This option might be preferred for decentralized developer groups who need to confirm everything on the chain. - - - - ```shell - --syncmode=consensus-layer (default) - ``` - - - - ```shell - --syncmode=full (not default) - ``` - - - - ```shell - --config op-mainnet - --Sync.SnapSync=false - --Sync.FastSync=false - ``` - - +Snap sync requires no datadir on OP Mainnet. With snap sync, `op-node` tells the execution client to snap sync, and then the execution client downloads the state at tip and once complete switches to inserting blocks one by one. + +### Configuration for op-node + +```shell +--syncmode=execution-layer +``` + + + The `--syncmode=execution-layer` flag is not the default setting and must be explicitly configured. + + +### Configuration for op-geth + +```shell +--syncmode=snap +``` + + + The `--syncmode=snap` flag is the default setting for `op-geth`. + + +### Configuration for Nethermind + +```shell +--config op-mainnet +--Sync.SnapSync=true +``` + + + A single restart of `Nethermind` during Snap Sync may extend the sync time by up to 2 hours because `Nethermind` has to rebuild the caches by reading millions of values from the database. + ## Enabling execution layer sync for alternative clients + In addition to `op-geth` and `Nethermind`, you can enable execution-layer syncing with alternative execution clients such as `reth` and `op-erigon`. -Unlike `op-geth` and `Nethermind`, `reth` and `op-erigon` are designed as archive nodes, which means they require the complete history of the chain. +Unlike `op-geth` and `Nethermind`, `reth` and `op-erigon` are designed as archive nodes, which means they require the complete history of the chain. However, these clients can still retrieve block headers and data through the P2P network instead of deriving each individual block, resulting in a faster initial sync. -For OP Mainnet, the [bedrock datadir](/operators/node-operators/management/snapshots) is required. For other OP Stack networks, no datadir is required. +For OP Mainnet, the [bedrock datadir](/operators/node-operators/management/snapshots) is required. For other OP Stack networks, no datadir is required. + +### Configuration for reth -To enable execution layer sync for these clients, set the following flags on `op-node`: ```shell -# for reth ---syncmode=execution-layer (not default) ---l2.enginekind=reth (not default) +--syncmode=execution-layer +--l2.enginekind=reth +``` -# for erigon ---syncmode=execution-layer (not default) ---l2.enginekind=erigon (not default) + + Both flags are not the default setting and must be explicitly configured. + + +### Configuration for op-erigon + +```shell +--syncmode=execution-layer +--l2.enginekind=erigon ``` + + Both flags are not the default setting and must be explicitly configured. + + ## Next steps * See the [Node Configuration](/node-operators/guides/base-config#configuration) guide for additional explanation or customization. From e8fec1244571f56f2339dc1cffe9f95dfd00d9b0 Mon Sep 17 00:00:00 2001 From: jsvisa Date: Thu, 6 Nov 2025 19:10:30 +0800 Subject: [PATCH 2/9] docs(node): add how is snap sync working page --- .../reference/features/snap-sync.mdx | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 node-operators/reference/features/snap-sync.mdx diff --git a/node-operators/reference/features/snap-sync.mdx b/node-operators/reference/features/snap-sync.mdx new file mode 100644 index 000000000..a2127e2ee --- /dev/null +++ b/node-operators/reference/features/snap-sync.mdx @@ -0,0 +1,65 @@ +--- +title: Snap Sync +description: Learn how snap sync works and its benefits for node operators. +--- + +Snap Sync is a native feature of execution clients that significantly improves the experience of syncing an OP Stack node. This section provides an overview of snap sync, its benefits, and links to detailed implementation guides. + +## Overview + +Snap Sync works by downloading a snapshot of the state from other nodes on the network. Instead of re-executing every single block from genesis, the node downloads a recent state snapshot and then starts executing blocks from that point forward. This means that performing a Snap Sync is significantly faster than performing a full sync. + +Both `op-geth` and `Nethermind` support Snap Sync, which can be optionally enabled on `op-node` when using either of these execution clients. + +## Benefits of snap sync + +Snap Sync provides several key benefits for node operators: + +* **No datadir required for OP Mainnet**: Node operators can sync without having to download the [bedrock datadir](/operators/node-operators/management/snapshots). +* **Post-Ecotone network joining**: Nodes can join the network after Ecotone activates without requiring a [blob archiver](/operators/node-operators/management/blobs). +* **Archive node support**: Archive nodes are fully supported with Snap Sync. +* **Faster sync times**: By downloading a state snapshot rather than re-executing all blocks, sync times are dramatically reduced. + +## How snap sync works + + + 1. **Initial state download**: + + * The node connects to peers on the network and requests a snapshot of the current state. + * State data is downloaded in parallel from multiple peers to optimize sync speed. + + 2. **State verification**: + + * The downloaded state is cryptographically verified against the state root in recent block headers. + * This ensures the integrity and correctness of the downloaded state. + + 3. **Block execution**: + + * Once the state snapshot is complete, the node switches to inserting blocks one by one. + * From this point forward, the node processes blocks normally like any other synced node. + + +## Supported execution clients + +Snap Sync is supported by the following execution clients: + +* **op-geth**: Native snap sync support with `--syncmode=snap` (enabled by default) +* **Nethermind**: Native snap sync support with `--Sync.SnapSync=true` +* **reth**: Execution-layer sync support (archive mode) +* **op-erigon**: Execution-layer sync support (archive mode) + +## Network requirements + +For snap sync to work properly, nodes need to be able to discover and connect to peers: + +* **Port requirements**: All `op-geth` nodes should expose port `30303` TCP and `30303` UDP +* **Custom ports**: If using custom ports via `--discovery.port` or `--port`, ensure those ports are properly opened +* **Exceptions**: Sequencers and transaction ingress nodes may have different requirements + +## Links to related pages + +For detailed instructions on enabling and configuring snap sync, refer to the following resources: + +* [Using Snap Sync for Node Operators](/node-operators/guides/management/snap-sync) +* [Using Snap Sync for Chain Operators](/operators/chain-operators/management/snap-sync) +* [Node Configuration Guide](/node-operators/guides/base-config#configuration) From 6254329b4d6725c4143c369dc877b24dfaa91bf6 Mon Sep 17 00:00:00 2001 From: jsvisa Date: Thu, 6 Nov 2025 19:10:50 +0800 Subject: [PATCH 3/9] docs(node): reference to snap sync --- node-operators/guides/management/snap-sync.mdx | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/node-operators/guides/management/snap-sync.mdx b/node-operators/guides/management/snap-sync.mdx index 4b73241b0..d826a4502 100644 --- a/node-operators/guides/management/snap-sync.mdx +++ b/node-operators/guides/management/snap-sync.mdx @@ -3,15 +3,7 @@ title: Using snap sync for node operators description: Learn how to use and enable snap sync on your node. --- -This guide reviews the optional feature of Snap Sync for node operators, including benefits and how to enable the feature. - -Snap Sync significantly improves the experience of syncing an OP Stack node. Snap Sync is a native feature of the execution clients. Both `op-geth` and `nethermind` support Snap Sync, which can be optionally enabled on `op-node` with `op-geth` or `nethermind`. -Snap Sync works by downloading a snapshot of the state from other nodes on the network and is then able to start executing blocks from the completed state rather than having to re-execute every single block. -This means that performing a Snap Sync is significantly faster than performing a full sync. - -* For OP Mainnet, node operators will be able to sync without having to download the [bedrock datadir](/operators/node-operators/management/snapshots). -* This also enables nodes to join the network after Ecotone activates without requiring a [blob archiver](/operators/node-operators/management/blobs). -* Archive nodes are also fully supported. +This guide shows you how to enable and configure Snap Sync for your node. For an overview of how snap sync works and its benefits, see the [Snap Sync feature page](/node-operators/reference/features/snap-sync). ## Enable snap sync for your node @@ -88,6 +80,7 @@ For OP Mainnet, the [bedrock datadir](/operators/node-operators/management/snaps ## Next steps -* See the [Node Configuration](/node-operators/guides/base-config#configuration) guide for additional explanation or customization. +* See the [Snap Sync feature page](/node-operators/reference/features/snap-sync) for an overview of how snap sync works and its benefits. +* See the [Node Configuration](/node-operators/guides/base-config#configuration) guide for additional explanation or customization. * To enable snap sync for your chain, see [Using Snap Sync for Chain Operators](/operators/chain-operators/management/snap-sync). * If you experience difficulty at any stage of this process, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions). From 4da2df347a0a1d1aaf3ee40e7bbb063cbedfd682 Mon Sep 17 00:00:00 2001 From: jsvisa Date: Thu, 6 Nov 2025 19:11:10 +0800 Subject: [PATCH 4/9] docs(all): add snap sync feature page --- docs.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs.json b/docs.json index de97d07ed..41f02c78f 100644 --- a/docs.json +++ b/docs.json @@ -1957,6 +1957,12 @@ "node-operators/reference/architecture/rollup-node" ] }, + { + "group": "Features", + "pages": [ + "node-operators/reference/features/snap-sync" + ] + }, "node-operators/reference/json-rpc", "node-operators/reference/releases" ] From d1c9770a2c8c046f827c37a6a400938afafbfe47 Mon Sep 17 00:00:00 2001 From: jsvisa Date: Thu, 6 Nov 2025 19:25:23 +0800 Subject: [PATCH 5/9] docs(snap): ensure the configs are set in op-node --- node-operators/guides/management/snap-sync.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/node-operators/guides/management/snap-sync.mdx b/node-operators/guides/management/snap-sync.mdx index d826a4502..afc6d5ce6 100644 --- a/node-operators/guides/management/snap-sync.mdx +++ b/node-operators/guides/management/snap-sync.mdx @@ -56,7 +56,9 @@ However, these clients can still retrieve block headers and data through the P2P For OP Mainnet, the [bedrock datadir](/operators/node-operators/management/snapshots) is required. For other OP Stack networks, no datadir is required. -### Configuration for reth +### Configuration for op-node with reth + +Set the following flags on `op-node`: ```shell --syncmode=execution-layer @@ -64,10 +66,12 @@ For OP Mainnet, the [bedrock datadir](/operators/node-operators/management/snaps ``` - Both flags are not the default setting and must be explicitly configured. + Both flags are not the default setting and must be explicitly configured on `op-node`. -### Configuration for op-erigon +### Configuration for op-node with op-erigon + +Set the following flags on `op-node`: ```shell --syncmode=execution-layer @@ -75,7 +79,7 @@ For OP Mainnet, the [bedrock datadir](/operators/node-operators/management/snaps ``` - Both flags are not the default setting and must be explicitly configured. + Both flags are not the default setting and must be explicitly configured on `op-node`. ## Next steps From 05a11419d2e199cc70d88d5b1d3700f71c232078 Mon Sep 17 00:00:00 2001 From: jsvisa Date: Thu, 6 Nov 2025 19:36:12 +0800 Subject: [PATCH 6/9] docs(snap): add archive and consensus sync --- node-operators/guides/management/snap-sync.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/node-operators/guides/management/snap-sync.mdx b/node-operators/guides/management/snap-sync.mdx index afc6d5ce6..31bfd29be 100644 --- a/node-operators/guides/management/snap-sync.mdx +++ b/node-operators/guides/management/snap-sync.mdx @@ -82,6 +82,13 @@ Set the following flags on `op-node`: Both flags are not the default setting and must be explicitly configured on `op-node`. +## Alternative sync modes + +Snap sync is the recommended sync mode for most node operators, but other sync modes are available depending on your needs: + +* **Archive nodes**: If you need to maintain complete historical state, see the [Archive Node guide](/node-operators/guides/management/archive-node) +* **Consensus-layer sync**: For independent L1-based verification without P2P networking, see the [Consensus-Layer Sync reference](/node-operators/reference/consensus-layer-sync) + ## Next steps * See the [Snap Sync feature page](/node-operators/reference/features/snap-sync) for an overview of how snap sync works and its benefits. From 890d57ca8af1212522dcc78b1e663ba5b8893979 Mon Sep 17 00:00:00 2001 From: jsvisa Date: Thu, 6 Nov 2025 19:43:26 +0800 Subject: [PATCH 7/9] docs(guides): add archive-node --- .../guides/management/archive-node.mdx | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 node-operators/guides/management/archive-node.mdx diff --git a/node-operators/guides/management/archive-node.mdx b/node-operators/guides/management/archive-node.mdx new file mode 100644 index 000000000..b6d2c56ce --- /dev/null +++ b/node-operators/guides/management/archive-node.mdx @@ -0,0 +1,118 @@ +--- +title: Running an archive node +description: Learn how to configure and run an archive node. +--- + +This guide shows you how to configure your node to run as an archive node. Archive nodes store the complete history of the blockchain, including all historical states. + +## Overview + +Archive nodes maintain the entire state history of the blockchain, allowing you to query any historical state at any block height. This is useful for: + +* Block explorers that need to provide historical data +* Analytics and data analysis applications +* Services that need to query historical state +* Debugging and auditing purposes + +Archive nodes use execution-layer sync but configure the execution client to retain all historical state data instead of pruning it. + +## Requirements + +* **OP Mainnet**: Requires the [bedrock datadir](/operators/node-operators/management/snapshots) +* **Other OP Stack networks**: No datadir required +* **Storage**: Archive nodes require significantly more disk space than regular nodes (several terabytes for OP Mainnet) +* **Sync time**: Archive sync with execution-layer mode is faster than full block-by-block execution + +## Configuration + +### Configuration for op-node + +Set the following flag on `op-node`: + +```shell +--syncmode=execution-layer +``` + + + The `--syncmode=execution-layer` flag is not the default setting and must be explicitly configured. + + +### Configuration for op-geth + +Set the following flags on `op-geth`: + +```shell +--syncmode=full +--gcmode=archive +``` + + + Both flags are not the default settings and must be explicitly configured. The `--syncmode=full` flag ensures every block is executed, and `--gcmode=archive` disables state pruning. + + +### Configuration for Nethermind + +Archive sync can be enabled by using the archive configuration for your network (configurations with `_archive` suffix): + +```shell +--config op-mainnet_archive +``` + + + Replace `op-mainnet_archive` with the appropriate archive configuration for your network (e.g., `op-sepolia_archive` for OP Sepolia). + + +## Archive mode with alternative clients + +Alternative execution clients such as `reth` and `op-erigon` are designed as archive nodes by default, which means they always maintain the complete history of the chain. When using these clients with execution-layer sync, they will automatically operate in archive mode. + +### Configuration for op-node with reth + +Set the following flags on `op-node`: + +```shell +--syncmode=execution-layer +--l2.enginekind=reth +``` + + + Both flags are not the default setting and must be explicitly configured on `op-node`. `reth` operates as an archive node by default. + + +### Configuration for op-node with op-erigon + +Set the following flags on `op-node`: + +```shell +--syncmode=execution-layer +--l2.enginekind=erigon +``` + + + Both flags are not the default setting and must be explicitly configured on `op-node`. `op-erigon` operates as an archive node by default. + + +## How archive sync works + +With execution-layer sync mode enabled: + +1. **Initial sync**: The node downloads block headers and data through the P2P network +2. **Block execution**: The node executes every block in the chain to build the complete state history +3. **State retention**: Unlike regular nodes, archive nodes never prune historical state data +4. **Faster than legacy**: While still executing all blocks, this is faster than the legacy consensus-layer sync because block data is retrieved via P2P instead of being derived from L1 + +## Storage considerations + +Archive nodes require substantial storage: + +* **OP Mainnet**: Several terabytes and growing +* **Other networks**: Varies by network age and activity +* **Growth rate**: Storage requirements increase continuously as new blocks are added +* **Recommendation**: Use fast SSD storage for optimal performance + +## Next steps + +* See the [Snap Sync guide](/node-operators/guides/management/snap-sync) for non-archive node configuration +* See the [Node Configuration](/node-operators/guides/base-config#configuration) guide for additional explanation or customization +* See the [Snapshots guide](/node-operators/guides/management/snapshots) for information about downloading the bedrock datadir +* If you experience difficulty at any stage of this process, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions) From 6cce04ce65680958624ead6d11a278c0c3cefe5b Mon Sep 17 00:00:00 2001 From: jsvisa Date: Thu, 6 Nov 2025 19:43:40 +0800 Subject: [PATCH 8/9] docs(ref): add consensus sync --- .../reference/consensus-layer-sync.mdx | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 node-operators/reference/consensus-layer-sync.mdx diff --git a/node-operators/reference/consensus-layer-sync.mdx b/node-operators/reference/consensus-layer-sync.mdx new file mode 100644 index 000000000..d18f6e8c3 --- /dev/null +++ b/node-operators/reference/consensus-layer-sync.mdx @@ -0,0 +1,101 @@ +--- +title: Consensus-layer sync +description: Learn about the consensus-layer sync mode. +--- + +This page documents the consensus-layer sync mode, which is the default sync method for op-node but not the recommended approach for most node operators. + +## Overview + +Consensus-layer sync is a sync approach where `op-node` reads transaction data from L1 and derives blocks, then inserts them into the execution client. Unlike execution-layer sync (snap sync), this method does not rely on P2P networking to download state or block data from other L2 nodes. + +While consensus-layer sync is still the default mode, **execution-layer sync (snap sync) is recommended** for faster synchronization and better performance. + +## When to use consensus-layer sync + +This sync mode might be preferred in the following scenarios: + +* **Independent verification**: Decentralized developer groups who need to independently verify the entire chain by deriving all data from L1 +* **No P2P connectivity**: Environments where P2P networking is restricted or unavailable +* **L1-only trust model**: Applications that prefer to trust only L1 data without relying on L2 peer nodes +* **Debugging and research**: Analyzing how blocks are derived from L1 data + + + Consensus-layer sync is significantly slower than execution-layer sync (snap sync). For most node operators, [snap sync](/node-operators/guides/management/snap-sync) is the recommended approach for faster synchronization. + + +## Configuration + +### Configuration for op-node + +Set the following flag on `op-node`: + +```shell +--syncmode=consensus-layer +``` + + + The `--syncmode=consensus-layer` is the default setting for `op-node`. You don't need to specify it explicitly unless you want to be explicit about the sync mode or are overriding a different configuration. + + +### Configuration for op-geth + +Set the following flag on `op-geth`: + +```shell +--syncmode=full +``` + + + The `--syncmode=full` flag is not the default setting and must be explicitly configured. This ensures blocks are inserted by `op-node` rather than synced via P2P. + + +### Configuration for Nethermind + +Set the following flags on `Nethermind`: + +```shell +--config op-mainnet +--Sync.SnapSync=false +--Sync.FastSync=false +``` + + + Replace `op-mainnet` with the appropriate configuration for your network (e.g., `op-sepolia` for OP Sepolia). + + +## How consensus-layer sync works + +The consensus-layer sync process: + +1. **L1 monitoring**: `op-node` continuously monitors the L1 chain for transaction batches +2. **Block derivation**: `op-node` derives L2 blocks from the L1 transaction data +3. **Block insertion**: Derived blocks are inserted into the execution client one by one +4. **State building**: The execution client builds state by executing each block sequentially + +This approach ensures that every block is derived from L1 and independently verified, but it's much slower than downloading state snapshots from peers. + +## Performance considerations + +* **Sync time**: Significantly slower than snap sync or archive sync with execution-layer mode +* **Network requirements**: Requires reliable L1 RPC access but minimal L2 P2P connectivity +* **Resource usage**: Lower P2P bandwidth usage but more L1 RPC calls +* **OP Mainnet**: For OP Mainnet, you'll still need the [bedrock datadir](/operators/node-operators/management/snapshots) for state before the Bedrock upgrade + +## Comparison with other sync modes + +| Feature | Consensus-Layer (Legacy) | Execution-Layer (Snap Sync) | Archive with Execution-Layer | +|---------|-------------------------|----------------------------|------------------------------| +| Data source | L1 only | L2 P2P + L1 | L2 P2P + L1 | +| Sync speed | Slowest | Fastest | Medium | +| State pruning | Yes (by default) | Yes | No | +| Historical state | Not available | Not available | Full history | +| P2P required | No | Yes | Yes | +| Verification | Full L1 derivation | Cryptographic verification | Full execution | + +## Next steps + +* See the [Snap Sync guide](/node-operators/guides/management/snap-sync) for the recommended fast sync method +* See the [Archive Node guide](/node-operators/guides/management/archive-node) for running an archive node +* See the [Node Configuration](/node-operators/guides/base-config#configuration) guide for additional explanation or customization +* If you experience difficulty at any stage of this process, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions) From 85208435208ed6fec9823392964463e595a635ef Mon Sep 17 00:00:00 2001 From: jsvisa Date: Thu, 6 Nov 2025 19:43:52 +0800 Subject: [PATCH 9/9] docs(all): add index page --- docs.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs.json b/docs.json index 41f02c78f..92d439f9f 100644 --- a/docs.json +++ b/docs.json @@ -1925,6 +1925,7 @@ { "group": "Management", "pages": [ + "node-operators/guides/management/archive-node", "node-operators/guides/management/blobs", "node-operators/guides/management/regenesis-history", "node-operators/guides/management/snap-sync", @@ -1964,6 +1965,7 @@ ] }, "node-operators/reference/json-rpc", + "node-operators/reference/consensus-layer-sync", "node-operators/reference/releases" ] }