[ZIP-6] Prepare ZKsync for ZK Gateway

StanislavBreadless · January 29, 2025, 3:48pm

Title	Prepare ZKsync for ZK Gateway
Proposal Type	ZIP
One Sentence Summary:	This proposal aims to upgrade ZKsync protocol features essential for compatibility with the forthcoming ZK Gateway, alongside other enhancements to empower ZK Chains and developers.
Proposal Author	Matter Labs
Proposal Sponsor:	TBC
Date Created:	TBC
Version	v1
Summary of Action	To be updated
Link to contracts	GitHub - matter-labs/era-contracts at release-v26

Summary

This proposal seeks to prepare the ZKsync protocol for the upcoming ZK Gateway upgrade. ZK Gateway is slated for future deployment through a separate governance vote. This upgrade aims to align ZKsync’s existing contracts with ZK Gateway’s requirements, ensuring a seamless integration process and reducing the complexity of the upgrade to deploy ZK Gateway. Additionally, this proposal introduces enhancements to support custom Data Availability (DA) and bridge development, fostering greater flexibility for ZK Chains and developers.

Abstract

The primary objective of this proposal is to upgrade the ZKsync protocol by improving aspects of the ZKsync protocol required for compatibility with the ZK Gateway upgrade. ZK Gateway is a middleware component that provides proof aggregation across ZK Chains and will enable fast interoperability in future upgrades. The upgrade to deploy ZK Gateway is expected to be submitted to the Token Assembly for a vote in the coming months. This proposal serves as a foundational step to align ZKsync’s existing contracts with the new ZK Gateway requirements, facilitating a smooth upgrade process for the deployment of ZK Gateway. The changes focus on streamlining the upgrade processes, adjusting lifecycle management for contract migrations, and introducing robust protocols for handling contract transitions effectively.

As well as the improvements mentioned, this upgrade also contains features that are not related to ZK Gateway, including: easier-to-use interfaces for developing custom bridges on top of ZK chains, support of custom DA as well as easier upgrading and deployment of new ZK chains.

Motivation

The motivations for this proposal are:

Risk Mitigation and Simplified Upgrade Path for ZK Gateway: Proactively updating the ZKsync infrastructure to align with the ZK Gateway’s requirements reduces the risk of complications during the ZK Gateway’s future rollout. Separating the protocol changes from the actual deployment of the Gateway itself minimizes the complexity of the upgrade process. This proposal focuses only on the necessary protocol changes to enable the future integration of the ZK Gateway, with the deployment of the ZK Gateway to be addressed in a subsequent ZIP.
Custom Data Availability (DA) Solutions: An integral component of this proposal involves introducing features that empower ZK chain administrators and developers with more control and flexibility. Enabling custom DA solutions is pivotal for catering to the specific needs of different chains and ensuring the long-term success of the Elastic Network. This update ensures that developers and administrators of ZK Chains are equipped with the tools necessary to optimize their operations within the Elastic Network effectively.

Specification

Prepare ZKsync for ZK Gateway

Custom Settlement Layers: Prepare the infrastructure necessary to support custom settlement layers for future deployments. This will allow ZK Chains within the Elastic Network to use ZK Gateway (once deployed) as their custom settlement layer, enabling future rapid proof aggregation and seamless cross-chain interoperability.

Additional Features

Custom Data Availability Layer Support: Introduce support for custom data availability layers, enabling each ZK Chain within the Elastic Network to manage its data availability requirements efficiently and autonomously.
Bridging Architecture Enhancements: Implement changes that simplify the creation of bridges for assets with unique behaviors, facilitating smoother asset transfers between L1 and L2.
Easier upgrade and more trustless deployment of chains: As a result of the new bridging architecture, the standard bridging contracts, which include L2AssetRouter and L2NativeTokenVault, are now deployed upon genesis. After this upgrade, ZK Chains can rely less on the correctness of the manual initialization process. The upgrade flow for ZKsync governance will also be improved. Currently the Protocol Governor needs to upgrade a shared bridge on each separate ZK Chain. After this upgrade, this action will be automatically included as part of a protocol upgrade.

Full documentation related to the contracts for this version can be read in this repo: era-contracts/docs at release-v26 · matter-labs/era-contracts · GitHub.

Support for custom settlement layers

This release adds all the necessary functionality to deploy settlement layers and allow ZK Chains to migrate on top of them. In the future, the ZK Gateway settlement layer will be introduced and ZK Chains will be able to utilize it for cheaper batch processing and faster native interoperability.

