Overview

Celo-blockchain v1.3.0-stable is the first mainnet release of the v1.3.x release branch. It includes considerable changes and improvements relative to v1.2.x.

Most importantly, it sets the activation block numbers for the Churrito and Donut hard forks on mainnet and Alfajores. As a consequence, all mainnet and Alfajores node operators must upgrade their nodes prior to the hard forks' activation. Unupgraded nodes will be unable to stay synced to the network after hard fork activation. Churrito and Donut are scheduled to activate together as follows:

• Alfajores: block number 4960000 (est. May 4th, 2021)
• Mainnet: block number 6774000 (est. May 19th, 2021)

See below for upgrade instructions. Additionally, if you use the JSON RPC API, see below regarding some small breaking changes in the behavior of eth_call.

Release highlights:

The biggest and most important change in v1.3.0 is the implementation and activation of the Donut hard fork, which includes the following CIPs:

• CIP 25: Ed25519 Precompile
• CIP 31: BLS Curve Operations on 12-381
• CIP 30: BLS Curve Operations on 12-377
• CIP 20: Extensible Hash Function Precompile
• CIP 21: Governable Lookback Window
• CIP 22: Epoch Snark Data
• CIP 26: Precompile for BLS
• CIP 28: Split etherbase
• CIP 35: Support for Ethereum-compatible transactions

In addition to the Churrito and Donut hard fork, the main changes are: merges from upstream (go-ethereum), optimizations to block creation, support for signing typed data (CIP-8), an exciting new tool called mycelo, and the renaming of celo-blockchain's Go module from github.com/ethereum/go-ethereum to github.com/celo-org/celo-blockchain. See below for more details.

Docker images:

• geth: us.gcr.io/celo-org/geth:1.3.0
• geth-all: us.gcr.io/celo-org/geth-all:1.3.0

Upgrading notes

These notes assume you are upgrading from v1.2.x. If you are upgrading from versions v1.1.x or v1.0.x, please also check the release notes from v1.1.x and v1.2.x as appropriate to your case.

