How verified-zkevm/clean works
Project Type and Purpose
• This project is a domain-specific language (DSL) for defining zero-knowledge circuits.
• Its purpose is to offer a formal, bug-free, and verified framework for writing zk circuits that can later be translated to various arithmetizations (with AIR as a target in this version).
Analyzing the File Structure
• Top-Level Components:
• The .github folder and its workflows (CI configuration) indicate automated testing and CI/CD pipelines.
• The "Clean" directory is the heart of the DSL, containing subdirectories such as:
▪ Circuit: Contains fundamental circuit definitions, operations, and proofs (e.g., Provable, SubCircuit, Theorems).
▪ Gadgets: Implements reusable circuit building blocks for specific operations (Addition8, Addition32, Boolean, Equality, etc.).
▪ Table and Tables: Likely handling lookup or runtime tables that are used within circuits.
▪ Types: Defines custom types such as Byte and U32 which appear to play a significant role in the DSL.
▪ Utils: Provides utility modules, including support functions for fields, primes, tactics, and vector operations.
• Examples and experiments illustrate usage and experimentation with the DSL and its components.
• Additional files (Clean.lean, lakefile.lean, lake-manifest.json, etc.) are part of the Lean ecosystem and build system.
Extracting Key Architectural Insights from the README
• The README presents “clean” as an embedded DSL intended for writing and verifying zk circuits.
• The instructions emphasize using Lean and the lake build tool for compiling/checking code, and recommend VSCode for interactive feedback.
• The project is built around the ideas of formal verification and modularity – important architectural principles to capture.
(a) Identify the Main Components
• DSL Core Engine:
• Represents the Lean DSL and the underlying language constructs defined by files in the Clean directory.
• Circuit Module:
• Encapsulates the core mechanisms for circuit representation (modules under Clean/Circuit).
• Gadgets Library:
• Contains pre-built, composable gadgets (under Clean/Gadgets) for various arithmetic and boolean operations.
• Lookup/Tables Module:
• Manages static or dynamic tables (under Clean/Table and Clean/Tables) that are key to circuit evaluations.
• Types and Utilities:
• These modules provide basic types (e.g., Byte, U32) and utilities (field operations, tactics, vector manipulations) used across the system.
• Examples & Experiments:
• How the DSL is used in practice and serve as integration tests.
• CI/CD & Build Infrastructure:
• Represented by .github/workflows and lake configuration files, indicating a pipeline for continuous verification and deployment.
(b) Determine Relationships and Interactions
• That Gadgets and Circuit modules interact closely: gadgets are essentially higher-level reusable abstractions built on circuit principles.
• Bidirectional interactions between the types/utilities modules and the core DSL components – since types like Byte and U32 permeate many layers.
(c) Highlight Architectural Patterns or Design Principles
• Modularity: Each major element (Circuits, Gadgets, Tables, Types) is separated into distinct directories reflecting a modular design.
• Reusability: The Gadgets and Table libraries emphasize reusability of zk circuit components.
• Formal Verification: The inclusion of theorem files (Theorems, Provable) underlines the system’s emphasis on correctness.
• Separation of Concerns: With clear directories for proofs, circuit definitions, and utility functions, the design segregates the DSL’s logical components from its supporting infrastructure.
(d) Mention Relevant Technologies and Frameworks
• Lean4 as the primary language and environment for defining the DSL.
• Lake as the build tool integrated with Lean.
• CI/CD configured with GitHub Actions (.github/workflows/ci.yml).
• VSCode and its Lean4 extension as part of the recommended toolchain for development.