From d38582f1c1d88ed6802a03fee6440f609f170bb7 Mon Sep 17 00:00:00 2001 From: Matthew Slipper Date: Mon, 23 Sep 2024 00:54:52 -0600 Subject: [PATCH] Add tutorial for devnet --- .../chain-operators/tutorials/_meta.json | 2 +- .../tutorials/create-l2-rollup.mdx | 812 +++--------------- 2 files changed, 127 insertions(+), 687 deletions(-) diff --git a/pages/builders/chain-operators/tutorials/_meta.json b/pages/builders/chain-operators/tutorials/_meta.json index 465ec6d7b..54daf18e0 100644 --- a/pages/builders/chain-operators/tutorials/_meta.json +++ b/pages/builders/chain-operators/tutorials/_meta.json @@ -1,5 +1,5 @@ { - "create-l2-rollup": "Creating Your Own L2 Rollup Testnet", + "create-l2-rollup": "Creating Your Own L2 Rollup Devnet", "sdk": "Using the Optimism SDK", "adding-derivation-attributes": "Adding Attributes to the Derivation Function", "adding-precompiles": "Adding a Precompile", diff --git a/pages/builders/chain-operators/tutorials/create-l2-rollup.mdx b/pages/builders/chain-operators/tutorials/create-l2-rollup.mdx index 80396150e..500484aa8 100644 --- a/pages/builders/chain-operators/tutorials/create-l2-rollup.mdx +++ b/pages/builders/chain-operators/tutorials/create-l2-rollup.mdx @@ -1,744 +1,183 @@ --- -title: Creating Your Own L2 Rollup Testnet +title: Creating Your Own L2 Rollup Devnet lang: en-US -description: This tutorial walks you through spinning up an OP Stack testnet chain. +description: This tutorial walks you through spinning up an OP Stack devnet chain. --- -import { Callout, Steps } from 'nextra/components' -import { WipCallout } from '@/components/WipCallout' - - -# Creating Your Own L2 Rollup Testnet - +import {Callout, Steps} from 'nextra/components' +import {WipCallout} from '@/components/WipCallout' +# Creating Your Own L2 Rollup Devnet -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. + This guide is currently under active development. If you run into any issues, please open an issue on + [Github](https://github.com/ethereum-optimism/optimism). -This tutorial is **designed for developers** who want to learn about the OP Stack by spinning up an OP Stack testnet chain. -You'll walk through the full deployment process and teach you all of the components that make up the OP Stack, and **you'll end up with your very own OP Stack testnet**. +This tutorial is **designed for developers** who want to learn about the OP Stack by spinning up a local OP Stack devnet. +You'll perform the full deployment process, and **you'll end up with your very own OP Stack devnet**. It's useful to understand what each of these components does before you start deploying your chain. To learn about the different components please -read the [deployment overview page](/builders/chain-operators/deploy/overview). +read the [deployment overview page](/builders/chain-operators/deploy/overview). -You can use this testnet to experiment and perform tests, or you can choose to modify the chain to adapt it to your own needs. -**The OP Stack is free and open source software licensed entirely under the MIT license**. -You don't need permission from anyone to modify or deploy the stack in any configuration you want. +You can use this devnet to experiment and perform tests, or you can choose to modify the chain to adapt it to your own needs. +**The OP Stack is free and open source software licensed entirely under the MIT license**. You don't need permission from +anyone to modify or deploy the stack in any configuration you want. -Modifications to the OP Stack may prevent a chain from being able to benefit from aspects of the [Optimism Superchain](/stack/explainer). -Make sure to check out the [Superchain Explainer](/stack/explainer) to learn more. + Modifications to the OP Stack may prevent a chain from being able to benefit from aspects of the [Optimism + Superchain](/stack/explainer). Make sure to check out the [Superchain Explainer](/stack/explainer) to learn more. -## Software Dependencies +## Installing Dependencies | Dependency | Version | Version Check Command | | ------------------------------------------------------------- | -------- | --------------------- | -| [git](https://git-scm.com/) | `^2` | `git --version` | -| [go](https://go.dev/) | `^1.21` | `go version` | -| [node](https://nodejs.org/en/) | `^20` | `node --version` | -| [pnpm](https://pnpm.io/installation) | `^8` | `pnpm --version` | -| [foundry](https://github.com/foundry-rs/foundry#installation) | `^0.2.0` | `forge --version` | -| [make](https://linux.die.net/man/1/make) | `^3` | `make --version` | -| [jq](https://github.com/jqlang/jq) | `^1.6` | `jq --version` | -| [direnv](https://direnv.net) | `^2` | `direnv --version` | +| [docker](https://docs.docker.com/engine/install/) | `^27` | `docker --version` | +| [kurtosis](https://docs.kurtosis.com/install/) | `^1.3.0` | `kurtosis version` | ### Notes on Specific Dependencies -#### `node` - -We recommend using the latest LTS version of Node.js (currently v20). -[`nvm`](https://github.com/nvm-sh/nvm) is a useful tool that can help you manage multiple versions of Node.js on your machine. -You may experience unexpected errors on older versions of Node.js. - -#### `foundry` - -It's recommended to use the scripts in the monorepo's `package.json` for managing `foundry` to ensure you're always working with the correct version. This approach simplifies the installation, update, and version checking process. Make sure to clone the monorepo locally before proceeding. -#### `direnv` - -Parts of this tutorial use [`direnv`](https://direnv.net) as a way of loading environment variables from `.envrc` files into your shell. -This means you won't have to manually export environment variables every time you want to use them. -`direnv` only ever has access to files that you explicitly allow it to see. - -After [installing `direnv`](https://direnv.net/docs/installation.html), you will need to **make sure that [`direnv` is hooked into your shell](https://direnv.net/docs/hook.html)**. -Make sure you've followed [the guide on the `direnv` website](https://direnv.net/docs/hook.html), then **close your terminal and reopen it** so that the changes take effect (or `source` your config file if you know how to do that). - - -Make sure that you have correctly hooked `direnv` into your shell by modifying your shell configuration file (like `~/.bashrc` or `~/.zshrc`). -If you haven't edited a config file then you probably haven't configured `direnv` properly (and things might not work later). - - -## Get Access to a Sepolia Node - -You'll be deploying a OP Stack Rollup chain that uses a Layer 1 blockchain to host and order transaction data. -The OP Stack Rollups were designed to use EVM Equivalent blockchains like Ethereum, OP Mainnet, or standard Ethereum testnets as their L1 chains. - -**This guide uses the Sepolia testnet as an L1 chain**. -We recommend that you also use Sepolia. -You can also use other EVM-compatible blockchains, but you may run into unexpected errors. -If you want to use an alternative network, make sure to carefully review each command and replace any Sepolia-specific values with the values for your network. - -Since you're deploying your OP Stack chain to Sepolia, you'll need to have access to a Sepolia node. -You can either use a node provider like [Alchemy](https://www.alchemy.com/) (easier) or run your own Sepolia node (harder). - -## Build the Source Code - -You're going to be spinning up your OP Stack chain directly from source code instead of using a container system like [Docker](https://www.docker.com/). -Although this adds a few extra steps, it means you'll have an easier time modifying the behavior of the stack if you'd like to do so. -If you want a summary of the various components you'll be using, take another look at the [What You're Going to Deploy](#what-youre-going-to-deploy) section above. - - -You're using the home directory `~/` as the work directory for this tutorial for simplicity. -You can use any directory you'd like but using the home directory will allow you to copy/paste the commands in this guide. -If you choose to use a different directory, make sure you're using the correct directory in the commands throughout this tutorial. - - -### Build the Optimism Monorepo +#### `docker` - +We recommend using the latest version of Docker on Linux, or [OrbStack](https://orbstack.dev/) (a drop-in replacement +for Docker Desktop) on OSX. -{

Clone the Optimism Monorepo

} +#### `kurtosis` -```bash -cd ~ -git clone https://github.com/ethereum-optimism/optimism.git -``` - -{

