🎉 We are deprecating the Optimism SDK and migrating all tutorials to use viem/op-stack. Read more →
OP Stack
Smart contracts
Upgrading Smart Contracts from v1.6.0 to v1.8.0

Upgrading Optimism L1 smart contracts from v1.6.0 to v1.8.0

This guide provides specific instructions for upgrading Optimism's Layer 1 contracts from op-contracts/v1.6.0 to op-contracts/v1.8.0. This upgrade includes important changes to the system configuration and fault proof system.

Overview of the Holocene upgrade

The Holocene Upgrade supports two primary upgrade paths, each with specific components and considerations:

  1. Upgrading from v1.6.0 to v1.8.0:

    • Always upgrades the SystemConfig contract with improvements
    • Provides flexible options for fault proof implementation:
      • Permissionless fault proofs enabled (including FaultDisputeGame)
      • Permissioned fault proofs enabled (excluding FaultDisputeGame)

  2. Upgrading from v1.3.0 to v1.8.0:

    • Retains the existing L2OutputOracle for backward compatibility
    • Only upgrades the SystemConfig contract to v1.8.0 functionality

Required dependencies

Before starting the upgrade process, ensure you have the following tools installed in your environment:

For the complete set of dependencies and detailed installation instructions, refer to the superchain-ops README (opens in a new tab).

Step-by-step upgrade process

1. Clone the repository

git clone --branch proposal/op-contracts/v1.8.0 --depth 1 git@github.com:ethereum-optimism/monorepo.git
cd monorepo/packages/contracts-bedrock/scripts/upgrades/holocene

2. Configure environment

cp .env.example .env
# Edit .env with your specific configuration requirements
vim .env

3. Build Docker image

just build-image

Note: Ensure Docker has at least 16GB of memory allocated (the default is 8GB), or the Solidity compilations may fail due to memory constraints.

4. Execute upgrade

just run $(realpath path/to/deploy-config.json)

This command performs several critical functions:

  • Deploys the new smart contract implementations required for the upgrade
  • Optionally generates a safe upgrade bundle for multisig execution
  • Optionally generates a superchain-ops upgrade task for coordination

To specify a custom output folder path instead of the default output/ directory:

just run $(realpath path/to/deploy-config.json) $(realpath path/to/output)

Configuration requirements

Fault game prestate value

The deploy-config.json that you use for your chain must set the latest faultGameAbsolutePrestate value, not the original value that was set during initial deployment of the chain.

You can use the following recommended value, which is based on op-program/v1.4.0-rc.3 and includes Holocene activations for various networks:

0x03f89406817db1ed7fd8b31e13300444652cdb0b9c509a674de43483b2f83568

This prestate includes Holocene activations for the following networks:

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

Script modifications

If you need to make local modifications to the scripts in the scripts/ directory to accommodate your specific network requirements, you must rebuild the Docker image with just build-image before running just run again.

Additional Resources