How tejaaswini/zeroking works
Overview:
ZeroKing is a trustless, privacy-preserving chess game that leverages zero‐knowledge cryptography to verify game moves and user actions. It has a full‐stack architecture with a frontend built on SvelteKit (in the ui directory) and a backend contracts layer (in the contracts directory) containing the core game logic, state management, and move validation. The UI interacts with a zkApp client (using o1js and zkAppWorker) to communicate with Mina protocols and enforce zero‐knowledge proofs.
Key Components:
Contracts (Backend – zk Proofs & Game Logic)
• Board Module (contracts/src/Board/Board.ts):
– Likely functions: initializeBoard(), renderBoard(); could include functions such as updateBoardState() based on moves.
• Chess Module (contracts/src/Chess.ts & contracts/src/Chess.test.ts):
– Central chess game engine. Possible functions: startGame(), processMove(), endGame().
• GameLogic Module (contracts/src/GameLogic/GameLogic.ts & GameLogic.test.ts):
– Contains logic for move validation and enforcing game rules. Expected functions: validateMove(), checkGameStatus(), triggerGameOver().
• GameState Module (contracts/src/GameState/GameState.ts & GameState.test.ts):
– Manages the state of the game. Functions might include: updateGameState(), getCurrentState(), resetGameState().
• Move Module (contracts/src/Move/Move.ts & Path.ts & tests):
– Handles move details and path validation. Functions such as: calculateMovePath(), validatePath(), parseMoveInput().
• Piece Module (contracts/src/Piece/Piece.ts & tests):
– Defines chess pieces and their behavior. Get functions like: getPieceType(), determineLegalMoves().
• PlayerState Module (contracts/src/PlayerState/PlayerState.ts & tests):
– Manages individual player information. Expected functions: updatePlayerStatus(), recordPlayerAction().
• Module (contracts/src/Position/Position.ts & tests):
– Handles board coordinates and positions. Likely includes: convertCoordinate(), validatePosition().
UI (Frontend – SvelteKit Application)
• Routes:
– Landing Page (+page.svelte): Provides .edu email login using zkEmail proof.
– Game Pages (game/+page.svelte, Board.svelte, DashboardLayout.svelte, etc.): The core Chess UI where players interact.
• UI Components:
– Reusable components (e.g., AuroConnect.svelte, ToastModal.svelte) and support for notifications (using French Toast).
• zkApp Integration:
– Located in ui/src/lib/zkapp (ZkappWorker.ts and ZkappWorkerClient.ts): Provides client-side integration with the zkApp for processing zero-knowledge proofs and interactions with Mina.
• Utility Functions:
– Additional UI libraries (like lib/Stopwatch.ts, lib/ellipsis.ts) to support user interactions and visual feedback.
External Interfaces & Technologies
• zkEmail: Provides .edu-only login through a zero-knowledge proof generation for identity verification.
• Mina blockchain: The underlying platform where on-chain move validation occurs.
• Wallet Integration: The project requires a Mina wallet (Auro) to interact with the zkApp.
• Notification System (French Toast): For clean notifications during game events.
• Testing: Jest configuration indicates thorough unit tests across GameLogic, Board, GameState, etc.
Relationships and Data Flow:
• The UI initiates user interactions:
• A user logs in using an .edu email, triggering zkEmail proof generation.
• On successful login, the interface displays the chess board and game controls.
• The UI communicates with the zkApp client layer (via ZkappWorker and ZkappWorkerClient) to forward move inputs.
• The zkApp client then interacts with the underlying contracts (chain or simulated layer) that run the game logic (modules such as Chess, GameState, Move, etc.)
• Between modules, functions like processMove(), validateMove(), updateGameState() are called to ensure each move is provably correct within the zero-knowledge circuit.
• There is also interaction with external services like the Mina blockchain network for move validation and, eventually, NFT minting for game outcomes.
Design Principles and Architectural Patterns:
• Separation of Concerns: UI components handle interactions and presentation, while smart-contract-like modules handle game logic, move validation, and state management.
• Modular Design: Each functional domain (Board, GameLogic, GameState, Move, Piece, PlayerState, Position) is encapsulated in its module.
• Test-Driven Development: Each module has accompanying tests (e.g., *.test.ts files) ensuring robust, verifiable logic.
• Event-Driven Flow: UI events (login, paper move submission, game resignation) generate data flows to backend modules that process and update game state.
• UI Layer:
• zkApp Client Layer:
• Game Logic / Contracts Layer:
• Board Module (with functions: initializeBoard(), updateBoardState())
• Chess Module (startGame(), processMove(), endGame())
• GameLogic Module (validateMove(), checkGameStatus(), triggerGameOver())
• GameState Module (updateGameState(), getCurrentState(), resetGameState())
• Move Module (calculateMovePath(), validatePath(), parseMoveInput())
• Piece Module (getPieceType(), determineLegalMoves())
• PlayerState Module (updatePlayerStatus(), recordPlayerAction())
• Module (convertCoordinate(), validatePosition())
• External Interfaces:
• UI → zkApp Client: For sending game moves and handling proofs.
• zkApp Client → Contracts/Smart Logic: For invoking functions like processMove() and validateMove().
• Contracts → External Blockchain: For on-chain move validations and subsequent notifications.
• External responses (game over events, NFT minting triggers) flow back through the chain to UI.
Naming Functions
• In the Contracts section, label:
– Board: initializeBoard(), renderBoard()
– Chess: startGame(), processMove(), endGame()
– GameLogic: validateMove(), checkGameStatus(), triggerGameOver()
– GameState: updateGameState(), getCurrentState(), resetGameState()
– Move: calculateMovePath(), validatePath(), parseMoveInput()
– Piece: getPieceType(), determineLegalMoves()
– PlayerState: updatePlayerStatus(), recordPlayerAction()
– Position: convertCoordinate(), validatePosition()
For this full-stack chess application:
• Clear segregation between the user interface and the backend (contracts) handling zero-knowledge proofs.
• Integration points with external services like zkEmail for secure login and Mina for blockchain interactions.
• Modular design of game logic, with each domain (Board, Move, etc.) treated as an independent component.
Final Notes for the Principal Software Engineer: