| Proposal Type | ZIP |
|---|---|
| One Sentence Summary | ZIP-16 proposes the v31 upgrade for ZKsync. |
| Proposal Author | Matter Labs |
| Proposal Sponsor | Matter Labs |
| Date Created | July 2026 |
| Version | v2 |
| Summary of Action | Upgrade ZKsync to v31 |
| Link to Contracts | draft-v31 branch |
This is the current, rescoped v31 proposal. It supersedes the original ZIP-16 draft, which is deprecated and retained for reference: https://forum.zknation.io/t/zip-16-v31-interop-bundles-upgrade/979
Abstract
ZIP-16 proposes the v31 protocol upgrade for ZKsync. 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.
- A direct Era upgrade path from v29 to v31.
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. Protocol version 30 was used for ZKsync OS chains and was not deployed to Era mainnet, so Era chains upgrade directly from v29 to v31, rolling the v30 compatibility work into the next Era-facing release rather than requiring a separate mainnet upgrade. This foundational alignment keeps Era and ZKsync OS in a single codebase and streamlines the path for future protocol upgrades.
Specification
The implementation of the new protocol version can be viewed on the release-v31 branch 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 current release-v31 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
Because protocol version 30 was reserved for ZKsync OS and was not deployed to Era mainnet, v31 incorporates the v30 compatibility work. 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
Protocol version 30 was assigned to ZKsync OS chains and was not deployed to Era mainnet. Era chains therefore upgrade directly from v29 to v31.
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
- Era skips protocol version 30. Tooling that assumes sequential Era mainnet protocol numbers must handle a direct upgrade from v29 to v31.
- Node software and external nodes must upgrade to a v31-compatible zksync-era. v31 batches use commitment-scheme-based pubdata parameters that older external nodes cannot fully deserialize.
- Custom DA validators are removed from L2. Chains must migrate to the supported commitment-scheme-based DA options.
- Legacy SystemContext batch methods now revert. Off-chain systems that still call getBatchHash, getBatchNumberAndTimestamp, currentBlockInfo, getBlockNumberAndTimestamp, or blockHash must be updated before the upgrade.
- 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 at protocol version 31.
Audit
The v31 contracts were audited by OpenZeppelin. The audit report is publicly accessible here:
https://github.com/matter-labs/era-contracts/blob/draft-v31/audits/v.31%20Interop%20Audit%20(OpenZeppelin).pdf
Any minor fixes applied after the audit are noted in this post.
Estimated time to reach ZKsync Era
Each chain can upgrade at its own pace. Submission and vote timing will be confirmed when voting opens. We will update this section with confirmed dates before the proposal is submitted onchain. As usual, the upgrade start will be primarily time-based and the blockheight is not known in advance.