Enter the Optimism Monorepo

} - -```bash -cd optimism -``` - -{

Check out the correct branch

} - - -You will be using the `tutorials/chain` branch of the Optimism Monorepo to deploy an OP Stack testnet chain during this tutorial. -This is a non-production branch that lags behind the `develop` branch. -You should **NEVER** use the `develop` or `tutorials/chain` branches in production. - - -```bash -git checkout tutorials/chain -``` - -{

Check your dependencies

} - - -Don't skip this step! Make sure you have all of the required dependencies installed before continuing. - - -Run the following script and double check that you have all of the required versions installed. -If you don't have the correct versions installed, you may run into unexpected errors. - -```bash -./packages/contracts-bedrock/scripts/getting-started/versions.sh -``` - -{

Install dependencies

} - -```bash -pnpm install -``` - -{

Build the various packages inside of the Optimism Monorepo

} - -```bash -make op-node op-batcher op-proposer -pnpm build -``` - - - -### Build `op-geth` - - - -{

Clone op-geth

} - -```bash -cd ~ -git clone https://github.com/ethereum-optimism/op-geth.git -``` - -{

Enter op-geth

} - -```bash -cd op-geth -``` - -{

Build op-geth

} - -```bash -make geth -``` - - - -## Fill Out Environment Variables - -You'll need to fill out a few environment variables before you can start deploying your chain. - - - -{

