Documentation Index

Fetch the complete documentation index at: https://docs.optimism.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Merging Two Chains Into a Shared Dispute Game

​

Before You Begin

• Exactly two chains, referred to below as chainA and chainB, are being merged.
• Neither chain has activated interop yet.
• Both chains run permissionless fault proofs with SUPER_CANNON_KONA (game type 9) as the respected game type today.
• The per-chain op-proposer, op-challenger, and op-dispute-mon instances stood up by the single-chain super-roots upgrade are running for both chains, each backed by its own single-chain op-supernode (chainA’s stack tracks only chainA; chainB’s stack tracks only chainB). These keep running through migration cutover and the subsequent drain window.
• A separate op-supernode instance is in sync and derives exactly chainA and chainB (and no other chains) in the same process. This is the supernode the new shared op-proposer, op-challenger, and op-dispute-mon point at after migration; it must not double as a multi-chain supernode for any other chain or interop cluster.
• Both chains have already been upgraded to a release that exposes OPContractsManagerMigrator.migrate and have Features.INTEROP and Features.ETH_LOCKBOX enabled on their SystemConfig. These features are turned on automatically by OPContractsManagerV2.upgrade() when the OPCM container has the OPTIMISM_PORTAL_INTEROP dev feature set; that pre-upgrade is a prerequisite for this runbook.

​

Install Required Tooling

​

Gather the Required Inputs

op-fetcher fetch \
  --l1-rpc-url $L1_RPC \
  --system-config <SystemConfigProxy> \
  --l1-standard-bridge <L1StandardBridgeProxy> \
  --output-file <chainX>.json

​

Verify the Preconditions

• Confirm the same ProxyAdmin owner across both chains. migrate reverts with OPContractsManagerMigrator_ProxyAdminOwnerMismatch otherwise. Each chain’s ProxyAdmin proxy may differ as long as the owner Safe is identical on both.
  diff <(jq -r '.roles.OpChainProxyAdminOwner' <chainA>.json) <(jq -r '.roles.OpChainProxyAdminOwner' <chainB>.json)
  # Expect: no output (identical).
  
• Confirm the same SuperchainConfig across both chains. migrate reverts with OPContractsManagerMigrator_SuperchainConfigMismatch otherwise.
  diff <(jq -r '.addresses.SuperchainConfigProxy' <chainA>.json) <(jq -r '.addresses.SuperchainConfigProxy' <chainB>.json)
  # Expect: no output (identical).
  
• Confirm both chains have Features.INTEROP and Features.ETH_LOCKBOX enabled. _migratePortal reverts with OPContractsManagerMigrator_InteropFeatureNotEnabled or OPContractsManagerMigrator_EthLockboxFeatureNotEnabled if either is missing. These flip automatically during the prerequisite OPCMv2.upgrade() against an OPTIMISM_PORTAL_INTEROP-enabled OPCM container; if any of the four checks below returns false, run that prerequisite upgrade first. Features constants are short-string bytes32 values, so feed them through cast format-bytes32-string.
  for SC in <SystemConfig_chainA> <SystemConfig_chainB>; do
      for F in INTEROP ETH_LOCKBOX; do
          echo "$SC $F = $(cast call $SC 'isFeatureEnabled(bytes32)(bool)' "$(cast format-bytes32-string $F)" --rpc-url $L1_RPC)"
      done
  done
  # Expect: every line ends in true.
  
• Confirm neither chain runs in Custom Gas Token mode. _migratePortal reverts with OPContractsManagerMigrator_CustomGasTokenNotSupported for any CGT chain.
  cast call <SystemConfig_chainA> 'isCustomGasToken()(bool)' --rpc-url $L1_RPC
  cast call <SystemConfig_chainB> 'isCustomGasToken()(bool)' --rpc-url $L1_RPC
  # Expect: both false.
  
• Confirm the current respected game type on both chains is SUPER_CANNON_KONA (9).
  cast call <oldASR_chainA> 'respectedGameType()(uint32)' --rpc-url $L1_RPC
  cast call <oldASR_chainB> 'respectedGameType()(uint32)' --rpc-url $L1_RPC
  # Expect: 9 for both.
  
• Confirm the shared supernode derives exactly the two merging chains. Verify with your infrastructure team that the instance behind $SUPERNODE_RPC has chainA and chainB in its dependency set and no other chains. A supernode that also tracks an unrelated chain (or an interop cluster that includes one) computes super roots over that broader set, and those roots will not match what the shared SUPER_CANNON_KONA and SUPER_PERMISSIONED_CANNON games verify. The per-chain drain instances continue to use their existing single-chain supernodes; do not repoint them at the shared one.
• Confirm the shared supernode is in sync. It must report a finalized L2 head within both chains’ expected finality windows:
  cast rpc supernode_syncStatus --rpc-url $SUPERNODE_RPC | jq -r '.finalized_timestamp'
  
  If the supernode is materially behind either chain, postpone the migration.
