Skip to content

Update Docs for Deploying OP Stack Smart Contracts Using op-deployer #1281

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.

Sign up for GitHub

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

Closed
Parent: Update oracles.mdx - SUPRA Oracle + VRF in OP Devs Docs Page.
wants to merge 14 commits into from
Closed

Update Docs for Deploying OP Stack Smart Contracts Using op-deployer #1281

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
7a1464d
Updated callouts
krofax Jan 24, 2025
b51399e
fix indentation issues
krofax Jan 24, 2025
af231c4
updated the L1 contract deployement section
krofax Jan 24, 2025
b83fa28
removed redundant section
krofax Jan 24, 2025
c553cf3
Add the steps to l2 testnet tutorial
krofax Jan 24, 2025
90586bd
fix format error
krofax Jan 24, 2025
acfdf9b
fix conflict
krofax Jan 27, 2025
08fc670
fix lint issues
krofax Jan 27, 2025
5685246
updated the instructions for deployment
krofax Jan 28, 2025
acebb69
update the download instructions
krofax Jan 28, 2025
2c77491
updated bas command
krofax Jan 28, 2025
3225bc9
Update pages/builders/chain-operators/deploy/smart-contracts.mdx
krofax Jan 29, 2025
e8bd089
remove duplicated
krofax Jan 29, 2025
0be9501
fixed typo
krofax Jan 29, 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
80 changes: 62 additions & 18 deletions pages/builders/chain-operators/deploy/smart-contracts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,12 @@ lang: en-US
description: Learn how to deploy the OP Stack L1 smart contracts.
---

import { Callout } from 'nextra/components'
import { Callout, Steps } from 'nextra/components'

# OP Stack smart contract deployment

<Callout type="warning">
This page is out of date and shows the legacy method for smart contract deployment.
For the latest recommended method, use [op-deployer](/builders/chain-operators/tools/op-deployer).
<Callout type="info">
Standard OP Stack chains must use the latest governance approved and audited versions of the smart contract code.
</Callout>

The following guide shows you how to deploy the OP Stack L1 smart contracts.
Expand All @@ -19,29 +18,28 @@ 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.

<Callout>
Standard OP Stack chains should use the latest governance approved and audited versions of the smart contract code.
<Callout type="warning">
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.
</Callout>

## Deployment configuration
## 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](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/deploy-config).

Deploying your OP Stack contracts requires creating a deployment configuration
JSON file. You will create a new deployment configuration file in the following
monorepo subdirectory: [packages/contracts-bedrock/deploy-config](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/deploy-config)
For the full set of deployment configuration options and their meanings, you
can see the [rollup deployment configuration page](/builders/chain-operators/configuration/rollup).
For a detailed explanation of the configuration options and their meanings, refer to the [rollup deployment configuration page](/builders/chain-operators/configuration/rollup).

## Deployment script
## Deployment script (Legacy Method)