Enter the Optimism Monorepo

} - -```bash -cd ~/optimism -``` - -{

Duplicate the sample environment variable file

} - -```bash -cp .envrc.example .envrc -``` - -{

Fill out the environment variable file

} - -Open up the environment variable file and fill out the following variables: - -| Variable Name | Description | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `L1_RPC_URL` | URL for your L1 node (a Sepolia node in this case). | -| `L1_RPC_KIND` | Kind of L1 RPC you're connecting to, used to inform optimal transactions receipts fetching. Valid options: `alchemy`, `quicknode`, `infura`, `parity`, `nethermind`, `debug_geth`, `erigon`, `basic`, `any`. | - - - -## Generate Addresses - -You'll need four addresses and their private keys when setting up the chain: - -* The `Admin` address has the ability to upgrade contracts. -* The `Batcher` address publishes Sequencer transaction data to L1. -* The `Proposer` address publishes L2 transaction results (state roots) to L1. -* The `Sequencer` address signs blocks on the p2p network. - - - -{

Enter the Optimism Monorepo

} - -```bash -cd ~/optimism -``` - -{

Generate new addresses

} - - -You should **not** use the `wallets.sh` tool for production deployments. -If you are deploying an OP Stack based chain into production, you should likely be using a combination of hardware security modules and hardware wallets. - - -```bash -./packages/contracts-bedrock/scripts/getting-started/wallets.sh -``` - -{

Check the output

} - -Make sure that you see output that looks something like the following: - -```text -Copy the following into your .envrc file: - -# Admin address -export GS_ADMIN_ADDRESS=0x9625B9aF7C42b4Ab7f2C437dbc4ee749d52E19FC -export GS_ADMIN_PRIVATE_KEY=0xbb93a75f64c57c6f464fd259ea37c2d4694110df57b2e293db8226a502b30a34 - -# Batcher address -export GS_BATCHER_ADDRESS=0xa1AEF4C07AB21E39c37F05466b872094edcf9cB1 -export GS_BATCHER_PRIVATE_KEY=0xe4d9cd91a3e53853b7ea0dad275efdb5173666720b1100866fb2d89757ca9c5a - -# Proposer address -export GS_PROPOSER_ADDRESS=0x40E805e252D0Ee3D587b68736544dEfB419F351b -export GS_PROPOSER_PRIVATE_KEY=0x2d1f265683ebe37d960c67df03a378f79a7859038c6d634a61e40776d561f8a2 - -# Sequencer address -export GS_SEQUENCER_ADDRESS=0xC06566E8Ec6cF81B4B26376880dB620d83d50Dfb -export GS_SEQUENCER_PRIVATE_KEY=0x2a0290473f3838dbd083a5e17783e3cc33c905539c0121f9c76614dda8a38dca -``` - -{

Save the addresses

} - -Copy the output from the previous step and paste it into your `.envrc` file as directed. - -{

Fund the addresses

} - -**You will need to send ETH to the `Admin`, `Proposer`, and `Batcher` addresses.** -The exact amount of ETH required depends on the L1 network being used. -**You do not need to send any ETH to the `Sequencer` address as it does not send transactions.** - -It's recommended to fund the addresses with the following amounts when using Sepolia: - -* `Admin` — 0.5 Sepolia ETH -* `Proposer` — 0.2 Sepolia ETH -* `Batcher` — 0.1 Sepolia ETH - -**To get the required Sepolia ETH to fund the addresses, we recommend using the [Superchain Faucet](https://console.optimism.io/faucet?utm_source=docs)** together with [Coinbase verification](https://help.coinbase.com/en/coinbase/getting-started/getting-started-with-coinbase/id-doc-verification). - - - -## Load Environment variables - -Now that you've filled out the environment variable file, you need to load those variables into your terminal. - - - -{

Enter the Optimism Monorepo

} - -```bash -cd ~/optimism -``` - -{

Load the variables with direnv

} - - -You're about to use `direnv` to load environment variables from the `.envrc` file into your terminal. -Make sure that you've [installed `direnv`](https://direnv.net/docs/installation.html) and that you've properly [hooked `direnv` into your shell](#configuring-direnv). - - -Next you'll need to allow `direnv` to read this file and load the variables into your terminal using the following command. - -```bash -direnv allow -``` - - -WARNING: `direnv` will unload itself whenever your `.envrc` file changes. -**You *must* rerun the following command every time you change the `.envrc` file.** - - -{

Confirm that the variables were loaded

} - -After running `direnv allow` you should see output that looks something like the following (the exact output will vary depending on the variables you've set, don't worry if it doesn't look exactly like this): - -```bash -direnv: loading ~/optimism/.envrc -direnv: export +DEPLOYMENT_CONTEXT +ETHERSCAN_API_KEY +GS_ADMIN_ADDRESS +GS_ADMIN_PRIVATE_KEY +GS_BATCHER_ADDRESS +GS_BATCHER_PRIVATE_KEY +GS_PROPOSER_ADDRESS +GS_PROPOSER_PRIVATE_KEY +GS_SEQUENCER_ADDRESS +GS_SEQUENCER_PRIVATE_KEY +IMPL_SALT +L1_RPC_KIND +L1_RPC_URL +PRIVATE_KEY +TENDERLY_PROJECT +TENDERLY_USERNAME -``` - -**If you don't see this output, you likely haven't [properly configured `direnv`](#configuring-direnv).** -Make sure you've configured `direnv` properly and run `direnv allow` again so that you see the desired output. - - +Kurtosis is a tool for packaging and deploying containerized services. It's used in this tutorial to automatically deploy +your devnet in an isolated environment. ## Configure your network -Once you've built both repositories, you'll need to head back to the Optimism Monorepo to set up the configuration file for your chain. -Currently, chain configuration lives inside of the [`contracts-bedrock`](https://github.com/ethereum-optimism/optimism/tree/v1.1.4/packages/contracts-bedrock) package in the form of a JSON file. - - +Now that you've installed all the necessary dependencies, you can start configuring your network. The Kurtosis package +accepts a YAMl file which configures how many network participants there are, what kind of software they're running, and +the network's topology. An example YAML file is below: + +```yaml +optimism_package: + chains: # you can define multiple L2s, which will be deployed against the same L1 as a single Superchain + - participants: # each participant is a node in the network. here we've defined two, one running op-geth and one running op-reth + - el_type: op-geth + sequencer: true # this node will be the sequencer + - el_type: op-reth + network_params: + name: rollup-1 # can be anything as long as it is unique + chain_id: 12345 # can be anything as long as it is unique + op_contract_deployer_params: # configures the contract versions to deploy + image: mslipper/op-deployer:latest + artifacts_url: https://storage.googleapis.com/oplabs-contract-artifacts/artifacts-v1-4accd01f0c35c26f24d2aa71aba898dd7e5085a2ce5daadc8a84b10caf113409.tar.gz +``` + +Save the above configuration to a file. For the rest of this tutorial, we'll assume you've saved it to `network-config.yaml`. -{

Enter the Optimism Monorepo

} +## Start your network + +Now that you've configured your network, you can start it up using the Kurtosis CLI. Run the command below: ```bash -cd ~/optimism +kurtosis run github.com/ethpandaops/ethereum-package --args-file ./network-config.yml ``` -{

Move into the contracts-bedrock package

} +This command will start up your network and deploy the OP Stack based on the configuration you created. The command will +produce a lot of output and will take about five minutes to complete. Once it's done, you'll see a message that looks like +the one below: -```bash -cd packages/contracts-bedrock ``` +INFO[2024-09-23T00:31:29-06:00] =================================================== +INFO[2024-09-23T00:31:29-06:00] || Created enclave: blue-marsh || +INFO[2024-09-23T00:31:29-06:00] =================================================== +Name: blue-marsh +UUID: 91af529557cb +Status: RUNNING +Creation Time: Mon, 23 Sep 2024 00:29:58 MDT +Flags: -{

Generate the configuration file

} - -Run the following script to generate the `getting-started.json` configuration file inside of the `deploy-config` directory. +========================================= Files Artifacts ========================================= +UUID Name +a5824b041b28 1-lighthouse-geth-0-63-0 +f7c0e13e9871 el_cl_genesis_data +bfa022049aea final-genesis-timestamp +0b5c53e3940f genesis-el-cl-env-file +46a78cc34966 genesis_validators_root +038ad1a753ed jwt_file +4fbc4bde03c2 keymanager_file +c36887606978 op-deployer-configs +d638c3222e56 op-deployer-fund-script +b02f20c287ac op_jwt_filerollup-1 +655d57862785 prysm-password +28203054f5ec validator-ranges -```bash -./scripts/getting-started/config.sh +========================================== User Services ========================================== +UUID Name Ports Status +29643e475cb7 cl-1-lighthouse-geth http: 4000/tcp -> http://127.0.0.1:33639 RUNNING + metrics: 5054/tcp -> http://127.0.0.1:33640 + tcp-discovery: 9000/tcp -> 127.0.0.1:33641 + udp-discovery: 9000/udp -> 127.0.0.1:32920 +e7dfdc2588ae el-1-geth-lighthouse engine-rpc: 8551/tcp -> 127.0.0.1:33636 RUNNING + metrics: 9001/tcp -> http://127.0.0.1:33637 + rpc: 8545/tcp -> 127.0.0.1:33634 + tcp-discovery: 30303/tcp -> 127.0.0.1:33638 + udp-discovery: 30303/udp -> 127.0.0.1:32919 + ws: 8546/tcp -> 127.0.0.1:33635 +5ff43094ccc3 op-batcher-rollup-1 http: 8548/tcp -> http://127.0.0.1:33650 RUNNING +aa30d376acc9 op-cl-1-op-node-op-geth-rollup-1 http: 8547/tcp -> http://127.0.0.1:33648 RUNNING + tcp-discovery: 9003/tcp -> 127.0.0.1:33649 + udp-discovery: 9003/udp -> 127.0.0.1:32922 +af4abdbbe939 op-el-1-op-geth-op-node-rollup-1 engine-rpc: 8551/tcp -> 127.0.0.1:33645 RUNNING + metrics: 9001/tcp -> 127.0.0.1:33646 + rpc: 8545/tcp -> http://127.0.0.1:33643 + tcp-discovery: 30303/tcp -> 127.0.0.1:33647 + udp-discovery: 30303/udp -> 127.0.0.1:32921 + ws: 8546/tcp -> 127.0.0.1:33644 +578ee2b5bfe7 validator-key-generation-cl-validator-keystore RUNNING +aa69f73e96c1 vc-1-geth-lighthouse metrics: 8080/tcp -> http://127.0.0.1:33642 RUNNING ``` -{

Review the configuration file (Optional)

} +Also take note of the last log line above this message, which contains the address of the standard bridge. You'll +need this address to deposit funds on your L2. -If you'd like, you can review the configuration file that was just generated by opening up `deploy-config/getting-started.json` in your favorite text editor. -It's recommended to keep this file as-is for now so you don't run into any unexpected errors. +This might look complicated, but it's just a list of the services that were started up by Kurtosis. For each service, you +can see: - +- The enclave name, which identifies the services you just deployed within Kurtosis. The enclave is an isolated environment +that runs your devnet. +- The service's name, which you can use with the Kurtosis CLI to view its logs and interact with it. +- The service's ports and addresses, which you can use to connect to the service. -## Deploy the Create2 Factory (Optional) +At this point your chain is up and running. Let's move on to the next section to learn how to interact with it. -If you're deploying an OP Stack chain to a network other than Sepolia, you may need to deploy a Create2 factory contract to the L1 chain. -This factory contract is used to deploy OP Stack smart contracts in a deterministic fashion. +## Interact with your network - -This step is typically only necessary if you are deploying your OP Stack chain to custom L1 chain. -If you are deploying your OP Stack chain to Sepolia, you can safely skip this step. - +You now have a fully functioning OP Stack Rollup. You can connect your wallet to this chain the same way you'd connect +your wallet to any other EVM chain. You can find your node's RPC URL by running `kurtosis enclave inspect `. +Your enclave name is outputted at the end of the `kurtosis run` command above. The RPC url is the `rpc` port name in any +of the execution client services identified by `op-el`. - +### Depositing funds onto your network -{

