L1→L2 Migration Changes

Table of Contents

The switch from the Celo L1 blockchain to the Celo L2 introduces a variety of changes, most of which are not visible to the majority of developers and even less to the end users. However, tool developers, infrastructure operators and some developers will have to take a few of these changes into account. This page contains all information to check if this is the case for you or not.

Changes for Contracts Developers

  • Removed precompiles (all except the transfer precompile)
  • During the migration the following hardforks are enabled:
  • The following Optimism specific hardforks are enabled:
    • Canyon
    • Delta
    • Ecotone
    • Fjord
      • Notably, this hardfork also enables the P256VERIFY precompile, which performs signature verification for the secp256r1 elliptic curve. This curve has widespread adoption. It's used by Passkeys, Apple Secure Enclave and many other systems.
    • Granite

Precompile Deprecation and Epoch Management

As part of Celo's transition to a L2 network, the following Celo precompiles, except the Transfer precompile, will be deprecated.

  • FRACTION_MUL
  • PROOF_OF_POSSESSION
  • GET_VALIDATOR
  • NUMBER_VALIDATORS
  • EPOCH_SIZE
  • BLOCK_NUMBER_FROM_HEADER
  • HASH_HEADER
  • GET_PARENT_SEAL_BITMAP
  • GET_VERIFIED_SEAL_BITMAP

This means that the geth client is no longer responsible for processing epochs. Instead, processing of epochs, rewards distribution and storage of currently elected validators is now handled by the EpochManager contract.

Any contract supporting the use of precompiles will now revert on Celo as a L2. This includes the UsingPrecompiles contract. More details here

To keep costs of processing epochs low, only the following key functions (used for querying the current epoch or elected validators) have been ported over to the [EpochManager] contract.

  • getEpochNumberOfBlock(uint256)
  • getEpochNumber()
  • validatorSignerAddressFromCurrentSet()
  • numberValidatorsInCurrentSet()

Read more on new epoch management and reward distribution or deprecated precompiles.

FeeCurrencyDirectory

We introduced a new contract, FeeCurrencyDirectory, which is responsible for managing the fee currencies used in the Celo network. This contract is replacement for FeeCurrencyWhitelist and keeps track of ERC-20 tokens that can be used as gas currencies on Celo network with additional setup of intrinsic gas cost of transactions for these fee currencies.

FeeCurrencyWhitelist

The FeeCurrencyWhitelist contract has been replaced by the FeeCurrencyDirectory contract.

Deactivated Random Contract

The Random core contract has been deactivated. The EIP-4399 PREVRANDAO opcode provide some pseudo-randomness now. Please be aware of the limitations mentioned in the EIP, as well as the following OP Stack specific limitations:

  • The randao value is read from the L1, it is known a longer time in advance.
  • Since multiple L2 blocks are derived from the same L1 block, the PREVRANDAO value will not change with every L2 block, but only with the L1 block.

Deactivated BlockchainParameters Contract

The BlockchainParameters core contract has been deactivated.

The blockGasLimit can now be found by querying the Optimism L1 SystemConfig contract deployed at 0x43cb8878b4B62D9853452140eFB42CF30672e23a and calling the gasLimit() getter.

The intrinsicGasForAlternativeFeeCurrency can now be found by querying the FeeCurrencyDirectory contract function getCurrencyConfig(token).intrinsicGas.

Updated Governance Hotfix

The Governance Hotfix process has undergone several changes due to the absence of validators on L2, now using a multisig approach. Here’s a detailed explanation of these changes:

Original Hotfix Process

Previously, the hotfix process relied heavily on a set of validators:

  1. Validator Approval: A byzantine quorum of validators was needed to whitelist a hotfix. Validators had financial incentives to act in the network's best interest, ensuring that any approved hotfix had been vetted by a trustworthy group.
  2. Dynamic Validator Set: The list of validators who approved the hotfix changed with each epoch. This dynamic nature made it difficult for validators to collude and approve a malicious hotfix.
  3. Epoch-Dependent: If a hotfix was not executed within the same epoch it was approved, it needed to be reapproved by the new set of validators in the next epoch.
  4. Prepare Step: The hotfix required a "prepare" step, ensuring that the current set of validators had approved the hotfix before it could be executed.

Updated Hotfix Process

