superchain-ops
repository. It’s intended primarily for chains that are part of the Superchain, those with the Foundation or Security Council as signers, and/or chains requiring a highly secure process.
For chains that don’t require the enhanced security of superchain-ops or security council signing, you can instead use op-deployer to upgrade your chain.
For non-Optimism governed chains, you can use op-deployer and your own tooling to upgrade your chain.
superchain-ops
is a highly secure service designed for Optimism chains. It provides a structured and security-focused approach to chain upgrades. The process involves creating tasks that use predefined templates to generate the necessary upgrade transactions.
Who should use superchain-ops
superchain-ops
is primarily intended for:
-
Chains in the Superchain: For standard chains officially part of the Superchain, upgrades are typically handled through
superchain-ops
. -
Chains with Foundation or Security Council as signers: If your chain has the Foundation multi-sig or Security Council as signers, your upgrade tasks should go through
superchain-ops
. -
Chains requiring a highly secure process: For chains that prioritize security over automation,
superchain-ops
provides an intentionally manual workflow with thorough verification steps (e.g. EVM state diff inspection).
Understanding templates and tasks
superchain-ops
uses two key concepts:
-
Templates: Define what the upgrade is and contain the code for specific upgrade paths (e.g.,
op-contracts/v1.8.0
toop-contracts/v2.0.0
). Templates are version-specific and live in the /src/improvements/template directory. -
Tasks: Use a template to define a specific upgrade transaction for a chain. Multiple tasks can use the same template. Tasks are organized by network (
eth
orsep
) in the /src/improvements/tasks directory.
General upgrade process
The following process outlines how to upgrade a chain usingsuperchain-ops
, using the op-contracts/v1.8.0
to op-contracts/v2.0.0
upgrade as an example. This same pattern applies to other OPCM-based upgrades (like op-contracts/v2.0.0
to op-contracts/v3.0.0
).
Step 1: Clone the superchain-ops
repository
Step 1a: One-time Install Dependencies Setup
Follow the ‘Install Dependencies’ instructions in the ‘Quick Start’ section of theREADME.md
file.
Step 2: Create a new task using the quick start
OPCMUpgradeV200
for a op-contracts/v1.8.0
to op-contracts/v2.0.0
upgrade) and provide the necessary details.
This will create a new task directory containing a config.toml
and README
file. The config file will look like this:
Step 3: Configure the task
You’ll have to add additional properties to yourconfig.toml
file to fully configure your task. For example, when upgrading from op-contracts/v1.8.0
to op-contracts/v2.0.0
, you can look at a previous task for reference: src/improvements/tasks/eth/002-opcm-upgrade-v200/config.toml:
This is an example task. You must figure out which values you’ll need for your own specific task. Ensure you replace all addresses and other values in the example below.