1. Review the breaking changes listed below in the "Break Changes" section, and update your node configuration and related applications as appropriate. In particular, even users who do not run their own node but rather use 3rd party nodes via the JSON RPC API should check the breaking changes section below for the changes affecting the behavior of eth_call in some special cases.
2. Client flag deprecations:
   • The following flags had no effect (the corresponding values were instead being taken from the genesis config) and so are being deprecated (see #1288 and #1136). If you have been using them, you should remove them:
     • --istanbul.requesttimeout
     • --istanbul.blockperiod
     • --istanbul.proposerpolicy
     • --istanbul.lookbackwindow
3. If you were using the --txpool.globalslots flag to limit the size of the transaction pool, you may safely remove that flag. This flag was necessary due to inefficiencies in the transaction pool and in block production which have been fixed in v1.3.0-stable (see below for more details)
4. If you want to make use of CIP-28 (split etherbase), you can do so, after Donut has been activated, by using --miner.validator and --tx-fee-recipient instead of --etherbase. It is possible to use the new flags before Donut is activated, but this would not have the desired effect since that depends on CIP-28 being active already. Setting the two flags to different addresses before Donut activation will lead to warnings being logged to inform you that they are not yet having the intended effect and so is not recommended.
5. Confirming that your node is set to activate Churrito and Donut. In the case of testnets such as Alfajores and Baklava, hard fork activation depends on using the corresponding flags (--alfajores or --baklava). Therefore, if you are running a node on Alfajores or Baklava, be sure to specify the corresponding flag if you aren't already. In the case of mainnet, no flag is needed, and hard fork activation will be set without any action needed besides upgrading. If you wish to verify that it has been set, there are two ways:
   1. When the node starts up, it logs the activation blocks numbers for all hard forks. For example, a mainnet node running v1.3.0 will show the following, indicating the block number at which Churrito and Donut will activate:

      INFO [04-14|14:59:24.238] Initialised chain configuration          config="{ChainID: 42220 Homestead: 0 DAO: <nil> DAOSupport: true EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0 Constantinople: 0 Petersburg: 0 Istanbul: 0 Churrito: 6774000, Donut: 6774000, Engine: istanbul}"
      

   2. While the node is running, you can see the node's hard fork activation configuration among the results of the admin_nodeInfo RPC API method, under protocols > istanbul > config. If running the admin API, you can access this either via an RPC request or from the geth attach console using admin.nodeInfo (or admin.nodeInfo.protocols.istanbul.config to get just the relevant parts). The results will indicate the block numbers at which Churrito and Donut are set to activate, e.g.

      > admin.nodeInfo.protocols.istanbul.config
      {
        FullHeaderChainAvailable: true,
        byzantiumBlock: 0,
        chainId: 42220,
        churritoBlock: 6774000,
        constantinopleBlock: 0,
        daoForkSupport: true,
        donutBlock: 6774000,
        eip150Block: 0,
        eip150Hash: "0x0000000000000000000000000000000000000000000000000000000000000000",
        eip155Block: 0,
        eip158Block: 0,
        homesteadBlock: 0,
        istanbul: {
          blockperiod: 5,
          epoch: 17280,
          lookbackwindow: 12,
          policy: 2,
          requesttimeout: 3000
        },
        istanbulBlock: 0,
        petersburgBlock: 0
      }
      

Breaking changes (relative to v1.2.x)

Besides the backwards incompatibility inherent in a hard fork (that unupgraded clients will not function properly after the hard fork is activated), there are some breaking changes in this release:

• The default value for --light.serve has been changed to zero, so that serving light clients is now opt-in rather than opt-out. As a result, if you wish your node to serve light clients, you must use the --light.serve flag with a nonzero value. Note that the documentation on running a full node already included this flag, so if you were following the instructions there you don't need to change anything. On the other hand, if you do not wish to serve light clients and have been using --light.serve 0, you will no longer need to include that flag (but you need not remove it, either).
• RPC calls to eth_call which don't specify a from address will now default the from field to the zero address. Previously, they defaulted to the node's first account if there was one (and the zero address otherwise). This change was adopted as part of merging changes from upstream. What this means is that, if you were making calls whose result depends on the from address, you must specify the from address yourself. See #1251 and ethereum/go-ethereum#20685 for more context.
• RPC calls to eth_call which specify a non-zero gas price will fail if the from account does not have sufficient funds to pay the transaction fee. This was already the case if you were specifying a non-Celo fee currency, but constitutes a breaking change if the fee currency was set to null (meaning Celo). The reason is that, prior to this change, there was a hack in place (inherited from upstream) which modified the account's balance (in the ephemeral EVM instance, not on-chain) before processing the call, to ensure it wouldn't fail due to not being able to pay for fees. This hack led to incorrect results in calls which depend on the account's balance. This has been changed upstream and the change included in celo-blockchain as part of merging. See #1251 and ethereum/go-ethereum#20783 for more context. As a user of eth_call, we recommend you omit the gas price (which would then default to zero), or specify a gas price of zero. If you wish to simulate what would happen with a certain non-zero gas price, you may specify it, but be aware that this will lead to the call failing if the account does not have sufficient funds to pay the fees.
• Validators running behind a proxy, if wishing to use Celostats, must include the --celostats flag on the validator as well on the proxy. This is as described in the docs. However, prior to v1.3.0, the actual behavior differed from that described in the docs, with it being sufficient to have the flag on the proxy. In v1.3.0, this has been fixed so that the actual behavior agrees with the documentation and how one would it expect to be. See #1508.
• celo-blockchain's Go module has been renamed from github.com/ethereum/go-ethereum (inherited from upstream) to github.com/celo-org/celo-blockchain (#1375). If you are using importing celo-blockchain packages into your own project, you will need to update the package names accordingly.

If you're upgrading from versions 1.1.x or 1.0.x, please review the release notes from the relevant prior releases as well.

Other notable changes

• Optimizations to block production:
  • Prior to v1.2.5, inefficiencies in the transaction pool meant that validators were not able to produce blocks in a timely manner in the presence of a transaction pool with a large number of transactions.
  • v1.2.5 included a fix for a key inefficiency behind this (see #1467).
  • v1.3.0 adds to this a couple of optimizations to the block creation process: (a) avoiding unnecessary contract calls (proportional to the number of transactions in the pool) which were being done when the block was close to being full (#1490), and (b) removing a redundant gas price minimum check per transaction to be included (#1500).
  • Put together, these changes mean that (a) validators can now handle full transaction pools without degraded performance, and (b) block construction takes less time, which could be used in the future to safely increase the block gas limit further.
• New RPC methods:
  • eth_validator and eth_txFeeRecipient, which respectively return the addresses being used for receiving validator rewards and transaction fees (#1195, and see CIP 28: Split etherbase).
  • istanbul.getLookbackWindow which returns the size of the lookback window in effect at the specified block number (#1432, and see CIP 21: Governable Lookback Window).
• mycelo
  • mycelo is a new tool, included in celo-blockchain, which can be used to easily create and run local testnets, or to generate a genesis file for a testnet that will be run elsewhere.
  • Its most exciting feature is its ability to include the Celo core contracts already deployed in the genesis state, so that you don't need to deploy and initialize them after the testnet is running, which takes considerably longer.
  • It has already proven to be very useful during celo-blockchain development and testing, and continues to be iterated on.
  • Read about mycelo and how to use it in its readme.
• Merged upstream (go-ethereum) changes corresponding to versions v1.9.11 (#1209), v1.9.12 (#1239), v1.9.13 (#1251), and part of v1.9.14 (#1336)
  • Includes two of the breaking changes mentioned above.
  • Includes an implementation of EIP-2464, which makes propagation of transactions across the network more efficient.
  • Implements DNS-based discovery, which could be used as a complement to UDP-based discovery. Though we are not using this in Celo, it is there and could be used in the future.
  • The beginning of go-ethereum's implementation of snapshots.
  • Support for running the HTTP and WS RPC services using the same port.
  • Support for Solidity v0.6.0 in account/bind.
  • More informative errors from eth_call and eth_estimateGas: if the transaction reverts, you will get the revert reason instead of the notorious gas required exceeds allowance (13000000) or always failing transaction error. See #1425 for the eth_call change.
• Support for CIP-8 on mobile devices (#1219, #1220, #1221).
• Celostats improvements (#1487, #1508):
  • Improved reliability (maintaining the connection to Celostats).
  • Celostats can now show information about validators behind proxies, rather than just the proxies.
  • Fix for a bug when using both an active and a replica validator.
• Fix for a race condition bug that would sometimes lead to an Inconsistent subjects between PREPARE and proposal error (#1470).
• Fix an upstream bug in the ethereum peer handler, which was causing the infamous "useless peer" error messages to appear instead of the actual error that led to disconnecting from the peer (#1283).
• Fix a couple of bugs in the discovery table which could lead a new node's table becoming empty shortly after startup, rendering the node unable to find peers (#1194).
• celo-blockchain now uses Go version 1.16.2.