How wakeuplabs-io/starkware-private-erc20 works
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)