• Confirm the prestate server serves both super prestates.
  curl -fI "$PRESTATE_URL/$SUPER_CANNON_KONA_PRESTATE.bin.gz"
  curl -fI "$PRESTATE_URL/$SUPER_PERMISSIONED_PRESTATE.bin.gz"
  
• Note the chain B DelayedWETH divergence. migrate reuses chain A’s DelayedWETH for the new shared super games and does not touch chain B’s. After migration, chain B’s SystemConfig.delayedWETH() still references chain B’s old DelayedWETH, which is no longer attached to any super game. Future OPCMv2.upgrade() calls against chain B that read SystemConfig.delayedWETH() will therefore reference a different contract than the shared games use. Track this in your operational runbook so future upgrades do not surprise you. The bonds posted by chain B’s still-in-flight pre-migration games continue to claim out of chain B’s old DelayedWETH, so the divergence does not block the drain described in Drain Pre-Migration Games and Reclaim Bonds.

​

Stage the Off-Chain Configuration

​

Stand Up a Shared op-challenger

​

Stand Up a Shared op-dispute-mon

​

Leave op-proposer Unchanged for Now

​

Generate the Starting Anchor Super Root

# .finalized_timestamp is a JSON number (decimal unix seconds).
TS=$(cast rpc supernode_syncStatus --rpc-url $SUPERNODE_RPC | jq -r '.finalized_timestamp')
# superroot_atTimestamp expects a hex-encoded JSON string (hexutil.Uint64); cast 2h handles the conversion.
cast rpc superroot_atTimestamp "$(cast 2h $TS)" --rpc-url $SUPERNODE_RPC | jq -r '.data.super_root'
echo "timestamp=$TS"

• super_root (a bytes32 hash from .data.super_root)—passed as Proposal.root in startingAnchorRoot.
• timestamp (the uint64 you passed in)—passed as Proposal.l2SequenceNumber. For super games this field is the timestamp itself, not a block number.

​

Build the superchain-ops Task

​

Configure config.toml

l2chains = [
    {name = "<chainA name>t stat", chainId = <chainA id>},
    {name = "<chainB name>", chainId = <chainB id>},
]

templateName = "OPCMMigrateInterop"

[addresses]
OPCM = "0x<OPCM address with OPTIMISM_PORTAL_INTEROP enabled>"

# One stanza per chain, both required.
[[migrateChains]]
chainId = <chainA id>
systemConfigProxy = "0x<SystemConfig_chainA>"

[[migrateChains]]
chainId = <chainB id>
systemConfigProxy = "0x<SystemConfig_chainB>"

# Starting anchor for the new shared AnchorStateRegistry, computed in the previous step.
[startingAnchorRoot]
root = "0x<super root hash>"
l2SequenceNumber = <timestamp>

# 9 = SUPER_CANNON_KONA. Required because both chains run permissionless fault proofs today.
startingRespectedGameType = 9

# Both super game types must be registered. The migration validator requires it.
# The template assembles the on-chain DisputeGameConfig.gameArgs bytes from these
# fields: abi.encode(absolutePrestate) for game type 9, and
# abi.encode(absolutePrestate, proposer, challenger) for game type 5.

[[disputeGameConfigs]]
gameType = 9                             # SUPER_CANNON_KONA
enabled = true
initBond = 80000000000000000             # match the value gathered in the inputs
absolutePrestate = "0x<super-cannon-kona prestate>"

[[disputeGameConfigs]]
gameType = 5                             # SUPER_PERMISSIONED_CANNON
enabled = true
initBond = 80000000000000000
absolutePrestate = "0x<super-permissioned-cannon prestate>"
proposer = "0x<privileged proposer>"
challenger = "0x<privileged challenger>"

expectedValidationErrors = ""            # fill in after the dry run if any structurally expected codes appear

​

Capture expectedValidationErrors

cd superchain-ops/src/tasks/<network>/<NNN-name>
just simulate

​

Execute the Migration

1. Stop both per-chain op-proposer processes. Once the migration broadcasts, the per-chain factories no longer have SUPER_CANNON_KONA registered, so DisputeGameFactory.create reverts. Stopping the proposers first prevents wasted gas.
2. Leave both per-chain op-challenger and op-dispute-mon instances running. They continue to defend and observe in-flight pre-migration games on the per-chain factories.
3. Sign and broadcast the task using your team’s standard superchain-ops signing workflow.
4. Wait for the L1 transaction to confirm.

