On September 12, 2024, ZKsync announced the launch of its governance system in this blog post, outlining a framework in alignment with the ZK Credo. This governance system is structured to ensure that no single entity can unilaterally enact protocol changes. Instead, authority is distributed among the three independent bodies:

  1. Token Assembly: Comprising token holders and their Delegates, this body can propose and vote on protocol upgrades directly on-chain.
  2. Security Council: A group of technical experts responsible for reviewing and approving protocol upgrades, as well as addressing security threats.
  3. Guardians: Individuals who ensure that proposals align with the values outlined in the ZK Credo and act as a check on the other governance bodies.

Moonsong Labs was engaged to develop technical tools that support decentralized decision making given the unique requirements of the ZKsync governance model.This collaboration resulted in the creation of the GovAuth App and the Upgrade Verification Tool, designed to facilitate coordination among governance bodies and enhance the verification process for protocol upgrades.

This article examines the technical implementation of these tools, focusing on their role in addressing governance challenges within ZKSync.

Background and Context

To effectively implement this governance model, tools were needed that would:

  • Simplify the coordination of multi-signature approvals across decentralized bodies, specifically Guardians and Security Council.
  • Enhance transparency and accessibility for all governance participants.
  • Enable independent verification of protocol upgrades in a user-friendly manner.

These requirements formed the basis for the technical solutions developed by Moonsong Labs. 

Objectives

Moonsong Labs was tasked with implementing software that met these high-level objectives:

  1. Develop a web-based app for facilitating governance actions, including protocol upgrades, emergency interventions, and proposal vetoes, ensuring compatibility with the SAFE signature process.
  2. Create a command-line tool for stakeholders to independently verify upgrade proposals and analyze protocol changes in a human-readable format.

Research and Discovery

Moonsong Labs conducted research into existing blockchain governance systems to identify gaps in multi-signature coordination and independent verification tools. Based on this research, Moonsong Labs presented a set of technical options for evaluation.

Key findings included:

  • A lack of user-friendly tools for independent verification in many protocols.
  • Fragmented signature coordination processes requiring significant manual effort.

Governance Contracts
Moonsong Labs analyzed ZKSync’s governance contracts and processes to translate technical requirements into actionable tool designs. This included understanding contract interactions for proposals, approvals, and upgrades.

Solution Design Technical

Implementation and Process Design

The governance voting process on ZKsync requires coordination among multiple stakeholders. While the process was embedded in a series of smart contracts (ZKSync Governance GitHub Repository), a mechanism was needed to enable seamless coordination and interaction for those involved.

The applications developed as part of this solution include:

GovAuth App
Purpose: Provides a web interface to coordinate governance actions for the Security Council, Guardians, and the Foundation.
Architecture: Built with Remix, viem, wagmi, and RainbowKit for smart contract interactions, alongside a backend for signature storage and action coordination.
Key Features:

  • Protocol Upgrade Workflow: Tracks proposal statuses, displays upgrade metadata, and facilitates multi-signature approval.
  • Signature Coordination: Collects and bundles signatures from SAFE multisig wallets or EOAs.
  • Emergency Interventions: Supports emergency upgrades, freezes, unfreezes and direct vetos to L2 proposals.
  • Role-Based Access: Limits actions based on user roles (e.g., Guardian, Security Council member).

The original version of this diagram was published by L2beat. Modifications were made to illustrate the use case presented in this article. 

Upgrade Verification Tool

Purpose: Enables stakeholders to verify protocol upgrade proposals independently and locally.
Architecture: A CLI tool built with Node.js, designed to fetch and decode upgrade data, facilitating offline analysis.
Key Features:

  • Upgrade Decoding: Transforms protocol upgrade data into human-readable reports.
  • Facet and Bytecode Comparison: Highlights differences in proposed contract changes.
  • Storage Diff Analysis: Simulates upgrades to show changes in the main contract’s storage.

Key Features of the Governance Tools

Governance Flows

The app was built to support four primary governance workflows:

  1. Standard Protocol Upgrades
  2. Emergency Protocol Upgrades
  3. Protocol Freeze Actions
  4. Guardian Vetos for Proposals on L2