Due to the absence of validators on L2, the process now incorporates a multisig approach:

  1. Multisig Approval: The new process requires the approval of an approver multisig, but now also includes the Security Council multisig.
  2. Fixed Signers: Unlike the previous dynamic set of validators, the list of Security Council signers remains fixed. This change simplifies the approval process but also increases the risk of collusion among the fixed set of signers.
  3. Execution Time Limit: If a hotfix is not executed within the specified executionTimeLimit, it must be reset and re-approved. This keeps the time constraint but no longer depends on epoch changes.
  4. Collusion Risk: The fixed list of Security Council signers introduces a new risk factor. Without clear incentives for the signers to act in the network's best interest, there is a higher risk of collusion and the potential for malicious hotfixes being approved.

Changes for JSON-RPC Users

  • Removed tx types, see also the tx types page:
    • Celo legacy tx
    • CIP-42

State Changes during the Migration

The migration is the process of converting the Celo L1 chain into an L2 based on Ethereum. This migration involves different steps and requires the blockchain to shortly pause block production.

During the migration the following things are done:

  • Historic blockchain data such as blocks, headers and transactions are transformed into a version readable by the updated execution client. During this process some data, such as data required for the Istanbul consensus algorithm, is removed as it is no longer required.
  • OP Stack L2 contracts are deployed.
  • The new Celo unreleased treasury core contract is initialized.

Historical data migration

Celo started as a fork of go-ethereum but initially some significant changes to the structure of headers and blocks were made because it was operating with a Proof of Stake consensus mechanism.

At the outset Celo blocks lacked the following fields that Ethereum blocks had:

  • sha3Uncles
  • uncles
  • difficulty
  • gasLimit (the gasLimit was defined by a contract and so had to be retrieved from state)
  • mixHash
  • nonce

Later in the Espresso hardfork, dynamic fee transactions were introduced. Instead of relying on the baseFeePerGas field on the block header, the baseFeePerGas was also retrieved from state via a contract call similar to gasLimit.

In the Gingerbread hardfork (block 21616000) all the fields listed above plus baseFeePerGas were added to the internal block representation to bring future blocks into alignment with Ethereum. A constant difficulty field of 0x0 was added to all pre-Gingerbread RPC API block responses.

Celo added the following fields to block bodies:

  • randomness
  • epochSnarkData

As additions they do not damage compatibility at the RPC API level as API clients would generally ignore them. However, in the transition to L2 these fields are planned for removal because they will no longer be needed.

In the transition to L2 as an attempt to improve the situation with RPC API compatibility for historical blocks, all post-Gingerbread fields will be returned for all blocks. Both pre-Gingerbread and post-Gingerbread blocks retrieved from the L2 RPC API would look the same with the exception of baseFeePerGas which for now will not be returned for pre-Gingerbread blocks.

L2 Block Structure

Going forward, blocks occurring after the transition point will gain an extra field, parentBeaconBlockRoot, which will bring our block structure fully up to date with Ethereum’s block structure.

As Ethereum evolves in the time before we make the transition to L2 we could end up with additional fields being added to the L2 Block Structure, and this document will be updated accordingly.

State migration

The OP stack requires a number of contracts to be available on the L2. Those contracts have predefined addresses and cannot be deployed like normal contracts. Instead they are written to the state during the migration.

As this process touches the blockchain state, it is important that it is transparent and can be verified by every node operator and user. Therefore, every node operator can do the migration locally and check the resulting state against Celo L2 state.

OP predeploys

The predeploys to be added to the state are supplied in form of an allocation file which contains a mapping of account addresses to their state. In the state migration tool this file is read and every account copied into the Celo L1 state.

There's a number of checks to make sure this doesn't end up causing problems.

  • If an account to be written to the state already has a balance, this balance is added to the copied account balance. This makes sure the total amount of Celo doesn't change.
  • If an account already contains code, it is checked that the code is the same.

CeloUnreleasedTreasury set up

The CeloUnreleasedTreasury is a new contract available on the migrated Celo L2. See the spec for more information.

During the migration it needs to be setup with the remaining unminted Celo.

This is done by first reading the total supply of Celo tokens at the time of the migration. This value is then subtracted from the max supply of Celo tokens, which is 1,000,000,000. This difference is the remaining amount of tokens that gets set as the balance of the distribution schedule contract.

Other Changes

  • No need for validators, since a centralized sequencer is used

CIP-64 Receipts Now Contain the baseFee

For the Celo L1, the effectiveGasPrice for CIP-64 txs is only available until the block state is pruned. Afterwards, the blockchain client is unable to get the baseFee for the relevant feeCurrency, which is required to calculate the effectiveGasPrice. To avoid this and make the effectiveGasPrice available permanently, the baseFee is included as the last field in the RLP-encoded CIP-64 receipt for CIP-64 txs submitted after the L2 migration. The EIP-2718 ReceiptPayload for this transaction type is now rlp([status, cumulativeGasUsed, logsBloom, logs, baseFee]).