# internetmaximalism/intmax2-zkp architecture

> Architecture diagram of the GitHub repository internetmaximalism/intmax2-zkp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/internetmaximalism/intmax2-zkp
- Repository: https://github.com/internetmaximalism/intmax2-zkp

## Overview

##### Project Type and Purpose
- Type: A Rust library implementing Zero-Knowledge (ZK) rollup circuits.
- Purpose: Provide a suite of recursive ZK circuits (Validity, Balance, Withdrawal, Claim, Proof of Innocence) to offload computation from Layer 1 to clients, ensuring privacy and scalability.

##### File Structure
Top-level modules:
- src/circuits – ZK circuit implementations, organized by feature (validity, balance, withdrawal, claim, proof_of_innocence, plus test utilities).
- src/common – Shared data types: blocks, deposits, trees, witnesses, signatures, errors.
- src/utils – Helper algorithms: Merkle trees, Poseidon hashes, serialization, recursive-verifiability utilities.
- src/wrapper_config – Configuration for plonky2 backends (curve parameters, hashing).
- tests – End-to-end test harness.
- Cargo.toml, rustfmt, toolchain, coverage scripts – Build, test, and formatting config.

##### README for Additional Insights
- Circuits form a processing pipeline: each circuit both consumes and produces a public state.
- Recursive proofs: e.g. the Validity circuit wraps previous validity proofs.
- External dependencies: plonky2_keccak and plonky2_bn254 for hashing and curve operations.

##### Main Components and Their Relationships
– Transaction sets, Deposits, Withdrawals, Privacy-mining requests.

– Validity Circuit
– Balance Circuit (send/receive/update)
– Withdrawal Circuit
– Claim Circuit
– Proof of Innocence

– Data models, Merkle-tree structures, witness formats used by all circuits.

– Merkle-tree algorithms, hashing helpers, recursive-verifiability abstractions.

– plonky2 configurations (curve, hashing parameters).

– plonky2_keccak, plonky2_bn254

– Drives a full end-to-end proof generation and verification.

##### Architectural Patterns and Design Principles
- Modularity: Each circuit feature is its own directory, with processors, targets, and PIs.
- Separation of concerns:
– src/common for data definitions,
– src/utils for algorithms,
– src/circuits for ZK logic,
– wrapper_config for backend parameters.
- Recursion: Validity proofs wrap prior proofs; recursive-verifiable utilities support this.
- Extensibility: New circuits can plug into the same common and util layers, reusing wrapper_config.

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
    classDef logic fill:#9f6,stroke:#333,stroke-width:1px
    classDef common fill:#6cf,stroke:#333,stroke-width:1px
    classDef util fill:#6cf,stroke:#333,stroke-width:1px
    classDef config fill:#f96,stroke:#333,stroke-width:1px
    classDef test fill:#ccc,stroke:#333,stroke-width:1px

    subgraph "External Inputs" 
        Inputs["Transaction Sets, Deposits, Withdrawals, Privacy Requests"]:::external
    end

    subgraph "Circuit Modules" 
        Validity["Validity Circuit"]:::logic
        Balance["Balance Circuit"]:::logic
        Withdrawal["Withdrawal Circuit"]:::logic
        Claim["Claim Circuit"]:::logic
        ProofInnocence["Proof of Innocence"]:::logic
        TestUtils["Circuit Test Utilities"]:::logic
    end

    Common["Common Data Layer"]:::common
    Utils["Utility Layer"]:::util
    WrapperConfig["Wrapper Configuration"]:::config
    ExternalBackend["plonky2_keccak & plonky2_bn254"]:::external
    Outputs["Proofs & Updated Public State"]:::external
    TestHarness["End-to-End Test Harness"]:::test

    Inputs -->|"feeds inputs"| Validity
    Inputs -->|"feeds inputs"| Balance
    Inputs -->|"feeds inputs"| Withdrawal
    Inputs -->|"feeds inputs"| Claim
    Inputs -->|"feeds inputs"| ProofInnocence

    Validity -->|"uses types & witnesses"| Common
    Balance -->|"uses types & witnesses"| Common
    Withdrawal -->|"uses types & witnesses"| Common
    Claim -->|"uses types & witnesses"| Common
    ProofInnocence -->|"uses types & witnesses"| Common
    TestUtils -->|"uses types & witnesses"| Common

    Validity -->|"calls algorithms"| Utils
    Balance -->|"calls algorithms"| Utils
    Withdrawal -->|"calls algorithms"| Utils
    Claim -->|"calls algorithms"| Utils
    ProofInnocence -->|"calls algorithms"| Utils
    TestUtils -->|"calls algorithms"| Utils

    Validity -->|"reads config"| WrapperConfig
    Balance -->|"reads config"| WrapperConfig
    Withdrawal -->|"reads config"| WrapperConfig
    Claim -->|"reads config"| WrapperConfig
    ProofInnocence -->|"reads config"| WrapperConfig
    TestUtils -->|"reads config"| WrapperConfig

    WrapperConfig -->|"configures backend"| ExternalBackend

    Validity -->|"outputs proof & state"| Outputs
    Balance -->|"outputs proof & state"| Outputs
    Withdrawal -->|"outputs proof & state"| Outputs
    Claim -->|"outputs proof & state"| Outputs
    ProofInnocence -->|"outputs proof & state"| Outputs
    TestUtils -->|"outputs state for tests"| Outputs

    Outputs --> TestHarness
    TestHarness -->|"invokes circuits"| Validity
    TestHarness -->|"invokes circuits"| Balance
    TestHarness -->|"invokes circuits"| Withdrawal
    TestHarness -->|"invokes circuits"| Claim
    TestHarness -->|"invokes circuits"| ProofInnocence
    TestHarness -->|"invokes utils & common"| Common
    TestHarness -->|"verifies with backend"| ExternalBackend

    click Validity "https://github.com/internetmaximalism/intmax2-zkp/tree/main/src/circuits/validity"
    click Balance "https://github.com/internetmaximalism/intmax2-zkp/tree/main/src/circuits/balance"
    click Withdrawal "https://github.com/internetmaximalism/intmax2-zkp/tree/main/src/circuits/withdrawal"
    click Claim "https://github.com/internetmaximalism/intmax2-zkp/tree/main/src/circuits/claim"
    click ProofInnocence "https://github.com/internetmaximalism/intmax2-zkp/tree/main/src/circuits/proof_of_innocence"
    click TestUtils "https://github.com/internetmaximalism/intmax2-zkp/tree/main/src/circuits/test_utils"
    click Common "https://github.com/internetmaximalism/intmax2-zkp/tree/main/src/common"
    click Utils "https://github.com/internetmaximalism/intmax2-zkp/tree/main/src/utils"
    click WrapperConfig "https://github.com/internetmaximalism/intmax2-zkp/tree/main/src/wrapper_config"
    click TestHarness "https://github.com/internetmaximalism/intmax2-zkp/blob/main/tests/e2e.rs"
    click Outputs "https://github.com/internetmaximalism/intmax2-zkp/blob/main/src/lib.rs"

    class Inputs,ExternalBackend external
    class Validity,Balance,Withdrawal,Claim,ProofInnocence,TestUtils logic
    class Common common
    class Utils util
    class WrapperConfig config
    class TestHarness test
```