Check if the factory exists

} +Your network was configured to pre-fund development addresses using the `test test test test test test test test test test test junk` +mnemonic. To get ETH onto your L2, you import one of the private keys from that mnemonic into your favorite wallet or use +a CLI tool like `cast`. For the purposes of this tutorial, we'll use `cast` and assume you want to use the first address +generated by that mnemonic. -The Create2 factory contract will be deployed at the address `0x4e59b44847b379578588920cA78FbF26c0B4956C`. -You can check if this contract has already been deployed to your L1 network with a block explorer or by running the following command: +To move ETH onto your L2, run the following command. Make sure to replace the values in angle brackets with real values: ```bash -cast codesize 0x4e59b44847b379578588920cA78FbF26c0B4956C --rpc-url $L1_RPC_URL +cast send --mnemonic 'test test test test test test test test test test test junk' --mnemonic-path "m/44'/60'/0'/0/0" \ + --to "" --amount "eth" --rpc-url "http://127.0.0.1:" ``` -If the command returns `0` then the contract has not been deployed yet. -If the command returns `69` then the contract has been deployed and you can safely skip this section. - -{

Fund the factory deployer

} - -You will need to send some ETH to the address that will be used to deploy the factory contract, `0x3fAB184622Dc19b6109349B94811493BF2a45362`. -This address can only be used to deploy the factory contract and will not be used for anything else. -Send at least 1 ETH to this address on your L1 chain. - -{

Deploy the factory

} - -Using `cast`, deploy the factory contract to your L1 chain: +Wait ~30 seconds, then check your balance on L2 by running the following command: ```bash -cast publish --rpc-url $L1_RPC_URL 0xf8a58085174876e800830186a08080b853604580600e600039806000f350fe7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf31ba02222222222222222222222222222222222222222222222222222222222222222a02222222222222222222222222222222222222222222222222222222222222222 +export ETH_RPC_URL="http://127.0.0.1:" +export ADDRESS="0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" +cast balance "$ADDRESS" ``` -{

Wait for the transaction to be mined

} - -Make sure that the transaction is included in a block on your L1 chain before continuing. - -{

Verify that the factory was deployed

} - -Run the code size check again to make sure that the factory was properly deployed: - -```bash -cast codesize 0x4e59b44847b379578588920cA78FbF26c0B4956C --rpc-url $L1_RPC_URL -``` - - - -## Deploy the L1 contracts - -Once you've configured your network, it's time to deploy the L1 contracts necessary for the functionality of the chain. - - - -{

