# icme-lab/zkengine_dev architecture

> Architecture diagram of the GitHub repository icme-lab/zkengine_dev, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/icme-lab/zkengine_dev
- Repository: https://github.com/icme-lab/zkengine_dev

## Overview

##### Main Components
- Core Engine (zkEngine Library): Represents the central logic of the engine. The core includes modules such as:
- wasm_snark: This module is the heart of the proving process and proof verification. It provides functions like setup (producing public parameters), proving (executing the WASM code under a given step size), and verifying proofs.
- wasm_ctx & wasm_args: These components build and manage the execution context for a given WASM program. The WASMArgsBuilder is used to provide the file path, function name (e.g., "fib" or "kth_factor"), and function arguments.
- Aggregation and Sharding: These modules (located in src/aggregation and src/sharding) could address how the workload or data is partitioned and then combined – likely to support scalability or efficient memory consistency checks.
- Utils: Various helper modules like logging, tracing, and error handling that support the overall engine.

##### Third-Party Integration
- Wasmi: A Wasi or WASM interpreter engine integrated under the third-party directory. This is used to interpret or process WASM bytecode. It provides the underlying WASM execution environment which the zkEngine builds upon.
- External WASM Files: The WASM programs (e.g., in the wasm/ directory) are the inputs that the engine works on. They provide real-world examples (e.g., Fibonacci, kth_factor, etc.) and use cases.

##### Relationships and Data Flow
- Memory Consistency (MCC) and Switchboard: Within the wasm_snark module, break out internal components such as:
▪ Gadgets: Constraint systems and arithmetic operations (e.g., int, mcc).
▪ MCC (Memory Consistency Check) modules: Responsible for verifying large memory spaces and using memory_step_size.
▪ Switchboard: Handling ALU operations (with subcomponents for int32, int64, etc.).
As internal components that feed into the overall “WasmSNARK” proving flow.

##### Architectural Patterns or Design Principles
- Modular Design: The code is organized across different modules (aggregation, sharding, wasm_snark, utils) which promotes clear separation of concerns.
- Layering: The system layers the WASM input processing (WASMCtx), the proving engine (WasmSNARK with its gadgets and MCC), and the post-processing verification steps.
- Integration of Third-Party Libraries: The incorporation of wasmi shows how external dependencies are wrapped within the project to provide WASM module support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Invocation & Setup Phase
    subgraph "Client Invocation & Setup Phase"
        A["Client/Invocation (Example Code)"]:::client
        B["WasmSNARK::setup (Setup Phase)"]:::core
        C["WASMPublicParams (Output)"]:::core
        A -->|"invokes"| B
        B -->|"produces"| C
    end

    %% Execution Context Setup
    subgraph "Execution Context Setup"
        D["External WASM Files"]:::external
        E["WASMArgsBuilder (Creates Execution Context)"]:::core
        F["WASMCtx (Execution Context)"]:::core
        D -->|"provides_input"| E
        E -->|"builds"| F
    end

    %% Proving Engine
    subgraph "Proving Engine"
        G["WasmSNARK::prove (with StepSize)"]:::core
        H["Gadgets (Constraint Systems)"]:::internal
        I["MCC (Memory Consistency Check)"]:::internal
        J["Switchboard/ALU"]:::internal
        K["snark (Proof)"]:::core
        L["Witness Instance"]:::core
        F -->|"provides_input"| G
        G -->|"uses"| H
        G -->|"uses"| I
        G -->|"uses"| J
        G -->|"outputs"| K
        G -->|"outputs"| L
    end

    %% Verification Phase
    subgraph "Verification Phase"
        M["snark.verify (Verification)"]:::core
        K -->|"verifies_with"| M
        L -->|"verifies_with"| M
    end

    %% Core Engine Modules
    subgraph "Core Engine Modules"
        N["Core Engine (zkEngine Library)"]:::core
        O["Aggregation Module"]:::util
        P["Sharding Module"]:::util
        Q["Utils (Logging/Tracing/etc.)"]:::util
        N -->|"contains"| B
        N -->|"contains"| G
        N -->|"modular_design"| O
        N -->|"modular_design"| P
        N -->|"modular_design"| Q
    end

    %% External Dependencies
    subgraph "External Dependencies"
        R["wasmi (WASM Interpreter)"]:::external
        R -->|"supports_execution"| F
    end

    %% Click Events
    click A "https://github.com/icme-lab/zkengine_dev/tree/main/examples/"
    click N "https://github.com/icme-lab/zkengine_dev/blob/main/src/lib.rs"
    click B "https://github.com/icme-lab/zkengine_dev/tree/main/src/wasm_snark"
    click G "https://github.com/icme-lab/zkengine_dev/tree/main/src/wasm_snark"
    click F "https://github.com/icme-lab/zkengine_dev/blob/main/src/wasm_ctx.rs"
    click E "https://github.com/icme-lab/zkengine_dev/blob/main/src/utils/wasm.rs"
    click O "https://github.com/icme-lab/zkengine_dev/tree/main/src/aggregation"
    click P "https://github.com/icme-lab/zkengine_dev/tree/main/src/sharding"
    click Q "https://github.com/icme-lab/zkengine_dev/tree/main/src/utils"
    click R "https://github.com/icme-lab/zkengine_dev/tree/main/third-party/wasmi"
    click D "https://github.com/icme-lab/zkengine_dev/tree/main/wasm/"

    %% Styles
    classDef client fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef internal fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#922b21,stroke-width:2px;
    classDef util fill:#d5f5e3,stroke:#1e8449,stroke-width:2px;
```
