op-contracts/v9.0.0, makes the ETHLockbox the custody and pause identifier for every chain, hardens the L1 withdrawal path, and includes the L1 contract changes that interop needs.
It has no L2 hardfork, so there is no activation timestamp to configure.
Each network is upgraded by executing an onchain task.
This notice is provisional.
The dates below are targets that depend on Optimism Governance approval, and contract and component versions will be added when the release candidates are published.
What’s included
ETHLockbox as the custody and pause identifier
After Upgrade 21, every chain has anETHLockbox, and the lockbox is the only identifier used for a chain-specific pause.
The ETH_LOCKBOX feature on SystemConfig can no longer be disabled.
- A chain whose ETH is still held by the
OptimismPortalhas the feature enabled by the upgrade, and the portal’s ETH balance moves into the chain’sETHLockboxin the same transaction. - A chain that already uses an
ETHLockboxkeeps its ETH where it is. - A chain that uses a custom gas token keeps custody in the portal and does not move ETH.
ETH_LOCKBOX feature was enabled, and the OptimismPortal address otherwise.
After it, the OptimismPortal, SystemConfig, AnchorStateRegistry, and DelayedWETH all resolve their chain-specific pause through the lockbox.
Initializer argument types change for these contracts, but their function selectors do not.
OptimismPortal.paused() remains the check to rely on.
See Pausing the bridge for how pause identifiers work.
L1 bridge hardening
OptimismPortal2.finalizeWithdrawalTransaction reverts with OptimismPortal_L1CDMCallFailed when the sender is the L2CrossDomainMessenger and the call into the L1CrossDomainMessenger fails, so the withdrawal stays retryable instead of being finalized as failed.
L1CrossDomainMessenger.relayMessage reserves more gas to record a relay’s outcome, which is what lets a failed message be replayed, and copies the payload into memory before its gas check so the copy no longer uses up the reserved gas.
The relay gas constants are split into LOCAL_* (this chain’s relay) and REMOTE_* (baseGas charged for the other chain).
The RELAY_* getters remain as aliases of REMOTE_* on IL1CrossDomainMessenger.
Interop contract changes
Upgrade 21 includes the L1 contract changes that interop needs. These changes do nothing until a later upgrade uses them: Upgrade 21 does not call the migration, and it does not activate interop.OPContractsManagerV2.migrate merges a set of independent chains into one interop set in a single transaction.
It deploys a shared ETHLockbox, DisputeGameFactory, and AnchorStateRegistry, moves every chain’s ETH into the shared lockbox, points each portal at the shared contracts, and enables the INTEROP feature.
Only the ProxyAdmin owner can call it.
The migration is one-way, because INTEROP cannot be disabled and a migrated chain is rejected if it is migrated again.
It also invalidates every withdrawal proof made before it, so users must prove those withdrawals again.
The shared dispute game runbook describes the migration flow and is not yet cleared for production chains.
For the node topology that interop requires, see Interop activation prep.
Withdrawal proof cleanup
OptimismPortal.deleteProvenWithdrawal(bytes32,address) lets anyone delete a withdrawal proof whose dispute game can never lead to finalization, meaning the game resolved in favor of the challenger or was blacklisted.
It emits WithdrawalProofDeleted.
Proofs against valid games are not affected.
OPCM and StandardValidator updates
OPContractsManagerV2 and OPContractsManagerStandardValidator are updated for the changes above.
The validator adds assertions for the new lockbox and pause configuration and handles the shared ProxyAdmin of interop chains.
Required actions
Chain operators
- Update Guardian pause tooling and runbooks to pass the chain’s
ETHLockboxaddress, read fromethLockbox()on theOptimismPortal, as the chain-specific pause identifier. - Update any monitoring that filters
PausedandUnpausedevents by theOptimismPortaladdress. - If you monitor the ETH balance of the
OptimismPortal, monitor theETHLockboxbalance instead after the upgrade. - Chains governed by the Optimism Security Council are upgraded through Optimism Governance.
- OP Enterprise Fully Managed chains: Optimism handles the upgrade, and no action is required for the contract upgrade itself.
- OP Enterprise Self Managed chains: you must already be on Upgrade 20. Open a PR in superchain-ops with your Upgrade 21 task, and the OP Labs team will review it. Contact your Optimism point of contact if you need support.
- All other chains: you must already be on Upgrade 20. Upgrade your L1 contracts with OPCM.
- Update
op-challengerto v1.11.0 and, on a permissionless chain, configure the new absolute prestate, as described in Update the absolute prestate.
See Pausing the bridge for how chain-specific pause identifiers work and how to pause a chain.
Update the absolute prestate
Upgrade 21 has no hardfork, but it ships a new absolute prestate built fromkona-client/v1.9.0.
op-challenger v1.11.0 bundles the matching kona-host v1.9.0, so updating op-challenger is the only off-chain component change.
No other OP Stack component needs a new version for the prestate.
- Permissioned chains do not use an absolute prestate for
SUPER_PERMISSIONEDgames. Updateop-challengerand no other prestate work is required. - Permissionless chains in the superchain registry (OP, Ink, Unichain, and Soneium, on both Sepolia and Mainnet) are covered by the standard prestate, which Optimism sets onchain as part of the governed upgrade. Update
op-challengerand confirm it can fetch the new prestate. - Permissionless chains outside the superchain registry are not covered by the standard prestate. Build your own, host it for
op-challenger, and set it onchain as part of your OPCM upgrade by following the steps below.
1
Build or verify the absolute prestate
- Standard chain configuration
- Custom chain configuration
The standard prestate is the Confirm the output matches the published hashes.
kona-client v1.9.0 cannon64-kona-interop hash in standard-prestates.toml:cannon64-kona-interop:0x03e5a54835d39c1d83b198314473e1f111c3539c04f65c3e8a9b8ccebe3737c9. Used bySUPER_CANNON_KONAgames after Upgrade 20.
kona-client/v1.9.0 in the monorepo, reproduce the prestate, and read the hash:2
Upload the new preimage file
Upload the new preimage file to wherever you store your other absolute preimage files. This is the location
--prestates-url or --cannon-kona-prestates-url points at. op-challenger fetches the file from there when it needs to play a game.The build writes a copy named after the absolute prestate hash, for example 0x<hash>.bin.gz. Keep that filename when you upload it.
Keep the Upgrade 20 prestate file in place so op-challenger can finish games created before the upgrade.
A custom prestate must be hosted at a URL reachable by every challenger that participates on the chain.3
Update op-challenger
Update
op-challenger to v1.11.0 before the L1 contract upgrade.
Your existing game types and prestate URL flags carry over unchanged.
Review the release notes before upgrading: v1.11.0 renames list-games and list-claims output fields, rejects unusable --run entries in run-trace, and refuses to start kona-host with a missing or invalid dependency set file.If you do not use the standard OP Labs op-challenger Docker image, set the kona-host binary path, built from kona-host/v1.9.0:4
Set the new prestate onchain
Pass your new hash as the
absolutePrestate in the dispute game configuration of your OPCM upgrade input, so the upgrade transaction registers it in the DisputeGameFactory.
Simulate and validate the expected output before executing the transaction.After the upgrade, confirm the onchain prestate matches your build. The prestate lives in the first 32 bytes of gameArgs(<gameType>) on the DisputeGameFactory, or on a created game instance. absolutePrestate() on the bare implementation returns zero.Node operators
Upgrade 21 has no L2 hardfork. Required component versions, if any, will be listed here when the release candidates are published.App developers and infrastructure integrators
Ordinary L2 contracts and transactions are not affected. Update an integration if it does any of the following:- Reads the ETH balance of the
OptimismPortalto measure the ETH held for a chain. After the upgrade, read the balance of the chain’sETHLockbox. - Filters
Pausedevents from theSuperchainConfigby theOptimismPortaladdress. - Tracks withdrawal proofs and should handle the new
WithdrawalProofDeletedevent. - Finalizes or relays withdrawals.
finalizeWithdrawalTransactionnow reverts withOptimismPortal_L1CDMCallFailedwhen the call into the L1 messenger fails; treat it as retryable with more gas. A messenger withdrawal that can never be relayed stays proven but unfinalized rather than being finalized as failed. - Reads the messenger’s relay gas constants. They are split into
LOCAL_*andREMOTE_*; theRELAY_*getters remain as aliases ofREMOTE_*.
See Exchanges and bridges for guidance on monitoring chain balances and pause state.
Users
No action is required.Upgrade timing
Upgrade 21 is applied as an L1 contract upgrade, so each network is upgraded by executing an onchain task.
OP Enterprise Fully Managed chains follow this tentative timeline.
OP Enterprise Self Managed chains can reach out to their Optimism point of contact if they need any support.
Governed Sepolia OP Stack chains are upgraded first, followed by a seven-day soak period before mainnet execution.
Mainnet execution depends on Optimism Governance approval and a healthy Sepolia soak, so these dates can move.
The Governance proposal and onchain vote will be linked here when they are published.
Verify readiness
After Sepolia execution, and before mainnet execution:- Confirm your Guardian pause tooling targets the
ETHLockboxand thatOptimismPortal.paused()reflects a test pause. - Confirm your dashboards and alerts read the
ETHLockboxbalance and the lockbox pause identifier. - Run integration tests that cover every portal balance read and
Pausedevent filter listed in this notice.