ethereum-optimism / superchain-ops

> **⚠️ Important Notice: System Upgrade (August 2025)** > > The Superchain-ops system has undergone a significant upgrade. For access to historical executed tasks and previous system documentation, please refer to this tag for the archived tasks repository. > > • Need help? Create an issue on this repo. Superchain-ops Task System A tooling system for developers to write, test, and simulate onchain state changes safely before execution. > 📚 More detailed documentation can be found in the docs directory. Repository Structure The repository is organized as follows: Quick Start > ⚠️ **IMPORTANT**: **Do not** update to a newer version unless you're told to do so by the maintainers of this repository. We pin to specific allowed versions of to reduce the likelihood of installing a vulnerable version of . You **must** use the script to install . • Install dependencies: Run the commands below to set up your environment. is a **one-time setup** that ensures all signers and developers use the same dependency versions. > For more information on , please refer to the CONTRIBUTING.md guide. • Run tests: • Create a new task: Follow the interactive prompts from the command to create a new task. This will create a new directory in the directory with the task name you provided. Please make sure to complete all the TODOs in the created files before submitting your task for review. > Note: An file will be created in the new tasks directory. Please make sure to fill out the variable with a high enough value to simulate the task. • Configure the task in e.g. The TOML array is optional. It can be used to specify the addresses that we want to overwrite. You can see an example of its use in this task. It's used when the user is adding an address to the table that is already defined in the file. The TOML table is optional. It can be used to specify the addresses of the contracts involved in an upgrade. You can see an example of its use in this task. The TOML table is optional, but in most cases we use it to specify the nonces of the multisig safes involved in an upgrade. Selecting the correct nonce is important and requires careful consideration. You can see an example of its use in this task. If you're unsure about the format of the and fields, you must default to using 66-character hex strings (i.e. followed by 64 hex characters). For example, setting the nonce for a Safe to would look like: However, in some cases it's possible to use the decimal value directly: But **do not** pass the decimal value as a string—this will cause undefined behavior: • Simulate the task: **For individual task simulation** (from the task directory): **Examples:** • **Single Safe Operations** (most common - see SINGLE.md): • **Nested Safe Operations** (see NESTED.md): • **Deeply Nested Safes** (child safe owned by another child safe): > ℹ️ [child-safe-name-depth-1] or [child-safe-name-depth-2] refers to a safe name defined manually by the task developer under the table in the tasks config.toml file or under a given network (e.g. ) in file. > Example: NestedSafe1 in sep/001-opcm-upgrade-v200/config.toml. **For stacked simulation** (recommended - simulates dependencies): • Create a Tenderly account. Once a user simulates a task, we print a Tenderly link. This allows us to compare our local simulation with Tenderly's simulation state changes. If you don’t already have a Tenderly account, go to https://dashboard.tenderly.co/login and sign up. The free account is sufficient. • Fill out the and files. • If your task status is not or , it is considered non-terminal and will automatically be included in stacked simulations. • If your task has a file, you **must** fill out the section. This is so that we can detect if the domain and message hashes change unexpectedly. Any mismatches will cause the task to revert. FAQ How do I simulate a task that depends on another task? > Note: > Tasks get executed in the order they are defined in the directory. We use 3 digit prefixes to order the tasks e.g. is executed before , etc. Stacked simulations are supported. To use this feature, you can use the following command: e.g. > **Note**: For nested architectures, specify child safes in ownership order: depth-1 safe (owned by root) then depth-2 safe (owned by depth-1). Another useful command is to list the tasks that will be simulated in a stacked simulation: e.g. How do I sign a task that depends on another task? To sign a task, you can use the command in . This command will simulate all tasks up to and including the specified task, and then prompt you to sign the transaction for the final task in the stack using your signing device. **Environment variables:** • - Hardware wallet derivation path index (default: 0). The value is inserted into the BIP44 Ethereum path as (e.g. -> , -> ). Use this to select the desired Ethereum account on your hardware wallet. • - If set, uses keystore instead of ledger. By default, keys are stored under . **Examples:** To sign the task on the Ethereum mainnet as the safe: To use a custom HD path: To use keystore instead of ledger: The command will then: • List all the tasks that will be simulated in the stack. • Simulate the tasks in order. • Prompt you to approve the transaction on your Ledger device for the final task ( in this example). How do I perform a contract upgrade directly on an L2? You can execute an upgrade directly on an L2 (e.g. ). detects that the task is upgrading directly via an L2. It does this by looking at the RPC url, which is decided by the directory that the task is contained within (i.e. ). • Create your task in the correct directory for your L2 (e.g. ). • Set to the chain you're targetting. • Set in . • In (keyed by chainId), include every identifier your template uses (e.g., , , ). : : Example: see . How do I add a private key to my keystore? Use Foundry's keystore. Import your key and set a password when prompted: By default, keys are stored under . Li…