op-deployer
:
Deployment usage
Deploying an OP Stack chain involves deploying multiple contracts, which can consume a substantial amount of gas. On testnets like Sepolia, costs may fluctuate significantly depending on network congestion. We recommend ensuring your deployer wallet has a buffer of at least 1.5 to 3.5 ETH , depending on gas prices and configuration. Always check current gas estimates before deploying.
op-deployer
is deploying new OP Chains. This process is broken down into three steps:
init
: configure your chain
To get started with op-deployer
, create an intent file that defines your desired chain configuration. Use the built-in op-deployer
utility to generate this file:
op-deployer uses a declarative intent file to determine how a new chain should be configured.
Then, it runs through a deployment pipeline to actually deploy the chain.
- Replace
<l2-chain-id>
with the exact value. - The
--workdir
flag specifies the output directory for the generated intent file and related configs. You can name this directory anything you like ,.deployer
is just an example.
.deployer
in your current working directory containing the intent file and an empty state.json
file. state.json
is populated with the results of your deployment, and never needs to be edited directly.
Your intent file will need to be modified to your parameters, but it will initially look something like this:
Do not use the default addresses in the intent for a production chain! They are generated from the
test... junk
mnemonic. Any funds they hold will be stolen on a live chain.Before you can use your intent file for a deployment, you will need to update all zero values to whatever is appropriate for your chain.
For dev environments, it is ok to use all EOAs/hot-wallets.
- baseFeeVaultRecipient
- l1FeeVaultRecipient
- sequencerFeeVaultRecipient
- l1ProxyAdminOwner
- l2ProxyAdminOwner
- systemConfigOwner
- unsafeBlockSigner
- batcher
- proposer
- challenger
Understanding the intent.toml fields
Working with artifacts
Theartifacts-locator
parameter specifies where the contract deployment artifacts are located. There are several ways to provide artifacts:
Using local files
To use local artifacts (recommended for production or if you’re experiencing issues with remote artifacts):-
Clone the contracts repository:
-
Build the contract artifacts:
-
Use the local path in your command, referencing the artifacts from:
<monorepo-root>/packages/contracts-bedrock/forge-artifacts
Using tagged artifacts
For development or testing, you can try using tagged artifacts:Application failed: failed to parse artifacts URL: unsupported tag
, you’ll need to use the local files method described above, else If you use an invalid tag, the command will display all valid options.
Contract locator schemes
op-deployer uses contract locators to find contract artifacts to deploy. Locators are just URLs under the hood. Thel1ContractsLocator
and l2ContractsLocator
fields support several schemes for specifying where to find the contract implementations:
tag://
- References a specific tagged release of the contracts (e.g.,tag://op-contracts/v1.8.0-rc.4
). In this case, the contracts bytecode will be downloaded from a fixed bytecode bundle on GCS.file://
- Points to a directory on local disk containing the artifacts. This is useful for local development, since you can point it at your local monorepo e.g.file://<path-to-repo-root>/packages/contracts-bedrock/forge-artifacts
http://
orhttps://
- Points to a target directory containing contract artifacts. The URL should directly reference the directory containing theforge-artifacts
directory, in this case, the bytecode will be downloaded from the URL specified.
When using any scheme other than tag://, you must set configType to either custom or standard-overrides in your intent file.
op-deployer
will fill in all other configuration variables with those that match the standard configuration. You can override these default settings by adding them to your intent file using the table below:
chains
table.
apply
: deploy your chain
Hardware wallets are not supported, but you can use ephemeral hot wallets since this deployer key has no privileges.
- Replace
<rpc-url>
with yourL1_RPC_URL
and<private key>
with your private key
-
Deployment targets:
The
--deployment-target
flag specifies where to deploy:live
: Deploys directly to a live L1 network. Requires-l1-rpc-url
and-private-key
.genesis
: Generates an L1 genesis file for local testing or development.calldata
: Produces calldata for multisig wallets, enabling offline deployment.noop
: Performs a dry-run without actual deployment, useful for testing configurations.
verify
: verify contract source code on block explorers
After deploying your contracts, you can verify them on block explorers like Etherscan:
-l1-rpc-url
: RPC URL for the L1 chain-etherscan-api-key
: API key for the block explorer (e.g., from Etherscan)-artifacts-locator
: Path or plugin to locate contract artifacts-input-file
: Path to a JSON file containing deployment data:- Create an
input.json
file in the same directory. - Navigate to your
state.json
file and locate theimplementationsDeployment
object. - Copy everything inside the
implementationsDeployment
object (without the object name itself) and paste it into your newinput.json
file.
- Create an
You don’t need to specify a
--workdir
, op-deployer will automatically look for deployment artifacts from the deploy step, unless overridden.inspect
: generate genesis files and chain information
To add your chain to the Superchain Registry you will need to provide the chain artifacts. To get these chain artifacts, you will need to write the output of these commands to new files.
state.json
file by navigating to your working directory. With the contracts deployed, generate the genesis and rollup configuration files by running the following commands:
genesis.json
and rollup.json
you can spin up a node on your network. You can also use the following inspect subcommands to get additional chain artifacts:
Upgrade usage
Theupgrade
command in op-deployer
simplifies the process of upgrading existing OP Stack chains from one version to the next. This functionality works similar to database migrations - each upgrade command upgrades a chain from exactly one previous version to the next version in sequence.
Unlike the bootstrap
or apply
commands, the upgrade
command doesn’t directly interact with the chain. Instead, it generates calldata that you can then execute using tools like cast
, Gnosis SAFE, or other wallet management systems you use for L1 operations. This approach provides flexibility in how you execute the upgrade while maintaining security through your existing operational procedures.
Chains that are several versions behind the latest can be upgraded by running multiple upgrade commands in sequence, with each command handling one version increment. The upgrade process requires you to be using the standard OP Contracts Manager and the standard shared SuperchainConfig contract for compatibility.
For detailed instructions on using the upgrade command, including configuration examples and step-by-step procedures, see the upgrade documentation.
Bootstrap usage
op-deployer
provides a set of bootstrap commands specifically designed for initializing a new superchain target on an L1 network. These commands are essential when you’re setting up a completely new superchain target environment rather than deploying a new chain on an existing superchain.
Bootstrap process overview
When bootstrapping a new superchain target, you typically need to follow this process:- Deploy proxy admin (
bootstrap proxy
): Sets up theERC-1967
proxy for the superchain management contracts. - Deploy Superchain configuration (
bootstrap superchain
): Creates the foundational superchain configuration contracts. - Deploy implementations (
bootstrap implementations
): Deploys the implementation contracts needed for the dispute game. - Deploy validator (
bootstrap validator
): Deploys theStandardValidator
for the superchain.
Bootstrap proxy
Thebootstrap proxy
command deploys a new ERC-1967
proxy admin, which is required for upgradeability of the superchain contracts.
Command usage
Parameter | Description | Required | Example |
---|---|---|---|
—l1-rpc-url | RPC URL for the L1 chain | Yes | https://sepolia.infura.io/v3/YOUR_API_KEY |
—private-key | Private key for transaction signing | Yes | 0xabcd…1234 |
—artifacts-locator | Location of contract artifacts | Yes | Contract artifacts location, can be found in intent.toml , e.g tag://op-contracts/v3.0.0-rc.2 |
—proxy-owner | Address that will own the proxy | Yes | e.g Your proxyAdminOwner from your intent.toml |
—outfile | File to write output JSON | No | proxy-output.json |
—cache-dir | Directory to cache artifacts | No | .artifacts-cache |
Bootstrap superchain
Thebootstrap superchain
command initializes the core SuperchainConfig
and ProtocolVersions
contracts. These contracts maintain global configuration parameters (including pause functionality) and protocol version requirements across all chains in the superchain. This step is typically performed once when establishing a new superchain on an L1 network, with the deployed addresses needed for subsequent bootstrap commands.
Command usage
Parameter | Description | Required | Example |
---|---|---|---|
—l1-rpc-url | RPC URL for the L1 chain | Yes | https://sepolia.infura.io/v3/YOUR_API_KEY |
—private-key | Private key for signing transaction | Yes | 0xabcd…1234 |
—artifacts-locator | Contract artifacts location, can be found in intent.toml | Yes | tag://op-contracts/v3.0.0-rc.2 |
—superchain-proxy-admin-owner | Address that owns the superchain proxy admin, can be found in state.json | Yes | 0x1234…abcd |
—protocol-versions-owner | Address that can update protocol versions can be found in state.json | Yes | 0x2345…bcde |
—guardian | Address authorized to pause L1 withdrawals from contracts, blacklist dispute games, and set the respected game type, can be found in state.json | Yes | 0x3456…cdef |
—paused | Whether the superchain starts paused | No (defaults to false) | false |
—required-protocol-version | Minimum required protocol version address | No | 1.0.0 |
—recommended-protocol-version | Recommended protocol version | No | 1.0.0 |
—outfile | File to write output JSON | No (defaults to stdout) | superchain-output.json |
—cache-dir | Directory to cache artifacts | No | .artifacts-cache |
Bootstrap implementations
Thebootstrap implementations
command deploys essential OP Stack infrastructure contracts. Chain operators use this command when spinning up a brand new superchain target, not when adding a chain to an existing superchain.
Command usage
Parameter | Description | Required | Default | Example |
---|---|---|---|---|
—l1-rpc-url | RPC URL for the L1 chain | Yes | - | https://sepolia.infura.io/v3/YOUR_API_KEY |
—private-key | Private key for transaction signing | Yes | - | 0xabcd…1234 |
—artifacts-locator | Location of contract artifacts | Yes | - | file:///path/to/artifacts |
—mips-version | MIPS version for the fault proof system (1 or 2) | No | From standard config | 2 |
—withdrawal-delay-seconds | Delay for withdrawals in seconds | No | From standard config | 604800 (1 week) |
—min-proposal-size-bytes | Minimum size for proposals in bytes | No | From standard config | 1 |
—challenge-period-seconds | Challenge period in seconds | No | From standard config | 604800 (1 week) |
—proof-maturity-delay-seconds | Proof maturity delay in seconds | No | From standard config | 60 |
—dispute-game-finality-delay-seconds | Dispute game finality delay in seconds | No | From standard config | 604800 (1 week) |
—superchain-config-proxy | Address of superchain config proxy | Yes | - | Result from superchain command |
—protocol-versions-proxy | Address of protocol versions proxy | Yes | - | Result from superchain command |
—upgrade-controller | Address of upgrade controller | Yes | - | 0x0000…0000 |
—use-interop | Whether to enable interoperability features | No | false | true |
—outfile | File to write output JSON | No | stdout | implementations-output.json |
—cache-dir | Directory to cache artifacts | No | - | .artifacts-cache |
Understanding MIPS version
Themips-version
parameter determines which version of the Cannon MIPS VM to use for fault proofs:
- MIPS Version 1 (MIPS32): The original implementation based on the 32-bit MIPS architecture. Suitable for most legacy or existing deployments.
- MIPS Version 2 (MIPS64): An enhanced implementation based on the 64-bit MIPS architecture, offering improved performance and efficiency. Generally preferred for new deployments.
Next steps
- For more details, check out the tool and documentation in the op-deployer repository.
- For more information on OP Contracts Manager, refer to the OPCM documentation.