Skip to main content
ZK proofs are experimental and under active development. Do not rely on them to secure a production chain yet.
This runbook moves a single OP Stack chain from its current super-root dispute game, SUPER_CANNON_KONA (game type 9) or SUPER_PERMISSIONED (game type 5), to the ZK dispute game (ZK_DISPUTE_GAME, game type 10). It runs as one opcm.upgrade call against the chain’s own AnchorStateRegistry and DisputeGameFactory. By the end, op-zk-proposer creates ZK games for the chain, op-challenger checks them, and op-dispute-mon monitors them. Games created before the migration keep their original implementation and resolve as before, and withdrawals proven against them stay valid.
The ZK dispute game commits to super roots. A chain still on output-root games must first move to super roots: follow Upgrading a chain from output roots to super roots, then return here.
This runbook covers a chain with its own DisputeGameFactory and AnchorStateRegistry. It does not cover an interop set whose chains share them; for that case, see Path C of the migration specification.
For the normative description of the migration, see the ZK dispute game migration specification.

Before you begin

Gather the required inputs

Chain addresses. Read the chain’s SystemConfig, AnchorStateRegistry (<ASR>), and DisputeGameFactory (<DGF>) addresses from its superchain-registry entry or with op-fetcher, as in the super roots runbook. Current game type. Confirm the chain’s respected game type:
ZK game parameters. Release artifacts. The OPContractsManager address for op-contracts/v10.0.0 (Upgrade 22) or a later release, from validation/standard/standard-versions-<network>.toml in the superchain-registry. Earlier releases deploy the ZK dispute game only behind a development feature flag. OPContractsManager sets the game’s verifier to its SP1PlonkAdapter, so you do not supply a verifier.

Stand up the off-chain services first

On a chain moving from SUPER_PERMISSIONED, this migration makes proposals permissionless. On either path, the ZK game needs a funded proposer that can prove, and a challenger, from the moment it becomes the respected game type. Bring them up before the upgrade:
  • op-zk-proposer. Configure it as in Configure op-zk-proposer, fund its L1 signer and its prover network account, and publish the prestate’s program files. Do not start it yet: until the upgrade lands, there is no ZK game for it to create.
  • op-challenger. Add zk to --game-types on the running challenger. On a chain moving from SUPER_CANNON_KONA, keep super-cannon-kona in the list so games already in flight stay defended. See Configure op-challenger for ZK dispute games.
  • op-dispute-mon. No change is needed. It discovers ZK games from the same DisputeGameFactory and uses its existing --superroot-rpc.
Confirm that the prestate files download and decompress. $ZK_PRESTATE is the lowercase, 0x-prefixed prestate:

Build the upgrade

The upgrade is one opcm.upgrade call for the chain. Its input has one dispute game configuration for each of the six game types that OPContractsManager supports, in this order: CANNON (0), PERMISSIONED_CANNON (1), CANNON_KONA (8), SUPER_PERMISSIONED (5), SUPER_CANNON_KONA (9), and ZK_DISPUTE_GAME (10). Set them as follows: Add an overrides.cfg.startingRespectedGameType extra instruction with the data abi.encode(uint32(10)) on either path. This instruction sets the respected game type to ZK_DISPUTE_GAME. Without it, the respected game type keeps its current value. A chain moving from SUPER_CANNON_KONA then fails the upgrade, because OPContractsManager requires the respected game type after the upgrade to be enabled. A chain moving from SUPER_PERMISSIONED upgrades, but type 5 stays respected, so its ZK games cannot back withdrawals or update the anchor state. OPContractsManager checks the input and reverts with OPContractsManagerV2_InvalidGameConfigs if:
  • the entries are not the six game types in the order above,
  • the ZK prestate is zero,
  • either ZK duration is zero or above type(uint32).max,
  • the ZK challenger bond or init bond is zero,
  • a disabled entry, or the SUPER_PERMISSIONED entry, has a non-zero init bond, or
  • the respected game type after the upgrade is not enabled.
The anchor state does not change. The current game type already commits to super roots, so the existing anchor is a valid starting point for the first ZK game. Simulate the upgrade against an L1 fork with your team’s standard superchain-ops workflow, and resolve every validation error it reports before you sign. The standard validator checks that the ZK game uses the release’s implementation and verifier and the expected prestate, that its durations, challenger bond, and init bond are not zero, and that SUPER_PERMISSIONED is still registered.

Execute the upgrade

  1. Stop the chain’s current proposer. Games already in flight continue to resolve.
  2. Leave op-challenger and op-dispute-mon running.
  3. Sign and broadcast the upgrade.
  4. Wait for the L1 transaction to confirm.
The upgrade:
  • installs the ZK dispute game implementation and its configuration on <DGF>,
  • on a chain moving from SUPER_CANNON_KONA, clears that game type’s implementation, and
  • sets the respected game type in <ASR> to 10.

Verify the upgrade on-chain

If any check fails, stop, do not start op-zk-proposer, and escalate through your incident-response process.
OPContractsManager validated the ZK configuration during the upgrade. To confirm the values it stored, read them from the first game; see the next section.

Start op-zk-proposer

Start op-zk-proposer. Check its logs for op-zk-proposer started and no anchor, prestate, or verifier errors; see Start the proposer. Within one proposal interval, it creates the first ZK game, building on the anchor state. Check the game’s configuration and claim:

Verify after the migration

  • Games from before the migration still resolve. Watch an in-flight game of the previous type until it resolves. On a chain moving from SUPER_CANNON_KONA, keep super-cannon-kona in op-challenger --game-types until every such game has resolved. op-challenger cannot play SUPER_PERMISSIONED games, and --game-types does not accept them. It still closes them and claims their bonds, as it does for every game type that it no longer plays.
  • op-challenger watches ZK games. Its logs show a Game info line for each ZK game, with no errors from the super root source.
  • op-dispute-mon reports ZK games. op_dispute_mon_games has series with game_type="zk", and op_dispute_mon_zk_games_pending_lifecycle_action does not stay above zero.
  • The anchor advances. The first ZK game updates the anchor state when someone closes it, after it has resolved and its finality delay has passed. op-zk-proposer closes its games when it claims their bonds. Closing is possible at least maxChallengeDuration plus the AnchorStateRegistry finality delay after the game was created, unless the proposer proves it early with fast finality. Schedule a check of getAnchorRoot() after that window.

Next steps