ethereum-optimism · bradleycamacho · Apr 10, 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"
+}
@@ -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).
@@ -0,0 +1,121 @@
+---
+title: Upgrading Smart Contracts from v1.6.0 to v1.8.0
+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 from v1.6.0 to v1.8.0
+
+This guide provides specific instructions for upgrading Optimism's Layer 1 contracts from `op-contracts/v1.6.0` to `op-contracts/v1.8.0`. This upgrade includes important changes to the system configuration and fault proof system.
+
+## Overview of the Holocene upgrade
+
+The Holocene Upgrade supports two primary upgrade paths, each with specific components and considerations:
+
+1.  **Upgrading from v1.6.0 to v1.8.0:**
+    *   Always upgrades the `SystemConfig` contract with improvements
+    *   Provides flexible options for fault proof implementation:
+        *   Permissionless fault proofs enabled (including `FaultDisputeGame`)
+        *   Permissioned fault proofs enabled (excluding `FaultDisputeGame`)
+
+2.  **Upgrading from v1.3.0 to v1.8.0:**
+    *   Retains the existing `L2OutputOracle` for backward compatibility
+    *   Only upgrades the `SystemConfig` contract to v1.8.0 functionality
+
+## Required dependencies
+
+Before starting the upgrade process, ensure you have the following tools installed in your environment:
+
+*   [Docker](https://docs.docker.com/engine/install/) for containerized execution
+*   [just](https://github.com/casey/just) command runner for executing upgrade scripts
+*   [Foundry](https://getfoundry.sh/) for contract simulation and verification
+
+For the complete set of dependencies and detailed installation instructions, refer to the [superchain-ops README](https://github.com/ethereum-optimism/superchain-ops/tree/main).
+
+## Step-by-step upgrade process
+
+### 1. Clone the repository
+
+```sh
+git clone --branch proposal/op-contracts/v1.8.0 --depth 1 [email protected]:ethereum-optimism/monorepo.git
+cd monorepo/packages/contracts-bedrock/scripts/upgrades/holocene
+```
+
+### 2. Configure environment
+
+```sh
+cp .env.example .env
+# Edit .env with your specific configuration requirements
+vim .env
+```
+
+### 3. Build Docker image
+
+```sh
+just build-image
+```
+
+**Note:** Ensure Docker has at least 16GB of memory allocated (the default is 8GB), or the Solidity compilations may fail due to memory constraints.
+
+### 4. Execute upgrade
+
+```sh
+just run $(realpath path/to/deploy-config.json)
+```
+
+This command performs several critical functions:
+
+*   Deploys the new smart contract implementations required for the upgrade
+*   Optionally generates a safe upgrade bundle for multisig execution
+*   Optionally generates a `superchain-ops` upgrade task for coordination
+
+To specify a custom output folder path instead of the default `output/` directory:
+
+```sh
+just run $(realpath path/to/deploy-config.json) $(realpath path/to/output)
+```
+
+## Configuration requirements
+
+### Fault game prestate value
+
+The `deploy-config.json` that you use for your chain must set the latest `faultGameAbsolutePrestate` value, not the original value that was set during initial deployment of the chain.
+
+You can use the following recommended value, which is based on `op-program/v1.4.0-rc.3` and includes Holocene activations for various networks:
+
+```
+0x03f89406817db1ed7fd8b31e13300444652cdb0b9c509a674de43483b2f83568
+```
+
+This prestate includes Holocene activations for the following networks:
+
+*   **Sepolia networks:** Base, OP, Metal, Mode, Zora, Ethernity, Unichain, Ink
+*   **Mainnet networks:** Base, OP, Orderly, Lyra, Metal, Mode, Zora, Lisk, Ethernity, Binary
+
+### Script modifications
+
+If you need to make local modifications to the scripts in the `scripts/` directory to accommodate your specific network requirements, you must rebuild the Docker image with `just build-image` before running `just run` again.
+
+## Additional Resources
+
+*   [Optimism Documentation](https://community.optimism.io/docs/)
+*   [superchain-ops Repository](https://github.com/ethereum-optimism/superchain-ops)
+*   [Optimism Monorepo](https://github.com/ethereum-optimism/optimism)
@@ -22,7 +22,7 @@ import { SuperchainContractTable } from '@/components/SuperchainContractTable'
 # Contract Addresses
 
 This reference guide lists all the contract addresses for OP Stack chains, as found on the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry/tree/main). This doc will periodically be updated with addresses across the Superchain.
-See the [Smart Contracts Overview](/stack/smart-contracts) for high-level details and access to the source code.
+See the [Smart Contracts Overview](/stack/smart-contracts/smart-contracts) for high-level details and access to the source code.
 
 <Callout>
 This page is automatically generated from packages in the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry/tree/main) which keeps the content synced and up-to-date.

@@ -168,6 +168,7 @@
 # General redirects
 # ----------------------------------------------------------------------------
 
+/stack/smart-contracts      /stack/smart-contracts/smart-contracts
 /get-started/design-principles      /stack/design-principles
 /index                              /