ZK Word Mastermind Game on StarkNet

This project implements the classic Word Mastermind game on StarkNet, leveraging Zero-Knowledge Proofs (ZKPs) for fair and private gameplay. Players try to guess each other's secret codes, and feedback (hits/blows) is verified on-chain using ZK proofs generated with Noir and Garaga, ensuring honesty without revealing the secret codes prematurely.

The game features a User Interface (UI) built with a modern web stack, allowing players to easily interact with the game, create/join games, submit guesses, and manage ZK proof generation for feedback.

This repository is based on the scaffold-garaga starter, providing a foundation for Noir+Garaga+Starknet applications with in-browser proving.

Table of Contents

• ZK Word Mastermind Game on StarkNet
  • Table of Contents
  • Overview
  • Features
  • Game Flow
  • Tech Stack
  • Project Structure
  • Installation & Setup
  • Development Workflow
    • 1. Build Noir Circuit
    • 2. Generate Witness (Optional - for testing circuit logic)
    • 3. Generate Verification Key
    • 4. Generate Cairo Verifier Contract (with Garaga)
    • 5. Start Local StarkNet Devnet
    • 6. Declare & Deploy Verifier Contract
    • 7. Declare & Deploy Mastermind Game Contract
    • 8. Prepare & Run the UI Application
  • Useful Links

Overview

Mastermind is a code-breaking game for two players. In this ZK version:

1. Each player sets a secret 4-character code (e.g., 'A', 'B', 'C', 'D').
2. Players commit to a cryptographic hash of their secret code on-chain.
3. Players take turns guessing each other's codes.
4. When providing "hit" (correct character, correct position) and "blow" (correct character, wrong position) feedback, the player whose code was guessed generates a ZK proof. This proof, verified by an on-chain Cairo verifier contract (generated by Garaga), confirms the accuracy of the feedback without revealing the secret code.
5. The main Mastermind game contract manages game state, player actions, and interacts with the ZK verifier.

Features

• Classic Mastermind Gameplay: Two players, secret codes, guesses, and hit/blow feedback.
• On-Chain Game Logic: Player registration, game creation/joining, turn management, and win/loss/tie conditions handled by a StarkNet Cairo smart contract.
• Secret Code Commitment: Cryptographic commitments (Poseidon hashes) to secret codes prevent mid-game changes.
• ZK-Verified Feedback: Noir circuits define the logic for hit/blow calculation, and Garaga generates the Cairo verifier for UltraHonk proofs, ensuring fair feedback.
• User-Friendly Web Interface: Allows players to interact with the game, including managing ZK proof aspects seamlessly.
• StarkNet Integration: Built for the StarkNet L2 network.

Game Flow

1. Connect Wallet & Register: Players connect their StarkNet wallets (e.g., Argent X, Braavos) via the UI and register a player name.
2. Create/Join Game: A player can create a new game or join an existing one.
3. Commit Solution Hash: Both players commit a hash of their secret code (e.g., 4 unique uppercase letters) and a salt.
4. Gameplay (Turns):
   • Player A guesses Player B's code.
   • Player B (via the UI) calculates hits & blows. The UI then helps generate a ZK proof for this feedback using the Noir circuit and Barretenberg.
   • Player B submits the proof and the H&B counts to the Mastermind contract, which uses the Garaga-generated verifier to confirm.
   • Roles reverse for Player B to guess Player A's code.
5. Game End: The game ends if a player guesses correctly (4 hits) or if the maximum number of rounds is reached (tie).
6. Reveal Solution (Optional): Players can reveal their actual secret code and salt for full transparency.

Tech Stack

• ZK Circuits: Noir Language
• Proving Backend: Barretenberg (for UltraHonk proofs)
• ZK Verifier Generation: Garaga (Noir -> Cairo Verifier)
• Smart Contracts: Cairo for StarkNet
• Blockchain: StarkNet
• Frontend Application: (React, TypeScript, Vite, Starknet-React, Scaffold-Stark).
• Package Management (JS): Bun
• StarkNet Tooling: sncast.

