[ZIP-18] Resubmission of the ZKsync v31 Upgrade

Abstract

This proposal resubmits ZIP-16 with updated upgrade calldata. The Token Assembly approved ZIP-16 in July 2026, but the upgrade was not executed. The release delivers:

• Priority Mode for ZKsync OS L1-settling chains, giving users a permissionless path to withdraw their funds even if the sequencer stops processing.
• Broad ZKsync OS compatibility work across the protocol's contract layer.
• An upgrade of ZKsync Era chains from protocol version v0.30.1 to v0.33.0, and of ZKsync OS chains from v0.30.1 to v0.31.2.

Motivation

v31 advances two priorities for ZKsync.

It introduces Priority Mode for L1-settling ZKsync OS chains, a censorship-resistance escape hatch for chains that settle directly to L1. If priority transactions remain unprocessed for too long, anyone can activate a restricted settlement path, so users can withdraw their funds even if the sequencer stops processing.

It also consolidates ZKsync Era and ZKsync OS onto a shared codebase and reduces protocol surface area. This foundational alignment keeps Era and ZKsync OS in a single codebase and streamlines the path for future protocol upgrades.

What changed since ZIP-16

ZIP-16 was approved by the Token Assembly vote in July 2026. Its calldata was never executed, for two reasons:

• During review, the Security Council was made aware of issues in the ZIP-16 calldata that needed to be fixed before deployment.
• Since the vote, ZKsync Era chains have moved to protocol version v0.30.1, while the ZIP-16 calldata expected v0.29. It can no longer be executed as approved.

The calldata in this proposal was regenerated against the current state of Ethereum mainnet. The scope of the upgrade is the same as in ZIP-16. The differences are:

