How to configure challenger for your chain

Build the executable

• Clone the monorepo

git clone https://github.com/ethereum-optimism/optimism.git

• Check out the latest release of op-challenger (opens in a new tab) 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.

  git checkout op-challenger/vX.Y.Z

• Build challenger

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:

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 <path-to-safe-head-db>   # Replace <path-to-safe-head-db> 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 <op-node-archive-node-url> \
     --safedb.path <path-to-safe-head-db>
   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.

--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 (opens in a new tab).

• 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 (opens in a new tab), 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

--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 (opens in a new tab)
  • This file contains the cannon memory state.

Execute challenger

The final step is to execute challenger with the required flags. It will look something like this (but with required flags added):

./op-challenger/bin/op-challenger \
  --trace-type 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:

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.