From 406fbdc13e802fe0bd44afd74218677ca1af8f67 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Wed, 23 Jul 2025 15:55:58 +0100 Subject: [PATCH 01/12] Refactor op-challenger documentation and update links - Updated the link for the op-challenger tool in the architecture documentation. - Added a new card for configuring the op-challenger in the deployment section. - Removed the op-challenger tutorial file as its content has been integrated into the deployment section. - Updated metadata to include op-challenger description. - Added a redirect for the op-challenger tool to its new location. --- .../chain-operators/architecture.mdx | 2 +- pages/operators/chain-operators/deploy.mdx | 2 + .../chain-operators/deploy/_meta.json | 3 +- .../chain-operators/deploy/op-challenger.mdx | 399 ++++++++++++++++++ pages/operators/chain-operators/tools.mdx | 4 - .../chain-operators/tools/op-challenger.mdx | 234 ---------- pages/stack/fault-proofs/challenger.mdx | 2 +- public/_redirects | 2 + words.txt | 231 +++++----- 9 files changed, 522 insertions(+), 357 deletions(-) create mode 100644 pages/operators/chain-operators/deploy/op-challenger.mdx delete mode 100644 pages/operators/chain-operators/tools/op-challenger.mdx diff --git a/pages/operators/chain-operators/architecture.mdx b/pages/operators/chain-operators/architecture.mdx index 2a9d9a34d..22d7a9774 100644 --- a/pages/operators/chain-operators/architecture.mdx +++ b/pages/operators/chain-operators/architecture.mdx @@ -178,7 +178,7 @@ The [op-conductor](/operators/chain-operators/tools/op-conductor) RPC can act as ### op-challenger -The [op-challenger](/operators/chain-operators/tools/op-challenger) verifies the correctness of the L2 state by challenging invalid state transitions. This ensures the network's security and validity. +The [op-challenger](/operators/chain-operators/deploy/op-challenger) verifies the correctness of the L2 state by challenging invalid state transitions. This ensures the network's security and validity. ### Ethereum L1 nodes diff --git a/pages/operators/chain-operators/deploy.mdx b/pages/operators/chain-operators/deploy.mdx index ee408564e..72da80410 100644 --- a/pages/operators/chain-operators/deploy.mdx +++ b/pages/operators/chain-operators/deploy.mdx @@ -38,5 +38,7 @@ This section provides information on OP Stack genesis creation, deployment overv + + diff --git a/pages/operators/chain-operators/deploy/_meta.json b/pages/operators/chain-operators/deploy/_meta.json index da35b2252..d277bc0e9 100644 --- a/pages/operators/chain-operators/deploy/_meta.json +++ b/pages/operators/chain-operators/deploy/_meta.json @@ -5,6 +5,7 @@ "validate-deployment": "Validate your contract deployment", "sequencer-node": "Spinning up the sequencer", "proposer-setup-guide": "Spinning up the proposer", - "spin-batcher": "Spinning up the batcher" + "spin-batcher": "Spinning up the batcher", + "op-challenger": "op-challenger" } diff --git a/pages/operators/chain-operators/deploy/op-challenger.mdx b/pages/operators/chain-operators/deploy/op-challenger.mdx new file mode 100644 index 000000000..fba206714 --- /dev/null +++ b/pages/operators/chain-operators/deploy/op-challenger.mdx @@ -0,0 +1,399 @@ +--- +title: How to configure challenger for your chain +description: Learn how to configure challenger for your OP Stack chain. +lang: en-US +content_type: tutorial +topic: configure-challenger-for-your-chain +personas: + - chain-operator +categories: + - mainnet + - testnet + - fault-proofs + - op-challenger + - chain-configuration +is_imported_content: 'false' +--- + +# How to configure challenger for your chain + +## Overview + +This guide provides step-by-step instructions for setting up the configuration and monitoring options for `op-challenger`. The challenger is a critical fault proofs component that monitors dispute games and challenges invalid claims to protect your OP Stack chain. + +See the [OP-Challenger Explainer](/stack/fault-proofs/challenger) for a general overview of this fault proofs feature. + +The challenger is responsible for: + +* Monitoring dispute games created by the fault proof system +* Challenging invalid claims in dispute games +* Defending valid state transitions +* Resolving games when possible + +## Prerequisites + +### Essential requirements + +Before configuring your challenger, complete the following steps: + +1. **Deployed OP Stack chain with fault proofs enabled:** + * L1 contracts deployed with dispute game factory + * Fault proof system active on your chain + * Access to your chain's contract addresses + +2. **Required infrastructure access:** + * L1 RPC endpoint (Ethereum, Sepolia, etc.) + * L1 Beacon node endpoint (for blob access) + * L2 archive node with debug API enabled + * Rollup node (op-node) with historical data + +3. **Configuration files:** + * `rollup.json` - Rollup configuration file + * `genesis-l2.json` - L2 genesis file + * Prestate files for your network version + +### Software requirements + +* Git (for cloning repositories) +* Go 1.21+ (if building from source) +* Docker and Docker Compose (optional but recommended) +* Access to a funded Ethereum account for challenger operations + +### Finding the current stable releases + +To ensure you're using the latest compatible versions of OP Stack components, always check the official releases page: + +[OP Stack releases page](https://github.com/ethereum-optimism/optimism/releases) + +Look for the latest `op-challenger/v*` release. The challenger version used in this guide (op-challenger/v0.2.11) is a verified stable version. + +Always check the release notes to ensure you're using compatible versions with your chain's deployment. + +## Software installation + +For challenger deployment, we recommend building from source as it provides better control and helps with debugging. A Docker alternative is also provided. + +### Build from source (Recommended) + +Building from source gives you full control over the binaries and is the preferred approach for production deployments. + +1. **Clone and build op-challenger** + +```bash +# Clone the optimism monorepo +git clone https://github.com/ethereum-optimism/optimism.git +cd optimism + +# Check out the latest release of op-challenger +git checkout op-challenger/v0.2.11 + +# Install dependencies and build +pnpm install +make op-challenger + +# Binary will be available at ./op-challenger/bin/op-challenger +``` + +### Verify installation + +Check that you have properly installed the challenger component: + +```bash +# Make sure you're in the optimism directory +./op-challenger/bin/op-challenger --help +``` + +## Configuration setup + +### 1. Organize your workspace + +After building the binaries, create your challenger working directory: + +```bash +# Create challenger directory +mkdir ~/challenger-node +cd ~/challenger-node + +# Create necessary subdirectories +mkdir scripts +mkdir challenger-data +``` + +### 2. Copy configuration files + +```bash +# Copy configuration files to your challenger directory +# Adjust paths based on your deployment setup +cp /path/to/your/rollup.json . +cp /path/to/your/genesis-l2.json . +``` + +### 3. Environment variables + +You'll need to gather several pieces of information before creating your configuration. Here's where to get each value: + +**L1 network access:** + +* L1 RPC URL: Your L1 node endpoint (Infura, Alchemy, or self-hosted) +* L1 Beacon URL: Beacon chain API endpoint for blob access + +**L2 network access:** + +* L2 RPC URL: Your op-geth archive node endpoint +* Rollup RPC URL: Your op-node endpoint with historical data + +**Challenger wallet:** + +* Private key for challenger operations (must be funded) + +**Network configuration:** + +* Game factory address from your contract deployment +* Network identifier (e.g., op-sepolia, op-mainnet, or custom) + +Create your `.env` file with the actual values: + +```bash +# Create .env file with your actual values +cat > .env << 'EOF' +# L1 Configuration - Replace with your actual RPC URLs +L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY +L1_BEACON_URL=https://ethereum-sepolia-beacon-api.publicnode.com + +# L2 Configuration - Replace with your actual node endpoints +L2_RPC_URL=http://your-op-geth-archive:8545 +ROLLUP_RPC_URL=http://your-op-node:8547 + +# Challenger wallet - Replace with your actual private key +PRIVATE_KEY=0xYOUR_ACTUAL_PRIVATE_KEY + +# Network configuration +NETWORK=op-sepolia +GAME_FACTORY_ADDRESS=0xYOUR_GAME_FACTORY_ADDRESS + +# Data directory +DATADIR=./challenger-data + +# Cannon configuration +CANNON_PRESTATES_URL=https://example.com/prestates +CANNON_ROLLUP_CONFIG=./rollup.json +CANNON_L2_GENESIS=./genesis-l2.json +EOF +``` + +**Important:** Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values. + +## Challenger configuration + +### Understanding key configuration flags + +#### `--l1-eth-rpc` + +* HTTP provider URL for a standard L1 node, can be a full node +* `op-challenger` will be sending many requests, so use a trusted node that can handle many transactions +* **Critical:** Challenger controls significant funds and will spend if needed to defend games + +#### `--l1-beacon` + +* Needed for blob access from L1 consensus layer +* **Important considerations:** + * If your chain posts regularly: standard beacon node is sufficient + * If your chain doesn't post valid output roots within 18 days: blob archiver is required + * Configure consensus node to not prune blobs if needed + +#### `--l2-eth-rpc` + +* Must be an `op-geth` archive node with `debug` API enabled +* Doesn't need full bedrock history but needs access to data from any active game start + +#### `--rollup-rpc` + +* Must be an `op-node` archive node with historical output roots +* **SafeDB Configuration:** The `op-node` must have SafeDB enabled: + * Set `--safedb.path` to persist safe head update data + * Example: `--safedb.path /path/to/safe-head-db` + * If path not set, SafeDB will be disabled + +#### `--network` + +* Identifies the L2 network (e.g., `op-sepolia`, `op-mainnet`) +* When using `--network` flag, `--game-factory-address` is auto-loaded from [superchain-registry](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json) +* For custom networks, you must specify `--game-factory-address` and related configs manually + +#### `--cannon-prestates-url` + +* The prestate is the version of `op-program` deployed on chain +* **Critical:** Must use the correct version to avoid invalid claims +* Challenger will refuse to interact with games that have different prestate hash +* Two options: + * `--cannon-prestate`: path to single prestate JSON file + * `--cannon-prestates-url`: URL to load multiple prestates (recommended) + +### Create challenger startup script + +Create `scripts/start-challenger.sh`: + +```bash +#!/bin/bash +source .env + +# Path to the challenger binary +../optimism/op-challenger/bin/op-challenger \ + --l1-eth-rpc=$L1_RPC_URL \ + --l1-beacon=$L1_BEACON_URL \ + --l2-eth-rpc=$L2_RPC_URL \ + --rollup-rpc=$ROLLUP_RPC_URL \ + --selective-claim-resolution \ + --private-key=$PRIVATE_KEY \ + --network=$NETWORK \ + --datadir=$DATADIR \ + --cannon-prestates-url=$CANNON_PRESTATES_URL \ + --cannon-rollup-config=$CANNON_ROLLUP_CONFIG \ + --cannon-l2-genesis=$CANNON_L2_GENESIS \ + --trace-type=permissioned,cannon \ + --log.level=info \ + --log.format=json +``` + +### Custom network configuration + +For custom networks not in the superchain-registry, additional flags are required: + +```bash +# Additional flags for custom networks +--cannon-rollup-config rollup.json \ +--cannon-l2-genesis genesis-l2.json \ +--cannon-server ./op-program/bin/op-program \ +--cannon-prestate ./op-program/bin/prestate.json \ +--game-factory-address=0xYOUR_GAME_FACTORY_ADDRESS +``` + +**Warning:** These options vary based on which `--network` is specified. Chain operators always need to specify a way to load prestates and must also specify the cannon-server when not using Docker images. + +## Initializing and starting the challenger + +### Start the challenger + +```bash +# Make sure you're in the challenger-node directory +cd ~/challenger-node + +# Make script executable +chmod +x scripts/start-challenger.sh + +# Start challenger +./scripts/start-challenger.sh +``` + +### Verify challenger is running + +Monitor challenger logs to ensure it's operating correctly: + +```bash +# Check challenger logs +tail -f challenger-data/challenger.log + +# Or if running in foreground, monitor the output +``` + +The challenger should show logs indicating: + +* Successful connection to L1 and L2 nodes +* Loading of prestates and configuration +* Monitoring of dispute games + +## Docker alternative + +If you prefer containerized deployment, you can use the official Docker images that include embedded `op-program` server and Cannon executable. + +### Complete Docker setup + +Create `docker-compose.yml`: + +```yaml +version: '3.8' + +services: + challenger: + image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:v0.2.11 + user: "1000" + volumes: + - ./challenger-data:/data + - ./rollup.json:/workspace/rollup.json:ro + - ./genesis-l2.json:/workspace/genesis-l2.json:ro + environment: + - L1_RPC_URL=${L1_RPC_URL} + - L1_BEACON_URL=${L1_BEACON_URL} + - L2_RPC_URL=${L2_RPC_URL} + - ROLLUP_RPC_URL=${ROLLUP_RPC_URL} + - PRIVATE_KEY=${PRIVATE_KEY} + - NETWORK=${NETWORK} + command: + - "op-challenger" + - "--l1-eth-rpc=${L1_RPC_URL}" + - "--l1-beacon=${L1_BEACON_URL}" + - "--l2-eth-rpc=${L2_RPC_URL}" + - "--rollup-rpc=${ROLLUP_RPC_URL}" + - "--selective-claim-resolution" + - "--private-key=${PRIVATE_KEY}" + - "--network=${NETWORK}" + - "--datadir=/data" + - "--cannon-prestates-url=${CANNON_PRESTATES_URL}" + restart: unless-stopped + ports: + - "8548:8548" # If challenger exposes metrics endpoint +``` + +Start with Docker: + +```bash +# Start the challenger service +docker-compose up -d + +# View logs +docker-compose logs -f challenger +``` + +## Testing and debugging (Optional) + +Use `op-challenger` subcommands to interact with the Fault Proof System for testing and debugging purposes: + +### Available subcommands + +| Subcommand | Description | +| --------------- | -------------------------------------------------------- | +| `list-games` | List the games created by a dispute game factory | +| `list-claims` | List the claims in a dispute game | +| `list-credits` | List the credits in a dispute game | +| `create-game` | Creates a dispute game via the factory | +| `move` | Creates and sends a move transaction to the dispute game | +| `resolve` | Resolves the specified dispute game if possible | +| `resolve-claim` | Resolves the specified claim if possible | + +### Example testing commands + +```bash +# List recent games +./op-challenger/bin/op-challenger list-games \ + --l1-eth-rpc=$L1_RPC_URL \ + --game-factory-address=$GAME_FACTORY_ADDRESS + +# List claims in a specific game +./op-challenger/bin/op-challenger list-claims \ + --l1-eth-rpc=$L1_RPC_URL \ + --game-address=0xGAME_ADDRESS +``` + +### Monitoring with op-dispute-mon + +Consider running `op-dispute-mon` for enhanced security monitoring: + +* Provides visibility into all game statuses for the last 28 days +* Essential for production challenger deployments +* Create Grafana dashboards using: [Download the Dispute Monitor JSON](/resources/grafana/dispute-monitor-1718214549035.json) + +## Next steps + +* Read the [OP-Challenger Explainer](/stack/fault-proofs/challenger) for additional context and FAQ +* Review the detailed [challenger specifications](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html) for implementation details +* If you experience any problems, reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions) diff --git a/pages/operators/chain-operators/tools.mdx b/pages/operators/chain-operators/tools.mdx index d46a54afa..1952fdf2a 100644 --- a/pages/operators/chain-operators/tools.mdx +++ b/pages/operators/chain-operators/tools.mdx @@ -32,12 +32,8 @@ This section provides information on chain monitoring options, deploying a block - - - - diff --git a/pages/operators/chain-operators/tools/op-challenger.mdx b/pages/operators/chain-operators/tools/op-challenger.mdx deleted file mode 100644 index 7d7f8c025..000000000 --- a/pages/operators/chain-operators/tools/op-challenger.mdx +++ /dev/null @@ -1,234 +0,0 @@ ---- -title: How to configure challenger for your chain -description: Learn how to configure challenger for your OP Stack chain. -lang: en-US -content_type: tutorial -topic: configure-challenger-for-your-chain -personas: - - chain-operator -categories: - - mainnet - - testnet - - fault-proofs - - op-challenger - - chain-configuration -is_imported_content: 'false' ---- - -import { Callout, Steps } from 'nextra/components' - -# How to configure challenger for your chain - -This guide provides a walkthrough of setting up the configuration and monitoring options for `op-challenger`. See the [OP-Challenger Explainer](/stack/fault-proofs/challenger) for a general overview of this fault proofs feature. - - - ### Build the executable - - * Clone the monorepo - - ```bash - git clone https://github.com/ethereum-optimism/optimism.git - ``` - - * Check out the [latest release of `op-challenger`](https://github.com/ethereum-optimism/optimism/releases) and use the commit to deploy. Alternatively, chain operators can use the prebuilt challenger docker images included in the release notes. - If a Docker image is used, it already comes with `op-program` server and an executable for Cannon embedded, so the Cannon bin doesn't need to be specified. - - ```bash - git checkout op-challenger/vX.Y.Z - ``` - - - Chain operators need to specify the arguments and `op-program` server if `op-challenger` is running outside of Docker, but there's a Cannon server option which points to `op-program`'s executable. - - - * Build challenger - - ```bash - cd optimism - pnpm install - make op-challenger - ``` - - ### Configure challenger - - * Configure challenger with the required flags. Tip: Use the `op-challenger --help` to view all subcommands, command line, and environment variable options. - * The example config file below shows the flags to configure in this step: - - ```docker - challenger: - user: "1000" - image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:v0.2.11 - command: - - "op-challenger" - - "--l1-eth-rpc=http://sepolia-el-1:8545" - - "--l1-beacon=http://sepolia-cl-1:5051" - - "--l2-eth-rpc=http://op-sepolia-el-1:8545" - - "--rollup-rpc=http://op-sepolia-cl-1:5051" - - "--selective-claim-resolution" - - "--private-key=...." - - "--network=..." - - "--datadir=/data" - - "--cannon-prestates-url=..." - volumes: - - "./challenger-data:/data" - ``` - - #### `--l1-eth-rpc` - - * This is the HTTP provider URL for a standard L1 node, can be a full node. `op-challenger` will be sending many requests, so chain operators need a node that is trusted and can easily handle many transactions. - * Note: Challenger has a lot of money, and it will spend it if it needs to interact with games. That might risk not defending games or challenging games correctly, so chain operators should really trust the nodes being pointed at Challenger. - - #### `--l1-beacon` - - * This is needed just to get blobs from. - * In some instances, chain operators might need a blob archiver or L1 consensus node configured not to prune blobs: - * If the chain is proposing regularly, a blob archiver isn't needed. There's only a small window in the blob retention period that games can be played. - * If the chain doesn't post a valid output root in 18 days, then a blob archiver running a challenge game is needed. If the actor gets pushed to the bottom of the game, it could lose if it's the only one protecting the chain. - - #### `--l2-eth-rpc` - - * This needs to be `op-geth` archive node, with `debug` enabled. - * Technically doesn't need to go to bedrock, but needs to have access to the start of any game that is still in progress. - - #### `--rollup-rpc` - - * This needs to be an `op-node` archive node because challenger needs access to output roots from back when the games start. See below for important configuration details: - - 1. Safe Head Database (SafeDB) Configuration for op-node: - - * The `op-node` behind the `op-conductor` must have the SafeDB enabled to ensure it is not stateless. - * To enable SafeDB, set the `--safedb.path` value in your configuration. This specifies the file path used to persist safe head update data. - * Example Configuration: - - ``` - --safedb.path # Replace with your actual path - ``` - - - If this path is not set, the SafeDB feature will be disabled. - - - 2. Ensuring Historical Data Availability: - - * Both `op-node` and `op-geth` must have data from the start of the games to maintain network consistency and allow nodes to reference historical state and transactions. - * For `op-node`: Configure it to maintain a sufficient history of blockchain data locally or use an archive node. - * For `op-geth`: Similarly, configure to store or access historical data. - * Example Configuration: - - ``` - op-node \ - --rollup-rpc \ - --safedb.path - ``` - - - Replace `` with the URL of your archive node and `` with the desired path for storing SafeDB data. - - - #### `--private-key` - - * Chain operators must specify a private key or use something else (like `op-signer`). - * This uses the same transaction manager arguments as `op-node` , batcher, and proposer, so chain operators can choose one of the following options: - * a mnemonic - * a private key - * `op-signer` endpoints - - #### `--network` - - * This identifies the L2 network `op-challenger` is running for, e.g., `op-sepolia` or `op-mainnet`. - * When using the `--network` flag, the `--game-factory-address` will be automatically pulled from the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json). - * When cannon is executed, challenger needs the roll-up config and the L2 Genesis, which is op-geth's Genesis file. Both files are automatically loaded when Cannon Network is used, but custom networks will need to specify both Cannon L2 Genesis and Cannon rollup config. - * For custom networks not in the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json), the `--game-factory-address` and rollup must be specified, as follows: - - ``` - --cannon-rollup-config rollup.json \ - --cannon-l2-genesis genesis-l2.json \ - # use this if running challenger outside of the docker image - --cannon-server ./op-program/bin/op-program \ - # json or url, version of op-program deployed on chain - # if you use the wrong one, you will lose the game - # if you deploy your own contracts, you specify the hash, the root of the json file - # op mainnet are tagged versions of op-program - # make reproducible prestate - # challenger verifies that onchain - --cannon-prestate ./op-program/bin/prestate.json \ - # load the game factory address from system config or superchain registry - # point the game factory address at the dispute game factory proxy - --game-factory-address - ``` - - - These options vary based on which `--network` is specified. Chain operators always need to specify a way to load prestates and must also specify the cannon-server whenever the docker image isn't being used. - - - #### `--datadir` - - * This is a directory that `op-challenger` can write to and store whatever data it needs. It will manage this directory to add or remove data as needed under that directory. - * If running in docker, it should point to a docker volume or mountpoint, so the data isn't lost on every restart. The data can be recreated if needed but particularly if challenger has executed cannon as part of responding to a game it may mean a lot of extra processing. - - #### `--cannon-prestates-url` - - The pre-state is effectively the version of `op-program` that is deployed on chain. And chain operators must use the right version. `op-challenger` will refuse to interact with games that have a different absolute prestate hash to avoid making invalid claims. If deploying your own contracts, chain operators must specify an absolute prestate hash taken from the `make reproducible-prestate` command during contract deployment, which will also build the required prestate json file. - - All governance approved releases use a tagged version of `op-program`. These can be rebuilt by checking out the version tag and running `make reproducible-prestate`. - - * There are two ways to specify the prestate to use: - * `--cannon-prestate`: specifies a path to a single Cannon pre-state Json file - * `--cannon-prestates-url`: specifies a URL to load pre-states from. This enables participating in games that use different prestates, for example due to a network upgrade. The prestates are stored in this directory named by their hash. - * Example final URL for a prestate: - * [https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json](https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json) - * This file contains the cannon memory state. - - - Challenger will refuse to interact with any games if it doesn't have the matching prestate. - - - ### Execute challenger - - The final step is to execute challenger with the required flags. It will look something like this (but with required flags added): - - ```bash - ./op-challenger/bin/op-challenger \ - --trace-type permissioned,cannon \ - --l1-eth-rpc http://localhost:8545 \ - --rollup-rpc http://localhost:9546 \ - --game-factory-address $DISPUTE_GAME_FACTORY \ - --datadir temp/challenger-data \ - --cannon-rollup-config .devnet/rollup.json \ - --cannon-l2-genesis .devnet/genesis-l2.json \ - --cannon-bin ./cannon/bin/cannon \ - --cannon-server ./op-program/bin/op-program \ - --cannon-prestate ./op-program/bin/prestate.json \ - --l2-eth-rpc http://localhost:9545 \ - --mnemonic "test test test test test test test test test test test junk" \ - --hd-path "m/44'/60'/0'/0/8" \ - ``` - - ### Test and debug challenger (optional) - - This is an optional step to use `op-challenger` subcommands, which allow chain operators to interact with the Fault Proof System onchain for testing and debugging purposes. For example, it is possible to test and explore the system in the following ways: - - * create games yourself, and it doesn't matter if the games are valid or invalid. - * perform moves in games and then claim and resolve things. - - Here's the list of op-challenger subcommands: - - | subcommand | description | - | --------------- | -------------------------------------------------------- | - | `list-games` | List the games created by a dispute game factory | - | `list-claims` | List the claims in a dispute game | - | `list-credits` | List the credits in a dispute game | - | `create-game` | Creates a dispute game via the factory | - | `move` | Creates and sends a move transaction to the dispute game | - | `resolve` | Resolves the specified dispute game if possible | - | `resolve-claim` | Resolves the specified claim if possible | - - Additionally, chain operators should consider running `op-dispute-mon`. It's an incredibly useful security monitoring service to keep an eye on games, basically giving chain operators visibility into all the status of the games for the last 28 days. - Chain operators can easily create their grafana dashboard for Dispute Monitor using the following json file: [Download the Dispute Monitor JSON](/resources/grafana/dispute-monitor-1718214549035.json). - - -## Next steps - -* Additional questions? See the FAQ section in the [OP Challenger Explainer](/stack/fault-proofs/challenger). -* For more detailed info on `op-challenger`, see the [specs](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html?utm_source=op-docs&utm_medium=docs). -* If you experience any problems, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions). diff --git a/pages/stack/fault-proofs/challenger.mdx b/pages/stack/fault-proofs/challenger.mdx index 06f6e7d1a..c9088135c 100644 --- a/pages/stack/fault-proofs/challenger.mdx +++ b/pages/stack/fault-proofs/challenger.mdx @@ -101,7 +101,7 @@ The `FaultDisputeGame` does not put a time cap on resolution - because of the li ## Next steps -* Ready to get started? Read our guide on how to [configure `op-challenger` on your OP Stack chain](/operators/chain-operators/tools/op-challenger). +* Ready to get started? Read our guide on how to [configure `op-challenger` on your OP Stack chain](/operators/chain-operators/deploy/op-challenger). * For more info about how `op-challenger` works under the hood, [check out the specs](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html?utm_source=op-docs&utm_medium=docs). ## FAQs diff --git a/public/_redirects b/public/_redirects index 826a3dd7d..252eb6d7b 100644 --- a/public/_redirects +++ b/public/_redirects @@ -81,6 +81,8 @@ /operators/node-operators/tutorials/testnet /operators/node-operators/tutorials/run-node-from-source /stack/dev-net /chain-operators/tutorials/chain-dev-net +/operators/chain-operators/tools/op-challenger /operators/chain-operators/deploy/op-challenger + # ---------------------------------------------------------------------------- # Stack Documentation Migration # ---------------------------------------------------------------------------- diff --git a/words.txt b/words.txt index 1e334fde3..91f33e2af 100644 --- a/words.txt +++ b/words.txt @@ -1,7 +1,7 @@ -accountqueue ACCOUNTQUEUE -accountslots +accountqueue ACCOUNTSLOTS +accountslots ACDC ADDI ADDIU @@ -9,58 +9,58 @@ ADDU airgap Allnodes allocs -alphanet Alphanet -alphanets +alphanet Alphanets +alphanets altda ANDI Ankr Apeworx Arweave authrpc -autorelay Autorelay +autorelay autorelayer basefee bcde -betanet Betanet -betanets +betanet Betanets +betanets BGEZ BGTZ Biconomy BLEZ -blobpool BLOBPOOL +blobpool blobspace Blockdaemon blockhash blocklists -blocklogs BLOCKLOGS -blockprofilerate +blocklogs BLOCKPROFILERATE +blockprofilerate Blockscout -blockspace Blockspace +blockspace blocktime -blocktimes Blocktimes -bloomfilter +blocktimes BLOOMFILTER +bloomfilter BLTZ Bootcamp bootnode -bootnodes -Bootnodes BOOTNODES +Bootnodes +bootnodes bottlenecked -brotli Brotli -callouts +brotli Callouts +callouts CCIP cdef Celestia @@ -73,66 +73,66 @@ chaosnet Chugsplash Clabby codebases -collateralized Collateralized +collateralized compr Comprensive -computependingblock COMPUTEPENDINGBLOCK +computependingblock confs corsdomain counterfactually -crosschain Crosschain +crosschain Crossmint daserver -datacap DATACAP -datadir +datacap DATADIR +datadir Defi Defillama's delegatecall -devnet Devnet -devnets +devnet Devnets +devnets devs direnv -disabletxpoolgossip DISABLETXPOOLGOSSIP -discv +disabletxpoolgossip Discv +discv DIVU Drand dripcheck Drippie Eigen EIPs -enabledeprecatedpersonal ENABLEDEPRECATEDPERSONAL +enabledeprecatedpersonal enginekind -erigon Erigon -etherbase +erigon ETHERBASE +etherbase Ethernity Ethernow -ethstats ETHSTATS -evmtimeout +ethstats EVMTIMEOUT +evmtimeout executability exfiltrate -exitwhensynced EXITWHENSYNCED +exitwhensynced extensibly -extradata EXTRADATA +extradata Farcaster Faultproof -fdlimit FDLIMIT +fdlimit Flashblocks Flashbots forkable @@ -141,51 +141,51 @@ FPVM FPVMs Fraxtal Funct -gascap GASCAP +gascap gaslessly -gcmode GCMODE +gcmode Gelato gifs -globalqueue GLOBALQUEUE -globalslots +globalqueue GLOBALSLOTS +globalslots gokzg growthepie hardfork hardforks -healthcheck HEALTHCHECK +healthcheck healthchecks -historicalrpc HISTORICALRPC -historicalrpctimeout +historicalrpc HISTORICALRPCTIMEOUT -holesky -Holesky +historicalrpctimeout HOLESKY +Holesky +holesky IERC -ignoreprice IGNOREPRICE +ignoreprice Immunefi -inator Inator -influxdbv +inator INFLUXDBV +influxdbv initcode -ipcdisable IPCDISABLE +ipcdisable ipcfile -ipcpath IPCPATH +ipcpath IPFS JALR -journalremotes JOURNALREMOTES -jspath +journalremotes JSPATH +jspath jwtsecret Keccak leveldb @@ -194,182 +194,181 @@ Lisk logfile logfmt Mainnets -maxage MAXAGE -maxbackups +maxage MAXBACKUPS -maxpeers +maxbackups MAXPEERS -maxpendpeers +maxpeers MAXPENDPEERS -maxprice +maxpendpeers MAXPRICE -memprofilerate +maxprice MEMPROFILERATE -merkle +memprofilerate Merkle +merkle MFHI MFLO Mgas Minato -minfreedisk MINFREEDISK -minsuggestedpriorityfee +minfreedisk MINSUGGESTEDPRIORITYFEE +minsuggestedpriorityfee Mintable Mintplex MIPSEVM Mitigations -monitorism Monitorism +monitorism Moralis Mordor -mountpoint MOVN MOVZ MTHI MTLO MULT multiaddr -multichain Multichain +multichain multiclient multisigs MULTU nethermind -netrestrict NETRESTRICT -networkid +netrestrict NETWORKID -newpayload +networkid NEWPAYLOAD +newpayload nextra -nocompaction NOCOMPACTION -nodekey +nocompaction NODEKEY -nodekeyhex +nodekey NODEKEYHEX +nodekeyhex nodename Nodies -nodiscover NODISCOVER -nolocals +nodiscover NOLOCALS -noprefetch +nolocals NOPREFETCH -nopruning +noprefetch NOPRUNING -nosyncserve +nopruning NOSYNCSERVE +nosyncserve Numba NVME -offchain Offchain +offchain onlyreqtostatic opchaina opchainb -opcm OPCM +opcm Openfort oplabs opnode's outfile outperformance pcscdpath -pectra Pectra +pectra Pectra's -peerstore Peerstore +peerstore peerstores -permissioned Permissioned +permissioned permissioning -permissionless Permissionless +permissionless permissionlessly Perps Peta Pimlico POAP POAPs -pprof PPROF -precommitments +pprof Precommitments +precommitments preconfigured predeploy -predeployed Predeployed -predeploys +predeployed Predeploys +predeploys prefunded -preimage Preimage -preimages +preimage PREIMAGES +preimages preinstall -preinstalls Preinstalls -prestate +preinstalls Prestate +prestate prestates PREVRANDAO -pricebump PRICEBUMP -pricelimit +pricebump PRICELIMIT +pricelimit productionize productionized Protip Proxied -proxyd Proxyd +proxyd Pyth Pyth's QRNG -quicknode Quicknode +quicknode quickstarts rebalancing reemit Reemitting -regenesis Regenesis +regenesis Reimagine -rejournal REJOURNAL -remotedb +rejournal REMOTEDB +remotedb Reown Reown's replayability replayor reposts reproven -requiredblocks REQUIREDBLOCKS +requiredblocks rollouts -rollups Rollups +rollups Routescan rpckind -rpcprefix RPCPREFIX +rpcprefix rpcs RPGF -runbooks Runbooks +runbooks RWAs safedb Schnorr -sepolia -Sepolia SEPOLIA +Sepolia +sepolia seqnr -sequencerhttp SEQUENCERHTTP +sequencerhttp serv signup SLLV @@ -378,16 +377,16 @@ SLTIU SLTU smartcard snapshotlog -snapsync Snapsync +snapsync Solana Soneium soyboy Spearbit SRAV SRLV -stablecoins Stablecoins +stablecoins statefulset structs subcomponents @@ -396,21 +395,21 @@ subheaders subsecond SUBU Sunnyside -superchain -Superchain SUPERCHAIN +Superchain +superchain Superchain's superchainerc Superlend Superloans Superscan Superseed -supersim Supersim -syncmode +supersim SYNCMODE -synctarget +syncmode SYNCTARGET +synctarget syscalls SYSCON thirdweb @@ -424,8 +423,8 @@ Twei txfeecap txmgr txns -txpool TXPOOL +txpool txproxy txproxyd uncensorable @@ -436,21 +435,21 @@ Unprotect unsubmitted UPNP upstreaming -verkle VERKLE -vhosts +verkle VHOSTS -viem +vhosts Viem -viem's +viem Viem's -vmdebug +viem's VMDEBUG -vmodule +vmdebug VMODULE +vmodule xlarge XORI ZKPs ZKVM -zora Zora +zora From c154b56e116499353d8971d8f296e0eec74a9b13 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Wed, 23 Jul 2025 16:03:38 +0100 Subject: [PATCH 02/12] Remove optional testing and debugging section from op-challenger documentation to streamline content and focus on essential information. --- .../chain-operators/deploy/op-challenger.mdx | 31 ------------------- 1 file changed, 31 deletions(-) diff --git a/pages/operators/chain-operators/deploy/op-challenger.mdx b/pages/operators/chain-operators/deploy/op-challenger.mdx index fba206714..938ea0d6a 100644 --- a/pages/operators/chain-operators/deploy/op-challenger.mdx +++ b/pages/operators/chain-operators/deploy/op-challenger.mdx @@ -353,37 +353,6 @@ docker-compose up -d # View logs docker-compose logs -f challenger ``` - -## Testing and debugging (Optional) - -Use `op-challenger` subcommands to interact with the Fault Proof System for testing and debugging purposes: - -### Available subcommands - -| Subcommand | Description | -| --------------- | -------------------------------------------------------- | -| `list-games` | List the games created by a dispute game factory | -| `list-claims` | List the claims in a dispute game | -| `list-credits` | List the credits in a dispute game | -| `create-game` | Creates a dispute game via the factory | -| `move` | Creates and sends a move transaction to the dispute game | -| `resolve` | Resolves the specified dispute game if possible | -| `resolve-claim` | Resolves the specified claim if possible | - -### Example testing commands - -```bash -# List recent games -./op-challenger/bin/op-challenger list-games \ - --l1-eth-rpc=$L1_RPC_URL \ - --game-factory-address=$GAME_FACTORY_ADDRESS - -# List claims in a specific game -./op-challenger/bin/op-challenger list-claims \ - --l1-eth-rpc=$L1_RPC_URL \ - --game-address=0xGAME_ADDRESS -``` - ### Monitoring with op-dispute-mon Consider running `op-dispute-mon` for enhanced security monitoring: From 83a090421fc5b55ac84e5c5e6a1e7af9059a0cd5 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Wed, 23 Jul 2025 16:31:21 +0100 Subject: [PATCH 03/12] Update op-challenger description in metadata to provide clearer context for deployment --- pages/operators/chain-operators/deploy/_meta.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/operators/chain-operators/deploy/_meta.json b/pages/operators/chain-operators/deploy/_meta.json index d277bc0e9..61f001ab4 100644 --- a/pages/operators/chain-operators/deploy/_meta.json +++ b/pages/operators/chain-operators/deploy/_meta.json @@ -6,6 +6,6 @@ "sequencer-node": "Spinning up the sequencer", "proposer-setup-guide": "Spinning up the proposer", "spin-batcher": "Spinning up the batcher", - "op-challenger": "op-challenger" + "op-challenger": "Spinning up the op-challenger" } From 87e30fce4cceebb398e3df069701eb62e7120a70 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Tue, 29 Jul 2025 10:54:01 +0100 Subject: [PATCH 04/12] Clarify important considerations in op-challenger documentation regarding beacon node and blob archiver requirements. --- pages/operators/chain-operators/deploy/op-challenger.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/operators/chain-operators/deploy/op-challenger.mdx b/pages/operators/chain-operators/deploy/op-challenger.mdx index 938ea0d6a..d45cf24a8 100644 --- a/pages/operators/chain-operators/deploy/op-challenger.mdx +++ b/pages/operators/chain-operators/deploy/op-challenger.mdx @@ -197,8 +197,8 @@ EOF * Needed for blob access from L1 consensus layer * **Important considerations:** - * If your chain posts regularly: standard beacon node is sufficient - * If your chain doesn't post valid output roots within 18 days: blob archiver is required + * If your chain posts regularly, standard beacon node is sufficient + * If your chain doesn't post valid output roots within 18 days, blob archiver is required * Configure consensus node to not prune blobs if needed #### `--l2-eth-rpc` From 1aad17d61f85cc505f73789f224fc096babceafb Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Tue, 29 Jul 2025 15:51:13 +0100 Subject: [PATCH 05/12] Enhance op-challenger documentation with detailed configuration options and wallet setup --- .../chain-operators/deploy/op-challenger.mdx | 159 ++++++++++++------ 1 file changed, 109 insertions(+), 50 deletions(-) diff --git a/pages/operators/chain-operators/deploy/op-challenger.mdx b/pages/operators/chain-operators/deploy/op-challenger.mdx index d45cf24a8..a9e184811 100644 --- a/pages/operators/chain-operators/deploy/op-challenger.mdx +++ b/pages/operators/chain-operators/deploy/op-challenger.mdx @@ -15,9 +15,9 @@ categories: is_imported_content: 'false' --- -# How to configure challenger for your chain +import { Callout, Steps } from 'nextra/components' -## Overview +# How to configure challenger for your chain This guide provides step-by-step instructions for setting up the configuration and monitoring options for `op-challenger`. The challenger is a critical fault proofs component that monitors dispute games and challenges invalid claims to protect your OP Stack chain. @@ -158,19 +158,22 @@ Create your `.env` file with the actual values: cat > .env << 'EOF' # L1 Configuration - Replace with your actual RPC URLs L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY -L1_BEACON_URL=https://ethereum-sepolia-beacon-api.publicnode.com # L2 Configuration - Replace with your actual node endpoints L2_RPC_URL=http://your-op-geth-archive:8545 ROLLUP_RPC_URL=http://your-op-node:8547 -# Challenger wallet - Replace with your actual private key -PRIVATE_KEY=0xYOUR_ACTUAL_PRIVATE_KEY +# Wallet configuration (alternative to private key) +MNEMONIC="test test test test test test test test test test test junk" +HD_PATH="m/44'/60'/0'/0/8" # Network configuration NETWORK=op-sepolia GAME_FACTORY_ADDRESS=0xYOUR_GAME_FACTORY_ADDRESS +# Trace configuration +TRACE_TYPE=permissioned,cannon + # Data directory DATADIR=./challenger-data @@ -178,6 +181,8 @@ DATADIR=./challenger-data CANNON_PRESTATES_URL=https://example.com/prestates CANNON_ROLLUP_CONFIG=./rollup.json CANNON_L2_GENESIS=./genesis-l2.json +CANNON_BIN=./cannon/bin/cannon +CANNON_SERVER=./op-program/bin/op-program EOF ``` @@ -189,45 +194,115 @@ EOF #### `--l1-eth-rpc` -* HTTP provider URL for a standard L1 node, can be a full node -* `op-challenger` will be sending many requests, so use a trusted node that can handle many transactions -* **Critical:** Challenger controls significant funds and will spend if needed to defend games +* This is the HTTP provider URL for a standard L1 node, can be a full node. `op-challenger` will be sending many requests, so chain operators need a node that is trusted and can easily handle many transactions. +* Note: Challenger has a lot of money, and it will spend it if it needs to interact with games. That might risk not defending games or challenging games correctly, so chain operators should really trust the nodes being pointed at Challenger. #### `--l1-beacon` -* Needed for blob access from L1 consensus layer -* **Important considerations:** - * If your chain posts regularly, standard beacon node is sufficient - * If your chain doesn't post valid output roots within 18 days, blob archiver is required - * Configure consensus node to not prune blobs if needed +* This is needed just to get blobs from. +* In some instances, chain operators might need a blob archiver or L1 consensus node configured not to prune blobs: + * If the chain is proposing regularly, a blob archiver isn't needed. There's only a small window in the blob retention period that games can be played. + * If the chain doesn't post a valid output root in 18 days, then a blob archiver running a challenge game is needed. If the actor gets pushed to the bottom of the game, it could lose if it's the only one protecting the chain. #### `--l2-eth-rpc` -* Must be an `op-geth` archive node with `debug` API enabled -* Doesn't need full bedrock history but needs access to data from any active game start +* This needs to be `op-geth` archive node, with `debug` enabled. +* Technically doesn't need to go to bedrock, but needs to have access to the start of any game that is still in progress. #### `--rollup-rpc` -* Must be an `op-node` archive node with historical output roots -* **SafeDB Configuration:** The `op-node` must have SafeDB enabled: - * Set `--safedb.path` to persist safe head update data - * Example: `--safedb.path /path/to/safe-head-db` - * If path not set, SafeDB will be disabled +* This needs to be an `op-node` archive node because challenger needs access to output roots from back when the games start. See below for important configuration details: + +1. Safe Head Database (SafeDB) Configuration for op-node: + + * The `op-node` behind the `op-conductor` must have the SafeDB enabled to ensure it is not stateless. + + * To enable SafeDB, set the `--safedb.path` value in your configuration. This specifies the file path used to persist safe head update data. + + * Example Configuration: + + ``` + --safedb.path # Replace with your actual path + ``` + + + If this path is not set, the SafeDB feature will be disabled. + + + 2. Ensuring Historical Data Availability: + + * Both `op-node` and `op-geth` must have data from the start of the games to maintain network consistency and allow nodes to reference historical state and transactions. + * For `op-node`: Configure it to maintain a sufficient history of blockchain data locally or use an archive node. + * For `op-geth`: Similarly, configure to store or access historical data. + * Example Configuration: + + ``` + op-node \ + --rollup-rpc \ + --safedb.path + ``` + + + Replace `` with the URL of your archive node and `` with the desired path for storing SafeDB data. + + +#### `--private-key` + +* Chain operators must specify a private key or use something else (like `op-signer`). +* This uses the same transaction manager arguments as `op-node` , batcher, and proposer, so chain operators can choose one of the following options: + * a mnemonic + * a private key + * `op-signer` endpoints #### `--network` -* Identifies the L2 network (e.g., `op-sepolia`, `op-mainnet`) -* When using `--network` flag, `--game-factory-address` is auto-loaded from [superchain-registry](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json) -* For custom networks, you must specify `--game-factory-address` and related configs manually +* This identifies the L2 network `op-challenger` is running for, e.g., `op-sepolia` or `op-mainnet`. +* When using the `--network` flag, the `--game-factory-address` will be automatically pulled from the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json). +* When cannon is executed, challenger needs the roll-up config and the L2 Genesis, which is op-geth's Genesis file. Both files are automatically loaded when Cannon Network is used, but custom networks will need to specify both Cannon L2 Genesis and Cannon rollup config. +* For custom networks not in the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json), the `--game-factory-address` and rollup must be specified, as follows: + + ``` + --cannon-rollup-config rollup.json \ + --cannon-l2-genesis genesis-l2.json \ + # use this if running challenger outside of the docker image + --cannon-server ./op-program/bin/op-program \ + # json or url, version of op-program deployed on chain + # if you use the wrong one, you will lose the game + # if you deploy your own contracts, you specify the hash, the root of the json file + # op mainnet are tagged versions of op-program + # make reproducible prestate + # challenger verifies that onchain + --cannon-prestate ./op-program/bin/prestate.json \ + # load the game factory address from system config or superchain registry + # point the game factory address at the dispute game factory proxy + --game-factory-address + ``` + + + These options vary based on which `--network` is specified. Chain operators always need to specify a way to load prestates and must also specify the cannon-server whenever the docker image isn't being used. + + +#### `--datadir` + +* This is a directory that `op-challenger` can write to and store whatever data it needs. It will manage this directory to add or remove data as needed under that directory. +* If running in docker, it should point to a docker volume or mount point, so the data isn't lost on every restart. The data can be recreated if needed but particularly if challenger has executed cannon as part of responding to a game it may mean a lot of extra processing. #### `--cannon-prestates-url` -* The prestate is the version of `op-program` deployed on chain -* **Critical:** Must use the correct version to avoid invalid claims -* Challenger will refuse to interact with games that have different prestate hash -* Two options: - * `--cannon-prestate`: path to single prestate JSON file - * `--cannon-prestates-url`: URL to load multiple prestates (recommended) +The pre-state is effectively the version of `op-program` that is deployed on chain. And chain operators must use the right version. `op-challenger` will refuse to interact with games that have a different absolute prestate hash to avoid making invalid claims. If deploying your own contracts, chain operators must specify an absolute prestate hash taken from the `make reproducible-prestate` command during contract deployment, which will also build the required prestate json file. + +All governance approved releases use a tagged version of `op-program`. These can be rebuilt by checking out the version tag and running `make reproducible-prestate`. + +* There are two ways to specify the prestate to use: + * `--cannon-prestate`: specifies a path to a single Cannon pre-state Json file + * `--cannon-prestates-url`: specifies a URL to load pre-states from. This enables participating in games that use different prestates, for example due to a network upgrade. The prestates are stored in this directory named by their hash. +* Example final URL for a prestate: + * [https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json](https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json) + * This file contains the cannon memory state. + + + Challenger will refuse to interact with any games if it doesn't have the matching prestate. + ### Create challenger startup script @@ -239,37 +314,20 @@ source .env # Path to the challenger binary ../optimism/op-challenger/bin/op-challenger \ + --trace-type $TRACE_TYPE \ --l1-eth-rpc=$L1_RPC_URL \ - --l1-beacon=$L1_BEACON_URL \ --l2-eth-rpc=$L2_RPC_URL \ --rollup-rpc=$ROLLUP_RPC_URL \ - --selective-claim-resolution \ --private-key=$PRIVATE_KEY \ --network=$NETWORK \ --datadir=$DATADIR \ --cannon-prestates-url=$CANNON_PRESTATES_URL \ --cannon-rollup-config=$CANNON_ROLLUP_CONFIG \ --cannon-l2-genesis=$CANNON_L2_GENESIS \ - --trace-type=permissioned,cannon \ - --log.level=info \ - --log.format=json -``` - -### Custom network configuration - -For custom networks not in the superchain-registry, additional flags are required: - -```bash -# Additional flags for custom networks ---cannon-rollup-config rollup.json \ ---cannon-l2-genesis genesis-l2.json \ ---cannon-server ./op-program/bin/op-program \ ---cannon-prestate ./op-program/bin/prestate.json \ ---game-factory-address=0xYOUR_GAME_FACTORY_ADDRESS + --mnemonic=$MNEMONIC \ + --hd-path=$HD_PATH ``` -**Warning:** These options vary based on which `--network` is specified. Chain operators always need to specify a way to load prestates and must also specify the cannon-server when not using Docker images. - ## Initializing and starting the challenger ### Start the challenger @@ -353,9 +411,10 @@ docker-compose up -d # View logs docker-compose logs -f challenger ``` + ### Monitoring with op-dispute-mon -Consider running `op-dispute-mon` for enhanced security monitoring: +Consider running [`op-dispute-mon`](/operators/chain-operators/tools/chain-monitoring#dispute-mon) for enhanced security monitoring: * Provides visibility into all game statuses for the last 28 days * Essential for production challenger deployments From a88d1897bbcdc1f76594b7263bc5ea52f6580bd0 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Tue, 29 Jul 2025 15:54:58 +0100 Subject: [PATCH 06/12] remove handcode text --- pages/operators/chain-operators/deploy/op-challenger.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/pages/operators/chain-operators/deploy/op-challenger.mdx b/pages/operators/chain-operators/deploy/op-challenger.mdx index a9e184811..f6437d565 100644 --- a/pages/operators/chain-operators/deploy/op-challenger.mdx +++ b/pages/operators/chain-operators/deploy/op-challenger.mdx @@ -88,7 +88,6 @@ cd optimism git checkout op-challenger/v0.2.11 # Install dependencies and build -pnpm install make op-challenger # Binary will be available at ./op-challenger/bin/op-challenger From 215a7c84b6663829e68ee2123bb79ab323f2aba3 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Tue, 29 Jul 2025 17:01:17 +0100 Subject: [PATCH 07/12] Update op-challenger documentation to improve clarity on directory structure --- .../chain-operators/deploy/op-challenger.mdx | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/pages/operators/chain-operators/deploy/op-challenger.mdx b/pages/operators/chain-operators/deploy/op-challenger.mdx index f6437d565..ab3163c74 100644 --- a/pages/operators/chain-operators/deploy/op-challenger.mdx +++ b/pages/operators/chain-operators/deploy/op-challenger.mdx @@ -100,6 +100,8 @@ Check that you have properly installed the challenger component: ```bash # Make sure you're in the optimism directory ./op-challenger/bin/op-challenger --help + +# You should see the challenger help output with available commands and flags ``` ## Configuration setup @@ -109,13 +111,19 @@ Check that you have properly installed the challenger component: After building the binaries, create your challenger working directory: ```bash -# Create challenger directory -mkdir ~/challenger-node -cd ~/challenger-node +# Create challenger directory (this should be at the same level as optimism directory) +mkdir /challenger-node +cd /challenger-node # Create necessary subdirectories mkdir scripts mkdir challenger-data + +# Verify the optimism directory is accessible +# Directory structure should look like: +# /optimism/ (contains the built binaries) +# /challenger-node/ (your working directory) +ls -la ../optimism/op-challenger/bin/op-challenger ``` ### 2. Copy configuration files From 3dd7d6252be695e9a3b8982d1c1330d950fe7a24 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Tue, 29 Jul 2025 17:02:08 +0100 Subject: [PATCH 08/12] Refine op-challenger documentation with updated directory commands and configuration instructions --- .../chain-operators/deploy/op-challenger.mdx | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/pages/operators/chain-operators/deploy/op-challenger.mdx b/pages/operators/chain-operators/deploy/op-challenger.mdx index ab3163c74..bbd3b3be8 100644 --- a/pages/operators/chain-operators/deploy/op-challenger.mdx +++ b/pages/operators/chain-operators/deploy/op-challenger.mdx @@ -112,8 +112,8 @@ After building the binaries, create your challenger working directory: ```bash # Create challenger directory (this should be at the same level as optimism directory) -mkdir /challenger-node -cd /challenger-node +mkdir challenger-node +cd challenger-node # Create necessary subdirectories mkdir scripts @@ -123,7 +123,6 @@ mkdir challenger-data # Directory structure should look like: # /optimism/ (contains the built binaries) # /challenger-node/ (your working directory) -ls -la ../optimism/op-challenger/bin/op-challenger ``` ### 2. Copy configuration files @@ -158,7 +157,7 @@ You'll need to gather several pieces of information before creating your configu * Game factory address from your contract deployment * Network identifier (e.g., op-sepolia, op-mainnet, or custom) -Create your `.env` file with the actual values: +Copy and paste in your terminal, to create your env file. ```bash # Create .env file with your actual values @@ -167,12 +166,11 @@ cat > .env << 'EOF' L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY # L2 Configuration - Replace with your actual node endpoints -L2_RPC_URL=http://your-op-geth-archive:8545 -ROLLUP_RPC_URL=http://your-op-node:8547 +L2_RPC_URL=http://localhost:8545 +ROLLUP_RPC_URL=http://localhost:8547 +L1_BEACON=http://sepolia-cl-1:5051 -# Wallet configuration (alternative to private key) -MNEMONIC="test test test test test test test test test test test junk" -HD_PATH="m/44'/60'/0'/0/8" +PRIVATE_KEY=0xYOUR_ACTUAL_PRIVATE_KEY # Network configuration NETWORK=op-sepolia @@ -321,18 +319,19 @@ source .env # Path to the challenger binary ../optimism/op-challenger/bin/op-challenger \ - --trace-type $TRACE_TYPE \ + --trace-type permissioned,cannon \ --l1-eth-rpc=$L1_RPC_URL \ --l2-eth-rpc=$L2_RPC_URL \ + --l1-beacon=$L1_BEACON \ --rollup-rpc=$ROLLUP_RPC_URL \ - --private-key=$PRIVATE_KEY \ - --network=$NETWORK \ + --game-factory-address $GAME_FACTORY_ADDRESS \ --datadir=$DATADIR \ + --cannon-bin=$CANNON_BIN \ --cannon-prestates-url=$CANNON_PRESTATES_URL \ --cannon-rollup-config=$CANNON_ROLLUP_CONFIG \ --cannon-l2-genesis=$CANNON_L2_GENESIS \ - --mnemonic=$MNEMONIC \ - --hd-path=$HD_PATH + --cannon-server=$CANNON_SERVER \ + --private-key=$PRIVATE_KEY ``` ## Initializing and starting the challenger @@ -341,7 +340,7 @@ source .env ```bash # Make sure you're in the challenger-node directory -cd ~/challenger-node +cd challenger-node # Make script executable chmod +x scripts/start-challenger.sh From 0a4b8c0760598ba5d10ebc222016bfae47e65c3f Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Mon, 18 Aug 2025 17:07:28 +0100 Subject: [PATCH 09/12] Enhance op-challenger documentation with structured steps for configuration and deployment, including updated commands, wallet setup, and Docker instructions. --- .../chain-operators/deploy/op-challenger.mdx | 299 +++++++++++++++--- 1 file changed, 250 insertions(+), 49 deletions(-) diff --git a/pages/operators/chain-operators/deploy/op-challenger.mdx b/pages/operators/chain-operators/deploy/op-challenger.mdx index bbd3b3be8..9c153f45c 100644 --- a/pages/operators/chain-operators/deploy/op-challenger.mdx +++ b/pages/operators/chain-operators/deploy/op-challenger.mdx @@ -15,7 +15,7 @@ categories: is_imported_content: 'false' --- -import { Callout, Steps } from 'nextra/components' +import { Callout, Steps, Tabs, Tab } from 'nextra/components' # How to configure challenger for your chain @@ -36,21 +36,26 @@ The challenger is responsible for: Before configuring your challenger, complete the following steps: -1. **Deployed OP Stack chain with fault proofs enabled:** - * L1 contracts deployed with dispute game factory - * Fault proof system active on your chain - * Access to your chain's contract addresses + -2. **Required infrastructure access:** - * L1 RPC endpoint (Ethereum, Sepolia, etc.) - * L1 Beacon node endpoint (for blob access) - * L2 archive node with debug API enabled - * Rollup node (op-node) with historical data +### Deploy OP Stack chain with fault proofs enabled +* L1 contracts deployed with dispute game factory +* Fault proof system active on your chain +* Access to your chain's contract addresses +* [Generate an absolute prestate](/operators/chain-operators/tutorials/absolute-prestate#generating-the-absolute-prestate) for your network version - This is critical as the challenger will refuse to interact with games if it doesn't have the matching prestate -3. **Configuration files:** - * `rollup.json` - Rollup configuration file - * `genesis-l2.json` - L2 genesis file - * Prestate files for your network version +### Set up required infrastructure access +* L1 RPC endpoint (Ethereum, Sepolia, etc.) +* L1 Beacon node endpoint (for blob access) +* L2 archive node with debug API enabled +* Rollup node (op-node) with historical data + +### Prepare configuration files +* `rollup.json` - Rollup configuration file +* `genesis-l2.json` - L2 genesis file +* `prestate.json` - The absolute prestate file generated in step 1 + + ### Software requirements @@ -65,19 +70,21 @@ To ensure you're using the latest compatible versions of OP Stack components, al [OP Stack releases page](https://github.com/ethereum-optimism/optimism/releases) -Look for the latest `op-challenger/v*` release. The challenger version used in this guide (op-challenger/v0.2.11) is a verified stable version. +Look for the latest `op-challenger/v*` release. The challenger version used in this guide (op-challenger/v1.5.0) is a verified stable version. Always check the release notes to ensure you're using compatible versions with your chain's deployment. ## Software installation -For challenger deployment, we recommend building from source as it provides better control and helps with debugging. A Docker alternative is also provided. +For challenger deployment, you can either build from source (recommended for better control and debugging) or use Docker for a containerized setup. -### Build from source (Recommended) + + +### Build and Configure Building from source gives you full control over the binaries and is the preferred approach for production deployments. -1. **Clone and build op-challenger** +**Clone and build op-challenger** ```bash # Clone the optimism monorepo @@ -85,10 +92,10 @@ git clone https://github.com/ethereum-optimism/optimism.git cd optimism # Check out the latest release of op-challenger -git checkout op-challenger/v0.2.11 +git checkout op-challenger/v1.5.0 # Install dependencies and build -make op-challenger +just op-challenger # Binary will be available at ./op-challenger/bin/op-challenger ``` @@ -106,7 +113,9 @@ Check that you have properly installed the challenger component: ## Configuration setup -### 1. Organize your workspace + + +### Organize your workspace After building the binaries, create your challenger working directory: @@ -125,7 +134,7 @@ mkdir challenger-data # /challenger-node/ (your working directory) ``` -### 2. Copy configuration files +### Copy configuration files ```bash # Copy configuration files to your challenger directory @@ -134,7 +143,7 @@ cp /path/to/your/rollup.json . cp /path/to/your/genesis-l2.json . ``` -### 3. Environment variables +### Set up environment variables You'll need to gather several pieces of information before creating your configuration. Here's where to get each value: @@ -170,7 +179,10 @@ L2_RPC_URL=http://localhost:8545 ROLLUP_RPC_URL=http://localhost:8547 L1_BEACON=http://sepolia-cl-1:5051 -PRIVATE_KEY=0xYOUR_ACTUAL_PRIVATE_KEY +# Wallet configuration - Choose either mnemonic + HD path OR private key +MNEMONIC="test test test test test test test test test test test junk" +HD_PATH="m/44'/60'/0'/0/0" +# PRIVATE_KEY=0xYOUR_ACTUAL_PRIVATE_KEY # Alternative to mnemonic # Network configuration NETWORK=op-sepolia @@ -183,38 +195,44 @@ TRACE_TYPE=permissioned,cannon DATADIR=./challenger-data # Cannon configuration -CANNON_PRESTATES_URL=https://example.com/prestates +CANNON_BIN=./cannon/bin/cannon CANNON_ROLLUP_CONFIG=./rollup.json CANNON_L2_GENESIS=./genesis-l2.json -CANNON_BIN=./cannon/bin/cannon CANNON_SERVER=./op-program/bin/op-program +CANNON_PRESTATE=./prestate-proof.json EOF ``` **Important:** Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values. -## Challenger configuration ### Understanding key configuration flags -#### `--l1-eth-rpc` +
+--l1-eth-rpc * This is the HTTP provider URL for a standard L1 node, can be a full node. `op-challenger` will be sending many requests, so chain operators need a node that is trusted and can easily handle many transactions. * Note: Challenger has a lot of money, and it will spend it if it needs to interact with games. That might risk not defending games or challenging games correctly, so chain operators should really trust the nodes being pointed at Challenger. +
-#### `--l1-beacon` +
+--l1-beacon * This is needed just to get blobs from. * In some instances, chain operators might need a blob archiver or L1 consensus node configured not to prune blobs: * If the chain is proposing regularly, a blob archiver isn't needed. There's only a small window in the blob retention period that games can be played. * If the chain doesn't post a valid output root in 18 days, then a blob archiver running a challenge game is needed. If the actor gets pushed to the bottom of the game, it could lose if it's the only one protecting the chain. +
-#### `--l2-eth-rpc` +
+--l2-eth-rpc * This needs to be `op-geth` archive node, with `debug` enabled. * Technically doesn't need to go to bedrock, but needs to have access to the start of any game that is still in progress. +
-#### `--rollup-rpc` +
+--rollup-rpc * This needs to be an `op-node` archive node because challenger needs access to output roots from back when the games start. See below for important configuration details: @@ -234,7 +252,7 @@ EOF If this path is not set, the SafeDB feature will be disabled. - 2. Ensuring Historical Data Availability: +2. Ensuring Historical Data Availability: * Both `op-node` and `op-geth` must have data from the start of the games to maintain network consistency and allow nodes to reference historical state and transactions. * For `op-node`: Configure it to maintain a sufficient history of blockchain data locally or use an archive node. @@ -250,16 +268,20 @@ EOF Replace `` with the URL of your archive node and `` with the desired path for storing SafeDB data. +
-#### `--private-key` +
+--private-key * Chain operators must specify a private key or use something else (like `op-signer`). * This uses the same transaction manager arguments as `op-node` , batcher, and proposer, so chain operators can choose one of the following options: * a mnemonic * a private key * `op-signer` endpoints +
-#### `--network` +
+--network * This identifies the L2 network `op-challenger` is running for, e.g., `op-sepolia` or `op-mainnet`. * When using the `--network` flag, the `--game-factory-address` will be automatically pulled from the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json). @@ -286,13 +308,17 @@ EOF These options vary based on which `--network` is specified. Chain operators always need to specify a way to load prestates and must also specify the cannon-server whenever the docker image isn't being used. +
-#### `--datadir` +
+--datadir * This is a directory that `op-challenger` can write to and store whatever data it needs. It will manage this directory to add or remove data as needed under that directory. * If running in docker, it should point to a docker volume or mount point, so the data isn't lost on every restart. The data can be recreated if needed but particularly if challenger has executed cannon as part of responding to a game it may mean a lot of extra processing. +
-#### `--cannon-prestates-url` +
+--cannon-prestates-url The pre-state is effectively the version of `op-program` that is deployed on chain. And chain operators must use the right version. `op-challenger` will refuse to interact with games that have a different absolute prestate hash to avoid making invalid claims. If deploying your own contracts, chain operators must specify an absolute prestate hash taken from the `make reproducible-prestate` command during contract deployment, which will also build the required prestate json file. @@ -307,7 +333,11 @@ All governance approved releases use a tagged version of `op-program`. These can Challenger will refuse to interact with any games if it doesn't have the matching prestate. + Check this [guide](/operators/chain-operators/tutorials/absolute-prestate#generating-the-absolute-prestate) on how to generate a absolute prestate. +
+ + ### Create challenger startup script @@ -327,11 +357,12 @@ source .env --game-factory-address $GAME_FACTORY_ADDRESS \ --datadir=$DATADIR \ --cannon-bin=$CANNON_BIN \ - --cannon-prestates-url=$CANNON_PRESTATES_URL \ --cannon-rollup-config=$CANNON_ROLLUP_CONFIG \ --cannon-l2-genesis=$CANNON_L2_GENESIS \ --cannon-server=$CANNON_SERVER \ - --private-key=$PRIVATE_KEY + --cannon-prestate=$CANNON_PRESTATE \ + --mnemonic "$MNEMONIC" \ + --hd-path "$HD_PATH" ``` ## Initializing and starting the challenger @@ -366,20 +397,180 @@ The challenger should show logs indicating: * Loading of prestates and configuration * Monitoring of dispute games -## Docker alternative + + +### Docker Setup + +The Docker setup provides a containerized environment for running the challenger. This method uses the official Docker image that includes embedded `op-program` server and Cannon executable. + + + +### Create environment file +First, create a `.env` file with your configuration values. This file will be used by Docker Compose to set up the environment variables: + +```bash +# Create .env file with your actual values +cat > .env << 'EOF' +# L1 Configuration - Replace with your actual RPC URLs +L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY +L1_BEACON=http://sepolia-cl-1:5051 + +# L2 Configuration - Replace with your actual node endpoints +L2_RPC_URL=http://localhost:8545 +ROLLUP_RPC_URL=http://localhost:8547 + +# Wallet configuration - Choose either mnemonic + HD path OR private key +MNEMONIC="test test test test test test test test test test test junk" +HD_PATH="m/44'/60'/0'/0/0" + +# Network configuration +NETWORK=op-sepolia +GAME_FACTORY_ADDRESS=0xYOUR_GAME_FACTORY_ADDRESS +EOF +``` +**Important:** Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values. + +### Understanding configuration flags +Each environment variable maps to a specific challenger configuration flag. Here's what each one does: + +
+--l1-eth-rpc + +* This is the HTTP provider URL for a standard L1 node, can be a full node. `op-challenger` will be sending many requests, so chain operators need a node that is trusted and can easily handle many transactions. +* Note: Challenger has a lot of money, and it will spend it if it needs to interact with games. That might risk not defending games or challenging games correctly, so chain operators should really trust the nodes being pointed at Challenger. +
+ +
+--l1-beacon + +* This is needed just to get blobs from. +* In some instances, chain operators might need a blob archiver or L1 consensus node configured not to prune blobs: + * If the chain is proposing regularly, a blob archiver isn't needed. There's only a small window in the blob retention period that games can be played. + * If the chain doesn't post a valid output root in 18 days, then a blob archiver running a challenge game is needed. If the actor gets pushed to the bottom of the game, it could lose if it's the only one protecting the chain. +
+ +
+--l2-eth-rpc + +* This needs to be `op-geth` archive node, with `debug` enabled. +* Technically doesn't need to go to bedrock, but needs to have access to the start of any game that is still in progress. +
+ +
+--rollup-rpc + +* This needs to be an `op-node` archive node because challenger needs access to output roots from back when the games start. See below for important configuration details: + +1. Safe Head Database (SafeDB) Configuration for op-node: + + * The `op-node` behind the `op-conductor` must have the SafeDB enabled to ensure it is not stateless. + + * To enable SafeDB, set the `--safedb.path` value in your configuration. This specifies the file path used to persist safe head update data. + + * Example Configuration: + + ``` + --safedb.path # Replace with your actual path + ``` + + + If this path is not set, the SafeDB feature will be disabled. + + +2. Ensuring Historical Data Availability: + + * Both `op-node` and `op-geth` must have data from the start of the games to maintain network consistency and allow nodes to reference historical state and transactions. + * For `op-node`: Configure it to maintain a sufficient history of blockchain data locally or use an archive node. + * For `op-geth`: Similarly, configure to store or access historical data. + * Example Configuration: + + ``` + op-node \ + --rollup-rpc \ + --safedb.path + ``` + + + Replace `` with the URL of your archive node and `` with the desired path for storing SafeDB data. + +
+ +
+--private-key + +* Chain operators must specify a private key or use something else (like `op-signer`). +* This uses the same transaction manager arguments as `op-node` , batcher, and proposer, so chain operators can choose one of the following options: + * a mnemonic + * a private key + * `op-signer` endpoints +
+ +
+--network + +* This identifies the L2 network `op-challenger` is running for, e.g., `op-sepolia` or `op-mainnet`. +* When using the `--network` flag, the `--game-factory-address` will be automatically pulled from the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json). +* When cannon is executed, challenger needs the roll-up config and the L2 Genesis, which is op-geth's Genesis file. Both files are automatically loaded when Cannon Network is used, but custom networks will need to specify both Cannon L2 Genesis and Cannon rollup config. +* For custom networks not in the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json), the `--game-factory-address` and rollup must be specified, as follows: + + ``` + --cannon-rollup-config rollup.json \ + --cannon-l2-genesis genesis-l2.json \ + # use this if running challenger outside of the docker image + --cannon-server ./op-program/bin/op-program \ + # json or url, version of op-program deployed on chain + # if you use the wrong one, you will lose the game + # if you deploy your own contracts, you specify the hash, the root of the json file + # op mainnet are tagged versions of op-program + # make reproducible prestate + # challenger verifies that onchain + --cannon-prestate ./op-program/bin/prestate.json \ + # load the game factory address from system config or superchain registry + # point the game factory address at the dispute game factory proxy + --game-factory-address + ``` + + + These options vary based on which `--network` is specified. Chain operators always need to specify a way to load prestates and must also specify the cannon-server whenever the docker image isn't being used. + +
+ +
+--datadir -If you prefer containerized deployment, you can use the official Docker images that include embedded `op-program` server and Cannon executable. +* This is a directory that `op-challenger` can write to and store whatever data it needs. It will manage this directory to add or remove data as needed under that directory. +* If running in docker, it should point to a docker volume or mount point, so the data isn't lost on every restart. The data can be recreated if needed but particularly if challenger has executed cannon as part of responding to a game it may mean a lot of extra processing. +
-### Complete Docker setup +
+--cannon-prestates-url -Create `docker-compose.yml`: +The pre-state is effectively the version of `op-program` that is deployed on chain. And chain operators must use the right version. `op-challenger` will refuse to interact with games that have a different absolute prestate hash to avoid making invalid claims. If deploying your own contracts, chain operators must specify an absolute prestate hash taken from the `make reproducible-prestate` command during contract deployment, which will also build the required prestate json file. + +All governance approved releases use a tagged version of `op-program`. These can be rebuilt by checking out the version tag and running `make reproducible-prestate`. + +* There are two ways to specify the prestate to use: + * `--cannon-prestate`: specifies a path to a single Cannon pre-state Json file + * `--cannon-prestates-url`: specifies a URL to load pre-states from. This enables participating in games that use different prestates, for example due to a network upgrade. The prestates are stored in this directory named by their hash. +* Example final URL for a prestate: + * [https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json](https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json) + * This file contains the cannon memory state. + + + Challenger will refuse to interact with any games if it doesn't have the matching prestate. + Check this [guide](/operators/chain-operators/tutorials/absolute-prestate#generating-the-absolute-prestate) on how to generate a absolute prestate. + +
+ +### Set up Docker Compose +Create a `docker-compose.yml` file that defines the challenger service: ```yaml version: '3.8' services: challenger: - image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:v0.2.11 + image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:v1.5.0 user: "1000" volumes: - ./challenger-data:/data @@ -387,28 +578,33 @@ services: - ./genesis-l2.json:/workspace/genesis-l2.json:ro environment: - L1_RPC_URL=${L1_RPC_URL} - - L1_BEACON_URL=${L1_BEACON_URL} + - L1_BEACON=${L1_BEACON} - L2_RPC_URL=${L2_RPC_URL} - ROLLUP_RPC_URL=${ROLLUP_RPC_URL} - - PRIVATE_KEY=${PRIVATE_KEY} + - MNEMONIC=${MNEMONIC} + - HD_PATH=${HD_PATH} - NETWORK=${NETWORK} + - GAME_FACTORY_ADDRESS=${GAME_FACTORY_ADDRESS} command: - "op-challenger" - "--l1-eth-rpc=${L1_RPC_URL}" - - "--l1-beacon=${L1_BEACON_URL}" + - "--l1-beacon=${L1_BEACON}" - "--l2-eth-rpc=${L2_RPC_URL}" - "--rollup-rpc=${ROLLUP_RPC_URL}" - "--selective-claim-resolution" - - "--private-key=${PRIVATE_KEY}" + - "--mnemonic=${MNEMONIC}" + - "--hd-path=${HD_PATH}" - "--network=${NETWORK}" + - "--game-factory-address=${GAME_FACTORY_ADDRESS}" - "--datadir=/data" - - "--cannon-prestates-url=${CANNON_PRESTATES_URL}" + - "--cannon-prestate=/workspace/prestate-proof.json" restart: unless-stopped ports: - "8548:8548" # If challenger exposes metrics endpoint ``` -Start with Docker: +### Launch the challenger +Start the challenger service and monitor its logs: ```bash # Start the challenger service @@ -418,6 +614,11 @@ docker-compose up -d docker-compose logs -f challenger ``` + + + + + ### Monitoring with op-dispute-mon Consider running [`op-dispute-mon`](/operators/chain-operators/tools/chain-monitoring#dispute-mon) for enhanced security monitoring: From 0aee6f48dc500ce133889430d62b515f9645c6b4 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Tue, 19 Aug 2025 13:37:42 +0100 Subject: [PATCH 10/12] Update op-challenger documentation to specify paths for cannon binary and configuration files, enhancing clarity for users setting up their environment. --- .../chain-operators/deploy/op-challenger.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/pages/operators/chain-operators/deploy/op-challenger.mdx b/pages/operators/chain-operators/deploy/op-challenger.mdx index 9c153f45c..7e72b1b4e 100644 --- a/pages/operators/chain-operators/deploy/op-challenger.mdx +++ b/pages/operators/chain-operators/deploy/op-challenger.mdx @@ -195,11 +195,14 @@ TRACE_TYPE=permissioned,cannon DATADIR=./challenger-data # Cannon configuration -CANNON_BIN=./cannon/bin/cannon -CANNON_ROLLUP_CONFIG=./rollup.json -CANNON_L2_GENESIS=./genesis-l2.json -CANNON_SERVER=./op-program/bin/op-program -CANNON_PRESTATE=./prestate-proof.json +# Path to the cannon binary (built from optimism repo) +CANNON_BIN=/cannon/bin/cannon + +# Configuration files +CANNON_ROLLUP_CONFIG= +CANNON_L2_GENESIS= +CANNON_SERVER=/op-program/bin/op-program +CANNON_PRESTATE= EOF ``` From e1c201573ed7277a206699ef2558cbe74f90b368 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Tue, 19 Aug 2025 14:06:48 +0100 Subject: [PATCH 11/12] Update proposer setup guide to correct DisputeGameFactory address extraction command for improved accuracy. --- pages/operators/chain-operators/deploy/proposer-setup-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/operators/chain-operators/deploy/proposer-setup-guide.mdx b/pages/operators/chain-operators/deploy/proposer-setup-guide.mdx index 734d9771a..6b620580f 100644 --- a/pages/operators/chain-operators/deploy/proposer-setup-guide.mdx +++ b/pages/operators/chain-operators/deploy/proposer-setup-guide.mdx @@ -111,7 +111,7 @@ cd proposer-node cp ../.deployer/state.json . # Extract the DisputeGameFactory address -GAME_FACTORY_ADDRESS=$(cat state.json | jq -r '.opChainDeployments[0].disputeGameFactoryProxyAddress') +GAME_FACTORY_ADDRESS=$(cat state.json | jq -r '.opChainDeployments[0].DisputeGameFactoryProxy') echo "DisputeGameFactory Address: $GAME_FACTORY_ADDRESS" ``` From b2f4dd260407f35508a204fc7e147e5bfbe253e9 Mon Sep 17 00:00:00 2001 From: Blessing Krofegha Date: Tue, 19 Aug 2025 15:04:01 +0100 Subject: [PATCH 12/12] Auto-fix: Update breadcrumbs, spelling dictionary and other automated fixes --- pages/stack/fault-proofs/explainer.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/fault-proofs/explainer.mdx b/pages/stack/fault-proofs/explainer.mdx index 52eefd5c0..19960474e 100644 --- a/pages/stack/fault-proofs/explainer.mdx +++ b/pages/stack/fault-proofs/explainer.mdx @@ -96,7 +96,7 @@ Users would generally just propose a single output root if they need to withdraw The [`create-game`](https://github.com/ethereum-optimism/optimism/tree/develop/op-challenger#create-game) subcommand of `op-challenger` is **for testing purposes only** and should not be used in production environments. It is not intended as a replacement for proper `op-proposer` infrastructure. -For detailed guidance on running `op-challenger`, see the [OP-Challenger explainer](/stack/fault-proofs/challenger) and [how to configure challenger for your chain](/operators/chain-operators/tools/op-challenger). +For detailed guidance on running `op-challenger`, see the [OP-Challenger explainer](/stack/fault-proofs/challenger) and [how to configure challenger for your chain](/operators/chain-operators/deploy/op-challenger). ### How much ETH should a chain operator put aside to operate the Fault Proof System?