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.

​

Upgrading a Chain From Output Roots to Super Roots

​

Before You Begin

​

Required tooling

​

Gather the Required Inputs

cd <optimism-monorepo>/op-fetcher
just build-all
go run ./cmd fetch \
  --l1-rpc-url "$L1_RPC" \
  --system-config "<SystemConfigProxy>" \
  --l1-standard-bridge "<L1StandardBridgeProxy>" \
  --output-file chain.json

• 1 (PERMISSIONED_CANNON) — chain is permissioned. The new respected game type is 5 (SUPER_PERMISSIONED_CANNON).
• 0 (CANNON) or 8 (CANNON_KONA) — chain is permissionless. The new respected game type is 9 (SUPER_CANNON_KONA).

​

Verify the Preconditions

• Confirm the template injects overrides.cfg.startingAnchorRoot. Open superchain-ops/src/template/OPCMUpgradeV800.sol and check _buildExtraInstructions. As of writing it only injects overrides.cfg.startingRespectedGameType and PermittedProxyDeployment. Without an overrides.cfg.startingAnchorRoot override, OPCM falls back to the existing on-chain startingAnchorRoot, which on a pre-upgrade chain is an output-root-shaped value with a block-number l2SequenceNumber — not a valid super-root anchor. The template must be extended to read a starting super-root anchor from TOML and add it as a third extra instruction. Fix the template before continuing.
• Confirm the op-supernode tracks only this chain. op-proposer, op-challenger, and op-dispute-mon must point at a supernode instance whose dependency set contains only this chain’s L2 chain ID. A supernode that also tracks other chains computes super roots across all of them, and those roots will not match what this chain’s SUPER_CANNON_KONA / SUPER_PERMISSIONED_CANNON games verify. If the same physical operator also runs supernodes for other chains (or an interop cluster), stand up a dedicated single-chain supernode instance for this upgrade.
• Verify the op-supernode is healthy. Confirm it reports a finalized L2 head within the chain’s expected finality window:
  cast rpc supernode_syncStatus --rpc-url $SUPERNODE_RPC | jq -r '.finalized_timestamp'
  
  If the supernode is materially behind, postpone.
• Verify the prestate server serves the new hash.
  curl -fI "$PRESTATE_URL/$SUPER_PRESTATE_HASH.bin.gz"
  

​

Stage the Off-Chain Configuration

​

Update op-challenger

​

Update 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 overrides.cfg.startingAnchorRoot.
• timestamp (the uint64 you passed in) — passed as Proposal.l2SequenceNumber. This field is the timestamp itself, not a block number or sequence index.

​

Build the superchain-ops Task

​

Configure config.toml

l2chains = [
    {name = "<chain name>", chainId = <chain id>},
]

templateName = "OPCMUpgradeV800"

[[opcmUpgrades]]
chainId = <chain id>
# Kona-interop super prestate, used by both SUPER_PERMISSIONED_CANNON and
# SUPER_CANNON_KONA. The `-interop` variant supports super roots and works whether
# or not interop is enabled or scheduled on the chain.
cannonKonaPrestate = "0x<kona-interop super prestate>"
expectedValidationErrors = ""   # fill in after the dry run
initBond = 80000000000000000    # 0.08 ether, applied to every enabled super game type
startingRespectedGameType = <9 or 5>   # 9 permissionless, 5 permissioned

# Pending template extension — see the "Generate the Starting Anchor Super Root" section.
startingAnchorRoot = { root = "0x<super root hash>", l2SequenceNumber = <timestamp> }

[addresses]
OPCM = "0x<OPCM v8.x.y address>"

​

Capture expectedValidationErrors

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

• Resolve it if it points at a fixable input — a wrong address, a wrong prestate, a template release mismatch, a missing override, or a registry entry that needs updating.
• Add it to expectedValidationErrors only after justifying it with an inline comment in the TOML explaining why it is structurally expected for this chain.

​

Execute the Upgrade

1. Stop op-proposer for the chain. Existing games continue to resolve; only new proposals halt.
2. Leave op-challenger and op-dispute-mon running. Both were configured earlier and pick up super-root games automatically.
3. Sign and broadcast the task using your team’s standard superchain-ops signing workflow.
4. Wait for the L1 transaction to confirm.

• <ASR> is re-initialised with the supplied anchor and respected game type. The retirement timestamp is not bumped, so existing in-flight games stay valid.
• The super dispute game implementation or implementations are installed on <DGF>.
• Implementation pointers for the game types passed with enabled = false are cleared, blocking creation of new games of those types.

