ethereum-optimism · bradleycamacho · May 30, 2025 · Apr 10, 2025 · Apr 10, 2025 · Apr 10, 2025
@@ -38,7 +38,7 @@ contracts that are deployed when the chain is created.
   Standard OP Stack chains should only use governance approved and audited
   smart contracts. The monorepo has them tagged with the following pattern
   `op-contracts/vX.X.X` and you can review the release notes for details on the
-  changes. Read more about the details in our [Smart Contract Release Section](/stack/smart-contracts#official-releases).
+  changes. Read more about the details in our [Smart Contract Release Section](/stack/smart-contracts/smart-contracts#official-releases).
 </Callout>
 
 ## Sequencer node

@@ -32,10 +32,9 @@ Deploying OP Stack L1 contracts is a critical step in setting up your rollup.
   generally not considered backwards compatible.
 </Callout>
 
-## Deployment workflow
-
 <Steps>
-  ### Install op-deployer
+
+### Install op-deployer
 
   First, install the `op-deployer` tool following the [installation instructions](/operators/chain-operators/tools/op-deployer#installation).
 

@@ -35,8 +35,8 @@ There are two main steps to get started building your own self-hosted OP Chain:
   *   **Chain Architecture**: OP Chains use execution and consensus clients as well as the OP Stack's privileged roles. For more details, see the [Chain Architecture](/operators/chain-operators/architecture) guide.
   *   **Smart Contracts**: OP Chains use several smart contracts on the L1 
   blockchain to manage aspects of the Rollup. Each OP Stack chain has its own 
-  set of [L1 smart contracts](/stack/smart-contracts), 
-  [L2 predeploy contracts](/stack/smart-contracts),
+  set of [L1 smart contracts](/stack/smart-contracts/smart-contracts), 
+  [L2 predeploy contracts](/stack/smart-contracts/smart-contracts),
   and [L2 preinstall contracts](/operators/chain-operators/features/preinstalls)
   that are deployed when the chain is created.
   *   **Preinstalls**: OP Chains come with [preinstalled core contracts](/operators/chain-operators/features/preinstalls), making them usable as soon as a chain is initialized on the OP Stack.

@@ -9,13 +9,13 @@
   "design-principles": "Design philosophy & principles",
   "components": "OP Stack components",
   "public-devnets": "Public devnets",
-  "smart-contracts": "Smart contracts",
   "superchain-ops-guide": "Superchain-ops upgrades",
   "opcm": "OP Contracts Manager",
   "rollup": "Rollup",
   "fault-proofs": "Fault proofs",
   "transactions": "Transactions",
   "features": "Features",
+  "smart-contracts": "Smart contracts",
   "security": "Security",
   "+++ Experimental": {
     "title": "",

@@ -24,7 +24,7 @@ import { Callout, Tabs, Steps } from 'nextra/components'
 
 The OP Contracts Manager is a contract that deploys the L1 contracts for an OP Stack chain in a single transaction. It provides a minimal set of user-configurable parameters to ensure that the resulting chain meets the standard configuration requirements. Additionally, as of [Upgrade 13](https://gov.optimism.io/t/upgrade-proposal-13-opcm-and-incident-response-improvements/9739), instances of OPCM can upgrade existing OP Stack chains.
 
-The version deployed is always a governance-approved contract release. The set of governance approved contract releases can be found on the Optimism Monorepo releases page, and is the set of releases named `op-contracts/vX.Y.Z`. It deploys the [Fault Proof System](/stack/fault-proofs/explainer), using the [PermissionedDisputeGame](/stack/smart-contracts#permissioneddisputegame).
+The version deployed is always a governance-approved contract release. The set of governance approved contract releases can be found on the Optimism Monorepo releases page, and is the set of releases named `op-contracts/vX.Y.Z`. It deploys the [Fault Proof System](/stack/fault-proofs/explainer), using the [PermissionedDisputeGame](/stack/smart-contracts/smart-contracts#permissioneddisputegame).
 
 ## Purpose
 

@@ -0,0 +1,6 @@
+{
+  "smart-contracts": "Smart Contracts",
+  "superchain-ops-guide": "Upgrade using superchain-op",
+  "op-deployer-upgrade.mdx": "Upgrade using op-deployer",
+  "upgrade-op-contracts-1-3-1-8.mdx": "Upgrade OP Contracts v1.3.0 to v1.8.0"
+}
@@ -0,0 +1,85 @@
+---
+title: Upgrade L1 contracts using `op-deployer`
+description: Learn about how to upgrade smart contracts using op-deployer
+lang: en-US
+content_type: guide
+topic: smart-contract-overview
+personas:
+  - protocol-developer
+  - chain-operator
+categories:
+  - protocol
+  - l1-contracts
+  - contract-upgrades
+is_imported_content: 'false'
+---
+
+import { Steps } from 'nextra/components'
+
+# Upgrade L1 contracts using `op-deployer`
+
+[`op-deployer`](/operators/chain-operators/tools/op-deployer) simplifies the process of deploying and upgrading the OP Stack. Using the `upgrade` command, you can upgrade a chain from one version to the next.
+
+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.
+
+Unlike the bootstrap or apply commands, upgrade does not directly interact with the chain. Instead, it generates calldata. You can then use this calldate with cast, Gnosis SAFE, or whatever tooling you use to manage your L1.
+
+## Limitations of `upgrade`
+
+There are a few limitations to `upgrade`:
+
+Using the standard OP Contracts Manager currently requires you to be using the standard shared SuperchainConfig contract. If you're not using this, you will need to utilize the `bootstrap` command to deploy your own Superchain target, including your own `opcm` instance.
+
+## Using `upgrade`
+
+<Steps>
+  ### Install `op-deployer`
+
+  [Install `op-deployer`](/operators/chain-operators/tools/op-deployer#installation) from source or pre-built binary.
+
+  ### Create a `config.json` file
+
+  Create a `config.json` file using the following example:
+
+  ```json
+  {
+    "prank": "<address of the contract of the L1 ProxyAdmin owner>",
+    "opcm": "<address of the chain's OPCM>",
+    "chainConfigs": [
+      {
+        "systemConfigProxy": "<address of the chain's system config proxy>",
+        "proxyAdmin": "<address of the chain's proxy admin>",
+        "absolutePrestate": "<32-byte hash of the chain's absolute prestate>"
+      }
+    ]
+  }
+  ```
+
+  The standard OPCM instances (`opcm` in the example above) and absolute prestates (`absolutePrestate`) are found in the superchain registry:
+
+  *   `opcm`: under `op_contracts_manager` for [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-mainnet.toml) and [Sepolia](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-sepolia.toml).
+  *   `absolutePrestate`: the `hash` under your [chosen upgrade](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-prestates.toml)
+
+  ### Generate calldata
+
+  Run the following command:
+
+  ```bash
+  op-deployer upgrade <version> \
+    --config <path to config JSON>
+  ```
+
+  `version` must be either major release `2.0` or higher.
+
+  The output should look like:
+
+  ```json
+  {
+    "to": "<maps to the prank address>",
+    "data": "<calldata>",
+    "value": "0x0"
+  }
+  ```
+
+  Now you have the calldata that can be executed onchain to perform the L1 contract upgrade. You should simulate this upgrade and make sure the changes are expected. You can reference the validation files of previously executed upgrade tasks in the [superchain-ops repo](https://github.com/ethereum-optimism/superchain-ops/blob/main/tasks/eth/022-holocene-fp-upgrade/NestedSignFromJson.s.sol) to see what the expected changes are. Once you're confident the state changes are expected, you can sign and execute the upgrade.
+</Steps>