[ZIP-6] Prepare ZKsync for ZK Gateway

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:

1. 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.
2. 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 Feature

• 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: https://github.com/matter-labs/era-contracts/tree/release-v26/docs.

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: https://github.com/matter-labs/era-contracts/blob/release-v26/docs/gateway/overview.md

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: https://github.com/matter-labs/era-contracts/blob/release-v26/docs/gateway/gateway_da.md

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

https://github.com/matter-labs/era-contracts/blob/release-v26/docs/bridging/asset_router/overview.md

Additional differences

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

https://github.com/matter-labs/era-contracts/blob/release-v26/docs/upgrade_history/gateway_upgrade/gateway_diff_review.md

ZIP-6 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:

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

Audit reports

Multiple audits of the intermediate versions of the codebase have been performed by OpenZeppelin, which culminated into the final "Release Candidate Audit":

• ZKsync Custom Asset Bridge Audit (OpenZeppelin).pdf
• ZKChain Upgrades and Libraries Diff Audit (OpenZeppelin).pdf
• ZKsync ZKChain and Gateway Upgrade Audit (OpenZeppelin).pdf
• ZKChain Release Candidate Audit (OpenZeppelin).pdf

The last audit has found only Low/Note issues the fixes for which we decided to include in the next release, to keep the codebase identical to the one that was released on our internal staging env and the private testnet.

Also, an audit was conducted by Audittens: ZKsync Gateway Audit (Audittens).pdf. It covered the contracts at commit 7198b54fbcba37aa7a1dd75fc3067391af33e03e. All the issues found by Audittens were resolved.

Later on, we conducted a CodeHawks competition with $500000 prize pool https://codehawks.cyfrin.io/c/2024-10-zksync for the full codebase that features the code the for upgrade. All the issues found during the contest were resolved. The final report is still private at the moment, but the diff between commits 7198b54fbcba37aa7a1dd75fc3067391af33e03e and a5754174938bd16a57b3cb59af5c604f9789bbc5 (that came after fixes from the Audittens' report and the CodeHawks contest) has been briefly reviewed by Audittens. This is also mentioned in the Audittens' report provided above.

The final commit that is identical to the code that is being deployed has been covered in the OpenZeppelin's Release Candidate report mentioned above. The diff can be seen here. The diff contains only non-contract changes (scripts, tests, etc).

Also, for reference the diff between a5754174938bd16a57b3cb59af5c604f9789bbc5 (the last one reviewed by Audittens) and 4f109c42315c1d51bcad2b1a92b7044b6d6550f7 used for the release is the following one. It contains only:

• Non-contract changes (scripts, tests, etc). This includes a new contract called ChainAdminOwnable but it is a full copy of the ChainAdmin contract from the current repo. This helps to test the backwards compatibility of tooling with the old ChainAdmin implementation. Due to the complexity of the new ChainAdmin contract, the Ownable it is also the recommended chain admin implementation to be used by chains. Ultimately, chains are never restricted in the version that they use (and may build their custom one if they wish to).
• Contracts in da-contracts/contracts/da-layers/avail/* These contracts are not within the scope of the upgrade and will not be deployed as part of this upgrade.
• system-contracts/contracts/L2GatewayUpgrade.sol has been amended to remove the requirement for the upgrade of the wrapped base token implementation to the new version. This is needed to allow the support of the custom wrapped base token implementations for chains. This change was thoroughly reviewed by an internal audit and included in the OpenZeppelin's Release Candidate Audit.

Additional known issues

The following issues have been identified internally:

• The default wrapped base token will always have the default Wrapped Base Token/WBT name and symbol respectively. This issue has a minor impact and could be fixed in the future. It was kept this way to keep the code the same between testing environments and the mainnet deployment.
• Additional issues around correctly setting up the facets for chains on top of Gateway have been found. These were fixed in this PR, but these issues do not affect the current upgrade, since the Gateway chain is not being deployed as part of it.

Gateway chain will be deployed within a separate ZIP and it will include the fixes for the issues above.

Upgrade review process

It is recommended to get familiar with the upgrade process here.

The community now has access to a Rust tool to verify the correctness of the upgrade. You can explore and use the tool directly by visiting the Protocol Upgrade Verification Tool repo.

⚠️ Warnings: Currently, the protocol-upgrade-verification-tool tools returns two warnings:

• That chain 325 does not have a wrapped base token. This has been agreed on with that chain. If you don't like the warning you can amend the tool to ignore the chain.
• That the admin of the l2 wrapped base token store (https://etherscan.io/address/0x00937bfa497EBf4a26c14209B544dFb14d960555#writeContract) is not the ecosystem admin. This is true, we have given the ecosystem admin (https://etherscan.io/address/0x2cf3bD6a9056b39999F3883955E183F655345063#code) the status of pending admin, but it needs to accept it.

The latter should not be a blocker to start the voting delay. We will have plenty of time before the vote period actually begins to accept the vote.