# yoii-inc/zk-mpc architecture

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

- Interactive diagram: https://gitdiagram.com/yoii-inc/zk-mpc
- Repository: https://github.com/yoii-inc/zk-mpc

## Overview

##### Major Components
- Core Cryptographic Libraries (arkworks/*): These directories encapsulate the basic math, field and polynomial operations, elliptic curve arithmetic, SNARK construction (groth16, marlin, r1cs-std, poly-commit, etc.), and curve definitions.
- MPC Sub-Crates:
– mpc-algebra: Implements MPC-friendly algebra types (e.g., MpcField, MpcVar) and operations.
– mpc-net: Handles networking, communication protocols among participants.
– mpc-trait: Encapsulates shared trait definitions for MPC computations.
- Application/Client Logic (src/): Implements high-level circuit definitions (various circuits, constraint definitions in input_circuit.rs and circuits/*), and modules for encryption (she) and zk-SNARK integration (groth16.rs, marlin.rs). It also includes orchestration of the preprocessing phase (producing necessary computation artifacts) and the online phase (executing MPC protocols).
- Examples & Scripts:
– Werewolf game (both CLI and standalone game binaries) that demonstrates using the MPC, secret input specification, and online computation.
– Benchmark scripts (in benches and docs) and various run-*.zsh scripts that orchestrate the overall process.

##### Relationships and Data Flow
- Preprocessing Phase: The “main” binary (src/main.rs) orchestrates the initialization of the MPC protocols where circuits, constraints, and cryptographic proofs (e.g., commitment generation, ZKP proofs) are generated using the underlying arkworks libraries and mpc-algebra.
- Online Phase: The online script (run_online.zsh) triggers the network module (mpc-net) to perform live multiparty computation, using secret inputs specified via JSON (inputs folder) and validated by circuit constraints.
- Interaction between Modules:
– The application layer (src/circuits, src/she, etc.) calls functions provided by the arkworks primitives to build circuits and generate proofs.
– The mpc-algebra and mpc-trait crates serve as wrappers/adapters that combine the abstract cryptographic operations with concrete MPC protocols.
– The mpc-net crate ensures that the different parties communicate their shares and results according to the SPDZ-like protocol delineated in the README.
– The examples (e.g., Werewolf game) illustrate a complete flow: input specification, preprocessing (via groth16 or marlin), and execution of an MPC-based online phase.

##### Architectural Patterns and Protocols
- Layered Design: Separate low-level cryptographic computations (arkworks libraries) from higher-level MPC coordination (mpc-algebra, mpc-net).
- Modularization: Each major cryptographic primitive and protocol is isolated into its own sub-crate (e.g., poly-commit, curves, nonnative), making it easier to understand dependencies.
- Dual-Phase Execution: The system distinctly separates the offline (preprocessing) and online computation phases, a common pattern in MPC design.
- Extensibility: The design supports multiple protocols (e.g., Groth16, Marlin, SHE) and allows users to plug in custom circuits or even custom game logic (as in Werewolf).

##### Technology and Framework Details
- Rust-based build system (Cargo with separate Cargo.toml files for each sub-crate).
- GitHub integration for continuous integration (see .github/workflows).
- Usage of Rust macros and constraints (see ff-macros, r1cs-std) to enforce field arithmetic and circuit synthesis.
- Shell scripts (zsh files) that help trigger different phases of the system.
- JSON-based input specification (via inputs/inputs.json) for secret parameters.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Cryptographic Libraries
    subgraph "Core Cryptographic Libraries"
        A1("Algebra"):::crypto
        A2("Crypto-Primitives"):::crypto
        A3("Curves"):::crypto
        A4("Groth16"):::crypto
        A5("Marlin"):::crypto
        A6("Nonnative"):::crypto
        A7("Poly-Commit"):::crypto
        A8("R1CS-Std"):::crypto
        A9("Snark"):::crypto
        A10("Std"):::crypto
    end

    %% MPC Modules
    subgraph "MPC Modules"
        B1("mpc-algebra"):::mpc
        B2("mpc-net"):::mpc
        B3("mpc-trait"):::mpc
    end

    %% Application Logic
    subgraph "Application Logic"
        C1("Main Orchestrator (src/main.rs)"):::app
        C2("Groth16 Module (src/groth16.rs)"):::app
        C3("Marlin Module (src/marlin.rs)"):::app
        C4("SHE Module (src/she.rs)"):::app
        C5("Circuit Definitions (src/circuits/input_circuit.rs)"):::app
        C6("Other Circuits (src/circuits/*)"):::app
        C7("JSON Input (inputs/inputs.json)"):::app
    end

    %% Examples & Scripts
    subgraph "Examples & Scripts"
        D1("Werewolf Game (CLI - examples/werewolf_cli/)"):::example
        D2("Werewolf Binary (examples/bin_werewolf.rs)"):::example
        D3("Online Phase Script (run_online.zsh)"):::example
        D4("Werewolf Script (run_werewolf.zsh)"):::example
        D5("Groth16 Script (run_groth16.zsh)"):::example
        D6("Marlin Script (run_marlin.zsh)"):::example
        D7("Benchmark & Other Scripts (benches & docs)"):::example
    end

    %% Data Flow Connections
    C1 -->|"calls"| B1
    C1 -->|"calls"| B3
    C1 -->|"utilizes"| A1
    C1 -->|"utilizes"| A2
    C1 -->|"utilizes"| A3
    C1 -->|"utilizes"| A4
    C1 -->|"utilizes"| A5
    C1 -->|"utilizes"| A7
    C1 -->|"utilizes"| A8
    C1 -->|"utilizes"| A9
    C1 -->|"utilizes"| A10
    C1 -->|"orchestrates"| C5
    C1 -->|"orchestrates"| C6
    C1 -->|"consumes"| C7
    D1 -->|"drives"| C1
    D3 -->|"triggers_online_phase"| B2
    B2 -->|"communicates_results"| C1

    %% Class Definitions for Colors
    classDef crypto fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef mpc fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef app fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef example fill:#FFFFE0,stroke:#000,stroke-width:2px;

    %% Click Events for Core Cryptographic Libraries
    click A1 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/algebra"
    click A2 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/crypto-primitives"
    click A3 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/curves"
    click A4 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/groth16"
    click A5 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/marlin"
    click A6 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/nonnative"
    click A7 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/poly-commit"
    click A8 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/r1cs-std"
    click A9 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/snark"
    click A10 "https://github.com/yoii-inc/zk-mpc/tree/main/arkworks/std"

    %% Click Events for MPC Modules
    click B1 "https://github.com/yoii-inc/zk-mpc/tree/main/mpc-algebra/"
    click B2 "https://github.com/yoii-inc/zk-mpc/tree/main/mpc-net/"
    click B3 "https://github.com/yoii-inc/zk-mpc/tree/main/mpc-trait/"

    %% Click Events for Application Logic
    click C1 "https://github.com/yoii-inc/zk-mpc/blob/main/src/main.rs"
    click C2 "https://github.com/yoii-inc/zk-mpc/blob/main/src/groth16.rs"
    click C3 "https://github.com/yoii-inc/zk-mpc/blob/main/src/marlin.rs"
    click C4 "https://github.com/yoii-inc/zk-mpc/blob/main/src/she.rs"
    click C5 "https://github.com/yoii-inc/zk-mpc/blob/main/src/circuits/input_circuit.rs"
    click C6 "https://github.com/yoii-inc/zk-mpc/tree/main/src/circuits/"
    click C7 "https://github.com/yoii-inc/zk-mpc/blob/main/inputs/inputs.json"

    %% Click Events for Examples & Scripts
    click D1 "https://github.com/yoii-inc/zk-mpc/tree/main/examples/werewolf_cli/"
    click D2 "https://github.com/yoii-inc/zk-mpc/blob/main/examples/bin_werewolf.rs"
    click D3 "https://github.com/yoii-inc/zk-mpc/blob/main/run_online.zsh"
    click D4 "https://github.com/yoii-inc/zk-mpc/blob/main/run_werewolf.zsh"
    click D5 "https://github.com/yoii-inc/zk-mpc/blob/main/run_groth16.zsh"
    click D6 "https://github.com/yoii-inc/zk-mpc/blob/main/run_marlin.zsh"
    click D7 "https://github.com/yoii-inc/zk-mpc/tree/main/benches"
```
