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 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
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 for your network version - This is critical as the challenger will refuse to interact with games if it doesn’t have the matching prestate
2
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
3
Prepare configuration files
rollup.json- Rollup configuration filegenesis-l2.json- L2 genesis fileprestate.json- The absolute prestate file generated in step 1
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 This guide is verified against the following versions:- op-challenger —
op-challenger/v1.9.4(look for the latestop-challenger/v*). - op-reth —
v2.2.5(look for the latest op-reth release). op-reth is both the sequencer’s execution client and the archive node the challenger reads withdrawal proofs from. - kona-client — the absolute prestate is built from a tagged
kona-client/v*release (e.g.kona-client/v1.6.0-rc.1). Use the tag matching the prestate registered on your chain; for governance-approved upgrades the version is named in the upgrade notice. See the kona-client prestate tutorial.
Software installation
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
- Use docker
Build and configure
Building from source gives you full control over the binaries and is the preferred approach for production deployments.Clone and build op-challengerkona-host, the pre-image oracle server for the cannon-kona game type. Build it from the kona-client release tag matching the absolute prestate registered on your chain (see Finding the current stable releases), so the server matches the kona-client build committed on chain:Verify installation
Check that you have properly installed the challenger component:Configuration setup
1
Organize your workspace
After building the binaries, create your challenger working directory:
2
Copy configuration files
3
Set up 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:Important: Replace ALL placeholder values (
- L1 RPC URL: Your L1 node endpoint (Infura, Alchemy, or self-hosted)
- L1 Beacon URL: Beacon chain API endpoint for blob access
- L2 RPC URL: Your op-reth archive node endpoint
- Rollup RPC URL: Your op-node endpoint with historical data
- Private key for challenger operations (must be funded)
- Game factory address from your contract deployment
- Network identifier (e.g., op-sepolia, op-mainnet, or custom)
YOUR_ACTUAL_*) with your real configuration values.4
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-challengerwill 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 an
op-retharchive node, withdebugenabled. - Technically doesn’t need to go to bedrock, but needs to have access to the start of any game that is still in progress.
- The withdrawal-proof data the challenger reads via
eth_getProofis served by op-reth’s historical-proofs store. Enable it with--proofs-history --proofs-history.storage-version v2, set a persistent--proofs-history.storage-path, and size--proofs-history.windowto cover the dispute game window (≥ 28 days). On permissioned chains,--rpc.eth-proof-windowbounds how far backeth_getProofwill serve. See Running op-reth with historical proofs. - Seed the proofs storage once before starting the node with
--proofs-history, or op-reth refuses to start (theproofs-historyExEx panics withProofs storage not initialized). With the node stopped, runop-reth proofs init --chain <chain-or-genesis> --datadir <reth-datadir> --proofs-history.storage-path <proofs-db-path> --proofs-history.storage-version v2. It snapshots the chain’s current state to seed the sidecar; the ExEx then indexes forward as the node syncs. Initialize at (or near) genesis so the whole fault-proof window is covered — a node seeded at the current tip only serves proofs for blocks after that point.
--rollup-rpc
--rollup-rpc
- This needs to be an
op-nodearchive node because challenger needs access to output roots from back when the games start. See below for important configuration details:
-
Safe Head Database (SafeDB) Configuration for op-node:
-
The
op-nodebehind theop-conductormust have the SafeDB enabled to ensure it is not stateless. -
To enable SafeDB, set the
--safedb.pathvalue in your configuration. This specifies the file path used to persist safe head update data. -
Example Configuration:
If this path is not set, the SafeDB feature will be disabled.
-
The
-
Ensuring Historical Data Availability:
-
Both
op-nodeandop-rethmust 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-reth: Similarly, configure to store or access historical data. -
Example Configuration:
Replace<op-node-archive-node-url>with the URL of your archive node and<path-to-safe-head-db>with the desired path for storing SafeDB data. -
Both
--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-signerendpoints
--network
--network
-
This identifies the L2 network
op-challengeris running for, e.g.,op-sepoliaorop-mainnet. -
When using the
--networkflag, the--game-factory-addresswill be automatically pulled from thesuperchain-registry. -
When the trace is generated, challenger needs the rollup config and the L2 genesis file. Both files are automatically loaded when a registry
--networkis used, but custom networks must specify both the L2 genesis and rollup config. -
For custom networks not in the
superchain-registry, the--game-factory-addressand rollup must be specified, as follows:
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-kona-server whenever the docker image isn’t being used.--datadir
--datadir
- This is a directory that
op-challengercan 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-kona-prestate / --cannon-kona-prestates-url
--cannon-kona-prestate / --cannon-kona-prestates-url
The prestate is effectively the version of
kona-client that is deployed on chain (run inside the Cannon VM as the cannon-kona game type). 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 just reproducible-prestate-kona command during contract deployment, which will also build the required prestate file.All governance approved releases use a tagged version of kona-client. These can be rebuilt by checking out the version tag and running just reproducible-prestate-kona.- There are two ways to specify the prestate to use:
--cannon-kona-prestate: specifies a path to a single kona-client absolute-prestate file--cannon-kona-prestates-url: specifies a URL to load prestates 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
- 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 on how to generate a absolute prestate.
Create challenger startup script
Createscripts/start-challenger.sh:Initializing and starting the challenger
Start the challenger
Verify challenger is running
Monitor challenger logs to ensure it’s operating correctly:- Successful connection to L1 and L2 nodes
- Loading of prestates and configuration
- Monitoring of dispute games
Monitoring with op-dispute-mon
Consider runningop-dispute-mon for enhanced security monitoring:
- Provides visibility into all game statuses for the last 28 days
- Essential for production challenger deployments
Next steps
- Read the OP-Challenger Explainer for additional context and FAQ
- Review the detailed challenger specifications for implementation details
- If you experience any problems, reach out to developer support