Deploy the L1 contracts

} - -```bash -forge script scripts/Deploy.s.sol:Deploy --private-key $GS_ADMIN_PRIVATE_KEY --broadcast --rpc-url $L1_RPC_URL --slow -``` - - -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.** - - - - -## 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. - -You need to generate three 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). - - - -{

Navigate to the op-node package

} - -```bash -cd ~/optimism/op-node -``` - -{

Create genesis files

} - -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 -``` - -{

Create an authentication key

} - -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: - -```bash -openssl rand -hex 32 > jwt.txt -``` - -{

Copy genesis files into the op-geth directory

} - -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`: - -```bash -cp genesis.json ~/op-geth -cp jwt.txt ~/op-geth -``` - - - -## Initialize `op-geth` - -You're almost ready to run your chain! -Now you just need to run a few commands to initialize `op-geth`. -You're going to be running a Sequencer node, so you'll need to import the `Sequencer` private key that you generated earlier. -This private key is what your Sequencer will use to sign new blocks. - - - -{

Navigate to the op-geth directory

} - -```bash -cd ~/op-geth -``` - -{

Create a data directory folder

} - -```bash -mkdir datadir -``` - -{

Initialize op-geth

} - -```bash -build/bin/geth init --datadir=datadir genesis.json -``` - - - -## Start `op-geth` - -Now you'll start `op-geth`, your Execution Client. -Note that you won't start seeing any transactions until you start the Consensus Client in the next step. - - - -{

