# 0xbow-io/privacy-pools-core architecture

> Architecture diagram of the GitHub repository 0xbow-io/privacy-pools-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0xbow-io/privacy-pools-core
- Repository: https://github.com/0xbow-io/privacy-pools-core

## Overview

##### Project type and purpose
- This is a monorepo implementing a blockchain privacy protocol (“Privacy Pool”) that combines zero‑knowledge circuits, on‑chain smart contracts, a middleware relayer, and a TypeScript SDK.
- Its goal is to let users deposit assets publicly, then withdraw them privately by proving membership in an approved set via ZK proofs.

##### File structure
- Top‑level: GitHub workflows, docs, ops/Helm‑chart, Yarn workspace packages.
- packages/circuits: Circom circuits that define ZK proof logic, builds to WASM, R1CS, zKeys.
- packages/contracts: Solidity smart contracts (managed with Foundry), deployable on EVM.
- packages/relayer: Node/TypeScript service exposing HTTP endpoints, holds a lightweight DB (SQLite), submits proofs & txns to chain.
- packages/sdk: TypeScript client library; wraps circuits, web3 provider, and contract ABI calls.
- ops/chart: Helm chart for deploying relayer (or other services) to Kubernetes.
- docs/: Static documentation site (Docusaurus).

##### README for additional insights
- Confirms four core logical layers: Circuits, Contracts, Relayer, SDK.
- Mentions support for native & ERC20 assets, an approved‐address set, and compliance.

##### Elements
- UI → SDK → Circuits → SDK → (Relayer or direct) → Contracts → Blockchain.
- Contracts → Events → Relayer → SDK → UI.
- Middleware (Relayer + DB) in another.
- On‑chain (Contracts + Blockchain) in a third.
- Deployment/infrastructure (Helm, Kubernetes) in a fourth.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    User["User / UI"]:::client

    %% Off-chain Compute
    subgraph "Off-chain Compute"
        SDK["SDK Layer"]:::offchain
        CircuitsSrc["Zero-Knowledge Circom Sources"]:::offchain
        CircuitsBuild["Circuits Build Artifacts (WASM, zKey)"]:::offchain
        CircuitsSetup["Circuits Trusted Setup"]:::offchain
    end

    %% Middleware
    subgraph "Relayer Service"
        Relayer["Relayer Service"]:::middleware
        Handlers["Relayer HTTP Handlers"]:::middleware
        Config["Relayer Configuration & JSON Schemas"]:::middleware
        Routes["Relayer Routes"]:::middleware
        Logic["Relayer Service Logic"]:::middleware
        Web3Prov["Relayer Web3 Provider"]:::middleware
        DB["Relayer Database (SQLite)"]:::middleware
    end

    %% On-chain Components
    subgraph "On-chain"
        ContractsSrc["Smart Contracts Source Code"]:::onchain
        Verifiers["Contracts Verifiers"]:::onchain
        Chain["Blockchain Network"]:::onchain
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Helm["Kubernetes / Helm Chart"]:::infra
        Docs["Documentation Site"]:::infra
        CI["GitHub Workflows"]:::infra
    end

    %% Flow
    User -->|"invoke SDK API"| SDK
    SDK -->|"fetch/compile circuits"| CircuitsSrc
    CircuitsSrc --> CircuitsBuild
    CircuitsSrc --> CircuitsSetup
    CircuitsBuild --> SDK
    CircuitsSetup --> SDK
    SDK -->|"submit tx via provider"| ContractsSrc
    SDK -->|"send proof & payload"| Relayer
    Relayer --> Handlers
    Handlers --> Routes
    Routes --> Config
    Routes --> Logic
    Logic --> Web3Prov
    Logic --> DB
    Web3Prov --> ContractsSrc
    ContractsSrc -->|"deploy/verifies ZK proof"| Chain
    Verifiers --> Chain
    Chain -->|"emit events"| Relayer
    Relayer -->|"push notifications"| SDK
    Helm --> Relayer

    %% Click Events
    click CircuitsSrc "https://github.com/0xbow-io/privacy-pools-core/tree/dev/packages/circuits/circuits"
    click CircuitsBuild "https://github.com/0xbow-io/privacy-pools-core/tree/dev/packages/circuits/build"
    click CircuitsSetup "https://github.com/0xbow-io/privacy-pools-core/tree/dev/packages/circuits/trusted-setup"
    click SDK "https://github.com/0xbow-io/privacy-pools-core/blob/dev/packages/sdk/src/index.ts"
    click Relayer "https://github.com/0xbow-io/privacy-pools-core/tree/dev/packages/relayer"
    click Handlers "https://github.com/0xbow-io/privacy-pools-core/tree/dev/packages/relayer/src/handlers"
    click Config "https://github.com/0xbow-io/privacy-pools-core/tree/dev/packages/relayer/src/config"
    click Routes "https://github.com/0xbow-io/privacy-pools-core/blob/dev/packages/relayer/src/routes/index.ts"
    click Logic "https://github.com/0xbow-io/privacy-pools-core/blob/dev/packages/relayer/src/services/privacyPoolRelayer.service.ts"
    click Web3Prov "https://github.com/0xbow-io/privacy-pools-core/blob/dev/packages/relayer/src/providers/web3.provider.ts"
    click DB "https://github.com/0xbow-io/privacy-pools-core/blob/dev/packages/relayer/src/providers/sqlite.provider.ts"
    click ContractsSrc "https://github.com/0xbow-io/privacy-pools-core/tree/dev/packages/contracts/src/contracts"
    click Verifiers "https://github.com/0xbow-io/privacy-pools-core/tree/dev/packages/contracts/src/contracts/verifiers"
    click Helm "https://github.com/0xbow-io/privacy-pools-core/tree/dev/ops/chart"
    click Docs "https://github.com/0xbow-io/privacy-pools-core/tree/dev/docs"
    click CI "https://github.com/0xbow-io/privacy-pools-core/tree/dev/.github/workflows"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:1px
    classDef offchain fill:#bbf,stroke:#333,stroke-width:1px
    classDef middleware fill:#bfb,stroke:#333,stroke-width:1px
    classDef onchain fill:#fbb,stroke:#333,stroke-width:1px
    classDef infra fill:#ffd,stroke:#333,stroke-width:1px
```