Project Structure

• packages/circuits/: Contains the Noir circuit (src/main.nr) for hit/blow calculation and proof generation logic.
• packages/contracts/: Contains the Cairo smart contracts:
  • packages/contracts/mastermind: contains main game logic contract.
  • packages/contracts/verifier: The Garaga-generated ZK verifier contract.
• /packages/app/: Contains the frontend user interface application.
• Makefile: Defines common commands for installation, building, and deployment.

Installation & Setup

Ensure you have Node.js >= 20 installed.

1. Install Bun (Package Manager):

   make install-bun

2. Install Noir and Barretenberg (Specific Versions for ZK):

   make install-noir
   make install-barretenberg

3. Install StarkNet Toolkit (via asdf): This command will install asdf if you don't have it, then install the StarkNet tools.

   make install-starknet

4. Install StarkNet Devnet: For spawning a local StarkNet chain.

   make install-devnet

5. Install Garaga (Python 3.10 required): Make sure you have Python 3.10.

   make install-garaga

Note on Versions: Specific versions of Noir, Barretenberg, and Garaga are crucial for compatibility. If you encounter issues, double-check that the installed versions match those expected by the scaffold-garaga base or this project's specific lockfiles/dependencies.

Development Workflow

This workflow outlines the steps from writing your Noir circuit to running the full-stack application.

1. Build Noir Circuit

Compile the Noir circuit packages/circuits/src/main.nr:

make build-circuit

2. Generate Witness (Optional - for testing circuit logic)

Provide sample inputs in packages/circuits/Prover.toml and execute the circuit to generate a witness:

make exec-circuit

This generates packages/circuits/target/witness.gz.

3. Generate Verification Key

Generate the verification key for your compiled circuit:

make gen-vk

This creates packages/circuits/target/vk.

4. Generate Cairo Verifier Contract (with Garaga)

Use Garaga to convert the Noir verification key into a deployable Cairo verifier contract:

make gen-verifier

This will generate contracts/src/verifier.cairo (or similar path).

5. Start Local StarkNet Devnet

In a separate terminal, start your local StarkNet development network:

make devnet

You can also use:

yarn chain

Which supports predeploy more accounts and is more suitable for the frontend application.

Note the RPC URL and predefined account addresses/private keys.

6. Declare & Deploy Verifier Contract

You'll need a StarkNet account funded on your devnet.

• Initialize Account File The Makefile have a like make accounts-file to set up account.

• Declare the Verifier Contract: Upload the verifier contract's code to the devnet.

  make declare-verifier

  This command (defined in Makefile) typically uses sncast. Note the class_hash output(You will need to put this into the mastermind contract in the VERIFIER_CLASSHASH constant.

• Deploy the Verifier Contract: Instantiate the declared verifier contract class.

  make deploy-verifier

  You will need to update the class_hash in the Makefile. Note the deployed verifier contract_address.

7. Declare & Deploy Mastermind Game Contract

The Mastermind game contract (packages/contracts/mastermind) needs to know the class hash of the ZK verifier (You can insert it into the constant VERIFIER_CLASSHASH in the lib.cairo).

• Build, Declare, and Deploy the Mastermind Contract:

  yarn deploy

8. Prepare & Run the UI Application

1. Install Frontend Dependencies (if not already done by top-level installs):

   yarn install:client

2. Run the UI Development Server:

   yarn start

   Open your browser to the local address provided http://localhost:5173. You should now be able to interact with the deployed Mastermind game!

Useful Links

• Noir Language:
  • Quickstart
  • Documentation
• Garaga:
  • Documentation
  • Deploy Noir SNARK Verifier on StarkNet
• Scaffold-garaga:
  • [GitHub](https://github.com/keep-starknet-strange/scaffold-garaga
• Scaffold-Stark:
  • GitHub
  • Website
• StarkNet:
  • StarkNet.js Docs
  • StarkNet Quickstart
  • StarkNet Foundry (Sncast) 101
• Cairo Language:
  • The Cairo Book