The smart contracts are deployed using [foundry](https://github.com/foundry-rs)
and you can find the script's source code in the monorepo at
The legacy method for deploying smart contracts uses [foundry](https://github.com/foundry-rs) and the deployment script located in the monorepo at
[packages/contracts-bedrock/scripts/deploy/Deploy.s.sol](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/scripts/deploy/Deploy.s.sol).

### State diff

Before deploying the contracts, you can verify the state diff by using the `runWithStateDiff()` function signature in the deployment script, which produces
the outputs inside [`snapshots/state-diff/`](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/snapshots/state-diff).
Run the deployment with state diffs by executing:
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/`](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/snapshots/state-diff).
Run the deployment with state diffs using the following command:

```bash
forge script -vvv scripts/deploy/Deploy.s.sol:Deploy --sig 'runWithStateDiff()' --rpc-url $ETH_RPC_URL --broadcast --private-key $PRIVATE_KEY
Expand Down Expand Up @@ -82,6 +80,52 @@ 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:

<Steps>
{<h3>Set Up Your Environment</h3>}

* Install `op-deployer`:
The recommended way to install `op-deployer` is to download the latest release from the monorepo's
[release page](https://github.com/ethereum-optimism/optimism/releases). 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](/builders/chain-operators/tools/op-deployer#init-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:

```bash
./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.

</Steps>

<Callout type="info">
If you need deterministic deployment (e.g., for deploying contracts at the same address across multiple chains),
use the `CREATE2` method.
</Callout>

## Best practices

Production users should deploy their L1 contracts from a contracts release.
Expand Down
17 changes: 13 additions & 4 deletions pages/builders/chain-operators/tools/op-deployer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,14 @@ import {Callout, Steps} from 'nextra/components'

The recommended way to install `op-deployer` is to download the latest release from the monorepo's
[release page](https://github.com/ethereum-optimism/optimism/releases). To install a release, download the binary
for your platform then extract it somewhere on your `PATH`. The rest of this tutorial will assume that you have
for your platform then extract it somewhere on your `PATH`.

Run the following command:
```bash
cd op-deployer && just build
```

The rest of this tutorial will assume that you have
installed `op-deployer` using this method.

## Deployment usage
Expand All @@ -31,6 +38,7 @@ To get started with `op-deployer`, create an intent file that defines your desir
```
./bin/op-deployer init --l1-chain-id 11155111 --l2-chain-ids <l2-chain-id> --workdir .deployer
```
Replace `<l2-chain-id>` with the correct value.

This command will create a directory called `.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.

Expand Down Expand Up @@ -97,8 +105,9 @@ You can also do chain by chain configurations in the `chains` table.
Now that you've created your intent file, you can apply it to your chain to deploy the L1 smart contracts:

```
op-deployer apply --workdir .deployer --l1-rpc-url <rpc-url> --private-key <private key hex>
./bin/op-deployer apply --workdir .deployer --l1-rpc-url <rpc-url> --private-key <private key hex>
```
* Replace `<rpc-url>` with your `L1_RPC_URL` and `<private key>` with your private key

This command will deploy the OP Stack to L1. It will deploy all L2s specified in the intent file. Superchain
configuration will be set to the Superchain-wide defaults - i.e., your chain will be opted into the [Superchain pause](https://specs.optimism.io/protocol/superchain-config.html#pausability)
Expand All @@ -114,8 +123,8 @@ address as other chains on the Superchain.
Inspect the `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:

```
op-deployer inspect genesis --workdir .deployer <l2-chain-id> > .deployer/genesis.json
op-deployer inspect rollup --workdir .deployer <l2-chain-id> > .deployer/rollup.json
./bin/op-deployer inspect genesis --workdir .deployer <l2-chain-id> > .deployer/genesis.json
./bin/op-deployer inspect rollup --workdir .deployer <l2-chain-id> > .deployer/rollup.json
```

Now that you have your `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 data:
Expand Down
84 changes: 45 additions & 39 deletions pages/builders/chain-operators/tutorials/create-l2-rollup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,6 @@ import { WipCallout } from '@/components/WipCallout'
<WipCallout />
# Creating your own L2 rollup testnet



<Callout type="info">
Please **be prepared to set aside approximately one hour** to get everything running properly and **make sure to read through the guide carefully**.
You don't want to miss any important steps that might cause issues down the line.
Expand Down Expand Up @@ -419,71 +417,79 @@ cast codesize 0x4e59b44847b379578588920cA78FbF26c0B4956C --rpc-url $L1_RPC_URL

Once you've configured your network, it's time to deploy the L1 contracts necessary for the functionality of the chain.

### Using `op-deployer`

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

<Steps>
{<h3>Set Up Your Environment</h3>}

* Install `op-deployer`:
The recommended way to install `op-deployer` is to download the latest release from the monorepo's
[release page](https://github.com/ethereum-optimism/optimism/releases). 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.

{<h3>Deploy the L1 contracts</h3>}
### Create an intent file

* Define the configuration of your chain in an intent file.
* This file specifies the deployment parameters for deploying the L1 smart contract.
Follow the instructions provided in the [configure your chain](/builders/chain-operators/tools/op-deployer#init-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:

```bash
forge script scripts/Deploy.s.sol:Deploy --private-key $GS_ADMIN_PRIVATE_KEY --broadcast --rpc-url $L1_RPC_URL --slow
./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.

<Callout>
If you see a nondescript error that includes `EvmError: Revert` and `Script failed` then you likely need to change the `IMPL_SALT` environment variable.
This variable determines the addresses of various smart contracts that are deployed via [CREATE2](https://eips.ethereum.org/EIPS/eip-1014).
If the same `IMPL_SALT` is used to deploy the same contracts twice, the second deployment will fail.
**You can generate a new `IMPL_SALT` by running `direnv allow` anywhere in the Optimism Monorepo.**
</Callout>
### 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.

</Steps>

## Generate the L2 config files

Now that you've set up the L1 smart contracts you can automatically generate several configuration files that are used within the Consensus Client and the Execution Client.
Now that you've set up the L1 smart contracts you can automatically generate several configuration files that are used within the consensus client and the execution client.

You need to generate three important files:
You need to generate two important files:

1. `genesis.json` includes the genesis state of the chain for the Execution Client.
2. `rollup.json` includes configuration information for the Consensus Client.
3. `jwt.txt` is a [JSON Web Token](https://jwt.io/introduction) that allows the Consensus Client and the Execution Client to communicate securely (the same mechanism is used in Ethereum clients).

<Steps>

{<h3>Navigate to the op-node package</h3>}

```bash
cd ~/optimism/op-node
```
{<h3>Install op-deployer</h3>}

{<h3>Create genesis files</h3>}

Now you'll generate the `genesis.json` and `rollup.json` files within the `op-node` folder:

```bash
go run cmd/main.go genesis l2 \
--deploy-config ../packages/contracts-bedrock/deploy-config/getting-started.json \
--l1-deployments ../packages/contracts-bedrock/deployments/getting-started/.deploy \
--outfile.l2 genesis.json \
--outfile.rollup rollup.json \
--l1-rpc $L1_RPC_URL
```
Ensure you have the `op-deployer` tool installed.
For installation instructions, see the [op-deployer installation section](/builders/chain-operators/tools/op-deployer#installation).

{<h3>Create an authentication key</h3>}
{<h3>Generate configuration files</h3>}

Next you'll create a [JSON Web Token](https://jwt.io/introduction) that will be used to authenticate the Consensus Client and the Execution Client.
This token is used to ensure that only the Consensus Client and the Execution Client can communicate with each other.
You can generate a JWT with the following command:
With the contracts deployed, generate the genesis and rollup configuration files by running the following commands:

```bash
openssl rand -hex 32 > jwt.txt
op-deployer inspect genesis --workdir .deployer <l2-chain-id> > .deployer/genesis.json
op-deployer inspect rollup --workdir .deployer <l2-chain-id> > .deployer/rollup.json
```
Replace `<l2-chain-id>` with the L2 chain ID.

{<h3>Copy genesis files into the op-geth directory</h3>}
{<h3>Get data</h3>}

Finally, you'll need to copy the `genesis.json` file and `jwt.txt` file into `op-geth` so you can use it to initialize and run `op-geth`:
Now that you have your `genesis.json` and `rollup.json`
you can use the following inspect subcommands to get additional data:

```bash
cp genesis.json ~/op-geth
cp jwt.txt ~/op-geth
op-deployer inspect l1 --workdir .deployer <l2-chain-id> # outputs all L1 contract addresses for an L2 chain
op-deployer inspect deploy-config --workdir .deployer <l2-chain-id> # outputs the deploy config for an L2 chain
```

</Steps>
Expand Down
5 changes: 1 addition & 4 deletions words.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,7 @@ DISABLETXPOOLGOSSIP
disabletxpoolgossip
Discv
discv
disincentivize
DIVU
Drand
dripcheck
Expand Down Expand Up @@ -122,7 +123,6 @@ Farcaster
Faultproof
FDLIMIT
fdlimit
featureset
Flashblocks
Flashbots
forkable
Expand Down Expand Up @@ -281,7 +281,6 @@ pprof
Precommitments
precommitments
preconfigured
Preconfigured
predeploy
Predeployed
predeployed
Expand Down Expand Up @@ -377,7 +376,6 @@ Superchain
superchain
Superchain's
Superchainerc
superchainerc
Superchains
Superscan
Supersim
Expand Down Expand Up @@ -410,7 +408,6 @@ unmetered
Unprotect
unsubmitted
UPNP
usafe
VERKLE
verkle
VHOSTS
Expand Down