# wakeuplabs-io/starkware-private-erc20 architecture

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

- Interactive diagram: https://gitdiagram.com/wakeuplabs-io/starkware-private-erc20
- Repository: https://github.com/wakeuplabs-io/starkware-private-erc20

## Overview

##### Main components
- Frontend (UI): Located in packages/ui. This is a React application (using TypeScript, Tailwind, etc.) that handles user interactions, connects to wallet providers (e.g., Argent), builds proofs, displays balances, and renders the flows (transfer, approve/transfer_from, deposit).
- API Service: Found in packages/api. This Node/TypeScript service mainly acts as a middleware to receive proof inputs, compute the zk proof (or adjust calldata as needed), and interact with the smart contracts.
- Circuits: Residing in packages/circuits with separate directories for “transfer”, “approve”, “transfer_from”, “deposit”, and a “common” component. These circuits are designed with Noir (using Nargo and Garaga for verifier generation) and represent the zero-knowledge proof logic that validates state transitions.
- Smart Contracts: Under packages/contracts, containing contract logic written in Cairo. This includes ERC-20 functionality (with extensions for privacy) and verifier integrations, along with deployment scripts.
- Supporting Assets & Infrastructure: The assets (demo videos, images) and configuration files (.env.example, sst.config.ts, GitHub workflows) indicate deployment-related files. The project also uses AWS for deployment (via SST) and includes “just” tasks for command-line operations.

##### Out the relationships and data flows
- The UI (frontend) interacts with both the API and smart contracts:
- Users use the UI to generate zk-wallets, build transactions, and view their token balances by querying on-chain events (commitment and nullifier events).
- It gathers user input (such as transfer amounts, scanning QR codes for receiver details, etc.) and communicates with the API to assemble and compute the zk proofs.
- The API acts as an intermediary, accepting proof inputs from the UI, computing safe calldata, and forwarding the instructions to the blockchain.
- The smart contracts (deployed on Starknet) rely on underlying circuits for verification:
- When a transfer or approval is submitted, the transaction first hits the smart contract, which then calls the deployed circuit verifier (e.g., transfer, transfer_from, approve, or deposit verifiers).
- The circuits validate the inputs (commitment validity, correct nullifier usage, balance consistency, etc.) and then the contract updates the state (emitting NewCommitment or NewNullifier events).
- The circuits themselves (in packages/circuits) are built and maintained separately and deployed as verifier contracts. They work in tandem with the contracts to ensure the correctness of calculated zk proofs.

##### Important design patterns and technologies
- Monorepo organization that separates concerns by package (UI, API, Circuits, Contracts).
- A clear full-stack separation, with dedicated layers for the client (React UI), server/middleware (TypeScript API), on-chain logic (Cairo smart contracts), and zero-knowledge proof logic (Noir circuits).
- The system makes heavy use of event-driven updates (blockchain events like NewCommitment and NewNullifier) to indirectly rebuild the user’s balance.
- Leveraging AWS (using SST for infra deployment) for deploying the API and circuit verifiers.
- Adoption of modern toolchains such as “just” for build/deployment scripts, and usage of Docker/Docker Compose for containerizing services (especially in the API package).

- Clearly labeled components:
- Frontend (UI/React)
- Backend API (Node/TypeScript)
- Zero-Knowledge Circuits (transfer, approve, transfer_from, deposit)
- Blockchain Smart Contracts (Cairo / Starknet)
- Infrastructure/Deployment (AWS, Docker, SST)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        UI["Frontend (UI)"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        API["API Service"]:::backend
    end

    %% Smart Contracts Layer
    subgraph "Smart Contracts Layer"
        ERC["ERC-20 & Privacy Logic"]:::contracts
        VI["Verifier Integrations"]:::contracts
        DS["Deployment Scripts"]:::contracts
    end

    %% Zero-Knowledge Circuits
    subgraph "Zero-Knowledge Circuits"
        TC["Transfer Circuit"]:::circuits
        AC["Approve Circuit"]:::circuits
        TFC["Transfer_From Circuit"]:::circuits
        DC["Deposit Circuit"]:::circuits
        CC["Common Circuit"]:::circuits
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        DI["Deployment & Infra"]:::infra
    end

    %% Connections
    UI -->|"proofInputPrep"| API
    API -->|"submitTransaction"| ERC
    ERC -->|"callsVerifier"| VI

    %% Verifier triggers specific circuits for proof validation
    VI -->|"verify_transfer"| TC
    VI -->|"verify_approve"| AC
    VI -->|"verify_transfer_from"| TFC
    VI -->|"verify_deposit"| DC
    VI -->|"verify_common"| CC

    %% Smart contract emits events back to UI
    ERC -- "state_update" --> UI

    %% Deployment influences API and Smart Contracts deployment
    DI -->|"deploy_API"| API
    DI -->|"deploy_SC"| ERC

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef contracts fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef circuits fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/ui"
    click API "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/api"
    click TC "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/circuits/transfer"
    click AC "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/circuits/approve"
    click TFC "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/circuits/transfer_from"
    click DC "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/circuits/deposit"
    click CC "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/circuits/common"
    click ERC "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/contracts/src/erc20"
    click VI "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/contracts/src/verifiers"
    click DS "https://github.com/wakeuplabs-io/starkware-private-erc20/tree/main/packages/contracts/scripts/deploy"
    click DI "https://github.com/wakeuplabs-io/starkware-private-erc20/blob/main/sst.config.ts"
```
