zk-mastermind is an implementation of the popular Mastermind game using zero-knowledge proofs for verification.
The live version of the game can be found here 🧠
This game was built using:
- Circom, the popular zkSNARK circuit programming language, for the actual mastermind zk circuit.
- snarkjs to generate zkSNARK proofs using the circuit behind an API.
- thirdweb to deploy the verifier smart contract
- Next for the frontend application and API.
- Chakra for the frontend UI components and styling.
Mastermind is a game of breaking codes. It involves two parties: the code maker and the code breaker.
Every game, the computer (the code maker) comes up with a random code. You're goal as the code breaker is to correctly guess the code within 10 turns.
Each time you make a guess, you can check it and the code breaker will tell you how close your guess was with two simple pieces of information:
- How many of the pegs in your guess are the correct color and in the correct position?
- How many of the pegs in your guess are the correct color but in the wrong position?
Using only this information, you have to break the code.
You may be wondering how zero-knowledge proofs fit into all this.
Consider the following question: how do you know that the code breaker is telling the truth when it gives you its response?
Since you don't have the code, the code breaker could be completely lying about how much of your guess is correct, and you wouldn't know. So how do we solve this issue?
What if the code breaker could prove to us that they have some specific code - and for that code, our guess has a specific number correct and partially correct - all without revealing the code itself.
This is exactly what zero-knowledge proofs let us do!
In fact, this is exactly what's happening with this game:
- You submit your guess and the code breaker responds with the number correct and partial, along with a zkSNARK proof that they are telling the truth.
- You can verify this proof by sending it to a smart contract deployed on-chain, which will confirm that the zkSNARK is valid.
Before running the project, you'll need to create a .env.local file in the root of the project and add the NEXT_PUBLIC_VERIFYING_CONTRACT_ADDRESS environment variable. This should be set to the address of the verifying contract deployed on-chain to goerli - you can use the contract address used by the actual game if you don't want to deploy your own: 0xC6997E09edF6AEFEf7c0D2240089D46A88B42347.
You can run the project locally after running yarn install by running the yarn dev command in the root directory. This will start the frontend and API on localhost:3000.
The actual zero-knowledge circuit for the mastermind game can be found in the circuits/mastermind/circuit.circom file.
After making any edits to this file, you'll have to compile the circuit with the yarn build:circuits command.
This comamnd will run through a number of steps necessary to securely compile and generate the circuit - including the trusted setup process using a Powers of Tau setup ceremony, where it will prompt you to enter a random string as entropy twice.
Once you build the circuits, you can generate and deploy a new verifier smart contract with the yarn build:contract and yarn deploy commands.
The core logic and interesting files in this project are:
circuits/mastermind/circuit.circom: the actual zero-knowledge circuit for the mastermind game, which includes an algorithm to verify that a specific guess and solution pair have a specific number of correct and partially correct pegs.contracts/Verifier.sol: the smart contract that verifies zkSNARK proofs generated by the circuit (via the Next API).pages/api/proof.ts: the Next API endpoint that generates zkSNARK proofs for a given guess and solution pair using the compiled WASM circuit.context/GameContext.tsx: the React context that manages the entire frontend game state, including the current guess, solution, and number of correct and partially correct pegs.components/Game.tsx: the React component that handles rendering of the entire game baord and logs section.