Upgrading Optimism L1 smart contracts

This guide outlines the definitive process for upgrading Optimism Layer 1 smart contracts using the superchain-ops repository.

The superchain-ops repository

The superchain-ops repository (opens in a new tab) is the central hub for all Optimism network upgrades. It contains:

Execution code for deployments
Artifacts from previous upgrades
Tools for validating and executing new upgrades

The repository structure is explicitly designed to track all significant network changes that require authorization to execute. When planning an upgrade, you must use this repository.

Repository structure requirements

You must organize your upgrade according to these strict requirements:

Top level directory names must follow the EIP-3770 (opens in a new tab) short name for the network (e.g., "mainnet", "sepolia").

Each task directory must contain:

README.md: Describing precisely what the task will execute
Validation.md: Detailing the expected state changes with justifications
A foundry script for post-upgrade assertions:
- Use SignFromJson.s.sol for a Safe owned by EOA signers
- Use NestedSignFromJson.s.sol for a Safe owned by other Safes
input.json: Defining the exact transaction for execution
.env: Containing all environment variables specific to this task

See the repo (opens in a new tab) for more info.

Upgrade process

Follow these steps to upgrade your smart contracts:

Required dependencies

You must install these tools before beginning:

docker - Required for containerized execution
just - Required for running script commands
foundry - Required for contract validation

Step-by-step workflow

Set up your environment: First, clone the repository with the appropriate branch for your upgrade target:
```
git clone --branch [specific-version-branch] --depth 1 [repository-url]
cd [path-to-upgrade-scripts]
```
You must use the specific branch that contains the contract version you're upgrading to.
Configure your environment variables:
```
cp .env.example .env
vim .env
```
Your .env file must include all necessary configuration parameters.
Build the Docker image:
```
just build-image
```
You must allocate at least 16GB of memory to Docker or the compilation will fail. The default 8GB is insufficient.
Run the upgrade task:
```
just run $(realpath path/to/deploy-config.json)
```
Your deploy-config.json must contain the correct configuration values for your target network.

CRITICAL: If your upgrade involves fault proof systems, you must set the correct faultGameAbsolutePrestate value. Use the latest value, not the original deployment value.

Resources

For detailed installation instructions, see the superchain-ops README (opens in a new tab).