[ZIP-12] V29 Interop Messaging

Protocol Development Archived ZIPs
1
Proposal Type ZIP
One Sentence Summary: ZIP-12 proposes the V29 upgrade for ZKsync.
Proposal Author Matter Labs
Proposal Sponsor: Cyfrin
Date Created: 2025-09-26
Version v1
Summary of Action ZIP-12 proposes the V29 upgrade for ZKsync which introduces interop messaging for ZKsync Chains
Link to contracts GitHub - matter-labs/era-contracts at draft-v29

Abstract

ZIP-12 proposes the v29 protocol upgrade for ZKsync, introducing Interop Messaging, that will enable native message passing between ZKsync Chains.

Motivation

ZKsync v29 upgrades the protocol to improve interoperability for ZKsync Chains within the Elastic Network. It introduces cross-chain communication, via the Interop Messaging mechanism that allows ZKsync Chains to share and store commitment roots from peer chains via the ZKsync Gateway, enabling Merkle-proof-based verification of cross-chain messages. This enables trustless, low-fee communication between ZKsync Chains.

These improvements align with ZKsync’s mission of building a scalable, user-centric Ethereum ecosystem.

Specification

The implementation of the new protocol version can be viewed on GitHub.

Interop Messaging

ZKsync v29 introduces a mechanism for chains connected to ZKsync Gateway to communicate with each other through a shared root commitment system, which is already present in v28, but was used only for L2→L1 communication for chains that are connected to ZKsync Gateway.

  • Each ZKChain appends a new batch leaf to its chainTree, resulting in a new chainRoot.
  • The updated chainRoot modifies the corresponding leaf in the global sharedTree, resulting in a new interop root.
  • The final sharedTree root is emitted in a NewInteropRoot event.
  • Operators of ZKsync Chains must feed these new interop roots into the bootloader of each chain, which stores them in L2InteropRootStorage.
  • Merkle proofs against these roots can be used to verify cross-ZKChain messages.

Code improvements

  • Bridgehub’s functionality responsible for connecting the chain to either ZKsync Gateway or L1 has been moved into a separate contract called ChainAssetHandler.
  • ValidatorTimelock has been updated to an upgradeable version controlled by the ZKsync Governance and has been changed to support different roles for commit, prove, execute and revert.
  • EcPairing precompile has been updated so that reverting and returning false are now consistent with EIP-197, improving EVM equivalence.

Note on Fast Finality

The audit mentions the support of the fast finality feature. This feature would allow for faster subjective finality for chains that are connected to ZKsync Gateway.

While the release still contains the contract support for the feature, the server integration has been deprioritized in favor of ZIP-13 and ensuring faster delivery for ZKsync OS in general.

Rationale

Interop Messaging

The Interop Messaging design in v29 enables secure message-passing between ZKsync Chains connected to ZKsync Gateway, establishing the foundation for advanced interoperability features like asset transfers and cross-chain contract calls. This approach supports ZKsync’s strategy of continuous, incremental upgrades, delivering immediate functionality while paving the way for future capabilities.

The specified design ensures that the interop is secure, while scalable, since all messages from all chains are aggregated into one root. By importing this single global root, a ZKsync Chain can validate messages coming from the entire Elastic Network.

Also, in the proposed design L2<>L2 messages reuse the same approach as the one that was used for L2→L1 messages, allowing ZKsync Chains to take advantage of the existing battle-tested codebase and providing better compatibility with the existing tooling.

Code improvements

Refactoring of Bridgehub allowed maintaining small code size and facilitated separation of concerns.

Making ValidatorTimelock an upgradeable contract allows for adding new features in the releases without changing the address, while making its validator permissions separate for commit/prove/execute/reverts opens doors for more advanced setups for batch settlement permissions.

Implementation & Backward Compatibility

The upgrade modifies bootloader logic, L2 storage contracts, and L1 settlement coordination logic. While backward compatibility is maintained for existing ZKsync Chain operations, chains that wish to support interoperability must update to the new version.

In this release, interoperability is available only for chains that are connected to ZKsync Gateway. As such, upgrading ZKsync Gateway to the v29 will be a prerequisite for the support of this feature.

Breaking changes

