Skip to content

Latest commit

 

History

History
110 lines (84 loc) · 5.47 KB

architecture.md

File metadata and controls

110 lines (84 loc) · 5.47 KB
Raw

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

  • /contracts

    • /ethereum: Smart contracts deployed on the Ethereum L1.
    • /zksync: Smart contracts deployed on the zkSync L2.

  • /core

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

      • /admin-tools: CLI tools for admin operations (e.g. restarting prover jobs).

      • /prover: zkSync prover orchestrator application.

      • zksync_core/src

        • /api_server Externally facing APIs.
          • /web3: zkSync implementation of the Web3 API.
          • /tx_sender: Helper module encapsulating the transaction processing logic.
        • /bin: The executable main starting point for the zkSync server.
        • /circuit_breaker_checker: zkSync watchdog.
        • /eth_sender: Submits transactions to the zkSync smart contract.
        • /eth_watch: Fetches data from the L1. for L2 censorship resistance.
        • /fee_monitor: Monitors the ratio of fees collected by executing txs over the costs of interacting with Ethereum.
        • /fee_ticker: Module to define the price components of L2 transactions.
        • /gas_adjuster: Module to determine the fees to pay in txs containing blocks submitted to the L1.
        • /gas_tracker: Module for predicting L1 gas cost for the Commit/PublishProof/Execute operations.
        • /metadata_calculator: Module to maintain the zkSync state tree.
        • /state_keeper: The sequencer. In charge of collecting the pending txs from the mempool, executing them in the VM, and sealing them in blocks.
        • /witness_generator: Takes the sealed blocks and generates a Witness, the input for the prover containing the circuits to be proved.

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

      • /basic_types: Crate with essential zkSync primitive types.
      • /config: All the configured values used by the different zkSync apps.
      • /contracts: Contains definitions of commonly used smart contracts.
      • /crypto: 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.
      • /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.
      • /object_store: Abstraction for storing blobs outside the main data store.
      • /prometheus_exporter: Prometheus data exporter.
      • /prover_utils: Utilities related to the proof generation.
      • /queued_job_processor: An abstraction for async job processing
      • /storage: An encapsulated database interface.
      • /types: zkSync network operations, transactions, and common types.
      • /utils: Miscellaneous helpers for zkSync crates.
      • /vlog: zkSync logging utility.
      • /vm: ULightweight out-of-circuit VM interface.
      • /web3_decl: Declaration of the Web3 API.

    • /tests: Testing infrastructure for zkSync network.

      • /loadnext: An app for load testing the zkSync server.
      • /test_account: A representation of zkSync account.
      • /testkit: A relatively low-level testing library and test suite for zkSync.
      • /ts-integration: Integration tests set implemented in TypeScript.

  • /docker: Project docker files.

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

  • /etc: Configration files.

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

  • /keys: Verification keys for circuit module.

  • /sdk: Implementation of client libraries for the zkSync network in different programming languages.

    • /zksync-rs: Rust client library for zkSync.
    • /zksync-web3.js: A JavaScript / TypeScript client library for zkSync.