Open up a new terminal

} - -You'll need a terminal window to run `op-geth` in. - -{

Navigate to the op-geth directory

} - -```bash -cd ~/op-geth -``` - -{

Run op-geth

} - - -You're using `--gcmode=archive` to run `op-geth` here because this node will act as your Sequencer. -It's useful to run the Sequencer in archive mode because the `op-proposer` requires access to the full state. -Feel free to run other (non-Sequencer) nodes in full mode if you'd like to save disk space. Just make sure at least one other archive node exists and the `op-proposer` points to it. - - - -It's important that you've already initialized the geth node at this point as per the previous section. Failure to do this will cause startup issues between `op-geth` and `op-node`. - - -```bash -./build/bin/geth \ - --datadir ./datadir \ - --http \ - --http.corsdomain="*" \ - --http.vhosts="*" \ - --http.addr=0.0.0.0 \ - --http.api=web3,debug,eth,txpool,net,engine \ - --ws \ - --ws.addr=0.0.0.0 \ - --ws.port=8546 \ - --ws.origins="*" \ - --ws.api=debug,eth,txpool,net,engine \ - --syncmode=full \ - --gcmode=archive \ - --nodiscover \ - --maxpeers=0 \ - --networkid=42069 \ - --authrpc.vhosts="*" \ - --authrpc.addr=0.0.0.0 \ - --authrpc.port=8551 \ - --authrpc.jwtsecret=./jwt.txt \ - --rollup.disabletxpoolgossip=true -``` - - - -## Start `op-node` - -Once you've got `op-geth` running you'll need to run `op-node`. -Like Ethereum, the OP Stack has a Consensus Client (`op-node`) and an Execution Client (`op-geth`). -The Consensus Client "drives" the Execution Client over the Engine API. - - - -{

