> ## 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. # Upgrade 21 > Prepare for Upgrade 21, an L1 contract upgrade that makes the ETHLockbox the custody and pause identifier for every chain and ships the L1 contract changes for interop. 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. > [!NOTE] > > 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](https://docs.optimism.io/op-stack/security/pause.md) 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](https://docs.optimism.io/chain-operators/tutorials/merge-shared-dispute-game.md) describes the migration flow and is not yet cleared for production chains. For the node topology that interop requires, see [Interop activation prep](https://docs.optimism.io/notices/interop-prep.md). ### 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. > [!NOTE] > > See [Pausing the bridge](https://docs.optimism.io/op-stack/security/pause.md) 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. > [!NOTE] > > See [Exchanges and bridges](https://docs.optimism.io/op-stack/security/exchanges-and-bridges.md) 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. | Milestone | Target date | | - | - | | Governance proposal published | **Monday, November 2, 2026** | | Sepolia execution | **Monday, November 9, 2026** | | Governance veto period ends | **Wednesday, November 11, 2026** | | Mainnet execution | **Monday, November 16, 2026** | 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.