[ZIP-16] ZKsync v31 Upgrade

Abstract

ZIP-16 proposes the ZKsync v31 protocol upgrade. The release includes:

• Priority Mode for ZKsync OS chains settling directly on L1, providing users with a permissionless withdrawal path if the sequencer stops processing transactions.
• Protocol-contract compatibility improvements for ZKsync OS.
• A direct upgrade path for ZKsync Era from protocol version 29 to version 31.

Motivation

Version 31 advances two major protocol priorities.

First, it introduces Priority Mode for ZKsync OS chains that settle directly on Ethereum. If priority transactions remain unprocessed beyond a defined expiration period, anyone may activate a restricted settlement path. This ensures that users retain a way to withdraw their funds when the sequencer is unavailable or censoring transactions.

Second, the release brings ZKsync Era and ZKsync OS closer to a shared protocol codebase. Protocol version 30 was used for ZKsync OS chains but was not deployed to Era mainnet. Era therefore upgrades directly from v29 to v31, incorporating the relevant compatibility work without requiring an intermediate mainnet upgrade.

Specification

The implementation of the new protocol version is available in the draft-v31 branch of matter-labs/era-contracts.

Priority Mode for ZKsync OS L1-settling chains

Priority Mode is introduced as a censorship-resistance mechanism for ZKsync OS chains that settle directly on L1.

• The feature is optional. ZK Chains are not required to enable it.
• Users continue submitting L1-to-L2 priority transactions through the existing flow.
• The current v31 implementation sets PRIORITY_EXPIRATION to four days.
• If the oldest unprocessed priority transaction exceeds that period, anyone may call activatePriorityMode() on the chain’s L1 contract.
• While Priority Mode is active, batches may contain only transactions from the priority queue.
• Anyone may settle an eligible batch through PermissionlessValidator, which commits, proves, and executes it atomically.
• A chain administrator may permanently permit Priority Mode by calling permanentlyAllowPriorityMode.

ZKsync OS Compatibility

Because protocol version 30 was assigned to ZKsync OS and was not deployed to Era mainnet, v31 incorporates the relevant compatibility work.

The release includes:

• Restructuring L2 system contracts so they can operate without constructors or immutable variables, with contracts separated into L1, L2, and base variants.
• Removing custom DA validators in favor of a fixed set of supported commitment options.
• Removing separate L2 verifier contracts so the same verifier architecture can be used across L1 and L2.

Note on Version Numbering

Protocol version 30 was used for ZKsync OS chains but was not deployed to ZKsync Era mainnet. Era chains therefore upgrade directly from protocol version 29 to protocol version 31.

Rationale

Priority Mode for ZKsync OS L1-settling chains

Priority Mode establishes a deterministic censorship-resistance fallback.

After a queued priority transaction reaches its expiration threshold, anyone can transition an eligible chain into a restricted mode in which only priority transactions are processed and settlement becomes permissionless. This preserves users’ ability to exit even when the sequencer is unavailable.

The mechanism is limited to chains settling directly on L1. Chains settling through Gateway require additional coordination that is outside the scope of this release.

ZKsync OS Compatibility

The ZKsync OS compatibility work removes contract patterns that could prevent the protocol from operating consistently across Era and ZKsync OS.

It also reduces protocol complexity by removing custom DA validators and the legacy separation between L1 and L2 verifier contracts.

Some smaller changes

• Added support for automatically executing the upgrade through the server.
• Removed redundant L2 verifier contracts and reused the corresponding L1 verifiers.
• Continued improving protocol documentation.

Implementation & Backwards Compatibility

The upgrade changes bootloader behavior, L2 system contracts, L1 settlement coordination, and the server-side protocol implementation.

Existing ZKsync Chain operations remain supported, but chains that intend to adopt protocol version 31 must update their software and integrations.

Breaking Changes

1. Era skips protocol version 30. Tooling that assumes sequential Era protocol-version numbers must support a direct transition from v29 to v31.
2. Nodes must support v31. Node operators and external-node operators must deploy a v31-compatible version of zksync-era. Older external nodes cannot fully deserialize the new commitment-scheme-based pubdata parameters.
3. Custom DA validators are removed. Chains using custom L2 DA validators must migrate to the supported commitment-scheme-based DA configurations.
4. Legacy SystemContext batch methods revert. Off-chain systems must stop using the following legacy methods before the upgrade:
   • getBatchHash
   • getBatchNumberAndTimestamp
   • currentBlockInfo
   • getBlockNumberAndTimestamp
   • blockHash
5. Separate L2 verifier contracts are removed. Integrations relying on the previous split-verifier architecture must be updated.

Security Considerations

The primary security considerations concern the Priority Mode execution path, the protocol-version transition, and alignment between the server release and the v31 contracts.

• Permissionless Priority Mode activation is available only after the priority-transaction expiration threshold is reached.
• Once Priority Mode is active, batches are restricted to transactions from the priority queue.
• Server-side support must remain synchronized with the v31 contract set because batch metadata and pubdata-validation semantics change at protocol version 31.

Audit

The v31 contracts were audited by OpenZeppelin.

The audit report is available here:

OpenZeppelin v31 audit report

After the audit was completed, additional changes were applied to the contracts during internal testing and to reflect the reduced scope of the final proposal. The full set of post-audit changes is available in the following comparison.

The contract changes were:

• Updates to L1AssetTracker that allow users to continue finalizing withdrawals after the ecosystem has been upgraded to v31 but before individual chains have completed their own upgrades. This reduces pressure on chains to upgrade immediately and lowers the coordination overhead associated with the ecosystem-wide upgrade.
• A minor bug fix in L2AssetTracker that affected withdrawals during upgrades.
• Removal of an unused variable from L2MessageRoot.

Estimated time to reach ZKsync Era

Each chain may upgrade according to its own schedule.

The upgrade activation is expected to be primarily time-based, so the relevant block height may not be known in advance. The actual release date is heavily influenced by the voting process. If the proposal is approved and executed on L1 in 21 days, the expected time to reach ZKsync Era is the 4th of August.