{"id":16742123,"url":"https://github.com/vplasencia/zkgames","last_synced_at":"2025-08-10T13:09:48.763Z","repository":{"id":42514543,"uuid":"479469267","full_name":"vplasencia/zkGames","owner":"vplasencia","description":"zkGames is a platform that allows users to play zk (zero knowledge) games and mint an NFT as proof that they have won.","archived":false,"fork":false,"pushed_at":"2022-07-08T15:16:27.000Z","size":8593,"stargazers_count":68,"open_issues_count":0,"forks_count":18,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T01:11:11.345Z","etag":null,"topics":["blockchain","circom","circuit","snarkjs","solidity","zero-knowledge","zkp"],"latest_commit_sha":null,"homepage":"https://zkgames.vercel.app/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vplasencia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-08T16:48:04.000Z","updated_at":"2025-02-07T21:10:25.000Z","dependencies_parsed_at":"2022-09-01T18:00:27.169Z","dependency_job_id":null,"html_url":"https://github.com/vplasencia/zkGames","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vplasencia/zkGames","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vplasencia%2FzkGames","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vplasencia%2FzkGames/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vplasencia%2FzkGames/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vplasencia%2FzkGames/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vplasencia","download_url":"https://codeload.github.com/vplasencia/zkGames/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vplasencia%2FzkGames/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269728453,"owners_count":24465654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","circom","circuit","snarkjs","solidity","zero-knowledge","zkp"],"created_at":"2024-10-13T01:22:43.723Z","updated_at":"2025-08-10T13:09:48.736Z","avatar_url":"https://github.com/vplasencia.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zkGames \u003c!-- omit in toc --\u003e\n\n![zkGamesRepoImage](https://user-images.githubusercontent.com/52170174/164951489-8f3d9b0a-4334-4dfb-b0d6-b6a87ff81424.png)\n\nzkGames is a platform that allows users to play zk (zero knowledge) games and mint an NFT as proof that they have won.\n\n\u003c!-- The project is currently on [Harmony Testnet](https://explorer.pops.one/) and the frontend is hosted on [Vercel](https://github.com/vercel/vercel). --\u003e\n\nThe project is currently on [Harmony Mainnet](https://explorer.harmony.one/) and the frontend is hosted on [Vercel](https://github.com/vercel/vercel).\n\nzkGames has 3 games so far: Futoshiki, Skyscrapers and Sudoku.\n\nzkGames Link:\n\n\u003chttps://zkgames.one/\u003e\n\nzkGames Demo Video:\n\n\u003chttps://youtu.be/EpeK3WzmS8Y\u003e\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n\n- [Project Structure](#project-structure)\n  - [circuits](#circuits)\n  - [contracts](#contracts)\n  - [zkgames-ui](#zkgames-ui)\n- [Zero Knowledge Structure](#zero-knowledge-structure)\n- [Run Locally](#run-locally)\n  - [Clone the Repository](#clone-the-repository)\n  - [Run circuits](#run-circuits)\n  - [Run contracts](#run-contracts)\n  - [Run zkgames-ui](#run-zkgames-ui)\n- [Steps to Add a New Game](#steps-to-add-a-new-game)\n- [Some Images of the zkGames Application](#some-images-of-the-zkgames-application)\n  - [Initial page](#initial-page)\n  - [Futoshiki Game](#futoshiki-game)\n  - [Skyscrapers Game](#skyscrapers-game)\n  - [Sudoku Game](#sudoku-game)\n\n## Project Structure\n\nThe project has three main folders:\n\n- circuits\n- contracts\n- zkgames-ui\n\n### circuits\n\nThe [circuits folder](/circuits/) contains all the circuits used in zkGames.\n\nTo learn more about the zkGames circuits, read the [README file](/circuits/README.md) inside the `circuits` folder.\n\n### contracts\n\nThe [contracts folder](/contracts/) contains all the smart contracts used in zkGames.\n\nTo learn more about the zkGames smart contracts, read the [README file](/contracts/README.md) inside the `contracts` folder.\n\n### zkgames-ui\n\nThe [zkgames-ui folder](/zkgames-ui/) contains the zkGames frontend.\n\nTo learn more about the zkGames frontend, read the [README file](/zkgames-ui/README.md) in the `zkgames-ui` folder.\n\n## Zero Knowledge Structure\n\nThe following graphic shows the structure of the most important zero knowledge elements of the zkGames project.\n\n```text\n├── circuits\n│   ├── futoshiki\n│   │   ├── futoshiki.circom\n│   ├── skyscrapers\n│   │   ├── skyscrapers.circom\n│   ├── sudoku\n│   │   ├── sudoku.circom\n├── contracts\n│   ├── contracts\n│   │   ├── Futoshiki\n│   │   │   ├── Futoshiki.sol\n│   │   │   ├── verifier.sol\n│   │   ├── Skyscrapers\n│   │   │   ├── Skyscrapers.sol\n│   │   │   ├── verifier.sol\n│   │   ├── Sudoku\n│   │   │   ├── Sudoku.sol\n│   │   │   ├── verifier.sol\n├── zkgames-ui\n│   ├── public\n│   │   ├── zkproof\n│   │   │   ├── futoshiki\n│   │   │   │   ├── futoshiki.wasm\n│   │   │   │   ├── futoshiki_0001.zkey\n│   │   │   ├── skyscrapers\n│   │   │   │   ├── skyscrapers.wasm\n│   │   │   │   ├── skyscrapers_0001.zkey\n│   │   │   ├── sudoku\n│   │   │   │   ├── sudoku.wasm\n│   │   │   │   ├── sudoku_0001.zkey\n│   ├── zkproof\n│   │   ├── futoshiki\n│   │   │   ├── snarkjsFutoshiki.js\n│   │   ├── skyscrapers\n│   │   │   ├── snarkjsSkyscrapers.js\n│   │   ├── sudoku\n│   │   │   ├── snarkjsSudoku.js\n│   │   ├── snarkjsZkproof.js\n```\n\n## Run Locally\n\n### Clone the Repository\n\n```bash\ngit clone https://github.com/vplasencia/zkGames.git\n```\n\n### Run circuits\n\nTo run cicuits, go inside the `circuits` folder:\n\n```bash\ncd circuits\n```\n\nThen, follow the intructions in the [README file](/circuits/README.md) in the `circuits` folder.\n\n### Run contracts\n\nTo run contracts, go inside the `contracts` folder:\n\n```bash\ncd contracts\n```\n\nThen, follow the intructions in the [README file](/contracts/README.md) in the `contracts` folder.\n\n### Run zkgames-ui\n\nTo run the frontend, go inside the `zkgames-ui` folder:\n\n```bash\ncd zkgames-ui\n```\n\nThen, follow the intructions in the [README file](/zkgames-ui/README.md) in the `zkgames-ui` folder.\n\n## Steps to Add a New Game\n\nSteps to follow to add a new game (in each step you can check how is done with the other games):\n\n1\\. **Create the required circom circuits:**\n\n- Inside the circuits folder, create a new folder and inside the new folder, create the necessary circom circuits.\n- Compile the circuit and generate the `wasm`, `zkey` and `verifier.sol` files using the `execute.sh` file.\n\n2\\. **Create the necessary smart contracts:**\n\n- Inside the `contracts/contracts` folder, create a new folder with the necessary smart contracts. Add here the verifier.sol generated before using snarkjs.\n- Change the solidity version to `^0.8.4` (it is the version used in the other smart contracts) and the contract name (to `\u003cgameName\u003eVerifier`) in `verifier.sol`.\n- Test the functionalities of the new smart contracts in `scripts/run.js`.\n- Update the `contracts/scripts/deploy.js` file and deploy smart contracts.\n\n3\\. **Create the user interface of the game:**\n\n- Inside `zkgames-ui/components`, add a new folder to create all the components needed to render the game.\n- Add a new page inside `zkgames-ui/pages` to access the new game.\n- Create the css of that page inside `zkgames-ui/styles`, called `\u003cGameName\u003e.module.css`.\n- Add an image inside `zkgames-ui/assets` to represent the game (width: 700 pixels and height: 700 pixels).\n- Inside `zkgames-ui/public/zkproof` add a new folder with the wasm and zkey elements generated before.\n- Inside `zkgames-ui/utils/abiFiles`, add a new folder with the `json` abi file of the smart contract.\n- In `zkgames-ui/utils/contractaddress.json`, add the new contract address.\n- In `zkgames-ui/zkproof`, create a new folder and inside the new folder create a new file called `snarkjs\u003cNewGame\u003e.js` with the code to export the call data.\n- In `zkgames-ui/components/gameList.js` add the game as follows:\n\n```javascript\n {\n   nameGame: \"\u003cnameGame\u003e\",\n   imageGame: nameGameImage,\n   urlGame: \"/\u003cnameGame\u003e\",\n }\n```\n\n## Some Images of the zkGames Application\n\n### Initial page\n\n![InitialPage](https://user-images.githubusercontent.com/52170174/164957823-ea7dfb78-c151-4830-b714-e3f66a424d57.png)\n\n### Futoshiki Game\n\n![FutoshikiGame](https://user-images.githubusercontent.com/52170174/164957832-95c27552-8248-453c-a6e3-7bca2d97d087.png)\n\n### Skyscrapers Game\n\n![SkyscrapersGame](https://user-images.githubusercontent.com/52170174/164957837-959530b8-399b-4551-8a37-145e9ff70e3e.png)\n\n### Sudoku Game\n\n![SudokuGame](https://user-images.githubusercontent.com/52170174/164957841-08d9166d-99ba-4dbe-88b1-86a507734e6c.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvplasencia%2Fzkgames","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvplasencia%2Fzkgames","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvplasencia%2Fzkgames/lists"}