• OPCM deploys and initializes new ETHLockbox, DisputeGameFactory, and AnchorStateRegistry proxies. The new AnchorStateRegistry binds to the new factory and sets retirementTimestamp to block.timestamp at initialization.
• OPCM calls OptimismPortal2.migrateToSharedDisputeGame on each chain to repoint the portal at the new lockbox and the new AnchorStateRegistry. It also authorizes each chain’s existing portal on the shared lockbox, authorizes each chain’s existing lockbox to forward liquidity, and migrates that liquidity into the shared lockbox.
• OPCM zeroes every implementation pointer on each chain’s existing per-chain DisputeGameFactory. Already-deployed game proxies on those factories are unaffected and continue to resolve.

op-fetcher fetch \
  --l1-rpc-url $L1_RPC \
  --system-config <SystemConfig_chainA> \
  --l1-standard-bridge <L1StandardBridge_chainA> \
  --output-file <chainA>-postmigrate.json

op-fetcher fetch \
  --l1-rpc-url $L1_RPC \
  --system-config <SystemConfig_chainB> \
  --l1-standard-bridge <L1StandardBridge_chainB> \
  --output-file <chainB>-postmigrate.json

SHARED_ASR=$(jq -r '.addresses.AnchorStateRegistryProxy' <chainA>-postmigrate.json)
SHARED_DGF=$(jq -r '.addresses.DisputeGameFactoryProxy' <chainA>-postmigrate.json)
SHARED_LOCKBOX=$(jq -r '.addresses.EthLockboxProxy' <chainA>-postmigrate.json)

diff <(jq -r '.addresses.AnchorStateRegistryProxy, .addresses.DisputeGameFactoryProxy, .addresses.EthLockboxProxy' <chainA>-postmigrate.json) \
     <(jq -r '.addresses.AnchorStateRegistryProxy, .addresses.DisputeGameFactoryProxy, .addresses.EthLockboxProxy' <chainB>-postmigrate.json)
# Expect: no output (identical).

​

Verify the Migration On-Chain

​

Verify the Shared Registry and Factory

# Respected game type on the new ASR
cast call $SHARED_ASR 'respectedGameType()(uint32)' --rpc-url $L1_RPC
# Expect: 9 (SUPER_CANNON_KONA)

# Anchor root and timestamp on the new ASR
cast call $SHARED_ASR 'getAnchorRoot()(bytes32,uint256)' --rpc-url $L1_RPC
# Expect: (<super root hash>, <timestamp>) from "Generate the Starting Anchor Super Root"

# Retirement timestamp on the new ASR
cast call $SHARED_ASR 'retirementTimestamp()(uint64)' --rpc-url $L1_RPC
# Expect: equal to the migration block's timestamp

# Game implementations registered on the shared factory
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 5 --rpc-url $L1_RPC   # SUPER_PERMISSIONED_CANNON
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 9 --rpc-url $L1_RPC   # SUPER_CANNON_KONA
# Expect both: non-zero

# Init bonds match the configured values
cast call $SHARED_DGF 'initBonds(uint32)(uint256)' 5 --rpc-url $L1_RPC
cast call $SHARED_DGF 'initBonds(uint32)(uint256)' 9 --rpc-url $L1_RPC

# No legacy implementations registered on the shared factory
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 0 --rpc-url $L1_RPC   # CANNON
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 1 --rpc-url $L1_RPC   # PERMISSIONED_CANNON
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 8 --rpc-url $L1_RPC   # CANNON_KONA
# Expect each: 0x0000000000000000000000000000000000000000

​

Confirm Per-Chain Factories Are Cleared

for OLD_DGF in <oldDGF_chainA> <oldDGF_chainB>; do
    for GT in 0 1 5 8 9; do
        echo "$OLD_DGF gameImpls($GT)= $(cast call $OLD_DGF 'gameImpls(uint32)(address)' $GT --rpc-url $L1_RPC)"
    done
done
# Expect every entry: 0x0000000000000000000000000000000000000000

​

Confirm the Shared Lockbox Is Authorized

cast call $SHARED_LOCKBOX 'authorizedPortals(address)(bool)' <OptimismPortal2_chainA> --rpc-url $L1_RPC
cast call $SHARED_LOCKBOX 'authorizedPortals(address)(bool)' <OptimismPortal2_chainB> --rpc-url $L1_RPC
# Expect both: true

​

Start the Shared op-challenger and op-dispute-mon

