[ZIP-16] V31 Interop Bundles Upgrade

Protocol Development Draft ZIPs
1
Proposal Type ZIP
One Sentence Summary ZIP-16 proposes the v31 upgrade for ZKsync.
Proposal Author Matter Labs
Proposal Sponsor TBC
Date Created April 2026
Version v1
Summary of Action Upgrade ZKsync to v31
Link to Contracts draft-v31 branch

Abstract

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

  • Interop Calls and Bundles, providing infrastructure for native cross-chain token bridging and interactions between ZKsync Chains connected to ZKsync Gateway.

  • Interop Fees, both user and operator space.

  • Support of Stage 1 for ZKsync OS L1-settling chains.

  • Broad ZKsync OS compatibility work across the protocol’s contract layer.

Motivation

ZKsync v31 is a major protocol upgrade that advances three priorities for the Elastic Network;

  • Extending the interoperability foundation laid in v29 by introducing Interop Asset Transfers achievable via new Calls and Bundles functionality. Where v29 introduced interop roots and cross-chain message passing, v31 adds the contracts and accounting required for asset movement between ZKsync Chains connected to ZKsync Gateway. This enables a native bridging path built on the same trust model as the broader interop stack.

  • Introducing Stage 1 Mode for L1-settling ZKsync OS Chains, an escape-hatch mechanism for chains that settle directly to L1. Priority Mode is intended to improve censorship resistance by allowing anyone to activate a restricted settlement path if priority transactions remain unprocessed for too long.

  • Contract-layer work needed for ZKsync OS compatibility. 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. (This rolls the v30 compatibility work into the next Era-facing release rather than requiring a separate mainnet upgrade).

Specification

The implementation of the new protocol version can be viewed on the draft-v31 branch of matter-labs/era-contracts.

Interop Asset Transfers

