From 215920f995c20e0c330f0ab9a9d1cb9f3335db67 Mon Sep 17 00:00:00 2001 From: soyboy Date: Mon, 17 Nov 2025 12:20:25 -0800 Subject: [PATCH 1/2] starting to refactor the deployment section --- chain-operators/deployment-guide.mdx | 51 ++++++++++++ chain-operators/guides/deployment/genesis.mdx | 14 +--- .../guides/deployment/overview.mdx | 36 ++------- .../guides/deployment/sequencer-node.mdx | 17 ++-- .../guides/deployment/smart-contracts.mdx | 47 +++-------- .../guides/deployment/validate-deployment.mdx | 29 ++----- chain-operators/tools/op-deployer.mdx | 79 ++++++++++--------- chain-operators/tools/op-validator.mdx | 6 +- docs.json | 3 +- 9 files changed, 130 insertions(+), 152 deletions(-) create mode 100644 chain-operators/deployment-guide.mdx diff --git a/chain-operators/deployment-guide.mdx b/chain-operators/deployment-guide.mdx new file mode 100644 index 000000000..22051b56c --- /dev/null +++ b/chain-operators/deployment-guide.mdx @@ -0,0 +1,51 @@ +--- +title: Deployment +description: Learn about the high level steps on how to deploy an OP Stack chain. +--- + +The OP Stack is an open-source, modular, Ethereum Layer 2 rollup stack. +This guide will walk you through the high level steps on how to deploy an OP Stack chain. + +## Components + +First we'll start with the components that come together to create your Layer 2 blockchain: + +todo: determine if we want collapseable components to make this more compact + +- **Smart contracts**: The OP Stack uses a set of smart contracts on Ethereum to bridge between the L1 and L2 domains and manage aspects of the rollup. +- **Sequencer**: The OP Stack relies on a sequencer node to build the canonical layer 2 blocks. The sequencer (and all replica) nodes consist of a consensus client and execution client. They are responsible for determining maintaining the consensus rules around, executing transactions, and maintaing the state of the blockchain. Optimism maintains the `op-node` and `op-geth`; however, there are alternative clients available from other cleint teams like `reth`, `nethermind`, and a handful of others. +- **Batcher**: The batcher is a service that publishes transactions made directly to the sequencer onto Ethereum. Using Ethereum as a data availability layer, the OP Stack inherits Ethereum's security properties by allowing anyone to derive the state of the L2 blockchain from L1. +- **Proposer**: The proposer is a service responsible for publishing the L2 state root to Ethereum. This enables cross-chain communication and provable withdrawals from L2 to L1. +- **Challenger**: The challenger enforces network security by disputing invalid state roots that have been posted to Ethereum. This services protects the bridge from invalid withdrawals being made. + +## Deployment + +The following section will walk you through the sequence of steps a chain operator will follow to begin sequencing a chain. + + + + + Using a CLI tool called [op-deployer](/chain-operators/tools/op-deployer) you will configure your chain and then deploy the smart contracts on Ethereum. + + + After deploying the L1 system contracts, you will use the same tool to generate two files necessary to run nodes on the L2 network: + + * **Genesis file** (`genesis.json`): Initializes the execution client (`op-geth`) + * **Rollup configuration file** (`rollup.json`): Configures the consensus client (`op-node`) + + These files contain all the essential information your off chain components need to interact with Ethereum. + + + + After deploying the L1 smart contracts and generating your genesis files, it's crucial to verify that your deployment conforms to the standard configuration. + + + a + + + a + + + a + + diff --git a/chain-operators/guides/deployment/genesis.mdx b/chain-operators/guides/deployment/genesis.mdx index f79843d86..948d7989e 100644 --- a/chain-operators/guides/deployment/genesis.mdx +++ b/chain-operators/guides/deployment/genesis.mdx @@ -1,13 +1,11 @@ --- -title: Chain artifacts creation -description: Learn how to create genesis and rollup configuration files using op-deployer after L1 contract deployment. +title: Chain genesis creation +description: Learn how to create genesis and rollup configuration files. --- - - # Overview -After deploying the L1 system contracts for your OP Stack chain, you need to generate two files to run nodes on the L2 network: +After deploying the L1 system contracts for your OP Stack chain using `op-deployer`, you need to generate two files to run nodes on the L2 network: * **Genesis file** (`genesis.json`): Initializes the execution client (`op-geth`) * **Rollup configuration file** (`rollup.json`): Configures the consensus client (`op-node`) @@ -89,9 +87,3 @@ If you encounter issues with the generated files: Never manually edit the generated genesis or rollup files unless you fully understand the implications. Incorrect configurations can lead to consensus failures or chain security issues. - -## Next steps - -* Learn how to [initialize](/node-operators/guides/base-config#initialization-via-genesis-file) `op-geth` with your `genesis.json` file -* Learn how to [configure](/node-operators/guides/base-config#configuring-op-node) `op-node` with your `rollup.json` file -* Learn more about the off-chain [architecture](/operators/chain-operators/architecture) diff --git a/chain-operators/guides/deployment/overview.mdx b/chain-operators/guides/deployment/overview.mdx index 4b94f7ca5..d3eccd065 100644 --- a/chain-operators/guides/deployment/overview.mdx +++ b/chain-operators/guides/deployment/overview.mdx @@ -69,34 +69,8 @@ mechanism to invalidate the erroneous data. ## Software 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` | - -### 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. - -## Next steps - -* Discover how to [deploy the smart contracts](/operators/chain-operators/deploy/smart-contracts). -* Find out how to create your [genesis file](/operators/chain-operators/deploy/genesis). -* Explore some chain operator [best practices](/chain-operators/guides/management/best-practices). +You will need to install a number of software dependencies to deploy the OP Stack. +We use [`mise`](https://mise.jdx.dev/) as a dependency manager for these tools. +Once properly installed, `mise` will provide the correct versions for each tool. +`mise` does not replace any other installations of these binaries and will only serve these binaries when you are working inside of the `optimism` directory. +The `mise.toml` file will contain the required versions of the software dependencies. diff --git a/chain-operators/guides/deployment/sequencer-node.mdx b/chain-operators/guides/deployment/sequencer-node.mdx index ee49e0422..f182e48a5 100644 --- a/chain-operators/guides/deployment/sequencer-node.mdx +++ b/chain-operators/guides/deployment/sequencer-node.mdx @@ -73,8 +73,8 @@ Always check the release notes to ensure you're using compatible versions. For spinning up a sequencer, we recommend building from source as it provides better control, and helps with debugging. In this guide Docker alternative is also provided. - - + + Building from source gives you full control over the binaries. #### 1. Clone and build op-node @@ -397,9 +397,9 @@ In this guide Docker alternative is also provided. Your sequencer node is now operational and ready to process transactions. - + - + If you prefer containerized deployment, you can use the official Docker images, and do the following: 1. **Set up directory structure and copy configuration files:** @@ -558,13 +558,6 @@ In this guide Docker alternative is also provided. Your sequencer node is now operational and ready to process transactions. - + - -## Next steps - -* Discover how to [deploy chains with op-deployer](/operators/chain-operators/tools/op-deployer) for standardized OP Stack deployments. -* Learn how to configure and deploy the [batcher](/operators/chain-operators/configuration/batcher) to submit transaction data to L1. -* Set up the [proposer](/operators/chain-operators/configuration/proposer) to submit output roots for withdrawals. -* Explore chain operator [best practices](/chain-operators/guides/management/best-practices) for production deployments. diff --git a/chain-operators/guides/deployment/smart-contracts.mdx b/chain-operators/guides/deployment/smart-contracts.mdx index eb0c45603..1306bbd20 100644 --- a/chain-operators/guides/deployment/smart-contracts.mdx +++ b/chain-operators/guides/deployment/smart-contracts.mdx @@ -3,27 +3,25 @@ title: Smart contract deployment description: Learn how to deploy the OP Stack L1 smart contracts. --- - - - - - - # Overview This guide outlines the process for deploying the OP Stack L1 smart contracts using `op-deployer`. -Deploying OP Stack L1 contracts is a critical step in setting up your rollup. +Deploying OP Stack L1 contracts is the first step in spinning up your rollup. - Always deploy from official contract releases. You can find official release versions in the - [smart contract overview](/stack/smart-contracts#official-releases). Contract changes are - generally not considered backwards compatible. + For a standard version of the OP Stack, always deploy from an official contract release tag, which have been approved by Optimism Governance. + This is especially important for chains that intend to join the Superchain. + You can find these in the [Superchain Registry](https://github.com/ethereum-optimism/superchain-registry/validation/standard). + + Contract changes are generally not considered backwards compatible. + + - First, install the `op-deployer` tool following the [installation instructions](/operators/chain-operators/tools/op-deployer#installation). + First, install the `op-deployer` tool following the [installation instructions](/chain-operators/tools/op-deployer#installation). @@ -68,30 +66,3 @@ Deploying OP Stack L1 contracts is a critical step in setting up your rollup. -## Contract versioning - -The OP Stack follows semantic versioning (X.Y.Z) for contract releases: - -* **Major (X):** Breaking changes that require coordination, such as Ecotone or the Fault Proof System -* **Minor (Y):** New features or improvements that maintain backwards compatibility -* **Patch (Z):** Bug fixes and minor improvements - -Contract releases are tagged in the repository as `op-contracts/vX.Y.Z`. - - - For standard chains intended to join the Superchain, always use the latest Optimism Governance approved - release. You can find these in the [Superchain Registry](https://github.com/ethereum-optimism/superchain-registry). - - -## Version compatibility - -When selecting a contract version, consider: - -* L2 Client compatibility: Ensure your chosen contract version is compatible with the op-geth and op-node versions you plan to use -* Feature requirements: Different versions support different features (e.g., only v2.0.0+ supports permissionless fault proofs) -* Security updates: Always prefer the latest patch version within your chosen major.minor version - -## Next Steps - -* Learn how to [create your genesis file](/operators/chain-operators/deploy/genesis). -* See all [configuration options](/operators/chain-operators/configuration/rollup) and example configurations. diff --git a/chain-operators/guides/deployment/validate-deployment.mdx b/chain-operators/guides/deployment/validate-deployment.mdx index f0fbc4d04..dd5cd1ecd 100644 --- a/chain-operators/guides/deployment/validate-deployment.mdx +++ b/chain-operators/guides/deployment/validate-deployment.mdx @@ -1,5 +1,5 @@ --- -title: Validate your contract deployment +title: Validate your deployment description: Learn how to validate your OP Stack deployment using op-validator --- @@ -10,14 +10,15 @@ This guide walks you through using `op-validator` to validate your deployment ag ## Prerequisites -* Complete deployment of L1 smart contracts using [op-deployer](/operators/chain-operators/deploy/smart-contracts). -* Generate [genesis and rollup](/operators/chain-operators/deploy/genesis) files. -* Install [op-validator](/operators/chain-operators/tools/op-validator). +* Complete deployment of L1 smart contracts using [op-deployer](/chain-operators/deploy/smart-contracts). +* Generate [genesis and rollup](/chain-operators/deploy/genesis) files. +* Install [op-validator](/chain-operators/tools/op-validator). + ## Validation process - If you haven't already installed op-validator, follow the [installation instructions](/operators/chain-operators/tools/op-validator#installation). + If you haven't already installed op-validator, follow the [installation instructions](/chain-operators/tools/op-validator#installation). @@ -39,23 +40,9 @@ This guide walks you through using `op-validator` to validate your deployment ag Run the op-validator with the appropriate version parameter matching your deployed contracts: - - **For op-contracts v1.8.0:** - - ```bash - ./bin/op-validator validate v1.8.0 \ - --l1-rpc-url "" \ - --absolute-prestate "" \ - --proxy-admin "" \ - --system-config "" \ - --l2-chain-id "" \ - --fail - ``` - - **For op-contracts v2.0.0:** - + ```bash - ./bin/op-validator validate v2.0.0 \ + ./bin/op-validator validate \ --l1-rpc-url "" \ --absolute-prestate "" \ --proxy-admin "" \ diff --git a/chain-operators/tools/op-deployer.mdx b/chain-operators/tools/op-deployer.mdx index a821938e5..bba6063f5 100644 --- a/chain-operators/tools/op-deployer.mdx +++ b/chain-operators/tools/op-deployer.mdx @@ -1,64 +1,71 @@ --- -title: Deployer -description: Learn how op-deployer can simplify deploying a standard OP Stack Chain. +title: OP Deployer +description: OP Deployer is a CLI tool for deploying and upgrading smart contracts for OP Stack chains. --- +## Overview + +OP Deployer is a CLI tool that simplifies deploying and upgrading smart contracts for OP Stack chains. +It also exposes a suite of libraries that allow developers to easily manage smart contracts from their applications. +OP Deployer aims to make doing the right thing easy, and doing dangerous things hard. +As such its configuration and API are optimized for deploying and upgrading Standard OP Chains. +However, it also exposes a lower-level set of primitives and configuration directives which users can use to deploy more complex configurations if the need arises. + + + OP Deployer is undergoing active development and has been used for several mainnet deployments. + It is considered production-ready. + However, please keep in mind that **OP Deployer has not been audited** and that any chains deployed using OP Deployer should be checked thoroughly for correctness prior to launch. + + +## Installation There are a couple of ways to install `op-deployer`: - + + - Navigate to the Optimism monorepo's [release page](https://github.com/ethereum-optimism/optimism/releases). + - Select the latest stable release of op-deployer. + - Download the binary that matches your operating system. + - Extract the binary to a location on your system PATH + - Run this command to verify that you have it installed: + + ```bash + op-deployer --version + ``` + + To install from source, you will need [Go](https://go.dev/doc/install), `just`, and `git`. After installing all of that, run following: ```bash - - git clone https://github.com/ethereum-optimism/optimism.git # you can skip this if you already have the repo + git clone https://github.com/ethereum-optimism/optimism.git + git checkout cd optimism/op-deployer just build cp ./bin/op-deployer /usr/local/bin/op-deployer # or any other directory in your $PATH - - # Verify installation, run this command to verify that you have it installed. - op-deployer --version - ``` - - - - Another way to install `op-deployer`, is to download the latest release from the monorepo's [release page](https://github.com/ethereum-optimism/optimism/releases). - - 1. Go to [https://github.com/ethereum-optimism/optimism/releases](https://github.com/ethereum-optimism/optimism/releases) - 2. Find the latest release that includes op-deployer - 3. Under **assets**, download the binary that matches your operating system: - - * `op-deployer-linux-amd64` for Linux - * `op-deployer-darwin-amd64` or `op-deployer-darwin-arm64` for macOS - * `op-deployer-windows-amd64.exe` for Windows - - 4. Extract the binary to a location on your system PATH - 5. Verify installation, run this command to verify that you have it installed. - - ```bash op-deployer --version ``` - + ## 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. + Deploying an OP Stack chain involves deploying multiple contracts, which can consume a substantial amount of gas. + On 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. -The base use case for `op-deployer` is deploying new OP Chains. This process is broken down into three steps: - -### `init`: configure your chain +The use case for `op-deployer` is deploying new OP Chains. +This process is broken down into three steps: -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: +### Initialize new intent and state files - - 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. - +To get started with `op-deployer`, create an intent file that defines your desired chain configuration. +It uses a declarative intent file to determine how a new chain should be configured. +After you're satisified with your configuration, you will run a deployment pipeline to actually deploy the smart contracts with your configurations applied. +Use the built-in `op-deployer init` utility to generate this file: ```bash op-deployer init \ diff --git a/chain-operators/tools/op-validator.mdx b/chain-operators/tools/op-validator.mdx index 773177072..262181e96 100644 --- a/chain-operators/tools/op-validator.mdx +++ b/chain-operators/tools/op-validator.mdx @@ -1,9 +1,11 @@ --- -title: op-validator +title: OP Validator description: Learn how to use op-validator to validate chain configurations and deployments. --- -The `op-validator` is a tool for validating Standard OP Stack chain configurations and deployments to ensure they're in compliance with the [Standard Rollup Charter](/superchain/concepts/blockspace-charter#the-standard-rollup-charter). It works by calling into the `StandardValidator` smart contracts (`StandardValidatorV180` and `StandardValidatorV200`). These then perform a set of checks, and return error codes for any issues found. +The `op-validator` is a tool for validating Standard OP Stack chain configurations and deployments to ensure they're in compliance with the [Standard Rollup Charter](/superchain/concepts/blockspace-charter#the-standard-rollup-charter). +It works by calling into the `StandardValidator` smart contracts. +These then perform a set of checks, and return error codes for any issues found. These checks include: diff --git a/docs.json b/docs.json index f9cf0291b..ab9cd95d1 100644 --- a/docs.json +++ b/docs.json @@ -1677,6 +1677,7 @@ { "group": "Guides", "pages": [ + "/chain-operators/deployment-guide", { "group": "Configuration", "pages": [ @@ -1690,8 +1691,8 @@ "group": "Deployment", "pages": [ "chain-operators/guides/deployment/overview", - "chain-operators/guides/deployment/genesis", "chain-operators/guides/deployment/smart-contracts", + "chain-operators/guides/deployment/genesis", "chain-operators/guides/deployment/validate-deployment", "chain-operators/guides/deployment/sequencer-node", "chain-operators/guides/deployment/spin-batcher", From 6f8339527f47c3f8ba779daeddf229ceaf98e135 Mon Sep 17 00:00:00 2001 From: soyboy Date: Thu, 20 Nov 2025 19:42:48 -0500 Subject: [PATCH 2/2] reducing deployment section to quickstart --- chain-operators/deployment-guide.mdx | 51 -- chain-operators/guides/deployment/genesis.mdx | 89 --- .../guides/deployment/overview.mdx | 76 --- .../deployment/proposer-setup-guide.mdx | 249 -------- .../guides/deployment/sequencer-node.mdx | 563 ------------------ .../guides/deployment/smart-contracts.mdx | 68 --- .../guides/deployment/spin-batcher.mdx | 225 ------- .../guides/deployment/validate-deployment.mdx | 88 --- docs.json | 52 +- index.mdx | 251 ++------ 10 files changed, 82 insertions(+), 1630 deletions(-) delete mode 100644 chain-operators/deployment-guide.mdx delete mode 100644 chain-operators/guides/deployment/genesis.mdx delete mode 100644 chain-operators/guides/deployment/overview.mdx delete mode 100644 chain-operators/guides/deployment/proposer-setup-guide.mdx delete mode 100644 chain-operators/guides/deployment/sequencer-node.mdx delete mode 100644 chain-operators/guides/deployment/smart-contracts.mdx delete mode 100644 chain-operators/guides/deployment/spin-batcher.mdx delete mode 100644 chain-operators/guides/deployment/validate-deployment.mdx diff --git a/chain-operators/deployment-guide.mdx b/chain-operators/deployment-guide.mdx deleted file mode 100644 index 22051b56c..000000000 --- a/chain-operators/deployment-guide.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Deployment -description: Learn about the high level steps on how to deploy an OP Stack chain. ---- - -The OP Stack is an open-source, modular, Ethereum Layer 2 rollup stack. -This guide will walk you through the high level steps on how to deploy an OP Stack chain. - -## Components - -First we'll start with the components that come together to create your Layer 2 blockchain: - -todo: determine if we want collapseable components to make this more compact - -- **Smart contracts**: The OP Stack uses a set of smart contracts on Ethereum to bridge between the L1 and L2 domains and manage aspects of the rollup. -- **Sequencer**: The OP Stack relies on a sequencer node to build the canonical layer 2 blocks. The sequencer (and all replica) nodes consist of a consensus client and execution client. They are responsible for determining maintaining the consensus rules around, executing transactions, and maintaing the state of the blockchain. Optimism maintains the `op-node` and `op-geth`; however, there are alternative clients available from other cleint teams like `reth`, `nethermind`, and a handful of others. -- **Batcher**: The batcher is a service that publishes transactions made directly to the sequencer onto Ethereum. Using Ethereum as a data availability layer, the OP Stack inherits Ethereum's security properties by allowing anyone to derive the state of the L2 blockchain from L1. -- **Proposer**: The proposer is a service responsible for publishing the L2 state root to Ethereum. This enables cross-chain communication and provable withdrawals from L2 to L1. -- **Challenger**: The challenger enforces network security by disputing invalid state roots that have been posted to Ethereum. This services protects the bridge from invalid withdrawals being made. - -## Deployment - -The following section will walk you through the sequence of steps a chain operator will follow to begin sequencing a chain. - - - - - Using a CLI tool called [op-deployer](/chain-operators/tools/op-deployer) you will configure your chain and then deploy the smart contracts on Ethereum. - - - After deploying the L1 system contracts, you will use the same tool to generate two files necessary to run nodes on the L2 network: - - * **Genesis file** (`genesis.json`): Initializes the execution client (`op-geth`) - * **Rollup configuration file** (`rollup.json`): Configures the consensus client (`op-node`) - - These files contain all the essential information your off chain components need to interact with Ethereum. - - - - After deploying the L1 smart contracts and generating your genesis files, it's crucial to verify that your deployment conforms to the standard configuration. - - - a - - - a - - - a - - diff --git a/chain-operators/guides/deployment/genesis.mdx b/chain-operators/guides/deployment/genesis.mdx deleted file mode 100644 index 948d7989e..000000000 --- a/chain-operators/guides/deployment/genesis.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Chain genesis creation -description: Learn how to create genesis and rollup configuration files. ---- - -# Overview - -After deploying the L1 system contracts for your OP Stack chain using `op-deployer`, you need to generate two files to run nodes on the L2 network: - -* **Genesis file** (`genesis.json`): Initializes the execution client (`op-geth`) -* **Rollup configuration file** (`rollup.json`): Configures the consensus client (`op-node`) - -This guide shows you how to generate these files from your L1 contract deployment data using `op-deployer`. - -## Prerequisites - -Before generating genesis and rollup configuration files, ensure you have: - -1. Deployed the L1 contracts successfully using the [`op-deployer apply`](/operators/chain-operators/tools/op-deployer#apply-deploy-your-chain) command - -2. Access to your deployment workspace directory (`.deployer` if you've followed the instructions in the L1 deployment contracts guide) - -## Generating genesis and rollup files - -After your L1 contracts have been deployed, follow these steps to generate the configuration files: - -### Step 1: Locate your deployment state file - -The `op-deployer` tool creates a `state.json` file in your workspace directory that contains all the necessary information about your deployed contracts. - -Verify that this file exists in your workspace: - -```bash -ls -la .deployer/state.json -``` - -### Step 2: Generate the L2 genesis file - -Use the `inspect genesis` command to retrieve your L2 genesis file: - -```bash -op-deployer inspect genesis --workdir .deployer > .deployer/genesis.json -``` - -Replace `` with your L2 network's chain ID. - -### Step 3: Generate the rollup configuration file - -Use the `inspect rollup` command to retrieve your rollup configuration file: - -```bash -op-deployer inspect rollup --workdir .deployer > .deployer/rollup.json -``` - -### Step 4: Verify the generated files - -Examine the generated files to ensure they contain the expected configuration: - -```bash -# View the genesis file structure -jq . .deployer/genesis.json | head -20 - -# View the rollup configuration -jq . .deployer/rollup.json -``` - -The `genesis.json` file contains the initial state of your L2 blockchain, including: - -* Chain configuration parameters -* Initial account states -* Genesis block properties - -The `rollup.json` file contains the rollup protocol parameters, including: - -* L1 contract addresses -* Sequencing settings -* Protocol upgrade activation times - -## Troubleshooting - -If you encounter issues with the generated files: - -* [Verify](/operators/chain-operators/tools/op-deployer#verify-verify-contract-source-code-on-block-explorers) that your L1 contract deployment was successful -* Check that you're using the correct **L2 chain ID** in the generation commands -* Ensure your `state.json` file is up-to-date with your latest deployment - - - Never manually edit the generated genesis or rollup files unless you fully understand the implications. Incorrect configurations can lead to consensus failures or chain security issues. - diff --git a/chain-operators/guides/deployment/overview.mdx b/chain-operators/guides/deployment/overview.mdx deleted file mode 100644 index d3eccd065..000000000 --- a/chain-operators/guides/deployment/overview.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Deployment overview -description: Learn about the different components of deploying a standard OP Stack chain. ---- - -When deploying a **standard OP Stack chain**, you'll be setting up several key -components. It's useful to understand what each of these components does before -you start deploying your chain. The following information assumes you're -deploying a Rollup on Ethereum, but most concepts apply generally to any -standard OP Stack deployment. - -## Smart contracts - -The OP Stack uses a set of smart contracts on the L1 blockchain to manage -aspects of the Rollup. Each OP Stack chain has its own set of L1 smart -contracts that are deployed when the chain is created. - - - Standard OP Stack chains should only use governance approved and audited - smart contracts. The monorepo has them tagged with the following pattern - `op-contracts/vX.X.X` and you can review the release notes for details on the - changes. Read more about the details in our [Smart Contract Release Section](/op-stack/protocol/smart-contracts#official-releases). - - -## Sequencer node - -OP Stack chains use a Sequencer node to gather proposed transactions from users -and publish them to the L1 blockchain. OP Stack chains rely on at least one of -these Sequencer nodes. You can also run additional replica (non-Sequencer) -nodes. - -### Consensus client - -OP Stack Rollup nodes, like Ethereum nodes, have a consensus client. The -consensus client is responsible for determining the list and ordering of blocks -and transactions that are part of your blockchain. Several implementations of -the OP Stack consensus client exist, including `op-node` (maintained by the -Optimism Foundation), [`magi`](https://github.com/a16z/magi) (maintained by -a16z) and [`hildr`](https://github.com/optimism-java/hildr) (maintained by OptimismJ). - -### Execution client - -OP Stack nodes, like Ethereum nodes, also have an execution client. The -execution client is responsible for executing transactions and maintaining the -state of the blockchain. Various implementations of the OP Stack execution -client exist, including `op-geth` (maintained by the Optimism Foundation), -[`op-erigon`](https://github.com/testinprod-io/op-erigon) (maintained by Test -in Prod), and [`op-nethermind`](https://docs.nethermind.io/get-started/installing-nethermind/#supported-networks). - -## Batcher - -The Batcher is a service that publishes transactions from the Rollup to the L1 -blockchain. The Batcher runs continuously alongside the Sequencer and publishes -transactions in regular batches. - -## Proposer - -The Proposer is a service responsible for publishing transactions *results* (in -the form of L2 state roots) to the L1 blockchain. This allows smart contracts -on L1 to read the state of the L2, which is necessary for cross-chain -communication and reconciliation between state changes. - -## Challenger - -The Challenger enforces network security by disputing invalid state roots (if -any) that have been posted by the Proposer. It monitors on-chain data and, in -the event of a suspected fraud, triggers a fault proof or another dispute -mechanism to invalidate the erroneous data. - -## Software dependencies - -You will need to install a number of software dependencies to deploy the OP Stack. -We use [`mise`](https://mise.jdx.dev/) as a dependency manager for these tools. -Once properly installed, `mise` will provide the correct versions for each tool. -`mise` does not replace any other installations of these binaries and will only serve these binaries when you are working inside of the `optimism` directory. -The `mise.toml` file will contain the required versions of the software dependencies. diff --git a/chain-operators/guides/deployment/proposer-setup-guide.mdx b/chain-operators/guides/deployment/proposer-setup-guide.mdx deleted file mode 100644 index e33eb960b..000000000 --- a/chain-operators/guides/deployment/proposer-setup-guide.mdx +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Spinning up the proposer -description: Learn how to set up and configure an OP Stack proposer to post L2 state roots. ---- - - -After you have [spun up your sequencer](/operators/chain-operators/deploy/sequencer-node), you need to attach a proposer to post your L2 state roots data back onto L1 so we can prove withdrawal validity. The proposer is a critical component that enables trustless L2-to-L1 messaging and creates the authoritative view of L2 state from L1's perspective. - -This guide assumes you already have a functioning sequencer and the necessary L1 contracts deployed using [`op-deployer`](/operators/chain-operators/tools/op-deployer). If you haven't set up your sequencer yet, please refer to the [sequencer guide](/operators/chain-operators/deploy/sequencer-node) first. - -To see configuration info for the proposer, check out the [configuration page](/operators/chain-operators/configuration/proposer). - -## Understanding the proposer's role - -The proposer (`op-proposer`) serves as a crucial bridge between your L2 chain and L1. Its primary responsibilities include: - -* **State commitment**: Proposing L2 state roots to L1 at regular intervals -* **Withdrawal enablement**: Providing the necessary commitments for users to prove and finalize withdrawals - -The proposer creates dispute games via the `DisputeGameFactory` contract. - -## Prerequisites - -Before setting up your proposer, ensure you have: - -**Running infrastructure:** - -* An operational sequencer node -* Access to a L1 RPC endpoint - -**Network information:** - -* Your L2 chain ID and network configuration -* L1 network details (chain ID, RPC endpoints) - -## Software installation - -### Build from source - -Clone and build `op-proposer` - -```bash -# If you don't already have the optimism repository from the sequencer setup -git clone https://github.com/ethereum-optimism/optimism.git -cd optimism - -# Checkout the latest release tag -git checkout op-proposer/v1.10.0 - -# Build op-proposer -cd op-proposer -just - -# Binary will be available at ./bin/op-proposer -``` - - - This uses `op-proposer/v1.10.0` which is compatible with op-node/v1.13.3 and op-geth/v1.101511.1 from [spinning up the sequencer guide](/operators/chain-operators/deploy/sequencer-node). - Always check the [release notes](https://github.com/ethereum-optimism/optimism/releases) for compatibility. - - -### Verify installation - -Run this command to verify the installation. - -```bash -./bin/op-proposer --version -``` - -## Configuration setup - -### 1. Organize your workspace - -At the same level as your sequencer from the [sequencer tutorial](/chain-operators/guides/deployment/sequencer-node): - -```bash -# Create proposer directory at the same level as your sequencer -mkdir proposer-node -cd proposer-node - -# Create scripts directory -mkdir scripts -``` - -### 2. Extract DisputeGameFactory address - -Extract the `DisputeGameFactory` contract address from your op-deployer output: - -```bash -# Navigate to proposer directory -cd proposer-node - -# Copy the state.json from .deployer directory created while using op-deployer -# Update the path if your .deployer directory is located elsewhere -cp ../.deployer/state.json . - -# Extract the DisputeGameFactory address -GAME_FACTORY_ADDRESS=$(cat state.json | jq -r '.opChainDeployments[0].DisputeGameFactoryProxy') -echo "DisputeGameFactory Address: $GAME_FACTORY_ADDRESS" -``` - - - The proposer only needs the `DisputeGameFactory` address to submit proposals. - The `GAME_TYPE=0` represents the standard fault proof game type. - - -### 3. Set up environment variables - -Create your `.env` file with the actual values: - -```bash -# Create .env file with your actual values -# L1 Configuration - Replace with your actual RPC URL -L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY - -# L2 Configuration - Should match your sequencer setup -L2_RPC_URL=http://localhost:8545 -ROLLUP_RPC_URL=http://localhost:8547 - -# Contract addresses - Extract from your op-deployer output -GAME_FACTORY_ADDRESS=YOUR_ACTUAL_GAME_FACTORY_ADDRESS - -# Private key - Replace with your actual private key -PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY - -# Proposer configuration -PROPOSAL_INTERVAL=3600s -GAME_TYPE=0 -POLL_INTERVAL=20s - -# RPC configuration -PROPOSER_RPC_PORT=8560 -``` - -**Important**: Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values! - -### 4. Get your private key - -Get a private key from your wallet. - -## Proposer configuration - -Create `scripts/start-proposer.sh`: - -```bash -#!/bin/bash - -source .env - -# Path to the op-proposer binary we built -../optimism/op-proposer/bin/op-proposer \ - --poll-interval=$POLL_INTERVAL \ - --rpc.port=$PROPOSER_RPC_PORT \ - --rpc.enable-admin \ - --rollup-rpc=$ROLLUP_RPC_URL \ - --l1-eth-rpc=$L1_RPC_URL \ - --private-key=$PRIVATE_KEY \ - --game-factory-address=$GAME_FACTORY_ADDRESS \ - --game-type=$GAME_TYPE \ - --proposal-interval=$PROPOSAL_INTERVAL \ - --num-confirmations=1 \ - --resubmission-timeout=30s \ - --wait-node-sync=true \ - --log.level=info -``` - -Your final directory structure should look like: - -```bash -~/ -├── optimism/ # Contains op-proposer binary -├── sequencer-node/ # Your sequencer setup -├── .deployer/ # From op-deployer -│ └── state.json -└── proposer-node/ # Your proposer working directory - ├── state.json # Copied from .deployer - ├── .env - └── scripts/ - └── start-proposer.sh -``` - -## Starting the proposer - -### 1. Verify prerequisites - -Ensure your sequencer and op-node are running: - -```bash - -# Test L1 connectivity -# Note: Make sure you have exported these environment variables to your current shell session: -# export L1_RPC_URL="https://sepolia.infura.io/v3/YOUR_KEY" -# export L2_RPC_URL="http://localhost:8545" -# export ROLLUP_RPC_URL="http://localhost:8547" - -curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \ - $L1_RPC_URL - -# Test L2 connectivity -curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \ - $L2_RPC_URL - -# Test rollup node connectivity -curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' \ - $ROLLUP_RPC_URL -``` - -### 2. Start the proposer - -```bash -# Make the script executable -chmod +x scripts/start-proposer.sh - -# Start the proposer -./scripts/start-proposer.sh -``` - -## Verification - -Verify your proposer is working correctly: - -### Check proposer status - -```bash - -# Monitor proposal activity -curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"optimism_outputAtBlock","params":["latest"],"id":1}' \ - http://localhost:8547 - -# Check if your proposer address has enough ETH for gas -# (Replace with your actual proposer address) -curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xYOUR_PROPOSER_ADDRESS","latest"],"id":1}' \ - $L1_RPC_URL -``` - -Your proposer is now operational! - -## Next steps - -* Learn how to set up the [sequencer node](/operators/chain-operators/deploy/sequencer-node) for your OP Stack chain. -* For detailed parameter documentation, see the [proposer configuration reference](/operators/chain-operators/configuration/proposer). -* For more detail on deploying new dispute games with OPCM, [see the docs](/operators/chain-operators/tutorials/dispute-games). -* checkout the [migrating to permissionless fault proofs](/operators/chain-operators/tutorials/migrating-permissionless) guide -* For cost optimization resources, check out the [Fee calculation tools](/operators/chain-operators/tools/fee-calculator). diff --git a/chain-operators/guides/deployment/sequencer-node.mdx b/chain-operators/guides/deployment/sequencer-node.mdx deleted file mode 100644 index f182e48a5..000000000 --- a/chain-operators/guides/deployment/sequencer-node.mdx +++ /dev/null @@ -1,563 +0,0 @@ ---- -title: Spinning up the sequencer -description: Spin up a single sequencer node after verifying L1 smart-contract deployment. ---- - - -This guide provides step-by-step instructions for spinning up a sequencer node after deploying L1 smart contracts for your OP Stack chain with [`op-deployer`](/operators/chain-operators/tools/op-deployer). - -A sequencer node consists of two core components: - -* **op-geth**: Execution layer that processes transactions and maintains state -* **op-node**: Consensus layer that orders transactions and creates L2 blocks - -The sequencer is responsible for: - -* Ordering transactions from users -* Building L2 blocks -* Signing blocks on the P2P network - -## Prerequisites - -### Essential requirements - -Before spinning up your sequencer, complete the following steps: - -**1. Successful L1 contract deployment:** - -* Deployed L1 contracts using [`op-deployer apply`](/operators/chain-operators/tools/op-deployer#apply-deploy-your-chain) command. -* Generated genesis and rollup configuration files using: - ```bash - op-deployer inspect genesis --workdir .deployer > .deployer/genesis.json - op-deployer inspect rollup --workdir .deployer > .deployer/rollup.json - ``` - -**2. Required configuration files:** - -* `genesis.json` - L2 genesis file for initializing op-geth -* `rollup.json` - Rollup configuration file for op-node -* Access to your deployment `state.json` file from op-deployer - -**3. L1 network access:** - -* L1 RPC endpoint (Ethereum, Sepolia, etc.) -* L1 Beacon node endpoint - -### Software requirements - -* Git (for cloning repositories) -* Go 1.21+ (if building from source) -* Docker and Docker Compose (optional but recommended) -* OpenSSL for JWT secret generation - -### Finding the current stable releases - -To ensure you're using the latest compatible versions of OP Stack components, always check the official releases page: - -**[release page](https://github.com/ethereum-optimism/optimism/releases)** - -The main components you'll need for sequencer deployment are: - -* **op-node**: Look for the latest `op-node/v*` release -* **op-geth**: Look for the latest `op-geth/v*` [release](https://github.com/ethereum-optimism/op-geth/releases) - - -The versions used in this guide (**op-node/v1.13.3** and **op-geth/v1.101511.1**) are verified compatible versions. - -According to the **op-node v1.13.3** [release notes](https://github.com/ethereum-optimism/optimism/releases/tag/op-node%2Fv1.13.3), this op-node version specifically corresponds to **op-geth v1.101511.1**. -Always check the release notes to ensure you're using compatible versions. - - -## Software installation - -For spinning up a sequencer, we recommend building from source as it provides better control, and helps with debugging. -In this guide Docker alternative is also provided. - - - - Building from source gives you full control over the binaries. - - #### 1. Clone and build op-node - - ```bash - # Clone the optimism monorepo - git clone https://github.com/ethereum-optimism/optimism.git - cd optimism - - # Checkout the latest release tag - git checkout op-node/v1.13.3 - - # Build op-node - cd op-node - just - - # Binary will be available at ./bin/op-node - ``` - - #### 2. Clone and build op-geth - - ```bash - # Clone op-geth repository (in a separate directory) - git clone https://github.com/ethereum-optimism/op-geth.git - cd op-geth - - # Checkout to this release tag - git checkout v1.101511.1 - - # Build op-geth - make geth - - # Binary will be available at ./build/bin/geth - ``` - - ### Verify installation - - Check that you have properly installed the needed components. - - ```bash - # Make sure you're in the right directory - ./bin/op-node --version - ./build/bin/geth version - ``` - - ## Configuration setup - - ### 1. Organize your workspace - - After building the binaries, you should have the following directory structure: - - ``` - ~/ - ├── optimism/ # Optimism monorepo - │ └── op-node/ - │ └── bin/ - │ └── op-node # Built binary - ├── op-geth/ # OP-Geth repository - │ └── build/ - │ └── bin/ - │ └── geth # Built binary - └── .deployer/ # From op-deployer - ├── genesis.json - └── rollup.json - ``` - - Now create your sequencer working directory. We recommend creating it at the same level for easy path references: - - ```bash - # Create sequencer directory at the root level - mkdir ~/sequencer-node - cd ~/sequencer-node - ``` - - - - If you prefer to keep binaries close to your configuration, you can copy them: - - ```bash - mkdir ~/sequencer-node/bin - cp ~/optimism/op-node/bin/op-node ~/sequencer-node/bin/ - cp ~/op-geth/build/bin/geth ~/sequencer-node/bin/ - - # Then update scripts to use: - # ./bin/geth - # ./bin/op-node - ``` - - - ### 2. Generate JWT secret - - ```bash - # Generate JWT secret in the sequencer directory - openssl rand -hex 32 > jwt.txt - - # Set appropriate permissions - chmod 600 jwt.txt - ``` - - ### 3. Set up directory structure and copy files - - In this guide, we're going to be using the binaries from their original build locations, we only need to create directories for configuration files and scripts. - - ```bash - # Create scripts directory - mkdir scripts - - # Copy configuration files from op-deployer - cp ~/.deployer/genesis.json . - cp ~/.deployer/rollup.json . - ``` - - Your final directory structure should look like: - - ```bash - ~/sequencer-node/ - ├── jwt.txt - ├── genesis.json - ├── rollup.json - └── scripts/ - ├── start-op-geth.sh # (to be created) - └── start-op-node.sh # (to be created) - ``` - - ### 4. Environment variables - - You'll need to gather several pieces of information before creating your configuration. Here's where to get each value: - - ### Get L1 network access - - You need access to the L1 network (Ethereum mainnet or Sepolia testnet) and its beacon node: - - **L1 RPC URL options:** - - * **Infura**: [infura.io](https://infura.io) - Requires an API key from a project - * **Alchemy**: [alchemy.com](https://alchemy.com) - Requires an API key from an app - - **L1 Beacon URL options:** - - * **Public beacon APIs**: `https://ethereum-sepolia-beacon-api.publicnode.com` (Sepolia) or `https://ethereum-beacon-api.publicnode.com` (Mainnet) - * **Infura beacon**: `https://sepolia.infura.io/v3/YOUR_KEY` (if your Infura plan includes beacon access) - - ### Get private key from your wallet - - For this basic sequencer setup, you only need a private key during op-node initialization. - - ### Get your public IP address - - ```bash - # Find your public IP address, once you get it, update the P2P_ADVERTISE_IP in your .env - curl ifconfig.me - # or - curl ipinfo.io/ip - ``` - - ### Choose your ports - - The default ports are standard but can be changed if needed: - - * `8545`: op-geth HTTP RPC (standard Ethereum RPC port) - * `8546`: op-geth WebSocket RPC - * `8551`: op-geth Auth RPC (for op-node communication) - * `8547`: op-node RPC - * `9222`: P2P networking (must be open on firewall) - - - - Now create your `.env` file with the actual values: - - ```bash - # Create .env file with your actual values - # L1 Configuration - Replace with your actual RPC URLs - L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY - L1_BEACON_URL=https://ethereum-sepolia-beacon-api.publicnode.com - - # Sequencer configuration - SEQUENCER_ENABLED=true - SEQUENCER_STOPPED=false - - # Private keys - PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY - - # P2P configuration - Replace with your actual public IP - P2P_LISTEN_PORT=9222 - P2P_ADVERTISE_IP=YOUR_ACTUAL_PUBLIC_IP - - # RPC configuration (can customize ports if needed) - OP_NODE_RPC_PORT=8547 - OP_GETH_HTTP_PORT=8545 - OP_GETH_WS_PORT=8546 - OP_GETH_AUTH_PORT=8551 - - # JWT secret location - JWT_SECRET=./jwt.txt - ``` - - **Important**: Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values. - - ## Sequencer specific configuration - - ### op-geth configuration for sequencer - - Create `scripts/start-op-geth.sh`: - - ```bash - #!/bin/bash - source .env - - # Path to the op-geth binary we built - ../op-geth/build/bin/geth \ - --datadir=./op-geth-data \ - --http \ - --http.addr=0.0.0.0 \ - --http.port=$OP_GETH_HTTP_PORT \ - --http.vhosts="*" \ - --http.corsdomain="*" \ - --http.api=eth,net,web3,debug,txpool,admin \ - --ws \ - --ws.addr=0.0.0.0 \ - --ws.port=$OP_GETH_WS_PORT \ - --ws.origins="*" \ - --ws.api=eth,net,web3,debug,txpool,admin \ - --authrpc.addr=0.0.0.0 \ - --authrpc.port=$OP_GETH_AUTH_PORT \ - --authrpc.vhosts="*" \ - --authrpc.jwtsecret=$JWT_SECRET \ - --syncmode=full \ - --gcmode=archive \ - --rollup.disabletxpoolgossip=true \ - --rollup.sequencerhttp=http://localhost:$OP_NODE_RPC_PORT - ``` - - ### op-node configuration for sequencer - - Create `scripts/start-op-node.sh`: - - ```bash - #!/bin/bash - - source .env - - # Path to the op-node binary we built - ../optimism/op-node/bin/op-node \ - --l1=$L1_RPC_URL \ - --l1.beacon=$L1_BEACON_URL \ - --l2=http://localhost:$OP_GETH_AUTH_PORT \ - --l2.jwt-secret=$JWT_SECRET \ - --rollup.config=./rollup.json \ - --sequencer.enabled=$SEQUENCER_ENABLED \ - --sequencer.stopped=$SEQUENCER_STOPPED \ - --sequencer.max-safe-lag=3600 \ - --verifier.l1-confs=4 \ - --p2p.listen.ip=0.0.0.0 \ - --p2p.listen.tcp=$P2P_LISTEN_PORT \ - --p2p.listen.udp=$P2P_LISTEN_PORT \ - --p2p.advertise.ip=$P2P_ADVERTISE_IP \ - --p2p.advertise.tcp=$P2P_LISTEN_PORT \ - --p2p.advertise.udp=$P2P_LISTEN_PORT \ - --p2p.sequencer.key=$PRIVATE_KEY \ - --rpc.addr=0.0.0.0 \ - --rpc.port=$OP_NODE_RPC_PORT \ - --rpc.enable-admin \ - --log.level=info \ - --log.format=json - ``` - - ## Initializing and starting the sequencer - - - - ### Initialize op-geth with your genesis file - - ```bash - # Make sure you're in the sequencer-node directory - cd ~/sequencer-node - - # Initialize op-geth with your genesis file - ../op-geth/build/bin/geth init --datadir=./op-geth-data --state.scheme=hash ./genesis.json - ``` - - ### Start op-geth - - ```bash - # Make scripts executable - chmod +x scripts/start-op-geth.sh - chmod +x scripts/start-op-node.sh - - # Start op-geth in the background or in a separate terminal - ./scripts/start-op-geth.sh - ``` - - **Note**: You should see output indicating that op-geth is starting and listening on the configured ports. - - ### Start op-node - - ```bash - # In a separate terminal, navigate to the sequencer directory - cd ~/sequencer-node - - # Start op-node - ./scripts/start-op-node.sh - ``` - - ### Verify sequencer is running - - Once both services are running, verify they're working correctly: - - ```bash - # Check op-geth is responding, do this in another terminal - curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \ - http://localhost:8545 - - # Check sequencer status - curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"admin_sequencerActive","params":[],"id":1}' \ - http://localhost:8547 - ``` - - - Your sequencer node is now operational and ready to process transactions. - - - - - If you prefer containerized deployment, you can use the official Docker images, and do the following: - - 1. **Set up directory structure and copy configuration files:** - - ```bash - # Create your sequencer working directory - mkdir ~/sequencer-node - cd ~/sequencer-node - - # Copy configuration files from op-deployer output - # Note: Adjust the path if your .deployer directory is located elsewhere - cp ~/.deployer/genesis.json . - cp ~/.deployer/rollup.json . - - # Generate JWT secret - openssl rand -hex 32 > jwt.txt - chmod 600 jwt.txt - ``` - - 2. **Create environment variables file:** - - ```bash - # Create .env file with your actual values - cat > .env << 'EOF' - # L1 Configuration - Replace with your actual RPC URLs - L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY - L1_BEACON_URL=https://ethereum-sepolia-beacon-api.publicnode.com - - # Private keys - Replace with your actual private key - PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY - - # (Run `curl ifconfig.me` in a separate shell to obtain the value, then paste it below) - - # P2P configuration - Replace with your actual public IP - P2P_ADVERTISE_IP=YOUR_ACTUAL_PUBLIC_IP - - EOF - ``` - - **Important**: Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values. - - 3. **Create docker-compose.yml:** - - ```yaml - ' - - services: - op-geth: - image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-geth:v1.101511.1 - volumes: - # Mount entire directory to avoid file mounting issues - - .:/workspace - working_dir: /workspace - ports: - - "8545:8545" - - "8546:8546" - - "8551:8551" - command: - - "--datadir=/workspace/op-geth-data" - - "--http" - - "--http.addr=0.0.0.0" - - "--http.port=8545" - - "--ws" - - "--ws.addr=0.0.0.0" - - "--ws.port=8546" - - "--authrpc.addr=0.0.0.0" - - "--authrpc.port=8551" - - "--authrpc.jwtsecret=/workspace/jwt.txt" - - "--syncmode=full" - - "--gcmode=archive" - - "--rollup.disabletxpoolgossip=true" - - "--http.vhosts=*" - - "--http.corsdomain=*" - - "--http.api=eth,net,web3,debug,txpool,admin" - - "--ws.origins=*" - - "--ws.api=eth,net,web3,debug,txpool,admin" - - "--authrpc.vhosts=*" - - op-node: - image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.13.3 - depends_on: - - op-geth - volumes: - - .:/workspace - working_dir: /workspace - ports: - - "8547:8547" - - "9222:9222" - environment: - - L1_RPC_URL=${L1_RPC_URL} - - L1_BEACON_URL=${L1_BEACON_URL} - - PRIVATE_KEY=${PRIVATE_KEY} - - P2P_ADVERTISE_IP=${P2P_ADVERTISE_IP} - command: - - "op-node" - - "--l1=${L1_RPC_URL}" - - "--l1.beacon=${L1_BEACON_URL}" - - "--l2=http://op-geth:8551" - - "--l2.jwt-secret=/workspace/jwt.txt" - - "--rollup.config=/workspace/rollup.json" - - "--sequencer.enabled=true" - - "--sequencer.stopped=false" - - "--sequencer.max-safe-lag=3600" - - "--verifier.l1-confs=4" - - "--p2p.listen.ip=0.0.0.0" - - "--p2p.listen.tcp=9222" - - "--p2p.listen.udp=9222" - - "--p2p.advertise.ip=${P2P_ADVERTISE_IP}" - - "--p2p.advertise.tcp=9222" - - "--p2p.advertise.udp=9222" - - "--p2p.sequencer.key=${PRIVATE_KEY}" - - "--rpc.addr=0.0.0.0" - - "--rpc.port=8547" - - "--rpc.enable-admin" - - "--log.level=info" - - "--log.format=json" - ``` - - 4. **Initialize op-geth with Docker:** - - ```bash - # Make sure you're in the sequencer-node directory with all files copied - cd ~/sequencer-node - - # Initialize op-geth using Docker - docker run --rm \ - -v $(pwd):/workspace \ - -w /workspace \ - us-docker.pkg.dev/oplabs-tools-artifacts/images/op-geth:v1.101511.1 \ - init --datadir=./op-geth-data --state.scheme=hash ./genesis.json - ``` - - 5. **Start the services:** - - ```bash - # Start both services - docker-compose up -d - - # View logs - docker-compose logs -f - ``` - - 6. **Final directory structure:** - - ```bash - ~/sequencer-node/ - ├── jwt.txt # Generated JWT secret - ├── genesis.json # Copied from ~/.deployer/ - ├── rollup.json # Copied from ~/.deployer/ - ├── .env # Environment variables - ├── docker-compose.yml # Docker configuration - └── op-geth-data/ # Created by Docker during initialization - ├── geth/ # Geth data - └── keystore/ # Key files - ``` - - Your sequencer node is now operational and ready to process transactions. - - - - diff --git a/chain-operators/guides/deployment/smart-contracts.mdx b/chain-operators/guides/deployment/smart-contracts.mdx deleted file mode 100644 index 1306bbd20..000000000 --- a/chain-operators/guides/deployment/smart-contracts.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Smart contract deployment -description: Learn how to deploy the OP Stack L1 smart contracts. ---- - -# Overview - -This guide outlines the process for deploying the OP Stack L1 smart contracts using `op-deployer`. - -Deploying OP Stack L1 contracts is the first step in spinning up your rollup. - - - For a standard version of the OP Stack, always deploy from an official contract release tag, which have been approved by Optimism Governance. - This is especially important for chains that intend to join the Superchain. - You can find these in the [Superchain Registry](https://github.com/ethereum-optimism/superchain-registry/validation/standard). - - - - Contract changes are generally not considered backwards compatible. - - - - - First, install the `op-deployer` tool following the [installation instructions](/chain-operators/tools/op-deployer#installation). - - - - Generate an intent file that defines your chain configuration: - - ```bash - op-deployer init \ - --l1-chain-id \ - --l2-chain-ids \ - --workdir .deployer \ - --intent-type - ``` - - Customize the generated intent file according to your requirements. See the [op-deployer configuration guide](/operators/chain-operators/tools/op-deployer#understanding-the-intenttoml-fields) for details. - - - - Execute the deployment: - - ```bash - op-deployer apply --workdir .deployer --l1-rpc-url --private-key - ``` - - - - Verify your deployed contracts on block explorers: - - ```bash - op-deployer verify \ - --l1-rpc-url \ - --etherscan-api-key - ``` - - - - Generate the necessary configuration files for your L2 node: - - ```bash - op-deployer inspect genesis --workdir .deployer > .deployer/genesis.json - op-deployer inspect rollup --workdir .deployer > .deployer/rollup.json - ``` - - - diff --git a/chain-operators/guides/deployment/spin-batcher.mdx b/chain-operators/guides/deployment/spin-batcher.mdx deleted file mode 100644 index 7ec8dbbeb..000000000 --- a/chain-operators/guides/deployment/spin-batcher.mdx +++ /dev/null @@ -1,225 +0,0 @@ ---- -title: Spinning up the batcher -description: Learn how to set up and configure an OP Stack batcher to submit L2 transaction batches to L1. ---- - - -After you have spun up your [sequencer](/operators/chain-operators/deploy/sequencer-node), you need to configure a batcher to submit L2 transaction batches to L1. The batcher is a critical component that ensures L2 transaction data is available on L1 for data availability and enables users to reconstruct the L2 state. - -This guide assumes you already have a functioning sequencer and the necessary L1 contracts deployed using [`op-deployer`](/operators/chain-operators/tools/op-deployer). If you haven't set up your sequencer yet, please refer to the [sequencer guide](/operators/chain-operators/deploy/sequencer-node) first. - -## Understanding the batcher's role - -The batcher (`op-batcher`) serves as a crucial component that bridges your L2 chain data to L1. Its primary responsibilities include: - -* **Batch submission**: Collecting L2 transactions and submitting them as batches to L1 -* **Data availability**: Ensuring L2 transaction data is available on L1 for verification -* **Cost optimization**: Compressing and efficiently packing transaction data to minimize L1 costs -* **Channel management**: Managing data channels for optimal batch submission timing - -The batcher reads transaction data from your sequencer and submits compressed batches to the `BatchInbox` contract on L1. - -## Prerequisites - -Before setting up your batcher, ensure you have: - -**Running infrastructure:** - -* An operational sequencer node -* Access to a L1 RPC endpoint - -**Network information:** - -* Your L2 chain ID and network configuration -* L1 network details (chain ID, RPC endpoints) -* `BatchInbox` contract address from your deployment - -## Software installation - -### Finding the current stable releases - -To ensure you're using the latest compatible versions of OP Stack components, always check the official [releases page](https://github.com/ethereum-optimism/optimism/releases). - -Look for the latest `op-batcher/v*` release that's compatible with your sequencer setup. - - - This guide uses `op-batcher/v1.13.1` which is compatible with op-node/v1.13.3 and op-geth/v1.101511.0 from the sequencer setup. - Always check the [release notes](https://github.com/ethereum-optimism/optimism/releases) for compatibility information. - - -### Build from source - -Clone and build op-batcher: - -```bash -# If you don't already have the optimism repository from the sequencer setup -git clone https://github.com/ethereum-optimism/optimism.git -cd optimism - -# Checkout the latest release tag -git checkout op-batcher/v1.13.1 - -# Build op-batcher -cd op-batcher -just - -# Binary will be available at ./bin/op-batcher -``` - -### Verify installation - -Run this command to verify the installation: - -```bash -./bin/op-batcher --version -``` - -### Docker alternative (For containerized environments) - -If you prefer containerized deployment, you can use the official Docker images. - -### Complete Docker setup guide - - - - If you choose the Docker approach, you'll need to: - - 1. **Set up directory structure and copy configuration files:** - - ```bash - # Create your batcher working directory - mkdir ~/batcher-node - cd ~/batcher-node - - # Copy configuration files from op-deployer output - # Note: Adjust the path if your .deployer directory is located elsewhere - cp ~/.deployer/state.json . - - # Extract the BatchInbox address - BATCH_INBOX_ADDRESS=$(cat state.json | jq -r '.opChainDeployments[0].SystemConfigProxy') - echo "BatchInbox Address: $BATCH_INBOX_ADDRESS" - ``` - - 2. **Create environment variables file:** - - ```bash - # Create .env file with your actual values - cat > .env << 'EOF' - # L1 Configuration - Replace with your actual RPC URLs - L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY - - # L2 Configuration - Should match your sequencer setup - L2_RPC_URL=http://op-geth:8545 - ROLLUP_RPC_URL=http://op-node:8547 - - # Contract addresses - Extract from your op-deployer output - BATCH_INBOX_ADDRESS=YOUR_ACTUAL_BATCH_INBOX_ADDRESS - - # Private key - Replace with your actual private key - BATCHER_PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY - - # Batcher configuration - POLL_INTERVAL=1s - SUB_SAFETY_MARGIN=6 - NUM_CONFIRMATIONS=1 - SAFE_ABORT_NONCE_TOO_LOW_COUNT=3 - RESUBMISSION_TIMEOUT=30s - MAX_CHANNEL_DURATION=25 - - # RPC configuration - BATCHER_RPC_PORT=8548 - EOF - ``` - - **Important**: Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values. - - 3. **Create docker-compose.yml:** - - - This configuration assumes your sequencer is running in a Docker container named `sequencer-node` on the same `op-stack` network. - Make sure your sequencer is running before starting the batcher. - - - ```yaml - -services: - op-batcher: - image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-batcher:v1.13.1 - volumes: - - .:/workspace - working_dir: /workspace - ports: - - "8548:8548" - env_file: - - .env - command: - - "op-batcher" - - "--l2-eth-rpc=${L2_RPC_URL}" - - "--rollup-rpc=${ROLLUP_RPC_URL}" - - "--poll-interval=${POLL_INTERVAL}" - - "--sub-safety-margin=${SUB_SAFETY_MARGIN}" - - "--num-confirmations=${NUM_CONFIRMATIONS}" - - "--safe-abort-nonce-too-low-count=${SAFE_ABORT_NONCE_TOO_LOW_COUNT}" - - "--resubmission-timeout=${RESUBMISSION_TIMEOUT}" - - "--rpc.addr=0.0.0.0" - - "--rpc.port=${BATCHER_RPC_PORT}" - - "--rpc.enable-admin" - - "--max-channel-duration=${MAX_CHANNEL_DURATION}" - - "--l1-eth-rpc=${L1_RPC_URL}" - - "--private-key=${BATCHER_PRIVATE_KEY}" - - "--batch-type=1" - - "--data-availability-type=blobs" - - "--compress" - - "--log.level=info" - restart: unless-stopped - ``` - - 4. **Start the batcher service:** - - ```bash - # Make sure your sequencer network exists - docker network create op-stack 2>/dev/null || true - - # Start the batcher - docker-compose up -d - - # View logs - docker-compose logs -f op-batcher - ```` - - 5. **Verify batcher is running:** - - ```bash - # Check batcher RPC is responding - curl -X POST -H "Content-Type: application/json" \ - --data '{"jsonrpc":"2.0","method":"admin_startBatcher","params":[],"id":1}' \ - http://localhost:8548 - - # Check container status - docker-compose ps - ``` - - 6. **Final directory structure:** - - ```bash - ~/batcher-node/ - ├── state.json # Copied from ~/.deployer/ - ├── .env # Environment variables - └── docker-compose.yml # Docker configuration - ``` - - - - The rest of this guide assumes you're using the **build-from-source** approach. - If you chose Docker, refer to the collapsible section. - - - -## Next steps - -* For detailed parameter documentation, see the [batcher configuration reference](/operators/chain-operators/configuration/batcher). -* For monitoring and metrics setup, check the [chain monitoring guide](/operators/chain-operators/tools/chain-monitoring). -* For cost optimization strategies, refer to the [Fee calculation tools](/operators/chain-operators/tools/fee-calculator). -* Consider setting up the [op-challenger](/operators/chain-operators/tutorials/dispute-games) for a complete fault proof system. - -Your batcher is now operational and will continuously submit L2 transaction batches to L1! diff --git a/chain-operators/guides/deployment/validate-deployment.mdx b/chain-operators/guides/deployment/validate-deployment.mdx deleted file mode 100644 index dd5cd1ecd..000000000 --- a/chain-operators/guides/deployment/validate-deployment.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Validate your deployment -description: Learn how to validate your OP Stack deployment using op-validator ---- - -# Overview - -After deploying the L1 smart contracts for your OP Stack chain, it's crucial to verify that your deployment conforms to the standard configuration. -This guide walks you through using `op-validator` to validate your deployment against the Superchain standard. - -## Prerequisites - -* Complete deployment of L1 smart contracts using [op-deployer](/chain-operators/deploy/smart-contracts). -* Generate [genesis and rollup](/chain-operators/deploy/genesis) files. -* Install [op-validator](/chain-operators/tools/op-validator). - -## Validation process - - - - If you haven't already installed op-validator, follow the [installation instructions](/chain-operators/tools/op-validator#installation). - - - - You'll need the following information to validate your deployment: - - * **L1 RPC URL:** A reliable RPC endpoint for your L1 network - * **Absolute prestate:** The absolute prestate hash of your deployment - * **Proxy admin address:** Your chain's proxy admin contract address (not the proxy admin owner) - * **System config address:** Your chain's SystemConfig contract address - * **L2 chain ID:** The chain ID of your L2 network - - Use `op-deployer` to retrieve the following information: - - ```bash - # Get deployment information - op-deployer inspect l1 --workdir .deployer - ``` - - - - Run the op-validator with the appropriate version parameter matching your deployed contracts: - - ```bash - ./bin/op-validator validate \ - --l1-rpc-url "" \ - --absolute-prestate "" \ - --proxy-admin "" \ - --system-config "" \ - --l2-chain-id "" \ - --fail - ``` - - - - The validator will check multiple aspects of your deployment against the standard configuration: - - * Contract implementations and versions - * Proxy configurations - * System parameters - * Cross-component relationships - * Security settings - - If validation passes, you'll see a success message. If there are issues, you'll see error codes with descriptions like: - - | ERROR | DESCRIPTION | - | --------- | ------------------------------------------------------ | - | SYSCON-10 | SystemConfig version mismatch | - | SYSCON-40 | SystemConfig implementation address mismatch | - | L1xDM-10 | L1CrossDomainMessenger version mismatch | - | L1xDM-20 | L1CrossDomainMessenger implementation address mismatch | - | L1SB-10 | L1StandardBridge version mismatch | - | L1SB-20 | L1StandardBridge implementation address | - - - - If your deployment has validation errors: - - 1. Understand the errors - Review the error codes and descriptions. - 2. Consider redeployment - For critical issues, redeploying with corrected parameters may be necessary. - - - -## Next Steps - -* If you plan to join the Superchain, follow the [Standard Rollup Charter](/superchain/concepts/blockspace-charter). -* Configure [monitoring and maintenance](/operators/chain-operators/tools/chain-monitoring) -* Read the [op-deployer docs](/operators/chain-operators/tools/op-deployer) diff --git a/docs.json b/docs.json index ab9cd95d1..55c99078b 100644 --- a/docs.json +++ b/docs.json @@ -187,7 +187,7 @@ }, { "source": "/builders/chain-operators/overview", - "destination": "/operators/chain-operators/self-hosted" + "destination": "/" }, { "source": "/builders/chain-operators/configuration/batcher", @@ -239,7 +239,7 @@ }, { "source": "/stack/dev-net", - "destination": "/chain-operators/quickstarts/self-hosted" + "destination": "/" }, { "source": "/stack/protocol/deposit-flow", @@ -1027,7 +1027,7 @@ }, { "source": "/operators/chain-operators/self-hosted", - "destination": "/chain-operators/quickstarts/self-hosted" + "destination": "/" }, { "source": "/operators/chain-operators/tools", @@ -1083,7 +1083,7 @@ }, { "source": "/chain-operators/tutorials/chain-dev-net", - "destination": "/chain-operators/quickstarts/self-hosted" + "destination": "/" }, { "source": "/operators/chain-operators/tutorials/create-l2-rollup", @@ -1660,6 +1660,34 @@ { "source": "/concepts/security/fp-security", "destination": "/op-stack/fault-proofs/fp-security" + }, + { + "source": "chain-operators/guides/deployment/overview", + "destination": "/" + }, + { + "source": "/chain-operators/guides/deployment/smart-contracts", + "destination": "/chain-operators/tutorials/op-deployer-setup" + }, + { + "source": "/chain-operators/guides/deployment/genesis", + "destination": "/chain-operators/tools/op-deployer" + }, + { + "source": "/chain-operators/guides/deployment/validate-deployment", + "destination": "/chain-operators/tools/op-validator" + }, + { + "source": "/chain-operators/guides/deployment/sequencer-node", + "destination": "/chain-operators/tutorials/op-geth-setup" + }, + { + "source": "/chain-operators/guides/deployment/spin-batcher", + "destination": "/chain-operators/tutorials/op-batcher-setup" + }, + { + "source": "/chain-operators/guides/deployment/proposer-setup-guide", + "destination": "/chain-operators/tutorials/op-proposer-setup" } ], "navigation": { @@ -1668,16 +1696,14 @@ "tab": "Chain Operators", "groups": [ { - "group": "Quickstarts", + "group": "Quickstart", "pages": [ - "chain-operators/quickstarts/self-hosted", "index" ] }, { "group": "Guides", "pages": [ - "/chain-operators/deployment-guide", { "group": "Configuration", "pages": [ @@ -1687,18 +1713,6 @@ "chain-operators/guides/configuration/rollup" ] }, - { - "group": "Deployment", - "pages": [ - "chain-operators/guides/deployment/overview", - "chain-operators/guides/deployment/smart-contracts", - "chain-operators/guides/deployment/genesis", - "chain-operators/guides/deployment/validate-deployment", - "chain-operators/guides/deployment/sequencer-node", - "chain-operators/guides/deployment/spin-batcher", - "chain-operators/guides/deployment/proposer-setup-guide" - ] - }, { "group": "Features", "pages": [ diff --git a/index.mdx b/index.mdx index e34b5e079..07d99c0d6 100644 --- a/index.mdx +++ b/index.mdx @@ -1,217 +1,64 @@ --- title: "Deploy the OP Stack" +description: "Launch a scalable and customizable Layer 2 Rollup blockchain with Ethereum-grade security - powered by Optimism." mode: "wide" --- -

