Testnet Canyon + protocol-version upgrade guide

[sbvegan]

Testnet Canyon + Multi-chain upgrade guide

Hey y’all! The latest rollup node software includes two important changes. (1) The Canyon testnet hard fork is scheduled for November 14th at 17:00:00 UTC 2023. This means OP Testnet nodes will need the following required updates outlined in the attached document. (2) These releases also lay the foundation for future iterations of the Superchain. We suggest doing this by November 7th 2023. Please reach out if you have any questions.

About the multi-chain node upgrade

These releases enshrine a protocol-version within nodes as a constant in the software, with requirements and recommendations signaled through the L1 ProtocolVersions contract. Nodes periodically read the value from L1 and compare it against the locally hardcoded constant. This release also introduces a "Superchain target" (within the superchain-registry, a library the op-node uses) which groups chains together.

Each chain operator is still in charge of upgrading their own sequencer nodes, but their nodes will now be aware of upgrades, and can be configured to halt or produce warnings when an upgrade is near and the node is behind the protocol-version. Because this behavior is optional, this is not a consensus-critical change for this release. However, we anticipate future releases to utilize this functionality more explicitly, and upgrade the Superchain in unison.

rollup.json and genesis.json are deprecated for chains that follow a Superchain target, and will be imported into the op-node from the superchain-registry instead.

Instructions on how to upgrade

This is the upgrade guide to the Canyon hard fork and synced multi-chain upgrades.

Releases

• Upgrade your op-node to version: v1.3.0. Available as this GitHub release.
• Upgrade you op-geth to version v1.101304.0. Available as this GitHub release.

Feel free to upgrade verifier nodes first, before sequencer nodes, to test out this change.

Recommended configuration

Note: this configuration path uses the multi-chain functionalities described above. You can set these configurations on both testnets and mainnet now (and not enable Canyon until we coordinate the upgrade).

1. Setting the network flags:

   • On op-geth specify --op-network with a pre-configured OP Stack network.
   • On op-node specify --network with a pre-configured OP Stack network.

   The following are the supported options:

   options: base-goerli, base-mainnet, base-sepolia, op-goerli, op-labs-chaosnet-0-goerli-dev-0, op-labs-devnet-0-goerli-dev-0, op-mainnet, op-sepolia, pgn-mainnet, pgn-sepolia, zora-goerli, zora-mainnet
   

2. Loading and reporting protocol versions from the Superchain:

   • On op-node set --rollup.load-protocol-versions to true.

Example node configuration values

For OP-Sepolia.

Note: can also be configured with ENV vars, on both op-node and op-geth!

op-node

--network=op-sepolia
--rollup.halt=minor     # optional for opting in to halting on incompatible breaking changes
--rollup.load-protocol-versions=true

new `op-node` config options

```
--network value                                                        ($OP_NODE_NETWOR
K)
          Predefined network selection. See above for available networks

--rollup.halt value                                                    ($OP_NODE_ROLLUP_HALT)
          Opt-in option to halt on incompatible protocol version requirements of the given
          level (major/minor/patch/none), as signaled onchain in L1
   
--rollup.load-protocol-versions     (default: false; suggested: true)  ($OP_NODE_ROLLUP_LOAD_PROTOCOL_VERSIONS)
          Load protocol versions from the Superchain L1 ProtocolVersions contract (if
          available), and report in logs and metrics
```

op-geth

--op-network=op-sepolia
--rollup.halt=minor    # optional for opting in to halting on incompatible breaking changes

new `op-geth` config options

---rollup.halt value                                                    ($GETH_ROLLUP_HALT)
          Opt-in option to halt on incompatible protocol version requirements of the given
          level (major/minor/patch/none), as signaled through the Engine API by the rollup
          node

--op-network value                                                ($GETH_OP_NETWORK)
          Pick an OP Stack network configuration
   
--rollup.superchain-upgrades   (default: false)                   ($GETH_ROLLUP_SUPERCHAIN_UPGRADES)
          Apply superchain-registry config changes to the local chain-configuration; optional
          if op-network is **specified**

Manual configuration

Not recommended, but supported. Only do this on Goerli & Sepolia and NOT MAINNET.

Using an existing datadir / geth init and rollup.json configuration.

1. On op-geth use the flag --override.canyon.
2. On op-node either add canyon_time to the rollup.json or use the --override.canyon flag at timestamp 1699981200
3. Please note: We strongly suggest using the --network flag. We recommend against long term us of the override.canyon flag because the node does not persist the canyon timestamp. If the flag is removed, without activating canyon another way, the node will diverge.

Verifying your configuration on Goerli & Sepolia

You can verify your node is configured correctly with the following:

• Both op-node and op-geth log their configuration at startup
• Check that Canyon time is set to 1699981200 in the op-node logs
• Check that Canyon time and Shanghai time are set to 1699981200 in the op-geth logs

Let us know if you have any questions!

[sbvegan]

OP Labs blog post: https://blog.oplabs.co/canyon-hardfork/

[boastal]

Not sure how to check the last upgrade step

Verifying your configuration on Goerli & Sepolia

Can this be done only after the hardfork?

[sbvegan]

When your node starts up it should output these configurations in the logs. You can check your logs and make sure the Canyon and Shanghai timestamps are in there.

[GrapeBaBa]

@sbvegan hi, we have a Java rollup client https://github.com/optimism-java/hildr which support bedrock, now we consider upgrade to support Canyon. Are there a issue/PR list for tracking major changes about op-node(rollup node spec) which we can easily check? That's helpful for us to update our rollup client.

[sbvegan]

Yup! You can check out this issue with the sub-issues the client engineers tracked for the canyon upgrade: ethereum-optimism/optimism#7452