• Fixes from the review. The issues raised during review are fixed in the regenerated calldata. The upgrade contracts it references are deployed on Ethereum and verified on Etherscan. OpenZeppelin reviewed the regenerated calldata; the only change since that review is the Era version label (v0.32.2 → v0.33.0).
• Protocol Upgrade Handler. As in ZIP-16, the upgrade points the Protocol Upgrade Handler at new Security Council, Guardians and Emergency Upgrade Board contracts, the same contracts as in ZIP-16. This now happens in the same call that upgrades the handler, instead of in three separate calls. Stage 0 therefore has 12 calls instead of 15. Stages 1 and 2 contain the same calls as in ZIP-16.
• Compiler. The ZKsync Era bootloader and system contracts are compiled with zksolc 1.5.17 (release notes), with the bootloader adjusted for the newer optimizer (era-contracts #2522).
• Version numbers. See Note on Version Numbering below.

Specification

The implementation can be viewed at tag v31-mainnet of matter-labs/era-contracts.

Priority Mode for ZKsync OS L1-settling chains

Priority Mode is introduced in era-contracts #1943 as a censorship-resistance mechanism for ZKsync OS chains that settle directly to L1. It guarantees that users can withdraw their funds even if the sequencer stops processing.

• This is an opt-in feature, and we do not force ZK Chains to use it in any way.
• Users can submit L1-to-L2 priority transactions the same way they did before.
• The code sets PRIORITY_EXPIRATION = 4 days. If the first unprocessed priority transaction remains outstanding for at least that long, anyone can call activatePriorityMode() on the chain's L1 contract.
• Once activated, batches may contain only priority-queue transactions, and anyone can settle a batch through PermissionlessValidator, which atomically commits, proves, and executes the batch.
• A chain admin can permanently enable Priority Mode for a chain by calling permanentlyAllowPriorityMode.

ZKsync OS Compatibility

The release includes:

• L2 contract restructuring, adapting L2 system contracts to work without constructors or immutables and splitting contracts into L1, L2, and Base variants.
• Custom DA validator removal, moving DA validation to a fixed set of supported commitment options.
• L2 Verifier removal, so the same verifiers are used on both L1 and L2.

Note on Version Numbering

ZKsync Era chains currently run protocol version v0.30.1 and upgrade directly to v0.33.0. ZKsync OS chains upgrade from v0.30.1 to v0.31.2.

Versions v0.31 and v0.32 were used while v31 rolled out on testnet and staging. The Era target is labeled v0.33.0 because our staging environment already runs the same bootloader and system contracts, compiled with zksolc 1.5.17, as v0.33.0, so one version number maps to one bootloader build everywhere.

Rationale

Priority Mode for ZKsync OS L1-settling chains

Priority Mode creates a deterministic censorship fallback for eligible chains. Once the timeout for a queued priority transaction is reached, anyone can move the chain into a mode where only priority transactions are processed and settlement is permissionless, so users retain the ability to exit even if the sequencer is unavailable.

Limiting this mechanism to L1-settling chains reflects the fact that Gateway-settling chains require additional coordination that is not part of the current design.

ZKsync OS Compatibility

The ZKsync OS work removes contract patterns that might make the codebase incompatible with ZKsync OS, effectively keeping Era and ZKsync OS support in the same codebase. Removing custom DA validators and separate L2 verifiers also reduces protocol surface area and eliminates legacy distinctions that are no longer required.

Some smaller changes

• Added the ability for the server to execute the upgrade automatically.
• Removed L2 Verifiers to reuse L1 Verifiers, since they are now the same.
• Continuous improvement of documentation.

Implementation & Backwards Compatibility

The upgrade modifies bootloader logic, L2 system contracts, L1 settlement coordination, and the server-side protocol implementation. While backwards compatibility is maintained for existing ZKsync Chain operations, chains that wish to support the new version must update.

Breaking Changes

1. Era jumps from v0.30.1 to v0.33.0. Tooling that assumes sequential Era mainnet protocol numbers must handle the jump.
2. Node software and external nodes must upgrade to a zksync-era release that supports protocol version v0.33. Batches after the upgrade use commitment-scheme-based pubdata parameters that older external nodes cannot fully deserialize. The minimum zksync-era release is v32.0.0 (zksync-era releases are numbered independently of protocol versions; v32.0.0 is the first that runs protocol v0.33). External node operators must run matterlabs/external-node:v32.0.0-alpha or later before the upgrade executes.
3. Custom DA validators are removed from L2. Chains must migrate to the supported commitment-scheme-based DA options.
4. Legacy SystemContext batch methods now revert. Off-chain systems that still call getBatchHash, getBatchNumberAndTimestamp, currentBlockInfo, getBlockNumberAndTimestamp, or blockHash must be updated before the upgrade.
5. Separate L2 Verifier contracts are removed. Integrations that referenced the old split verifier layout must update.

Security Considerations

The v31 upgrade's trust surface centers on the Priority Mode path, the protocol-version boundary, and the server-side release.

• The Priority Mode path introduces a permissionless activation and settlement mechanism for L1-settling ZKsync OS chains, as specified above. Activation is gated by the priority-transaction expiration window, and once active, batches are restricted to priority-queue transactions.
• Server-side support must remain aligned with the v31 contract set, because batch metadata and pubdata validation semantics change with this upgrade.
• The upgrade calldata was checked against Ethereum mainnet before submission: verification of the calldata against the deployed contracts reports no errors, and the full governance sequence was executed in simulation on a fork of Ethereum mainnet.

Audit

The v31 contracts were audited by OpenZeppelin. The audit report is publicly accessible here.

OpenZeppelin also reviewed the regenerated upgrade calldata in September 2026, at commit 66ad9d57; the only change since is the Era version label (v0.32.2 → v0.33.0). The report leaves one check for after deployment: that the contracts landed at the expected addresses on mainnet. It passed after the contracts were deployed on 6 October 2026.

Changes since the ZIP-16 vote are listed in What changed since ZIP-16 above.

Onchain Actions and Verification

• The onchain proposal is a single proposal on the ZKsync Protocol Governor with three actions, one per upgrade stage (stage 0, 1 and 2). Each action sends an L2→L1 message that carries an upgrade proposal for the Protocol Upgrade Handler on Ethereum.
• Stage 0 has 12 calls, stage 1 has 23 and stage 2 has 7.
• The contracts these calls reference are already deployed on Ethereum and verified on Etherscan.
• The upgrade calldata and its verification tooling are public in matter-labs/era-contracts, in l1-contracts/upgrade-envs/v0.31.0-interopB/output/mainnet. Anyone can check the calldata against the deployed contracts with protocol-ops (protocol_ops ecosystem verify-upgrade); see docs/ecosystem-upgrade-deploy.md.

Estimated time to reach ZKsync Era

Each chain can upgrade at its own pace. As usual, the upgrade start will be primarily time-based and the block height is not known in advance.

Pending a successful governance vote, the tentative time to reach ZKsync Era is the week of October 26th, 2026.