Open up a new terminal

} - -You'll need a terminal window to run the `op-node` in. - -{

Navigate to the op-node directory

} - -```bash -cd ~/optimism/op-node -``` - -{

Run op-node

} - -```bash -./bin/op-node \ - --l2=http://localhost:8551 \ - --l2.jwt-secret=./jwt.txt \ - --sequencer.enabled \ - --sequencer.l1-confs=5 \ - --verifier.l1-confs=4 \ - --rollup.config=./rollup.json \ - --rpc.addr=0.0.0.0 \ - --p2p.disable \ - --rpc.enable-admin \ - --p2p.sequencer.key=$GS_SEQUENCER_PRIVATE_KEY \ - --l1=$L1_RPC_URL \ - --l1.rpckind=$L1_RPC_KIND -``` - -Once you run this command, you should start seeing the `op-node` begin to sync L2 blocks from the L1 chain. -Once the `op-node` has caught up to the tip of the L1 chain, it'll begin to send blocks to `op-geth` for execution. -At that point, you'll start to see blocks being created inside of `op-geth`. - - -**By default, your `op-node` will try to use a peer-to-peer to speed up the synchronization process.** -If you're using a chain ID that is also being used by others, like the default chain ID for this tutorial (42069), your `op-node` will receive blocks signed by other sequencers. -These requests will fail and waste time and network resources. -**To avoid this, this tutorial starts with peer-to-peer synchronization disabled (`--p2p.disable`).** - -Once you have multiple nodes, you may want to enable peer-to-peer synchronization. -You can add the following options to the `op-node` command to enable peer-to-peer synchronization with specific nodes: - -``` - --p2p.static= \ - --p2p.listen.ip=0.0.0.0 \ - --p2p.listen.tcp=9003 \ - --p2p.listen.udp=9003 \ -``` - -You can alternatively also remove the [--p2p.static](/builders/node-operators/configuration/consensus-config#p2pstatic) option, but you may see failed requests from other chains using the same chain ID. - - - - -## Start `op-batcher` - -The `op-batcher` takes transactions from the Sequencer and publishes those transactions to L1. -Once these Sequencer transactions are included in a finalized L1 block, they're officially part of the canonical chain. -The `op-batcher` is critical! - -It's best to give the `Batcher` address at least 1 Sepolia ETH to ensure that it can continue operating without running out of ETH for gas. -Keep an eye on the balance of the `Batcher` address because it can expend ETH quickly if there are a lot of transactions to publish. - - - -{

