This page describes the historical Celo Layer 1 blockchain. It is useful for understanding Celo’s history, but does not reflect the current state of the network. As of block height 31,056,500 (March 26, 2025, 3:00 AM UTC), Celo has transitioned to an Ethereum Layer 2.
Recent Releases
When an upgrade is required
Upgrades to the Celo node software will often be optional improvements, such as improvements to performance, new useful features, and non-critical bug fixes. Occasionally, they may be required when the upgrade is necessary to continue operating on the network, such as hard forks, or critical bug fixes.Upgrading a non-validating node
Use these instructions to update non-validating nodes, such as your account node or your attestation node on the Baklava testnet. Also use these instructions to upgrade your proxy node, but remember not to stop the proxy of a running validator.Pull the latest Docker image
Stop and remove the existing node
Stop and remove the existing node. Make sure to stop the node gracefully (i.e. giving it time to shut down and complete any writes to disk) or your chain data may become corrupted. Note: Thedocker run
commands in the documentation have been updated to now include --stop-timeout 300
, which should make the -t 300
in docker stop
below redundant. However, it is still recommended to include it just in case.
Upgrading a Validating Node
Upgrading a validating node is much the same, but requires extra care to be taken to prevent validator downtime. One option to complete a validating node upgrade is to perform a key rotation onto a new node. Pull the latest Docker image, as mentioned above, then execute a Validator signing key rotation, using the latest image as the new Validator signing node. A recommended procedure for key rotation is documented in the Key Management guide. A second option is to perform a hot-swap to switch over to a new validator node. The new validator node must be configured with the same set of proxies as the existing validator node.Hotswapping Validator Nodes
Hotswap is being introduced in version 1.2.0. When upgrading nodes that are not yet on 1.2.0 refer to the guide to perform a key rotation.
[start, stop)
.
Note that the replica node must use the same set of proxies as the primary node. If it does not it will not be able to switchover without downtime due to needing to the complete the announce protocol from scratch. Replicas behind the same set of proxies as the primary node will be able to switchover without downtime.
RPC Methods
istanbul.start()
andistanbul.startAtBlock()
start validating immediately or at a blockistanbul.stop()
andistanbul.stopAtBlock()
stop validating immediately or at a blockistanbul.replicaState
will give you the state of the node and the start/stop blocksistanbul.validating
will give you true/false if the node is validating
startAtBlock
and stopAtBlock
must be given a block in the future.Geth Flags
--istanbul.replica
flag which starts a validator in replica mode.
replicastate
folder inside it’s data directory. If that folder exists the node will configure itself as a validator or replica depending on the previous stored state. The stored state will take precedence over the command line flags. If the folder does not exists the node will stored it’s state as configured by the command line. When RPC calls are made to start or stop validating, those changes will be persisted to the replicastate
folder.
If reconfiguring a node to be a replica or reusing a data directory, make sure that the node was previously configured as replica or that the
replicastate
folder is removed. If there is an existing replicastate
folder from a node that was not configured as a replica the node will attempt to start validating.Steps to upgrade
- Pull the latest docker image.
- Start a new validator node on a second host in replica mode (
--istanbul.replica
flag). It should be otherwise configured exactly the same as the existing validator.- It needs to connect to the existing proxies and the validator signing key to connect to other validators in listen mode.
- If reconfiguring a node to be a replica or reusing a data directory, make sure that the node was previously configured as replica or that the
replicastate
folder is removed.
- Once the replica is synced and has validator enode urls for all validators, it is ready to swapped in.
- Check validator enode urls with
istanbul.valEnodeTableInfo
in the geth console. The fieldenode
should be filled in for each validator peer.
- Check validator enode urls with
- In the geth console on the primary run
istanbul.stopAtBlock(xxxx)
- Make sure to select a block number comfortably in the future.
- You can check what the stop block is with
istanbul.replicaState
in the geth console. - You can run
istanbul.start()
to clear the stop block
- In the geth console of the replica run
istanbul.startAtBlock(xxxx)
- You can check what the start block is with
istanbul.replicaState
in the geth console. - You can run
istanbul.stop()
to clear the start block
- You can check what the start block is with
- Confirm that the transition occurred with
istanbul.replicaState
- The last block that the old primary will sign is block number
xxxx - 1
- The first block that the new primary will sign is block number
xxxx
- The last block that the old primary will sign is block number
- Tear down the old primary once the transition has occurred.
Upgrading Proxy Nodes
Release 1.2.0 is backwards incompatible in the Validator and Proxy connection. Validators and proxies must be upgraded to 1.2.0 at the same time.