These workflows involve multiple stages and require signatures from various stakeholders that are involved in ZKSync governance, coordinated across different locations and timeframes.

Flow Coordination and Execution

To meet the ZKSync governance requirements, the app includes functionalities to:

  • Generate Messages: Approving an action is done by signing a specific message. The web app is in charge of building that message by fetching data from the blockchain, taking input from users, and then combining and formatting those following the governance protocol.
  • Authenticate and Identify Users: Users connect their wallet with the app for authentication and verifying user roles (e.g., Guardian, Security Council Member, or Visitor) against governance smart contracts.
  • Display Relevant Data: Presenting action-specific details clearly to ensure users understand their involvement.
  • Facilitate Signatures: Enabling secure and streamlined signature collection for governance actions.
  • Validate and Store Signatures: Ensuring collected signatures are valid and meet the required thresholds for executing actions.

Once all required signatures are gathered, the app compiles a valid transaction, facilitates payment of associated costs, and broadcasts the transaction to the blockchain.

Flow-Specific Features

  1. Standard Protocol Upgrades
    • The process follows the steps defined in the ZKSync Governance Documentation.
    • The app ensures stakeholders perform actions at the correct stages and tracks progress through the workflow.
  2. Emergency Protocol Upgrades
    • Create an Emergency Upgrade proposal by defining a list of transactions, an executor, and specific metadata.
    • The app gathers signatures from Guardians, Security Council members, and the ZK Association.
    • Once the signatures are there, the executor can execute the emergency upgrade.
  3. Protocol Freeze Actions
    • Supports various freeze types (e.g., soft, hard, unfreeze) and ensures no duplicate actions of the same type occur simultaneously.
    • Tracks vote thresholds and expiration dates for freeze actions.
  4. Guardian L2 Vetos
    • Guardians veto proposals on L2 by signing and broadcasting a message from L1.
    • The app identifies active proposals on L2, gathers signatures, and executes veto transactions upon meeting requirements.

Design Considerations

The app does not maintain a user database; instead, it connects to the user's wallets and verifies their roles via governance contracts on every write interaction. It also identifies governance proposals initiated on L2 but not yet started on L1, ensuring smooth transition and execution across layers.

Deep Dive: Protocol Upgrade Authentication

The original version of this diagram was published by L2beat. Modifications were made to illustrate the use case presented in this article 

Protocol upgrade authentication involves a coordinated workflow across the Governance Authentication App, the Upgrade Verification Tool, and ZKsync governance & upgrade smart contracts. Here's a detailed breakdown of the process

1. Proposal Creation and Approval on ZKsync Era & Communication to Ethereum

The process begins with a protocol upgrade proposal being created on ZKsync Era (L2) using the governance system. A proposer initiates the proposal by calling the propose() method on the UpgradeGovernor contract. This proposal includes details such as the proposed changes, associated metadata, and an identifier (proposal ID). Once the proposal is submitted, it undergoes a voting process (using platforms such as Tally) where eligible Delegates cast their votes.

Upon meeting the required quorum, the proposal is marked as approved and queued to prepare it for execution. At this stage, the proposal is registered as a pending upgrade on L2.

After the proposal is approved, the UpgradeGovernor contract emits a message to ZKsync’s governance contracts in the Ethereum mainnet (L1) via the MessageBridge. The message serves as a notification to L1, enabling governance bodies to take further action. 

All this is standard governance procedure from ZKsync governance system. Once the message arrives, the GovAuth app starts to enter into play. 

2. Upgrade Initialization in the Governance Authentication App

Once the message reaches L1, stakeholders can use the GovAuth app to facilitate the initiation of the upgrade process. The app provides an interface where authorized users can select the approved proposal from a list and helps building a transaction calling the startUpgrade method on the ProtocolUpgradeHandler contract. This marks the official start of the protocol upgrade process.

  • At this stage, the app displays key information about the upgrade, including its status and the timeline for approval. The startUpgrade method establishes the approval period during which the relevant governing bodies must review and sign off on the upgrade.

Once this is completed, the stakeholders—namely, the guardians and members of the security council—can begin the authentication process. 

