zkMaze

Note: zkMaze is a demonstration project showcasing zero-knowledge proofs. It is not intended for production use.

zkMaze is a web3 maze game that leverages ZKPs to verify player moves revealing the maze configuration.

In zkMaze, the maze is generated and committed via a Merkle tree using the Poseidon hash function by a host, and players submit moves that are validated through zk-SNARK proofs.

The system supports multiple difficulty levels—each with a fixed maze size and a set number of moves per proof—to.

The architecture includes:

• Maze Generation & Commitment: Host generates a maze (with configurable sizes such as 8×8, 16×16, and 32×32) and computes a Merkle tree over the maze cells.
• Zero-Knowledge Circuits: Pre-generated circuits (single-move and multi-move) verify that moves are valid against the committed maze. Each difficulty level is parameterized by grid size, Merkle tree depth, and fixed moves per proof.
• CLI, Frontend & Backend: A CLI for hosting and playing locally, a front-end for web gameplay, with a back-end for API.
• Trusted Setup & On-Chain Verification: A Powers of Tau ceremony and Groth16 setup generate zk-SNARK parameters, and a Solidity verifier contract is deploy for on-chain proof verification + game state.

On-Chain Contracts:

• MazeGame: 0x7404209B933F419Cc4150224ef6c54D49bb50040
• 8x8 Verifier: 0xeca57b8114fd125e60195be9c4c50420fa6bdbe3
• 16x16 Verifier: 0xa92aae02d4824f4ee1c509e8b9bb6643bc2705e3
• 32x32 Verifier: 0x791731b268c53e2c635c47cc8b47c814fb8bff60

Base Sepolia

• MazeGame: 0xA0aB27726488e676e3C05AaBc857a500323Bc485
• 8x8 Verifier: 0x39658ba8840A5c0652Df9b1C031d62c37DBc4A68
• 16x16 Verifier: 0xF180f1210614FC1bba959EB2543E320b9ae125c4
• 32x32 Verifier: 0x1392e7406163D22237B9b203f5B6C3F552f30063

Frontend Deployment

• Compile website

  cd src/frontend && pnpm build
  

• Copy and paste build files in thieu.dev public/zkmaze folder

---

Dependencies

• circom: For compiling zk-SNARK circuits.
• foundry: A smart contract development framework for Ethereum.
• pnpm: Fast, disk space efficient package manager.
• snarkjs: Tool for proving and verifying zk-SNARK proofs. (installed via pnpm automatically)
• Node.js: Runtime environment for CLI and server components. (use nvm for version management)
• Make: For executing build and setup commands.

---

Quick Start

• Install circom:

Follow the circom installation guide.

• Install foundry:

Follow the foundry installation guide.

• Install dependencies:

  pnpm install

• Run the entire ceremony (trusted setup and circuit compilation):

  make

if it fails:

• double-check that you have installed all dependencies correctly, especially circom and foundry.

• run

  make zkeys
  make all

• Start local development environment:

  pnpm all

• Start each service separately:

  anvil # in a separate terminal
  make deploy
  docker compose up -d

• Clean generated files:

  make clean

---

Detailed Instructions

1. Trusted Setup and Circuit Compilation

zkMaze uses a Powers of Tau ceremony to generate secure parameters for zk-SNARK proofs.

• Powers of Tau Targets:

  • make ptau_new: Initialize a new Powers of Tau ceremony.
  • make ptau_contrib1, make ptau_contrib2, make ptau_contrib3: Sequential contributions to the ptau file.
  • make ptau_verify: Verify the integrity of the current ptau file.
  • make ptau_beacon: Incorporate a random beacon for additional randomness.
  • make ptau_prepare: Prepare the ptau file for Phase 2 (trusted setup).
  • make ptau_verify_final: Verify the finalized ptau file.

• Circuit Compilation Targets:

  • make compile_circuit: Compile the primary single-move circuit.
  • make compile_circuit_multi: Compile the multi-move circuit for higher difficulty levels.

2. ZKey Setup and Proof Generation

Set up the Groth16 proving keys and generate zk-SNARK proofs for maze moves.

• ZKey Setup Targets:

  • make zkey_setup: Create the initial zkey.
  • make zkey_contrib1, make zkey_contrib2, make zkey_contrib3: Add contributions to the zkey.
  • make ptau_zkey_verify: Verify the intermediate zkey integrity.
  • make ptau_zkey_verify_final: Finalize and verify the final zkey.
  • make zkey_export_verification: Export the verification key for proof verification.

• Proof Generation Targets:

  • make fullprove: Generate a zk-SNARK proof using the input JSON, compiled circuit, and final zkey.
  • make verify_proof: Verify the generated proof using the verification key.
  • make export_verifier: Export a Solidity verifier contract for on-chain proof verification.
  • make export_calldata: Export formatted Solidity calldata for on-chain integration.

3. Running the Game

zkMaze supports multiple modes via its CLI, allowing both host and player interactions.

• Host Mode:

  • Generate a maze configuration and commit the maze with a chosen difficulty (easy, normal, or hard).
  • Example:

    pnpm cli host --difficulty normal

• Player Mode:

  • Generate circuit inputs for moves and play interactively (WASD controls) or in non-interactive mode.
  • Example:

    pnpm cli play

4. Monorepo Structure

The repository is organized as a monorepo with dedicated workspaces:

• frontend: Contains the interactive UI for gameplay and visualization.

• cloudflare-worker: Contains the Cloudflare Worker for handling API requests.

---

Contributing

Contributions are highly welcome! Please review the CONTRIBUTING.md and CODE_OF_CONDUCT.md before contributing. Open an issue to discuss significant changes before submitting a pull request.

---

License

This project is licensed under the MIT License.