ZKsync v2 Project Architecture

This document will help you answer the question: where can I find the logic for x? by giving a directory-tree style structure of the physical architecture of the ZKsync Era project.

High-Level Overview

The zksync-era repository has the following main units:

Smart Contracts: All the smart contracts in charge of the protocols on the L1 & L2. Some main contracts:

  • L1 & L2 bridge contracts.
  • The ZKsync rollup contract on Ethereum.
  • The L1 proof verifier contract.

Core App: The execution layer. A node running the ZKsync network in charge of the following components:

  • Monitoring the L1 smart contract for deposits or priority operations.
  • Maintaining a mempool that receives transactions.
  • Picking up transactions from the mempool, executing them in a VM, and changing the state accordingly.
  • Generating ZKsync chain blocks.
  • Preparing circuits for executed blocks to be proved.
  • Submitting blocks and proofs to the L1 smart contract.
  • Exposing the Ethereum-compatible web3 API.

Prover App: The prover app takes blocks and metadata generated by the server and constructs a validity zk proof for them.

Storage Layer: The different components and subcomponents don’t communicate with each other directly via APIs, rather via the single source of truth – the db storage layer.

Low-Level Overview

This section provides a physical map of folders & files in this repository. It doesn’t aim to be complete, it only shows the most important parts.

  • /contracts: A submodule with L1, L2, and system contracts. See repository.

  • /core

    • /bin: Executables for the microservices components comprising ZKsync Core Node.

      • /zksync_server: Main sequencer implementation.
      • /external_node: A read replica that can sync from the main node.
      • /tee_prover: Implementation of the TEE prover.

    • /node: Composable node parts.

      • /node_framework: Framework used to compose parts of the node.
      • /api_server: Implementation of Web3 JSON RPC server.
      • /base_token_adjuster: Adaptor to support custom (non-ETH) base tokens.
      • /block_reverter: Component for reverting L2 blocks and L1 batches.
      • /commitment_generator: Component for calculation of commitments required for ZKP generation.
      • /consensus: p2p utilities.
      • /consistency_checker: Security component for the external node.
      • /da_clients: Clients for different data availability solutions.
      • /da_dispatcher: Adaptor for alternative DA solutions.
      • /eth_sender: Component responsible for submitting batches to L1 contract.
      • /eth_watch: Component responsible for retrieving data from the L1 contract.
      • /fee_model: Fee logic implementation.
      • /genesis: Logic for performing chain genesis.
      • /metadata_calculator: Component responsible for Merkle tree maintenance.
      • /node_storage_init: Strategies for the node initialization.
      • /node_sync: Node synchronization for the external node.
      • /proof_data_handler: Gateway API for interaction with the prover subsystem.
      • /reorg_detector: Component responsible for detecting reorgs on the external node.
      • /state_keeper: Main part of the sequencer, responsible for forming blocks and L1 batches.
      • /vm_runner: Set of components generating various data by re-running sealed L1 batches.

    • /lib: All the library crates used as dependencies of the binary crates above.

      • /basic_types: Crate with essential ZKsync primitive types.
      • /config: All the configuration values used by the different ZKsync apps.
      • /contracts: Contains definitions of commonly used smart contracts.
      • /crypto_primitives: Cryptographical primitives used by the different ZKsync crates.
      • /dal: Data availability layer
        • /migrations: All the db migrations applied to create the storage layer.
        • /src: Functionality to interact with the different db tables.
      • /db_connection: Generic DB interface.
      • /eth_client: Module providing an interface to interact with an Ethereum node.
      • /eth_signer: Module to sign messages and txs.
      • /mempool: Implementation of the ZKsync transaction pool.
      • /merkle_tree: Implementation of a sparse Merkle tree.
      • /mini_merkle_tree: In-memory implementation of a sparse Merkle tree.
      • /multivm: A wrapper over several versions of VM that have been used by the main node.
      • /object_store: Abstraction for storing blobs outside the main data store.
      • /queued_job_processor: An abstraction for async job processing
      • /state: A state keeper responsible for handling transaction execution and creating miniblocks and L1 batches.
      • /storage: An encapsulated database interface.
      • /test_account: A representation of ZKsync account.
      • /types: ZKsync network operations, transactions, and common types.
      • /utils: Miscellaneous helpers for ZKsync crates.
      • /vlog: ZKsync observability stack.
      • /vm_interface: Generic interface for ZKsync virtual machine.
      • /web3_decl: Declaration of the Web3 API.

    • /tests: Testing infrastructure for ZKsync network.

      • /loadnext: An app for load testing the ZKsync server.
      • /ts-integration: Integration tests set implemented in TypeScript.

  • /prover: ZKsync prover orchestrator application.

  • /docker: Project docker files.

  • /bin & /infrastructure: Infrastructure scripts that help to work with ZKsync applications.

  • /etc: Configuration files.

    • /env:.env files that contain environment variables for different configurations of ZKsync Server / Prover.

  • /keys: Verification keys for circuit module.