|
| 1 | +--- |
| 2 | +title: Upgrade L1 contracts using `op-deployer` |
| 3 | +description: Learn about how to upgrade smart contracts using op-deployer |
| 4 | +lang: en-US |
| 5 | +content_type: guide |
| 6 | +topic: smart-contract-deployer-upgrade |
| 7 | +personas: |
| 8 | + - protocol-developer |
| 9 | + - chain-operator |
| 10 | +categories: |
| 11 | + - protocol |
| 12 | + - l1-contracts |
| 13 | + - contract-upgrades |
| 14 | +is_imported_content: 'false' |
| 15 | +--- |
| 16 | + |
| 17 | +import { Steps } from 'nextra/components' |
| 18 | + |
| 19 | +# Upgrade L1 contracts using `op-deployer` |
| 20 | + |
| 21 | +[`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. |
| 22 | + |
| 23 | +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 upgraded to the latest version by running multiple upgrade commands in sequence. |
| 24 | + |
| 25 | +Unlike the bootstrap or apply commands, upgrade does not directly interact with the chain. Instead, it generates calldata. You can then use this calldata with cast, Gnosis SAFE, or whatever tooling you use to manage your L1. |
| 26 | + |
| 27 | +## Limitations of `upgrade` |
| 28 | + |
| 29 | +There are a few limitations to `upgrade`: |
| 30 | + |
| 31 | +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. |
| 32 | + |
| 33 | +## Using `upgrade` |
| 34 | + |
| 35 | +<Steps> |
| 36 | + ### Install `op-deployer` |
| 37 | + |
| 38 | + [Install `op-deployer`](/operators/chain-operators/tools/op-deployer#installation) from source or pre-built binary. |
| 39 | + |
| 40 | + ### Create a `config.json` file |
| 41 | + |
| 42 | + Create a `config.json` file using the following example: |
| 43 | + |
| 44 | + ```json |
| 45 | + { |
| 46 | + "prank": "<address of the contract of the L1 ProxyAdmin owner>", |
| 47 | + "opcm": "<address of the chain's OPCM>", |
| 48 | + "chainConfigs": [ |
| 49 | + { |
| 50 | + "systemConfigProxy": "<address of the chain's system config proxy>", |
| 51 | + "proxyAdmin": "<address of the chain's proxy admin>", |
| 52 | + "absolutePrestate": "<32-byte hash of the chain's absolute prestate>" |
| 53 | + } |
| 54 | + ] |
| 55 | + } |
| 56 | + ``` |
| 57 | + |
| 58 | + The standard OPCM instances (`opcm` in the example above) and absolute prestates (`absolutePrestate`) are found in the superchain registry: |
| 59 | + |
| 60 | + * `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). |
| 61 | + * `absolutePrestate`: the `hash` under your [chosen upgrade](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-prestates.toml) |
| 62 | + |
| 63 | + ### Generate calldata |
| 64 | + |
| 65 | + Run the following command: |
| 66 | + |
| 67 | + ```bash |
| 68 | + op-deployer upgrade <version> \ |
| 69 | + --config <path to config JSON> |
| 70 | + ``` |
| 71 | + |
| 72 | + `version` must be either major release `2.0` or higher. |
| 73 | + |
| 74 | + The output should look like: |
| 75 | + |
| 76 | + ```json |
| 77 | + { |
| 78 | + "to": "<maps to the prank address>", |
| 79 | + "data": "<calldata>", |
| 80 | + "value": "0x0" |
| 81 | + } |
| 82 | + ``` |
| 83 | + |
| 84 | + 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. |
| 85 | +</Steps> |
0 commit comments