From 298593622c5a4d1582f6656889a42f65880244cd Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 14:05:55 +0200 Subject: [PATCH 01/14] operators: document op-reth as the primary execution client Rewrite the core node-operator guides (run-node, archive-node, configuration, overview, architecture) around op-reth: empty-datadir start with optional snapshot bootstrap (OP_RETH__SNAPSHOT), no snap sync, OP_RETH__* variables and ports, and --l2.enginekind=reth. The op-geth flow is preserved in collapsed 'Still running op-geth?' accordions for operators on the old setup until their switch date. --- infra-partners/operators/architecture.mdx | 2 +- infra-partners/operators/archive-node.mdx | 66 +++++++++++++--------- infra-partners/operators/configuration.mdx | 58 +++++++++++-------- infra-partners/operators/overview.mdx | 8 +-- infra-partners/operators/run-node.mdx | 61 ++++++++++++-------- 5 files changed, 119 insertions(+), 76 deletions(-) diff --git a/infra-partners/operators/architecture.mdx b/infra-partners/operators/architecture.mdx index 5cc5db989..cbfe2850f 100644 --- a/infra-partners/operators/architecture.mdx +++ b/infra-partners/operators/architecture.mdx @@ -11,7 +11,7 @@ The Rollup Node is responsible for deriving L2 block payloads from L1 data and p ## Execution client -The Execution Client is responsible for executing the block payloads it receives from the Rollup Node over JSON-RPC via the standard [Ethereum Engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/common.md#engine-api----common-definitions). The Execution Client exposes the standard JSON-RPC API that Ethereum developers are familiar with, and can be used to query blockchain data and submit transactions to the network. The Execution Client is largely analogous to an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#what-are-nodes-and-clients) in Ethereum. +The Execution Client is responsible for executing the block payloads it receives from the Rollup Node over JSON-RPC via the standard [Ethereum Engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/common.md#engine-api----common-definitions). The Execution Client exposes the standard JSON-RPC API that Ethereum developers are familiar with, and can be used to query blockchain data and submit transactions to the network. The Execution Client is largely analogous to an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#what-are-nodes-and-clients) in Ethereum. On Celo this is `op-reth`; `op-geth` is supported until your network's [switch date](/infra-partners/notices/op-geth-deprecation). ## Next steps diff --git a/infra-partners/operators/archive-node.mdx b/infra-partners/operators/archive-node.mdx index e8d2771cf..9a8a181fa 100644 --- a/infra-partners/operators/archive-node.mdx +++ b/infra-partners/operators/archive-node.mdx @@ -9,11 +9,11 @@ sidebarTitle: "Run an Archive Node" This guide covers running a **full archive node**, which serves every historical-state RPC call (such as `eth_getBalance` or `eth_call`) at any block and requires terabytes of storage. Celo also supports a narrower **historical proofs** feature for serving historical data without keeping full archive state; a dedicated guide for it is forthcoming. - -**op-geth is being deprecated** + +**Execution client: op-reth** -These instructions use `op-geth`, which is supported only until your network's switch to `op-reth`. Celo is transitioning to `op-reth` as the primary execution client. See [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation) for the switch dates; archive-node guidance for `op-reth` will follow once a Celo-compatible release is published. - +These instructions use `op-reth`, Celo's primary execution client. `op-geth` is supported until your network's switch date — see the **Still running op-geth?** notes at the end of this guide and [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation). + ## Overview @@ -24,12 +24,12 @@ To run an L2 archive node, you need to start the L2 execution client in archive **Prerequisites** -These instructions assume you already have +An L2 archive node starts from an empty datadir, like a full node — no migrated L1 data is required. To serve pre-L2 historical state, you additionally need one of: -1. A migrated full node datadir that has been synced to the migration block. See [Migrating an L1 Node](/infra-partners/operators/migrate-node) if you do not have this. -2. A non-migrated Celo L1 archive node datadir. Do not attempt to migrate an archive datadir. +1. A non-migrated Celo L1 archive node datadir (the compose setup runs a legacy archive node from it). Do not attempt to migrate an archive datadir. +2. The RPC endpoint of a running legacy Celo L1 archive node. -Please ensure neither datadir is being used by a running node before proceeding. +Ensure any datadir you supply is not in use by a running node before proceeding. 1. Pull the latest version of [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) and `cd` into the root of the project. @@ -50,25 +50,24 @@ Please ensure neither datadir is being used by a running node before proceeding. cp $NETWORK.env .env ``` - #### Configure sync mode - - By default, [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) will start your node with `snap` sync. While `archive` nodes can technically run with `snap` sync, they will only store archive data from the point that `snap` sync completes. This will leave a gap in the archive data after the hardfork, so we recommend running archive nodes with `full` sync and a migrated pre-hardfork datadir. + #### Configure node type - To use `full` sync, configure `.env` as follows: + To enable `archive` mode, configure `.env` as follows: ```text - OP_GETH__SYNCMODE=full - DATADIR_PATH= + NODE_TYPE=archive ``` - #### Configure node type + #### Bootstrap your datadir - To enable `archive` mode, configure `.env` as follows: + `op-reth` has no snap sync, so an archive node syncs by executing every block from genesis into an **empty** datadir. To skip the long initial sync, bootstrap from a published archive snapshot: ```text - NODE_TYPE=archive + OP_RETH__SNAPSHOT=true ``` + With `NODE_TYPE=archive`, this downloads the archive snapshot. Leave `OP_RETH__SNAPSHOT=false` to execute every block from genesis instead. Either way, `DATADIR_PATH` must be empty on first start — a datadir written by `op-geth` cannot be reused. + #### Configure Historical RPC Service To handle RPC requests for pre-hardfork state and execution, an L2 archive node proxies to a legacy archive node or "Historical RPC Service". @@ -85,7 +84,7 @@ Please ensure neither datadir is being used by a running node before proceeding. 2. Start the legacy archive node yourself and configure `.env` as follows: ```text - OP_GETH__HISTORICAL_RPC= + OP_RETH__HISTORICAL_RPC= ``` This will cause any value you set for `HISTORICAL_RPC_DATADIR_PATH` to be ignored. The tool will not start a legacy archive node when it starts your L2 archive node. @@ -100,10 +99,10 @@ Please ensure neither datadir is being used by a running node before proceeding. If the following options are not configured correctly, your node will not be discoverable or reachable to other nodes on the network. This is likely to impair your node's ability to stay reliably connected to and synced with the network. - - `OP_NODE__P2P_ADVERTISE_IP` - Specifies the public IP to be shared via discovery so that other nodes can connect to your node. If unset op-node other nodes on the network will not be able to discover and connect to your node. + - `OP_NODE__P2P_ADVERTISE_IP` - Specifies the public IP to be shared via discovery so that other nodes can connect to your node. If unset, other nodes on the network will not be able to discover and connect to your op-node. - `PORT__OP_NODE_P2P` - Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 9222. - - `OP_GETH__NAT` - Controls how op-geth determines its public IP that is shared via the discovery mechanism. If the public IP is not correctly configured then other nodes on the network will not be able to discover and connect to your node. The default value of `any` will try to automatically determine the public IP, but the most reliable approach is to explicitly set the public IP using `extip:`. Other acceptable values are `(any|none|upnp|pmp|pmp:|extip:|stun:)`. - - `PORT__OP_GETH_P2P` - Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 30303. + - `OP_RETH__NAT` - Controls how op-reth determines its public IP that is shared via the discovery mechanism. If the public IP is not correctly configured then other nodes on the network will not be able to discover and connect to your node. The default value of `any` will try to automatically determine the public IP, but the most reliable approach is to explicitly set the public IP using `extip:`. Other acceptable values are `(any|none|upnp|publicip|extip:|stun:)`. + - `PORT__OP_RETH_P2P` - Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 30303. 3. Start the node(s). @@ -114,23 +113,38 @@ Please ensure neither datadir is being used by a running node before proceeding. 4. Check the progress of your L2 archive node as it syncs. ```bash - docker-compose logs -n 50 -f op-geth + docker-compose logs -n 50 -f op-reth ``` - This will display and follow the last 50 lines of logs. In a syncing node, you would expect to see `Syncing beacon headers downloaded=...` where the downloaded number is increasing and later lines such as `"Syncing: chain download in progress","synced":"21.07%"` where the percentage is increasing. Once the percentage reaches 100%, the node should be synced. + This will display and follow the last 50 lines of logs. As the node syncs you will see `op-reth` executing blocks and its head advancing toward the network's latest block. 5. Check that node is fully synced. - Once the node is fully synced, you can validate that it's following the network by fetching the current block number via the RPC API and seeing that it's increasing as expected. + You can validate that your node is following the network by fetching the current block number via the RPC API and seeing that it climbs as the node syncs and then tracks the network's latest block. ```bash cast block-number --rpc-url http://localhost:9993 ``` - Note that until fully synced, the RPC API will return 0 for the head block number. - 6. Try querying historical state to test archive functionality. ```bash cast balance --block
--rpc-url http://localhost:9993 ``` + + + +Until your network's [switch date](/infra-partners/notices/op-geth-deprecation), you can keep running an `op-geth` archive node from an existing checkout of [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose). The flow above is the same, with these differences: + +- **Sync mode instead of a snapshot.** `op-geth` archive nodes should run `full` sync against a migrated pre-hardfork datadir — `snap` sync only stores archive data from the point it completes, leaving a gap after the hardfork: + + ```text + OP_GETH__SYNCMODE=full + DATADIR_PATH= + ``` + +- **Historical RPC variable.** Use `OP_GETH__HISTORICAL_RPC` in place of `OP_RETH__HISTORICAL_RPC`. +- **P2P variables.** Use `OP_GETH__NAT` (values `any|none|upnp|pmp|pmp:|extip:|stun:`) and `PORT__OP_GETH_P2P` (default `30303`). +- **Logs.** Follow `docker-compose logs -n 50 -f op-geth`; a syncing node shows `Syncing beacon headers downloaded=...` and later `"Syncing: chain download in progress","synced":"21.07%"`. + + diff --git a/infra-partners/operators/configuration.mdx b/infra-partners/operators/configuration.mdx index 8f7a7d834..3986f5f99 100644 --- a/infra-partners/operators/configuration.mdx +++ b/infra-partners/operators/configuration.mdx @@ -3,25 +3,22 @@ title: "Configuration Reference" sidebarTitle: "Configuration" --- -This page documents the `.env` variables and the key client flags used by the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) setup. For the exhaustive op-geth and op-node command-line flag reference, link out to the Optimism docs ([op-geth config](https://docs.optimism.io/node-operators/reference/op-geth-config), [op-node config](https://docs.optimism.io/node-operators/reference/op-node-config)). +This page documents the `.env` variables and the key client flags used by the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) setup. For the exhaustive op-node command-line flag reference, see the Optimism [op-node config](https://docs.optimism.io/node-operators/reference/op-node-config) docs; for `op-reth`, the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) start scripts are the best reference. - -**op-geth is being deprecated** + +**Execution client: op-reth** -The variables below configure `op-geth`, the execution client used today. Celo is transitioning to `op-reth` as the primary execution client. See [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation) for the switch dates; `op-reth` configuration will be documented once a Celo-compatible release ships. - +The variables below configure `op-reth`, Celo's primary execution client. The `op-geth` equivalents remain valid until your network's switch date — see the **op-geth variables** accordion below and [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation). + -## Node type and sync mode +## Node type and sync | Variable | Values | Description | |---|---|---| | `NODE_TYPE` | `full` (default), `archive` | A `full` node stores historical state only for recent blocks. An `archive` node stores historical state for the entire chain (roughly 10x the storage). | -| `OP_GETH__SYNCMODE` | `snap`, `full` | Sync mode for the L2 execution client. If unset, a `full` node defaults to `snap` and an `archive` node defaults to `full`. | +| `OP_RETH__SNAPSHOT` | `true`, `false` (default) | When `true`, an empty datadir is bootstrapped from a published snapshot (`snapshots.celo.org`) instead of syncing from scratch. Ignored once the datadir holds data. | -- **`snap`** downloads chaindata from peers until it has an unbroken chain of headers up to the most recent block, then executes transactions from that point on. This is the fastest way to start and requires no migrated L1 data. -- **`full`** executes all transactions from genesis (or the last block in the datadir) to verify every header. It requires a migrated pre-hardfork datadir — see [Migrating an L1 Node](/infra-partners/operators/migrate-node). - -For archive nodes, see [Running an archive node](/infra-partners/operators/archive-node). +`op-reth` has no snap sync — it syncs by executing every block. A new node must start from an empty datadir (see [Run a node with Docker](/infra-partners/operators/run-node)); datadirs written by `op-geth` cannot be reused. For archive nodes, see [Running an archive node](/infra-partners/operators/archive-node). ## L1 connection @@ -38,8 +35,8 @@ An L2 archive node serves pre-hardfork state by proxying to a legacy Celo L1 arc | Variable | Description | |---|---| -| `HISTORICAL_RPC_DATADIR_PATH` | Path to a pre-hardfork archive datadir. If set, a Celo L1 node runs in archive mode and op-geth proxies pre-migration requests to it. | -| `OP_GETH__HISTORICAL_RPC` | RPC endpoint of a running legacy archive node. If set, this overrides `HISTORICAL_RPC_DATADIR_PATH` and no local Celo L1 node is started. | +| `HISTORICAL_RPC_DATADIR_PATH` | Path to a pre-hardfork archive datadir. If set, a Celo L1 node runs in archive mode and op-reth proxies pre-migration requests to it. | +| `OP_RETH__HISTORICAL_RPC` | RPC endpoint of a running legacy archive node. If set, this overrides `HISTORICAL_RPC_DATADIR_PATH` and no local Celo L1 node is started. | See [Running an archive node](/infra-partners/operators/archive-node) for the full setup. @@ -50,7 +47,7 @@ Configure these so other nodes can discover and reach yours. If they are wrong, | Variable | Description | |---|---| | `OP_NODE__P2P_ADVERTISE_IP` | Public IP that op-node advertises via discovery. If unset, other nodes cannot discover yours. | -| `OP_GETH__NAT` | How op-geth determines its public IP for discovery. One of `any`, `none`, `upnp`, `pmp`, `pmp:`, `extip:`, `stun:`. The default `any` auto-detects; the most reliable option is `extip:`. | +| `OP_RETH__NAT` | How op-reth determines its public IP for discovery. One of `any`, `none`, `upnp`, `publicip`, `extip:`, `stun:`. The default `any` auto-detects; the most reliable option is `extip:`. | ## Ports @@ -58,9 +55,9 @@ Each `PORT__*` variable overrides a default exposed in `docker-compose.yml`. Def | Variable | Default | Service | |---|---|---| -| `PORT__OP_GETH_HTTP` | `9993` | op-geth JSON-RPC (HTTP) | -| `PORT__OP_GETH_WS` | `9994` | op-geth JSON-RPC (WebSocket) | -| `PORT__OP_GETH_P2P` | `30303` | op-geth P2P | +| `PORT__OP_RETH_HTTP` | `9993` | op-reth JSON-RPC (HTTP) | +| `PORT__OP_RETH_WS` | `9994` | op-reth JSON-RPC (WebSocket) | +| `PORT__OP_RETH_P2P` | `30303` | op-reth P2P | | `PORT__OP_NODE_HTTP` | `9545` | op-node RPC | | `PORT__OP_NODE_P2P` | `9222` | op-node P2P | | `PORT__HEALTHCHECK_METRICS` | `7300` | Healthcheck metrics | @@ -75,20 +72,35 @@ Each `PORT__*` variable overrides a default exposed in `docker-compose.yml`. Def | Variable | Description | |---|---| -| `DATADIR_PATH` | Datadir location (defaults to `./envs//datadir`). If empty, a new datadir is initialised at that path. | -| `IPC_PATH` | Alternative location for the geth IPC file, if the datadir disk does not support unix domain sockets. | +| `DATADIR_PATH` | Datadir location (defaults to `./envs//datadir`). Must be empty on first start — `op-reth` initialises a new datadir there and cannot reuse one written by `op-geth`. | ## Key client flags These flags are set for you by the compose start scripts; they are listed here because they are the Celo-specific ones operators most often need to know about. -- **`--rollup.sequencerhttp`** (op-geth) — the sequencer endpoint transactions are forwarded to. Mainnet: `https://cel2-sequencer.celo.org`; Celo Sepolia: `https://sequencer.celo-sepolia.celo-testnet.org`. If this is wrong, transactions submitted to your node are not executed. -- **`--history.transactions=0`** (op-geth) — index the full transaction history so all transactions are retrievable by hash. Set by default; required if you run a public RPC node. +- **Sequencer endpoint** (op-reth, set via `OP_RETH__SEQUENCER_URL`) — the sequencer that transactions submitted to your node are forwarded to. Mainnet: `https://cel2-sequencer.celo.org`; Celo Sepolia: `https://sequencer.celo-sepolia.celo-testnet.org`. If this is wrong, transactions submitted to your node are not executed. - **`--syncmode=execution-layer`** (op-node) — op-node syncs via the execution client rather than the deprecated consensus-layer req/resp path. See [Deprecation of Req/Res CL P2P Sync](/infra-partners/notices/req-resp-cl-sync-deprecation). -- **`--l2.enginekind`** (op-node) — tells op-node which execution client it is driving. It must match your execution client: keep it set to **`geth`** while you run op-geth, which is the current Celo setup. Upstream op-node is moving this default to `reth` as part of the op-reth transition, so if you build a newer op-node yourself, set `--l2.enginekind=geth` explicitly until you have migrated to op-reth. +- **`--l2.enginekind=reth`** (op-node) — tells op-node which execution client it is driving. It is set to `reth` for `op-reth`, the current Celo setup. - **`--metrics.enabled`** (op-node) — exposes Prometheus metrics on port `7300`. See [Monitoring & metrics](/infra-partners/operators/monitoring). -For every other op-geth/op-node flag, see the Optimism [op-geth config](https://docs.optimism.io/node-operators/reference/op-geth-config) and [op-node config](https://docs.optimism.io/node-operators/reference/op-node-config) references. +For every other op-node flag, see the Optimism [op-node config](https://docs.optimism.io/node-operators/reference/op-node-config) reference. + + + +If you are still running `op-geth` from an older checkout of [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose), use these equivalents in place of their `OP_RETH__` counterparts. They stop working once your network reaches its [switch date](/infra-partners/notices/op-geth-deprecation). + +| Variable | Description | +|---|---| +| `OP_GETH__SYNCMODE` | `snap` or `full`. If unset, a `full` node defaults to `snap` and an `archive` node to `full`. `full` requires a migrated pre-hardfork datadir. | +| `OP_GETH__NAT` | How op-geth determines its public IP for discovery. One of `any`, `none`, `upnp`, `pmp`, `pmp:`, `extip:`, `stun:`. | +| `OP_GETH__HISTORICAL_RPC` | RPC endpoint of a running legacy archive node for pre-hardfork state. | +| `PORT__OP_GETH_HTTP` / `PORT__OP_GETH_WS` / `PORT__OP_GETH_P2P` | op-geth JSON-RPC (HTTP `9993`, WebSocket `9994`) and P2P (`30303`) ports. | +| `IPC_PATH` | Alternative location for the geth IPC file, if the datadir disk does not support unix domain sockets. | +| `IMAGE_TAG__OP_GETH` | Pin a specific op-geth image version. | + +Key op-geth flags: `--rollup.sequencerhttp` (sequencer endpoint), `--history.transactions=0` (index the full transaction history), and `--l2.enginekind=geth` on op-node. + + ## Monitoring diff --git a/infra-partners/operators/overview.mdx b/infra-partners/operators/overview.mdx index a541bbc6c..3d5ac163a 100644 --- a/infra-partners/operators/overview.mdx +++ b/infra-partners/operators/overview.mdx @@ -3,7 +3,7 @@ title: "Node Operators" sidebarTitle: "Overview" --- -This section helps you run and operate a Celo L2 node. If you are starting fresh, the fastest path is to [run a full node with Docker](/infra-partners/operators/run-node) and `snap` sync from scratch — no L1 data migration required. +This section helps you run and operate a Celo L2 node. If you are starting fresh, the fastest path is to [run a full node with Docker](/infra-partners/operators/run-node) — a new node bootstraps from a published snapshot (or syncs from scratch), with no L1 data migration required. ## What is a Celo L2 node? @@ -17,13 +17,13 @@ See [Architecture](/infra-partners/operators/architecture) for how these fit tog ## Node types -- **Full node** — follows the chain and serves recent state. Runs with `snap` sync by default, so it can start without a migrated L1 datadir. This is the right choice for most operators. +- **Full node** — follows the chain and serves recent state. Starts from an empty datadir — bootstrap it from a published snapshot or sync from scratch, with no migrated L1 datadir required. This is the right choice for most operators. - **Archive node** — additionally preserves all historical state, at the cost of terabytes of storage. See [Running an archive node](/infra-partners/operators/archive-node). ## Execution client -- **op-reth** — the execution client Celo is adopting as the primary client going forward, built on `reth`. A Celo-compatible release and migration guide are coming. -- **op-geth** — the execution client used today. It is being deprecated in favor of `op-reth` and remains fully supported until your network's switch date. All current guides use `op-geth`. +- **op-reth** — Celo's primary execution client, built on `reth`. The guides in this section use `op-reth`. +- **op-geth** — the previous execution client. It is deprecated in favor of `op-reth` and remains supported only until your network's switch date. **op-geth is being deprecated** diff --git a/infra-partners/operators/run-node.mdx b/infra-partners/operators/run-node.mdx index 24f23c7de..b9ac9c2f6 100644 --- a/infra-partners/operators/run-node.mdx +++ b/infra-partners/operators/run-node.mdx @@ -6,15 +6,11 @@ sidebarTitle: "Run a Node with Docker" This guide is designed to help node operators run a Celo L2 node with Docker. -**L1 to L2 data migration** +**Execution client: op-reth** -If you wish to migrate data from a Celo L1 node and have not yet done so, please see the [migration guide](/infra-partners/operators/migrate-node) before continuing. Alternatively, you can `snap` sync from scratch without migrating existing L1 data. - - - -**Execution client: op-geth today, op-reth next** +These instructions use `op-reth`, the execution client Celo is adopting as its primary client. A fresh node starts from an empty datadir and either downloads a published snapshot or syncs by executing every block — no L1 data migration required. -These instructions use `op-geth`. Celo is transitioning to `op-reth` as the primary execution client; `op-geth` remains fully supported until your network's switch date. See [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation) for the switch dates. +`op-geth` remains supported until your network's switch date — see the **Still running op-geth?** notes at the end of this guide, and [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation) for the switch dates. ## Recommended Hardware @@ -67,18 +63,23 @@ Follow these steps to run a full node. If you would like to run an archive node, cp $NETWORK.env .env ``` - #### Configure sync mode + #### Bootstrap your datadir - By default, [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) will start your node with `snap` sync. This allows your node to start without a migrated L1 datadir, as pre-hardfork block data will be automatically downloaded from peers during syncing. This is the easiest way to start an L2 node. + `op-reth` has no snap sync; it syncs by executing every block. A new node must start from an **empty** datadir, and you have two ways to populate it: - Alternatively, you can start your node with `full` sync if you have a migrated L1 datadir. For instructions on obtaining a migrated L1 datadir, please see [Migrating an L1 Node](/infra-partners/operators/migrate-node). + - **From a snapshot (fastest).** Set `OP_RETH__SNAPSHOT=true` in `.env`. On first start with an empty datadir, your node downloads a recent published snapshot (from `snapshots.celo.org`) and continues from there. Once the datadir holds data, the snapshot step is skipped. - To use `full` sync, configure `.env` as follows: + ```text + OP_RETH__SNAPSHOT=true + ``` - ```text - OP_GETH__SYNCMODE=full - DATADIR_PATH= - ``` + - **From scratch.** Leave `OP_RETH__SNAPSHOT=false` (the default). Your node executes every block from genesis. This needs no external data but takes considerably longer to reach the chain tip. + + + **Datadirs from op-geth cannot be reused** + + `op-reth` uses a different on-disk format. A datadir written by `op-geth` — including one produced by the [L1→L2 migration](/infra-partners/operators/migrate-node) — cannot be used with `op-reth`. Start from an empty `DATADIR_PATH`. Pre-L2 historical state is served separately; see [Running an archive node](/infra-partners/operators/archive-node). + #### Configure node type @@ -92,10 +93,10 @@ Follow these steps to run a full node. If you would like to run an archive node, If the following options are not configured correctly, your node will not be discoverable or reachable to other nodes on the network. This is likely to impair your node's ability to stay reliably connected to and synced with the network. - - `OP_NODE__P2P_ADVERTISE_IP` - Specifies the public IP to be shared via discovery so that other nodes can connect to your node. If unset op-node other nodes on the network will not be able to discover and connect to your node. + - `OP_NODE__P2P_ADVERTISE_IP` - Specifies the public IP to be shared via discovery so that other nodes can connect to your node. If unset, other nodes on the network will not be able to discover and connect to your op-node. - `PORT__OP_NODE_P2P` - Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 9222. - - `OP_GETH__NAT` - Controls how op-geth determines its public IP that is shared via the discovery mechanism. If the public IP is not correctly configured then other nodes on the network will not be able to discover and connect to your node. The default value of `any` will try to automatically determine the public IP, but the most reliable approach is to explicitly set the public IP using `extip:`. Other acceptable values are `(any|none|upnp|pmp|pmp:|extip:|stun:)`. - - `PORT__OP_GETH_P2P` - Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 30303. + - `OP_RETH__NAT` - Controls how op-reth determines its public IP that is shared via the discovery mechanism. If the public IP is not correctly configured then other nodes on the network will not be able to discover and connect to your node. The default value of `any` will try to automatically determine the public IP, but the most reliable approach is to explicitly set the public IP using `extip:`. Other acceptable values are `(any|none|upnp|publicip|extip:|stun:)`. + - `PORT__OP_RETH_P2P` - Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 30303. 3. Start the node. @@ -106,20 +107,36 @@ Follow these steps to run a full node. If you would like to run an archive node, 4. Check the progress of the node as it syncs. ```bash - docker-compose logs -n 50 -f op-geth + docker-compose logs -n 50 -f op-reth ``` - This will display and follow the last 50 lines of logs. In a syncing node, you would expect to see `Syncing beacon headers downloaded=...` where the downloaded number is increasing and later lines such as `"Syncing: chain download in progress","synced":"21.07%"` where the percentage is increasing. Once the percentage reaches 100%, the node should be synced. + This will display and follow the last 50 lines of logs. As the node syncs you will see `op-reth` executing blocks and its head advancing toward the network's latest block. 5. Check that node is fully synced. - Once the node is fully synced, you can validate that it's following the network by fetching the current block number via the RPC API and seeing that it's increasing as expected. + You can validate that your node is following the network by fetching the current block number via the RPC API and seeing that it climbs as the node syncs and then tracks the network's latest block. ```bash cast block-number --rpc-url http://localhost:9993 ``` - Note that until fully synced, the RPC API will return 0 for the head block number. + + +Until your network's [switch date](/infra-partners/notices/op-geth-deprecation), you can keep running `op-geth` from an existing checkout of [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) (the latest version runs `op-reth` only). The steps above are the same, with these differences: + +- **Sync mode instead of a snapshot.** `op-geth` starts with `snap` sync by default, which downloads pre-hardfork block data from peers — no migrated L1 datadir required. To run `full` sync against a migrated L1 datadir instead, set: + + ```text + OP_GETH__SYNCMODE=full + DATADIR_PATH= + ``` + +- **P2P variables.** Use `OP_GETH__NAT` (values `any|none|upnp|pmp|pmp:|extip:|stun:`) and `PORT__OP_GETH_P2P` (default `30303`) in place of their `OP_RETH__` equivalents. +- **Logs.** Follow `docker-compose logs -n 50 -f op-geth`. A syncing node shows `Syncing beacon headers downloaded=...` and later `"Syncing: chain download in progress","synced":"21.07%"`; until fully synced the RPC API returns `0` for the head block number. + +After your network's switch date, `op-geth` will no longer follow the chain — migrate to `op-reth` before then. + + ## Build from source From 05f517f0b5c2cda9cee89857227ea52bf0f652b8 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 14:09:48 +0200 Subject: [PATCH 02/14] operators: update supporting node docs for op-reth Network config (op-reth image + snapshots, execution-client bootnodes), public RPC, troubleshooting, monitoring (Prometheus metrics, not the InfluxDB push op-geth used), and maintenance (empty-datadir re-sync via snapshot) now describe op-reth, with op-geth kept only as the legacy path. --- infra-partners/operators/maintenance.mdx | 7 ++----- infra-partners/operators/monitoring.mdx | 14 +++++++------- infra-partners/operators/network-config.mdx | 20 ++++++++++++-------- infra-partners/operators/public-rpc-node.mdx | 10 +++++----- infra-partners/operators/troubleshooting.mdx | 18 +++++++++--------- 5 files changed, 35 insertions(+), 34 deletions(-) diff --git a/infra-partners/operators/maintenance.mdx b/infra-partners/operators/maintenance.mdx index dd12b436c..54d021ee0 100644 --- a/infra-partners/operators/maintenance.mdx +++ b/infra-partners/operators/maintenance.mdx @@ -23,7 +23,7 @@ This pulls the latest changes from GitHub and the latest images from the registr Network hardforks require running a compatible client version *before* the fork block, or your node will stop following the chain. Watch the [Notices](/infra-partners/notices/archive/l2-migration) for each upgrade's required versions and timing. The next major required migration is the move from op-geth to op-reth — see [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation). -To pin a specific image version instead of tracking the latest, set the matching `IMAGE_TAG__*` variable in your `.env` (for example `IMAGE_TAG__OP_GETH` or `IMAGE_TAG__OP_NODE`). +To pin a specific image version instead of tracking the latest, set the matching `IMAGE_TAG__*` variable in your `.env` (for example `IMAGE_TAG__OP_RETH` or `IMAGE_TAG__OP_NODE`). ## Restarting and stopping @@ -52,7 +52,4 @@ cp -a ./envs//datadir /path/to/backup ## Re-syncing -If you need to rebuild a node, you do not need a backup or snapshot: - -- A **full node** can `snap` sync from scratch — see [Run a node with Docker](/infra-partners/operators/run-node). -- A **full-sync or archive node** needs a migrated pre-hardfork datadir — see the migrated chaindata in [Network Config & Assets](/infra-partners/operators/network-config) and [Migrating an L1 Node](/infra-partners/operators/migrate-node). +If you need to rebuild a node, start from an empty `DATADIR_PATH` — a datadir written by op-geth cannot be reused. You can either bootstrap from a published snapshot (`OP_RETH__SNAPSHOT=true`) or execute every block from scratch; see [Run a node with Docker](/infra-partners/operators/run-node). Pre-L2 historical state for archive nodes is served separately — see [Running an archive node](/infra-partners/operators/archive-node). diff --git a/infra-partners/operators/monitoring.mdx b/infra-partners/operators/monitoring.mdx index 13d05c76e..1a49b3d70 100644 --- a/infra-partners/operators/monitoring.mdx +++ b/infra-partners/operators/monitoring.mdx @@ -26,9 +26,9 @@ The **Simple Node Dashboard** (Dashboards → Manage → Simple Node Dashboard) ## Where metrics come from -- **op-node** exposes Prometheus metrics on port `7300` (`--metrics.enabled`). Prometheus (port `9090`, configurable via `PORT__PROMETHEUS`) scrapes op-node, the healthcheck, and the challenger. -- **op-geth** pushes its metrics to InfluxDB (port `8086`, database `opgeth`). -- Grafana reads from both Prometheus and InfluxDB. +- **op-node** exposes Prometheus metrics on port `7300` (`--metrics.enabled`). Prometheus (port `9090`, configurable via `PORT__PROMETHEUS`) scrapes op-node, op-reth, the healthcheck, and the challenger. +- **op-reth** exposes Prometheus metrics that Prometheus scrapes. +- Grafana reads from Prometheus. ## Key metrics to watch @@ -50,16 +50,16 @@ For the full op-node metrics catalog, see the Optimism [Node Metrics and Monitor Even without the Grafana stack, you can confirm your node is syncing: ```sh -# Follow op-geth logs — look for the sync percentage increasing -docker compose logs -n 50 -f op-geth +# Follow op-reth logs — watch it execute blocks toward the chain tip +docker compose logs -n 50 -f op-reth # Check sync progress (requires foundry) ./progress.sh -# Once synced, the head block number increases over time +# As the node syncs, the head block number climbs and then tracks the network cast block-number --rpc-url http://localhost:9993 ``` -In the logs, a syncing node shows `Syncing beacon headers downloaded=...` (increasing) and later `"Syncing: chain download in progress","synced":"21.07%"` (percentage increasing). Until fully synced, the RPC API returns `0` for the head block number. +In the logs, a syncing node shows `op-reth` importing and executing blocks, with its head advancing toward the network's latest block. If your node is not syncing or has no peers, see [Troubleshooting](/infra-partners/operators/troubleshooting). diff --git a/infra-partners/operators/network-config.mdx b/infra-partners/operators/network-config.mdx index 70365369c..380f3bf3b 100644 --- a/infra-partners/operators/network-config.mdx +++ b/infra-partners/operators/network-config.mdx @@ -7,14 +7,15 @@ Bootnodes, container images, and downloadable artifacts needed to run a Celo L2 ## Mainnet -- [Full migrated chaindata](https://storage.googleapis.com/cel2-rollup-files/celo/celo-mainnet-migrated-chaindata.tar.zst) +- op-reth snapshots — published at [`snapshots.celo.org`](https://snapshots.celo.org); enable with `OP_RETH__SNAPSHOT=true` (see [Run a node](/infra-partners/operators/run-node)) - [Rollup deploy config](https://storage.googleapis.com/cel2-rollup-files/celo/config.json) - [L1 contract addresses](https://storage.googleapis.com/cel2-rollup-files/celo/deployment-l1.json) - [L2 allocs](https://storage.googleapis.com/cel2-rollup-files/celo/l2-allocs.json) - [rollup.json](https://storage.googleapis.com/cel2-rollup-files/celo/rollup.json) -- [Genesis](https://storage.googleapis.com/cel2-rollup-files/celo/genesis.json) used for snap syncing +- [Genesis](https://storage.googleapis.com/cel2-rollup-files/celo/genesis.json) +- [Full migrated chaindata](https://storage.googleapis.com/cel2-rollup-files/celo/celo-mainnet-migrated-chaindata.tar.zst) — geth-format, for legacy `op-geth` full/archive sync - P2P peers - - op-geth bootnode/peers, to be used with op-geth `--bootnodes` flag: + - Execution-client bootnodes, used by op-reth (`OP_RETH__BOOTNODES`) and op-geth (`--bootnodes`): ```text enode://28f4fcb7f38c1b012087f7aef25dcb0a1257ccf1cdc4caa88584dc25416129069b514908c8cead5d0105cb0041dd65cd4ee185ae0d379a586fb07b1447e9de38@34.169.39.223:30303 @@ -49,18 +50,20 @@ Bootnodes, container images, and downloadable artifacts needed to run a Celo L2 ``` - Container images: - - [Celo L1 client](https://us-docker.pkg.dev/celo-org/us.gcr.io/geth-all:1.8.9) - - [op-geth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-geth:celo-v2.1.0) + - [op-reth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-reth:celo-v0.0.1-rc.1) - [op-node](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-node:celo-v2.1.0) - [eigenda-proxy](https://ghcr.io/layr-labs/eigenda-proxy:v1.8.2) + - [op-geth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-geth:celo-v2.1.0) — legacy, until the switch date + - [Celo L1 client](https://us-docker.pkg.dev/celo-org/us.gcr.io/geth-all:1.8.9) — legacy archive / historical RPC service ## Celo Sepolia +- op-reth snapshots — published at [`snapshots.celo.org`](https://snapshots.celo.org); enable with `OP_RETH__SNAPSHOT=true` (see [Run a node](/infra-partners/operators/run-node)) - [L1 contract addresses](https://storage.googleapis.com/cel2-rollup-files/celo-sepolia/deployment-l1.json) - [rollup.json](https://storage.googleapis.com/cel2-rollup-files/celo-sepolia/rollup.json) -- [Genesis](https://storage.googleapis.com/cel2-rollup-files/celo-sepolia/genesis.json) used for snap syncing +- [Genesis](https://storage.googleapis.com/cel2-rollup-files/celo-sepolia/genesis.json) - P2P peers: - - op-geth bootnode/peers, to be used with op-geth `--bootnodes` flag: + - Execution-client bootnodes, used by op-reth (`OP_RETH__BOOTNODES`) and op-geth (`--bootnodes`): ```text enode://7fd35dfea27042fe008c74ea97c7a41254b293152730419a6e9bcd84bb03c7ced418c1043e2ef6ad63d2facca6fbdacfbf7c4bfcf33ee7e9a0e6b7eb0617595d@34.169.104.197:30303 @@ -79,6 +82,7 @@ Bootnodes, container images, and downloadable artifacts needed to run a Celo L2 ``` - Container images: - - [op-geth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-geth:celo-v2.1.2) + - [op-reth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-reth:celo-v0.0.1-rc.1) - [op-node](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-node:celo-v2.1.0) - [eigenda-proxy](https://ghcr.io/layr-labs/eigenda-proxy:v1.8.2) + - [op-geth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-geth:celo-v2.1.2) — legacy, until the switch date diff --git a/infra-partners/operators/public-rpc-node.mdx b/infra-partners/operators/public-rpc-node.mdx index cbee36137..f632bc2dd 100644 --- a/infra-partners/operators/public-rpc-node.mdx +++ b/infra-partners/operators/public-rpc-node.mdx @@ -5,22 +5,22 @@ sidebarTitle: "Run a Public RPC Node" A public RPC node serves JSON-RPC requests to external clients. This page covers the settings specific to operating one; to get a node running first, see [Run a node with Docker](/infra-partners/operators/run-node). -## Index all transactions +## Serve transaction lookups by hash -Set `--history.transactions=0` on op-geth so the full transaction history is indexed and every transaction is retrievable by hash. The [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) setup sets this by default. Without it, transactions cannot be looked up by hash. +A public RPC endpoint should return any transaction by its hash. op-reth exposes the standard `eth` namespace, so transactions are retrievable by hash within the node's retained history, and the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) setup needs no extra configuration for this. (On the legacy op-geth setup this instead requires `--history.transactions=0`, which the compose setup sets for you.) ## Forward transactions to the sequencer -Set `--rollup.sequencerhttp` so transactions submitted to your endpoint are forwarded to the sequencer and executed: +op-reth forwards transactions submitted to your endpoint to the sequencer so they are executed. The sequencer endpoint is set for you by the compose setup (via `OP_RETH__SEQUENCER_URL`): - Mainnet: `https://cel2-sequencer.celo.org` - Celo Sepolia: `https://sequencer.celo-sepolia.celo-testnet.org` -This is set for you by the compose setup. If it is missing or wrong, transactions submitted to your node are accepted but never executed. +If it is missing or wrong, transactions submitted to your node are accepted but never executed. ## Exposing the endpoint -op-geth serves JSON-RPC over HTTP on port `9993` and WebSocket on `9994` by default (configurable via `PORT__OP_GETH_HTTP` and `PORT__OP_GETH_WS` — see the [Configuration reference](/infra-partners/operators/configuration#ports)). The compose setup enables the `web3,debug,eth,txpool,net,engine` namespaces on the HTTP endpoint. +op-reth serves JSON-RPC over HTTP on port `9993` and WebSocket on `9994` by default (configurable via `PORT__OP_RETH_HTTP` and `PORT__OP_RETH_WS` — see the [Configuration reference](/infra-partners/operators/configuration#ports)). The compose setup enables the `web3,debug,eth,txpool,net` namespaces on these endpoints. When exposing this publicly, put a reverse proxy or load balancer with rate limiting in front of it, and be deliberate about which RPC namespaces you expose to untrusted clients. diff --git a/infra-partners/operators/troubleshooting.mdx b/infra-partners/operators/troubleshooting.mdx index 7665ade85..f85463fe2 100644 --- a/infra-partners/operators/troubleshooting.mdx +++ b/infra-partners/operators/troubleshooting.mdx @@ -5,22 +5,22 @@ sidebarTitle: "Troubleshooting" ## Transactions Are Not Being Executed When Submitted to a Node -If your node is synced but transactions submitted to it are not executed, make sure the `--rollup.sequencerhttp` flag is correctly set. +If your node is synced but transactions submitted to it are not executed, make sure the sequencer endpoint is correctly set. The compose setup configures it for you via `OP_RETH__SEQUENCER_URL`: -- Mainnet: `--rollup.sequencerhttp=https://cel2-sequencer.celo.org/` -- Celo Sepolia: `--rollup.sequencerhttp=https://sequencer.celo-sepolia.celo-testnet.org` +- Mainnet: `https://cel2-sequencer.celo.org` +- Celo Sepolia: `https://sequencer.celo-sepolia.celo-testnet.org` -If you are hosting a public RPC node, please make sure the flag `--history.transactions` is set to 0 in op-geth (i.e. `--history.transactions=0`), so all transactions are indexed. Otherwise, transactions will not be retrievable by hash. +If you are hosting a public RPC node, see [Run a public RPC node](/infra-partners/operators/public-rpc-node) for serving transaction lookups by hash. ## Checking Sync Progress -If you are unsure whether your node is syncing, follow the op-geth logs and watch the sync percentage climb: +If you are unsure whether your node is syncing, follow the op-reth logs and watch it execute blocks toward the chain tip: ```sh -docker compose logs -n 50 -f op-geth +docker compose logs -n 50 -f op-reth ``` -You can also run `./progress.sh` from the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repo, or query the head block number — it returns `0` until the node is fully synced, then increases over time: +You can also run `./progress.sh` from the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repo, or query the head block number — it climbs as the node syncs and then tracks the network's latest block: ```sh cast block-number --rpc-url http://localhost:9993 @@ -33,8 +33,8 @@ See [Monitoring & metrics](/infra-partners/operators/monitoring) for the Grafana If your node stalls or falls behind the sequencer, it usually has too few peers. Check `op_node_default_peer_count` (see [Monitoring & metrics](/infra-partners/operators/monitoring)); if it is low or zero, your node cannot discover or reach other nodes. This is almost always a P2P configuration problem: - Set `OP_NODE__P2P_ADVERTISE_IP` to your node's public IP. -- Set `OP_GETH__NAT` to `extip:` rather than relying on auto-detection. -- Make sure the P2P ports are reachable (op-geth `30303`, op-node `9222` by default). +- Set `OP_RETH__NAT` to `extip:` rather than relying on auto-detection. +- Make sure the P2P ports are reachable (op-reth `30303`, op-node `9222` by default). See the [Configuration reference](/infra-partners/operators/configuration#networking-p2p) for these variables. Because op-node now syncs via the execution layer, healthy execution-client peer connectivity is required — see [Deprecation of Req/Res CL P2P Sync](/infra-partners/notices/req-resp-cl-sync-deprecation). From a14cbc17b81d61f0842005d7e34af5ac8c6fcfd6 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 14:11:09 +0200 Subject: [PATCH 03/14] notices: point op-geth deprecation at the op-reth guides; mark L1 migration legacy The op-reth release is out, so the deprecation notice now links to the op-reth run-node/archive/configuration guides instead of promising them. Flag the L1-migration guide as a legacy op-geth path, since op-reth cannot reuse a migrated (geth-format) datadir. --- infra-partners/notices/op-geth-deprecation.mdx | 11 ++++++----- infra-partners/operators/migrate-node.mdx | 6 ++++++ 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/infra-partners/notices/op-geth-deprecation.mdx b/infra-partners/notices/op-geth-deprecation.mdx index c99beb076..07236bcb1 100644 --- a/infra-partners/notices/op-geth-deprecation.mdx +++ b/infra-partners/notices/op-geth-deprecation.mdx @@ -24,14 +24,15 @@ Following [Optimism's](https://docs.optimism.io/notices/op-geth-deprecation) dep Node operators must complete migration to `op-reth` by the switch date for their network (see above). -A Celo-compatible `op-reth` release and migration guide will be published shortly. In the meantime: +A Celo-compatible `op-reth` release is available, and the node-operator guides now use it: -- Review `op-reth` and its configuration. -- Begin planning your migration timeline -- Monitor updates in the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repository and this page for release details and instructions. +- Follow [Run a node with Docker](/infra-partners/operators/run-node) to run `op-reth`. A new node starts from an empty datadir — bootstrap it from a published snapshot (`OP_RETH__SNAPSHOT=true`) or sync from scratch; no L1 data migration is required. +- A migrated `op-geth` datadir cannot be reused — `op-reth` uses a different on-disk format. Start `op-reth` with an empty `DATADIR_PATH`. +- For archive nodes and pre-L2 historical state, see [Running an archive node](/infra-partners/operators/archive-node). +- See the [Configuration reference](/infra-partners/operators/configuration) for the `OP_RETH__*` variables, and the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repository for the latest images. ## RPC Providers and Bridge Operators For most RPC users, this transition should be seamless. `op-reth` supports the same JSON-RPC interface as `op-geth`. -However, some differences may exist in non-standard or debug RPC methods. We recommend validating your integrations against `op-reth` once test environments are available. +However, some differences may exist in non-standard or debug RPC methods. We recommend validating your integrations against `op-reth` on Celo Sepolia, which switches first (see the dates above). diff --git a/infra-partners/operators/migrate-node.mdx b/infra-partners/operators/migrate-node.mdx index 8346f2e09..7b8716015 100644 --- a/infra-partners/operators/migrate-node.mdx +++ b/infra-partners/operators/migrate-node.mdx @@ -3,6 +3,12 @@ title: Migrating a Celo L1 Node sidebarTitle: "Migrating an L1 Node" --- + +**Legacy path — not needed for op-reth** + +`op-reth`, Celo's primary execution client, cannot use a migrated datadir — the migration tool produces geth-format data. Run `op-reth` from an empty datadir instead: bootstrap it from a published snapshot or sync from scratch (see [Run a node with Docker](/infra-partners/operators/run-node)), and serve pre-L2 historical state via the historical RPC service (see [Running an archive node](/infra-partners/operators/archive-node)). The instructions below apply only to the legacy `op-geth` setup, until your network's [switch date](/infra-partners/notices/op-geth-deprecation). + + Unless you need to migrate your own Celo L1 data, we recommend using a snapshot instead. You can find the latest snapshot in the [Network Config & Assets](/infra-partners/operators/network-config) section. From 28b4487f29009d11fab4529a39accf5893cdc431 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 14:17:22 +0200 Subject: [PATCH 04/14] operators: fix review findings - migrate-node: drop op-geth 'snap sync' framing from the fresh-node pointer and refresh the stale post-hardfork snapshot promise - network-config: list all six Celo Sepolia op-reth bootnodes (the relabeled list was showing only the four trusted peers) --- infra-partners/operators/migrate-node.mdx | 4 ++-- infra-partners/operators/network-config.mdx | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/infra-partners/operators/migrate-node.mdx b/infra-partners/operators/migrate-node.mdx index 7b8716015..4be529a2f 100644 --- a/infra-partners/operators/migrate-node.mdx +++ b/infra-partners/operators/migrate-node.mdx @@ -18,7 +18,7 @@ This guide helps Celo L1 node operators migrate their nodes to Celo L2. It descr **Alternative options:** -- **Fresh L2 node**: Skip to the [node operator guide](/infra-partners/operators/run-node) for `snap` sync from scratch +- **Fresh L2 node**: Skip to the [node operator guide](/infra-partners/operators/run-node) — a new `op-reth` node starts from an empty datadir and syncs by executing blocks (bootstrap from a snapshot to speed it up) - **Pre-migrated data**: Download migrated datadirs from [Network Config & Assets](/infra-partners/operators/network-config) @@ -255,7 +255,7 @@ Both the `pre` and `full` migration commands will first run a script to check wh To resolve this: - Try re-running the migration with a different source datadir if available. - - We will post a full pre-hardfork database snapshot in the [Network config & Assets](/infra-partners/operators/network-config) section shortly after the hardfork, but we recommend having your own backup datadir available as well. + - A full pre-hardfork database snapshot is available in the [Network config & Assets](/infra-partners/operators/network-config) section; we still recommend having your own backup datadir available as well. - Ensure the datadir is fully synced to just before the hardfork block. To check if a db has gaps, you can simply re-run the migration command which will automatically perform the check each time. diff --git a/infra-partners/operators/network-config.mdx b/infra-partners/operators/network-config.mdx index 380f3bf3b..027110a5d 100644 --- a/infra-partners/operators/network-config.mdx +++ b/infra-partners/operators/network-config.mdx @@ -70,6 +70,8 @@ Bootnodes, container images, and downloadable artifacts needed to run a Celo L2 enode://151bcf170585971fc78129d9c16af355a1a53e1c825ce1ac20700ea754aa33eda60ca83de6f954bfed8d36c53f33295d93dbc3da9d549d6547d09467806b4b3d@104.199.124.11:30303 enode://aa5fb766438ac5a0354eb2eec1c0c002b56bb2ce7ed44f0e76e019cbb931222faa9ecfb0fa0055c0c62a2fcf04492d4129349a1045dfef140585250281885e4b@34.83.115.97:30303 enode://27c81ca466c99016d1595429afc68d66afb3ed9d5a2dd7f6a7797db23a4c826546a177b69b4932f3a75ce374b09d8ccc5b52dad615b3c47dbb8f6217d79ded22@35.247.1.226:30303 + enode://c0f8188765317e75616525c34a10de4c54eb060fcaa4ba30010bd2d3cb8cb1f2b5f6245916ef5cea677226e000ab12df7d99cc5d056983fa4668a9502e74b5cd@34.82.193.240:30303 + enode://bd330aee83982989bfc04bf32d2a36912c600c74177a8d9d2889992636fed98ffa2f75a70385e123c5f6744dd9ca7685779670fec135248834aba2d3875ba4e0@136.117.28.173:30303 ``` - op-node static peers, to be used with op-node `--p2p.bootnodes` flag: From 45b2150833036943448ceb6b4253ea5f7c0e2e72 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 14:17:57 +0200 Subject: [PATCH 05/14] run-node: drop obsolete full-node vs full-sync disambiguation op-reth has no sync-mode 'full', so the note distinguishing it from a full node type no longer applies. --- infra-partners/operators/run-node.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/infra-partners/operators/run-node.mdx b/infra-partners/operators/run-node.mdx index b9ac9c2f6..715c34f0c 100644 --- a/infra-partners/operators/run-node.mdx +++ b/infra-partners/operators/run-node.mdx @@ -83,7 +83,7 @@ Follow these steps to run a full node. If you would like to run an archive node, #### Configure node type - Your node will run as a `full` node by default, but can also be configured as an `archive` node if you wish to preserve access to all historical state. Note that `full` has a different meaning here than in the context of syncing. See [Running an archive node](/infra-partners/operators/archive-node) for more information. + Your node will run as a `full` node by default, but can also be configured as an `archive` node if you wish to preserve access to all historical state. See [Running an archive node](/infra-partners/operators/archive-node) for more information. #### Configure P2P for external network access From 1700e20af18b8bac4686716dceea81238d0d3912 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 15:25:23 +0200 Subject: [PATCH 06/14] operators: describe op-reth sync on its own terms Drop the 'no snap sync' framing in favor of describing how op-reth syncs. Fix the archive-node bootstrap text: NODE_TYPE=archive controls how much historical state is retained, independent of the snapshot, which only speeds up the initial sync. --- infra-partners/operators/archive-node.mdx | 4 ++-- infra-partners/operators/configuration.mdx | 2 +- infra-partners/operators/run-node.mdx | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/infra-partners/operators/archive-node.mdx b/infra-partners/operators/archive-node.mdx index 9a8a181fa..bfcc541cb 100644 --- a/infra-partners/operators/archive-node.mdx +++ b/infra-partners/operators/archive-node.mdx @@ -60,13 +60,13 @@ Ensure any datadir you supply is not in use by a running node before proceeding. #### Bootstrap your datadir - `op-reth` has no snap sync, so an archive node syncs by executing every block from genesis into an **empty** datadir. To skip the long initial sync, bootstrap from a published archive snapshot: + An archive node syncs by executing every block from genesis into an **empty** datadir, building the full historical state. To skip the long initial sync, bootstrap from a published snapshot: ```text OP_RETH__SNAPSHOT=true ``` - With `NODE_TYPE=archive`, this downloads the archive snapshot. Leave `OP_RETH__SNAPSHOT=false` to execute every block from genesis instead. Either way, `DATADIR_PATH` must be empty on first start — a datadir written by `op-geth` cannot be reused. + On first start this downloads the snapshot matching your `NODE_TYPE` and continues from there — it only speeds up the initial sync. `NODE_TYPE=archive` is what keeps the full historical state available, independent of whether you use a snapshot. `DATADIR_PATH` must be empty on first start — a datadir written by `op-geth` cannot be reused. #### Configure Historical RPC Service diff --git a/infra-partners/operators/configuration.mdx b/infra-partners/operators/configuration.mdx index 3986f5f99..18ae3fc5c 100644 --- a/infra-partners/operators/configuration.mdx +++ b/infra-partners/operators/configuration.mdx @@ -18,7 +18,7 @@ The variables below configure `op-reth`, Celo's primary execution client. The `o | `NODE_TYPE` | `full` (default), `archive` | A `full` node stores historical state only for recent blocks. An `archive` node stores historical state for the entire chain (roughly 10x the storage). | | `OP_RETH__SNAPSHOT` | `true`, `false` (default) | When `true`, an empty datadir is bootstrapped from a published snapshot (`snapshots.celo.org`) instead of syncing from scratch. Ignored once the datadir holds data. | -`op-reth` has no snap sync — it syncs by executing every block. A new node must start from an empty datadir (see [Run a node with Docker](/infra-partners/operators/run-node)); datadirs written by `op-geth` cannot be reused. For archive nodes, see [Running an archive node](/infra-partners/operators/archive-node). +`op-reth` syncs by executing every block. A new node starts from an empty datadir (see [Run a node with Docker](/infra-partners/operators/run-node)); datadirs written by `op-geth` cannot be reused. For archive nodes, see [Running an archive node](/infra-partners/operators/archive-node). ## L1 connection diff --git a/infra-partners/operators/run-node.mdx b/infra-partners/operators/run-node.mdx index 715c34f0c..6f76f60a8 100644 --- a/infra-partners/operators/run-node.mdx +++ b/infra-partners/operators/run-node.mdx @@ -65,7 +65,7 @@ Follow these steps to run a full node. If you would like to run an archive node, #### Bootstrap your datadir - `op-reth` has no snap sync; it syncs by executing every block. A new node must start from an **empty** datadir, and you have two ways to populate it: + `op-reth` syncs by executing every block. A new node starts from an **empty** datadir, and you have two ways to populate it: - **From a snapshot (fastest).** Set `OP_RETH__SNAPSHOT=true` in `.env`. On first start with an empty datadir, your node downloads a recent published snapshot (from `snapshots.celo.org`) and continues from there. Once the datadir holds data, the snapshot step is skipped. From 56000d8febb37c68ee1abf5e74a3265f1cd77abe Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 15:29:58 +0200 Subject: [PATCH 07/14] operators: snapshot required on mainnet, optional on Celo Sepolia Mainnet needs a snapshot for the pre-L2 (Celo L1) history op-reth cannot re-execute; Celo Sepolia has no pre-L2 history and can sync from genesis. Also link the Optimism op-reth config reference and drop the redundant 'current Celo setup' aside. --- infra-partners/notices/op-geth-deprecation.mdx | 2 +- infra-partners/operators/archive-node.mdx | 4 ++-- infra-partners/operators/configuration.mdx | 8 ++++---- infra-partners/operators/maintenance.mdx | 2 +- infra-partners/operators/migrate-node.mdx | 4 ++-- infra-partners/operators/network-config.mdx | 4 ++-- infra-partners/operators/overview.mdx | 4 ++-- infra-partners/operators/run-node.mdx | 10 ++++++---- 8 files changed, 20 insertions(+), 18 deletions(-) diff --git a/infra-partners/notices/op-geth-deprecation.mdx b/infra-partners/notices/op-geth-deprecation.mdx index 07236bcb1..0cb22e9fa 100644 --- a/infra-partners/notices/op-geth-deprecation.mdx +++ b/infra-partners/notices/op-geth-deprecation.mdx @@ -26,7 +26,7 @@ Node operators must complete migration to `op-reth` by the switch date for their A Celo-compatible `op-reth` release is available, and the node-operator guides now use it: -- Follow [Run a node with Docker](/infra-partners/operators/run-node) to run `op-reth`. A new node starts from an empty datadir — bootstrap it from a published snapshot (`OP_RETH__SNAPSHOT=true`) or sync from scratch; no L1 data migration is required. +- Follow [Run a node with Docker](/infra-partners/operators/run-node) to run `op-reth`. A new node starts from an empty datadir — bootstrap it from a published snapshot (`OP_RETH__SNAPSHOT=true`, required on mainnet) or, on Celo Sepolia, sync from genesis; no L1 data migration is required. - A migrated `op-geth` datadir cannot be reused — `op-reth` uses a different on-disk format. Start `op-reth` with an empty `DATADIR_PATH`. - For archive nodes and pre-L2 historical state, see [Running an archive node](/infra-partners/operators/archive-node). - See the [Configuration reference](/infra-partners/operators/configuration) for the `OP_RETH__*` variables, and the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repository for the latest images. diff --git a/infra-partners/operators/archive-node.mdx b/infra-partners/operators/archive-node.mdx index bfcc541cb..3d71d05b4 100644 --- a/infra-partners/operators/archive-node.mdx +++ b/infra-partners/operators/archive-node.mdx @@ -60,13 +60,13 @@ Ensure any datadir you supply is not in use by a running node before proceeding. #### Bootstrap your datadir - An archive node syncs by executing every block from genesis into an **empty** datadir, building the full historical state. To skip the long initial sync, bootstrap from a published snapshot: + An archive node starts from an **empty** datadir and keeps the full historical state. Bootstrap it from a published snapshot: ```text OP_RETH__SNAPSHOT=true ``` - On first start this downloads the snapshot matching your `NODE_TYPE` and continues from there — it only speeds up the initial sync. `NODE_TYPE=archive` is what keeps the full historical state available, independent of whether you use a snapshot. `DATADIR_PATH` must be empty on first start — a datadir written by `op-geth` cannot be reused. + On first start this downloads the snapshot matching your `NODE_TYPE` (here, the archive snapshot) and continues from there. **On mainnet a snapshot is required** — it provides the pre-L2 (Celo L1) history. On **Celo Sepolia**, which has no pre-L2 history, you can instead leave `OP_RETH__SNAPSHOT=false` and execute every block from genesis. Either way, `NODE_TYPE=archive` is what keeps the full historical state available, and `DATADIR_PATH` must be empty on first start — a datadir written by `op-geth` cannot be reused. #### Configure Historical RPC Service diff --git a/infra-partners/operators/configuration.mdx b/infra-partners/operators/configuration.mdx index 18ae3fc5c..e0968b12f 100644 --- a/infra-partners/operators/configuration.mdx +++ b/infra-partners/operators/configuration.mdx @@ -3,7 +3,7 @@ title: "Configuration Reference" sidebarTitle: "Configuration" --- -This page documents the `.env` variables and the key client flags used by the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) setup. For the exhaustive op-node command-line flag reference, see the Optimism [op-node config](https://docs.optimism.io/node-operators/reference/op-node-config) docs; for `op-reth`, the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) start scripts are the best reference. +This page documents the `.env` variables and the key client flags used by the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) setup. For the exhaustive command-line flag references, see the Optimism [op-reth config](https://docs.optimism.io/node-operators/reference/op-reth-config) and [op-node config](https://docs.optimism.io/node-operators/reference/op-node-config) docs. **Execution client: op-reth** @@ -16,7 +16,7 @@ The variables below configure `op-reth`, Celo's primary execution client. The `o | Variable | Values | Description | |---|---|---| | `NODE_TYPE` | `full` (default), `archive` | A `full` node stores historical state only for recent blocks. An `archive` node stores historical state for the entire chain (roughly 10x the storage). | -| `OP_RETH__SNAPSHOT` | `true`, `false` (default) | When `true`, an empty datadir is bootstrapped from a published snapshot (`snapshots.celo.org`) instead of syncing from scratch. Ignored once the datadir holds data. | +| `OP_RETH__SNAPSHOT` | `true`, `false` (default) | When `true`, an empty datadir is bootstrapped from a published snapshot (`snapshots.celo.org`). Required on mainnet, which needs the pre-L2 history; optional on Celo Sepolia, which can sync from genesis. Ignored once the datadir holds data. | `op-reth` syncs by executing every block. A new node starts from an empty datadir (see [Run a node with Docker](/infra-partners/operators/run-node)); datadirs written by `op-geth` cannot be reused. For archive nodes, see [Running an archive node](/infra-partners/operators/archive-node). @@ -80,10 +80,10 @@ These flags are set for you by the compose start scripts; they are listed here b - **Sequencer endpoint** (op-reth, set via `OP_RETH__SEQUENCER_URL`) — the sequencer that transactions submitted to your node are forwarded to. Mainnet: `https://cel2-sequencer.celo.org`; Celo Sepolia: `https://sequencer.celo-sepolia.celo-testnet.org`. If this is wrong, transactions submitted to your node are not executed. - **`--syncmode=execution-layer`** (op-node) — op-node syncs via the execution client rather than the deprecated consensus-layer req/resp path. See [Deprecation of Req/Res CL P2P Sync](/infra-partners/notices/req-resp-cl-sync-deprecation). -- **`--l2.enginekind=reth`** (op-node) — tells op-node which execution client it is driving. It is set to `reth` for `op-reth`, the current Celo setup. +- **`--l2.enginekind=reth`** (op-node) — tells op-node which execution client it is driving. It is set to `reth` for `op-reth`. - **`--metrics.enabled`** (op-node) — exposes Prometheus metrics on port `7300`. See [Monitoring & metrics](/infra-partners/operators/monitoring). -For every other op-node flag, see the Optimism [op-node config](https://docs.optimism.io/node-operators/reference/op-node-config) reference. +For every other op-reth/op-node flag, see the Optimism [op-reth config](https://docs.optimism.io/node-operators/reference/op-reth-config) and [op-node config](https://docs.optimism.io/node-operators/reference/op-node-config) references. diff --git a/infra-partners/operators/maintenance.mdx b/infra-partners/operators/maintenance.mdx index 54d021ee0..2f7c612f5 100644 --- a/infra-partners/operators/maintenance.mdx +++ b/infra-partners/operators/maintenance.mdx @@ -52,4 +52,4 @@ cp -a ./envs//datadir /path/to/backup ## Re-syncing -If you need to rebuild a node, start from an empty `DATADIR_PATH` — a datadir written by op-geth cannot be reused. You can either bootstrap from a published snapshot (`OP_RETH__SNAPSHOT=true`) or execute every block from scratch; see [Run a node with Docker](/infra-partners/operators/run-node). Pre-L2 historical state for archive nodes is served separately — see [Running an archive node](/infra-partners/operators/archive-node). +If you need to rebuild a node, start from an empty `DATADIR_PATH` — a datadir written by op-geth cannot be reused. Bootstrap from a published snapshot (`OP_RETH__SNAPSHOT=true`, required on mainnet) or, on Celo Sepolia, execute every block from genesis; see [Run a node with Docker](/infra-partners/operators/run-node). Pre-L2 historical state for archive nodes is served separately — see [Running an archive node](/infra-partners/operators/archive-node). diff --git a/infra-partners/operators/migrate-node.mdx b/infra-partners/operators/migrate-node.mdx index 4be529a2f..232055634 100644 --- a/infra-partners/operators/migrate-node.mdx +++ b/infra-partners/operators/migrate-node.mdx @@ -6,7 +6,7 @@ sidebarTitle: "Migrating an L1 Node" **Legacy path — not needed for op-reth** -`op-reth`, Celo's primary execution client, cannot use a migrated datadir — the migration tool produces geth-format data. Run `op-reth` from an empty datadir instead: bootstrap it from a published snapshot or sync from scratch (see [Run a node with Docker](/infra-partners/operators/run-node)), and serve pre-L2 historical state via the historical RPC service (see [Running an archive node](/infra-partners/operators/archive-node)). The instructions below apply only to the legacy `op-geth` setup, until your network's [switch date](/infra-partners/notices/op-geth-deprecation). +`op-reth`, Celo's primary execution client, cannot use a migrated datadir — the migration tool produces geth-format data. Run `op-reth` from an empty datadir instead — bootstrap it from a published snapshot (see [Run a node with Docker](/infra-partners/operators/run-node)) — and serve pre-L2 historical state via the historical RPC service (see [Running an archive node](/infra-partners/operators/archive-node)). The instructions below apply only to the legacy `op-geth` setup, until your network's [switch date](/infra-partners/notices/op-geth-deprecation). @@ -18,7 +18,7 @@ This guide helps Celo L1 node operators migrate their nodes to Celo L2. It descr **Alternative options:** -- **Fresh L2 node**: Skip to the [node operator guide](/infra-partners/operators/run-node) — a new `op-reth` node starts from an empty datadir and syncs by executing blocks (bootstrap from a snapshot to speed it up) +- **Fresh L2 node**: Skip to the [node operator guide](/infra-partners/operators/run-node) — a new `op-reth` node starts from an empty datadir and bootstraps from a published snapshot (or syncs from genesis on Celo Sepolia) - **Pre-migrated data**: Download migrated datadirs from [Network Config & Assets](/infra-partners/operators/network-config) diff --git a/infra-partners/operators/network-config.mdx b/infra-partners/operators/network-config.mdx index 027110a5d..478a5f797 100644 --- a/infra-partners/operators/network-config.mdx +++ b/infra-partners/operators/network-config.mdx @@ -7,7 +7,7 @@ Bootnodes, container images, and downloadable artifacts needed to run a Celo L2 ## Mainnet -- op-reth snapshots — published at [`snapshots.celo.org`](https://snapshots.celo.org); enable with `OP_RETH__SNAPSHOT=true` (see [Run a node](/infra-partners/operators/run-node)) +- op-reth snapshots — published at [`snapshots.celo.org`](https://snapshots.celo.org); a mainnet node must bootstrap from one (`OP_RETH__SNAPSHOT=true`) for the pre-L2 history (see [Run a node](/infra-partners/operators/run-node)) - [Rollup deploy config](https://storage.googleapis.com/cel2-rollup-files/celo/config.json) - [L1 contract addresses](https://storage.googleapis.com/cel2-rollup-files/celo/deployment-l1.json) - [L2 allocs](https://storage.googleapis.com/cel2-rollup-files/celo/l2-allocs.json) @@ -58,7 +58,7 @@ Bootnodes, container images, and downloadable artifacts needed to run a Celo L2 ## Celo Sepolia -- op-reth snapshots — published at [`snapshots.celo.org`](https://snapshots.celo.org); enable with `OP_RETH__SNAPSHOT=true` (see [Run a node](/infra-partners/operators/run-node)) +- op-reth snapshots — published at [`snapshots.celo.org`](https://snapshots.celo.org); optional, enable with `OP_RETH__SNAPSHOT=true` to skip syncing from genesis (see [Run a node](/infra-partners/operators/run-node)) - [L1 contract addresses](https://storage.googleapis.com/cel2-rollup-files/celo-sepolia/deployment-l1.json) - [rollup.json](https://storage.googleapis.com/cel2-rollup-files/celo-sepolia/rollup.json) - [Genesis](https://storage.googleapis.com/cel2-rollup-files/celo-sepolia/genesis.json) diff --git a/infra-partners/operators/overview.mdx b/infra-partners/operators/overview.mdx index 3d5ac163a..abb15ab5a 100644 --- a/infra-partners/operators/overview.mdx +++ b/infra-partners/operators/overview.mdx @@ -3,7 +3,7 @@ title: "Node Operators" sidebarTitle: "Overview" --- -This section helps you run and operate a Celo L2 node. If you are starting fresh, the fastest path is to [run a full node with Docker](/infra-partners/operators/run-node) — a new node bootstraps from a published snapshot (or syncs from scratch), with no L1 data migration required. +This section helps you run and operate a Celo L2 node. If you are starting fresh, the fastest path is to [run a full node with Docker](/infra-partners/operators/run-node) — a new node bootstraps from a published snapshot (or, on Celo Sepolia, syncs from genesis), with no L1 data migration required. ## What is a Celo L2 node? @@ -17,7 +17,7 @@ See [Architecture](/infra-partners/operators/architecture) for how these fit tog ## Node types -- **Full node** — follows the chain and serves recent state. Starts from an empty datadir — bootstrap it from a published snapshot or sync from scratch, with no migrated L1 datadir required. This is the right choice for most operators. +- **Full node** — follows the chain and serves recent state. Starts from an empty datadir — bootstrap it from a published snapshot (or sync from genesis on Celo Sepolia), with no migrated L1 datadir required. This is the right choice for most operators. - **Archive node** — additionally preserves all historical state, at the cost of terabytes of storage. See [Running an archive node](/infra-partners/operators/archive-node). ## Execution client diff --git a/infra-partners/operators/run-node.mdx b/infra-partners/operators/run-node.mdx index 6f76f60a8..dbad9f4e4 100644 --- a/infra-partners/operators/run-node.mdx +++ b/infra-partners/operators/run-node.mdx @@ -8,7 +8,7 @@ This guide is designed to help node operators run a Celo L2 node with Docker. **Execution client: op-reth** -These instructions use `op-reth`, the execution client Celo is adopting as its primary client. A fresh node starts from an empty datadir and either downloads a published snapshot or syncs by executing every block — no L1 data migration required. +These instructions use `op-reth`, the execution client Celo is adopting as its primary client. A fresh node starts from an empty datadir and bootstraps from a published snapshot (required on mainnet) or, on Celo Sepolia, syncs from genesis — no L1 data migration required. `op-geth` remains supported until your network's switch date — see the **Still running op-geth?** notes at the end of this guide, and [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation) for the switch dates. @@ -65,15 +65,17 @@ Follow these steps to run a full node. If you would like to run an archive node, #### Bootstrap your datadir - `op-reth` syncs by executing every block. A new node starts from an **empty** datadir, and you have two ways to populate it: + `op-reth` syncs by executing every block. A new node starts from an **empty** datadir, populated in one of two ways depending on your network: - - **From a snapshot (fastest).** Set `OP_RETH__SNAPSHOT=true` in `.env`. On first start with an empty datadir, your node downloads a recent published snapshot (from `snapshots.celo.org`) and continues from there. Once the datadir holds data, the snapshot step is skipped. + - **From a snapshot.** Set `OP_RETH__SNAPSHOT=true` in `.env`. On first start with an empty datadir, your node downloads a recent published snapshot (from `snapshots.celo.org`) and continues from there. Once the datadir holds data, the snapshot step is skipped. ```text OP_RETH__SNAPSHOT=true ``` - - **From scratch.** Leave `OP_RETH__SNAPSHOT=false` (the default). Your node executes every block from genesis. This needs no external data but takes considerably longer to reach the chain tip. + **On mainnet a snapshot is required** — it provides the pre-L2 (Celo L1) history, which `op-reth` cannot reproduce by executing blocks. + + - **From genesis.** On **Celo Sepolia**, which has no pre-L2 history, you can leave `OP_RETH__SNAPSHOT=false` (the default) and execute every block from genesis. This needs no external data but takes considerably longer to reach the chain tip. **Datadirs from op-geth cannot be reused** From 415031650035b0154965a06c0a77f12625e1d662 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 15:32:41 +0200 Subject: [PATCH 08/14] troubleshooting: show the op-reth --rollup.sequencer flag Restore the explicit sequencer flag in the transactions-not-executing section, using op-reth's --rollup.sequencer (op-geth used --rollup.sequencerhttp, which reth does not have). --- infra-partners/operators/troubleshooting.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/infra-partners/operators/troubleshooting.mdx b/infra-partners/operators/troubleshooting.mdx index f85463fe2..3dafcc159 100644 --- a/infra-partners/operators/troubleshooting.mdx +++ b/infra-partners/operators/troubleshooting.mdx @@ -5,10 +5,10 @@ sidebarTitle: "Troubleshooting" ## Transactions Are Not Being Executed When Submitted to a Node -If your node is synced but transactions submitted to it are not executed, make sure the sequencer endpoint is correctly set. The compose setup configures it for you via `OP_RETH__SEQUENCER_URL`: +If your node is synced but transactions submitted to it are not executed, make sure the sequencer endpoint is correctly set. op-reth forwards transactions to the sequencer via the `--rollup.sequencer` flag, which the compose setup sets for you from `OP_RETH__SEQUENCER_URL`: -- Mainnet: `https://cel2-sequencer.celo.org` -- Celo Sepolia: `https://sequencer.celo-sepolia.celo-testnet.org` +- Mainnet: `--rollup.sequencer=https://cel2-sequencer.celo.org` +- Celo Sepolia: `--rollup.sequencer=https://sequencer.celo-sepolia.celo-testnet.org` If you are hosting a public RPC node, see [Run a public RPC node](/infra-partners/operators/public-rpc-node) for serving transaction lookups by hash. From 669a2ce30e4a49ac467d91afa2b73ce2acbae3f2 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 15:36:14 +0200 Subject: [PATCH 09/14] configuration: name the --rollup.sequencer flag in the key flags list --- infra-partners/operators/configuration.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/infra-partners/operators/configuration.mdx b/infra-partners/operators/configuration.mdx index e0968b12f..0c17fc7e0 100644 --- a/infra-partners/operators/configuration.mdx +++ b/infra-partners/operators/configuration.mdx @@ -78,7 +78,7 @@ Each `PORT__*` variable overrides a default exposed in `docker-compose.yml`. Def These flags are set for you by the compose start scripts; they are listed here because they are the Celo-specific ones operators most often need to know about. -- **Sequencer endpoint** (op-reth, set via `OP_RETH__SEQUENCER_URL`) — the sequencer that transactions submitted to your node are forwarded to. Mainnet: `https://cel2-sequencer.celo.org`; Celo Sepolia: `https://sequencer.celo-sepolia.celo-testnet.org`. If this is wrong, transactions submitted to your node are not executed. +- **`--rollup.sequencer`** (op-reth, set via `OP_RETH__SEQUENCER_URL`) — the sequencer that transactions submitted to your node are forwarded to. Mainnet: `https://cel2-sequencer.celo.org`; Celo Sepolia: `https://sequencer.celo-sepolia.celo-testnet.org`. If this is wrong, transactions submitted to your node are not executed. - **`--syncmode=execution-layer`** (op-node) — op-node syncs via the execution client rather than the deprecated consensus-layer req/resp path. See [Deprecation of Req/Res CL P2P Sync](/infra-partners/notices/req-resp-cl-sync-deprecation). - **`--l2.enginekind=reth`** (op-node) — tells op-node which execution client it is driving. It is set to `reth` for `op-reth`. - **`--metrics.enabled`** (op-node) — exposes Prometheus metrics on port `7300`. See [Monitoring & metrics](/infra-partners/operators/monitoring). From 0fb5ddec64215795307f81d24e1c7581915488fe Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Fri, 19 Jun 2026 15:39:09 +0200 Subject: [PATCH 10/14] public-rpc-node: name the --rollup.sequencer flag in the sequencer section --- infra-partners/operators/public-rpc-node.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/infra-partners/operators/public-rpc-node.mdx b/infra-partners/operators/public-rpc-node.mdx index f632bc2dd..95f918387 100644 --- a/infra-partners/operators/public-rpc-node.mdx +++ b/infra-partners/operators/public-rpc-node.mdx @@ -11,10 +11,10 @@ A public RPC endpoint should return any transaction by its hash. op-reth exposes ## Forward transactions to the sequencer -op-reth forwards transactions submitted to your endpoint to the sequencer so they are executed. The sequencer endpoint is set for you by the compose setup (via `OP_RETH__SEQUENCER_URL`): +op-reth forwards transactions submitted to your endpoint to the sequencer so they are executed, via the `--rollup.sequencer` flag. The sequencer endpoint is set for you by the compose setup (from `OP_RETH__SEQUENCER_URL`): -- Mainnet: `https://cel2-sequencer.celo.org` -- Celo Sepolia: `https://sequencer.celo-sepolia.celo-testnet.org` +- Mainnet: `--rollup.sequencer=https://cel2-sequencer.celo.org` +- Celo Sepolia: `--rollup.sequencer=https://sequencer.celo-sepolia.celo-testnet.org` If it is missing or wrong, transactions submitted to your node are accepted but never executed. From ece53b0f06aa223361171ae8a16469b25a1ae998 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 22 Jun 2026 10:55:18 +0200 Subject: [PATCH 11/14] review --- infra-partners/notices/op-geth-deprecation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/infra-partners/notices/op-geth-deprecation.mdx b/infra-partners/notices/op-geth-deprecation.mdx index 0cb22e9fa..0ef11ceb4 100644 --- a/infra-partners/notices/op-geth-deprecation.mdx +++ b/infra-partners/notices/op-geth-deprecation.mdx @@ -16,7 +16,7 @@ Celo is switching its execution client from `op-geth` to `op-reth`. All node ope Following [Optimism's](https://docs.optimism.io/notices/op-geth-deprecation) deprecation of op-geth, Celo will also discontinue support for `op-geth` and adopt `op-reth` as the primary execution client. -- **`op-geth`**: Supported only until the switch date for each network. After that, it will no longer be compatible with the network. +- **`op-geth`**: Supported only until the switch date for each network. After that, it might follow the wrong chain. - **`op-reth`**: The new supported execution client built on `reth`. - **`op-node`**: No changes. It remains fully supported. From 19e4c1d90209f6549e681e86c848fcb1e52eb8df Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 22 Jun 2026 15:59:23 +0200 Subject: [PATCH 12/14] operators: use Compose v2 (docker compose) in node guides Compose v1 (docker-compose) is end-of-life; align run-node and archive-node with the v2 syntax already used elsewhere. --- infra-partners/operators/archive-node.mdx | 6 +++--- infra-partners/operators/run-node.mdx | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/infra-partners/operators/archive-node.mdx b/infra-partners/operators/archive-node.mdx index 3d71d05b4..66adb4599 100644 --- a/infra-partners/operators/archive-node.mdx +++ b/infra-partners/operators/archive-node.mdx @@ -107,13 +107,13 @@ Ensure any datadir you supply is not in use by a running node before proceeding. 3. Start the node(s). ```bash - docker-compose up -d --build + docker compose up -d --build ``` 4. Check the progress of your L2 archive node as it syncs. ```bash - docker-compose logs -n 50 -f op-reth + docker compose logs -n 50 -f op-reth ``` This will display and follow the last 50 lines of logs. As the node syncs you will see `op-reth` executing blocks and its head advancing toward the network's latest block. @@ -145,6 +145,6 @@ Until your network's [switch date](/infra-partners/notices/op-geth-deprecation), - **Historical RPC variable.** Use `OP_GETH__HISTORICAL_RPC` in place of `OP_RETH__HISTORICAL_RPC`. - **P2P variables.** Use `OP_GETH__NAT` (values `any|none|upnp|pmp|pmp:|extip:|stun:`) and `PORT__OP_GETH_P2P` (default `30303`). -- **Logs.** Follow `docker-compose logs -n 50 -f op-geth`; a syncing node shows `Syncing beacon headers downloaded=...` and later `"Syncing: chain download in progress","synced":"21.07%"`. +- **Logs.** Follow `docker compose logs -n 50 -f op-geth`; a syncing node shows `Syncing beacon headers downloaded=...` and later `"Syncing: chain download in progress","synced":"21.07%"`. diff --git a/infra-partners/operators/run-node.mdx b/infra-partners/operators/run-node.mdx index dbad9f4e4..51ae68363 100644 --- a/infra-partners/operators/run-node.mdx +++ b/infra-partners/operators/run-node.mdx @@ -103,13 +103,13 @@ Follow these steps to run a full node. If you would like to run an archive node, 3. Start the node. ```bash - docker-compose up -d --build + docker compose up -d --build ``` 4. Check the progress of the node as it syncs. ```bash - docker-compose logs -n 50 -f op-reth + docker compose logs -n 50 -f op-reth ``` This will display and follow the last 50 lines of logs. As the node syncs you will see `op-reth` executing blocks and its head advancing toward the network's latest block. @@ -134,7 +134,7 @@ Until your network's [switch date](/infra-partners/notices/op-geth-deprecation), ``` - **P2P variables.** Use `OP_GETH__NAT` (values `any|none|upnp|pmp|pmp:|extip:|stun:`) and `PORT__OP_GETH_P2P` (default `30303`) in place of their `OP_RETH__` equivalents. -- **Logs.** Follow `docker-compose logs -n 50 -f op-geth`. A syncing node shows `Syncing beacon headers downloaded=...` and later `"Syncing: chain download in progress","synced":"21.07%"`; until fully synced the RPC API returns `0` for the head block number. +- **Logs.** Follow `docker compose logs -n 50 -f op-geth`. A syncing node shows `Syncing beacon headers downloaded=...` and later `"Syncing: chain download in progress","synced":"21.07%"`; until fully synced the RPC API returns `0` for the head block number. After your network's switch date, `op-geth` will no longer follow the chain — migrate to `op-reth` before then. From 0289dffca0e39e979e328c9a655e022193776d04 Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 22 Jun 2026 16:00:14 +0200 Subject: [PATCH 13/14] network-config: note chain is selected by name, no genesis/rollup files needed The celo-l2-node-docker-compose setup selects the chain by name (op-node --network, op-reth --chain), so genesis.json and rollup.json don't need to be supplied for the standard networks. --- infra-partners/operators/network-config.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/infra-partners/operators/network-config.mdx b/infra-partners/operators/network-config.mdx index 478a5f797..362bc482f 100644 --- a/infra-partners/operators/network-config.mdx +++ b/infra-partners/operators/network-config.mdx @@ -5,6 +5,12 @@ sidebarTitle: "Network Config & Assets" Bootnodes, container images, and downloadable artifacts needed to run a Celo L2 node on each network. + +**You don't need to supply `genesis.json` or `rollup.json`** + +The recommended [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) setup selects the chain by name: op-node loads the rollup config from the superchain registry with `--network` (`celo-mainnet` / `celo-sepolia`), and op-reth loads the chain spec — genesis included — with `--chain` (`celo` / `celo-sepolia`). The `genesis.json` and `rollup.json` files below are listed for reference and for custom or from-source setups. + + ## Mainnet - op-reth snapshots — published at [`snapshots.celo.org`](https://snapshots.celo.org); a mainnet node must bootstrap from one (`OP_RETH__SNAPSHOT=true`) for the pre-L2 history (see [Run a node](/infra-partners/operators/run-node)) From e4ff21f2324d366c0d4cdb5f46f7273e8d07a6ff Mon Sep 17 00:00:00 2001 From: Paul Lange Date: Mon, 22 Jun 2026 16:02:29 +0200 Subject: [PATCH 14/14] network-config: bump op-reth image to celo-v1.0.0-rc.1 --- infra-partners/operators/network-config.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/infra-partners/operators/network-config.mdx b/infra-partners/operators/network-config.mdx index 362bc482f..9ce155dd6 100644 --- a/infra-partners/operators/network-config.mdx +++ b/infra-partners/operators/network-config.mdx @@ -56,7 +56,7 @@ The recommended [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l ``` - Container images: - - [op-reth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-reth:celo-v0.0.1-rc.1) + - [op-reth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-reth:celo-v1.0.0-rc.1) - [op-node](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-node:celo-v2.1.0) - [eigenda-proxy](https://ghcr.io/layr-labs/eigenda-proxy:v1.8.2) - [op-geth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-geth:celo-v2.1.0) — legacy, until the switch date @@ -90,7 +90,7 @@ The recommended [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l ``` - Container images: - - [op-reth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-reth:celo-v0.0.1-rc.1) + - [op-reth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-reth:celo-v1.0.0-rc.1) - [op-node](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-node:celo-v2.1.0) - [eigenda-proxy](https://ghcr.io/layr-labs/eigenda-proxy:v1.8.2) - [op-geth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-geth:celo-v2.1.2) — legacy, until the switch date