From 911433daa769817aafef58903deeee42ba8a4d03 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Fri, 11 Apr 2025 11:20:42 +0100 Subject: [PATCH 01/14] updated the bootstrap codebase --- .../chain-operators/tools/Deployer.md | 781 ++++++++++++++++++ 1 file changed, 781 insertions(+) create mode 100644 pages/operators/chain-operators/tools/Deployer.md diff --git a/pages/operators/chain-operators/tools/Deployer.md b/pages/operators/chain-operators/tools/Deployer.md new file mode 100644 index 000000000..3240f26b5 --- /dev/null +++ b/pages/operators/chain-operators/tools/Deployer.md @@ -0,0 +1,781 @@ +# Deployer + +`op-deployer` simplifies the process of deploying the OP Stack. It works similarly to [Terraform](https://www.terraform.io/). Like Terraform, you define a declarative config file called an "**intent**," then run a command to apply the intent to your chain. `op-deployer` will compare the state of your chain against the intent, and make whatever changes are necessary for them to match. In its current state, it is intended to deploy new standard chains that utilize the Superchain wide contracts. + +## Installation + +There are multiple ways to install `op-deployer`: + +### Option 1: Download pre-built binary (Recommended) + +The recommended way to install `op-deployer` is to download the latest release from the monorepo's [release page](https://github.com/ethereum-optimism/optimism/releases). + +1. Go to https://github.com/ethereum-optimism/optimism/releases +2. Find the latest release that includes op-deployer +3. Download the appropriate binary for your operating system +4. Extract the binary to a location on your system PATH +5. Make the binary executable (on Unix-based systems): + + ```bash + chmod +x /path/to/op-deployer + ``` + +6. Verify installation: + + ```bash + op-deployer --version + ``` + + +### Option 2: Build from source + +If you prefer to build from source: + +1. Clone the Optimism repository: + + ```bash + git clone https://github.com/ethereum-optimism/optimism.git + cd optimism + ``` + +2. Build the op-deployer binary: + + ```bash + make op-deployer + ``` + +3. The binary will be available at `./bin/op-deployer` + +## Deployment usage + +> ⚠️ WARNING: Gas cost ⚠️ +> +> +> Deploying an OP Stack chain can require significant gas. Ensure your deployer wallet has at least 3.5 ETH for deployment on mainnet or testnet. The exact amount will vary based on gas prices and configuration. +> + +The base use case for `op-deployer` is deploying new OP Chains. This process is broken down into three steps: + +### `init`: configure your chain + +To get started with `op-deployer`, create an intent file that defines your desired chain configuration. Use the built-in `op-deployer` utility to generate this file: + +> 📌 op-deployer uses a declarative intent file to determine how a new chain should be configured. Then, it runs through a deployment pipeline to actually deploy the chain. +> + +```bash +./bin/op-deployer init --l1-chain-id 11155111 --l2-chain-ids --workdir .deployer + +``` + +Replace `` with the exact value. + +This command will create a directory called `.deployer` in your current working directory containing the intent file and an empty `state.json` file. `state.json` is populated with the results of your deployment, and never needs to be edited directly. + +Your intent file will need to be modified to your parameters, but it will initially look something like this: + +> ⚠️ Do not use the default addresses in the intent for a production chain! They are generated from the test... junk mnemonic. Any funds they hold will be stolen on a live chain. +> + +```toml +configType = "standard-overrides" +l1ChainID = 11155111# The chain ID of Sepolia (L1) you'll be deploying to. +fundDevAccounts = true# Whether or not to fund dev accounts using the test... junk mnemonic on L2. +l1ContractsLocator = "tag://op-contracts/v1.8.0-rc.4"# L1 smart contracts versions +l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts"# L2 smart contracts versions# Delete this table if you are using the shared Superchain contracts on the L1# If you are deploying your own SuperchainConfig and ProtocolVersions contracts, fill in these details +[superchainRoles] + proxyAdminOwner = "0x1eb2ffc903729a0f03966b917003800b145f56e2" + protocolVersionsOwner = "0x79add5713b383daa0a138d3c4780c7a1804a8090" + guardian = "0x7a50f00e8d05b95f98fe38d8bee366a7324dcf7e" + +# List of L2s to deploy. op-deployer can deploy multiple L2s at once +[[chains]] +# Your chain's ID, encoded as a 32-byte hex string + id = "0x00000000000000000000000000000000000000000000000000000a25406f3e60" +# Update the fee recipient contract + baseFeeVaultRecipient = "0x100f829718B5Be38013CC7b29c5c62a08D00f1ff" + l1FeeVaultRecipient = "0xbAEaf33e883068937aB4a50871f2FD52e241013A" + sequencerFeeVaultRecipient = "0xd0D5D18F0ebb07B7d728b14AAE014eedA814d6BD" + eip1559DenominatorCanyon = 250 + eip1559Denominator = 50 + eip1559Elasticity = 6 +# Various ownership roles for your chain. When you use op-deployer init, these roles are generated using the# test... junk mnemonic. You should replace these with your own addresses for production chains. + [chains.roles] + l1ProxyAdminOwner = "0xdf5a644aed1b5d6cE0DA2aDd778bc5f39d97Ac88" + l2ProxyAdminOwner = "0xC40445CD88dDa2A410F86F6eF8E00fd52D8381FD" + systemConfigOwner = "0xB32296E6929F2507dB8153A64b036D175Ac6E89e" + unsafeBlockSigner = "0xA53526b516df4eEe3791734CE85311569e0eAD78" + batcher = "0x8680d36811420359093fd321ED386a6e76BE2AF3" + proposer = "0x41b3B204099771aDf857F826015703A1030b6675" + challenger = "0x7B51A480dAeE699CA3a4F68F9AAA434452112eF7" + +``` + +### Understanding the intent.toml fields + +Here's an explanation of the key fields in the intent file: + +**Global configuration:** + +- `configType`: Type of configuration to use ("standard-overrides" is most common) +- `l1ChainID`: The chain ID of the L1 network you're deploying to +- `fundDevAccounts`: Whether to fund development accounts on L2 (set to false for production) +- `l1ContractsLocator`: The version of L1 contracts to deploy +- `l2ContractsLocator`: The version of L2 contracts to deploy + +**Superchain roles:** + +- `proxyAdminOwner`: Address that can upgrade Superchain-wide contracts +- `protocolVersionsOwner`: Address that can update protocol versions +- `guardian`: Address with emergency powers (e.g., pausing withdrawals) + +**Chain-specific configuration:** + +- `id`: Unique identifier for your chain +- `baseFeeVaultRecipient`: Address that receives base fees +- `l1FeeVaultRecipient`: Address that receives L1 fees +- `sequencerFeeVaultRecipient`: Address that receives sequencer fees +- `eip1559DenominatorCanyon`, `eip1559Denominator`, `eip1559Elasticity`: Parameters for fee calculation + +**Chain roles:** + +- `l1ProxyAdminOwner`: Address that owns the L1 proxy admin contract +- `l2ProxyAdminOwner`: Address that owns the L2 proxy admin contract +- `systemConfigOwner`: Address that can update system configuration +- `unsafeBlockSigner`: Address that signs blocks in unsafe mode +- `batcher`: Address that batches transactions from L2 to L1 +- `proposer`: Address that proposes output roots +- `challenger`: Address that can challenge invalid output roots + +By default, `op-deployer` will fill in all other configuration variables with those that match the [standard configuration](https://specs.optimism.io/protocol/configurability.html?utm_source=op-docs&utm_medium=docs). You can override these default settings by adding them to your intent file using the table below: + +```toml +toml +[globalDeployOverrides] + l2BlockTime = 1# 1s L2blockTime is also standard, op-deployer defaults to 2s + +``` + +You can also do chain by chain configurations in the `chains` table. + +### `apply`: deploy your chain + +> 📌 Hardware wallets are not supported, but you can use ephemeral hot wallets since this deployer key has no privileges. +> + +Now that you've created your intent file, you can apply it to your chain to deploy the L1 smart contracts: + +```bash +bash +[ ] + +./bin/op-deployer apply --workdir .deployer --l1-rpc-url --private-key + +``` + +- Replace `` with your `L1_RPC_URL` and `` with your private key + +This command will deploy the OP Stack to L1. It will deploy all L2s specified in the intent file. Superchain +configuration will be set to the Superchain-wide defaults - i.e., your chain will be opted into the [Superchain pause](https://specs.optimism.io/protocol/superchain-config.html#pausability) +and will use the same [protocol versions](https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/superchain-upgrades.md) +address as other chains on the Superchain. + +### `verify`: verify contract source code on block explorers + +After deploying your contracts, you can verify them on block explorers like Etherscan: + +```bash +bash +[ ] + +op-deployer verify --workdir .deployer --l1-rpc-url --l1-explorer-api-url --l1-explorer-api-key + +``` + +The verification tool supports various options: + +- `-workdir`: Specifies the directory containing the deployment state +- `-l1-rpc-url`: RPC URL for the L1 chain +- `-l1-explorer-api-url`: API URL for the L1 block explorer (e.g., https://api-sepolia.etherscan.io/api for Sepolia) +- `-l1-explorer-api-key`: API key for the L1 block explorer +- `-retry`: Retry failed verifications +- `-overwrite`: Overwrite existing verifications +- `-skip-already-verified`: Skip contracts that are already verified +- `-retries`: Number of retries for failed verifications (default: 3) +- `-retry-delay`: Delay between retries in seconds (default: 1s) +- `-timeout`: Timeout for verification requests in seconds (default: 30s) +- `-contract-filter`: Regex filter for contract names to verify + +Example usage: + +```bash +bash +[ ] + +op-deployer verify --workdir .deployer \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_INFURA_KEY \ + --l1-explorer-api-url https://api-sepolia.etherscan.io/api \ + --l1-explorer-api-key YOUR_ETHERSCAN_API_KEY \ + --skip-already-verified + +``` + +### `inspect`: generate genesis files and chain information + +> 📌 To add your chain to the Superchain Registry you will need to provide the chain artifacts. To get these chain artifacts, you will need to write the output of these commands to new files. +> + +Inspect the `state.json` file by navigating to your working directory. With the contracts deployed, generate the genesis and rollup configuration files by running the following commands: + +```bash +bash +[ ] + +./bin/op-deployer inspect genesis --workdir .deployer > .deployer/genesis.json +./bin/op-deployer inspect rollup --workdir .deployer > .deployer/rollup.json + +``` + +Now that you have your `genesis.json` and `rollup.json` you can spin up a node on your network. You can also use the following inspect subcommands to get additional chain artifacts: + +```bash +bash +[ ] + +./bin/op-deployer inspect l1 --workdir .deployer # outputs all L1 contract addresses for an L2 chain +./bin/op-deployer inspect deploy-config --workdir .deployer # outputs the deploy config for an L2 chain +./bin/op-deployer inspect l2-semvers --workdir .deployer # outputs the semvers for all L2 chains + +``` + +# Bootstrap usage + +`op-deployer` provides a set of bootstrap commands specifically designed for initializing a new superchain on an L1 network. These commands are essential when you're setting up a completely new superchain environment rather than deploying a new chain on an existing superchain. + +## Bootstrap process overview + +When bootstrapping a new superchain, you typically need to follow this process: + +1. **Deploy proxy admin** (`bootstrap proxy`): Sets up the `ERC-1967` proxy for the superchain management contracts. +2. **Deploy Superchain configuration** (`bootstrap superchain`): Creates the foundational superchain configuration contracts. +3. **Deploy implementations** (`bootstrap implementations`): Deploys the implementation contracts needed for the dispute system. +4. **Deploy validator** (`bootstrap validator`): Deploys the `StandardValidator` for the superchain. + +## Bootstrap proxy + +The `bootstrap proxy` command deploys a new `ERC-1967` proxy admin, which is required for upgradeability of the superchain contracts. + +### Command usage + +```bash +op-deployer bootstrap proxy \ + --l1-rpc-url \ + --private-key \ + --artifacts-locator \ + --proxy-owner \ + --outfile proxy-output.json + +``` + +### Parameters + +``` +ParameterDescriptionRequiredExample--l1-rpc-urlRPC URL for the L1 chainYeshttps://sepolia.infura.io/v3/YOUR_API_KEY--private-keyPrivate key for transaction signingYes0xabcd...1234--artifacts-locatorLocation of contract artifactsYesfile:///path/to/artifacts ortag://op-contracts/v1.8.0-rc.4--proxy-ownerAddress that will own the proxyYes0x1234...abcd--outfileFile to write output JSONNoproxy-output.json--cache-dirDirectory to cache artifactsNo.artifacts-cache +``` + +### Example + +```bash +bash +[ ] + +op-deployer bootstrap proxy \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --proxy-owner 0xYOUR_OWNER_ADDRESS \ + --outfile proxy-output.json + +``` + +### Output + +The command outputs a JSON file containing the deployed proxy contract address: + +```json +json +[ ] + +{ + "ProxyAdmin": "0x123...abc" +} + +``` + +## Bootstrap Superchain + +The `bootstrap superchain` command initializes the core superchain configuration contracts that govern the entire superchain ecosystem. + +### Command Usage + +```bash +bash +[ ] + +op-deployer bootstrap superchain \ + --l1-rpc-url \ + --private-key \ + --artifacts-locator \ + --superchain-proxy-admin-owner \ + --protocol-versions-owner \ + --guardian \ + --paused \ + --required-protocol-version \ + --recommended-protocol-version \ + --outfile superchain-output.json + +``` + +### Parameters + +``` +ParameterDescriptionRequiredExample--l1-rpc-urlRPC URL for the L1 chainYeshttps://sepolia.infura.io/v3/YOUR_API_KEY--private-keyPrivate key for transaction signingYes0xabcd...1234--artifacts-locatorLocation of contract artifactsYesfile:///path/to/artifacts ortag://op-contracts/v1.8.0-rc.4--superchain-proxy-admin-ownerAddress that owns the superchain proxy adminYes0x1234...abcd--protocol-versions-ownerAddress that can update protocol versionsYes0x2345...bcde--guardianAddress with emergency powersYes0x3456...cdef--pausedWhether the superchain starts pausedNo (defaults to false)false--required-protocol-versionMinimum required protocol versionYes1.0.0--recommended-protocol-versionRecommended protocol versionYes1.0.0--outfileFile to write output JSONNo (defaults to stdout)superchain-output.json--cache-dirDirectory to cache artifactsNo.artifacts-cache +``` + +### Example + +```bash +bash +[ ] + +op-deployer bootstrap superchain \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --superchain-proxy-admin-owner 0xADMIN_OWNER_ADDRESS \ + --protocol-versions-owner 0xVERSIONS_OWNER_ADDRESS \ + --guardian 0xGUARDIAN_ADDRESS \ + --paused false \ + --required-protocol-version 1.0.0 \ + --recommended-protocol-version 1.0.0 \ + --outfile superchain-output.json + +``` + +### Output + +The command outputs a JSON file containing the deployed superchain contract addresses: + +```json +json +[ ] + +{ + "SuperchainConfig": "0x123...abc", + "ProtocolVersions": "0x456...def" +} + +``` + +## Bootstrap Implementations + +The `bootstrap implementations` command deploys the implementation contracts required for the dispute system of the OP Stack. + +### Command Usage + +```bash +bash +[ ] + +op-deployer bootstrap implementations \ + --l1-rpc-url \ + --private-key \ + --artifacts-locator \ + --l1-contracts-release \ + --mips-version <1|2> \ + --withdrawal-delay-seconds \ + --min-proposal-size-bytes \ + --challenge-period-seconds \ + --proof-maturity-delay-seconds \ + --dispute-game-finality-delay-seconds \ + --superchain-config-proxy
\ + --protocol-versions-proxy
\ + --upgrade-controller
\ + --use-interop \ + --outfile implementations-output.json + +``` + +### Parameters + +``` +ParameterDescriptionRequiredDefaultExample--l1-rpc-urlRPC URL for the L1 chainYes-https://sepolia.infura.io/v3/YOUR_API_KEY--private-keyPrivate key for transaction signingYes-0xabcd...1234--artifacts-locatorLocation of contract artifactsYes-file:///path/to/artifacts--l1-contracts-releaseVersion tag for L1 contractsYes-v1.8.0-rc.4--mips-versionMIPS version for the fault proof system (1 or 2)NoFrom standard config2--withdrawal-delay-secondsDelay for withdrawals in secondsNoFrom standard config604800 (1 week)--min-proposal-size-bytesMinimum size for proposals in bytesNoFrom standard config1--challenge-period-secondsChallenge period in secondsNoFrom standard config604800 (1 week)--proof-maturity-delay-secondsProof maturity delay in secondsNoFrom standard config60--dispute-game-finality-delay-secondsDispute game finality delay in secondsNoFrom standard config604800 (1 week)--superchain-config-proxyAddress of superchain config proxyYes-Result from superchain command--protocol-versions-proxyAddress of protocol versions proxyYes-Result from superchain command--upgrade-controllerAddress of upgrade controllerYes-0x0000...0000--use-interopWhether to enable interoperability featuresNofalsetrue--outfileFile to write output JSONNostdoutimplementations-output.json--cache-dirDirectory to cache artifactsNo-.artifacts-cache +``` + +### Understanding MIPS Version + +The MIPS version parameter determines which version of the Cannon MIPS VM to use for fault proofs: + +- **MIPS Version 1**: Original implementation, suitable for most deployments +- **MIPS Version 2**: Enhanced implementation with optimizations, generally preferred for new deployments + +For most new deployments, MIPS Version 2 is recommended unless you have specific compatibility requirements. + +### Example + +```bash +bash +[ ] + +op-deployer bootstrap implementations \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --l1-contracts-release v1.8.0-rc.4 \ + --mips-version 2 \ + --withdrawal-delay-seconds 604800 \ + --min-proposal-size-bytes 1 \ + --challenge-period-seconds 604800 \ + --proof-maturity-delay-seconds 60 \ + --dispute-game-finality-delay-seconds 604800 \ + --superchain-config-proxy 0xSUPERCHAIN_CONFIG_ADDRESS \ + --protocol-versions-proxy 0xPROTOCOL_VERSIONS_ADDRESS \ + --upgrade-controller 0x0000000000000000000000000000000000000000 \ + --outfile implementations-output.json + +``` + +### Output + +The command outputs a JSON file containing the deployed implementation contract addresses: + +```json +json +[ ] + +{ + "L1CrossDomainMessenger": "0x123...abc", + "L1ERC721Bridge": "0x234...bcd", + "L1StandardBridge": "0x345...cde", + "L2OutputOracle": "0x456...def", + "OptimismPortal": "0x567...efg", + "OptimismMintableERC20Factory": "0x678...fgh", + "AddressManager": "0x789...ghi", + "ProxyAdmin": "0x89a...hij", + "SystemConfig": "0x9ab...ijk", + "DisputeGameFactory": "0xabc...jkl" +} + +``` + +## Bootstrap Validator + +The `bootstrap validator` command deploys the validator contracts required for the superchain. This is typically done after deploying the implementations. + +### Command Usage + +```bash +bash +[ ] + +op-deployer bootstrap validator \ + --l1-rpc-url \ + --private-key \ + --artifacts-locator \ + --config \ + --outfile validator-output.json + +``` + +### Parameters + +``` +ParameterDescriptionRequiredExample--l1-rpc-urlRPC URL for the L1 chainYeshttps://sepolia.infura.io/v3/YOUR_API_KEY--private-keyPrivate key for transaction signingYes0xabcd...1234--artifacts-locatorLocation of contract artifactsYesfile:///path/to/artifacts--configPath to JSON configuration fileYesvalidator-config.json--outfileFile to write output JSONNovalidator-output.json--cache-dirDirectory to cache artifactsNo.artifacts-cache +``` + +### Configuration File Format + +The configuration file should be a JSON file with the following structure: + +```json +json +[ ] + +{ + "release": "v1.8.0-rc.4", + "superchainConfig": "0x123...abc", + "l1PAOMultisig": "0x234...bcd", + "challenger": "0x345...cde", + "superchainConfigImpl": "0x456...def", + "protocolVersionsImpl": "0x567...efg", + "l1ERC721BridgeImpl": "0x678...fgh", + "optimismPortalImpl": "0x789...ghi", + "ethLockboxImpl": "0x89a...hij", + "systemConfigImpl": "0x9ab...ijk", + "optimismMintableERC20FactoryImpl": "0xabc...jkl", + "l1CrossDomainMessengerImpl": "0xbcd...klm", + "l1StandardBridgeImpl": "0xcde...lmn", + "disputeGameFactoryImpl": "0xdef...mno", + "anchorStateRegistryImpl": "0xefg...nop", + "delayedWETHImpl": "0xfgh...opq", + "mipsImpl": "0xghi...pqr", + "withdrawalDelaySeconds": 604800 +} + +``` + +Most of these addresses should come from the output of the previous bootstrap commands, particularly the `bootstrap implementations` command. + +### Example + +```bash +bash +[ ] + +op-deployer bootstrap validator \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --config validator-config.json \ + --outfile validator-output.json + +``` + +### Output + +The command outputs a JSON file containing the deployed validator contract address: + +```json +json +[ ] + +{ + "validator": "0x123...abc" +} + +``` + +## Working with Artifacts + +The `artifacts-locator` parameter specifies where the contract deployment artifacts are located. There are several ways to provide artifacts: + +### Using Local Files + +To use local artifacts (recommended for production or if you're experiencing issues with remote artifacts): + +1. Clone the contracts repository: + + ```bash + bash + [ ] + + git clone https://github.com/ethereum-optimism/optimism.git + cd optimism + git checkout v1.8.0-rc.4# Use the desired version + + ``` + +2. Build the artifacts: + + ```bash + bash + [ ] + + cd packages/contracts-bedrock + pnpm install + pnpm build + + ``` + +3. Use the local path in your command: + + ```bash + bash + [ ] + + --artifacts-locator file:///absolute/path/to/optimism/packages/contracts-bedrock/artifacts + + ``` + + +### Using Tagged Artifacts + +For development or testing, you can try using tagged artifacts (but note there are known issues with this approach): + +```bash +bash +[ ] + +--artifacts-locator tag://op-contracts/v1.8.0-rc.4 + +``` + +If you encounter the error `Application failed: failed to parse artifacts URL: unsupported tag`, you'll need to use the local files method described above. + +## Complete Bootstrap Workflow Example + +Here's a step-by-step workflow to bootstrap a complete superchain from scratch: + +1. **Deploy Proxy Admin**: + + ```bash + bash + [ ] + + op-deployer bootstrap proxy \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --proxy-owner 0xYOUR_OWNER_ADDRESS \ + --outfile proxy-output.json + + ``` + +2. **Store the proxy admin address** for use in the next steps: + + ```bash + bash + [ ] + + PROXY_ADMIN=$(jq -r '.ProxyAdmin' proxy-output.json) + echo "Proxy Admin: $PROXY_ADMIN" + + ``` + +3. **Deploy Superchain Configuration**: + + ```bash + bash + [ ] + + op-deployer bootstrap superchain \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --superchain-proxy-admin-owner 0xADMIN_OWNER_ADDRESS \ + --protocol-versions-owner 0xVERSIONS_OWNER_ADDRESS \ + --guardian 0xGUARDIAN_ADDRESS \ + --paused false \ + --required-protocol-version 1.0.0 \ + --recommended-protocol-version 1.0.0 \ + --outfile superchain-output.json + + ``` + +4. **Store the superchain configuration addresses**: + + ```bash + bash + [ ] + + SUPERCHAIN_CONFIG=$(jq -r '.SuperchainConfig' superchain-output.json) + PROTOCOL_VERSIONS=$(jq -r '.ProtocolVersions' superchain-output.json) + echo "Superchain Config: $SUPERCHAIN_CONFIG" + echo "Protocol Versions: $PROTOCOL_VERSIONS" + + ``` + +5. **Deploy Implementations**: + + ```bash + bash + [ ] + + op-deployer bootstrap implementations \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --l1-contracts-release v1.8.0-rc.4 \ + --mips-version 2 \ + --withdrawal-delay-seconds 604800 \ + --min-proposal-size-bytes 1 \ + --challenge-period-seconds 604800 \ + --proof-maturity-delay-seconds 60 \ + --dispute-game-finality-delay-seconds 604800 \ + --superchain-config-proxy $SUPERCHAIN_CONFIG \ + --protocol-versions-proxy $PROTOCOL_VERSIONS \ + --upgrade-controller 0x0000000000000000000000000000000000000000 \ + --outfile implementations-output.json + + ``` + +6. **Extract implementation addresses** for the validator configuration: + + ```bash + bash + [ ] + + # Example of extracting implementation addresses + L1_CROSS_DOMAIN_MESSENGER_IMPL=$(jq -r '.L1CrossDomainMessenger' implementations-output.json) + L1_ERC721_BRIDGE_IMPL=$(jq -r '.L1ERC721Bridge' implementations-output.json) + # ... extract other implementation addresses similarly + + ``` + +7. **Create a validator configuration file**: + + ```bash + bash + [ ] + + cat > validator-config.json << EOF + { + "release": "v1.8.0-rc.4", + "superchainConfig": "$SUPERCHAIN_CONFIG", + "l1PAOMultisig": "0xYOUR_PAO_MULTISIG_ADDRESS", + "challenger": "0xYOUR_CHALLENGER_ADDRESS", + "superchainConfigImpl": "$SUPERCHAIN_CONFIG_IMPL", + "protocolVersionsImpl": "$PROTOCOL_VERSIONS_IMPL", + "l1ERC721BridgeImpl": "$L1_ERC721_BRIDGE_IMPL", + "optimismPortalImpl": "$OPTIMISM_PORTAL_IMPL", + "ethLockboxImpl": "$ETH_LOCKBOX_IMPL", + "systemConfigImpl": "$SYSTEM_CONFIG_IMPL", + "optimismMintableERC20FactoryImpl": "$OPTIMISM_MINTABLE_ERC20_FACTORY_IMPL", + "l1CrossDomainMessengerImpl": "$L1_CROSS_DOMAIN_MESSENGER_IMPL", + "l1StandardBridgeImpl": "$L1_STANDARD_BRIDGE_IMPL", + "disputeGameFactoryImpl": "$DISPUTE_GAME_FACTORY_IMPL", + "anchorStateRegistryImpl": "$ANCHOR_STATE_REGISTRY_IMPL", + "delayedWETHImpl": "$DELAYED_WETH_IMPL", + "mipsImpl": "$MIPS_IMPL", + "withdrawalDelaySeconds": 604800 + } + EOF + + ``` + +8. **Deploy Validator**: + + ```bash + bash + [ ] + + op-deployer bootstrap validator \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --config validator-config.json \ + --outfile validator-output.json + + ``` + +9. Once all these commands have successfully completed, you'll have bootstrapped the core components needed for a new superchain. You can now proceed to deploy individual chains using the standard `op-deployer apply` command. + +## Troubleshooting + +### Issue: Unsupported Tag Error + +If you encounter an error like `Application failed: failed to parse artifacts URL: unsupported tag` when using `tag://` format: + +**Solution**: Use local artifacts as described in the "Working with Artifacts" section. + +### Issue: MIPS Version Selection Error + +If you encounter an error indicating that MIPS version must be 1 or 2: + +**Solution**: Ensure you're specifying exactly `1` or `2` as the MIPS version value, not any other number. + +### Issue: Transaction Gas Issues + +If transactions fail due to gas limits or costs: + +**Solution**: Ensure your deployer account has sufficient ETH (at least 1 ETH for bootstrapping operations), and consider using a network with lower gas costs for testing. \ No newline at end of file From 0408a3ab995c8ba3387a926ce3c8fc48e2dbcc39 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Mon, 14 Apr 2025 16:56:53 +0100 Subject: [PATCH 02/14] updated docs --- .../chain-operators/tools/Deployer.md | 604 ++---------------- 1 file changed, 61 insertions(+), 543 deletions(-) diff --git a/pages/operators/chain-operators/tools/Deployer.md b/pages/operators/chain-operators/tools/Deployer.md index 3240f26b5..0804fafc7 100644 --- a/pages/operators/chain-operators/tools/Deployer.md +++ b/pages/operators/chain-operators/tools/Deployer.md @@ -14,13 +14,9 @@ The recommended way to install `op-deployer` is to download the latest release f 2. Find the latest release that includes op-deployer 3. Download the appropriate binary for your operating system 4. Extract the binary to a location on your system PATH -5. Make the binary executable (on Unix-based systems): - - ```bash - chmod +x /path/to/op-deployer - ``` + -6. Verify installation: +5. Verify installation: ```bash op-deployer --version @@ -54,7 +50,7 @@ If you prefer to build from source: > Deploying an OP Stack chain can require significant gas. Ensure your deployer wallet has at least 3.5 ETH for deployment on mainnet or testnet. The exact amount will vary based on gas prices and configuration. > -The base use case for `op-deployer` is deploying new OP Chains. This process is broken down into three steps: +The base use case for `op-deployer` is deploying new OP Chains. This process is broken down into four steps: ### `init`: configure your chain @@ -78,6 +74,7 @@ Your intent file will need to be modified to your parameters, but it will initia > ```toml +deploymentStrategy = "live" configType = "standard-overrides" l1ChainID = 11155111# The chain ID of Sepolia (L1) you'll be deploying to. fundDevAccounts = true# Whether or not to fund dev accounts using the test... junk mnemonic on L2. @@ -117,6 +114,7 @@ Here's an explanation of the key fields in the intent file: **Global configuration:** +- `deploymentStrategy`: Used to deploy both to live chains and L1 genesis files. Valid values are `live` and `genesis`. - `configType`: Type of configuration to use ("standard-overrides" is most common) - `l1ChainID`: The chain ID of the L1 network you're deploying to - `fundDevAccounts`: Whether to fund development accounts on L2 (set to false for production) @@ -127,30 +125,59 @@ Here's an explanation of the key fields in the intent file: - `proxyAdminOwner`: Address that can upgrade Superchain-wide contracts - `protocolVersionsOwner`: Address that can update protocol versions -- `guardian`: Address with emergency powers (e.g., pausing withdrawals) +- `guardian`: Address authorized to pause L1 withdrawals from contracts, blacklist dispute games, and set the respected game type in the `OptimismPortal` **Chain-specific configuration:** - `id`: Unique identifier for your chain -- `baseFeeVaultRecipient`: Address that receives base fees -- `l1FeeVaultRecipient`: Address that receives L1 fees +- `baseFeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `BaseFeeVault` +- `l1FeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `L1FeeVault` - `sequencerFeeVaultRecipient`: Address that receives sequencer fees - `eip1559DenominatorCanyon`, `eip1559Denominator`, `eip1559Elasticity`: Parameters for fee calculation **Chain roles:** -- `l1ProxyAdminOwner`: Address that owns the L1 proxy admin contract -- `l2ProxyAdminOwner`: Address that owns the L2 proxy admin contract -- `systemConfigOwner`: Address that can update system configuration -- `unsafeBlockSigner`: Address that signs blocks in unsafe mode +- `l1ProxyAdminOwner`: Address authorized to update the L1 Proxy Admin +- `l2ProxyAdminOwner`: Address authorized to upgrade protocol contracts via calls to the `ProxyAdmin`. This is the aliased L1 ProxyAdmin owner address. +- `systemConfigOwner`: Address authorized to change values in the `SystemConfig` contract. All configuration is stored on L1 and picked up by L2 as part of the [derivation](https://specs.optimism.io/protocol/derivation.html) of the L2 chain +- `unsafeBlockSigner`: Address which authenticates the unsafe/pre-submitted blocks for a chain at the P2P layer - `batcher`: Address that batches transactions from L2 to L1 -- `proposer`: Address that proposes output roots -- `challenger`: Address that can challenge invalid output roots +- `proposer`: Address which can create and interact with [permissioned dispute games](https://specs.optimism.io/fault-proof/stage-one/bridge-integration.html#permissioned-faultdisputegame) on L1. +- `challenger`: Address Account which can interact with existing permissioned dispute games + +### Contract locator schemes + +op-deployer uses contract locators to find contract artifacts to deploy. +Locators are just URLs under the hood. +The `l1ContractsLocator` and `l2ContractsLocator` fields support several schemes for specifying where to find the contract implementations: + +* `tag://` - References a specific tagged release of the contracts (e.g., `tag://op-contracts/v1.8.0-rc.4`). In this case, the contracts bytecode will be downloaded from a fixed bytecode bundle on GCS. +* `file://` - Points to a local Forge build artifacts directory. Must point to the `forge-artifacts` directory containing the compiled contract artifacts. +This is useful for local development, since you can point it at your local monorepo +e.g. `--artifacts-locator file:///Users/username/code/optimism/packages/contracts-bedrock/forge-artifacts/` +* `http://` or `https://` - Points to a target directory containing contract artifacts. The URL should directly reference the directory containing the `forge-artifacts` directory, in this case, the bytecode will be downloaded from the URL specified. + + +When using any scheme other than `tag://`, you must set `configType` to either `custom` or `standard-overrides` in your intent file. + + +For example: + +```toml +# When using tag:// scheme +configType = "standard-overrides" +l1ContractsLocator = "tag://op-contracts/v1.8.0-rc.4" +l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts" + +# When using other schemes (file://, http://, https://) +configType = "custom" # or "standard-overrides" +l1ContractsLocator = "file:///path/to/local/op-contracts/v1.8.0-rc.4/forge-artifacts" +l2ContractsLocator = "https://example.com/op-contracts/v1.7.0-beta.1+l2-contracts.tar.gz" +``` By default, `op-deployer` will fill in all other configuration variables with those that match the [standard configuration](https://specs.optimism.io/protocol/configurability.html?utm_source=op-docs&utm_medium=docs). You can override these default settings by adding them to your intent file using the table below: ```toml -toml [globalDeployOverrides] l2BlockTime = 1# 1s L2blockTime is also standard, op-deployer defaults to 2s @@ -185,9 +212,6 @@ address as other chains on the Superchain. After deploying your contracts, you can verify them on block explorers like Etherscan: ```bash -bash -[ ] - op-deployer verify --workdir .deployer --l1-rpc-url --l1-explorer-api-url --l1-explorer-api-key ``` @@ -209,9 +233,6 @@ The verification tool supports various options: Example usage: ```bash -bash -[ ] - op-deployer verify --workdir .deployer \ --l1-rpc-url https://sepolia.infura.io/v3/YOUR_INFURA_KEY \ --l1-explorer-api-url https://api-sepolia.etherscan.io/api \ @@ -228,9 +249,6 @@ op-deployer verify --workdir .deployer \ Inspect the `state.json` file by navigating to your working directory. With the contracts deployed, generate the genesis and rollup configuration files by running the following commands: ```bash -bash -[ ] - ./bin/op-deployer inspect genesis --workdir .deployer > .deployer/genesis.json ./bin/op-deployer inspect rollup --workdir .deployer > .deployer/rollup.json @@ -248,534 +266,34 @@ bash ``` -# Bootstrap usage - -`op-deployer` provides a set of bootstrap commands specifically designed for initializing a new superchain on an L1 network. These commands are essential when you're setting up a completely new superchain environment rather than deploying a new chain on an existing superchain. - -## Bootstrap process overview - -When bootstrapping a new superchain, you typically need to follow this process: - -1. **Deploy proxy admin** (`bootstrap proxy`): Sets up the `ERC-1967` proxy for the superchain management contracts. -2. **Deploy Superchain configuration** (`bootstrap superchain`): Creates the foundational superchain configuration contracts. -3. **Deploy implementations** (`bootstrap implementations`): Deploys the implementation contracts needed for the dispute system. -4. **Deploy validator** (`bootstrap validator`): Deploys the `StandardValidator` for the superchain. - -## Bootstrap proxy - -The `bootstrap proxy` command deploys a new `ERC-1967` proxy admin, which is required for upgradeability of the superchain contracts. - -### Command usage - -```bash -op-deployer bootstrap proxy \ - --l1-rpc-url \ - --private-key \ - --artifacts-locator \ - --proxy-owner \ - --outfile proxy-output.json - -``` - -### Parameters - -``` -ParameterDescriptionRequiredExample--l1-rpc-urlRPC URL for the L1 chainYeshttps://sepolia.infura.io/v3/YOUR_API_KEY--private-keyPrivate key for transaction signingYes0xabcd...1234--artifacts-locatorLocation of contract artifactsYesfile:///path/to/artifacts ortag://op-contracts/v1.8.0-rc.4--proxy-ownerAddress that will own the proxyYes0x1234...abcd--outfileFile to write output JSONNoproxy-output.json--cache-dirDirectory to cache artifactsNo.artifacts-cache -``` - -### Example - -```bash -bash -[ ] - -op-deployer bootstrap proxy \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --proxy-owner 0xYOUR_OWNER_ADDRESS \ - --outfile proxy-output.json - -``` - -### Output - -The command outputs a JSON file containing the deployed proxy contract address: - -```json -json -[ ] - -{ - "ProxyAdmin": "0x123...abc" -} - -``` - -## Bootstrap Superchain - -The `bootstrap superchain` command initializes the core superchain configuration contracts that govern the entire superchain ecosystem. - -### Command Usage - -```bash -bash -[ ] - -op-deployer bootstrap superchain \ - --l1-rpc-url \ - --private-key \ - --artifacts-locator \ - --superchain-proxy-admin-owner \ - --protocol-versions-owner \ - --guardian \ - --paused \ - --required-protocol-version \ - --recommended-protocol-version \ - --outfile superchain-output.json - -``` - -### Parameters - -``` -ParameterDescriptionRequiredExample--l1-rpc-urlRPC URL for the L1 chainYeshttps://sepolia.infura.io/v3/YOUR_API_KEY--private-keyPrivate key for transaction signingYes0xabcd...1234--artifacts-locatorLocation of contract artifactsYesfile:///path/to/artifacts ortag://op-contracts/v1.8.0-rc.4--superchain-proxy-admin-ownerAddress that owns the superchain proxy adminYes0x1234...abcd--protocol-versions-ownerAddress that can update protocol versionsYes0x2345...bcde--guardianAddress with emergency powersYes0x3456...cdef--pausedWhether the superchain starts pausedNo (defaults to false)false--required-protocol-versionMinimum required protocol versionYes1.0.0--recommended-protocol-versionRecommended protocol versionYes1.0.0--outfileFile to write output JSONNo (defaults to stdout)superchain-output.json--cache-dirDirectory to cache artifactsNo.artifacts-cache -``` - -### Example - -```bash -bash -[ ] - -op-deployer bootstrap superchain \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --superchain-proxy-admin-owner 0xADMIN_OWNER_ADDRESS \ - --protocol-versions-owner 0xVERSIONS_OWNER_ADDRESS \ - --guardian 0xGUARDIAN_ADDRESS \ - --paused false \ - --required-protocol-version 1.0.0 \ - --recommended-protocol-version 1.0.0 \ - --outfile superchain-output.json - -``` - -### Output - -The command outputs a JSON file containing the deployed superchain contract addresses: - -```json -json -[ ] - -{ - "SuperchainConfig": "0x123...abc", - "ProtocolVersions": "0x456...def" -} - -``` - -## Bootstrap Implementations - -The `bootstrap implementations` command deploys the implementation contracts required for the dispute system of the OP Stack. - -### Command Usage - -```bash -bash -[ ] - -op-deployer bootstrap implementations \ - --l1-rpc-url \ - --private-key \ - --artifacts-locator \ - --l1-contracts-release \ - --mips-version <1|2> \ - --withdrawal-delay-seconds \ - --min-proposal-size-bytes \ - --challenge-period-seconds \ - --proof-maturity-delay-seconds \ - --dispute-game-finality-delay-seconds \ - --superchain-config-proxy
\ - --protocol-versions-proxy
\ - --upgrade-controller
\ - --use-interop \ - --outfile implementations-output.json - -``` - -### Parameters - -``` -ParameterDescriptionRequiredDefaultExample--l1-rpc-urlRPC URL for the L1 chainYes-https://sepolia.infura.io/v3/YOUR_API_KEY--private-keyPrivate key for transaction signingYes-0xabcd...1234--artifacts-locatorLocation of contract artifactsYes-file:///path/to/artifacts--l1-contracts-releaseVersion tag for L1 contractsYes-v1.8.0-rc.4--mips-versionMIPS version for the fault proof system (1 or 2)NoFrom standard config2--withdrawal-delay-secondsDelay for withdrawals in secondsNoFrom standard config604800 (1 week)--min-proposal-size-bytesMinimum size for proposals in bytesNoFrom standard config1--challenge-period-secondsChallenge period in secondsNoFrom standard config604800 (1 week)--proof-maturity-delay-secondsProof maturity delay in secondsNoFrom standard config60--dispute-game-finality-delay-secondsDispute game finality delay in secondsNoFrom standard config604800 (1 week)--superchain-config-proxyAddress of superchain config proxyYes-Result from superchain command--protocol-versions-proxyAddress of protocol versions proxyYes-Result from superchain command--upgrade-controllerAddress of upgrade controllerYes-0x0000...0000--use-interopWhether to enable interoperability featuresNofalsetrue--outfileFile to write output JSONNostdoutimplementations-output.json--cache-dirDirectory to cache artifactsNo-.artifacts-cache -``` - -### Understanding MIPS Version - -The MIPS version parameter determines which version of the Cannon MIPS VM to use for fault proofs: - -- **MIPS Version 1**: Original implementation, suitable for most deployments -- **MIPS Version 2**: Enhanced implementation with optimizations, generally preferred for new deployments - -For most new deployments, MIPS Version 2 is recommended unless you have specific compatibility requirements. - -### Example - -```bash -bash -[ ] - -op-deployer bootstrap implementations \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --l1-contracts-release v1.8.0-rc.4 \ - --mips-version 2 \ - --withdrawal-delay-seconds 604800 \ - --min-proposal-size-bytes 1 \ - --challenge-period-seconds 604800 \ - --proof-maturity-delay-seconds 60 \ - --dispute-game-finality-delay-seconds 604800 \ - --superchain-config-proxy 0xSUPERCHAIN_CONFIG_ADDRESS \ - --protocol-versions-proxy 0xPROTOCOL_VERSIONS_ADDRESS \ - --upgrade-controller 0x0000000000000000000000000000000000000000 \ - --outfile implementations-output.json - -``` - -### Output - -The command outputs a JSON file containing the deployed implementation contract addresses: - -```json -json -[ ] - -{ - "L1CrossDomainMessenger": "0x123...abc", - "L1ERC721Bridge": "0x234...bcd", - "L1StandardBridge": "0x345...cde", - "L2OutputOracle": "0x456...def", - "OptimismPortal": "0x567...efg", - "OptimismMintableERC20Factory": "0x678...fgh", - "AddressManager": "0x789...ghi", - "ProxyAdmin": "0x89a...hij", - "SystemConfig": "0x9ab...ijk", - "DisputeGameFactory": "0xabc...jkl" -} - -``` - -## Bootstrap Validator - -The `bootstrap validator` command deploys the validator contracts required for the superchain. This is typically done after deploying the implementations. - -### Command Usage - -```bash -bash -[ ] - -op-deployer bootstrap validator \ - --l1-rpc-url \ - --private-key \ - --artifacts-locator \ - --config \ - --outfile validator-output.json - -``` - -### Parameters - -``` -ParameterDescriptionRequiredExample--l1-rpc-urlRPC URL for the L1 chainYeshttps://sepolia.infura.io/v3/YOUR_API_KEY--private-keyPrivate key for transaction signingYes0xabcd...1234--artifacts-locatorLocation of contract artifactsYesfile:///path/to/artifacts--configPath to JSON configuration fileYesvalidator-config.json--outfileFile to write output JSONNovalidator-output.json--cache-dirDirectory to cache artifactsNo.artifacts-cache -``` - -### Configuration File Format - -The configuration file should be a JSON file with the following structure: - -```json -json -[ ] - -{ - "release": "v1.8.0-rc.4", - "superchainConfig": "0x123...abc", - "l1PAOMultisig": "0x234...bcd", - "challenger": "0x345...cde", - "superchainConfigImpl": "0x456...def", - "protocolVersionsImpl": "0x567...efg", - "l1ERC721BridgeImpl": "0x678...fgh", - "optimismPortalImpl": "0x789...ghi", - "ethLockboxImpl": "0x89a...hij", - "systemConfigImpl": "0x9ab...ijk", - "optimismMintableERC20FactoryImpl": "0xabc...jkl", - "l1CrossDomainMessengerImpl": "0xbcd...klm", - "l1StandardBridgeImpl": "0xcde...lmn", - "disputeGameFactoryImpl": "0xdef...mno", - "anchorStateRegistryImpl": "0xefg...nop", - "delayedWETHImpl": "0xfgh...opq", - "mipsImpl": "0xghi...pqr", - "withdrawalDelaySeconds": 604800 -} - -``` - -Most of these addresses should come from the output of the previous bootstrap commands, particularly the `bootstrap implementations` command. - -### Example - -```bash -bash -[ ] - -op-deployer bootstrap validator \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --config validator-config.json \ - --outfile validator-output.json - -``` - -### Output - -The command outputs a JSON file containing the deployed validator contract address: - -```json -json -[ ] - -{ - "validator": "0x123...abc" -} - -``` - -## Working with Artifacts - -The `artifacts-locator` parameter specifies where the contract deployment artifacts are located. There are several ways to provide artifacts: - -### Using Local Files - -To use local artifacts (recommended for production or if you're experiencing issues with remote artifacts): - -1. Clone the contracts repository: - - ```bash - bash - [ ] - - git clone https://github.com/ethereum-optimism/optimism.git - cd optimism - git checkout v1.8.0-rc.4# Use the desired version - - ``` - -2. Build the artifacts: - - ```bash - bash - [ ] - - cd packages/contracts-bedrock - pnpm install - pnpm build - - ``` - -3. Use the local path in your command: - - ```bash - bash - [ ] - - --artifacts-locator file:///absolute/path/to/optimism/packages/contracts-bedrock/artifacts - - ``` - +## Bootstrap usage -### Using Tagged Artifacts +The bootstrap commands are specialized tools primarily used for initializing a new superchain on an L1 network that hasn't previously hosted one. -For development or testing, you can try using tagged artifacts (but note there are known issues with this approach): +### Available commands ```bash -bash -[ ] - ---artifacts-locator tag://op-contracts/v1.8.0-rc.4 +op-deployer bootstrap superchain --l1-chain-id --private-key --l1-rpc-url +op-deployer bootstrap implementations +op-deployer bootstrap proxy ``` -If you encounter the error `Application failed: failed to parse artifacts URL: unsupported tag`, you'll need to use the local files method described above. - -## Complete Bootstrap Workflow Example +### Bootstrap workflow -Here's a step-by-step workflow to bootstrap a complete superchain from scratch: +The bootstrap workflow involves several steps to initialize a new superchain: -1. **Deploy Proxy Admin**: - - ```bash - bash - [ ] - - op-deployer bootstrap proxy \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --proxy-owner 0xYOUR_OWNER_ADDRESS \ - --outfile proxy-output.json - - ``` - -2. **Store the proxy admin address** for use in the next steps: - - ```bash - bash - [ ] - - PROXY_ADMIN=$(jq -r '.ProxyAdmin' proxy-output.json) - echo "Proxy Admin: $PROXY_ADMIN" - - ``` - -3. **Deploy Superchain Configuration**: - - ```bash - bash - [ ] - - op-deployer bootstrap superchain \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --superchain-proxy-admin-owner 0xADMIN_OWNER_ADDRESS \ - --protocol-versions-owner 0xVERSIONS_OWNER_ADDRESS \ - --guardian 0xGUARDIAN_ADDRESS \ - --paused false \ - --required-protocol-version 1.0.0 \ - --recommended-protocol-version 1.0.0 \ - --outfile superchain-output.json - - ``` - -4. **Store the superchain configuration addresses**: - - ```bash - bash - [ ] - - SUPERCHAIN_CONFIG=$(jq -r '.SuperchainConfig' superchain-output.json) - PROTOCOL_VERSIONS=$(jq -r '.ProtocolVersions' superchain-output.json) - echo "Superchain Config: $SUPERCHAIN_CONFIG" - echo "Protocol Versions: $PROTOCOL_VERSIONS" - - ``` - -5. **Deploy Implementations**: - - ```bash - bash - [ ] - - op-deployer bootstrap implementations \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --l1-contracts-release v1.8.0-rc.4 \ - --mips-version 2 \ - --withdrawal-delay-seconds 604800 \ - --min-proposal-size-bytes 1 \ - --challenge-period-seconds 604800 \ - --proof-maturity-delay-seconds 60 \ - --dispute-game-finality-delay-seconds 604800 \ - --superchain-config-proxy $SUPERCHAIN_CONFIG \ - --protocol-versions-proxy $PROTOCOL_VERSIONS \ - --upgrade-controller 0x0000000000000000000000000000000000000000 \ - --outfile implementations-output.json - - ``` - -6. **Extract implementation addresses** for the validator configuration: - - ```bash - bash - [ ] - - # Example of extracting implementation addresses - L1_CROSS_DOMAIN_MESSENGER_IMPL=$(jq -r '.L1CrossDomainMessenger' implementations-output.json) - L1_ERC721_BRIDGE_IMPL=$(jq -r '.L1ERC721Bridge' implementations-output.json) - # ... extract other implementation addresses similarly - - ``` - -7. **Create a validator configuration file**: - - ```bash - bash - [ ] - - cat > validator-config.json << EOF - { - "release": "v1.8.0-rc.4", - "superchainConfig": "$SUPERCHAIN_CONFIG", - "l1PAOMultisig": "0xYOUR_PAO_MULTISIG_ADDRESS", - "challenger": "0xYOUR_CHALLENGER_ADDRESS", - "superchainConfigImpl": "$SUPERCHAIN_CONFIG_IMPL", - "protocolVersionsImpl": "$PROTOCOL_VERSIONS_IMPL", - "l1ERC721BridgeImpl": "$L1_ERC721_BRIDGE_IMPL", - "optimismPortalImpl": "$OPTIMISM_PORTAL_IMPL", - "ethLockboxImpl": "$ETH_LOCKBOX_IMPL", - "systemConfigImpl": "$SYSTEM_CONFIG_IMPL", - "optimismMintableERC20FactoryImpl": "$OPTIMISM_MINTABLE_ERC20_FACTORY_IMPL", - "l1CrossDomainMessengerImpl": "$L1_CROSS_DOMAIN_MESSENGER_IMPL", - "l1StandardBridgeImpl": "$L1_STANDARD_BRIDGE_IMPL", - "disputeGameFactoryImpl": "$DISPUTE_GAME_FACTORY_IMPL", - "anchorStateRegistryImpl": "$ANCHOR_STATE_REGISTRY_IMPL", - "delayedWETHImpl": "$DELAYED_WETH_IMPL", - "mipsImpl": "$MIPS_IMPL", - "withdrawalDelaySeconds": 604800 - } - EOF - - ``` - -8. **Deploy Validator**: - - ```bash - bash - [ ] - - op-deployer bootstrap validator \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --config validator-config.json \ - --outfile validator-output.json - - ``` - -9. Once all these commands have successfully completed, you'll have bootstrapped the core components needed for a new superchain. You can now proceed to deploy individual chains using the standard `op-deployer apply` command. - -## Troubleshooting - -### Issue: Unsupported Tag Error - -If you encounter an error like `Application failed: failed to parse artifacts URL: unsupported tag` when using `tag://` format: - -**Solution**: Use local artifacts as described in the "Working with Artifacts" section. - -### Issue: MIPS Version Selection Error +> 📌 TODO: Add detailed step-by-step instructions for a successful bootstrap flow, including expected order of operations and dependencies between commands. +> -If you encounter an error indicating that MIPS version must be 1 or 2: +When using the bootstrap command, you'll need to specify the following parameters: -**Solution**: Ensure you're specifying exactly `1` or `2` as the MIPS version value, not any other number. +- `-l1-chain-id`: The chain ID of the L1 network +- `-private-key`: The private key to use for deployment +- `-l1-rpc-url`: The RPC URL for the L1 network -### Issue: Transaction Gas Issues +### MIPS Version -If transactions fail due to gas limits or costs: +> 📌 TODO: Document the expected format and supported values for the MIPS version parameter. +> -**Solution**: Ensure your deployer account has sufficient ETH (at least 1 ETH for bootstrapping operations), and consider using a network with lower gas costs for testing. \ No newline at end of file From 6a1cefd4516ce94cf52b854e64307e2589e74274 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Thu, 24 Apr 2025 20:26:56 +0100 Subject: [PATCH 03/14] updated the op deployer docs --- .../chain-operators/tools/Deployer.md | 299 ----------- .../chain-operators/tools/op-deployer.mdx | 480 ++++++++++++++++-- words.txt | 4 + 3 files changed, 436 insertions(+), 347 deletions(-) delete mode 100644 pages/operators/chain-operators/tools/Deployer.md diff --git a/pages/operators/chain-operators/tools/Deployer.md b/pages/operators/chain-operators/tools/Deployer.md deleted file mode 100644 index 0804fafc7..000000000 --- a/pages/operators/chain-operators/tools/Deployer.md +++ /dev/null @@ -1,299 +0,0 @@ -# Deployer - -`op-deployer` simplifies the process of deploying the OP Stack. It works similarly to [Terraform](https://www.terraform.io/). Like Terraform, you define a declarative config file called an "**intent**," then run a command to apply the intent to your chain. `op-deployer` will compare the state of your chain against the intent, and make whatever changes are necessary for them to match. In its current state, it is intended to deploy new standard chains that utilize the Superchain wide contracts. - -## Installation - -There are multiple ways to install `op-deployer`: - -### Option 1: Download pre-built binary (Recommended) - -The recommended way to install `op-deployer` is to download the latest release from the monorepo's [release page](https://github.com/ethereum-optimism/optimism/releases). - -1. Go to https://github.com/ethereum-optimism/optimism/releases -2. Find the latest release that includes op-deployer -3. Download the appropriate binary for your operating system -4. Extract the binary to a location on your system PATH - - -5. Verify installation: - - ```bash - op-deployer --version - ``` - - -### Option 2: Build from source - -If you prefer to build from source: - -1. Clone the Optimism repository: - - ```bash - git clone https://github.com/ethereum-optimism/optimism.git - cd optimism - ``` - -2. Build the op-deployer binary: - - ```bash - make op-deployer - ``` - -3. The binary will be available at `./bin/op-deployer` - -## Deployment usage - -> ⚠️ WARNING: Gas cost ⚠️ -> -> -> Deploying an OP Stack chain can require significant gas. Ensure your deployer wallet has at least 3.5 ETH for deployment on mainnet or testnet. The exact amount will vary based on gas prices and configuration. -> - -The base use case for `op-deployer` is deploying new OP Chains. This process is broken down into four steps: - -### `init`: configure your chain - -To get started with `op-deployer`, create an intent file that defines your desired chain configuration. Use the built-in `op-deployer` utility to generate this file: - -> 📌 op-deployer uses a declarative intent file to determine how a new chain should be configured. Then, it runs through a deployment pipeline to actually deploy the chain. -> - -```bash -./bin/op-deployer init --l1-chain-id 11155111 --l2-chain-ids --workdir .deployer - -``` - -Replace `` with the exact value. - -This command will create a directory called `.deployer` in your current working directory containing the intent file and an empty `state.json` file. `state.json` is populated with the results of your deployment, and never needs to be edited directly. - -Your intent file will need to be modified to your parameters, but it will initially look something like this: - -> ⚠️ Do not use the default addresses in the intent for a production chain! They are generated from the test... junk mnemonic. Any funds they hold will be stolen on a live chain. -> - -```toml -deploymentStrategy = "live" -configType = "standard-overrides" -l1ChainID = 11155111# The chain ID of Sepolia (L1) you'll be deploying to. -fundDevAccounts = true# Whether or not to fund dev accounts using the test... junk mnemonic on L2. -l1ContractsLocator = "tag://op-contracts/v1.8.0-rc.4"# L1 smart contracts versions -l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts"# L2 smart contracts versions# Delete this table if you are using the shared Superchain contracts on the L1# If you are deploying your own SuperchainConfig and ProtocolVersions contracts, fill in these details -[superchainRoles] - proxyAdminOwner = "0x1eb2ffc903729a0f03966b917003800b145f56e2" - protocolVersionsOwner = "0x79add5713b383daa0a138d3c4780c7a1804a8090" - guardian = "0x7a50f00e8d05b95f98fe38d8bee366a7324dcf7e" - -# List of L2s to deploy. op-deployer can deploy multiple L2s at once -[[chains]] -# Your chain's ID, encoded as a 32-byte hex string - id = "0x00000000000000000000000000000000000000000000000000000a25406f3e60" -# Update the fee recipient contract - baseFeeVaultRecipient = "0x100f829718B5Be38013CC7b29c5c62a08D00f1ff" - l1FeeVaultRecipient = "0xbAEaf33e883068937aB4a50871f2FD52e241013A" - sequencerFeeVaultRecipient = "0xd0D5D18F0ebb07B7d728b14AAE014eedA814d6BD" - eip1559DenominatorCanyon = 250 - eip1559Denominator = 50 - eip1559Elasticity = 6 -# Various ownership roles for your chain. When you use op-deployer init, these roles are generated using the# test... junk mnemonic. You should replace these with your own addresses for production chains. - [chains.roles] - l1ProxyAdminOwner = "0xdf5a644aed1b5d6cE0DA2aDd778bc5f39d97Ac88" - l2ProxyAdminOwner = "0xC40445CD88dDa2A410F86F6eF8E00fd52D8381FD" - systemConfigOwner = "0xB32296E6929F2507dB8153A64b036D175Ac6E89e" - unsafeBlockSigner = "0xA53526b516df4eEe3791734CE85311569e0eAD78" - batcher = "0x8680d36811420359093fd321ED386a6e76BE2AF3" - proposer = "0x41b3B204099771aDf857F826015703A1030b6675" - challenger = "0x7B51A480dAeE699CA3a4F68F9AAA434452112eF7" - -``` - -### Understanding the intent.toml fields - -Here's an explanation of the key fields in the intent file: - -**Global configuration:** - -- `deploymentStrategy`: Used to deploy both to live chains and L1 genesis files. Valid values are `live` and `genesis`. -- `configType`: Type of configuration to use ("standard-overrides" is most common) -- `l1ChainID`: The chain ID of the L1 network you're deploying to -- `fundDevAccounts`: Whether to fund development accounts on L2 (set to false for production) -- `l1ContractsLocator`: The version of L1 contracts to deploy -- `l2ContractsLocator`: The version of L2 contracts to deploy - -**Superchain roles:** - -- `proxyAdminOwner`: Address that can upgrade Superchain-wide contracts -- `protocolVersionsOwner`: Address that can update protocol versions -- `guardian`: Address authorized to pause L1 withdrawals from contracts, blacklist dispute games, and set the respected game type in the `OptimismPortal` - -**Chain-specific configuration:** - -- `id`: Unique identifier for your chain -- `baseFeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `BaseFeeVault` -- `l1FeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `L1FeeVault` -- `sequencerFeeVaultRecipient`: Address that receives sequencer fees -- `eip1559DenominatorCanyon`, `eip1559Denominator`, `eip1559Elasticity`: Parameters for fee calculation - -**Chain roles:** - -- `l1ProxyAdminOwner`: Address authorized to update the L1 Proxy Admin -- `l2ProxyAdminOwner`: Address authorized to upgrade protocol contracts via calls to the `ProxyAdmin`. This is the aliased L1 ProxyAdmin owner address. -- `systemConfigOwner`: Address authorized to change values in the `SystemConfig` contract. All configuration is stored on L1 and picked up by L2 as part of the [derivation](https://specs.optimism.io/protocol/derivation.html) of the L2 chain -- `unsafeBlockSigner`: Address which authenticates the unsafe/pre-submitted blocks for a chain at the P2P layer -- `batcher`: Address that batches transactions from L2 to L1 -- `proposer`: Address which can create and interact with [permissioned dispute games](https://specs.optimism.io/fault-proof/stage-one/bridge-integration.html#permissioned-faultdisputegame) on L1. -- `challenger`: Address Account which can interact with existing permissioned dispute games - -### Contract locator schemes - -op-deployer uses contract locators to find contract artifacts to deploy. -Locators are just URLs under the hood. -The `l1ContractsLocator` and `l2ContractsLocator` fields support several schemes for specifying where to find the contract implementations: - -* `tag://` - References a specific tagged release of the contracts (e.g., `tag://op-contracts/v1.8.0-rc.4`). In this case, the contracts bytecode will be downloaded from a fixed bytecode bundle on GCS. -* `file://` - Points to a local Forge build artifacts directory. Must point to the `forge-artifacts` directory containing the compiled contract artifacts. -This is useful for local development, since you can point it at your local monorepo -e.g. `--artifacts-locator file:///Users/username/code/optimism/packages/contracts-bedrock/forge-artifacts/` -* `http://` or `https://` - Points to a target directory containing contract artifacts. The URL should directly reference the directory containing the `forge-artifacts` directory, in this case, the bytecode will be downloaded from the URL specified. - - -When using any scheme other than `tag://`, you must set `configType` to either `custom` or `standard-overrides` in your intent file. - - -For example: - -```toml -# When using tag:// scheme -configType = "standard-overrides" -l1ContractsLocator = "tag://op-contracts/v1.8.0-rc.4" -l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts" - -# When using other schemes (file://, http://, https://) -configType = "custom" # or "standard-overrides" -l1ContractsLocator = "file:///path/to/local/op-contracts/v1.8.0-rc.4/forge-artifacts" -l2ContractsLocator = "https://example.com/op-contracts/v1.7.0-beta.1+l2-contracts.tar.gz" -``` - -By default, `op-deployer` will fill in all other configuration variables with those that match the [standard configuration](https://specs.optimism.io/protocol/configurability.html?utm_source=op-docs&utm_medium=docs). You can override these default settings by adding them to your intent file using the table below: - -```toml -[globalDeployOverrides] - l2BlockTime = 1# 1s L2blockTime is also standard, op-deployer defaults to 2s - -``` - -You can also do chain by chain configurations in the `chains` table. - -### `apply`: deploy your chain - -> 📌 Hardware wallets are not supported, but you can use ephemeral hot wallets since this deployer key has no privileges. -> - -Now that you've created your intent file, you can apply it to your chain to deploy the L1 smart contracts: - -```bash -bash -[ ] - -./bin/op-deployer apply --workdir .deployer --l1-rpc-url --private-key - -``` - -- Replace `` with your `L1_RPC_URL` and `` with your private key - -This command will deploy the OP Stack to L1. It will deploy all L2s specified in the intent file. Superchain -configuration will be set to the Superchain-wide defaults - i.e., your chain will be opted into the [Superchain pause](https://specs.optimism.io/protocol/superchain-config.html#pausability) -and will use the same [protocol versions](https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/superchain-upgrades.md) -address as other chains on the Superchain. - -### `verify`: verify contract source code on block explorers - -After deploying your contracts, you can verify them on block explorers like Etherscan: - -```bash -op-deployer verify --workdir .deployer --l1-rpc-url --l1-explorer-api-url --l1-explorer-api-key - -``` - -The verification tool supports various options: - -- `-workdir`: Specifies the directory containing the deployment state -- `-l1-rpc-url`: RPC URL for the L1 chain -- `-l1-explorer-api-url`: API URL for the L1 block explorer (e.g., https://api-sepolia.etherscan.io/api for Sepolia) -- `-l1-explorer-api-key`: API key for the L1 block explorer -- `-retry`: Retry failed verifications -- `-overwrite`: Overwrite existing verifications -- `-skip-already-verified`: Skip contracts that are already verified -- `-retries`: Number of retries for failed verifications (default: 3) -- `-retry-delay`: Delay between retries in seconds (default: 1s) -- `-timeout`: Timeout for verification requests in seconds (default: 30s) -- `-contract-filter`: Regex filter for contract names to verify - -Example usage: - -```bash -op-deployer verify --workdir .deployer \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_INFURA_KEY \ - --l1-explorer-api-url https://api-sepolia.etherscan.io/api \ - --l1-explorer-api-key YOUR_ETHERSCAN_API_KEY \ - --skip-already-verified - -``` - -### `inspect`: generate genesis files and chain information - -> 📌 To add your chain to the Superchain Registry you will need to provide the chain artifacts. To get these chain artifacts, you will need to write the output of these commands to new files. -> - -Inspect the `state.json` file by navigating to your working directory. With the contracts deployed, generate the genesis and rollup configuration files by running the following commands: - -```bash -./bin/op-deployer inspect genesis --workdir .deployer > .deployer/genesis.json -./bin/op-deployer inspect rollup --workdir .deployer > .deployer/rollup.json - -``` - -Now that you have your `genesis.json` and `rollup.json` you can spin up a node on your network. You can also use the following inspect subcommands to get additional chain artifacts: - -```bash -bash -[ ] - -./bin/op-deployer inspect l1 --workdir .deployer # outputs all L1 contract addresses for an L2 chain -./bin/op-deployer inspect deploy-config --workdir .deployer # outputs the deploy config for an L2 chain -./bin/op-deployer inspect l2-semvers --workdir .deployer # outputs the semvers for all L2 chains - -``` - -## Bootstrap usage - -The bootstrap commands are specialized tools primarily used for initializing a new superchain on an L1 network that hasn't previously hosted one. - -### Available commands - -```bash -op-deployer bootstrap superchain --l1-chain-id --private-key --l1-rpc-url -op-deployer bootstrap implementations -op-deployer bootstrap proxy - -``` - -### Bootstrap workflow - -The bootstrap workflow involves several steps to initialize a new superchain: - -> 📌 TODO: Add detailed step-by-step instructions for a successful bootstrap flow, including expected order of operations and dependencies between commands. -> - -When using the bootstrap command, you'll need to specify the following parameters: - -- `-l1-chain-id`: The chain ID of the L1 network -- `-private-key`: The private key to use for deployment -- `-l1-rpc-url`: The RPC URL for the L1 network - -### MIPS Version - -> 📌 TODO: Document the expected format and supported values for the MIPS version parameter. -> - diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 833250634..7eacdef74 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -17,20 +17,54 @@ import {Callout, Steps} from 'nextra/components' # Deployer -`op-deployer` simplifies the process of deploying the OP Stack. It works similarly to [Terraform](https://www.terraform.io). Like Terraform, you define a declarative config file called an "intent," then run a command to apply the intent to your chain. `op-deployer` will compare the state of your chain against the intent, and make whatever changes are necessary for them to match. In its current state, it is intended to deploy new standard chains that utilize the Superchain wide contracts. +`op-deployer` simplifies the process of deploying the OP Stack. It works similarly to [Terraform](https://www.terraform.io/). Like Terraform, you define a declarative config file called an "**intent**," then run a command to apply the intent to your chain. `op-deployer` will compare the state of your chain against the intent, and make whatever changes are necessary for them to match. In its current state, it is intended to deploy new standard chains that utilize the Superchain wide contracts. ## Installation -The recommended way to install `op-deployer` is to download the latest release from the monorepo's -[release page](https://github.com/ethereum-optimism/optimism/releases). To install a release, download the binary -for your platform then extract it somewhere on your `PATH`. The rest of this tutorial will assume that you have -installed `op-deployer` using this method. +There are a couple of ways to install `op-deployer`: + +### Option 1: Download pre-built binary + +The recommended way to install `op-deployer` is to download the latest release from the monorepo's [release page](https://github.com/ethereum-optimism/optimism/releases). + +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 + +1. Extract the binary to a location on your system PATH +2. Verify installation, run this command to verify that you have it installed. + +```bash +op-deployer --version +``` + +### Option 2: Build from source (Recommended) + +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 +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 +``` ## Deployment usage -The base use case for `op-deployer` is deploying new OP Chains. This process is broken down into three steps: + + 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. + - +The base use case for `op-deployer` is deploying new OP Chains. This process is broken down into three steps: ### `init`: configure your chain @@ -41,11 +75,17 @@ To get started with `op-deployer`, create an intent file that defines your desir Then, it runs through a deployment pipeline to actually deploy the chain. -``` -./bin/op-deployer init --l1-chain-id 11155111 --l2-chain-ids --workdir .deployer +```bash +op-deployer init \ + --l1-chain-id \ + --l2-chain-ids \ + --workdir .deployer \ + --intent-type + ``` -Replace `` with the exact value. +* Replace `` with the exact value. +* The `--workdir` flag specifies the output directory for the generated intent file and related configs. You can name this directory anything you like , `.deployer` is just an example. This command will create a directory called `.deployer` in your current working directory containing the intent file and an empty `state.json` file. `state.json` is populated with the results of your deployment, and never needs to be edited directly. @@ -56,16 +96,13 @@ Your intent file will need to be modified to your parameters, but it will initia mnemonic. **Any funds they hold will be stolen on a live chain.** - ```toml +deploymentStrategy = "live" configType = "standard-overrides" -l1ChainID = 11155111 # The chain ID of Sepolia (L1) you'll be deploying to. -fundDevAccounts = true # Whether or not to fund dev accounts using the test... junk mnemonic on L2. -l1ContractsLocator = "tag://op-contracts/v1.8.0-rc.4" # L1 smart contracts versions -l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts" # L2 smart contracts versions - -# Delete this table if you are using the shared Superchain contracts on the L1 -# If you are deploying your own SuperchainConfig and ProtocolVersions contracts, fill in these details +l1ChainID = 11155111# The chain ID of Sepolia (L1) you'll be deploying to. +fundDevAccounts = true# Whether or not to fund dev accounts using the test... junk mnemonic on L2. +l1ContractsLocator = "tag://op-contracts/v1.8.0-rc.4"# L1 smart contracts versions +l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts"# L2 smart contracts versions# Delete this table if you are using the shared Superchain contracts on the L1# If you are deploying your own SuperchainConfig and ProtocolVersions contracts, fill in these details [superchainRoles] proxyAdminOwner = "0x1eb2ffc903729a0f03966b917003800b145f56e2" protocolVersionsOwner = "0x79add5713b383daa0a138d3c4780c7a1804a8090" @@ -73,17 +110,16 @@ l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts" # L2 smart # List of L2s to deploy. op-deployer can deploy multiple L2s at once [[chains]] - # Your chain's ID, encoded as a 32-byte hex string +# Your chain's ID, encoded as a 32-byte hex string id = "0x00000000000000000000000000000000000000000000000000000a25406f3e60" - # Update the fee recipient contract +# Update the fee recipient contract baseFeeVaultRecipient = "0x100f829718B5Be38013CC7b29c5c62a08D00f1ff" l1FeeVaultRecipient = "0xbAEaf33e883068937aB4a50871f2FD52e241013A" sequencerFeeVaultRecipient = "0xd0D5D18F0ebb07B7d728b14AAE014eedA814d6BD" eip1559DenominatorCanyon = 250 eip1559Denominator = 50 eip1559Elasticity = 6 - # Various ownership roles for your chain. When you use op-deployer init, these roles are generated using the - # test... junk mnemonic. You should replace these with your own addresses for production chains. +# Various ownership roles for your chain. When you use op-deployer init, these roles are generated using the# test... junk mnemonic. You should replace these with your own addresses for production chains. [chains.roles] l1ProxyAdminOwner = "0xdf5a644aed1b5d6cE0DA2aDd778bc5f39d97Ac88" l2ProxyAdminOwner = "0xC40445CD88dDa2A410F86F6eF8E00fd52D8381FD" @@ -95,11 +131,115 @@ l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts" # L2 smart ``` -By default, `op-deployer` will fill in all other configuration variables with those that match the [standard configuration](https://specs.optimism.io/protocol/configurability.html?utm_source=op-docs&utm_medium=docs). You can override these default settings by adding them to your intent file using the table below: +### Understanding the intent.toml fields + +Here's an explanation of the key fields in the intent file: + +**Global configuration:** + +* `deploymentStrategy`: Used to deploy both to live chains and L1 genesis files. Valid values are `live` and `genesis`. +* `configType`: Type of configuration to use ("standard-overrides" is most common) +* `l1ChainID`: The chain ID of the L1 network you're deploying to +* `fundDevAccounts`: Whether to fund development accounts on L2 (set to false for production) +* `l1ContractsLocator`: The version of L1 contracts to deploy +* `l2ContractsLocator`: The version of L2 contracts to deploy + +**Superchain roles:** + +* `proxyAdminOwner`: Address that can upgrade Superchain-wide contracts +* `protocolVersionsOwner`: Address that can update protocol versions +* `guardian`: Address authorized to pause L1 withdrawals from contracts, blacklist dispute games, and set the respected game type in the `OptimismPortal` + +**Chain-specific configuration:** + +* `id`: Unique identifier for your chain +* `baseFeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `BaseFeeVault` +* `l1FeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `L1FeeVault` +* `sequencerFeeVaultRecipient`: Address that receives sequencer fees +* `eip1559DenominatorCanyon`, `eip1559Denominator`, `eip1559Elasticity`: Parameters for fee calculation + +**Chain roles:** + +* `l1ProxyAdminOwner`: Address authorized to update the L1 Proxy Admin +* `l2ProxyAdminOwner`: Address authorized to upgrade protocol contracts via calls to the `ProxyAdmin`. This is the aliased L1 ProxyAdmin owner address. +* `systemConfigOwner`: Address authorized to change values in the `SystemConfig` contract. All configuration is stored on L1 and picked up by L2 as part of the [derivation](https://specs.optimism.io/protocol/derivation.html) of the L2 chain +* `unsafeBlockSigner`: Address which authenticates the unsafe/pre-submitted blocks for a chain at the P2P layer +* `batcher`: Address that batches transactions from L2 to L1 +* `proposer`: Address which can create and interact with [permissioned dispute games](https://specs.optimism.io/fault-proof/stage-one/bridge-integration.html#permissioned-faultdisputegame) on L1. +* `challenger`: Address Account which can interact with existing permissioned dispute games + +## Working with artifacts + +The `artifacts-locator` parameter specifies where the contract deployment artifacts are located. There are several ways to provide artifacts: + +### Using local files + +To use local artifacts (recommended for production or if you're experiencing issues with remote artifacts): + +1. Clone the contracts repository: + + ```bash + git clone https://github.com/ethereum-optimism/optimism.git + cd optimism + git checkout v1.8.0-rc.4 # Use the desired version + + ``` + +2. Build the contract artifacts: + + ```bash + cd packages/contracts-bedrock + just build + ``` + +3. Use the local path in your command, referencing the artifacts from: + `/packages/contracts-bedrock/forge-artifacts` + +### Using tagged artifacts + +For development or testing, you can try using tagged artifacts: + +```bash +--artifacts-locator tag://op-contracts/v1.8.0-rc.4 + +``` + +If you encounter the error `Application failed: failed to parse artifacts URL: unsupported tag`, you'll need to use the local files method described above, else If you use an invalid tag, the command will display all valid options. + +### Contract locator schemes + +op-deployer uses contract locators to find contract artifacts to deploy. +Locators are just URLs under the hood. +The `l1ContractsLocator` and `l2ContractsLocator` fields support several schemes for specifying where to find the contract implementations: + +* `tag://` - References a specific tagged release of the contracts (e.g., `tag://op-contracts/v1.8.0-rc.4`). In this case, the contracts bytecode will be downloaded from a fixed bytecode bundle on GCS. +* `file://` - Points to a directory on local disk containing the artifacts. + This is useful for local development, since you can point it at your local monorepo + e.g. `file:///packages/contracts-bedrock/forge-artifacts` +* `http://` or `https://` - Points to a target directory containing contract artifacts. The URL should directly reference the directory containing the `forge-artifacts` directory, in this case, the bytecode will be downloaded from the URL specified. + +> ⚠️ When using any scheme other than tag://, you must set configType to either custom or standard-overrides in your intent file. + +For example: + +```toml +# When using tag:// scheme +configType = "standard-overrides" +l1ContractsLocator = "tag://op-contracts/v1.8.0-rc.4" +l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts" + +# When using other schemes (file://, http://, https://) +configType = "custom" # or "standard-overrides" +l1ContractsLocator = "file:///path/to/local/op-contracts/v1.8.0-rc.4/forge-artifacts" +l2ContractsLocator = "" +``` + +By default, `op-deployer` will fill in all other configuration variables with those that match the [standard configuration](https://specs.optimism.io/protocol/configurability.html?utm_source=op-docs\&utm_medium=docs). You can override these default settings by adding them to your intent file using the table below: ```toml [globalDeployOverrides] - l2BlockTime = 1 # 1s L2blockTime is also standard, op-deployer defaults to 2s + l2BlockTime = 1# 1s L2blockTime is also standard, op-deployer defaults to 2s + ``` You can also do chain by chain configurations in the `chains` table. @@ -113,15 +253,63 @@ You can also do chain by chain configurations in the `chains` table. Now that you've created your intent file, you can apply it to your chain to deploy the L1 smart contracts: ```bash -./bin/op-deployer apply --workdir .deployer --l1-rpc-url --private-key +op-deployer apply --workdir .deployer --l1-rpc-url --private-key + ``` * Replace `` with your `L1_RPC_URL` and `` with your private key -This command will deploy the OP Stack to L1. It will deploy all L2s specified in the intent file. Superchain -configuration will be set to the Superchain-wide defaults - i.e., your chain will be opted into the [Superchain pause](https://specs.optimism.io/protocol/superchain-config.html#pausability) -and will use the same [protocol versions](https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/superchain-upgrades.md) -address as other chains on the Superchain. +This command will deploy the OP Stack to L1. It will deploy all L1 contracts for each L2 specified in the intent file. + +Superchain configuration will be set to the Superchain-wide defaults - i.e., your chain will be opted into the [Superchain pause](https://specs.optimism.io/protocol/superchain-config.html#pausability) and will use the same [protocol versions](https://github.com/ethereum-optimism/specs/blob/main/specs/protocol/superchain-upgrades.md) address as other chains on the Superchain. +You will need to specify additional arguments depending on what you're trying to do. +See below for a reference of each supported CLI arg: + +* Deployment targets: + + The `--deployment-target` flag specifies where to deploy: + + * `live`: Deploys directly to a live L1 network. Requires `-l1-rpc-url` and `-private-key`. + * `genesis`: Generates an L1 genesis file for local testing or development. + * `calldata`: Produces calldata for multisig wallets, enabling offline deployment. + * `noop`: Performs a dry-run without actual deployment, useful for testing configurations. + + Choose the deployment target that best fits your use case. + +### `verify`: verify contract source code on block explorers + +After deploying your contracts, you can verify them on block explorers like Etherscan: + +```bash +op-deployer verify \ + --l1-rpc-url \ + --input-file \ + --etherscan-api-key \ + --artifacts-locator + +``` + +### Common options: + +* `-l1-rpc-url`: RPC URL for the L1 chain +* `-etherscan-api-key`: API key for the block explorer (e.g., from Etherscan) +* `-artifacts-locator`: Path or plugin to locate contract artifacts +* `-input-file`: (Optional) Path to a JSON file containing deployment data +* `-contract-name`: (Optional) Name of a specific contract to verify + + + + You don't need to specify a --workdir—op-deployer will automatically look for deployment artifacts from the deploy step, unless overridden. + + +### Example: + +```bash +op-deployer verify \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_INFURA_KEY \ + --etherscan-api-key YOUR_ETHERSCAN_API_KEY + +``` ### `inspect`: generate genesis files and chain information @@ -132,41 +320,237 @@ address as other chains on the Superchain. Inspect the `state.json` file by navigating to your working directory. With the contracts deployed, generate the genesis and rollup configuration files by running the following commands: ```bash -./bin/op-deployer inspect genesis --workdir .deployer > .deployer/genesis.json -./bin/op-deployer inspect rollup --workdir .deployer > .deployer/rollup.json +op-deployer inspect genesis --workdir .deployer > .deployer/genesis.json +op-deployer inspect rollup --workdir .deployer > .deployer/rollup.json + ``` Now that you have your `genesis.json` and `rollup.json` you can spin up a node on your network. You can also use the following inspect subcommands to get additional chain artifacts: ```bash -./bin/op-deployer inspect l1 --workdir .deployer # outputs all L1 contract addresses for an L2 chain -./bin/op-deployer inspect deploy-config --workdir .deployer # outputs the deploy config for an L2 chain -./bin/op-deployer inspect l2-semvers --workdir .deployer # outputs the semvers for all L2 chains +op-deployer inspect l1 --workdir .deployer # outputs all L1 contract addresses for an L2 chain +op-deployer inspect deploy-config --workdir .deployer # outputs the deploy config for an L2 chain +op-deployer inspect l2-semvers --workdir .deployer # outputs the semvers for all L2 chains + ``` - ## Bootstrap usage -The bootstrap commands are specialized tools primarily used for initializing a new superchain on an L1 network that hasn't previously hosted one. +`op-deployer` provides a set of bootstrap commands specifically designed for initializing a new superchain on an L1 network. These commands are essential when you're setting up a completely new superchain environment rather than deploying a new chain on an existing superchain. + +### Bootstrap process overview + +When bootstrapping a new superchain, you typically need to follow this process: + +1. **Deploy proxy admin** (`bootstrap proxy`): Sets up the `ERC-1967` proxy for the superchain management contracts. +2. **Deploy Superchain configuration** (`bootstrap superchain`): Creates the foundational superchain configuration contracts. +3. **Deploy implementations** (`bootstrap implementations`): Deploys the implementation contracts needed for the dispute game. +4. **Deploy validator** (`bootstrap validator`): Deploys the `StandardValidator` for the superchain. -### Available commands +### Bootstrap proxy + +The `bootstrap proxy` command deploys a new `ERC-1967` proxy admin, which is required for upgradeability of the superchain contracts. + +### Command usage ```bash -op-deployer bootstrap superchain -op-deployer bootstrap implementations -op-deployer bootstrap proxy +op-deployer bootstrap proxy \ + --l1-rpc-url \ + --private-key \ + --artifacts-locator \ + --proxy-owner \ + --outfile proxy-output.json + ``` -### Use cases +### Parameters -The bootstrap commands are specifically designed for scenarios such as: -* Setting up a superchain on a new EVM-compatible L1. -* Initializing superchain contracts on a new Ethereum testnet (e.g., an alternative to Sepolia). -* Creating the foundational infrastructure for a brand new superchain deployment. +| Parameter | Description | Required | Example | +| ------------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------- | +| --l1-rpc-url | RPC URL for the L1 chain | Yes | [https://sepolia.infura.io/v3/YOUR\_API\_KEY](https://sepolia.infura.io/v3/YOUR_API_KEY) | +| --private-key | Private key for transaction signing | Yes | 0xabcd...1234 | +| --artifacts-locator | Location of contract artifacts | Yes | tag://op-contracts/v3.0.0-rc.2 | +| --proxy-owner | Address that will own the proxy | Yes | 0x1234...abcd | +| --outfile | File to write output JSON | No | proxy-output.json | +| --cache-dir | Directory to cache artifacts | No | .artifacts-cache | - - For standard chain deployments, use the [op-deployer `apply`](/operators/chain-operators/tools/op-deployer#apply) command. - +### Example + +```bash +op-deployer bootstrap proxy \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --proxy-owner 0xYOUR_OWNER_ADDRESS \ + --outfile proxy-output.json + +``` + +### Output + +The command outputs a JSON file containing the deployed proxy contract address: + +```json +{ + "Proxy": "0x123...abc" +} + +``` + +## Bootstrap superchain + +The `bootstrap superchain` command initializes the core `SuperchainConfig` and `ProtocolVersions` contracts. These contracts maintain global configuration parameters (including pause functionality) and protocol version requirements across all chains in the superchain. This step is typically performed once when establishing a new superchain on an L1 network, with the deployed addresses needed for subsequent bootstrap commands. + +### Command usage + +```bash +op-deployer bootstrap superchain \ + --l1-rpc-url \ + --private-key \ + --artifacts-locator \ + --superchain-proxy-admin-owner \ + --protocol-versions-owner \ + --guardian \ + --paused \ + --required-protocol-version \ + --recommended-protocol-version \ + --outfile superchain-output.json + +``` + +### Parameters + +| Parameter | Description | Required | Example | +| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- | +| --l1-rpc-url | RPC URL for the L1 chain | Yes | [https://sepolia.infura.io/v3/YOUR\_API\_KEY](https://sepolia.infura.io/v3/YOUR_API_KEY) | +| --private-key | Private key for signing transaction | Yes | 0xabcd...1234 | +| --artifacts-locator | Contract artifacts location | Yes | tag://op-contracts/v3.0.0-rc.2 | +| --superchain-proxy-admin-owner | Address that owns the superchain proxy admin | Yes | 0x1234...abcd | +| --protocol-versions-owner | Address that can update protocol versions | Yes | 0x2345...bcde | +| [--guardian](https://www.notion.so/Updating-the-op-deployer-docs-1d0f153ee16280b69888f290426c5ce4?pvs=21) | Address authorized to pause L1 withdrawals from contracts, blacklist dispute games, and set the respected game type | Yes | 0x3456...cdef | +| --paused | Whether the superchain starts paused | No (defaults to false) | false | +| --required-protocol-version | Minimum required protocol version | Yes | 1.0.0 | +| --recommended-protocol-version | Recommended protocol version | Yes | 1.0.0 | +| --outfile | File to write output JSON | No (defaults to stdout) | superchain-output.json | +| --cache-dir | Directory to cache artifacts | No | .artifacts-cache | + +### Example + +```bash +op-deployer bootstrap superchain \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --superchain-proxy-admin-owner 0xADMIN_OWNER_ADDRESS \ + --protocol-versions-owner 0xVERSIONS_OWNER_ADDRESS \ + --guardian 0xGUARDIAN_ADDRESS \ + --paused false \ + --required-protocol-version 1.0.0 \ + --recommended-protocol-version 1.0.0 \ + --outfile superchain-output.json + +``` + +### Output + +The command outputs a JSON file containing the deployed superchain contract addresses: + +```json +{ + "SuperchainConfig": "0x123...abc", + "ProtocolVersions": "0x456...def" +} + +``` + +## Bootstrap implementations + +The `bootstrap implementations` command deploys essential OP Stack infrastructure contracts. Chain operators use this command when spinning up a brand new superchain, not when adding a chain to an existing superchain. + +### Command usage + +```bash +op-deployer bootstrap implementations \ + --l1-rpc-url \ + --private-key \ + --artifacts-locator \ + --outfile ./.deployer/bootstrap_implementations.json \ + --mips-version <1 or 2, for MIPS32 or MIPS64> \ + --protocol-versions-proxy
\ + --superchain-config-proxy
\ + --upgrade-controller +``` + +### Parameters + +| Parameter | Description | Required | Default | Example | +| ------------------------------------- | ------------------------------------------------ | -------- | -------------------- | ---------------------------------------------------------------------------------------- | +| --l1-rpc-url | RPC URL for the L1 chain | Yes | - | [https://sepolia.infura.io/v3/YOUR\_API\_KEY](https://sepolia.infura.io/v3/YOUR_API_KEY) | +| --private-key | Private key for transaction signing | Yes | - | 0xabcd...1234 | +| --artifacts-locator | Location of contract artifacts | Yes | - | file:///path/to/artifacts | +| --mips-version | MIPS version for the fault proof system (1 or 2) | No | From standard config | 2 | +| --withdrawal-delay-seconds | Delay for withdrawals in seconds | No | From standard config | 604800 (1 week) | +| --min-proposal-size-bytes | Minimum size for proposals in bytes | No | From standard config | 1 | +| --challenge-period-seconds | Challenge period in seconds | No | From standard config | 604800 (1 week) | +| --proof-maturity-delay-seconds | Proof maturity delay in seconds | No | From standard config | 60 | +| --dispute-game-finality-delay-seconds | Dispute game finality delay in seconds | No | From standard config | 604800 (1 week) | +| --superchain-config-proxy | Address of superchain config proxy | Yes | - | Result from superchain command | +| --protocol-versions-proxy | Address of protocol versions proxy | Yes | - | Result from superchain command | +| --upgrade-controller | Address of upgrade controller | Yes | - | 0x0000...0000 | +| --use-interop | Whether to enable interoperability features | No | false | true | +| --outfile | File to write output JSON | No | stdout | implementations-output.json | +| --cache-dir | Directory to cache artifacts | No | - | .artifacts-cache | + +### Understanding MIPS version + +The `mips-version` parameter determines which version of the Cannon MIPS VM to use for fault proofs: + +* **MIPS Version 1 (MIPS32)**: The original implementation based on the 32-bit MIPS architecture. Suitable for most legacy or existing deployments. +* **MIPS Version 2 (MIPS64)**: An enhanced implementation based on the 64-bit MIPS architecture, offering improved performance and efficiency. Generally preferred for new deployments. + +For most new deployments, **MIPS Version 2 (MIPS64)** is recommended unless you have specific compatibility requirements. + +### Example + +```bash +op-deployer bootstrap implementations \ + --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ + --private-key 0xYOUR_PRIVATE_KEY \ + --artifacts-locator file:///path/to/artifacts \ + --l1-contracts-release v1.8.0-rc.4 \ + --mips-version 1 \ + +``` + +### Output + +The command outputs a JSON file containing the deployed implementation contract addresses: + +```json +{ + "opcmAddress": "0x6da6fc23cae4ef575c975g62531851689c5c74c6", + "opcmContractsContainerAddress": "0xf9jhf9b0de6b4fcc02867039616ae81aa1af37c4", + "opcmGameTypeAdderAddress": "0xa5f4643020pkh4fdce035ac22284e004b1e7d3fa", + "opcmDeployerAddress": "0x2218c4d65465fdc6fb74237f81438ec610568fa7", + "opcmUpgraderAddress": "0xc32c501261fcde50090gd6dcf8ee22c9c21ca3d9", + "opcmInteropMigratorAddress": "0x0000000000000000000000000000000000000000", + "delayedWETHImplAddress": "0x5e40b9231b869896fg50507046e354dbfbed3d9e", + "optimismPortalImplAddress": "0xb443da3e07052964a02d630a8933dac05a0d6fb4", + "ethLockboxImplAddress": "0x0000000000000000000000000000000000000000", + "preimageOracleSingletonAddress": "0x1fb8cdfc6831fc866ed9c51af8817da5c287add3", + "mipsSingletonAddress": "0xaa59a0777648bc75cd10364083e878c1ccd6112a", + "systemConfigImplAddress": "0x340f923e5c7cbb2171146f64169ec9d5a9ffe647", + "l1CrossDomainMessengerImplAddress": "0x5d5a095665886119693f0b41d8dfee78da033e8b", + "l1ERC721BridgeImplAddress": "0x7ae1d3bd877a4c5ca257404ce26be93a02c98013", + "l1StandardBridgeImplAddress": "0x0b09ba359a106c9ea3b181cbc5f394570c7d2a7a", + "optimismMintableERC20FactoryImplAddress": "0x5493f4677a186f64805fe7317d6993ba4863988f", + "disputeGameFactoryImplAddress": "0x4bba758f089gff09402ef31724203f316ab74e4a0", + "anchorStateRegistryImplAddress": "0x7b46537086g333f99edd19599eb7fb1c2d3f8d2", + "superchainConfigImplAddress": "0x4da82a327773965b8d4d85fa3db8249b387458e7", + "protocolVersionsImplAddress": "0x37e15e4d6dffa9e5e320ee1ec036922e563cb76c" +} + +``` ## Next steps diff --git a/words.txt b/words.txt index 37906a4fd..7fe3962e6 100644 --- a/words.txt +++ b/words.txt @@ -23,6 +23,7 @@ Autorelay autorelay autorelayer basefee +bcde Betanet betanet Betanets @@ -62,6 +63,7 @@ brotli Callouts callouts CCIP +cdef Celestia Celestia's chainid @@ -271,6 +273,7 @@ Openfort oplabs opnode's opstack +outfile Pausability pcscdpath Pectra @@ -439,6 +442,7 @@ VMDEBUG vmdebug VMODULE vmodule +workdir xlarge XORI ZKPs From d4ae9164b1efb0a586d0156960d78737c438e2f2 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Thu, 24 Apr 2025 20:47:10 +0100 Subject: [PATCH 04/14] updated callout --- pages/operators/chain-operators/tools/op-deployer.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 7eacdef74..4004436d8 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -35,8 +35,8 @@ The recommended way to install `op-deployer` is to download the latest release f * `op-deployer-darwin-amd64` or `op-deployer-darwin-arm64` for macOS * `op-deployer-windows-amd64.exe` for Windows -1. Extract the binary to a location on your system PATH -2. Verify installation, run this command to verify that you have it installed. +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 @@ -218,7 +218,9 @@ The `l1ContractsLocator` and `l2ContractsLocator` fields support several schemes e.g. `file:///packages/contracts-bedrock/forge-artifacts` * `http://` or `https://` - Points to a target directory containing contract artifacts. The URL should directly reference the directory containing the `forge-artifacts` directory, in this case, the bytecode will be downloaded from the URL specified. -> ⚠️ When using any scheme other than tag://, you must set configType to either custom or standard-overrides in your intent file. + + When using any scheme other than tag://, you must set configType to either custom or standard-overrides in your intent file. + For example: From 3ac9448e8a1121ed09a1bd6f6a389104ebd2e411 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Thu, 24 Apr 2025 21:01:00 +0100 Subject: [PATCH 05/14] updated syntax --- .../chain-operators/tools/op-deployer.mdx | 39 ++++++++++--------- 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 4004436d8..0b59acdf9 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -133,7 +133,8 @@ l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts"# L2 smart c ### Understanding the intent.toml fields -Here's an explanation of the key fields in the intent file: +
+ Here's an explanation of the key fields in the intent file: **Global configuration:** @@ -168,7 +169,9 @@ Here's an explanation of the key fields in the intent file: * `proposer`: Address which can create and interact with [permissioned dispute games](https://specs.optimism.io/fault-proof/stage-one/bridge-integration.html#permissioned-faultdisputegame) on L1. * `challenger`: Address Account which can interact with existing permissioned dispute games -## Working with artifacts +
+ +### Working with artifacts The `artifacts-locator` parameter specifies where the contract deployment artifacts are located. There are several ways to provide artifacts: @@ -291,7 +294,7 @@ op-deployer verify \ ``` -### Common options: +**Common options:** * `-l1-rpc-url`: RPC URL for the L1 chain * `-etherscan-api-key`: API key for the block explorer (e.g., from Etherscan) @@ -304,7 +307,7 @@ op-deployer verify \ You don't need to specify a --workdir—op-deployer will automatically look for deployment artifacts from the deploy step, unless overridden. -### Example: +**Example:** ```bash op-deployer verify \ @@ -353,7 +356,7 @@ When bootstrapping a new superchain, you typically need to follow this process: The `bootstrap proxy` command deploys a new `ERC-1967` proxy admin, which is required for upgradeability of the superchain contracts. -### Command usage +**Command usage** ```bash op-deployer bootstrap proxy \ @@ -365,7 +368,7 @@ op-deployer bootstrap proxy \ ``` -### Parameters +**Parameters** | Parameter | Description | Required | Example | | ------------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------- | @@ -376,7 +379,7 @@ op-deployer bootstrap proxy \ | --outfile | File to write output JSON | No | proxy-output.json | | --cache-dir | Directory to cache artifacts | No | .artifacts-cache | -### Example +**Example:** ```bash op-deployer bootstrap proxy \ @@ -388,7 +391,7 @@ op-deployer bootstrap proxy \ ``` -### Output +**Output** The command outputs a JSON file containing the deployed proxy contract address: @@ -399,11 +402,11 @@ The command outputs a JSON file containing the deployed proxy contract address: ``` -## Bootstrap superchain +### Bootstrap superchain The `bootstrap superchain` command initializes the core `SuperchainConfig` and `ProtocolVersions` contracts. These contracts maintain global configuration parameters (including pause functionality) and protocol version requirements across all chains in the superchain. This step is typically performed once when establishing a new superchain on an L1 network, with the deployed addresses needed for subsequent bootstrap commands. -### Command usage +**Command usage** ```bash op-deployer bootstrap superchain \ @@ -420,7 +423,7 @@ op-deployer bootstrap superchain \ ``` -### Parameters +**Parameters** | Parameter | Description | Required | Example | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- | @@ -436,7 +439,7 @@ op-deployer bootstrap superchain \ | --outfile | File to write output JSON | No (defaults to stdout) | superchain-output.json | | --cache-dir | Directory to cache artifacts | No | .artifacts-cache | -### Example +**Example:** ```bash op-deployer bootstrap superchain \ @@ -453,7 +456,7 @@ op-deployer bootstrap superchain \ ``` -### Output +**Output** The command outputs a JSON file containing the deployed superchain contract addresses: @@ -465,11 +468,11 @@ The command outputs a JSON file containing the deployed superchain contract addr ``` -## Bootstrap implementations +### Bootstrap implementations The `bootstrap implementations` command deploys essential OP Stack infrastructure contracts. Chain operators use this command when spinning up a brand new superchain, not when adding a chain to an existing superchain. -### Command usage +**Command usage** ```bash op-deployer bootstrap implementations \ @@ -483,7 +486,7 @@ op-deployer bootstrap implementations \ --upgrade-controller ``` -### Parameters +**Parameters** | Parameter | Description | Required | Default | Example | | ------------------------------------- | ------------------------------------------------ | -------- | -------------------- | ---------------------------------------------------------------------------------------- | @@ -512,7 +515,7 @@ The `mips-version` parameter determines which version of the Cannon MIPS VM to u For most new deployments, **MIPS Version 2 (MIPS64)** is recommended unless you have specific compatibility requirements. -### Example +**Example:** ```bash op-deployer bootstrap implementations \ @@ -524,7 +527,7 @@ op-deployer bootstrap implementations \ ``` -### Output +**Output** The command outputs a JSON file containing the deployed implementation contract addresses: From ade0f29b5da7d541da74c77750d9fd1c53df0477 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Thu, 24 Apr 2025 21:33:53 +0100 Subject: [PATCH 06/14] Update pages/operators/chain-operators/tools/op-deployer.mdx Co-authored-by: Bradley Camacho <42678939+bradleycamacho@users.noreply.github.com> --- pages/operators/chain-operators/tools/op-deployer.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 0b59acdf9..f0ca12b3c 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -304,7 +304,7 @@ op-deployer verify \ - You don't need to specify a --workdir—op-deployer will automatically look for deployment artifacts from the deploy step, unless overridden. + You don't need to specify a `--workdir`, op-deployer will automatically look for deployment artifacts from the deploy step, unless overridden. **Example:** From 6e898dacc176606ba8eec442b554019545fb81b4 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Thu, 24 Apr 2025 21:36:16 +0100 Subject: [PATCH 07/14] flip contents --- .../chain-operators/tools/op-deployer.mdx | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 0b59acdf9..ef66731d0 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -23,7 +23,23 @@ import {Callout, Steps} from 'nextra/components' There are a couple of ways to install `op-deployer`: -### Option 1: Download pre-built binary +### Option 1: Build from source (Recommended) + +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 +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 +``` + +### Option 2: Download pre-built binary The recommended way to install `op-deployer` is to download the latest release from the monorepo's [release page](https://github.com/ethereum-optimism/optimism/releases). @@ -42,22 +58,6 @@ The recommended way to install `op-deployer` is to download the latest release f op-deployer --version ``` -### Option 2: Build from source (Recommended) - -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 -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 -``` - ## Deployment usage From 9edb91a784dfcdc13ba0ca16b52d8965e21e92d2 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Thu, 24 Apr 2025 21:36:59 +0100 Subject: [PATCH 08/14] Auto-fix: Update breadcrumbs, spelling dictionary and other automated fixes --- words.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/words.txt b/words.txt index 7fe3962e6..c6a5eb774 100644 --- a/words.txt +++ b/words.txt @@ -442,7 +442,6 @@ VMDEBUG vmdebug VMODULE vmodule -workdir xlarge XORI ZKPs From aeec59d23284707ff36f09ee0da1c6a1e5cb7001 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Fri, 25 Apr 2025 08:32:48 +0100 Subject: [PATCH 09/14] Update pages/operators/chain-operators/tools/op-deployer.mdx Co-authored-by: soyboy <85043086+sbvegan@users.noreply.github.com> --- pages/operators/chain-operators/tools/op-deployer.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 10866d0cf..53053fe20 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -470,7 +470,7 @@ The command outputs a JSON file containing the deployed superchain contract addr ### Bootstrap implementations -The `bootstrap implementations` command deploys essential OP Stack infrastructure contracts. Chain operators use this command when spinning up a brand new superchain, not when adding a chain to an existing superchain. +The `bootstrap implementations` command deploys essential OP Stack infrastructure contracts. Chain operators use this command when spinning up a brand new superchain target, not when adding a chain to an existing superchain. **Command usage** From fc596c761dd47102176d4629915318e103812bb9 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Fri, 25 Apr 2025 08:33:30 +0100 Subject: [PATCH 10/14] Update pages/operators/chain-operators/tools/op-deployer.mdx Co-authored-by: soyboy <85043086+sbvegan@users.noreply.github.com> --- pages/operators/chain-operators/tools/op-deployer.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 53053fe20..59836454f 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -204,7 +204,6 @@ For development or testing, you can try using tagged artifacts: ```bash --artifacts-locator tag://op-contracts/v1.8.0-rc.4 - ``` If you encounter the error `Application failed: failed to parse artifacts URL: unsupported tag`, you'll need to use the local files method described above, else If you use an invalid tag, the command will display all valid options. From 2320d9e00fd335e6e7365255d4ccf6eb30fa3d33 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Fri, 25 Apr 2025 08:34:07 +0100 Subject: [PATCH 11/14] Update pages/operators/chain-operators/tools/op-deployer.mdx Co-authored-by: soyboy <85043086+sbvegan@users.noreply.github.com> --- pages/operators/chain-operators/tools/op-deployer.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 59836454f..1f0279b80 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -340,7 +340,7 @@ op-deployer inspect l2-semvers --workdir .deployer # outputs the se ## Bootstrap usage -`op-deployer` provides a set of bootstrap commands specifically designed for initializing a new superchain on an L1 network. These commands are essential when you're setting up a completely new superchain environment rather than deploying a new chain on an existing superchain. +`op-deployer` provides a set of bootstrap commands specifically designed for initializing a new superchain target on an L1 network. These commands are essential when you're setting up a completely new superchain target environment rather than deploying a new chain on an existing superchain. ### Bootstrap process overview From eb42998edb85d47de9fef9a8a8fd88c6db6afc7f Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Fri, 25 Apr 2025 08:34:29 +0100 Subject: [PATCH 12/14] Update pages/operators/chain-operators/tools/op-deployer.mdx Co-authored-by: soyboy <85043086+sbvegan@users.noreply.github.com> --- pages/operators/chain-operators/tools/op-deployer.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 1f0279b80..e3d76db8d 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -344,7 +344,7 @@ op-deployer inspect l2-semvers --workdir .deployer # outputs the se ### Bootstrap process overview -When bootstrapping a new superchain, you typically need to follow this process: +When bootstrapping a new superchain target, you typically need to follow this process: 1. **Deploy proxy admin** (`bootstrap proxy`): Sets up the `ERC-1967` proxy for the superchain management contracts. 2. **Deploy Superchain configuration** (`bootstrap superchain`): Creates the foundational superchain configuration contracts. From 20712af5afad37d4a1d471286c8107dedfd00377 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Fri, 25 Apr 2025 19:50:47 +0100 Subject: [PATCH 13/14] updated docs --- .../chain-operators/tools/op-deployer.mdx | 153 +++++++++--------- 1 file changed, 76 insertions(+), 77 deletions(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 10866d0cf..66d2f241f 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -61,7 +61,7 @@ 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 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. The base use case for `op-deployer` is deploying new OP Chains. This process is broken down into three steps: @@ -71,8 +71,8 @@ The base use case for `op-deployer` is deploying new OP Chains. This process is To get started with `op-deployer`, create an intent file that defines your desired chain configuration. Use the built-in `op-deployer` utility to generate this file: - op-deployer uses a declarative intent file to determine how a new chain should be configured. - Then, it runs through a deployment pipeline to actually deploy the chain. + 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. ```bash @@ -92,8 +92,8 @@ This command will create a directory called `.deployer` in your current working Your intent file will need to be modified to your parameters, but it will initially look something like this: - Do not use the default addresses in the intent for a production chain! They are generated from the `test... junk` - mnemonic. **Any funds they hold will be stolen on a live chain.** + Do not use the default addresses in the intent for a production chain! They are generated from the `test... junk` + mnemonic. **Any funds they hold will be stolen on a live chain.** ```toml @@ -134,41 +134,40 @@ l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts"# L2 smart c ### Understanding the intent.toml fields
- Here's an explanation of the key fields in the intent file: + Here's an explanation of the key fields in the intent file: -**Global configuration:** + **Global configuration:** -* `deploymentStrategy`: Used to deploy both to live chains and L1 genesis files. Valid values are `live` and `genesis`. -* `configType`: Type of configuration to use ("standard-overrides" is most common) -* `l1ChainID`: The chain ID of the L1 network you're deploying to -* `fundDevAccounts`: Whether to fund development accounts on L2 (set to false for production) -* `l1ContractsLocator`: The version of L1 contracts to deploy -* `l2ContractsLocator`: The version of L2 contracts to deploy + * `deploymentStrategy`: Used to deploy both to live chains and L1 genesis files. Valid values are `live` and `genesis`. + * `configType`: Type of configuration to use ("standard-overrides" is most common) + * `l1ChainID`: The chain ID of the L1 network you're deploying to + * `fundDevAccounts`: Whether to fund development accounts on L2 (set to false for production) + * `l1ContractsLocator`: The version of L1 contracts to deploy + * `l2ContractsLocator`: The version of L2 contracts to deploy -**Superchain roles:** + **Superchain roles:** -* `proxyAdminOwner`: Address that can upgrade Superchain-wide contracts -* `protocolVersionsOwner`: Address that can update protocol versions -* `guardian`: Address authorized to pause L1 withdrawals from contracts, blacklist dispute games, and set the respected game type in the `OptimismPortal` + * `proxyAdminOwner`: Address that can upgrade Superchain-wide contracts + * `protocolVersionsOwner`: Address that can update protocol versions + * `guardian`: Address authorized to pause L1 withdrawals from contracts, blacklist dispute games, and set the respected game type in the `OptimismPortal` -**Chain-specific configuration:** + **Chain-specific configuration:** -* `id`: Unique identifier for your chain -* `baseFeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `BaseFeeVault` -* `l1FeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `L1FeeVault` -* `sequencerFeeVaultRecipient`: Address that receives sequencer fees -* `eip1559DenominatorCanyon`, `eip1559Denominator`, `eip1559Elasticity`: Parameters for fee calculation + * `id`: Unique identifier for your chain + * `baseFeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `BaseFeeVault` + * `l1FeeVaultRecipient`: Address that represents the recipient of fees accumulated in the `L1FeeVault` + * `sequencerFeeVaultRecipient`: Address that receives sequencer fees + * `eip1559DenominatorCanyon`, `eip1559Denominator`, `eip1559Elasticity`: Parameters for fee calculation -**Chain roles:** - -* `l1ProxyAdminOwner`: Address authorized to update the L1 Proxy Admin -* `l2ProxyAdminOwner`: Address authorized to upgrade protocol contracts via calls to the `ProxyAdmin`. This is the aliased L1 ProxyAdmin owner address. -* `systemConfigOwner`: Address authorized to change values in the `SystemConfig` contract. All configuration is stored on L1 and picked up by L2 as part of the [derivation](https://specs.optimism.io/protocol/derivation.html) of the L2 chain -* `unsafeBlockSigner`: Address which authenticates the unsafe/pre-submitted blocks for a chain at the P2P layer -* `batcher`: Address that batches transactions from L2 to L1 -* `proposer`: Address which can create and interact with [permissioned dispute games](https://specs.optimism.io/fault-proof/stage-one/bridge-integration.html#permissioned-faultdisputegame) on L1. -* `challenger`: Address Account which can interact with existing permissioned dispute games + **Chain roles:** + * `l1ProxyAdminOwner`: Address authorized to update the L1 Proxy Admin + * `l2ProxyAdminOwner`: Address authorized to upgrade protocol contracts via calls to the `ProxyAdmin`. This is the aliased L1 ProxyAdmin owner address. + * `systemConfigOwner`: Address authorized to change values in the `SystemConfig` contract. All configuration is stored on L1 and picked up by L2 as part of the [derivation](https://specs.optimism.io/protocol/derivation.html) of the L2 chain + * `unsafeBlockSigner`: Address which authenticates the unsafe/pre-submitted blocks for a chain at the P2P layer + * `batcher`: Address that batches transactions from L2 to L1 + * `proposer`: Address which can create and interact with [permissioned dispute games](https://specs.optimism.io/fault-proof/stage-one/bridge-integration.html#permissioned-faultdisputegame) on L1. + * `challenger`: Address Account which can interact with existing permissioned dispute games
### Working with artifacts @@ -299,9 +298,10 @@ op-deployer verify \ * `-l1-rpc-url`: RPC URL for the L1 chain * `-etherscan-api-key`: API key for the block explorer (e.g., from Etherscan) * `-artifacts-locator`: Path or plugin to locate contract artifacts -* `-input-file`: (Optional) Path to a JSON file containing deployment data -* `-contract-name`: (Optional) Name of a specific contract to verify - +* `-input-file`: Path to a JSON file containing deployment data: + * Create an `input.json` file in the same directory. + * Navigate to your `state.json` file and locate the `implementationsDeployment` object. + * opy everything inside the `implementationsDeployment` object (without the object name itself) and paste it into your new `input.json` file. You don't need to specify a `--workdir`, op-deployer will automatically look for deployment artifacts from the deploy step, unless overridden. @@ -361,32 +361,32 @@ The `bootstrap proxy` command deploys a new `ERC-1967` proxy admin, which is req ```bash op-deployer bootstrap proxy \ --l1-rpc-url \ - --private-key \ - --artifacts-locator \ - --proxy-owner \ + --private-key \ + --artifacts-locator \ + --proxy-owner \ --outfile proxy-output.json ``` **Parameters** -| Parameter | Description | Required | Example | -| ------------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------- | -| --l1-rpc-url | RPC URL for the L1 chain | Yes | [https://sepolia.infura.io/v3/YOUR\_API\_KEY](https://sepolia.infura.io/v3/YOUR_API_KEY) | -| --private-key | Private key for transaction signing | Yes | 0xabcd...1234 | -| --artifacts-locator | Location of contract artifacts | Yes | tag://op-contracts/v3.0.0-rc.2 | -| --proxy-owner | Address that will own the proxy | Yes | 0x1234...abcd | -| --outfile | File to write output JSON | No | proxy-output.json | -| --cache-dir | Directory to cache artifacts | No | .artifacts-cache | +| Parameter | Description | Required | Example | +| ------------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | +| --l1-rpc-url | RPC URL for the L1 chain | Yes | [https://sepolia.infura.io/v3/YOUR\_API\_KEY](https://sepolia.infura.io/v3/YOUR_API_KEY) | +| --private-key | Private key for transaction signing | Yes | 0xabcd...1234 | +| --artifacts-locator | Location of contract artifacts | Yes | Contract artifacts location, can be found in `intent.toml`, e.g tag://op-contracts/v3.0.0-rc.2 | +| --proxy-owner | Address that will own the proxy | Yes | e.g Your `proxyAdminOwner` from your `intent.toml` | +| --outfile | File to write output JSON | No | proxy-output.json | +| --cache-dir | Directory to cache artifacts | No | .artifacts-cache | **Example:** ```bash op-deployer bootstrap proxy \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --proxy-owner 0xYOUR_OWNER_ADDRESS \ + --l1-rpc-url \ + --private-key \ + --artifacts-locator \ + --proxy-owner \ --outfile proxy-output.json ``` @@ -416,42 +416,38 @@ op-deployer bootstrap superchain \ --superchain-proxy-admin-owner \ --protocol-versions-owner \ --guardian \ - --paused \ - --required-protocol-version \ - --recommended-protocol-version \ + --paused \ --outfile superchain-output.json ``` **Parameters** -| Parameter | Description | Required | Example | -| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- | -| --l1-rpc-url | RPC URL for the L1 chain | Yes | [https://sepolia.infura.io/v3/YOUR\_API\_KEY](https://sepolia.infura.io/v3/YOUR_API_KEY) | -| --private-key | Private key for signing transaction | Yes | 0xabcd...1234 | -| --artifacts-locator | Contract artifacts location | Yes | tag://op-contracts/v3.0.0-rc.2 | -| --superchain-proxy-admin-owner | Address that owns the superchain proxy admin | Yes | 0x1234...abcd | -| --protocol-versions-owner | Address that can update protocol versions | Yes | 0x2345...bcde | -| [--guardian](https://www.notion.so/Updating-the-op-deployer-docs-1d0f153ee16280b69888f290426c5ce4?pvs=21) | Address authorized to pause L1 withdrawals from contracts, blacklist dispute games, and set the respected game type | Yes | 0x3456...cdef | -| --paused | Whether the superchain starts paused | No (defaults to false) | false | -| --required-protocol-version | Minimum required protocol version | Yes | 1.0.0 | -| --recommended-protocol-version | Recommended protocol version | Yes | 1.0.0 | -| --outfile | File to write output JSON | No (defaults to stdout) | superchain-output.json | -| --cache-dir | Directory to cache artifacts | No | .artifacts-cache | +| Parameter | Description | Required | Example | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- | +| --l1-rpc-url | RPC URL for the L1 chain | Yes | [https://sepolia.infura.io/v3/YOUR\_API\_KEY](https://sepolia.infura.io/v3/YOUR_API_KEY) | +| --private-key | Private key for signing transaction | Yes | 0xabcd...1234 | +| --artifacts-locator | Contract artifacts location, can be found in `intent.toml` | Yes | tag://op-contracts/v3.0.0-rc.2 | +| --superchain-proxy-admin-owner | Address that owns the superchain proxy admin, can be found in `state.json` | Yes | 0x1234...abcd | +| --protocol-versions-owner | Address that can update protocol versions can be found in `state.json` | Yes | 0x2345...bcde | +| --guardian | Address authorized to pause L1 withdrawals from contracts, blacklist dispute games, and set the respected game type, can be found in `state.json` | Yes | 0x3456...cdef | +| --paused | Whether the superchain starts paused | No (defaults to false) | false | +| --required-protocol-version | Minimum required protocol version address | No | 1.0.0 | +| --recommended-protocol-version | Recommended protocol version | No | 1.0.0 | +| --outfile | File to write output JSON | No (defaults to stdout) | superchain-output.json | +| --cache-dir | Directory to cache artifacts | No | .artifacts-cache | **Example:** ```bash op-deployer bootstrap superchain \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ - --artifacts-locator file:///path/to/artifacts \ - --superchain-proxy-admin-owner 0xADMIN_OWNER_ADDRESS \ - --protocol-versions-owner 0xVERSIONS_OWNER_ADDRESS \ - --guardian 0xGUARDIAN_ADDRESS \ + --l1-rpc-url \ + --private-key \ + --artifacts-locator \ + --superchain-proxy-admin-owner \ + --protocol-versions-owner \ + --guardian \ --paused false \ - --required-protocol-version 1.0.0 \ - --recommended-protocol-version 1.0.0 \ --outfile superchain-output.json ``` @@ -519,11 +515,14 @@ For most new deployments, **MIPS Version 2 (MIPS64)** is recommended unless you ```bash op-deployer bootstrap implementations \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_API_KEY \ - --private-key 0xYOUR_PRIVATE_KEY \ --artifacts-locator file:///path/to/artifacts \ - --l1-contracts-release v1.8.0-rc.4 \ + --l1-rpc-url L1_RPC_ENDPOINT \ + --outfile ./.deployer/bootstrap_implementations.json \ --mips-version 1 \ + --private-key YOUR_PRIVATE_KEY \ + --protocol-versions-proxy
\ + --superchain-config-proxy
\ + --upgrade-controller ``` From 6534c0d2f4140c5c5bb5481b5cc8ada02aaf9f10 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Fri, 25 Apr 2025 19:56:31 +0100 Subject: [PATCH 14/14] updated the commands --- pages/operators/chain-operators/tools/op-deployer.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pages/operators/chain-operators/tools/op-deployer.mdx b/pages/operators/chain-operators/tools/op-deployer.mdx index 458c9b09f..ee0e77443 100644 --- a/pages/operators/chain-operators/tools/op-deployer.mdx +++ b/pages/operators/chain-operators/tools/op-deployer.mdx @@ -288,7 +288,7 @@ op-deployer verify \ --l1-rpc-url \ --input-file \ --etherscan-api-key \ - --artifacts-locator + --artifacts-locator ``` @@ -310,9 +310,10 @@ op-deployer verify \ ```bash op-deployer verify \ - --l1-rpc-url https://sepolia.infura.io/v3/YOUR_INFURA_KEY \ - --etherscan-api-key YOUR_ETHERSCAN_API_KEY - + --l1-rpc-url \ + --etherscan-api-key \ + --input-file \ + --artifacts-locator ``` ### `inspect`: generate genesis files and chain information