​

Verify the Upgrade On-Chain

​

Common Checks

# Respected game type
cast call <ASR> 'respectedGameType()(uint32)' --rpc-url $L1_RPC
# Expect: 9 (permissionless) or 5 (permissioned)

# Anchor root and timestamp
cast call <ASR> 'getAnchorRoot()(bytes32,uint256)' --rpc-url $L1_RPC
# Expect: (<super root hash>, <timestamp>) from the previous step

# Retirement timestamp unchanged
cast call <ASR> 'retirementTimestamp()(uint64)' --rpc-url $L1_RPC
# Expect: same value as before the upgrade

# Pre-migration impls cleared
cast call <DGF> 'gameImpls(uint32)(address)' 0 --rpc-url $L1_RPC   # CANNON
cast call <DGF> 'gameImpls(uint32)(address)' 1 --rpc-url $L1_RPC   # PERMISSIONED_CANNON
cast call <DGF> 'gameImpls(uint32)(address)' 8 --rpc-url $L1_RPC   # CANNON_KONA
# Expect each: 0x0000000000000000000000000000000000000000

​

Permissionless Chain Checks

cast call <DGF> 'gameImpls(uint32)(address)' 5 --rpc-url $L1_RPC   # SUPER_PERMISSIONED_CANNON
cast call <DGF> 'gameImpls(uint32)(address)' 9 --rpc-url $L1_RPC   # SUPER_CANNON_KONA
# Expect both: non-zero

cast call <DGF> 'initBonds(uint32)(uint256)' 5 --rpc-url $L1_RPC
cast call <DGF> 'initBonds(uint32)(uint256)' 9 --rpc-url $L1_RPC
# Expect both: the configured TOML initBond (e.g. 80000000000000000 = 0.08 ether)

​

Permissioned Chain Checks

cast call <DGF> 'gameImpls(uint32)(address)' 5 --rpc-url $L1_RPC   # SUPER_PERMISSIONED_CANNON
# Expect: non-zero

cast call <DGF> 'initBonds(uint32)(uint256)' 5 --rpc-url $L1_RPC
# Expect: the configured TOML initBond (e.g. 80000000000000000 = 0.08 ether)

cast call <DGF> 'gameImpls(uint32)(address)' 9 --rpc-url $L1_RPC   # SUPER_CANNON_KONA
# Expect: 0x0000000000000000000000000000000000000000

​

Switch op-proposer to Super Roots

• The logs show the proposer polling the supernode and contain no references to --rollup-rpc.
• Within one --proposal-interval, the proposer submits a new game. Inspect it:
  COUNT=$(cast call <DGF> 'gameCount()(uint256)' --rpc-url $L1_RPC)
  # Expect: increased by 1 since the upgrade
  echo "gameCount=$COUNT"
  
  read -r GAME_TYPE CREATED_AT GAME_PROXY < <(cast call <DGF> 'gameAtIndex(uint256)(uint32,uint64,address)' $((COUNT-1)) --rpc-url $L1_RPC)
  # Expect: gameType matches the configured super type (5 or 9) and gameProxy is 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
  
  This confirms op-proposer is correctly configured and passing valid super roots.

​

Verify After the Upgrade

• Pre-migration game still resolves. Pick a still-in-flight pre-migration game (use op-dispute-mon dashboards or gameAtIndex to find one) and watch its status until it resolves:
  cast call <gameProxy> 'status()(uint8)' --rpc-url $L1_RPC
  # 0 = IN_PROGRESS, 1 = CHALLENGER_WINS, 2 = DEFENDER_WINS
  
• op-challenger is tracing both kinds of game. The challenger does not break metrics down by game type. Verify via the startup log (every configured trace type, including the new super types, should be listed as registered) and ongoing logs (no scheduler or game-poll errors as super games appear in the factory). The aggregate op_challenger_tracked_games{status} should keep advancing.
• op-dispute-mon reports super-root games. Dispute-mon also has no per-game-type metric. Confirm aggregate counters (games_agreement, claims, resolution_status) keep incrementing as super games are created and resolved, and that there are no errors in the dispute-mon logs about unrecognised game types.
• No new pre-migration games can be created. Optionally call DisputeGameFactory.create with one of the disabled game types and confirm it reverts.
• Anchor advances on first super-game finalisation. The first anchor update typically lands ~7 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 root. Track via op-dispute-mon rather than waiting in-line.