Warning
This repository is a work in progress. At a later date, it will be proposed to, and must be approved by, Optimism Governance. Until that time, the configuration described here is subject to change.
Important
We're making some changes to this repository and we've paused adding new chains for now. We'll reopen this process once the repository is ready. The Superchain itself, of course, remains open for business.
The Superchain Registry is an index of chains which serves as the source of truth for who’s in the Superchain and what modifications they’ve made to their chains. It hosts Superchain-configuration data in a minimal human-readable form and includes mainnet and testnet Superchain targets, along with their respective member chains.
Other configuration, such as contract-permissions and SystemConfig
parameters are hosted and governed onchain.
A list of chains in the registry can be seen in the top level chainList.toml
and chainList.json
files.
These files are autogenerated from scripts in the registry and will remain stable to build against.
To help with clarity and a common understanding, here are some helpful terms and their definitions.
Superchain member: A chain with an agreement in place to commit sequencer revenue back to the Optimism Collective.
Blockspace charter: A Blockspace Charter is a technical-focused governing document (and framework) for the Superchain.
Standard chain: A chain that conform to the Standard Rollup Charter - not ratified yet
Frontier chain: A non-standard chain which has modifications that do not fit the Standard Rollup Charter
criteria.
Standard chain candidate: A chain that has met most of the standard chain criteria, except for the ProxyAdminOwner
key handover.
Key handover: A colloquial term for updating the chain's ProxyAdminOwner
to fulfill the requirements from the standard rollup charter.
Chains in the superchain-registry are assigned a superchain_level
(shown in individual config files as well as the chainList.toml/json
summaries), depending on the set of validation checks that they pass.
Frontier chains have superchain_level = 1
.
Standard chains have superchain_level = 2
. Because they satisfy a much stricter set of validation checks (see the Standard Rollup Blockspace Charter), they also qualify as Stage 1 rollups chains.
The superchain configs are stored in a minimal form, and are embedded in downstream OP-Stack software (op-node
and op-geth
). This means that, after a chain has been added to the registry, and the dependency on the registry updates in the downstream software, it is possible to start an op-node
instance using the --network
flag (and also an op-geth
instance using the --op-network
tag) which will successfully sync with other nodes on that network.
The following are the steps you need to take to add a chain to the registry:
Important
Ensure your chain is listed at ethereum-lists/chains. This is to ensure your chain has a unique chain ID. Our validation suite will check against this repository. This is a mandatory prerequisite before being added to the registy.
You will be raising a Pull Request from your fork to the upstream repo.
Install the following dependencies
Dependency | Version | Version Check Command |
---|---|---|
git | ^2 |
git --version |
go | ^1.21 |
go version |
foundry | ^0.2.0 |
forge --version |
jq | ^1.6 |
jq --version |
just | ^1.28.0 |
just --version |
Make a copy of .env.example
named .env
, and alter the variables to appropriate values. Each value is explained in a comment in .env.example
.
Important
Adding a standard chain is a two-step process. For your initial PR, ensure
SCR_STANDARD_CHAIN_CANDIDATE=true
in the .env
file. After you've met all
of the Standard chain requirements, you'll open a new PR following the
Promote a chain to standard process.
Run the following script from the root of the repository to open the PR.
just add-chain
The remaining steps should then be followed to merge the config data into the registry -- a prerequisite for promoting the chain to a standard chain.
The tool will write the following data:
- The main configuration source, with genesis data, and address of onchain system configuration. These are written to
uperchain/configs/<superchain-target>/<chain-short-name>.toml
. - Hardfork override times, where they have been set, will be included. If and when a chain becomes a standard chain, a
superchain_time
is set in the chain config. From that time on, future hardfork activation times which are missing from the chain config will be inherited from superchain-wide values in the neighboringsuperchain.toml
file. - Genesis system config data
- Compressed
genesis.json
definitions (in theextra/genesis
directory) which pull in the bytecode by hash
The genesis largely consists of contracts common with other chains:
all contract bytecode is deduplicated and hosted in the extra/bytecodes
directory.
The format is a gzipped JSON genesis.json
file, with either:
- a
alloc
attribute, structured like a standardgenesis.json
, but withcodeHash
(bytes32,keccak256
hash of contract code) attribute per account, instead of thecode
attribute seen in standard Ethereum genesis definitions. - a
stateHash
attribute: to omit a large state (e.g. for networks with a re-genesis or migration history). Nodes can load the genesis block header, and state-sync to complete the node initialization.
Run the following command to run the Go validation checks, for only the chain you added (replace the <chain-id>
accordingly):
just validate <chain-id>
Note
If you set SCR_STANDARD_CHAIN_CANDIDATE
, your chain will be checked against the majority of the standard rollup requirements as outlined by the Standard Rollup Blockspace Charter (currently a draft pending Governance approval).
The final requirement to qualify as a standard chain concerns the ProxyAdminOwner
role. The validation check for this role will not be run until the chain is promoted to standard.
The validation_test.go
test declaration file defines which checks run on each class of chain. The parameters referenced in each check are recorded in TOML files in the standard
directory.
This tool will add your chain to the chainList.toml
and addresses.json
files, which contain summaries of all chains in the registry.
just codegen
Note
Please double check the diff to this file. This data may be consumed by external services, e.g. wallets. If anything looks incorrect, please get in touch.
When opening a PR:
- Open it from a non-protected branch in your fork (e.g. avoid the
main
branch). This allows maintainers to push to your branch if needed, which streamlines the review and merge process. - Open one PR per chain you would like to add. This ensures the merge of one chain is not blocked by unexpected issues.
Once the PR is opened, the same automated checks you've run locally will then run on your PR, and your PR will be reviewed in due course. Once these checks pass, the PR will be merged.
This process is only possible for chains already in the registry.
Run this command (replace the <chain-id>
accordingly):
just promote-to-standard <chain-id>
This command will:
- declare the chain as a standard chain
- set the
superchain_time
, so that the chain receives future hardforks with the rest of the superchain (baked into downstream OPStack software, selected with network flags). - activate the full suite of validation checks for standard chains, including checks on the
ProxyAdminOwner
MIT License, see LICENSE
file.