🎉 We are deprecating the Optimism SDK and migrating all tutorials to use viem/op-stack. Read more →
Builders
Chain operators
Deployment
Contract deployment

OP Stack smart contract deployment

Standard OP Stack chains must use the latest governance approved and audited versions of the smart contract code.

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 see the smart contract overview for the official release versions. Changes to the smart contracts are generally not considered backwards compatible.

⚠️

The following deployment information outlines the legacy method for deploying the OP Stack L1 contracts. This method is not recommended and is provided here only for historical context.

Deployment Configuration

To deploy OP Stack contracts, you need to create a deployment configuration JSON file. The file should be placed in the following monorepo subdirectory: packages/contracts-bedrock/deploy-config (opens in a new tab).

For a detailed explanation of the configuration options and their meanings, refer to the rollup deployment configuration page.

Deployment script (Legacy Method)

The legacy method for deploying smart contracts uses foundry (opens in a new tab) and the deployment script located in the monorepo at packages/contracts-bedrock/scripts/deploy/Deploy.s.sol (opens in a new tab).

State diff

You can verify the state diff before deploying the contracts by using the runWithStateDiff() function in the deployment script. This produces outputs in snapshots/state-diff/ (opens in a new tab). Run the deployment with state diffs using the following command:

forge script -vvv scripts/deploy/Deploy.s.sol:Deploy --sig 'runWithStateDiff()' --rpc-url $ETH_RPC_URL --broadcast --private-key $PRIVATE_KEY

Execution

  • Set the ETHERSCAN_API_KEY and add the --verify flag to verify your contracts.
  • DEPLOYMENT_OUTFILE will determine the filepath that the deployment artifact is written to on disk after the deployment. It comes in the form of a JSON file where keys are the names of the contracts and the values are the addresses the contract was deployed to.
  • DEPLOY_CONFIG_PATH is the path on the filesystem that points to a deployment config. The same deployment config JSON file should be used for L1 contracts deployment as when generating the L2 genesis allocs. See the deploy-config (opens in a new tab) directory for examples and the rollup configuration page for descriptions of the values.
  • IMPL_SALT env var can be used to set the create2 salt for deploying the implementation contracts.

This will deploy an entire new system of L1 smart contracts, including a new SuperchainConfig. In the future, there will be an easy way to deploy only proxies and use shared implementations for each of the contracts as well as a shared SuperchainConfig contract.

DEPLOYMENT_OUTFILE=deployments/artifact.json \
DEPLOY_CONFIG_PATH=<PATH_TO_MY_DEPLOY_CONFIG> \
  forge script scripts/deploy/Deploy.s.sol:Deploy \
  --broadcast --private-key $PRIVATE_KEY \
  --rpc-url $ETH_RPC_URL

Deploying a single contract

All functions for deploying a single contract are public, meaning that the --sig argument to forge script can be used to target the deployment of a single contract.

Using op-deployer

The recommended way to deploy the L1 smart contracts is with the op-deployer tool. Follow these steps:

Set Up Your Environment

  • Install op-deployer: The recommended way to install op-deployer is to download the latest release from the monorepo's release page (opens in a new tab). To install a release, download the binary for your platform then extract it somewhere on your PATH.
  • Access to the L1 blockchain (e.g., Sepolia or Mainnet) via an RPC URL.
  • A private key with sufficient funds to cover deployment costs.

Create an intent file

  • Define the configuration of your chain in an intent file.
  • This file specifies the deployment parameters for both L1. Follow the instructions provided in the configure your chain section to generate the intent file.

Run the apply command

The next step is to deploy the L1 smart contracts, by running the following command:

./bin/op-deployer apply --workdir .deployer --l1-rpc-url <rpc-url> --private-key <private key hex>
  • Replace <rpc-url> with your L1 RPC URL.
  • Replace <private key> with the private key of the account used for deployment.

Verify the deployment

Once the deployment is complete, you can verify the deployed contract addresses and configuration:

  • Check the deployment output for contract addresses and transaction details.
  • Verify the deployed contracts on the block explorer using the specified ETHERSCAN_API_KEY in the configuration file.

If you need deterministic deployment (e.g., for deploying contracts at the same address across multiple chains), use the CREATE2 method.

Best practices

Production users should deploy their L1 contracts from a contracts release. All contracts releases are on git tags with the following format: op-contracts/vX.Y.Z. If you're deploying a new standard chain, you should deploy the Fault Proof Fixes release (opens in a new tab) with the permissioned game type enabled. Starting with permissioned fault proofs gives chain operators time to get comfortable running the additional infrastructure requirements: op-challenger (opens in a new tab) and monitoring (opens in a new tab). There are also additional changes to the economics of operating a permissionless fault proof that chain operators should have a firm understanding of.

Next steps