From c8842fcd7b8b94f2eb5b7475ca6a1eebfecc42e2 Mon Sep 17 00:00:00 2001 From: Bradley Camacho <42678939+bradleycamacho@users.noreply.github.com> Date: Fri, 25 Apr 2025 12:58:28 -0700 Subject: [PATCH 1/7] Full chain upgrades commit --- pages/stack/_meta.json | 1 + pages/stack/chain-upgrades/_meta.json | 3 + .../chain-upgrades/superchain-ops-guide.mdx | 120 ++++++++++++++++++ 3 files changed, 124 insertions(+) create mode 100644 pages/stack/chain-upgrades/_meta.json create mode 100644 pages/stack/chain-upgrades/superchain-ops-guide.mdx diff --git a/pages/stack/_meta.json b/pages/stack/_meta.json index dccbe365d..b7d5294ab 100644 --- a/pages/stack/_meta.json +++ b/pages/stack/_meta.json @@ -10,6 +10,7 @@ "components": "OP Stack components", "public-devnets": "Public devnets", "smart-contracts": "Smart contracts", + "chain-upgrades": "Chain upgrades", "opcm": "OP Contracts Manager", "rollup": "Rollup", "fault-proofs": "Fault proofs", diff --git a/pages/stack/chain-upgrades/_meta.json b/pages/stack/chain-upgrades/_meta.json new file mode 100644 index 000000000..ffff0fbab --- /dev/null +++ b/pages/stack/chain-upgrades/_meta.json @@ -0,0 +1,3 @@ +{ + "superchain-ops-guide": "Upgrade contracts" +} \ No newline at end of file diff --git a/pages/stack/chain-upgrades/superchain-ops-guide.mdx b/pages/stack/chain-upgrades/superchain-ops-guide.mdx new file mode 100644 index 000000000..6f594d246 --- /dev/null +++ b/pages/stack/chain-upgrades/superchain-ops-guide.mdx @@ -0,0 +1,120 @@ +--- +title: 'Chain upgrade guide: Using superchain-ops' +description: Learn about using superchain-ops to upgrade your chain +lang: en-US +content_type: guide +topic: op-chain-upgrades-superchain-ops +personas: + - protocol-developer + - chain-operator +categories: + - protocol + - chain-deployment + - smart-contracts + - infrastructure + - superchain-contracts + - system-configuration + - deployment-tooling +is_imported_content: 'false' +--- + +# Chain upgrade guide: Using superchain-ops + +This guide outlines the process for upgrading Optimism chains using the `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 and manual process. + +`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: + +1. **Chains in the Superchain**: For standard chains officially part of the Superchain, upgrades are typically handled through `superchain-ops`. + +2. **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`. + +3. **Chains requiring a highly secure and manual process**: For chains that prioritize security over automation, `superchain-ops` provides an intentionally manual workflow with thorough verification steps. + +For chains that don't fall into these categories, you'll need to generate appropriate call data for upgrades through other means or develop your own upgrade process for non-OPCM upgrades. + +## 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., 1.8 to 2.0). Templates are version-specific and live in the (`/src/improvements/template`)[https://github.com/ethereum-optimism/superchain-ops/tree/main/src/improvements/template] directory. + +- **Tasks**: Chain-specific implementations of templates. Multiple tasks can use the same template for different chains. Tasks are organized by network (mainnet or testnet) in the (`/src/improvements/tasks`)[https://github.com/ethereum-optimism/superchain-ops/tree/main/src/improvements/tasks] directory. + +## General upgrade process + +The following process outlines how to upgrade a chain using `superchain-ops`, using the 1.8 to 2.0 upgrade as an example. This same pattern applies to other OPCM-based upgrades (like 2.0 to 3.0). + +### Step 1: Clone the `superchain-ops` repository + +```bash +git clone https://github.com/ethereum-optimism/superchain-ops.git +cd superchain-ops +``` + +### Step 2: Create a new task using the quick start + +```bash +cd src/improvements/ +just new task +``` + +Follow the prompts to select the appropriate template (e.g., `opcm-upgrade-v200` for a 1.8 to 2.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: + +``` +l2chains = [] # e.g. [{name = "OP Mainnet", chainId = 10}] +templateName = "OPCMUpgradeV200" + +``` + +### Step 4: Configure the task + +Look through other tasks in the directory to find the information necessary for your upgrade. For example, when upgrading from 1.8 to 2.0, you can look at the (`src/improvements/tasks/eth/002-opcm-upgrade-v200/config.toml`)[https://github.com/ethereum-optimism/superchain-ops/blob/main/src/improvements/tasks/eth/002-opcm-upgrade-v200/config.toml] file to see that your config file should look like the following: + + +Ensure you replace all addresses and other values in the example below + + +``` +l2chains = [ + {name = "Unichain", chainId = 130} +] + +templateName = "OPCMUpgradeV200" + +[opcmUpgrades] +absolutePrestates = [ + {absolutePrestate = "0x039facea52b20c605c05efb0a33560a92de7074218998f75bcdf61e8989cb5d9", chainId = 130}, +] + +[addresses] +OPCM = "0x026b2F158255Beac46c1E7c6b8BbF29A4b6A7B76" +# Deployed March 27, 2025: https://etherscan.io/tx/0x902ce895f70a72110d40c9a734a26380b2e27c370aae90721cdfa1ac972cfff8 +StandardValidatorV200 = "0xecabaeaa1d58261f1579232520c5b460ca58a164" +ChildSafe1 = "0xb0c4C487C5cf6d67807Bc2008c66fa7e2cE744EC" +ChildSafe2 = "0x847B5c174615B1B7fDF770882256e2D3E95b9D92" +ChildSafe3 = "0xc2819DC788505Aac350142A7A707BF9D03E3Bd03" +``` + +### Step 5: Simulate the task + +Before executing the upgrade, simulate it to ensure everything is configured correctly: + +``` +# Nested +SIMULATE_WITHOUT_LEDGER=1 just --dotenv-path $(pwd)/.env --justfile ../../../nested.just simulate +# Single +SIMULATE_WITHOUT_LEDGER=1 just --dotenv-path $(pwd)/.env --justfile ../../../single.just simulate +``` + +This will run through the upgrade process without actually executing the transactions. + +### Step 6: Execute or submit for review + +For chains within the Superchain, submit a pull request to have your task reviewed. If your chain is not within the Superchain, execute the transaction yourself. + From 4602733e99a9b825b133f36dc0d6d30b72616151 Mon Sep 17 00:00:00 2001 From: Bradley Camacho <42678939+bradleycamacho@users.noreply.github.com> Date: Fri, 25 Apr 2025 13:50:37 -0700 Subject: [PATCH 2/7] Test --- pages/stack/_meta.json | 2 +- pages/stack/chain-upgrades/_meta.json | 3 --- pages/stack/{chain-upgrades => }/superchain-ops-guide.mdx | 5 ++++- 3 files changed, 5 insertions(+), 5 deletions(-) delete mode 100644 pages/stack/chain-upgrades/_meta.json rename pages/stack/{chain-upgrades => }/superchain-ops-guide.mdx (98%) diff --git a/pages/stack/_meta.json b/pages/stack/_meta.json index b7d5294ab..4ad73a1e5 100644 --- a/pages/stack/_meta.json +++ b/pages/stack/_meta.json @@ -10,7 +10,7 @@ "components": "OP Stack components", "public-devnets": "Public devnets", "smart-contracts": "Smart contracts", - "chain-upgrades": "Chain upgrades", + "superchain-ops-guide": "Superchain-ops upgrades", "opcm": "OP Contracts Manager", "rollup": "Rollup", "fault-proofs": "Fault proofs", diff --git a/pages/stack/chain-upgrades/_meta.json b/pages/stack/chain-upgrades/_meta.json deleted file mode 100644 index ffff0fbab..000000000 --- a/pages/stack/chain-upgrades/_meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "superchain-ops-guide": "Upgrade contracts" -} \ No newline at end of file diff --git a/pages/stack/chain-upgrades/superchain-ops-guide.mdx b/pages/stack/superchain-ops-guide.mdx similarity index 98% rename from pages/stack/chain-upgrades/superchain-ops-guide.mdx rename to pages/stack/superchain-ops-guide.mdx index 6f594d246..ba81210b2 100644 --- a/pages/stack/chain-upgrades/superchain-ops-guide.mdx +++ b/pages/stack/superchain-ops-guide.mdx @@ -1,5 +1,5 @@ --- -title: 'Chain upgrade guide: Using superchain-ops' +title: Chain upgrade guide Using superchain-ops description: Learn about using superchain-ops to upgrade your chain lang: en-US content_type: guide @@ -18,6 +18,9 @@ categories: is_imported_content: 'false' --- +import { Callout } from 'nextra/components' + + # Chain upgrade guide: Using superchain-ops This guide outlines the process for upgrading Optimism chains using the `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 and manual process. From cd6730ccf73713984cfc6d6ef50649eb00b77694 Mon Sep 17 00:00:00 2001 From: Bradley Camacho <42678939+bradleycamacho@users.noreply.github.com> Date: Fri, 25 Apr 2025 15:24:30 -0700 Subject: [PATCH 3/7] Fixes --- pages/stack/superchain-ops-guide.mdx | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/pages/stack/superchain-ops-guide.mdx b/pages/stack/superchain-ops-guide.mdx index ba81210b2..b0dd724df 100644 --- a/pages/stack/superchain-ops-guide.mdx +++ b/pages/stack/superchain-ops-guide.mdx @@ -20,7 +20,6 @@ is_imported_content: 'false' import { Callout } from 'nextra/components' - # Chain upgrade guide: Using superchain-ops This guide outlines the process for upgrading Optimism chains using the `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 and manual process. @@ -31,11 +30,11 @@ This guide outlines the process for upgrading Optimism chains using the `superch `superchain-ops` is primarily intended for: -1. **Chains in the Superchain**: For standard chains officially part of the Superchain, upgrades are typically handled through `superchain-ops`. +1. **Chains in the Superchain**: For standard chains officially part of the Superchain, upgrades are typically handled through `superchain-ops`. -2. **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`. +2. **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`. -3. **Chains requiring a highly secure and manual process**: For chains that prioritize security over automation, `superchain-ops` provides an intentionally manual workflow with thorough verification steps. +3. **Chains requiring a highly secure and manual process**: For chains that prioritize security over automation, `superchain-ops` provides an intentionally manual workflow with thorough verification steps. For chains that don't fall into these categories, you'll need to generate appropriate call data for upgrades through other means or develop your own upgrade process for non-OPCM upgrades. @@ -43,9 +42,9 @@ For chains that don't fall into these categories, you'll need to generate approp `superchain-ops` uses two key concepts: -- **Templates**: Define what the upgrade is and contain the code for specific upgrade paths (e.g., 1.8 to 2.0). Templates are version-specific and live in the (`/src/improvements/template`)[https://github.com/ethereum-optimism/superchain-ops/tree/main/src/improvements/template] directory. +* **Templates**: Define what the upgrade is and contain the code for specific upgrade paths (e.g., 1.8 to 2.0). Templates are version-specific and live in the [/src/improvements/template](https://github.com/ethereum-optimism/superchain-ops/tree/main/src/improvements/template) directory. -- **Tasks**: Chain-specific implementations of templates. Multiple tasks can use the same template for different chains. Tasks are organized by network (mainnet or testnet) in the (`/src/improvements/tasks`)[https://github.com/ethereum-optimism/superchain-ops/tree/main/src/improvements/tasks] directory. +* **Tasks**: Chain-specific implementations of templates. Multiple tasks can use the same template for different chains. Tasks are organized by network (mainnet or testnet) in the [/src/improvements/tasks](https://github.com/ethereum-optimism/superchain-ops/tree/main/src/improvements/tasks) directory. ## General upgrade process @@ -69,21 +68,21 @@ Follow the prompts to select the appropriate template (e.g., `opcm-upgrade-v200` This will create a new task directory containing a `config.toml` and `README` file. The config file will look like this: -``` +```bash l2chains = [] # e.g. [{name = "OP Mainnet", chainId = 10}] templateName = "OPCMUpgradeV200" ``` -### Step 4: Configure the task +### Step 3: Configure the task -Look through other tasks in the directory to find the information necessary for your upgrade. For example, when upgrading from 1.8 to 2.0, you can look at the (`src/improvements/tasks/eth/002-opcm-upgrade-v200/config.toml`)[https://github.com/ethereum-optimism/superchain-ops/blob/main/src/improvements/tasks/eth/002-opcm-upgrade-v200/config.toml] file to see that your config file should look like the following: +Look through other tasks in the directory to find the information necessary for your upgrade. For example, when upgrading from 1.8 to 2.0, you can look at the [src/improvements/tasks/eth/002-opcm-upgrade-v200/config.toml](https://github.com/ethereum-optimism/superchain-ops/blob/main/src/improvements/tasks/eth/002-opcm-upgrade-v200/config.toml) file to see that your config file should look like the following: -Ensure you replace all addresses and other values in the example below + Ensure you replace all addresses and other values in the example below -``` +```bash l2chains = [ {name = "Unichain", chainId = 130} ] @@ -108,7 +107,7 @@ ChildSafe3 = "0xc2819DC788505Aac350142A7A707BF9D03E3Bd03" Before executing the upgrade, simulate it to ensure everything is configured correctly: -``` +```bash # Nested SIMULATE_WITHOUT_LEDGER=1 just --dotenv-path $(pwd)/.env --justfile ../../../nested.just simulate # Single @@ -120,4 +119,3 @@ This will run through the upgrade process without actually executing the transac ### Step 6: Execute or submit for review For chains within the Superchain, submit a pull request to have your task reviewed. If your chain is not within the Superchain, execute the transaction yourself. - From 2ffd408b9405f7d879ead0c352c31a611d863b6c Mon Sep 17 00:00:00 2001 From: Bradley Camacho <42678939+bradleycamacho@users.noreply.github.com> Date: Thu, 8 May 2025 08:36:41 -0700 Subject: [PATCH 4/7] Fix title --- pages/stack/superchain-ops-guide.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/stack/superchain-ops-guide.mdx b/pages/stack/superchain-ops-guide.mdx index b0dd724df..db29c589f 100644 --- a/pages/stack/superchain-ops-guide.mdx +++ b/pages/stack/superchain-ops-guide.mdx @@ -1,5 +1,5 @@ --- -title: Chain upgrade guide Using superchain-ops +title: Chain upgrade guide using superchain-ops description: Learn about using superchain-ops to upgrade your chain lang: en-US content_type: guide @@ -20,7 +20,7 @@ is_imported_content: 'false' import { Callout } from 'nextra/components' -# Chain upgrade guide: Using superchain-ops +# Chain upgrade guide using superchain-ops This guide outlines the process for upgrading Optimism chains using the `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 and manual process. From a26a1d3833308a48e1019ca05ec570562b02a44a Mon Sep 17 00:00:00 2001 From: Bradley Camacho <42678939+bradleycamacho@users.noreply.github.com> Date: Mon, 12 May 2025 08:31:13 -0700 Subject: [PATCH 5/7] Final edits --- pages/stack/superchain-ops-guide.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/pages/stack/superchain-ops-guide.mdx b/pages/stack/superchain-ops-guide.mdx index db29c589f..63fce98fb 100644 --- a/pages/stack/superchain-ops-guide.mdx +++ b/pages/stack/superchain-ops-guide.mdx @@ -107,6 +107,10 @@ ChildSafe3 = "0xc2819DC788505Aac350142A7A707BF9D03E3Bd03" Before executing the upgrade, simulate it to ensure everything is configured correctly: +```bash +just clean && just install +``` + ```bash # Nested SIMULATE_WITHOUT_LEDGER=1 just --dotenv-path $(pwd)/.env --justfile ../../../nested.just simulate @@ -119,3 +123,9 @@ This will run through the upgrade process without actually executing the transac ### Step 6: Execute or submit for review For chains within the Superchain, submit a pull request to have your task reviewed. If your chain is not within the Superchain, execute the transaction yourself. + +## Using op-deployer to create calldata + +The `upgrade` command in op-deployer allows you to upgrade a chain from one version to another. It consists of several subcommands, one for each upgrade version. Think of it like a database migration: each upgrade command upgrades a chain from exactly one previous version to the next. A chain that is several versions behind can be upgrade to the latest version by running multiple upgrade commands in sequence. + +To learn about the `upgrade` command, check out our [devdocs](https://devdocs.optimism.io/op-deployer/user-guide/upgrade.html). \ No newline at end of file From bbbda75e0f75c27ff1df707702c1b69cc3a667eb Mon Sep 17 00:00:00 2001 From: Bradley Camacho <42678939+bradleycamacho@users.noreply.github.com> Date: Mon, 12 May 2025 09:08:43 -0700 Subject: [PATCH 6/7] Fix lint --- pages/stack/superchain-ops-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/superchain-ops-guide.mdx b/pages/stack/superchain-ops-guide.mdx index 63fce98fb..fb921a997 100644 --- a/pages/stack/superchain-ops-guide.mdx +++ b/pages/stack/superchain-ops-guide.mdx @@ -128,4 +128,4 @@ For chains within the Superchain, submit a pull request to have your task review The `upgrade` command in op-deployer allows you to upgrade a chain from one version to another. It consists of several subcommands, one for each upgrade version. Think of it like a database migration: each upgrade command upgrades a chain from exactly one previous version to the next. A chain that is several versions behind can be upgrade to the latest version by running multiple upgrade commands in sequence. -To learn about the `upgrade` command, check out our [devdocs](https://devdocs.optimism.io/op-deployer/user-guide/upgrade.html). \ No newline at end of file +To learn about the `upgrade` command, check out our [devdocs](https://devdocs.optimism.io/op-deployer/user-guide/upgrade.html). From d578ed1499132fa42a139e16e855785798a147a0 Mon Sep 17 00:00:00 2001 From: Bradley Camacho <42678939+bradleycamacho@users.noreply.github.com> Date: Mon, 12 May 2025 09:10:57 -0700 Subject: [PATCH 7/7] lint again --- words.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/words.txt b/words.txt index 8af644f62..b8a74d12b 100644 --- a/words.txt +++ b/words.txt @@ -96,7 +96,8 @@ devnet Devnets devnets Devs - +Devdocs +devdocs direnv DISABLETXPOOLGOSSIP disabletxpoolgossip