Skip to content

Smart contract section #1563

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 46 commits into from
May 30, 2025
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
e799212
Smart contract section
bradleycamacho Apr 10, 2025
31f44c4
Fixes
bradleycamacho Apr 10, 2025
95fb41a
Fix lint
bradleycamacho Apr 10, 2025
5798c3e
Delete page
bradleycamacho Apr 10, 2025
2b7f303
Final edits
bradleycamacho May 12, 2025
e24ee32
Merge branch 'main' into contract-updates
bradleycamacho May 12, 2025
2592df3
breadcrumbs
bradleycamacho May 12, 2025
2e8be36
Merge branch 'contract-updates' of https://github.com/ethereum-optimi…
bradleycamacho May 12, 2025
821a44a
Fix lint
bradleycamacho May 12, 2025
e7b621f
Restore op-deployer content
bradleycamacho May 14, 2025
29ce7cc
Auto-fix: Update breadcrumbs, spelling dictionary and other automated…
bradleycamacho May 14, 2025
4314609
Merge branch 'main' into contract-updates
bradleycamacho May 14, 2025
1777ceb
Auto-fix: Update breadcrumbs, spelling dictionary and other automated…
bradleycamacho May 14, 2025
af6ad15
Move superchain-ops doc and create op-deployer doc
bradleycamacho May 14, 2025
b1c5b13
Auto-fix: Update breadcrumbs, spelling dictionary and other automated…
bradleycamacho May 14, 2025
7e9f4d9
Fix breadcrumbs
bradleycamacho May 14, 2025
961ec92
Import steps
bradleycamacho May 14, 2025
83546b2
Add links in upgrade overview page
bradleycamacho May 14, 2025
3a2f0aa
Implement feedback
bradleycamacho May 29, 2025
afc447b
Auto-fix: Update breadcrumbs, spelling dictionary and other automated…
bradleycamacho May 29, 2025
2bc5942
small fix
bradleycamacho May 29, 2025
8001e14
Auto-fix: Update breadcrumbs, spelling dictionary and other automated…
bradleycamacho May 29, 2025
dad9b21
Clarify upgrades
bradleycamacho May 29, 2025
6ce9a54
Update 1.3>1.8
bradleycamacho May 29, 2025
c6e4eac
fix docker references
bradleycamacho May 29, 2025
cf11fdd
fix title
bradleycamacho May 29, 2025
c333b2d
Fix docker again
bradleycamacho May 29, 2025
71005ab
Fix nav
bradleycamacho May 29, 2025
d3f60f4
Auto-fix: Update breadcrumbs, spelling dictionary and other automated…
bradleycamacho May 29, 2025
6c5e6cc
Merge branch 'main' into contract-updates
bradleycamacho May 29, 2025
24ef5f7
Auto-fix: Update breadcrumbs, spelling dictionary and other automated…
bradleycamacho May 29, 2025
e5cced2
Fix checkout
bradleycamacho May 29, 2025
a528cf1
Remove redundant info
bradleycamacho May 29, 2025
45a9539
Add code block formatting
bradleycamacho May 29, 2025
29ca519
Implement feedback
bradleycamacho May 29, 2025
2ac88ad
Add missing output descriptions
bradleycamacho May 29, 2025
acf3ccc
Implement feedback and small fixes
bradleycamacho May 29, 2025
38be307
Auto-fix: Update breadcrumbs, spelling dictionary and other automated…
bradleycamacho May 29, 2025
b1ce3b1
Update pages/stack/smart-contracts/upgrade-op-contracts-1-3-1-8.mdx
bradleycamacho May 30, 2025
dabfc54
Update pages/stack/smart-contracts/upgrade-op-contracts-1-3-1-8.mdx
bradleycamacho May 30, 2025
046d657
Update pages/stack/smart-contracts/upgrade-op-contracts-1-3-1-8.mdx
bradleycamacho May 30, 2025
09715e6
Update pages/stack/smart-contracts/upgrade-op-contracts-1-3-1-8.mdx
bradleycamacho May 30, 2025
3ffb217
Update pages/stack/smart-contracts/upgrade-op-contracts-1-3-1-8.mdx
bradleycamacho May 30, 2025
8f96d23
Implement feedback
bradleycamacho May 30, 2025
e782df1
Merge branch 'contract-updates' of https://github.com/ethereum-optimi…
bradleycamacho May 30, 2025
2521d60
Merge branch 'main' into contract-updates
bradleycamacho May 30, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion pages/operators/chain-operators/deploy/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions pages/operators/chain-operators/self-hosted.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion pages/stack/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": "",
Expand Down
2 changes: 1 addition & 1 deletion pages/stack/opcm.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
788 changes: 10 additions & 778 deletions pages/stack/smart-contracts.mdx

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions pages/stack/smart-contracts/_meta.json
Original file line number Diff line number Diff line change
@@ -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"
}
113 changes: 113 additions & 0 deletions pages/stack/smart-contracts/smart-contract-upgrades.mdx
Original file line number Diff line number Diff line change
@@ -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).
Loading