[Draft] 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