zkGuessWho Game

ZKU Cohort 3 Final Project - zkGuessWho is an on-chain “guess who” game.

The game is a variant of the “guess who” game https://en.wikipedia.org/wiki/Guess_Who%3F . A two player game where they try to identify the other’s chosen character. Zk proofs is used to keep the characters and the game privacy.

A player can get clues from the opponent's character by asking yes/no questions about the character's characteristics. There is only one chance to guess the opponent's character. If it is guessed, the game is won if not lost.

The broads consist on 24 characters and the character is defined by a set of 4 characteristics.

dApp: https://zk-guess-who.vercel.app/

demo: https://youtu.be/vziLUXe4Oc0

Project Structure

The project the following folders:

• circuits
• contracts
• frontend
• scripts
• docs (to be removed)

Circuits

The circuits folder contains all the circuits.

To learn more about the circuits, read the README file inside the circuits folder.

Contracts

The contracts folder contains all the smart contracts used in zkGames.

To learn more about the smart contracts, read the README file inside the contracts folder.

Frontend

The frontend folder contains the dApp frontend.

To learn more about the frontend, read the README file in the frontend folder.

Development

Installation

Install all folders/modules dependencies

$ yarn install

Test

Test all modules

$ yarn test

Local deployment

Local deploy contracts in hardhat node and dApp

In a shell console

$ cd contracts
$ npx hardhat node

In an other console

$ yarn dev-deploy

Script Utils

To copy circuits to contracts

$ scripts/copy-circuit-contract.sh 

To copy zks utils and abi to frontend

$ scripts/copy-zk-frons.sh

Installation Possible Errors

On npm install when trying to install circom_tester dependency

$ npm install

npm notice Beginning October 4, 2021, all connections to the npm registry - including for package installation - must use TLS 1.2 or higher. You are currently using plaintext http to connect. Please visit the GitHub blog for more information: https://github.blog/2021-08-23-npm-registry-deprecating-tls-1-0-tls-1-1/

Run yarn install instead of npm install

$ yarn install

Networks and Contracts Addresses

You can find the networks and contract address in networks.json

WARNING!!!

Browser Local Storage is used to store the game (the salt and selected character) per account if you clear the local store data could be inconsistent and you may BLOCK the GAME. In this case, please "Quit the game" through the game board link or let me know to free the Room.

Future Work

• UI/UX improvements
• Remove answer button unifying answer/ask in one message
• show all characters in a UI board
• Multi room game implementation.
• Random board.
• Graphical characters.
• ...