Most of the functionality remains compatible with the previous versions. However, some changes were introduced, mainly related to the code improvements efforts.

  1. Since the chain migration logic will move to ChainAssetHandler, once the ecosystem is upgraded to v29, only chains that have upgraded to the new version can change their settlement layer.
  2. To ensure backward compatibility and smooth upgrade, the current validatorTimelock() getter of the ChainTypeManager contract will return the address of the old validator timelock. To obtain the address of the new validator timelock, please use the new validatorTimelockPostV29() getter.

Also note, that since the ValidatorTimelock changes, the permissions for the current validators will have to be reinstalled for the new timelock by each ZKsync Chain separately. The Matter Labs team will provide the community with the tooling that ensures easy upgrade process for all ZKsync Chains.

Security Considerations

The v29 upgrade introduces new trust surfaces and bootloader logic. Key security considerations:

  • Interop root validation is performed inside the system contracts and cross-checked during settlement.
  • All interop roots and rolling hashes are subject to validation and must match expected data.

All major risks were reviewed and resolved through external audits.

Audit Summary

The v29 upgrade was audited by OpenZeppelin from May 20 to June 26, 2025. The audit covered all changed components, including bootloader changes, smart contracts, and L1/L2 integration. All findings were addressed before deployment. The audit report can be seen here.

Post-audit changes

The diff between the audited commit and the deployed one can be seen here. While it mostly contains changes to files out of the audit scope (scripts, CI workflows, etc.). It contains some minor changes to the contracts in scope for the audit to either make the upgrade process simpler or make it more future compatible with ZIP-13. These changes include:

  • Adding a getter in L2NativeTokenVault.
  • Some functions needed to conduct the upgrade properly in Bridgehub, CTMDeploymentTracker, ChainAssetHandler.
  • In ChainAssetHandler the restrictions were added to ensure that chains can only migrate to ZKsync Gateway only if they belong to the same ChainTypeManager. It will ensure that ZKsync OS chains cannot migrate on top of Era-based ZKsync Gateway to help isolate them from the rest of the network while their upgradeability is not controlled by the Governance yet.
  • In MessageRoot we added additional assurances that chains that settle on L1 cannot append batches to the global MessageRoot. This used to be enforced inside the implementation of each chain, but to allow ZIP-13, we had to ensure it on the ecosystem level.
  • Added validatorTimelockPostV29 variable to ChainTypeManager to ensure smoother upgrades.
  • Various additional cleanups to ensure easier integration with the server.

ZARP Approval

This ZIP includes calldata to grant the necessary permissions for audit reimbursements under the ZIP Audit Reimbursement Program (ZARP), passed in TPP-3, for both ZIP-11 and ZIP-12.

Child Capped Minters:

ZIP-11 child minter: 0x0455e47Ae27A20E026e69D69c4687d8e3F4ce635

  • Cap: 5,405,720 ZK / $270,286 USD at 5c

ZIP-12 child minter: 0xA790EF548B27aC62D36Cdc86979e8F606CC8850a

  • Cap: 5,200,000 ZK / $260,000 USD at 5c

Calldata Operation:

Grant MINTER role on ZarpMain to ZIP-11 and ZIP-12 child capped minters

These permissions enable the reimbursement of third-party audit costs incurred by the developer of the upgrade, which in this case is Matter Labs, upon successful execution of ZIP-12.

Estimated time to reach ZKsync Era

While each chain can decide to upgrade at its own pace, the upgrade is expected to reach ZKsync Era on Oct 22th at ~8:30 UTC. Note that, as usual, the blockheight is not known and the upgrade start will be primarily time-based.

3 Likes
2

Hello @StanislavBreadless
According to your post, the mainnet upgrade was supposed to be today. However, there is no voting yet. I believe there are some delays. When should we expect the proposal to go live on Tally as well as the upgrade to be done?

3

Hey @Demacia! I am really sorry for the late reply :frowning:

It was decided that before we publish ZIP12 to Tally, we’d make it more future compatible with upcoming upgrades (including ZIP13) as well as to harden some internal processes to ensure more secure and straightforward upgrade generation. We expect the vote to start in the upcoming days, either today or next Monday.

2 Likes
4

To clarify, I believe @StanislavBreadless means ZIP-12 will be submitted onchain within the coming days - voting starts only after the 3 day voting delay from the point the proposal is submitted onchain.

See an overview of the proposal process for ZIPs here.

3 Likes
5

Yes, thank you @theshelb!

1 Like
6

I updated the post to align with the Tally vote page

7

ZIP12 has been successfully executed!

It involved 3 transactions on L1:

2 Likes