Open up a new terminal

} - -You'll need a terminal window to run the `op-batcher` in. - -{

Navigate to the op-batcher directory

} - -```bash -cd ~/optimism/op-batcher -``` - -{

Run op-batcher

} - -```bash -./bin/op-batcher \ - --l2-eth-rpc=http://localhost:8545 \ - --rollup-rpc=http://localhost:9545 \ - --poll-interval=1s \ - --sub-safety-margin=6 \ - --num-confirmations=1 \ - --safe-abort-nonce-too-low-count=3 \ - --resubmission-timeout=30s \ - --rpc.addr=0.0.0.0 \ - --rpc.port=8548 \ - --rpc.enable-admin \ - --max-channel-duration=25 \ - --l1-eth-rpc=$L1_RPC_URL \ - --private-key=$GS_BATCHER_PRIVATE_KEY -``` - - -The [`--max-channel-duration=n`](/builders/chain-operators/configuration/batcher#set-your--op_batcher_max_channel_duration) setting tells the batcher to write all the data to L1 every `n` L1 blocks. -When it is low, transactions are written to L1 frequently and other nodes can synchronize from L1 quickly. -When it is high, transactions are written to L1 less frequently and the batcher spends less ETH. -If you want to reduce costs, either set this value to 0 to disable it or increase it to a higher value. - - - - -## Start `op-proposer` - -Now start `op-proposer`, which proposes new state roots. - - - -{

Open up a new terminal

} - -You'll need a terminal window to run the `op-proposer` in. - -{

Navigate to the op-proposer directory

} - -```bash -cd ~/optimism/op-proposer -``` - -{

Run op-proposer

} - -```bash -./bin/op-proposer \ - --poll-interval=12s \ - --rpc.port=8560 \ - --rollup-rpc=http://localhost:9545 \ - --l2oo-address=$(cat ../packages/contracts-bedrock/deployments/getting-started/.deploy | jq -r .L2OutputOracleProxy) \ - --private-key=$GS_PROPOSER_PRIVATE_KEY \ - --l1-eth-rpc=$L1_RPC_URL -``` - - - -## Connect Your Wallet to Your Chain - -You now have a fully functioning OP Stack Rollup with a Sequencer node running on `http://localhost:8545`. -You can connect your wallet to this chain the same way you'd connect your wallet to any other EVM chain. -If you need an easy way to connect to your chain, just [click here](https://chainid.link?network=opstack-getting-started). - -## Get ETH On Your Chain - -Once you've connected your wallet, you'll probably notice that you don't have any ETH to pay for gas on your chain. -The easiest way to deposit Sepolia ETH into your chain is to send ETH directly to the `L1StandardBridge` contract. - - - -{

Navigate to the contracts-bedrock directory

} - -```bash -cd ~/optimism/packages/contracts-bedrock -``` - -{

Get the address of the L1StandardBridgeProxy contract

} - -```bash -cat deployments/getting-started/.deploy | jq -r .L1StandardBridgeProxy -``` - -{

Send some Sepolia ETH to the L1StandardBridgeProxy contract

} - -Grab the L1 bridge proxy contract address and, using the wallet that you want to have ETH on your Rollup, send that address a small amount of ETH on Sepolia (0.1 or less is fine). -This will trigger a deposit that will mint ETH into your wallet on L2. -It may take up to 5 minutes for that ETH to appear in your wallet on L2. - - +Your balance should match the amount you sent. ## See Your Rollup in Action @@ -749,4 +188,5 @@ Send some transactions, deploy some contracts, and see what happens! * You can [modify the blockchain in various ways](../hacks/overview). * Check out the [protocol specs](https://specs.optimism.io/) for more detail about the rollup protocol. -* If you run into any problems, please visit the [Chain Operators Troubleshooting Guide](../management/troubleshooting) for help. +* If you run into any problems, please visit the [Chain Operators Troubleshooting Guide](../management/troubleshooting) + or [file an issue](https://github.com/ethereum-optimism/optimism/issues) for help.