zkShuffle Alpha Documentation

zkShuffle provides an easy access for Ethereum developers to create "mental poker" games utilizing zero-knowledge proofs. The concept of "mental poker" refers to the implementation of a fair gaming protocol over a communication system that doesn't involve any trusted third-party. The term was initially proposed in 1979 by Adi Shamir, Ron Rivest, and Leonard Adleman in a paper where they discussed the idea of creating a fair poker game in which players could not see each other's cards or shuffle and deal the cards themselves. The challenge of building a “mental poker” game is to ensure that no one can cheat while maintaining the communications reliable, efficient and low-cost.

zkShuffle is an efficient mental poker emphasizing the reduction of gas costs on Ethereum. zkShuffle can be applied beyond poker to many different types of card or board games where secure and fair card shuffle and deal are required without a trusted third party.

State Diagram

The following state diagram provides an overview of the game process managed by the ShuffleManager contract. To initiate a new game, it must first be created. Upon creation, the manager contract assigns a unique ID to this game and players can join the game with that ID. Once the final player has registered, the game starts. Players can check the current turn within the game. If it's their turn to perform an action (shuffle, deal or open), they carry out the action accordingly.

Main Components

Circuits

This directory contains Circom code to implement zkShuffle encryption and decryption circuits. It also contains the corresponding verifier contracts generated by snarkjs. Read more

Solidity Contracts

This directory contains contracts that manage shuffled deck and verify proofs on-chain. It comprises the manager contract, ShuffleManager.sol, as well as supplementary contracts tasked with operations such as encryption and decryption. The manager contract is responsible for creating new games, registering players, checking game states, and performing various operations required for game management. This frees developers from considering technical details such as card shuffling and dealing, such that developers can focus on game logic contracts. Read more

Typescript SDK (Alpha)

This directory contains typescript SDK as the standard interface to interact with shuffle manager contract. Developers could use SDK to generate zk proof generation and gaming private and public key management. We have released it as an npm package for easy import in front-end implementation. Read more

Game Contracts

Developers need to implement game contracts for a complete game, which contains game logic such as the order of players to take action and effects of each card. Please review this tutorial for a simple example: Tutorial

Use Case - zkHoldem

zkHoldem is one unique use case where zkShuffle helps to fundamentally eliminate the trust issue existing in the traditional online poker industry.

Through the utilization of zkShuffle, zkHoldem is able to provide a card shuffling & dealing mechanism that is 100% decentralized, where all players on the table will contribute a piece of randomness to the card deck they are using, effectively guaranteeing the fairness of card distribution in a zk identity-preserving way.

Website: www.zkholdem.xyz