# verified-zkevm/clean architecture

> Architecture diagram of the GitHub repository verified-zkevm/clean, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/verified-zkevm/clean
- Repository: https://github.com/verified-zkevm/clean

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core DSL
    subgraph "Core DSL"
        DSL_Core_Engine["DSL Core Engine"]:::core
    end

    %% DSL Modules
    subgraph "DSL Modules"
        Circuit_Module["Circuit Module"]:::module
        Gadgets_Library["Gadgets Library"]:::module
        Table_Module["Lookup Module (Table)"]:::module
        Tables_Module["Lookup Module (Tables)"]:::module
        Types_Module["Types Module"]:::module
        Utils_Module["Utils Module"]:::module
    end

    %% Usage & Integration
    subgraph "Usage & Integration"
        Examples["Examples"]:::integration
        Experiments["Experiments"]:::integration
        CI_CD_Pipeline["CI/CD Pipeline"]:::integration
        External_Tools["External Tools"]:::integration
    end

    %% Relationships from Core DSL to Modules
    DSL_Core_Engine -->|"primitives"| Circuit_Module
    DSL_Core_Engine -->|"primitives"| Gadgets_Library
    DSL_Core_Engine -->|"primitives"| Types_Module
    DSL_Core_Engine -->|"primitives"| Utils_Module

    %% Relationships among Modules
    Circuit_Module -->|"builds"| Gadgets_Library
    Gadgets_Library -->|"utilizes"| Circuit_Module
    Circuit_Module -->|"lookup"| Table_Module
    Circuit_Module -->|"lookup"| Tables_Module
    Types_Module ---|"shared"| Utils_Module

    %% Relationships to Usage & Integration
    DSL_Core_Engine -->|"used_in"| Examples
    DSL_Core_Engine -->|"used_in"| Experiments
    DSL_Core_Engine -->|"built_with"| CI_CD_Pipeline
    DSL_Core_Engine -->|"developed_with"| External_Tools

    %% Styling classes
    classDef core fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef module fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef integration fill:#ccccff,stroke:#333,stroke-width:2px;

    %% Click Events for DSL Core (Core DSL)
    click DSL_Core_Engine "https://github.com/verified-zkevm/clean/blob/main/Clean.lean"

    %% Click Events for DSL Modules
    click Circuit_Module "https://github.com/verified-zkevm/clean/tree/main/Clean/Circuit"
    click Gadgets_Library "https://github.com/verified-zkevm/clean/tree/main/Clean/Gadgets"
    click Table_Module "https://github.com/verified-zkevm/clean/tree/main/Clean/Table"
    click Tables_Module "https://github.com/verified-zkevm/clean/tree/main/Clean/Tables"
    click Types_Module "https://github.com/verified-zkevm/clean/tree/main/Clean/Types"
    click Utils_Module "https://github.com/verified-zkevm/clean/tree/main/Clean/Utils"

    %% Click Events for Usage & Integration
    click Examples "https://github.com/verified-zkevm/clean/tree/main/Clean/Examples"
    click Experiments "https://github.com/verified-zkevm/clean/tree/main/experiments"
    click CI_CD_Pipeline "https://github.com/verified-zkevm/clean/tree/main/.github/workflows"
    click External_Tools "https://github.com/verified-zkevm/clean/tree/main/lean-toolchain"
```