Please note, this upgrade does not include actual deployment of a settlement layer. This will require a separate governance vote in the future.

You can read more about how settlement layers work in this Github repo: era-contracts/docs/gateway/overview.md at release-v26 · matter-labs/era-contracts · GitHub

Custom DA layer support

Previously for all ZK Chains either Rollup or Validium DA layers were supported. Now the admin of each ZK Chain can select which DA layer to use.

As an additional security feature, we also introduced a permanentRollup mode, which allows a chain to become a rollup forever, excluding a possibility for a malicious admin to change the way the data availability is published for a ZK Chain. This will be the mode that ZKsync Era will use.

Soon after this upgrade is completed, the corresponding tooling will be provided. For those who are curious about how the functionality is implemented at a deeper level, you can check out this documentation: era-contracts/docs/gateway/gateway_da.md at release-v26 · matter-labs/era-contracts · GitHub

Changes to bridging architecture

Previously, all deposits of tokens went through the L1SharedBridge which sends messages to its L2 counterpart, that is responsible for the creation of the corresponding “bridged” versions of tokens. This contract also has the role of the vault for the assets.

This design makes it harder to develop a custom bridging mechanism. If someone wanted to create their own bridge, they would have to reimplement a lot of boilerplate and constantly keep themselves up-to-date with future features.

To make this process simpler, the bridging architecture has been updated:

The main contract will be called L1AssetRouter which interacts with its L2 counterpart. The L1AssetRouter will not hold the L1 tokens, but will serve as a central point of bridging communication between chains.
Instead of operating on token addresses, bridges will start operating on future-proof “asset ids”, which encode the asset origin id, as well as the contract that can define the canonical bridging contract for each chain. This contract that defines the correct way to bridge an asset is called “Asset deployment tracker”. On each chain, a separate “Asset handler” contract can be deployed to ensure that the bridging process is done as expected.
The default asset deployment tracker will be “native token vault”. It is represented by the L1NativeTokenVault on L1 and the L2NativeTokenVault on L2. The L1 contract will be where the funds are stored.
Note, that before, the L2SharedBridge had to be separately deployed after the creation of the chain. The new contracts (L2AssetRouter, L2NativeTokenVault, etc) will be pre-deployed. This will ensure easier upgrades for those contracts in the future. As a result, new ZK Chains will experience an easier flow of creation.
The old L1SharedBridge will NOT be upgraded to the L1AssetRouter or L1NativeTokenVault, but will be upgraded to the L1Nullifier contract that will be responsible for bookkeeping executed bridging operations. Thus, this upgrade will require migration of funds to the L1NativeTokenVault .

Detailed documentation on asset router and bridging

github.com

matter-labs/era-contracts/blob/release-v26/docs/bridging/asset_router/overview.md

# Overview of Custom Asset Bridging with the Asset Router

[back to readme](../../README.md)

Bridges are completely separate contracts from the ZKChains and system contracts. They are a wrapper for L1 <-> L2 communication on both L1 and L2. Upon locking assets on one layer, a request is sent to mint these bridged assets on the other layer.
Upon burning assets on one layer, a request is sent to unlock them on the other.

Custom asset bridging is a new bridging model that allows to:

1. Minimize the effort needed by custom tokens to be able to become part of the elastic chain ecosystem. Before, each custom token would have to build its own bridge, but now just custom asset deployment trackers / asset handler is needed. This is achieved by building a modular bridge which separates the logic of L1<>L2 messaging from the holding of the asset.
2. Unify the interfaces between L1 and L2 bridge contracts, paving the way for easy cross chain bridging. It will especially become valuable once interop is enabled.

#### New concepts

- assetId => identifier to track bridged assets across chains. This is used to link messages to specific asset handlers in the AssetRouters.
- AssetHandler => contract that manages liquidity (burns/mints, locks/unlocks, etc.) for specific token (or a set of them) on a chain. Every asset
- AssetDeploymentTracker => contract that manages the deployment of asset handlers across chains. This is the contract that registers these asset handlers in the AssetRouters.

### Normal flow

This file has been truncated. show original

Additional differences

Additional differences to the previous protocol version can be viewed here:

github.com

matter-labs/era-contracts/blob/release-v26/docs/upgrade_history/gateway_upgrade/gateway_diff_review.md

# Gateway upgrade changes

## Introduction & prerequisites

[back to readme](../../README.md)

This document assumes that the reader has general knowledge of how ZKsync Era works and how our ecosystem used to be like at the moment of shared bridge in general.

To read the documentation about the current system, you can read [here](../../README.md).

