Skip to content

docs(node): restruct the snap sync #1851

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Nov 16, 2025
+361 −99
Merged

docs(node): restruct the snap sync #1851

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
08de43f
docs(node): restructed snap sync page
jsvisa Nov 6, 2025
e8fec12
docs(node): add how is snap sync working page
jsvisa Nov 6, 2025
6254329
docs(node): reference to snap sync
jsvisa Nov 6, 2025
4da2df3
docs(all): add snap sync feature page
jsvisa Nov 6, 2025
d1c9770
docs(snap): ensure the configs are set in op-node
jsvisa Nov 6, 2025
05a1141
docs(snap): add archive and consensus sync
jsvisa Nov 6, 2025
890d57c
docs(guides): add archive-node
jsvisa Nov 6, 2025
6cce04c
docs(ref): add consensus sync
jsvisa Nov 6, 2025
8520843
docs(all): add index page
jsvisa Nov 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -1957,7 +1958,14 @@
"node-operators/reference/architecture/rollup-node"
]
},
{
"group": "Features",
"pages": [
"node-operators/reference/features/snap-sync"
]
},
"node-operators/reference/json-rpc",
"node-operators/reference/consensus-layer-sync",
"node-operators/reference/releases"
]
}
Expand Down
118 changes: 118 additions & 0 deletions node-operators/guides/management/archive-node.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```

<Info>
The `--syncmode=execution-layer` flag is not the default setting and must be explicitly configured.
</Info>

### Configuration for op-geth

Set the following flags on `op-geth`:

```shell
--syncmode=full
--gcmode=archive
```

<Info>
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.
</Info>

### 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
```

<Info>
Replace `op-mainnet_archive` with the appropriate archive configuration for your network (e.g., `op-sepolia_archive` for OP Sepolia).
</Info>

## 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
```

<Info>
Both flags are not the default setting and must be explicitly configured on `op-node`. `reth` operates as an archive node by default.
</Info>

### Configuration for op-node with op-erigon

Set the following flags on `op-node`:

```shell
--syncmode=execution-layer
--l2.enginekind=erigon
```

<Info>
Both flags are not the default setting and must be explicitly configured on `op-node`. `op-erigon` operates as an archive node by default.
</Info>

## 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)
168 changes: 69 additions & 99 deletions node-operators/guides/management/snap-sync.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,125 +3,95 @@ 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

<Info>
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.
</Info>

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.

<Tabs items={['op-node', 'op-geth', 'Nethermind']}>
<Tabs.Tab>
```shell
--syncmode=execution-layer (not default)
```
</Tabs.Tab>

<Tabs.Tab>
```shell
--syncmode=snap (default)
```
</Tabs.Tab>

<Tabs.Tab>
```shell
--config op-mainnet
--Sync.SnapSync=true
```

<Info>
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.
</Info>
</Tabs.Tab>
</Tabs>

* **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.

<Tabs items={['op-node', 'op-geth', 'Nethermind']}>
<Tabs.Tab>
```shell
--syncmode=execution-layer (not default)
```
</Tabs.Tab>

<Tabs.Tab>
```shell
--syncmode=full (not default)
--gcmode=archive (not default)
```
</Tabs.Tab>

<Tabs.Tab>
Archive sync can be enabled by using the archive configuration for your network (configurations with `_archive` suffix):
```shell
--config op-mainnet_archive
```
</Tabs.Tab>
</Tabs>

* **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.

<Tabs items={['op-node', 'op-geth', 'Nethermind']}>
<Tabs.Tab>
```shell
--syncmode=consensus-layer (default)
```
</Tabs.Tab>

<Tabs.Tab>
```shell
--syncmode=full (not default)
```
</Tabs.Tab>

<Tabs.Tab>
```shell
--config op-mainnet
--Sync.SnapSync=false
--Sync.FastSync=false
```
</Tabs.Tab>
</Tabs>
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
```

<Info>
The `--syncmode=execution-layer` flag is not the default setting and must be explicitly configured.
</Info>

### Configuration for op-geth

```shell
--syncmode=snap
```

<Info>
The `--syncmode=snap` flag is the default setting for `op-geth`.
</Info>

### Configuration for Nethermind

```shell
--config op-mainnet
--Sync.SnapSync=true
```

<Warning>
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.
</Warning>

## 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 op-node with reth

Set the following flags on `op-node`:

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
```

<Info>
Both flags are not the default setting and must be explicitly configured on `op-node`.
</Info>

# for erigon
--syncmode=execution-layer (not default)
--l2.enginekind=erigon (not default)
### Configuration for op-node with op-erigon

Set the following flags on `op-node`:

```shell
--syncmode=execution-layer
--l2.enginekind=erigon
```

<Info>
Both flags are not the default setting and must be explicitly configured on `op-node`.
</Info>

## 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 [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).
Loading