Launch scalable, customizable Layer 2s and apps with Ethereum-grade security - powered by the OP Stack.

- -
- +## Components - -
+The OP Stack is an open-source, modular, Ethereum Layer 2 rollup stack. +Before you deploy, it is important to understand how the key components and how they come together to create your blockchain. -
- +- **L1 Smart contracts**: A set of smart contracts to be deployed on Ethereum to bridge between the L1 and L2 domains and manage aspects of the rollup. +- **Sequencer**: A single privileged node that accept and derive user transactions on the network to construct the blockchain. +- **Batcher**: A sequencer service that publishes L2 transactions onto Ethereum. +Using Ethereum as a data availability layer, the OP Stack inherits Ethereum's security properties by allowing any node to derive the state of the L2 blockchain from L1. +- **Proposer**: A service responsible for publishing the L2 state root to Ethereum which enables user withdrawals of assets. +- **Challenger**: The challenger enforces network security by disputing invalid state roots that have been posted to Ethereum. - -
+## Deployment + +The following section will walk you through the sequence of steps a chain operator will follow to begin sequencing a chain. + + + + Using a CLI tool called [op-deployer](/chain-operators/tools/op-deployer) you will configure your chain and then deploy the smart contracts on Ethereum. + + + After deploying the L1 smart contracts you will use [op-validator](/chain-operators/tools/op-validator) to verify that your deployment configurations what you expect. + + + After deploying the L1 smart contracts, you will use [op-deployer](/chain-operators/tools/op-deployer) to generate two files necessary to run nodes on the L2 network: + + * **Genesis file** (`genesis.json`): Initializes the execution client (`op-geth`) + * **Rollup configuration file** (`rollup.json`): Configures the consensus client (`op-node`) + + These files contain all the essential information your services need to interact with Ethereum and the system contracts you deployed. + + + To begin sequencing transactions and building blocks, you will then run an **execution client** and **consensus client** that come together as your **sequencer node**. + + + Next you will run `op-batcher` which will publish user transactions on Ethereum. + + + Then you will run `op-proposer` to publish the L2 state root on Ethereum to enable withdrawals back to Ethereum. + + + Finally you will run `op-challenger` to monitor and dispute any invalid L2 state roots that have been posted. + + + +## Next Steps + +Of course there is a lot more work to do ensure you're operating a highly available chain. +Take a look at some of the [chain operator best practices](/chain-operators/guides/management/best-practices) to get an idea of some of the things you'll need to keep in mind. \ No newline at end of file