Protocol Upgrade v31: Priority Mode & ZKsync OS Compatibility

[sarahschwartz]

The protocol upgrade for v29 is live on ZKsync Chains, and next up is the v31 upgrade.
Below is a breakdown of what's included in v31 and how the upgrade will be rolled out.

ℹ️ Note on version numbering: protocol version 30 was used for ZKsync OS chains and was not deployed to ZKsync Era mainnet. Era chains therefore upgrade directly from v29 to v31.

Key Features

Priority Mode for ZKsync OS L1-settling chains

Priority Mode is a censorship-resistance mechanism for ZKsync OS chains that settle directly on L1. It guarantees that users can withdraw their funds even if the sequencer stops processing transactions.

Here's how it works:

• Priority Mode is an opt-in feature. 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

The second key feature of the v31 upgrade brings ZKsync Era and ZKsync OS closer to a shared protocol codebase. Because protocol version 30 was assigned to ZKsync OS and was not deployed to Era mainnet, v31 incorporates the relevant compatibility work:

• 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.

Other Changes

1. Added support for automatically executing the upgrade through the server.
2. Removed redundant L2 verifier contracts and reused the corresponding L1 verifiers.
3. Continued improvements to protocol documentation.

Breaking Changes

Existing ZKsync Chain operations remain supported, but chains that intend to adopt v31 must update their software and integrations:

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 (deprecated in v29):
   • getBatchHash
   • getBatchNumberAndTimestamp
   • currentBlockInfo
   • getBlockNumberAndTimestamp
   • blockHash
5. Separate L2 verifier contracts are removed. Integrations relying on the previous split-verifier architecture must be updated.

Audit

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

---

Upgrade Timeline

⚠️ All dates below are estimates and may shift. This rollout follows the ZK Nation upgrade process. Each chain may upgrade according to its own schedule, and the upgrade activation is expected to be primarily time-based, so the relevant block height may not be known in advance.

Date	Milestone
✅ July 13	On-chain proposal + voting begins.
August 13 (~12 pm CET)	ZKsync Era mainnet upgraded to v31 (pending a successful governance vote). Other ZKsync chains may upgrade at this stage.

📢 Progress and announcements will be posted on @ZKsyncDevs on X

---

More details about this protocol upgrade can be found in the ZIP-16 proposal.