diff --git a/build-on-celo/network-overview.mdx b/build-on-celo/network-overview.mdx index cb0a1c779..43b65a165 100644 --- a/build-on-celo/network-overview.mdx +++ b/build-on-celo/network-overview.mdx @@ -48,7 +48,7 @@ The Celo Sepolia Testnet is Celo's new developer testnet built on Ethereum Sepol **New Celo Sepolia Testnet Now Live!** Try Celo's new developer testnet on Ethereum Sepolia. -[Learn more →](/infra-partners/notices/celo-sepolia-launch) +[Learn more →](/infra-partners/notices/archive/celo-sepolia-launch) diff --git a/docs.json b/docs.json index de7bb58c3..aea907dfb 100644 --- a/docs.json +++ b/docs.json @@ -405,17 +405,23 @@ "tab": "Infra Partners", "groups": [ { - "group": "Notices", + "group": "Network Notices", "pages": [ + "infra-partners/notices/overview", "infra-partners/notices/op-geth-deprecation", "infra-partners/notices/req-resp-cl-sync-deprecation", - "infra-partners/notices/jovian-upgrade", - "infra-partners/notices/jello-upgrade", - "infra-partners/notices/l1-fusaka-upgrade", - "infra-partners/notices/celo-sepolia-launch", - "infra-partners/notices/eigenda-v2-upgrade", - "infra-partners/notices/isthmus-upgrade", - "infra-partners/notices/l2-migration" + { + "group": "Archive", + "pages": [ + "infra-partners/notices/archive/jovian-upgrade", + "infra-partners/notices/archive/jello-upgrade", + "infra-partners/notices/archive/l1-fusaka-upgrade", + "infra-partners/notices/archive/celo-sepolia-launch", + "infra-partners/notices/archive/eigenda-v2-upgrade", + "infra-partners/notices/archive/isthmus-upgrade", + "infra-partners/notices/archive/l2-migration" + ] + } ] }, { @@ -423,10 +429,27 @@ "pages": [ "infra-partners/operators/overview", "infra-partners/operators/architecture", - "infra-partners/operators/run-node", + "infra-partners/operators/run-node" + ] + }, + { + "group": "Node Management", + "pages": [ + "infra-partners/operators/archive-node", + "infra-partners/operators/public-rpc-node", + "infra-partners/operators/monitoring", + "infra-partners/operators/maintenance", + "infra-partners/operators/troubleshooting", "infra-partners/operators/migrate-node" ] }, + { + "group": "Reference", + "pages": [ + "infra-partners/operators/configuration", + "infra-partners/operators/network-config" + ] + }, { "group": "Celo L2 Specs", "pages": ["infra-partners/specs"] @@ -2795,19 +2818,47 @@ }, { "source": "/cel2/notices/celo-sepolia-launch", - "destination": "/infra-partners/notices/celo-sepolia-launch" + "destination": "/infra-partners/notices/archive/celo-sepolia-launch" }, { "source": "/cel2/notices/eigenda-v2-upgrade", - "destination": "/infra-partners/notices/eigenda-v2-upgrade" + "destination": "/infra-partners/notices/archive/eigenda-v2-upgrade" }, { "source": "/cel2/notices/isthmus-upgrade", - "destination": "/infra-partners/notices/isthmus-upgrade" + "destination": "/infra-partners/notices/archive/isthmus-upgrade" }, { "source": "/cel2/notices/l2-migration", - "destination": "/infra-partners/notices/l2-migration" + "destination": "/infra-partners/notices/archive/l2-migration" + }, + { + "source": "/infra-partners/notices/jovian-upgrade", + "destination": "/infra-partners/notices/archive/jovian-upgrade" + }, + { + "source": "/infra-partners/notices/jello-upgrade", + "destination": "/infra-partners/notices/archive/jello-upgrade" + }, + { + "source": "/infra-partners/notices/l1-fusaka-upgrade", + "destination": "/infra-partners/notices/archive/l1-fusaka-upgrade" + }, + { + "source": "/infra-partners/notices/celo-sepolia-launch", + "destination": "/infra-partners/notices/archive/celo-sepolia-launch" + }, + { + "source": "/infra-partners/notices/eigenda-v2-upgrade", + "destination": "/infra-partners/notices/archive/eigenda-v2-upgrade" + }, + { + "source": "/infra-partners/notices/isthmus-upgrade", + "destination": "/infra-partners/notices/archive/isthmus-upgrade" + }, + { + "source": "/infra-partners/notices/l2-migration", + "destination": "/infra-partners/notices/archive/l2-migration" }, { "source": "/cel2/operators/architecture", diff --git a/home/protocol/challengers.mdx b/home/protocol/challengers.mdx index 72cca988a..2737351db 100644 --- a/home/protocol/challengers.mdx +++ b/home/protocol/challengers.mdx @@ -3,7 +3,7 @@ title: Challengers description: Listing of the Celo Challengers --- -With the [Jello Hardfork](/infra-partners/notices/jello-upgrade), Celo switched to use OP Succinct Lite and introduced a set of independent challengers. Those challengers are responsible for checking the validity of the state roots sent to the L1. +With the [Jello Hardfork](/infra-partners/notices/archive/jello-upgrade), Celo switched to use OP Succinct Lite and introduced a set of independent challengers. Those challengers are responsible for checking the validity of the state roots sent to the L1. ## List of Challengers diff --git a/home/protocol/transactions/transaction-types.mdx b/home/protocol/transactions/transaction-types.mdx index b3ce8faae..6e70f5502 100644 --- a/home/protocol/transactions/transaction-types.mdx +++ b/home/protocol/transactions/transaction-types.mdx @@ -221,7 +221,7 @@ This transaction type is 100% compatible with Ethereum and has no Celo-specific [EIP-7702: Set Code for EOAs](https://eips.ethereum.org/EIPS/eip-7702). - It is scheduled for support on Celo during the - [Celo Isthmus](/infra-partners/notices/isthmus-upgrade) hardfork. + [Celo Isthmus](/infra-partners/notices/archive/isthmus-upgrade) hardfork. ### Legacy Transaction (`0`) diff --git a/infra-partners/notices/celo-sepolia-launch.mdx b/infra-partners/notices/archive/celo-sepolia-launch.mdx similarity index 100% rename from infra-partners/notices/celo-sepolia-launch.mdx rename to infra-partners/notices/archive/celo-sepolia-launch.mdx diff --git a/infra-partners/notices/eigenda-v2-upgrade.mdx b/infra-partners/notices/archive/eigenda-v2-upgrade.mdx similarity index 100% rename from infra-partners/notices/eigenda-v2-upgrade.mdx rename to infra-partners/notices/archive/eigenda-v2-upgrade.mdx diff --git a/infra-partners/notices/isthmus-upgrade.mdx b/infra-partners/notices/archive/isthmus-upgrade.mdx similarity index 100% rename from infra-partners/notices/isthmus-upgrade.mdx rename to infra-partners/notices/archive/isthmus-upgrade.mdx diff --git a/infra-partners/notices/jello-upgrade.mdx b/infra-partners/notices/archive/jello-upgrade.mdx similarity index 100% rename from infra-partners/notices/jello-upgrade.mdx rename to infra-partners/notices/archive/jello-upgrade.mdx diff --git a/infra-partners/notices/jovian-upgrade.mdx b/infra-partners/notices/archive/jovian-upgrade.mdx similarity index 100% rename from infra-partners/notices/jovian-upgrade.mdx rename to infra-partners/notices/archive/jovian-upgrade.mdx diff --git a/infra-partners/notices/l1-fusaka-upgrade.mdx b/infra-partners/notices/archive/l1-fusaka-upgrade.mdx similarity index 100% rename from infra-partners/notices/l1-fusaka-upgrade.mdx rename to infra-partners/notices/archive/l1-fusaka-upgrade.mdx diff --git a/infra-partners/notices/l2-migration.mdx b/infra-partners/notices/archive/l2-migration.mdx similarity index 100% rename from infra-partners/notices/l2-migration.mdx rename to infra-partners/notices/archive/l2-migration.mdx diff --git a/infra-partners/notices/overview.mdx b/infra-partners/notices/overview.mdx new file mode 100644 index 000000000..bff95d0d0 --- /dev/null +++ b/infra-partners/notices/overview.mdx @@ -0,0 +1,14 @@ +--- +title: "Overview" +sidebarTitle: "Overview" +description: "Active upgrade notices, deprecations, and network change announcements for Celo node operators." +--- + + + + Transition from op-geth to op-reth ahead of the Ethereum Glamsterdam hardfork. + + + The op-node Req/Res consensus-layer P2P sync client is deprecated in favor of execution-layer syncing. + + diff --git a/infra-partners/operators/architecture.mdx b/infra-partners/operators/architecture.mdx index 6b3985b06..5cc5db989 100644 --- a/infra-partners/operators/architecture.mdx +++ b/infra-partners/operators/architecture.mdx @@ -3,7 +3,7 @@ title: "Node Architecture" sidebarTitle: "Architecture" --- -This page reviews node architecture for all nodes running on the Celo network. All L2 Celo nodes are composed of two core software services, the Rollup Node and the Execution Client. Celo also optionally supports a third component, Legacy L1 Celo, that can serve stateful queries for blocks and transactions created before the L2 Upgrade. +This page reviews node architecture for all nodes running on the Celo network. All L2 Celo nodes are composed of two core software services, the Rollup Node and the Execution Client. Celo also optionally supports a third component, Legacy L1 Celo, that can serve stateful queries for blocks and transactions created before the [L2 migration](/infra-partners/notices/archive/l2-migration). ## Rollup node @@ -15,5 +15,5 @@ The Execution Client is responsible for executing the block payloads it receives ## Next steps -- To get your node up and running, start with the [operator guide](/infra-partners/operators/run-node). -- If you've already got a Celo node up and running, check out [how to migrate it to a L2 node](/infra-partners/operators/migrate-node). +- To get your node up and running, [run a node with Docker](/infra-partners/operators/run-node). +- If you are moving existing Celo L1 data to L2, see [how to migrate an L1 node](/infra-partners/operators/migrate-node). diff --git a/infra-partners/operators/archive-node.mdx b/infra-partners/operators/archive-node.mdx new file mode 100644 index 000000000..2fb4fa6bf --- /dev/null +++ b/infra-partners/operators/archive-node.mdx @@ -0,0 +1,136 @@ +--- +title: "Running an Archive Node" +sidebarTitle: "Run an Archive Node" +--- + + +**Archive node vs. historical proofs** + +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** + +These instructions use `op-geth`, which is supported only until the Ethereum Glamsterdam hardfork. 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 migration timeline; archive-node guidance for `op-reth` will follow once a Celo-compatible release is published. + + +## Overview + +To run an L2 archive node, you need to start the L2 execution client in archive mode. This allows the node to accept RPC requests that require archive data for blocks created after the L2 transition. For historical data from before the L2 transition, you can configure your node to forward those requests to a legacy Celo L1 archive node that contains the historical blockchain state. + +## Instructions + + +**Prerequisites** + +These instructions assume you already have + +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. + +Please ensure neither datadir is being used 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. + + ```bash + git clone https://github.com/celo-org/celo-l2-node-docker-compose.git + cd celo-l2-node-docker-compose + ``` + +2. Configure your `.env` file. + + #### Copy default configurations + + The [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repo contains a `.env` file for each Celo network (`celo-sepolia`, `mainnet`). Start by copying the default configuration for the appropriate network. + + ```bash + export NETWORK= + 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. + + To use `full` sync, configure `.env` as follows: + + ```text + OP_GETH__SYNCMODE=full + DATADIR_PATH= + ``` + + #### Configure node type + + To enable `archive` mode, configure `.env` as follows: + + ```text + NODE_TYPE=archive + ``` + + #### 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". + There are two ways to configure a Historical RPC Service for your archive node: + + 1. Supply a pre-hardfork archive datadir and let [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) start a legacy archive node. To do this configure `.env` as follows: + + ```text + HISTORICAL_RPC_DATADIR_PATH= + ``` + + When you start your L2 node, a legacy archive node will also start using the pre-hardfork archive datadir. Your L2 node will be configured to use the legacy archive node as its Historical RPC Service. + + 2. Start the legacy archive node yourself and configure `.env` as follows: + + ```text + OP_GETH__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. + + If you choose to run your own legacy archive node, you should do so with different flags than before the hardfork, as the node will no longer be syncing blocks or communicating with other nodes. To see how we recommend re-starting a legacy archive node as a Historical RPC Service, see [this script](https://github.com/celo-org/celo-l2-node-docker-compose/blob/30ee2c4ec2dacaff10aaba52e59969053c652f05/scripts/start-historical-rpc-node.sh#L19). + + #### Configure P2P for external network access + + + **Network Configuration** + + 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. + - `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. + +3. Start the node(s). + + ```bash + 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-geth + ``` + + 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. + +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. + + ```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 + ``` diff --git a/infra-partners/operators/configuration.mdx b/infra-partners/operators/configuration.mdx new file mode 100644 index 000000000..3cfd1708c --- /dev/null +++ b/infra-partners/operators/configuration.mdx @@ -0,0 +1,95 @@ +--- +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)). + + +**op-geth is being deprecated** + +The variables below configure `op-geth`, the execution client used today. Celo is transitioning to `op-reth` as the primary execution client ahead of the Ethereum Glamsterdam hardfork. See [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation); `op-reth` configuration will be documented once a Celo-compatible release ships. + + +## Node type and sync mode + +| 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`. | + +- **`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). + +## L1 connection + +| Variable | Description | +|---|---| +| `OP_NODE__RPC_ENDPOINT` | Layer 1 RPC endpoint. For reliability, use a paid plan or a self-hosted node. | +| `OP_NODE__L1_BEACON` | Layer 1 beacon endpoint. For reliability, use a paid plan or a self-hosted node. | +| `OP_NODE__RPC_TYPE` | Provider type for the L1 RPC endpoint: `alchemy`, `quicknode` (ETH only), `erigon`, or `basic` for other providers. | +| `HEALTHCHECK__REFERENCE_RPC_PROVIDER` | Public L2 RPC endpoint to compare against in the healthcheck (defaults to `https://forno.celo.org`). | + +## Historical state (pre-hardfork) + +An L2 archive node serves pre-hardfork state by proxying to a legacy Celo L1 archive node. + +| 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. | + +See [Running an archive node](/infra-partners/operators/archive-node) for the full setup. + +## Networking (P2P) + +Configure these so other nodes can discover and reach yours. If they are wrong, your node may fail to stay connected and synced. + +| 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:`. | + +## Ports + +Each `PORT__*` variable overrides a default exposed in `docker-compose.yml`. Defaults: + +| 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_NODE_HTTP` | `9545` | op-node RPC | +| `PORT__OP_NODE_P2P` | `9222` | op-node P2P | +| `PORT__HEALTHCHECK_METRICS` | `7300` | Healthcheck metrics | +| `PORT__PROMETHEUS` | `9090` | Prometheus | +| `PORT__GRAFANA` | `3000` | Grafana | +| `PORT__INFLUXDB` | `8086` | InfluxDB | +| `PORT__HISTORICAL_RPC_NODE_HTTP` | `9991` | Legacy L1 archive node (HTTP) | +| `PORT__HISTORICAL_RPC_NODE_WS` | `9992` | Legacy L1 archive node (WebSocket) | +| `PORT_EIGENDA_PROXY` | `4242` | EigenDA proxy | + +## Data directory + +| 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. | + +## 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. +- **`--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. +- **`--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. + +## Monitoring + +Set `MONITORING_ENABLED=true` to start the Grafana, Prometheus, InfluxDB, and healthcheck stack. See [Monitoring & metrics](/infra-partners/operators/monitoring). diff --git a/infra-partners/operators/maintenance.mdx b/infra-partners/operators/maintenance.mdx new file mode 100644 index 000000000..7a55c28a9 --- /dev/null +++ b/infra-partners/operators/maintenance.mdx @@ -0,0 +1,58 @@ +--- +title: "Upgrades & Maintenance" +sidebarTitle: "Upgrades & Maintenance" +--- + +Routine operational tasks for a running Celo L2 node, using the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) setup. + +## Upgrading your node + +To upgrade to the latest client versions: + +```sh +git pull +docker compose pull +docker compose up -d --build +``` + +This pulls the latest changes from GitHub and the latest images from the registry, rebuilds the containers, and restarts the node. + + +**Hardfork upgrades are time-sensitive** + +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 ahead of the Ethereum Glamsterdam hardfork — 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`). + +## Restarting and stopping + +```sh +# Restart with minimal downtime (no upgrade) +docker compose restart + +# Stop the node without wiping any data; safe to start again afterwards +docker compose down +``` + + +**`docker compose down -v` wipes all data** + +The `-v` flag deletes the node's volumes, including the chaindata. Only use it when you intend to discard everything and re-sync from scratch. + + +## Backing up your data + +The chaindata lives in `DATADIR_PATH` (default `./envs//datadir`). To back it up, stop the node first so the database is in a consistent state, then copy the datadir: + +```sh +docker compose down +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). diff --git a/infra-partners/operators/migrate-node.mdx b/infra-partners/operators/migrate-node.mdx index 3b5ca0856..8346f2e09 100644 --- a/infra-partners/operators/migrate-node.mdx +++ b/infra-partners/operators/migrate-node.mdx @@ -5,7 +5,7 @@ sidebarTitle: "Migrating an L1 Node" 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/run-node#network-config--assets) section. +You can find the latest snapshot in the [Network Config & Assets](/infra-partners/operators/network-config) section. This guide helps Celo L1 node operators migrate their nodes to Celo L2. It describes how to use the [migration tool](https://github.com/celo-org/optimism/tree/celo-rebase-12/op-chain-ops/cmd/celo-migrate) to transform pre-migration database snapshots into a format that Celo L2 nodes can use for a `full` sync. @@ -13,7 +13,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 -- **Pre-migrated data**: Download migrated datadirs from [Network Config & Assets](/infra-partners/operators/run-node#network-config--assets) +- **Pre-migrated data**: Download migrated datadirs from [Network Config & Assets](/infra-partners/operators/network-config) **Terminology** @@ -25,12 +25,11 @@ The terms L1 and pre-hardfork are used interchangeably to reference Celo before Migrating a pre-hardfork datadir involves these high-level steps: -1. Upgrade your L1 node to the [latest client release](/infra-partners/operators/run-node#mainnet-2) so it will stop producing blocks at the hardfork. -2. 1-2 days before the hardfork, stop your node and run a pre-migration to migrate the majority of data. This is not required, but is highly recommended for minimizing downtime. See [Preparing for the L2 migration](/infra-partners/notices/l2-migration). -3. Restart your node and wait for the hardfork. -4. Shut down your node once the hardfork block number is reached. -5. Run the migration tool to migrate your L1 datadir and produce the hardfork block. -6. Launch your L2 node with the migrated datadir. +1. Upgrade your L1 node to the [latest client release](/infra-partners/operators/network-config#mainnet) so it will stop producing blocks at the hardfork. +2. Restart your node and wait for the hardfork. +3. Shut down your node once the hardfork block number is reached. +4. Run the migration tool to migrate your L1 datadir and produce the hardfork block. +5. Launch your L2 node with the migrated datadir. ### Important Notes @@ -51,7 +50,7 @@ All node operators must upgrade their L1 (`celo-blockchain`) nodes to the requir **Archive Node Limitation** -Both pre-migration and full migration require **full node data only**. If you only have archive nodes, sync a full node before the hardfork. You cannot migrate archive data, even for L2 archive nodes. See [Running an archive node](/infra-partners/operators/run-node#running-an-archive-node) for details. +Both pre-migration and full migration require **full node data only**. If you only have archive nodes, sync a full node before the hardfork. You cannot migrate archive data, even for L2 archive nodes. See [Running an archive node](/infra-partners/operators/archive-node) for details. You can use either Docker or build from source. @@ -212,7 +211,7 @@ If you prefer not to use Docker, run the migration directly from source: - You can find the required input artifacts in the [Network config & Assets](/infra-partners/operators/run-node#network-config--assets) section. + You can find the required input artifacts in the [Network config & Assets](/infra-partners/operators/network-config) section. We recommend using the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) codebase as an additional reference for running the migration from source. @@ -250,7 +249,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/run-node#network-config--assets) section shortly after the hardfork, but we recommend having your own backup datadir available as well. + - 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. - 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/monitoring.mdx b/infra-partners/operators/monitoring.mdx new file mode 100644 index 000000000..13d05c76e --- /dev/null +++ b/infra-partners/operators/monitoring.mdx @@ -0,0 +1,65 @@ +--- +title: "Monitoring & Metrics" +sidebarTitle: "Monitoring" +--- + +The [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) setup ships with a monitoring stack so you can watch your node's health and sync status. + +## Enable monitoring + +Set the following in your `.env` file and restart: + +```text +MONITORING_ENABLED=true +``` + +This starts four services alongside your node: **Healthcheck**, **Prometheus**, **Grafana**, and **InfluxDB**. + +## Grafana dashboards + +With monitoring enabled, Grafana is available at [http://localhost:3000](http://localhost:3000) (configurable via `PORT__GRAFANA`). + +- **Username:** `admin` +- **Password:** `optimism` + +The **Simple Node Dashboard** (Dashboards → Manage → Simple Node Dashboard) shows basic node information and sync status. If you run the challenger, the **Succinct Challenger** dashboard shows challenger activity. + +## 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. + +## Key metrics to watch + +From **op-node** (Prometheus, `http://localhost:7300/metrics`): + +- **`op_node_default_refs_number`** — the op-node's current L1/L2 reference block numbers. If it stops increasing, your node is not syncing; if it goes backwards, your node is reorging. +- **`op_node_default_peer_count`** — how many peers op-node is connected to. Without peers, op-node cannot sync unsafe blocks and your node will lag behind the sequencer. +- **`op_node_default_rpc_client_request_duration_seconds`** — latency of the RPC calls op-node makes to L1 and to the execution client; useful for finding sync bottlenecks. + +From the **healthcheck** service: + +- **`healthcheck_reference_height - healthcheck_target_height`** — how far your node lags the reference RPC (`HEALTHCHECK__REFERENCE_RPC_PROVIDER`, default `https://forno.celo.org`). +- **`healthcheck_is_currently_diverged`** — non-zero if your node has diverged from the reference chain. + +For the full op-node metrics catalog, see the Optimism [Node Metrics and Monitoring](https://docs.optimism.io/node-operators/guides/monitoring/metrics) reference. + +## What healthy sync looks like + +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 + +# Check sync progress (requires foundry) +./progress.sh + +# Once synced, the head block number increases over time +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. + +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 new file mode 100644 index 000000000..70365369c --- /dev/null +++ b/infra-partners/operators/network-config.mdx @@ -0,0 +1,84 @@ +--- +title: "Network Config & Assets" +sidebarTitle: "Network Config & Assets" +--- + +Bootnodes, container images, and downloadable artifacts needed to run a Celo L2 node on each network. + +## Mainnet + +- [Full migrated chaindata](https://storage.googleapis.com/cel2-rollup-files/celo/celo-mainnet-migrated-chaindata.tar.zst) +- [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 +- P2P peers + - op-geth bootnode/peers, to be used with op-geth `--bootnodes` flag: + + ```text + enode://28f4fcb7f38c1b012087f7aef25dcb0a1257ccf1cdc4caa88584dc25416129069b514908c8cead5d0105cb0041dd65cd4ee185ae0d379a586fb07b1447e9de38@34.169.39.223:30303 + enode://a9077c3e030206954c5c7f22cc16a32cb5013112aa8985e3575fadda7884a508384e1e63c077b7d9fcb4a15c716465d8585567f047c564ada2e823145591e444@34.169.212.31:30303 + enode://029b007a7a56acbaa8ea50ec62cda279484bf3843fae1646f690566f784aca50e7d732a9a0530f0541e5ed82ba9bf2a4e21b9021559c5b8b527b91c9c7a38579@34.82.139.199:30303 + enode://f3c96b73a5772c5efb48d5a33bf193e58080d826ba7f03e9d5bdef20c0634a4f83475add92ab6313b7a24aa4f729689efb36f5093e5d527bb25e823f8a377224@34.82.84.247:30303 + enode://daa5ad65d16bcb0967cf478d9f20544bf1b6de617634e452dff7b947279f41f408b548261d62483f2034d237f61cbcf92a83fc992dbae884156f28ce68533205@34.168.45.168:30303 + enode://c79d596d77268387e599695d23e941c14c220745052ea6642a71ef7df31a13874cb7f2ce2ecf5a8a458cfc9b5d9219ce3e8bc6e5c279656177579605a5533c4f@35.247.32.229:30303 + enode://4151336075dd08eb6c75bfd63855e8a4bd6fd0f91ae4a81b14930f2671e16aee55495c139380c16e1094a49691875e69e40a3a5e2b4960c7859e7eb5745f9387@35.205.149.224:30303 + enode://ab999db751265c714b171344de1972ed74348162de465a0444f56e50b8cfd048725b213ba1fe48c15e3dfb0638e685ea9a21b8447a54eb2962c6768f43018e5c@34.79.3.199:30303 + enode://9d86d92fb38a429330546fe1aefce264e1f55c5d40249b63153e7df744005fa3c1e2da295e307041fd30ab1c618715f362c932c28715bc20bed7ae4fc76dea81@34.77.144.164:30303 + enode://c82c31f21dd5bbb8dc35686ff67a4353382b4017c9ec7660a383ccb5b8e3b04c6d7aefe71203e550382f6f892795728570f8190afd885efcb7b78fa398608699@34.76.202.74:30303 + enode://3bad5f57ad8de6541f02e36d806b87e7e9ca6d533c956e89a56b3054ae85d608784f2cd948dc685f7d6bbd5a2f6dd1a23cc03e529ea370dd72d880864a2af6a3@104.199.93.87:30303 + enode://1decf3b8b9a0d0b8332d15218f3bf0ceb9606b0efe18f352c51effc14bbf1f4f3f46711e1d460230cb361302ceaad2be48b5b187ad946e50d729b34e463268d2@35.240.26.148:30303 + ``` + + - op-node bootnodes, to be used with op-node `--p2p.bootnodes` flag: + + ```text + enr:-J64QJipvmFhMq6DVh6RR4HvIiiBtyy1NUg_QlnAAbf18SMqCxCPZtLgUiWED5p0HRVPv69Wth4YPsvdKXSUyh57mWuGAZXRp6HjgmlkgnY0gmlwhCJTtG-Hb3BzdGFja4TsyQIAiXNlY3AyNTZrMaECKPT8t_OMGwEgh_eu8l3LChJXzPHNxMqohYTcJUFhKQaDdGNwgiQGg3VkcIIkBg + enr:-J64QCxBGS49IQbkbwsUuVWt9CkMctMCRe0b-4dqRsLr4QJ1S52urWPUk2uhBU5uerRGpxWTZZW5FtJC-9gSBHN3cSiGAZXRp4rbgmlkgnY0gmlwhCKph0CHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaECqQd8PgMCBpVMXH8izBajLLUBMRKqiYXjV1-t2niEpQiDdGNwgiQGg3VkcIIkBg + enr:-J64QLG71bmmljNbLFx3qim6zXohKA3jbK_4C4d1cwixI-7VMoBIlnM6kWZVvvdWcbjTQ6QXB1LAO39eZWC4Heztj1-GAZXRpzUGgmlkgnY0gmlwhCKpySSHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDApsAenpWrLqo6lDsYs2ieUhL84Q_rhZG9pBWb3hKylCDdGNwgiQGg3VkcIIkBg + enr:-J64QKFU-u1x1gt3WmNP88EDUMQ316ymbzdGy83QjkBDqVSsJBn6-nipuqYQDeHYoLBLVJUMdyAiwxVbbDm14qQSf5qGAZXRppmIgmlkgnY0gmlwhCJTfzOHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEC88lrc6V3LF77SNWjO_GT5YCA2Ca6fwPp1b3vIMBjSk-DdGNwgiQGg3VkcIIkBg + enr:-J64QIXTVl0Opbdn20TSrkzpIZ4xQ54bERRlTmSeZ05dFLdlSbuRY7yn5tJeTPzsSldTw5V5E0qjEQcsfr20vMjTUDyGAZXRpiWygmlkgnY0gmlwhCPjrx6Hb3BzdGFja4TsyQIAiXNlY3AyNTZrMaED2qWtZdFrywlnz0eNnyBUS_G23mF2NORS3_e5RyefQfSDdGNwgiQGg3VkcIIkBg + enr:-J64QFAsbeR4xRSyVyQOk7bILUCoMjI2EnbZvo4UAK3842HMYw41-UZXdnQJH8lwvzWn7qsY3Vu73NuxzxWKn4XB5wiGAZXRpYPAgmlkgnY0gmlwhCJSxmKHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDx51ZbXcmg4flmWldI-lBwUwiB0UFLqZkKnHvffMaE4eDdGNwgiQGg3VkcIIkBg + enr:-J64QFQSrL3mfG-i64T-5DgVE5V9dGKC5A0JrEvD6CRpZvuLK3feg4bPaqFWfqXyNN_6IgY2z1Jkr4Mf2Zx-GdWlWquGAZXQkMdSgmlkgnY0gmlwhCImtd-Hb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDQVEzYHXdCOtsdb_WOFXopL1v0Pka5KgbFJMPJnHhau6DdGNwgiQGg3VkcIIkBg + enr:-J64QAp3g1m-5uX-_mBXWyo6ZQqAlnRcAt11Xwy0-ZzqaSrDSlg4adyOz6v9flzLgxYkVvXI50nJGs8GjLgT5bwDLtyGAZXQrD69gmlkgnY0gmlwhCJMJgaHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaECq5mdt1EmXHFLFxNE3hly7XQ0gWLeRloERPVuULjP0EiDdGNwgiQGg3VkcIIkBg + enr:-J64QFCZs1ePThNEsRxIIzbfDxYfap1nEyuPPpSUeeWOoPFWOp0zSEPwLEtXhG1eH-ipsB5CgtaVzcXOyT9hKeAeVVaGAZXQkaZ3gmlkgnY0gmlwhCO7ajaHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDnYbZL7OKQpMwVG_hrvziZOH1XF1AJJtjFT5990QAX6ODdGNwgiQGg3VkcIIkBg + enr:-J64QJ9LY8m9AjNgujuVT0juX8T6PHKojZEIqd-7_vhBasfiT2xUUJoUfWga_xVJGFECFcN6hPKB4TjihmYFxHXelwOGAZXQkclrgmlkgnY0gmlwhCJMELeHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDyCwx8h3Vu7jcNWhv9npDUzgrQBfJ7HZgo4PMtbjjsEyDdGNwgiQGg3VkcIIkBg + enr:-J64QGJFPZzLj2GLFgB4JhTde7rXChMNFERNbzrwYYTG7CY2SCSggFrU3VXczzWBvOoJWdbOMOzPuCI2klknGjruUxeGAZXQkf1LgmlkgnY0gmlwhGjHJzuHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDO61fV62N5lQfAuNtgGuH5-nKbVM8lW6JpWswVK6F1giDdGNwgiQGg3VkcIIkBg + enr:-J64QEXleDl25w0qEG__wmDgwnzB0F5zapu00D_jM4qkCbA3WIcLC8rXPm8dcrKdZNBuNXJOtNE6c2_ZDkuQMvIuhjCGAZXQwDjFgmlkgnY0gmlwhCKMdU-Hb3BzdGFja4TsyQIAiXNlY3AyNTZrMaECHezzuLmg0LgzLRUhjzvwzrlgaw7-GPNSxR7_wUu_H0-DdGNwgiQGg3VkcIIkBg + ``` + +- 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-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) + +## Celo Sepolia + +- [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 +- P2P peers: + - op-geth bootnode/peers, to be used with op-geth `--bootnodes` flag: + + ```text + enode://7fd35dfea27042fe008c74ea97c7a41254b293152730419a6e9bcd84bb03c7ced418c1043e2ef6ad63d2facca6fbdacfbf7c4bfcf33ee7e9a0e6b7eb0617595d@34.169.104.197:30303 + enode://151bcf170585971fc78129d9c16af355a1a53e1c825ce1ac20700ea754aa33eda60ca83de6f954bfed8d36c53f33295d93dbc3da9d549d6547d09467806b4b3d@104.199.124.11:30303 + enode://aa5fb766438ac5a0354eb2eec1c0c002b56bb2ce7ed44f0e76e019cbb931222faa9ecfb0fa0055c0c62a2fcf04492d4129349a1045dfef140585250281885e4b@34.83.115.97:30303 + enode://27c81ca466c99016d1595429afc68d66afb3ed9d5a2dd7f6a7797db23a4c826546a177b69b4932f3a75ce374b09d8ccc5b52dad615b3c47dbb8f6217d79ded22@35.247.1.226:30303 + ``` + + - op-node static peers, to be used with op-node `--p2p.bootnodes` flag: + + ```text + enr:-J-4QF7_9Y18cQSQ2wXHD_e65Qy82L1DpfVK4TlOuTDC9oAxeFxmvAn877A2ZXXfc08eLFgZP1mrRjkF4Kts1eGPGbKGAZg2ao5CgmlkgnY0gmlwhCKRF6aHb3BzdGFja4XMiKgFAIlzZWNwMjU2azGhA3_TXf6icEL-AIx06pfHpBJUspMVJzBBmm6bzYS7A8fOg3RjcIIkBoN1ZHCCJAY + enr:-J-4QEbMTKrBfyAeq9hWlEchulzvt1gWA-wAGa_kUdWw1K-faR-AjFNzhcVGG7yDnRb1RptLDGWVpl-WXWhrgJ4TKEaGAZg2XFFugmlkgnY0gmlwhCKotN-Hb3BzdGFja4XMiKgFAIlzZWNwMjU2azGhAxUbzxcFhZcfx4Ep2cFq81WhpT4cglzhrCBwDqdUqjPtg3RjcIIkBoN1ZHCCJAY + enr:-J-4QEawPak_hVU3h1wPZEGu7zLOv1C3k4WI8nHLUc83RqsRMauPtOPt8hYDFyxeJeaUyp0OUM0oyq-_9CEdshE1oWaGAZg2XLgDgmlkgnY0gmlwhCJSX5OHb3BzdGFja4XMiKgFAIlzZWNwMjU2azGhA6pft2ZDisWgNU6y7sHAwAK1a7LOftRPDnbgGcu5MSIvg3RjcIIkBoN1ZHCCJAY + enr:-J-4QCDpfivb0y0Sne1sZOqm1_WOKWWyJ6fo9j93jrxGVm0CcG6tScy3oQAaUuUbh-SmS_cQTO9ciw0_R3q1rpcjGLmGAZg2cWjGgmlkgnY0gmlwhCPFR5uHb3BzdGFja4XMiKgFAIlzZWNwMjU2azGhAifIHKRmyZAW0VlUKa_GjWavs-2dWi3X9qd5fbI6TIJlg3RjcIIkBoN1ZHCCJAY + ``` + +- Container images: + - [op-geth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-geth:celo-v2.1.2) + - [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) diff --git a/infra-partners/operators/overview.mdx b/infra-partners/operators/overview.mdx index ef22e9cb4..29714da21 100644 --- a/infra-partners/operators/overview.mdx +++ b/infra-partners/operators/overview.mdx @@ -1,12 +1,48 @@ --- -title: "Node Operators & Validators" +title: "Node Operators" sidebarTitle: "Overview" --- -While most applications should remain unaffected, node operators, validators, and RPC providers must ensure their systems are prepared for the transition to maintain seamless operations. +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. -See the following document for more details: +## What is a Celo L2 node? -* [Celo L2 migration](/infra-partners/notices/l2-migration) +A Celo L2 node is made up of two core services, plus an optional third: -See the guides for [running a node](/infra-partners/operators/run-node) or the guide on [how to migrate a L1 node](/infra-partners/operators/migrate-node). +- **Rollup node** (`op-node`) — derives L2 blocks from L1 data, analogous to a consensus client. +- **Execution client** — executes those blocks and exposes the standard Ethereum JSON-RPC API. +- **Legacy L1 (optional)** — serves stateful queries for blocks and transactions from before the L2 transition. + +See [Architecture](/infra-partners/operators/architecture) for how these fit together. + +## 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. +- **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 ahead of the Ethereum Glamsterdam hardfork but remains fully supported until then. All current guides use `op-geth`. + + +**op-geth is being deprecated** + +`op-geth` will not support the Ethereum Glamsterdam hardfork. All node operators must migrate to `op-reth` before that upgrade. See [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation) for details and follow the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repository for release updates. + + +## Guides + +- [Run a node with Docker](/infra-partners/operators/run-node) — the fastest way to get a full node syncing (also covers building from source). +- [Run an archive node](/infra-partners/operators/archive-node) — preserve access to all historical state. +- [Run a public RPC node](/infra-partners/operators/public-rpc-node) — operate a public JSON-RPC endpoint (and optionally earn rewards). +- [Monitoring & metrics](/infra-partners/operators/monitoring) — enable the Grafana/Prometheus stack and watch sync health. +- [Upgrades & maintenance](/infra-partners/operators/maintenance) — upgrade clients, restart safely, and back up your data. +- [Troubleshooting](/infra-partners/operators/troubleshooting) — fixes for common node issues. +- [Configuration reference](/infra-partners/operators/configuration) — the `.env` variables and key client flags. +- [Network Config & Assets](/infra-partners/operators/network-config) — bootnodes, container images, and downloadable artifacts. +- [Migrate an L1 node](/infra-partners/operators/migrate-node) — for operators moving existing Celo L1 data to L2 (legacy path). + +## Getting help + +Please reach out to our team on [Discord](https://chat.celo.org) in the [#celo-L2-support](https://discord.com/channels/600834479145353243/1286649605798367252) channel if you have any questions. diff --git a/infra-partners/operators/public-rpc-node.mdx b/infra-partners/operators/public-rpc-node.mdx new file mode 100644 index 000000000..cbee36137 --- /dev/null +++ b/infra-partners/operators/public-rpc-node.mdx @@ -0,0 +1,33 @@ +--- +title: "Running a Public RPC Node" +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 + +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. + +## Forward transactions to the sequencer + +Set `--rollup.sequencerhttp` so transactions submitted to your endpoint are forwarded to the sequencer and executed: + +- 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. + +## 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. + +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. + +## Earning rewards + +If you want to earn protocol rewards for operating a public RPC endpoint, register it with the Community RPC program: + +- [How it works](/contribute-to-celo/community-rpc-nodes/how-it-works) +- [Registering as an RPC node](/contribute-to-celo/community-rpc-nodes/registering-as-rpc-node) +- [Operating a Community RPC Node](/contribute-to-celo/community-rpc-nodes/community-rpc-node) (rewards and claiming) diff --git a/infra-partners/operators/run-node.mdx b/infra-partners/operators/run-node.mdx index 5987fcd8a..e52153578 100644 --- a/infra-partners/operators/run-node.mdx +++ b/infra-partners/operators/run-node.mdx @@ -1,8 +1,9 @@ --- -title: "Running a Celo Node" +title: "Running a Celo Node with Docker" +sidebarTitle: "Run a Node with Docker" --- -This guide is designed to help node operators run a Celo L2 node. +This guide is designed to help node operators run a Celo L2 node with Docker. **L1 to L2 data migration** @@ -10,6 +11,12 @@ This guide is designed to help node operators run a Celo L2 node. 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-geth`. Celo is transitioning to `op-reth` as the primary execution client ahead of the Ethereum Glamsterdam hardfork; `op-geth` remains fully supported until then. See [End of Support for op-geth](/infra-partners/notices/op-geth-deprecation) for the transition timeline. + + ## Recommended Hardware ### Mainnet @@ -31,24 +38,16 @@ If you wish to migrate data from a Celo L1 node and have not yet done so, please Storage size requirements will increase over time, especially for archive nodes. -If running an archive node, please make sure you also have enough storage for the legacy Celo L1 archive datadir. See [Running an archive node](#running-an-archive-node). +If running an archive node, please make sure you also have enough storage for the legacy Celo L1 archive datadir. See [Running an archive node](/infra-partners/operators/archive-node). ## Run Node with Docker To simplify running nodes, Celo has created the [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repository with all the necessary configuration files and docker compose templates to make running a Celo L2 node easy. -See the [README](https://github.com/celo-org/celo-l2-node-docker-compose/blob/main/README.md) for instructions on installing docker and docker compose if needed. - - -**Docker Desktop on MacOS** - -You will most likely need to increase the virtual disk limit in order to accommodate the chaindata directory. This can be done by opening Docker Desktop, going to Settings -> Resources -> Advanced and increasing the disk image size. - - ### Running a Full Node -Follow these steps to run a full node. If you would like to run an archive node, see [below](#running-an-archive-node). +Follow these steps to run a full node. If you would like to run an archive node, see [Running an archive node](/infra-partners/operators/archive-node). 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. @@ -83,7 +82,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](#running-an-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. 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. #### Configure P2P for external network access @@ -122,227 +121,12 @@ Follow these steps to run a full node. If you would like to run an archive node, Note that until fully synced, the RPC API will return 0 for the head block number. -### Running an Archive Node - -#### Overview - -To run an L2 archive node, you need to start the L2 execution client in archive mode. This allows the node to accept RPC requests that require archive data for blocks created after the L2 transition. For historical data from before the L2 transition, you can configure your node to forward those requests to a legacy Celo L1 archive node that contains the historical blockchain state. - -#### Instructions - - -**Prerequisites** - -These instructions assume you already have - -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. - -Please ensure neither datadir is being used 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. - - ```bash - git clone https://github.com/celo-org/celo-l2-node-docker-compose.git - cd celo-l2-node-docker-compose - ``` - -2. Configure your `.env` file. - - #### Copy default configurations - - The [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) repo contains a `.env` file for each Celo network (`celo-sepolia`, `mainnet`). Start by copying the default configuration for the appropriate network. - - ```bash - export NETWORK= - 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. - - To use `full` sync, configure `.env` as follows: - - ```text - OP_GETH__SYNCMODE=full - DATADIR_PATH= - ``` - - #### Configure node type - - To enable `archive` mode, configure `.env` as follows: - - ```text - NODE_TYPE=archive - ``` - - #### 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". - There are two ways to configure a Historical RPC Service for your archive node: - - 1. Supply a pre-hardfork archive datadir and let [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) start a legacy archive node. To do this configure `.env` as follows: - - ```text - HISTORICAL_RPC_DATADIR_PATH= - ``` - - When you start your L2 node, a legacy archive node will also start using the pre-hardfork archive datadir. Your L2 node will be configured to use the legacy archive node as its Historical RPC Service. - - 2. Start the legacy archive node yourself and configure `.env` as follows: - - ```text - OP_GETH__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. - - If you choose to run your own legacy archive node, you should do so with different flags than before the hardfork, as the node will no longer be syncing blocks or communicating with other nodes. To see how we recommend re-starting a legacy archive node as a Historical RPC Service, see [this script](https://github.com/celo-org/celo-l2-node-docker-compose/blob/30ee2c4ec2dacaff10aaba52e59969053c652f05/scripts/start-historical-rpc-node.sh#L19). - - #### Configure P2P for external network access - - - **Network Configuration** - - 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. - - `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. - -3. Start the node(s). - - ```bash - 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-geth - ``` - - 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. - -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. - - ```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 - ``` - -## Building a Node from Source - -Docker images are the easiest way to run a Celo node, but you can always build your own node from source code. You might wish to do this if you want to run on a specific architecture or inspect the source code. - -The [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) codebase is still the best reference for how to run your nodes from source, and below you can find all the [Network config & Assets](#network-config--assets) needed to participate in the hardfork. - -## Network Config & Assets - -### Mainnet - -- [Full migrated chaindata](https://storage.googleapis.com/cel2-rollup-files/celo/celo-mainnet-migrated-chaindata.tar.zst) -- [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 -- P2P peers - - op-geth bootnode/peers, to be used with op-geth `--bootnodes` flag: - - ```text - enode://28f4fcb7f38c1b012087f7aef25dcb0a1257ccf1cdc4caa88584dc25416129069b514908c8cead5d0105cb0041dd65cd4ee185ae0d379a586fb07b1447e9de38@34.169.39.223:30303 - enode://a9077c3e030206954c5c7f22cc16a32cb5013112aa8985e3575fadda7884a508384e1e63c077b7d9fcb4a15c716465d8585567f047c564ada2e823145591e444@34.169.212.31:30303 - enode://029b007a7a56acbaa8ea50ec62cda279484bf3843fae1646f690566f784aca50e7d732a9a0530f0541e5ed82ba9bf2a4e21b9021559c5b8b527b91c9c7a38579@34.82.139.199:30303 - enode://f3c96b73a5772c5efb48d5a33bf193e58080d826ba7f03e9d5bdef20c0634a4f83475add92ab6313b7a24aa4f729689efb36f5093e5d527bb25e823f8a377224@34.82.84.247:30303 - enode://daa5ad65d16bcb0967cf478d9f20544bf1b6de617634e452dff7b947279f41f408b548261d62483f2034d237f61cbcf92a83fc992dbae884156f28ce68533205@34.168.45.168:30303 - enode://c79d596d77268387e599695d23e941c14c220745052ea6642a71ef7df31a13874cb7f2ce2ecf5a8a458cfc9b5d9219ce3e8bc6e5c279656177579605a5533c4f@35.247.32.229:30303 - enode://4151336075dd08eb6c75bfd63855e8a4bd6fd0f91ae4a81b14930f2671e16aee55495c139380c16e1094a49691875e69e40a3a5e2b4960c7859e7eb5745f9387@35.205.149.224:30303 - enode://ab999db751265c714b171344de1972ed74348162de465a0444f56e50b8cfd048725b213ba1fe48c15e3dfb0638e685ea9a21b8447a54eb2962c6768f43018e5c@34.79.3.199:30303 - enode://9d86d92fb38a429330546fe1aefce264e1f55c5d40249b63153e7df744005fa3c1e2da295e307041fd30ab1c618715f362c932c28715bc20bed7ae4fc76dea81@34.77.144.164:30303 - enode://c82c31f21dd5bbb8dc35686ff67a4353382b4017c9ec7660a383ccb5b8e3b04c6d7aefe71203e550382f6f892795728570f8190afd885efcb7b78fa398608699@34.76.202.74:30303 - enode://3bad5f57ad8de6541f02e36d806b87e7e9ca6d533c956e89a56b3054ae85d608784f2cd948dc685f7d6bbd5a2f6dd1a23cc03e529ea370dd72d880864a2af6a3@104.199.93.87:30303 - enode://1decf3b8b9a0d0b8332d15218f3bf0ceb9606b0efe18f352c51effc14bbf1f4f3f46711e1d460230cb361302ceaad2be48b5b187ad946e50d729b34e463268d2@35.240.26.148:30303 - ``` - - - op-node bootnodes, to be used with op-node `--p2p.bootnodes` flag: - - ```text - enr:-J64QJipvmFhMq6DVh6RR4HvIiiBtyy1NUg_QlnAAbf18SMqCxCPZtLgUiWED5p0HRVPv69Wth4YPsvdKXSUyh57mWuGAZXRp6HjgmlkgnY0gmlwhCJTtG-Hb3BzdGFja4TsyQIAiXNlY3AyNTZrMaECKPT8t_OMGwEgh_eu8l3LChJXzPHNxMqohYTcJUFhKQaDdGNwgiQGg3VkcIIkBg - enr:-J64QCxBGS49IQbkbwsUuVWt9CkMctMCRe0b-4dqRsLr4QJ1S52urWPUk2uhBU5uerRGpxWTZZW5FtJC-9gSBHN3cSiGAZXRp4rbgmlkgnY0gmlwhCKph0CHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaECqQd8PgMCBpVMXH8izBajLLUBMRKqiYXjV1-t2niEpQiDdGNwgiQGg3VkcIIkBg - enr:-J64QLG71bmmljNbLFx3qim6zXohKA3jbK_4C4d1cwixI-7VMoBIlnM6kWZVvvdWcbjTQ6QXB1LAO39eZWC4Heztj1-GAZXRpzUGgmlkgnY0gmlwhCKpySSHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDApsAenpWrLqo6lDsYs2ieUhL84Q_rhZG9pBWb3hKylCDdGNwgiQGg3VkcIIkBg - enr:-J64QKFU-u1x1gt3WmNP88EDUMQ316ymbzdGy83QjkBDqVSsJBn6-nipuqYQDeHYoLBLVJUMdyAiwxVbbDm14qQSf5qGAZXRppmIgmlkgnY0gmlwhCJTfzOHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEC88lrc6V3LF77SNWjO_GT5YCA2Ca6fwPp1b3vIMBjSk-DdGNwgiQGg3VkcIIkBg - enr:-J64QIXTVl0Opbdn20TSrkzpIZ4xQ54bERRlTmSeZ05dFLdlSbuRY7yn5tJeTPzsSldTw5V5E0qjEQcsfr20vMjTUDyGAZXRpiWygmlkgnY0gmlwhCPjrx6Hb3BzdGFja4TsyQIAiXNlY3AyNTZrMaED2qWtZdFrywlnz0eNnyBUS_G23mF2NORS3_e5RyefQfSDdGNwgiQGg3VkcIIkBg - enr:-J64QFAsbeR4xRSyVyQOk7bILUCoMjI2EnbZvo4UAK3842HMYw41-UZXdnQJH8lwvzWn7qsY3Vu73NuxzxWKn4XB5wiGAZXRpYPAgmlkgnY0gmlwhCJSxmKHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDx51ZbXcmg4flmWldI-lBwUwiB0UFLqZkKnHvffMaE4eDdGNwgiQGg3VkcIIkBg - enr:-J64QFQSrL3mfG-i64T-5DgVE5V9dGKC5A0JrEvD6CRpZvuLK3feg4bPaqFWfqXyNN_6IgY2z1Jkr4Mf2Zx-GdWlWquGAZXQkMdSgmlkgnY0gmlwhCImtd-Hb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDQVEzYHXdCOtsdb_WOFXopL1v0Pka5KgbFJMPJnHhau6DdGNwgiQGg3VkcIIkBg - enr:-J64QAp3g1m-5uX-_mBXWyo6ZQqAlnRcAt11Xwy0-ZzqaSrDSlg4adyOz6v9flzLgxYkVvXI50nJGs8GjLgT5bwDLtyGAZXQrD69gmlkgnY0gmlwhCJMJgaHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaECq5mdt1EmXHFLFxNE3hly7XQ0gWLeRloERPVuULjP0EiDdGNwgiQGg3VkcIIkBg - enr:-J64QFCZs1ePThNEsRxIIzbfDxYfap1nEyuPPpSUeeWOoPFWOp0zSEPwLEtXhG1eH-ipsB5CgtaVzcXOyT9hKeAeVVaGAZXQkaZ3gmlkgnY0gmlwhCO7ajaHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDnYbZL7OKQpMwVG_hrvziZOH1XF1AJJtjFT5990QAX6ODdGNwgiQGg3VkcIIkBg - enr:-J64QJ9LY8m9AjNgujuVT0juX8T6PHKojZEIqd-7_vhBasfiT2xUUJoUfWga_xVJGFECFcN6hPKB4TjihmYFxHXelwOGAZXQkclrgmlkgnY0gmlwhCJMELeHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDyCwx8h3Vu7jcNWhv9npDUzgrQBfJ7HZgo4PMtbjjsEyDdGNwgiQGg3VkcIIkBg - enr:-J64QGJFPZzLj2GLFgB4JhTde7rXChMNFERNbzrwYYTG7CY2SCSggFrU3VXczzWBvOoJWdbOMOzPuCI2klknGjruUxeGAZXQkf1LgmlkgnY0gmlwhGjHJzuHb3BzdGFja4TsyQIAiXNlY3AyNTZrMaEDO61fV62N5lQfAuNtgGuH5-nKbVM8lW6JpWswVK6F1giDdGNwgiQGg3VkcIIkBg - enr:-J64QEXleDl25w0qEG__wmDgwnzB0F5zapu00D_jM4qkCbA3WIcLC8rXPm8dcrKdZNBuNXJOtNE6c2_ZDkuQMvIuhjCGAZXQwDjFgmlkgnY0gmlwhCKMdU-Hb3BzdGFja4TsyQIAiXNlY3AyNTZrMaECHezzuLmg0LgzLRUhjzvwzrlgaw7-GPNSxR7_wUu_H0-DdGNwgiQGg3VkcIIkBg - ``` - -- 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-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) - -### Celo Sepolia - -- [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 -- P2P peers: - - op-geth bootnode/peers, to be used with op-geth `--bootnodes` flag: - - ```text - enode://7fd35dfea27042fe008c74ea97c7a41254b293152730419a6e9bcd84bb03c7ced418c1043e2ef6ad63d2facca6fbdacfbf7c4bfcf33ee7e9a0e6b7eb0617595d@34.169.104.197:30303 - enode://151bcf170585971fc78129d9c16af355a1a53e1c825ce1ac20700ea754aa33eda60ca83de6f954bfed8d36c53f33295d93dbc3da9d549d6547d09467806b4b3d@104.199.124.11:30303 - enode://aa5fb766438ac5a0354eb2eec1c0c002b56bb2ce7ed44f0e76e019cbb931222faa9ecfb0fa0055c0c62a2fcf04492d4129349a1045dfef140585250281885e4b@34.83.115.97:30303 - enode://27c81ca466c99016d1595429afc68d66afb3ed9d5a2dd7f6a7797db23a4c826546a177b69b4932f3a75ce374b09d8ccc5b52dad615b3c47dbb8f6217d79ded22@35.247.1.226:30303 - ``` - - - op-node static peers, to be used with op-node `--p2p.bootnodes` flag: - - ```text - enr:-J-4QF7_9Y18cQSQ2wXHD_e65Qy82L1DpfVK4TlOuTDC9oAxeFxmvAn877A2ZXXfc08eLFgZP1mrRjkF4Kts1eGPGbKGAZg2ao5CgmlkgnY0gmlwhCKRF6aHb3BzdGFja4XMiKgFAIlzZWNwMjU2azGhA3_TXf6icEL-AIx06pfHpBJUspMVJzBBmm6bzYS7A8fOg3RjcIIkBoN1ZHCCJAY - enr:-J-4QEbMTKrBfyAeq9hWlEchulzvt1gWA-wAGa_kUdWw1K-faR-AjFNzhcVGG7yDnRb1RptLDGWVpl-WXWhrgJ4TKEaGAZg2XFFugmlkgnY0gmlwhCKotN-Hb3BzdGFja4XMiKgFAIlzZWNwMjU2azGhAxUbzxcFhZcfx4Ep2cFq81WhpT4cglzhrCBwDqdUqjPtg3RjcIIkBoN1ZHCCJAY - enr:-J-4QEawPak_hVU3h1wPZEGu7zLOv1C3k4WI8nHLUc83RqsRMauPtOPt8hYDFyxeJeaUyp0OUM0oyq-_9CEdshE1oWaGAZg2XLgDgmlkgnY0gmlwhCJSX5OHb3BzdGFja4XMiKgFAIlzZWNwMjU2azGhA6pft2ZDisWgNU6y7sHAwAK1a7LOftRPDnbgGcu5MSIvg3RjcIIkBoN1ZHCCJAY - enr:-J-4QCDpfivb0y0Sne1sZOqm1_WOKWWyJ6fo9j93jrxGVm0CcG6tScy3oQAaUuUbh-SmS_cQTO9ciw0_R3q1rpcjGLmGAZg2cWjGgmlkgnY0gmlwhCPFR5uHb3BzdGFja4XMiKgFAIlzZWNwMjU2azGhAifIHKRmyZAW0VlUKa_GjWavs-2dWi3X9qd5fbI6TIJlg3RjcIIkBoN1ZHCCJAY - ``` - -- Container images: - - [op-geth](https://us-west1-docker.pkg.dev/devopsre/celo-blockchain-public/op-geth:celo-v2.1.2) - - [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) - -## 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. - -- Mainnet: `--rollup.sequencerhttp=https://cel2-sequencer.celo.org/` -- Celo Sepolia: `--rollup.sequencerhttp=https://sequencer.celo-sepolia.celo-testnet.org` - -### Self-Hosted Public RPC Does Not Retrieve Transactions by Hash +## Build from source -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. +Docker images are the easiest way to run a Celo node, but you can also build from source — for example to run on a specific architecture or to inspect the code. The [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) codebase is the best reference, and the [Network Config & Assets](/infra-partners/operators/network-config) page lists everything you need to participate in the network. -## Getting Help +## Next steps -Please reach out to our team on [Discord](https://chat.celo.org) in the [#celo-L2-support](https://discord.com/channels/600834479145353243/1286649605798367252) channel if you have any questions. +- [Run an archive node](/infra-partners/operators/archive-node) — preserve access to all historical state. +- [Network Config & Assets](/infra-partners/operators/network-config) — bootnodes, container images, and downloadable artifacts. +- [Troubleshooting](/infra-partners/operators/troubleshooting) — fixes for common node issues, plus how to get help. diff --git a/infra-partners/operators/troubleshooting.mdx b/infra-partners/operators/troubleshooting.mdx new file mode 100644 index 000000000..7665ade85 --- /dev/null +++ b/infra-partners/operators/troubleshooting.mdx @@ -0,0 +1,43 @@ +--- +title: "Troubleshooting" +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. + +- Mainnet: `--rollup.sequencerhttp=https://cel2-sequencer.celo.org/` +- Celo Sepolia: `--rollup.sequencerhttp=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. + +## Checking Sync Progress + +If you are unsure whether your node is syncing, follow the op-geth logs and watch the sync percentage climb: + +```sh +docker compose logs -n 50 -f op-geth +``` + +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: + +```sh +cast block-number --rpc-url http://localhost:9993 +``` + +See [Monitoring & metrics](/infra-partners/operators/monitoring) for the Grafana dashboard and the metrics that show sync health. + +## Node Is Not Syncing or Has No Peers + +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). + +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). + +## Getting Help + +Please reach out to our team on [Discord](https://chat.celo.org) in the [#celo-L2-support](https://discord.com/channels/600834479145353243/1286649605798367252) channel if you have any questions. diff --git a/infra-partners/specs.mdx b/infra-partners/specs.mdx index dccfe4f98..4b75dbe50 100644 --- a/infra-partners/specs.mdx +++ b/infra-partners/specs.mdx @@ -1,5 +1,5 @@ --- title: Celo L2 Specs url: https://specs.celo.org/ -sidebarTitle: Getting Started ---- \ No newline at end of file +sidebarTitle: Specification +--- diff --git a/legacy/transition/whats-changed/l1-l2.mdx b/legacy/transition/whats-changed/l1-l2.mdx index fd0ffb78b..ec69c796c 100644 --- a/legacy/transition/whats-changed/l1-l2.mdx +++ b/legacy/transition/whats-changed/l1-l2.mdx @@ -87,7 +87,7 @@ Historically, the Celo L1 generated block receipts when system contract calls em ### Pre-transition execution and state access -RPC API calls for pre-transition blocks that are performing execution or accessing state are not directly supported by the new Celo L2 implementation. However, you can configure your Celo L2 node to proxy to an archive Celo L1 node for these calls. See the [archive node docs](/infra-partners/operators/run-node#running-an-archive-node). +RPC API calls for pre-transition blocks that are performing execution or accessing state are not directly supported by the new Celo L2 implementation. However, you can configure your Celo L2 node to proxy to an archive Celo L1 node for these calls. See the [archive node docs](/infra-partners/operators/archive-node). ## Unsupported geth keystore API diff --git a/tooling/testnets/celo-sepolia/index.mdx b/tooling/testnets/celo-sepolia/index.mdx index d974debad..d86022c9c 100644 --- a/tooling/testnets/celo-sepolia/index.mdx +++ b/tooling/testnets/celo-sepolia/index.mdx @@ -25,7 +25,7 @@ The full network information is available [in the network overview](/build-on-ce **New Celo Sepolia Testnet Now Live!** Try Celo's new developer testnet on Ethereum Sepolia. -[Learn more →](/infra-partners/notices/celo-sepolia-launch) +[Learn more →](/infra-partners/notices/archive/celo-sepolia-launch) @@ -51,4 +51,4 @@ For developers currently using Alfajores, consider the following when migrating ## Network Configuration -For detailed network configuration including RPC endpoints, contract addresses, and P2P peer information, see the [Running a Node guide](/infra-partners/operators/run-node#celo-sepolia). \ No newline at end of file +For detailed network configuration including RPC endpoints, contract addresses, and P2P peer information, see the [Network Config & Assets](/infra-partners/operators/network-config#celo-sepolia) page. \ No newline at end of file