🎉 We are deprecating the Optimism SDK and migrating all tutorials to use viem/op-stack. Read more →
Builders
Notices (README)
Preparing for Pectra breaking changes

Preparing for Pectra breaking changes

This page outlines breaking changes related to the Ethereum Pectra (Prague-Electra) hard fork for chain operators and node operators on OP Stack chains. If you experience difficulty at any stage of this process, please reach out to developer support (opens in a new tab).

This page will be updated continuously with information on upgrade runbooks and timelines as they come. Here's the tentative L1 Pectra hard fork times per the ACDC that happened on Feb 6th:

L1 Client testnet releases out by Feb 13 (ACDE):

  • Holesky slot: 3710976 (Mon, Feb 24 at 21:55:12 UTC)
  • Sepolia slot: 7118848 (Wed, Mar 5 at 07:29:36 UTC)
  • +30 day mainnet slot: 11444224 (Tue, Apr 8 at 23:25:11 UTC)

What's included in Pectra?

Pectra contains a variety of EIPs, some of which apply to the OP Stack; others do not. The following EIPs are included in Pectra as outlined in the Pectra Devnet 5 notes (opens in a new tab):

For chain operators

The OP Stack is dividing the Pectra upgrade into two parts:

  1. Make the necessary upgrades to make sure OP Stack chains do not break when the L1 Pectra upgrade activates. We will release new versions of the OP Stack to ensure that OP Stack chains remain functional after the L1 Pectra upgrade. If you're are running a fault proof enabled chain, you will need to follow additional steps outlined below.
  2. Upgrade OP Stack chains to support Pectra's new features that apply to L2s. We will implement all the features of Pectra that apply to L2s and will release a new version of the OP Stack that includes these features. We will provide more information as engineering work wraps up. We are tracking the spec work in thisissue (opens in a new tab).

These following steps are necessary for every chain operator:

Update to the latest releases

The software is currently being tested and we expect the releases to be cut by the end of this week (Feb 3rd to 7th). These release candidates (opens in a new tab) are currently baking on devnet.

  • op-node at vTBD
  • op-geth at vTBD
  • op-batcher at vTBD

Verify Your Configuration

Make the following checks to verify that your node is properly configured.

  • op-node and op-geth will log their configurations at startup
  • Check that the Pectra time is set to activation-timestamp in the op-node startup logs
  • Check that the Pectra time is set to activation-timestamp in the op-geth startup logs

For fault proof enabled chains

The following instructions assume your chain is on the latest contract release op-contracts/v1.8.0 and have Holocene activated.

The following steps are to update your absolute prestate on your chain. This is absolutely necessary for chains running permissionless fault proofs. For chains running the Fault Proof System with permissioned games you can skip this section because games will not be played out and the absolute prestate is not used.

The Pectra upgrade changes the derivation rules, permissionless fault proof chains need to upgrade the op-program version used in the fault proof system to support these changes. The op-program version used is specified via the faultGameAbsolutePrestate setting, deployed as part of FaultDisputeGame and PermissionedDisputeGame contracts.

Make sure the Superchain Registry is up to date

The new op-program release will pull the configurations from the superchain-registry (opens in a new tab). This is important because the op-challenger uses the op-program and it needs to be aware of your chain's configuration. If your chain that not in the superchain-registry, please open a PR to add your chain to the superchain-registry (opens in a new tab).

Verify the new absolute prestate

The following is based on the op-program/v1.5.0-rc.1 (opens in a new tab) which is wrapping up testing and the official release will be out soon.

You can use this new absolute prestate (0x03dfa3b3ac66e8fae9f338824237ebacff616df928cf7dada0e14be2531bc1f4) for the following chains:

  • Sepolia: Base, OP, Metal, Mode, Zora, Ethernity, Unichain, Ink
  • Mainnet: Base, OP, Orderly, Lyra, Metal, Mode, Zora, Lisk, Ethernity, Binary, Ink

You can verify this absolute prestate by running the following command (opens in a new tab) in the root of the monorepo:

make reproducible-prestate

You should expect the following output at the end of the command:

Cannon Absolute prestate hash: 
0x03dfa3b3ac66e8fae9f338824237ebacff616df928cf7dada0e14be2531bc1f4
Cannon64 Absolute prestate hash: 
0x03f83792f653160f3274b0888e998077a27e1f74cb35bcb20d86021e769340aa
CannonInterop Absolute prestate hash: 
0x03b7658b889796c1e372f57439e48eb46a5b008f6e6a4b7e5c8c2d3bddffa797

Deploy new dispute game contracts

You will then take the absolute prestate and deploy new FaultDisputeGame and PermissionedDisputeGame contracts with that value. You can reuse the Holocene script (opens in a new tab) to deploy the new contracts. The only change you will need to make is to update the absolutePrestate value in your deploy-config (opens in a new tab). Alternatively we will be releasing an OPPrestateUpdater that can be used to deploy the new contracts.

Update the DisputeGameFactory

You will then need to update the DisputeGameFactory to point to the new FaultDisputeGame and PermissionedDisputeGame contracts by calling DisputeGameFactory.setImplementation. You can utilize this template (opens in a new tab) to generate the transaction and validation script for this step. Before executing, you will need to update your op-challenger.

Update your op-challenger

Update your op-challenger to the new release version that will be provided soon and configure it to use the new absolute prestate.

Execute the upgrade

Once your challenger is ready, you can execute the "Set Dispute Game Implementation" transaction. Please simulate and validate that the expected output prior to executing the transaction.

For OP Stack forks

We are working on a PR that will include the ability to sync L1 after the Pectra upgrade. The commits from the PR will need to be applied to your chain before Pectra goes live on L1. We will provide a link to the PR after it is complete.

For node operators

Node operators will need to upgrade to the respective releases before the activation dates.

These following steps are necessary for every node operator:

Update to the latest release

The software is currently being tested and we expect the releases to be cut by the end of this week (Feb 3rd to 7th). These release candidates (opens in a new tab) are currently baking on devnet.

  • op-node at vTBD
  • op-geth at vTBD

Verify Your Configuration

Make the following checks to verify that your node is properly configured.

  • op-node and op-geth will log their configurations at startup
  • Check that the Pectra time is set to activation-timestamp in the op-node startup logs
  • Check that the Pectra time is set to activation-timestamp in the op-geth startup logs