How privacy-scaling-explorations/maci works
Components Identification
• On-Chain Components:
• Smart Contracts (found in packages/contracts) that implement the core anti-collusion voting logic, including deployment tasks, gatekeepers, poll factories, and message processors.
• Off-Chain Services:
• Coordinator Service (apps/coordinator): Responsible for coordinating message processing, authentication, and integrating with the on-chain contracts.
• Relayer Service (apps/relayer): Handles message relaying between users and the blockchain.
• Supporting Libraries/Modules:
• Cryptography (packages/crypto): Low-level cryptographic functions and utilities.
• Circuits (packages/circuits): zk-SNARK circuits (written in circom) used for zero-knowledge proofs.
• Core Business Logic (packages/core): Implements vote tallying, message processing, and the MACI state machine (via MaciState).
• Domain Objects (packages/domainobjs): Defines high-level classes to represent domain-specific entities (e.g., ballots, commands, keys).
• CLI Tool (packages/cli): Command-line interface that enables deployment and user interactions with the protocol.
• SDK (packages/sdk): Developer toolkit for integrating and interacting with MACI.
• Testing Suite (packages/testing): Comprehensive integration and unit tests.
• User Interface & Documentation:
• Website (apps/website): Provides documentation, blogs, and guides for developers and integrators.
Relationships and Interactions
• That the Coordinator and Relayer services interact with the contracts deployed on the blockchain (via Hardhat configurations and deployment scripts).
• Underlying dependency: The business logic (core), cryptographic operations (crypto), and zk-SNARK circuits (circuits) all feed into how the protocol processes and secures vote messages.
Architectural Patterns and Design Principles
• Modular / Workspace Structure: Emphasize the separation of concerns across different packages (each with its own unit tests, deployment scripts, and CI workflows).
• Layered Architecture:
• Presentation/Interface Layer (CLI, Website, SDK)
• Application/Service Layer (Coordinator, Relayer)
• Domain/Logic Layer (Core, Domain Objects, Cryptography, Circuits)
• CI/CD Integration: Include a note that automated pipelines (under .github/workflows) are used to build, test, and deploy components.
Relevant Technologies and Frameworks
• TypeScript is the primary programming language.
• Hardhat for smart contract compilation, testing, and deployment.
• Circom for writing and compiling zk-SNARK circuits.
• NestJS (implied by nest-cli.json files in coordinator and relayer) for structuring the backend services.
• pnpm as the mono-repo/package manager.
• GitHub Actions for CI/CD workflows.
Detail and Clarity
• Component is clearly defined with its purpose in the system.
• Directional dependencies are illustrated (for example, show that the Core business logic depends on the cryptographic and circuit functionalities).