For more info about the previous one, you can reach out to the following documentation:

[Code4rena Documentation Smart contract Section](https://github.com/code-423n4/2024-03-zksync/tree/main/docs/Smart%20contract%20Section)

## Changes from the shared bridge design

This section contains some of the important changes that happened since the shared bridge release in June. This section may not be fully complete and additional information will be provided in the sections that cover specific topics.

### Bridgehub now has chainId → address mapping

This file has been truncated. show original

ZIP-X Upgrade Process

The upgrade process is described in detail here:

https://github.com/matter-labs/era-contracts/blob/release-v26/docs/upgrade_history/gateway_upgrade/upgrade_process (no gateway chain).md

From the ZK Chains perspective:

Step 1: publishing of the upgrade data to the ChainTypeManager. After this step, the new protocol version will get published to the ChainTypeManager. This will not affect ZK Chains functionality in any way, but each ZK chain will have 2 weeks to upgrade itself to the new protocol version. The necessary instructions are expected to be relatively straightforward and will be provided in a timely manner.
Once a ZK Chain is upgraded, it will already have the new L2 contracts. These contracts will already support bridging of L2 tokens to L1. After this step, the L1 bridging contracts will not be upgraded. As a result, it is not possible to finalize withdrawals of L2-native tokens until the L1 bridging contracts are upgraded, which is covered in Step 2.
All else (including withdrawals of the L1-native tokens) will work as usual.
Step 2: finalization of the upgrade on L1. After the upgrade deadline has passed, the ZK Chains that have not yet upgraded, would stop from being able to publish new batches. For those ZK Chains that did migrate on time, no further action is needed.

Note however, immidiately after step 2 finalization is complete, ZK Chains — as well as their base tokens and bridging balances in general, need to be migrated to the new contracts. This can be done trustlessly by any wallet. The team that prepared the upgrade will do this for the entire network, which may take several minutes. As a result, this effectively means there will be several minutes of deposits not working for ZK chains while this upgrade takes place.

Rationale

This ZIP focuses only on the preparation of the Elastic Network for the future deployment of Gateway. The limited scope was chosen to keep the upgrade simpler. The Gateway chain would facilitate future proof aggregation and seamless interoperability between ZK chains.

Additional features such as custom data availability support, more generic bridging give ZK chains and developers more flexibility when working with the Elastic Network.

Backwards Compatibility

Due to renames for better readability (e.g. “hyperchain → ZK chain”, “StateTransitionManager → ChainTypeManager”), several getters on the contracts that were considered to be used rarely were deleted.

The existing SDKs will continue working for the old use-cases: depositing and withdrawing assets native to L1 on top of chains that were deployed before this upgrade.

However new use-cases:

Depositing and withdrawing assets native to L2
Any bridging for chains that were deployed after this upgrade

Would require a new SDK. The version of the new zksync-ethers SDK will be provided soon. Note, that this new SDK will not be compatible with chains that have not yet upgraded. Thus, with regard to the SDK, the upgrade should be done in the following order:

Firstly upgrade the chain
Then recommend the front-ends to migrate to the new SDK to support the new capabilities.

Security Considerations

This upgrade introduces a lot of changes in several places and so it went through extensive external and internal security audits. The links to audits will be provided soon.

StanislavBreadless · January 29, 2025, 3:57pm

The links to audits, the new SDK version, as well as the expected timelines will be added soon

admin · February 12, 2025, 5:49am

This proposal is now onchain. Voting starts in 7 days.
Link — Tally | ZKsync | Prepare ZKsync for ZK Gateway

admin · February 19, 2025, 10:29am

The voting period for ZIP-6 is live. Delegates can vote on Tally.

Curia · February 20, 2025, 3:51pm

This proposal is a big step forward in realizing our elastic chain vision and achieving seamless interoperability. we will support this proposal to pave the way for a more flexible and scalable ecosystem.

ibollanos · February 21, 2025, 3:16pm

Given the context (audit reports and documentation) and our checks on the proposal’s calldata, the proposal appears fine to Dedaub

DanielM · February 21, 2025, 6:30pm

So, I voted for this proposal. I think It makes upgrades easier, improves how assets move between chains, and gives developers more tools to build on ZKsync. I don’t see any arguments against it

smolphil · February 24, 2025, 3:28pm

The TDC is in full support of ZIP-6. We don’t see any downsides to the proposal, yet many upsides – like, lowering gas costs, speeding up transaction finality, and enabling seamless interoperability across chains. Custom DA, bridge development and easier upgrading and deployment of new ZK chains are also a big plus.

Sinkas · February 25, 2025, 6:06pm

The following reflects the views of L2BEAT’s governance team, composed of @kaereste and @Sinkas. It’s based on their combined research, fact-checking, and ideation.

We are voting FOR the proposal.

Our research team verified the proposed calldata using Matter Labs’ verification tool. They sampled some of the contracts’ source code that is already deployed on L1, which was discovered using the tool and the proposed calldata. Finally, scanning the 4 OpenZeppelin audits and the docs on GitHub and putting it into a bigger context, this proposal sets the stage for the ‘Gateway’ settlement Rollup and ZK chains like Era migrating to Layer 3. To make it clear, this proposal doesn’t migrate chains like Era to Layer 3, but it’s the first step towards enabling that migration in the future.

During the review, our research team found the following things that delegates should be aware of.

1. Data Availability (DA) switching post-deployment

Right now, and before the proposed upgrade executes, ZK stack chains must choose where they post their data as soon as they create their chain. After the proposed upgrade, ZK stack chains will be able to change their DA at any time, which would instantly affect the trust assumptions.

Since ZK Rollups can only worsen their trust assumptions when changing their DA, a ‘permanent-rollup’ mode is introduced that permanently fixes the DA Layer to Ethereum for any Rollup that opts in, as ZKsync Era committed to do. The implementation in the proposal allows immediate DA changes by the local chain admin, which is incompatible with Stage 1 Rollups (see L2BEAT’s Stages Framework for reference). We therefore urge teams aiming to build a decentralized Rollup to use the ‘permanent-rollup’ mode.

2. Shared Bridge to Asset Routers and Handlers

Currently, all canonical tokens get the same contract implementations on L2 and are kept in a shared bridge on L1. The proposal splits bridging logic into a few contracts.

Assets must specify a handler (escrow) and receive a unique token ID upon registration.
Each chain has a central asset router contract, which now allows token owners to define a custom l2 asset handler upon registration (meaning custom l2 contracts with upgradeability, minting etc.)
To migrate to this new asset router/handler paradigm, the L1SharedBridge on L1 is repurposed, and all assets from it are transferred to a default / canonical asset handler called L1NativeTokenVault.
The L1SharedBridge proxy is changed to an implementation called ‘L1Nullifier’ that accounts for the assets on the different chains (e.g. chainBalance mapping) and does not escrow any tokens.

This change will allow ZK chains to customize their tokens more, add L2 → L1 bridging for native tokens, and pave the way to a more interoperable Elastic Network. However, more customization also opens the door to bad customization and new trust assumptions from tokens that are canonically bridged but, for example, have contracts on L2 that can be changed at any time.

3. Custom Settlement Layers

This is a deep change that will not be immediately usable. It prepares the migration of chains to alternative settlement layers, allowing, e.g., the ZKsync Era L3 migration. Chain migration is coordinated by a ChainTypeManager (prev. StateTransitionManager) contract that is present on every chain that allows settlement (for example on the future ‘Gateway’ Rollup). The design allows future chains to move in the Elastic Network similarly to assets, freely choosing to be on Layer 2 or Layer 3 and on which ZK host chain.

Similarly to the DA switching mentioned above, a local chain admin can start a migration at any time, which is incompatible with Stage 1 (as defined by our Stages Framework - see above) unless done by a local SecurityCouncil.

However, at the time of writing this comment none of the ZK stack chains are Stage 1, and the Gateway deployment (first alternative settlement layer) is not part of this proposal, leaving only one settlement layer - Ethereum.

v26

The bigger picture for v26, which this proposed upgrade is just a part of, is an aggregation layer similar to Polygon’s AggLayer but kind of different since the aggregation layer will just be another ZK stack rollup. It will use a strict transactionFilterer and not be general purpose, focused on receiving data and proofs from its L3s and aggregating them to L1.

As far as we can tell and from the documentation we reviewed, the upgrade is well-presented, and the verification tool is useful. The audits are thorough, available docs are informative, and the L1 contracts are pre-deployed and verified. Regarding the upgrade itself, there are pros and cons to the proposed changes (as outlined above), but overall, we don’t see a solid reason that would compel us to vote against the proposal.

Shout-out to our research team for all their hard work going through everything to help us make an informed decision.

ZKSC · February 26, 2025, 12:00pm

ZKsync Security Council — Proposal Verification

The ZKsync Security Council has completed an initial review of ZIP-6 and shared the outcomes of the review in this forum post.

The ZKsync Security Council is comfortable that the proposal call data has been verified and is accurate.