Trustless, Decentralized Poker Powered by Zero-Knowledge Proofs
- Overview
- Demo
- Features
- How It Works
- Mental Poker Implementation
- Aleo Smart Contracts
- Architecture
- Repository Structure
- Challenges
- Getting Started
- Deployments
- Tech Stack
- Future Roadmap
- ETHGlobal Submission
- Contributing
- License
- Acknowledgments
EthGlobal Trifecta 2024 Hackathon - ZK Track Submission
ZKPoker is a trustless, decentralized poker platform powered by zero-knowledge proofs built on Aleo. Our implementation of mental poker eliminates the need for a trusted third party to deal cards or manage the game, ensuring complete fairness and true decentralization.
Most existing web3 poker solutions still rely on centralized components for card dealing and verification. ZKPoker solves the fundamental issue of "mental poker" - playing a fair card game without a trusted dealer - using modern cryptography and Aleo's privacy-preserving execution environment.
- Live Demo: https://zkpoker.vercel.app
- Video Demo: Watch on Loom
- Fully Decentralized Card Games: No trusted dealer or central server needed for shuffling and dealing cards
- Provably Fair: Zero-knowledge proofs ensure fairness without revealing players' cards
- Privacy Preserving: Players' strategies and hands are kept private until showdown
- On-chain Game Logic: All game mechanics run on Aleo smart contracts
- Beautiful UI: Modern, intuitive interface for seamless gameplay
- Wallet Integration: Connect with Leo wallet for secure authentication
- Responsive Design: Play on any device with adaptive layout
ZKPoker uses advanced cryptographic techniques to implement mental poker protocols on Aleo:
- Secure Shuffling: Players collaboratively shuffle an encrypted deck without seeing card values
- Private Card Dealing: Cards are dealt to players while preserving privacy
- Verifiable Actions: All player actions (check, bet, fold) are validated on-chain
- Zero-Knowledge Showdown: Only revealed hands are compared at showdown, maintaining privacy
flowchart TD
A[Game Initialization] --> B[Deck Creation]
B --> C[Player 1 Shuffle]
C --> D[Player 2 Shuffle]
D --> E[Player 3 Shuffle]
E --> F[Encrypted Dealing]
F --> G[Betting Rounds]
G --> H[Community Cards Reveal]
H --> I[More Betting Rounds]
I --> J[Showdown]
J --> K[Winner Determination]
K --> L[Prize Distribution]
L --> M[New Hand]
M -->|Next Round| B
Mental poker is a cryptographic problem of playing a fair card game over a distance without a trusted third party. Our implementation combines several techniques:
We use a modified version of the SRA protocol for secure card operations:
- Card Representation: Each card is represented as a unique 128-bit number
- Card Transformation: We use simple XOR operations for encryption/decryption to minimize ZK circuit complexity
- Multi-Key Encryption: Cards are encrypted with player-specific keys, requiring cooperation for decryption
// From zk_sra_encryption.aleo
function transform_card(card: u128, key: u128) -> u128 {
return card ^ key; // Simple XOR operation
}
sequenceDiagram
participant P1 as Player 1
participant P2 as Player 2
participant BC as Blockchain
Note over P1,P2: Card Encryption Process
P1->>P1: Generate key K₁
P2->>P2: Generate key K₂
P1->>BC: Encrypt card C with K₁: C' = C ⊕ K₁
BC->>P2: Send encrypted card C'
P2->>BC: Re-encrypt with K₂: C'' = C' ⊕ K₂
BC->>P1: Send double-encrypted card C''
Note over P1,P2: Decryption for Showdown
P1->>BC: Reveal K₁
P2->>BC: Reveal K₂
BC->>BC: Decrypt C'' = C'' ⊕ K₁ ⊕ K₂ = C
We implement a secure shuffling protocol where multiple players participate:
- Initial Deck Creation: A standard 52-card deck is initialized
- Player Shuffling: Each player applies their own secret shuffle to the encrypted deck
- Zero-Knowledge Verification: Players prove they performed a valid shuffle without revealing the permutation
// From zk_deck_shuffle.aleo
transition full_shuffle(
seed1: i8,
seed2: i8,
seed3: i8,
deck: [[u128; 26]; 2]
) -> [[u128; 26]; 2] {
// Complex shuffling logic goes here
// ...
return shuffled_deck;
}
The main contract manages the poker game state, including:
- Player turns and actions
- Blinds and betting rounds
- Card dealing and community card revelation
- Showdown and winner determination
// From mental_poker_trifecta.aleo
struct Game {
player1: address,
player2: address,
player3: address,
buy_in: u64,
deck: [[u128; 26]; 2],
state: u8,
dealer_button: u8,
players_out: u8,
players_folded: u8,
// Additional fields...
}
stateDiagram-v2
[*] --> WaitingForPlayers
WaitingForPlayers --> DeckInitialization
DeckInitialization --> DeckShuffling
DeckShuffling --> DealingHoleCards
DealingHoleCards --> PreFlopBetting
PreFlopBetting --> DealingFlop
DealingFlop --> FlopBetting
FlopBetting --> DealingTurn
DealingTurn --> TurnBetting
TurnBetting --> DealingRiver
DealingRiver --> RiverBetting
RiverBetting --> Showdown
Showdown --> WinnerDetermination
WinnerDetermination --> NextHand
NextHand --> DeckInitialization
PreFlopBetting --> WinnerDetermination: All but one player folds
FlopBetting --> WinnerDetermination: All but one player folds
TurnBetting --> WinnerDetermination: All but one player folds
RiverBetting --> WinnerDetermination: All but one player folds
Our implementation consists of four interconnected Aleo programs, maintained in a separate repository as a Git submodule in the leo-program directory. The contracts repository is available at https://github.com/henrikkv/poker.
The core contract managing the poker game, player actions, and state transitions:
- Game Creation: Initialize new games with blinds and buy-ins
- Player Management: Handle joining, betting, and folding
- Game Flow: Control betting rounds and turn progression
- State Machine: Manage the complex state transitions of a poker game
Implements the cryptographic primitives for card operations:
- Card Encryption: Transform cards using player-specific keys
- Card Decryption: Allow selective revelation of cards
- Multi-Card Processing: Efficiently handle operations on multiple cards
Handles operations on the entire deck:
- Deck Encryption: Encrypt the entire deck in parts
- Card Selection: Extract and process specific cards
- Hand Creation: Form player hands and community cards
Implements secure shuffling algorithms:
- Permutation Generation: Create unpredictable yet verifiable card orderings
- Multi-Party Shuffling: Allow each player to contribute to the shuffle
- Shuffle Verification: Ensure the integrity of the shuffle
Our ZKPoker implementation follows a modular architecture that separates concerns while allowing for secure interactions between components:
graph TB
subgraph "Frontend Application"
UI[User Interface]
GS[Game State]
WC[Wallet Connector]
WW[Web Workers]
end
subgraph "Aleo Blockchain"
subgraph "ZKPoker Contracts"
MPT[mental_poker_trifecta.aleo]
SRA[zk_sra_encryption.aleo]
DO[zk_deck_operations.aleo]
DS[zk_deck_shuffle.aleo]
end
BC[Blockchain State]
end
UI <--> GS
GS <--> WC
GS <--> WW
WC <--> MPT
WW <--> MPT
MPT <--> SRA
MPT <--> DO
MPT <--> DS
SRA <--> BC
DO <--> BC
DS <--> BC
MPT <--> BC
classDef frontend fill:#f9f9f9,stroke:#333,stroke-width:1px
classDef contract fill:#d8e8f4,stroke:#3c7aa8,stroke-width:1px
classDef blockchain fill:#e8f4d8,stroke:#5a8a3c,stroke-width:1px
class UI,GS,WC,WW frontend
class MPT,SRA,DO,DS contract
class BC blockchain
The architecture enables:
- Decentralized Execution: All game logic runs on the Aleo blockchain
- Client-Side Cryptography: Web Workers handle heavy cryptographic operations
- Modular Design: Each contract has a specific responsibility
- Secure Communication: All on-chain interactions are verifiable and private
The ZKPoker project is organized with a clear separation of concerns:
zkpoker/
├── src/ # Frontend application source code
│ ├── app/ # Next.js application routes
│ ├── components/ # React components
│ ├── services/ # Service modules (sound, game logic)
│ └── worker-poker.ts # Web Worker for Aleo operations
├── public/ # Static assets
│ ├── cards/ # Card images
│ ├── sounds/ # Game sounds and music
│ └── *.svg # UI elements and icons
├── leo-program/ # Git submodule for Aleo contracts
│ ├── src/ # Main contract code
│ ├── imports/ # Dependent contract modules
│ │ ├── zk_sra_encryption/
│ │ ├── zk_deck_operations/
│ │ └── zk_deck_shuffle/
│ └── build/ # Compiled contract artifacts
├── deployments.md # Deployment records and transaction IDs
└── README.md # Project documentation
To clone the repository with the submodule:
git clone --recurse-submodules https://github.com/yourusername/zkpoker.gitOr if you've already cloned the repository:
git submodule update --init --recursiveBuilding a trustless poker platform on Aleo presented several significant challenges:
Zero-knowledge proof generation for complex operations like shuffling is computationally intensive. We optimized our implementation by:
- Breaking down shuffle operations into smaller steps
- Using XOR-based encryption instead of more complex cryptography
- Optimizing data structures for Leo's constraints
Coordinating multiple players in a decentralized environment required careful protocol design:
- State machine with clear transitions for each player action
- Fallback mechanisms for disconnections or timeouts
- Incentive structures to prevent cheating
Balancing privacy with gameplay verification:
- Ensuring players can't see others' hole cards
- Allowing selective revelation during showdown
- Preventing collusion between players
Creating a smooth experience despite blockchain constraints:
- Implementing optimistic UI updates before on-chain confirmation
- Handling transaction failures gracefully
- Providing appropriate feedback during cryptographic operations
Integrating with Aleo wallets presented unique challenges:
- Limited Wallet Ecosystem: The Aleo ecosystem is still emerging, with fewer wallet options compared to EVM chains
- Adapter Compatibility: We faced issues with version compatibility in the
@demox-labs/aleo-wallet-adapterpackages - Transaction Signing: Implementing proper request handling for transaction signing and decryption permissions
- Error Handling: Working around unpredictable wallet behavior during connection and transaction signing
- Web Worker Integration: Coordinating between the main thread and web workers for wallet operations
To overcome these challenges, we implemented:
// Custom wallet connection handling with fallbacks
useEffect(() => {
if (!connected && publicKey) {
console.log('Wallet not connected. Please connect your wallet to play.')
setGameNotification({
message: 'Please connect your wallet to play',
type: 'error',
})
}
}, [connected, publicKey])
// Web Worker communication for blockchain operations
if (aleoWorker) {
aleoWorker.postMessage({
type: 'create_game',
gameId,
privateKey,
buyIn: playerData.chips,
})
}- Node.js 18+
- pnpm 8+
- Leo (Aleo SDK)
- A Leo-compatible wallet (like Leo Wallet extension)
- Clone the repository with submodules
git clone --recurse-submodules https://github.com/yourusername/zkpoker.git
cd zkpoker- Install dependencies
pnpm install- Start the development server
pnpm dev- Open http://localhost:3000 in your browser
To deploy the Leo programs to Aleo:
- Navigate to the Leo program directory
cd leo-program- Build the programs
leo build- Deploy to Aleo local testnet
leo deploy --recursive -yOur contracts are currently deployed on the Aleo local testnet using Amareleo Chain.
Here's a summary of our deployment costs to the local testnet:
| Program | Transaction ID | Cost (credits) |
|---|---|---|
| zk_deck_shuffle.aleo | at1pvpkuumy3r56eqyszyyt85ml6uzjfj3v23alau3d0z7s594jm5yqpl4lp0 | 108.432550 |
| zk_sra_encryption.aleo | at12cvm6ucvyeagkgf32ca93yh8m2h2lm5222xqdr84ak7n5rga7ygqra5uz5 | 13.611800 |
| zk_deck_operations.aleo | at1a2tsk3mj2sdc5a9yrnh5cxmjac7jp09zu4ekl6t99jy7hgc5nyzqc37fnl | 41.227700 |
| mental_poker_trifecta.aleo | at1rk88g2nwcjzdq75pfnsz0a6xd00gjgewvswzjzkxrzuaczn7qvxqexpmc0 | 46.994400 |
For detailed deployment information, see our deployments.md file.
- Next.js 15: React framework with App Router
- React 19: UI library
- TypeScript: Type-safe JavaScript
- Tailwind CSS: Utility-first CSS framework
- Howler.js: Audio library for game sounds
- Leo Wallet Adapter: Connect with Leo wallets
- Aleo: Privacy-focused L1 blockchain
- Leo: Language for zero-knowledge applications
- SnarkVM: Execution environment for Aleo programs
- Web Workers: Handle heavy cryptographic operations off the main thread
- ESLint/Prettier: Code formatting and linting
- pnpm: Fast, disk-efficient package manager
- VS Code: Recommended editor with Leo extensions
- Git Submodules: Manage contract code separately from frontend
gantt
title ZKPoker Development Roadmap
dateFormat YYYY-MM-DD
section Completed Features
Secure Deck Shuffling :done, 2025-03-20, 2025-03-23
Hand Evaluation Engine :done, 2025-03-20, 2025-03-23
Mental Poker System Implementation :done, 2025-03-20, 2025-03-30
section In Progress
Public Testnet Deployment :crit, active, 2025-03-24, 2025-03-24
Complete Texas Hold'em Implementation :active, 2025-03-30, 2025-04-09
section Game Variants
Sit-n-Go Tournaments :2025-04-10, 2025-05-01
Omaha Implementation :2025-05-02, 2025-06-01
Short Deck (6+ Hold'em) :2025-06-02, 2025-07-01
section Platform Features
Mobile App Development :2025-05-01, 2025-06-15
Multi-Language Support :2025-06-15, 2025-06-30
Advanced Analytics :2025-07-01, 2025-07-15
Community Features :2025-07-15, 2025-08-01
- Advanced Betting Rules: Implement full No-Limit Texas Hold'em betting structure
- Hand Evaluation: Complete 5-card combination evaluation for accurate hand strength calculation
- Side Pots: Support for multiple side pots in all-in scenarios
- Tournament Structure: Blind level increases and elimination progression
- Sit-n-Go: Quick tournament format with 6-9 players
- Multi-Table Tournaments: Support for larger player pools with table balancing
- Omaha: Four-card variant with more complex drawing possibilities
- Short Deck: Remove 2-5 cards for more action-packed gameplay
- Mobile App: Native mobile experience with push notifications
- Multi-Language Support: Internationalization for global audience
- Advanced Analytics: Hand history and strategy tools for players
- Community Building: Chat functions, player profiles, and achievements
- Public Testnet Deployment: Resolve current 500 errors and deploy to public Aleo testnet
- Optimized Circuits: Further reduction in ZK circuit complexity
- Improved Tutorial: Step-by-step onboarding for new players
- Enhanced Security: Additional measures to prevent collusion and cheating
- Wallet Compatibility: Support for additional Aleo wallets as they become available
ZKPoker was submitted to the ETHGlobal Trifecta 2024 Hackathon in the Zero Knowledge track.
- Submission Page: https://ethglobal.com/showcase/mental-poker-1e0kd
We welcome contributions to ZKPoker! Please see our CONTRIBUTING.md file for guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
- The Aleo team for their incredible platform and tools
- Amareleo for their support with a light local testnet
- EthGlobal Trifecta 2024 for the opportunity to showcase this project
- The mental poker research community for laying the cryptographic foundations
Built with ❤️ by the ZKPoker Team for EthGlobal Trifecta 2025