How albertobas/zk-connect-four works
• Front-end Application: Mark the Next.js React app (found under apps/web). This is responsible for the user interface, state management, API endpoints (inside pages/api), and interactions with the blockchain.
• Smart Contracts Backend: Represent the Solidity contracts located in apps/contracts. Include the Hardhat configuration, deploy scripts, and deployment artifacts (deployment JSON files). Show that these contracts are deployed on a blockchain network (e.g., Sepolia or localhost), with data flows related to game state and verification.
• Circuits Module: Capture the Circom circuits under apps/circuits. Note that these circuits include the game logic needed to generate zk-SNARK proofs (e.g., the connect-four.circom file) and also the related unit tests and export scripts. Include the dependency on the Powers of Tau file (in apps/circuits/ptau) necessary for setting up circuit parameters.
• Machine Learning / DQN Agent: Represent the ML component located within apps/web/model. Highlight that it comprises Python scripts (agent.py, training.py, etc.), Jupyter notebooks, and exported neural network models. This component trains and generates the policy (and corresponding ONNX models) used by the UI for providing an AI opponent.
• Shared Packages and Configurations: Optionally add a component for shared packages (in packages/) that contain utility libraries (e.g., eslint configurations, tsconfig, UI components in packages/ui) used across workspaces. This shows modularity and reuse across the front end and possibly contracts/circuits configuration.
Relationships and Data Flow
• That when a game reaches a conclusion, the UI interacts with the smart contracts for submitting or verifying zk-SNARK proofs. Connect the circuits module to both the UI and the smart contracts to show this interaction.
• AI component feeding into the user experience by having the front end request game moves from the DQN agent and use the ML predictions (including loading models, e.g., from ONNX files in apps/web/model/exports) to play against users.
Architectural Patterns and Important Technologies
• Separation of concerns among the three pillars: proof generation (Circuits), blockchain logic (Smart Contracts), and user interaction (Next.js front end).
• Integration points:
• The Circom circuits are a critical part of validating game outcomes via zk-SNARK proofs.
• The Hardhat-based smart contract layer manages game state and proof verification on-chain.
• The Next.js application bridges user actions with blockchain calls and manages state updates.
• The machine learning module implements reinforcement learning to train a DQN agent for game play. It also exports trained models which are consumed by the front end.
• Key technologies near each component:
• Circuits: Circom, TypeScript (for tests and scripts)
• Contracts: Solidity, Hardhat, TypeScript (for deploy scripts)
• Web: Next.js, React, TypeScript, PostCSS
• ML: Python, PyTorch, ONNX
• Additional shared tools: eslint, Prettier, pnpm, Turborepo
Essential Elements
• Component labels for each module and sub-system.
• A clear separation of the full-stack layers (front end, backend smart contracts, circuits proof system, and ML module).
• Notations for external dependencies (e.g., the Powers of Tau file dependency, external blockchain networks like Sepolia or localhost emulation).