The lifecycle of protocol upgrades is defined by the `ProtocolUpgradeHandler` contract, and more details can be found here. The web application is designed to understand each phase of this lifecycle, displaying the appropriate data to the relevant users and allowing them to take only the actions that are valid for that particular phase depending on their role (Visitor, Security Council, Guardian, Foundation, Admin). These actions may include signing to authenticate or to extend the legal veto period, among others.

3. Review and Verification using the Upgrade Verification Tool

During the approval period, the Guardians and Security Council members thoroughly review the proposed upgrade.

  • The Governance Authentication App serves as a central hub for tracking the approval timeline, monitoring signature collection progress, and accessing details about the upgrade.
  • Meanwhile, the Upgrade Verification Tool (CLI) provides stakeholders with a local, independent way to analyze the proposal. Users can download a JSON file containing the upgrade details from the app and use the upgrade reference commit (generally provided by governance facilitators).

The CLI offers several commands to facilitate this review. For example:

  • The id command uses the raw protocol upgrade file as input and calculates and prints the ID for a given upgrade.
    • When users attempt to approve an upgrade with their wallets, the only data displayed is the upgrade ID. To ensure they're approving the correct upgrade, users must recalculate the ID locally and verify that it matches the one shown in their wallets. For example:
  • The check command checks that the upgrade can be executed. Then, it summarizes the changes produced by the upgrade. The output has several sections:
    • Metadata: General information about the upgrade
    • Facet changes: Summary of facet changes for the main ZKsync diamond.
    • Property changes: Shows changes in the most important properties of the main diamond.
    • System contract changes: Lists system contracts being modified by the upgrade.
  • The storage-diff command simulates the upgrade and then shows how the storage of the main diamond gets modified by the upgrade.

5. Signature Collection

Once stakeholders are satisfied with their review, they proceed to authenticate the upgrade by providing their signatures. The GovAuth app facilitates this process by creating the message to sign. 

Usually, stakeholders use a SAFE multi-sig wallet. Once the necessary signature threshold is reached, the app receives the signature created by that SAFE. The app verifies the signature and saves it in the database.

The app tracks the collected signatures and provides visual feedback, showing the number of signatures collected versus the total required and the addresses that already authenticated the upgrade for transparency on the process. 

6. Approval, Timelock & Execution

After the required number of signatures has been collected and the review period has finished, the app enables the broadcast upgrade action with the bundle of all the respective signatures.  This is, again, a method call on the `ProtocolUpgradeHandler` where all the signatures are sent. 

After broadcasting the approval transaction, the timelock applies. After 1 day, the proposal is ready to be executed. Most upgrades specify a particular executor. Usually, this is the user in charge of setting everything up for the successful execution of the upgrade. For example, ensure that every service of l2 is running the correct software for the new version. Once everything is set, the executor can use the web app to broadcast the transaction that executes the upgrade.

After execution, the protocol is updated, and the upgrade process is complete. The app provides a final status update, confirming that the upgrade has been successfully executed.

Learnings and Opportunities

The project highlighted the complexity of decentralized governance tooling. Key takeaways include:

  • Transparency and Accessibility: Simplifying complex governance processes enhances stakeholder participation.
  • Technical Challenges: Translating governance workflows into user-friendly tools requires a deep understanding of smart contract architecture and on-chain interactions.
  • Broader Implications: These tools provide a blueprint for addressing governance challenges across Web3 ecosystems.

Conclusion 

ZKSync's governance system, with its clearly defined roles for the Token Assembly, Security Council, and Guardians, demonstrates a structured approach to enabling transparent processes and user-friendly participation in protocol decision-making. The thoughtful approach to designing ZKSync's governance system ensures that key principles such as resilience, distribution, and mission alignment are not only upheld but operationalized effectively through well-defined processes and innovative technical solutions. The tools serve as vital components in this vision, enabling efficient coordination and trustless verification while supporting ZKSync’s broader mission to advance decentralized innovation.

Moonsong Labs is an Engineering Services company and Venture Studio working for a broad range of Web3 Foundations and ecosystems.  To learn more about Moonsong Labs please visit: https://moonsonglabs.com/