ZKsync v31 introduces a bundle-based interop system in era-contracts #1491 that enables cross-chain token transfers between ZKsync Chains connected to ZKsync Gateway.

  • A bundle is a group of one or more cross-chain calls (InteropCall structs) sent together from a source chain to a destination chain.

  • Bundles are a flexible structure, allowing asset transfers and arbitrary calls to be sent between chains.

  • Bundles can be chained together. A bundle sent from chain A to chain B may be used to send another bundle to chain C.

  • The process of unbundling allows users to partially execute a subset of bundle calls on the receiving chain.

  • It’s possible to access-control who is able to execute/partially execute (otherwise known as unbundle) bundles.

  • InteropCenter is the user-facing L2 contract for sending bundles. It validates calls, processes indirect calls such as AssetRouter-mediated token transfers, collects fees, and emits the bundle as an L2→L1 message.

  • InteropHandler is the destination-side L2 contract. It verifies bundle inclusion against interop roots and executes the calls atomically, unless the bundle is explicitly unbundled by a designated party.

  • The system implements ERC-7786 for cross-chain message sending and receiving and ERC-7930 for interoperable address encoding.

  • Bundles follow a defined lifecycle: Unreceived, Verified, FullyExecuted, or Unbundled.

  • The asset-tracker contracts track balances across settlement layers. When a bundle is sent, value is debited on the source side; when it is finalized, value is credited on the destination side.

  • BaseTokenHolder (era-contracts #1992) is a new L2 system contract that manages base-token reserves via transfers rather than in-place minting and burning.

There are some limitations in current release:

  • InteropHandler contracts assumes that the recipient of a call implements IERC7786Recipient, meaning it’s not possible to send base token of chain A from any chain X to an EOA (with no delegated code) on chain A via interop. This limitation is going to be lifted in the next release, where system will mature even more.

  • In the current design it’s possible to cancel unexecuted calls in the bundle. However, no refund mechanism is available for any attached funds. We plan to add full “cancelling + refund” route in the next releases.

Interop Fees (era-contracts #1911) adds two fee modes for interop calls (paid by user on bundle send):

  • Dynamic base-token fees, set by the chain operator and denominated in the chain’s base token.

  • Fixed ZK-token fees, with the current draft-v31 code setting the default fixed fee to 10e18, i.e. 10 ZK tokens, per interop call.

  • This is introduced to the system as a censorship-resistant way of paying interop sending fees. The value of the Fixed Fee is not possible to change by operator of the chain, it’s only changeable with protocol upgrade.

Apart from these, there are also settlement fees that are being charged per interop call from chain operators when settling their chains on ZKsync Gateway. These are fixed and changeable by decentralized governance only, the value of settlement fees is denoted in ZK tokens. They are not directly related to users in sense that users are not being charged those, since settlement fees are proportional to total number of interop calls on chain → users have direct influence on total fee amount.

TBD Base Token Holder

Stage 1 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.

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

  • Chain admin can permanently enable Priority Mode for a chain by calling permanentlyAllowPriorityMode if the chain wants to be Stage 1.

  • L1-to-L2 transactions can now spend base tokens from the sender’s L2 balance, not only from the amount deposited in the same L1 transaction.

Governance Upgrade Delay. The governance-side work in zk-governance #32 would change UPGRADE_DELAY_PERIOD from 1 day to 5 days. Combined with the existing 3-day legal veto period, this would create an 8-day governance delay window. The existing soft-freeze period remains 12 hours.

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 alongside its interop changes. 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.

  • L1 DA validator support for ZKsync OS.

  • In ZKsync OS system contracts are proxies now (Note, that it’s not the case for ZKsync Era, things remain the same as before there), meaning that we will not force-deploy contracts on the same address (effectively changing the existing bytecode), but instead just update the implementation.

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

Interop Asset Transfers

The bundle-based design extends v29’s interop-root mechanism to having an asset-transfer functionality without introducing a separate trust model. Bundles provide a single verifiable unit for multi-step cross-chain function calls, while still allowing designated unbundling where partial execution is acceptable.

Asset transfers are secured with a bulkhead mechanism in AssetTracker contracts (similar to how NativeTokenVault’s bulkhead design operated before). Look here for technical explanation of the introduced mechanisms.

The dual-fee model separates operator-controlled base-token pricing from a fixed ZK-token path. This is important for chains that want a bounded, protocol-defined alternative to operator-set pricing and general censorship-resistance characteristics.

The BaseTokenHolder pattern replaces in-place minting and burning with explicit reserve management. This aligns the system with more standard token semantics and improves compatibility with external tooling.

Stage 1 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 (via a permissionless mechanism) can move the chain into a mode where only priority transactions are processed and settlement is permissionless.

Restricting permanent Priority Mode enablement to ZKsync OS chains reflects the current proving and settlement assumptions of the implementation. Restricting it to L1-settling chains reflects the fact that Gateway-settling chains require additional coordination that is not yet 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 an ability for server to execute upgrade automatically.

  • Tightened up security trust assumptions for Gateway.

  • Removed L2 Verifiers to reuse L1 Verifiers, since they are the same now.

  • 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 new features must update to the new version.

Breaking Changes

  1. Era skips protocol version 30. Tooling that assumes sequential Era mainnet protocol numbers must handle a direct upgrade from v29 to v31.

  2. Node software and external nodes must upgrade to a v31-compatible zksync-era. Protocol version 31 maps to VmMediumInterop, and v31 batches use commitment-scheme-based pubdata parameters that older external nodes cannot fully deserialize.

  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.

  6. L1-to-L2 base-token semantics change. A transaction may spend the sender’s existing L2 balance rather than only the amount deposited in the same request.

  7. Gateway restricts dangerous deployment contracts. The ZKsync OS deterministic deployment proxy is whitelisted-only on Gateway, and future dangerous contracts may be added through the same mechanism.

Security Considerations

The v31 upgrade introduces new trust surfaces in the interop layer, the Priority Mode path, the Gateway filterer, and the governance-side release boundary.

  • Interop bundle verification is performed through the existing system introduced in v29 using Merkle proofs against interop roots and is cross-checked during settlement.

  • Migration interval tracking ensures that message proofs are checked against the correct historical settlement layer.

  • Server-side support must remain aligned with the v31 contract set because batch metadata and pubdata validation semantics change at protocol version 31.

Audit Summary

TODO_FINAL(Audit Summary — add the public OpenZeppelin reports for the v31 audit once published.)

Post-audit Changes

TODO_FINAL(Post-audit changes — list the merged changes after the final public audit reports are published and fixes are finalized.)

Proposal Review Call April 29th