L1 to L2 data migrationIf you wish to migrate data from a Celo L1 node and have not yet done so, please see the migration guide before continuing. Alternatively, you can
snap
sync from scratch without migrating existing L1 data.Recommended Hardware
Mainnet
- 16GB+ RAM
- 1TB+ SSD (NVME Recommended)
- Minimum 4 CPU, recommended 8 CPU
- 100mb/s+ Download
Testnets (Alfajores, Baklava, and Celo Sepolia)
- 16GB+ RAM
- 500GB SSD (NVME Recommended)
- Minimum 4 CPU, recommended 8 CPU
- 100mb/s+ Download
Storage RequirementsStorage 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.
Run Node with Docker
To simplify running nodes, Celo has created the 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 for instructions on installing docker and docker compose if needed.Docker Desktop on MacOSYou will most likely need to increase the virtual disk limit in order to accomodate 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.-
Pull the latest version of celo-l2-node-docker-compose and
cd
into the root of the project. -
Configure your
.env
file.Copy default configurations
The celo-l2-node-docker-compose repo contains a<network>.env
file for each Celo network (alfajores
,baklava
,celo-sepolia
, andmainnet
). Start by copying the default configuration for the appropriate network.Configure sync mode
By default, celo-l2-node-docker-compose will start your node withsnap
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. Alternatively, you can start your node withfull
sync if you have a migrated L1 datadir. For instructions on obtaining a migrated L1 datadir, please see Migrating an L1 Node. To usefull
sync, configure.env
as follows:Configure node type
Your node will run as afull
node by default, but can also be configured as anarchive
node if you wish to preserve access to all historical state. Note thatfull
has a different meaning here than in the context of syncing. See Running an archive node for more information.Configure P2P for external network access
Network ConfigurationIf 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 ofany
will try to automatically determine the public IP, but the most reliable approach is to explicitly set the public IP usingextip:<your-public-ip>
. Other acceptable values are(any|none|upnp|pmp|pmp:<IP>|extip:<IP>|stun:<IP:PORT>)
.PORT__OP_GETH_P2P
- Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 30303.
-
Start the node.
-
Check the progress of the node as it syncs.
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. -
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.
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
PrerequisitesThese instructions assume you already have
- A migrated full node datadir that has been synced to the migration block. See Migrating an L1 Node if you do not have this.
- A non-migrated Celo L1 archive node datadir. Do not attempt to migrate an archive datadir.
-
Pull the latest version of celo-l2-node-docker-compose and
cd
into the root of the project. -
Configure your
.env
file.Copy default configurations
The celo-l2-node-docker-compose repo contains a<network>.env
file for each Celo network (alfajores
,baklava
,celo-sepolia
, andmainnet
). Start by copying the default configuration for the appropriate network.Configure sync mode
By default, celo-l2-node-docker-compose will start your node withsnap
sync. Whilearchive
nodes can technically run withsnap
sync, they will only store archive data from the point thatsnap
sync completes. This will leave a gap in the archive data after the hardfork, so we recommend running archive nodes withfull
sync and a migrated pre-hardfork datadir. To usefull
sync, configure.env
as follows:Configure node type
To enablearchive
mode, configure.env
as follows: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:-
Supply a pre-hardfork archive datadir and let celo-l2-node-docker-compose start a legacy archive node. To do this configure
.env
as follows: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. -
Start the legacy archive node yourself and configure
.env
as follows:This will cause any value you set forHISTORICAL_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.
Configure P2P for external network access
Network ConfigurationIf 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 ofany
will try to automatically determine the public IP, but the most reliable approach is to explicitly set the public IP usingextip:<your-public-ip>
. Other acceptable values are(any|none|upnp|pmp|pmp:<IP>|extip:<IP>|stun:<IP:PORT>)
.PORT__OP_GETH_P2P
- Specifies the port to be shared via discovery so that other nodes can connect to your node. Defaults to 30303.
-
Supply a pre-hardfork archive datadir and let celo-l2-node-docker-compose start a legacy archive node. To do this configure
-
Start the node(s).
-
Check the progress of your L2 archive node as it syncs.
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. -
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.
Note that until fully synced, the RPC API will return 0 for the head block number.
-
Try querying historical state to test archive functionality.
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 codebase is still the best reference for how to run your nodes from source, and below you can find all the Network config & Assets needed to participate in the hardfork.Network Config & Assets
Mainnet
- Full migrated chaindata
- Rollup deploy config
- L1 contract addresses
- L2 allocs
- rollup.json
- Genesis used for snap syncing
-
P2P peers
-
op-geth bootnode/peers, to be used with op-geth
--bootnodes
flag: -
op-node bootnodes, to be used with op-node
--p2p.bootnodes
flag:
-
op-geth bootnode/peers, to be used with op-geth
- Container images:
Alfajores
- Full migrated chaindata
- Rollup deploy config
- L1 contract addresses
- L2 allocs
- rollup.json
- Genesis used for snap syncing
-
P2P peers:
-
op-geth bootnode/peers, to be used with op-geth
--bootnodes
flag: -
op-node static peers, to be used with op-node
--p2p.bootnodes
flag:
-
op-geth bootnode/peers, to be used with op-geth
- Container images:
Baklava
- Final Celo L1 chaindata
- Full migrated chaindata
- Rollup deploy config
- L1 contract addresses
- L2 allocs
- rollup.json
- Genesis used for snap syncing
-
P2P peers:
-
op-geth bootnode/peers, to be used with op-geth
--bootnodes
flag: -
op-node static peers, to be used with op-node
--p2p.bootnodes
flag:
-
op-geth bootnode/peers, to be used with op-geth
- Container images:
Celo Sepolia
- L1 contract addresses
- rollup.json
- Genesis used for snap syncing
-
P2P peers:
-
op-geth bootnode/peers, to be used with op-geth
--bootnodes
flag: -
op-node static peers, to be used with op-node
--p2p.bootnodes
flag:
-
op-geth bootnode/peers, to be used with op-geth
- Container images:
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/
- Alfajores:
--rollup.sequencerhttp=https://sequencer.alfajores.celo-testnet.org
- Baklava:
--rollup.sequencerhttp=https://sequencer.baklava.celo-testnet.org
- Celo Sepolia:
--rollup.sequencerhttp=https://sequencer.celo-sepolia.celo-testnet.org
Self-Hosted Public RPC Does Not Retrieve Transactions by Hash
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.