1. Set the shared op-challenger’s --game-factory-address (OP_CHALLENGER_GAME_FACTORY_ADDRESS) to $SHARED_DGF and start the process. Confirm the startup log lists super-cannon-kona and super-permissioned as registered trace types and shows no errors connecting to the supernode RPC.
2. Set the shared op-dispute-mon’s --game-factory-address (OP_DISPUTE_MON_GAME_FACTORY_ADDRESS) to $SHARED_DGF and start the process. Confirm the startup log shows the supernode connection is healthy and the metrics endpoint is serving.

​

Cut Over to a Single Shared op-proposer

• The logs show the proposer polling the supernode and writing to the shared factory.
• Within one --proposal-interval, the proposer submits a new game on the shared factory. Inspect it:
  COUNT=$(cast call $SHARED_DGF 'gameCount()(uint256)' --rpc-url $L1_RPC)
  echo "gameCount=$COUNT"
  
  read -r GAME_TYPE CREATED_AT GAME_PROXY < <(cast call $SHARED_DGF 'gameAtIndex(uint256)(uint32,uint64,address)' $((COUNT-1)) --rpc-url $L1_RPC)
  # Expect: GAME_TYPE=9 and GAME_PROXY non-zero.
  echo "gameType=$GAME_TYPE createdAt=$CREATED_AT gameProxy=$GAME_PROXY"
  
  cast call $GAME_PROXY 'rootClaim()(bytes32)'        --rpc-url $L1_RPC
  cast call $GAME_PROXY 'l2SequenceNumber()(uint256)' --rpc-url $L1_RPC
  
• Recompute the super root for the proposed timestamp and confirm it matches the proposal:
  cast rpc superroot_atTimestamp "$(cast 2h <l2SequenceNumber from above>)" \
    --rpc-url $SUPERNODE_RPC | jq -r '.data.super_root'
  # Expect: equals rootClaim from above.
  

​

Drain Pre-Migration Games and Reclaim Bonds

• The two per-chain op-challenger instances continue to play retired games to DEFENDER_WINS or CHALLENGER_WINS and schedule bond claims as games finalize.
• Bond claims succeed without operator intervention. Chain A’s retired games claim through chain A’s DelayedWETH (which is also the one used by the new shared games); chain B’s retired games claim through chain B’s DelayedWETH, which is otherwise unused after migration.
• The two per-chain op-dispute-mon instances keep observing those games. The per-game-type metric op_dispute_mon_games{game_type="super-cannon-kona"} and the equivalent for super-permissioned should monotonically decrease toward zero across the drain window.
• op-challenger’s default --game-window is 28 days, sized to cover up to 16 days of game play plus a seven-day DelayedWETH withdrawal delay plus a five-day buffer. Do not shrink it on the per-chain instances; doing so risks dropping games before their bonds are claimable.

cast call <gameProxy> 'status()(uint8)' --rpc-url $L1_RPC
# 0 = IN_PROGRESS, 1 = CHALLENGER_WINS, 2 = DEFENDER_WINS

cast call <gameProxy> 'resolvedAt()(uint64)' --rpc-url $L1_RPC
# Non-zero once the game has resolved.

​

Verify After the Migration

• Confirm the shared op-challenger is defending super-root games. The challenger does not break metrics down by game type, so verify by way of the startup log (every configured trace type, including super-cannon-kona and super-permissioned, must be listed as registered) and by ongoing logs (no scheduler or game-poll errors as super games appear on the shared factory). The aggregate op_challenger_tracked_games{status="in_progress"} becomes non-zero as super games are created and remains non-zero while games are in progress.
• Confirm the shared op-dispute-mon reports super-root games. On the shared instance, op_dispute_mon_games{game_type="super-cannon-kona"} and op_dispute_mon_games{game_type="super-permissioned"} are non-zero once games are created. op_dispute_mon_failed_games stays near zero; a non-zero value typically points at missing --supernode-rpc or supernode unavailability.
• Confirm new pre-migration games cannot be created. Optionally call DisputeGameFactory.create with one of the cleared game types on either per-chain factory and confirm it reverts.
• Watch for the first super-game finalization. The first anchor update typically lands roughly seven days after the first super-root game is created (game duration plus DISPUTE_GAME_FINALITY_DELAY_SECONDS). Do not block the rollout on this—schedule a follow-up to re-run getAnchorRoot() after that window and confirm it returns the new game’s claim instead of the starting anchor.

​

Tear Down After the Drain

​

Next Steps

• Plan the full interop activation milestone—migrate joins the chains under a shared dispute game, but turning on cross-chain messaging is a separate step. See Interop Explainer when you are ready.
• Schedule a follow-up to verify the anchor advances on the first super-game finalization, roughly seven days after the new proposer’s first proposal. Re-run cast call $SHARED_ASR 'getAnchorRoot()(bytes32,uint256)' --rpc-url $L1_RPC and confirm it returns the new game’s claim.