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).
 </Callout>
 
 ## Sequencer node

@@ -29,7 +29,7 @@ For the latest recommended method, use [op-deployer](/operators/chain-operators/
 
 The following guide shows you how to deploy the OP Stack L1 smart contracts.
 The primary development branch is `develop`, however **you should only deploy
-official contract releases**. You can visit the [smart contract overview](/stack/smart-contracts#official-releases)
+official contract releases**. You can visit the [smart contract overview](/stack/smart-contracts/smart-contracts)
 for the official release versions. Changes to the smart contracts are
 generally not considered backwards compatible.
 

@@ -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,12 +9,12 @@
   "design-principles": "Design philosophy & principles",
   "components": "OP Stack components",
   "public-devnets": "Public devnets",
-  "smart-contracts": "Smart contracts",
   "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).
 
 ## Purpose
 

@@ -0,0 +1,5 @@
+{
+  "smart-contracts": "Smart Contracts",
+  "smart-contract-upgrades": "Smart Contracts upgrades",
+  "upgrade-op-contracts-1-6-1-8.mdx": "Upgrade v1.6.0 to v1.8.0"
+}
diff --git a/pages/stack/smart-contracts/smart-contract-upgrades.mdx b/pages/stack/smart-contracts/smart-contract-upgrades.mdx
@@ -0,0 +1,113 @@
+---
+title: Smart Contract upgrades
+description: Learn about upgrading the smart contracts that make up the OP Stack.
+lang: en-US
+content_type: guide
+topic: smart-contract-upgrades
+personas:
+  - protocol-developer
+  - chain-operator
+  - app-developer
+categories:
+  - mainnet
+  - protocol
+  - l1-contracts
+  - predeploys
+  - contract-addresses
+  - contract-upgrades
+  - architecture
+  - fault-proofs
+is_imported_content: 'false'
+---
+
+import { Callout } from 'nextra/components'
+
+# Upgrading Optimism L1 smart contracts
+
+This guide outlines the definitive process for upgrading Optimism Layer 1 smart contracts using the superchain-ops repository.
+
+## The superchain-ops repository
+
+The [superchain-ops repository](https://github.com/ethereum-optimism/superchain-ops/tree/main) is the central hub for all Optimism network upgrades. It contains:
+
+1.  Execution code for deployments
+2.  Artifacts from previous upgrades
+3.  Tools for validating and executing new upgrades
+
+The repository structure is explicitly designed to track all significant network changes that require authorization to execute. When planning an upgrade, you must use this repository.
+
+## Repository structure requirements
+
+You must organize your upgrade according to these strict requirements:
+
+Top level directory names must follow the [EIP-3770](https://eips.ethereum.org/EIPS/eip-3770) short name for the network (e.g., "mainnet", "sepolia").
+
+Each task directory must contain:
+
+*   `README.md`: Describing precisely what the task will execute
+*   `Validation.md`: Detailing the expected state changes with justifications
+*   A foundry script for post-upgrade assertions:
+    *   Use `SignFromJson.s.sol` for a Safe owned by EOA signers
+    *   Use `NestedSignFromJson.s.sol` for a Safe owned by other Safes
+*   `input.json`: Defining the exact transaction for execution
+*   `.env`: Containing all environment variables specific to this task
+
+See [the repo](https://github.com/ethereum-optimism/superchain-ops/tree/main) for more info.
+
+## Upgrade process
+
+Follow these steps to upgrade your smart contracts:
+
+### Required dependencies
+
+You must install these tools before beginning:
+
+*   `docker` - Required for containerized execution
+*   `just` - Required for running script commands
+*   `foundry` - Required for contract validation
+
+### Step-by-step workflow
+
+1.  **Set up your environment**:
+    First, clone the repository with the appropriate branch for your upgrade target:
+
+    ```sh
+    git clone --branch [specific-version-branch] --depth 1 [repository-url]
+    cd [path-to-upgrade-scripts]
+    ```
+
+    You must use the specific branch that contains the contract version you're upgrading to.
+
+2.  **Configure your environment variables**:
+
+    ```sh
+    cp .env.example .env
+    vim .env
+    ```
+
+    Your .env file must include all necessary configuration parameters.
+
+3.  **Build the Docker image**:
+
+    ```sh
+    just build-image
+    ```
+
+    You must allocate at least 16GB of memory to Docker or the compilation will fail. The default 8GB is insufficient.
+
+4.  **Run the upgrade task**:
+
+    ```sh
+    just run $(realpath path/to/deploy-config.json)
+    ```
+
+    Your deploy-config.json must contain the correct configuration values for your target network.
+
+    **CRITICAL:** If your upgrade involves fault proof systems, you must set the correct `faultGameAbsolutePrestate` value. Use the latest value, not the original deployment value.
+
+## Resources
+
+*   [superchain-ops Repository](https://github.com/ethereum-optimism/superchain-ops)
+*   [Optimism Monorepo](https://github.com/ethereum-optimism/optimism)
+
+For detailed installation instructions, see the [superchain-ops README](https://github.com/ethereum-optimism/superchain-ops/tree/main).