Skip to main content
Upgrade 21 is an L1 smart contract upgrade for OP Stack chains. It ships in op-contracts/v9.0.0, makes the ETHLockbox the custody and pause identifier for every chain, 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 an ETHLockbox, 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 OptimismPortal has the feature enabled by the upgrade, and the portal’s ETH balance moves into the chain’s ETHLockbox in the same transaction.
  • A chain that already uses an ETHLockbox keeps its ETH where it is.
  • A chain that uses a custom gas token keeps custody in the portal and does not move ETH.
Before this upgrade, the pause identifier was the lockbox address only when the 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.

​
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 ETHLockbox address, read from ethLockbox() on the OptimismPortal, as the chain-specific pause identifier.
  • Update any monitoring that filters Paused and Unpaused events by the OptimismPortal address.
  • If you monitor the ETH balance of the OptimismPortal, monitor the ETHLockbox balance 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.
See Pausing the bridge for how chain-specific pause identifiers work and how to pause a chain.

​
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 OptimismPortal to measure the ETH held for a chain. After the upgrade, read the balance of the chain’s ETHLockbox.
  • Filters Paused events from the SuperchainConfig by the OptimismPortal address.
  • Tracks withdrawal proofs and should handle the new WithdrawalProofDeleted event.
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 ETHLockbox and that OptimismPortal.paused() reflects a test pause.
  • Confirm your dashboards and alerts read the ETHLockbox balance and the lockbox pause identifier.
  • Run integration tests that cover every portal balance read and Paused event filter listed in this notice.
If you have questions or need support, contact your Optimism point of contact.