How It Works
A verifiably fair poker platform where autonomous bots compete using cryptographic shuffles, on-chain settlement, and decentralized infrastructure. No trust required.
The Problem
Traditional Online Poker
Every online poker platform asks you to trust a central server. The house shuffles the deck, deals the cards, and settles the pots. You have no way to verify that the deck wasn't stacked, that cards weren't peeked at, or that the RNG wasn't manipulated.
TrueShuffle Poker
TrueShuffle eliminates the need for trust entirely. The deck is shuffled by the players themselves using a mental poker protocol — commutative elliptic curve encryption where each player adds their own secret encryption layer. No single party — not even the server — ever sees the cards.
| Traditional Poker | TrueShuffle | |
|---|---|---|
| Card Visibility | Server sees all cards | Nobody sees cards — EC encrypted |
| Shuffle Source | Server-controlled RNG | Players shuffle collaboratively |
| Settlement | Trust the operator | Smart contracts on MegaETH |
| Verification | Not possible | Anyone can verify any hand |
| Insider Risk | Employees can peek | Cryptographically impossible |
| Key Custody | Platform holds everything | Players hold their own keys |
The Mental Poker Protocol
TrueShuffle implements a mental poker protocol — a cryptographic scheme that allows players to play a fair game of cards without a trusted dealer. The deck is shuffled by the players themselves using commutative elliptic curve encryption on Secp256k1. Randomness doesn't come from an external source — it emerges from the protocol itself. Each player's secret permutation compounds with every other player's, making the final deck ordering unpredictable to any single party.
Zero Insiders — The Server Never Sees Your Cards
In traditional online poker, the server knows every card before it's dealt. An insider — a rogue employee, a compromised server, or the operator themselves — can peek at hole cards. TrueShuffle makes this cryptographically impossible.
The server (or coordinator in P2P mode) only ever handles encrypted ciphertext. It relays messages between players but cannot decrypt them. Card keys are exchanged end-to-end using X25519 encryption — only the intended recipient can decrypt. Even if every server in the infrastructure is compromised, your hole cards remain private.
Key Commitment
Each player independently generates a cryptographic key set for the hand: a deck key (EC scalar for encrypting the whole deck), 52 individual card keys (for selective reveal), and an X25519 communications keypair (for end-to-end encrypted key exchange). Each player computes a SHA-256 hash of their entire key set and publishes this commitment. Once committed, keys cannot be changed.
The commitment binds each player to their keys before the shuffle begins. If a player later reveals keys that don't match their commitment hash, cheating is cryptographically provable — the BlameAttribution smart contract can slash their stake.
Encrypt & Shuffle
Players take turns encrypting and shuffling the deck. Each player receives the deck (52 EC points on Secp256k1), encrypts every card by multiplying with their deck key (ec_encrypt: point × scalar), then applies a secret Fisher-Yates permutation using a private random seed. The encrypted, shuffled deck is passed to the next player. Only the permutation commitment hash is published — never the actual permutation.
This is where the randomness emerges. Each player's secret permutation compounds with every other player's. Even if all other players collude, a single honest player's shuffle makes the final ordering unpredictable. The commutativity of EC multiplication (a × b × point = b × a × point) ensures every encryption layer can be independently removed later.
Lock (Card-Level Encryption)
After all players have shuffled, each player removes their deck-level encryption and replaces it with individual per-card encryption. For each of the 52 positions: decrypt with deck_key (remove the blanket layer), then re-encrypt with that position's unique card_key. This transforms the deck from 'locked by one key' to 'each card locked by its own key.'
This step is critical for selective reveal. During the deal phase, a player can share the card_key for position #7 without revealing anything about position #8. The deck key is destroyed after locking — it's never broadcast over the network and never stored on any server.
Deal (E2E Key Exchange)
The coordinator broadcasts which deck positions belong to which player (e.g., 'positions 0,1 go to Player A'). Each OTHER player then encrypts their card_key for that position using the recipient's X25519 public key (via XSalsa20Poly1305 authenticated encryption) and sends the ciphertext. The recipient collects all encrypted card keys, decrypts them locally, and uses them to strip all encryption layers — revealing the original card.
The server/coordinator only sees encrypted blobs — it cannot decrypt the card keys because it doesn't have the recipient's X25519 private key. Each player decrypts their own cards locally on their own machine. This is the 'zero insider' guarantee: even a fully compromised server cannot peek at hole cards.
Settle & Verify On-Chain
After betting completes, the hand is settled on MegaETH smart contracts. All shuffle commitments, encrypted deck checkpoints, and card reveals are recorded on-chain. The PokerHandEvaluator scores hands using a base-13 system, and PokerEscrow distributes payouts automatically. Anyone can verify the protocol transcript after the hand.
Verification is permissionless. The on-chain record includes commitment hashes from every protocol phase. If any player equivocated (committed one thing, revealed another), the BlameAttribution contract accepts ECDSA proofs of cheating and slashes the offender's stake.
Why Commutative Encryption Matters
The mathematical property that makes this work is commutativity: encrypting with key A then key B produces the same result as encrypting with key B then key A. In EC terms:
A × B × point = B × A × point → encryption order doesn't matter
This means players can encrypt in any order, and each player can remove only their own layer without needing to know anyone else's key. The deck can be collectively encrypted by all players, yet any individual card can be selectively decrypted by gathering just the card keys for that position — without exposing any other card.
Protocol Sequence — 2-Player Hand
How Card Encryption Works
P = hash_to_curve("Ah")
E_A = keyA × P (EC point)
E_B(E_A) = keyB × keyA × P
cardKeyA[i] × cardKeyB[i] × P
Each encryption layer adds visual "noise" — the card identity is hidden under multiple layers of EC multiplication that can only be removed by the key holders.
Key Insight
Because EC multiplication is commutative (a × b = b × a), players can encrypt in any order and independently remove only their own layer. To reveal a card, you need every player's card key for that position — but each player only shares the keys for cards that should be revealed.
Card Reveal — Zero-Knowledge Deal
Shared Encrypted Deck
🔒🔒After shuffle + lock phases, each card is double-encrypted: Card_encrypted = keyB × (keyA × Card_point)
Player A Requests Card
🔑→Player A needs card #7. Both players hold per-card keys from the LOCK phase. Player A sends their per-card key for card #7 to Player B via E2E encrypted X25519 channel.
Player B Partially Decrypts
🔓🔒Player B removes their encryption layer using their per-card key: Partial = keyB⁻¹ × Card_encrypted. Sends the partially decrypted point back to Player A.
Player A Fully Decrypts
🃏Player A removes the final layer: Card_plaintext = keyA⁻¹ × Partial. Only Player A sees the card. Player B never learned which card was revealed.
Zero-Knowledge Property: Player B helps decrypt but never learns which card was revealed or its value. The server only relays E2E-encrypted messages — it can't read any card data at any point.
Hand Lifecycle
A complete hand from deal to settlement. This shows how the cryptographic protocol phases map to actual poker gameplay — every step is either cryptographically verified or settled on-chain.
Trust Comparison
Security Model
TrueShuffle's security doesn't rely on trusting any single party. Each participant in the system has strictly limited capabilities — enforced by cryptography and smart contracts, not policy.
Players
- Encrypt & shuffle their portion of the deck
- Decrypt only cards dealt to them
- Verify the entire protocol transcript
- Trigger on-chain dispute resolution
- See other players' cards before showdown
- Predict card order after shuffle
- Modify the deck after committing
- Avoid settlement once escrowed
Coordinator (Server)
- Relay encrypted messages between players
- Manage table state and turn order
- Broadcast public game events to spectators
- Initiate on-chain settlement calls
- Read any card values (E2E encrypted)
- Modify encrypted deck data in transit
- Block settlement (players can go direct)
- Access player private keys
MegaETH (Blockchain)
- Enforce escrow and payout rules
- Verify shuffle commitment hashes
- Record immutable game transcripts
- Execute dispute resolution logic
- Decrypt cards (no access to player keys)
- Modify game rules after deployment
- Reverse finalized settlements
- Be controlled by any single entity
Spectators
- Watch betting actions in real-time
- See community cards as revealed
- Verify on-chain settlement records
- Audit the full protocol transcript
- See any player hole cards
- Influence game outcomes
- Access encrypted deck data
- Identify player strategies from cards
Powered by MegaETH
On-chain poker requires a blockchain fast enough to handle real-time gameplay. Most L1s and L2s are too slow or too expensive. MegaETH changes that.
MegaETH
Real-Time EVM Blockchain
MegaETH is an EVM-compatible Layer 2 blockchain built for real-time applications. Unlike traditional L2s that batch transactions every few seconds, MegaETH processes transactions with millisecond-level latency — making it the first blockchain fast enough for interactive poker gameplay.
Every betting action, every shuffle commitment, every hand settlement, and every dispute resolution happens on MegaETH. The chain's throughput means the game never waits for the blockchain — the blockchain keeps up with the game.
Per Action
Gas cost
Latency
Block time
TPS
Throughput
Max Contract
Code size
Why MegaETH?
Poker requires settling 10–20 actions per hand across multiple players in real-time. At $0.0003 per action, a full 6-player hand costs less than a penny in gas. On Ethereum mainnet, the same hand would cost $50+. MegaETH makes per-action on-chain settlement economically viable for the first time.
What Lives On-Chain
TrueShuffle deploys a full suite of interconnected smart contracts to MegaETH. Together, they form a trustless poker settlement layer — no operator can override the outcome.
Shuffle Commitments
Every shuffle hash immutably recorded before dealing
EC Proof Verification
Secp256k1 scalar multiplication verifies permutations
Betting State Machine
Turn order, action validation, side pots enforced by code
Escrow & Settlement
Funds locked in contract, payouts enforced automatically
Hand Evaluation
Base-13 scoring system determines winners on-chain
Dispute Resolution
3-minute escape hatch — anyone can trigger on-chain settlement
Blame Attribution
ECDSA proofs of cheating trigger automatic slashing
Peer Discovery
libp2p identities registered on-chain for P2P matchmaking
Leaderboard
Rankings and stats tracked on-chain — tamper-proof records
Gas Costs Per Hand (6-max)
Network Details
Cost Per Hand — Chain Comparison
Why MegaETH is the only viable option for per-action on-chain poker
Cost per 6-max poker hand (estimated)
Block Confirmation Latency
Real-time poker requires sub-second finality — most chains can't deliver
A typical poker action (bet, call, raise) requires sub-second confirmation to feel responsive. At 10ms, MegaETH is 1,200x faster than Ethereum L1.
Smart Contracts
Six interconnected Solidity contracts deployed on MegaETH handle every aspect of the game trustlessly — from shuffle verification to payout distribution. Each contract is independently auditable and operates without admin override.
MentalPokerGame
Manages the mental poker protocol on-chain. Stores encrypted deck commitments, verifies shuffle proofs via elliptic curve math, and handles transcript checkpoints for dispute resolution.
PokerBetting
Full Texas Hold'em betting state machine. Enforces turn order, validates actions (check/bet/call/raise/fold), manages side pots, and handles timeouts with auto-fold.
PokerEscrow
Holds player funds during gameplay. Distributes payouts after resolution. Collects rake. Supports multiple resolution paths: showdown, timeout, mass disconnect, and censorship recovery.
PokerHandEvaluator
Evaluates poker hands entirely on-chain using a base-13 scoring system. Handles 5-7 card evaluation, finds the best 5-card hand, and resolves ties deterministically.
BlameAttribution
Cryptographic proof of cheating. Players can prove invalid VSS shares, commitment equivocation, or duplicate cards using ECDSA signatures — triggering on-chain slashing.
Coordinator
Manages peer discovery for P2P games. Players register their libp2p identities on-chain, enabling trustless peer-to-peer connections without a central matchmaking server.
Shuffle Verification Flow
Commit
Each player's key commitment hash + encrypted deck checkpoint published on-chain
Verify Proof
Anyone can call verifyShuffleProof() — checks keccak256(proof) matches commitment
EC Verification
Per-player shuffle verified: newDeck[i] = ecMul(oldDeck[perm[i]], deckKey) on Secp256k1
Checkpoint
State recorded at 3 levels: seed hash, chain hash, and locked deck + Merkle root
Settle
PokerHandEvaluator scores hands on-chain, PokerEscrow distributes payouts
The Escape Hatch
If the server ever censors a player's actions, any player can bypass the server entirely by posting their actions and reveal keys directly to the smart contract. This triggers a 3-minute dispute window. After the window expires, the contract resolves the game based on the on-chain state — the server cannot block or override the outcome. This is the ultimate guarantee: even a malicious operator cannot steal your funds.
Transaction Flow — Money In, Money Out
Trustless guarantee: At no point does TrueShuffle (the operator) hold or control player funds. All money flows through immutable smart contracts — deposit, escrow, and payout are all on-chain.
Decentralization Stack
TrueShuffle is designed to minimize single points of failure at every layer. The goal: a poker platform that no single entity can shut down, censor, or manipulate.
IPFS
Frontend Hosting
libp2p
P2P Messaging
Mental Poker
Cryptographic Protocol
MegaETH
On-Chain Settlement
Tauri Desktop
Local Bot Execution
IPFS Deployment
The web UI is deployed to IPFS (InterPlanetary File System) — a content-addressed, peer-to-peer storage network. Once published, the frontend is immutable and distributed across thousands of nodes worldwide. No single server hosts it. Even if the original deployer disappears, the app remains accessible via any IPFS gateway.
Peer-to-Peer Communication
In decentralized mode, bots communicate directly with each other via libp2p — the same networking stack that powers IPFS and Filecoin. Messages are broadcast using the gossipsub protocol. No central relay server is required.
On-Chain Smart Contracts
All financial settlement happens on MegaETH via smart contracts. Deposits are locked in escrow, actions are recorded on-chain, and payouts are enforced by code — not by an operator. The contracts are immutable once deployed.
Mental Poker Protocol
Randomness is not sourced from any external beacon or server. It emerges from the protocol itself: each player generates secret keys and applies a private Fisher-Yates permutation to the deck. The compounding of all players' independent shuffles produces a final ordering that no single party can predict or control.
Client-Side Execution
Bots run on the player's own machine — not in the cloud. The desktop application is a native binary that executes locally. Your private keys never leave your device. The game logic, decision-making, and cryptographic operations all happen on your hardware.
Bot Architecture
Bots run as native desktop applications built with Tauri — a framework that combines a Rust backend with a lightweight web UI. The bot runs on your machine (Mac, Windows, or Linux) with full access to the OS keychain for secure key storage.
System Architecture
Desktop Application Layers
Spectator dashboard, stats, action feed, bot configuration
Bot engine, rule evaluation, crypto, networking
Private keys, wallet credentials, encrypted at rest
Centralized Mode
Server-Mediated
Bots connect to the TrueShuffle server via WebSocket. The server orchestrates the protocol phases and relays encrypted messages, but never sees card keys or plaintext cards. Shuffles and commitments are recorded on-chain. Simpler setup, lower latency.
Decentralized Mode
Fully Trustless
Bots communicate peer-to-peer via libp2p. Game rules are enforced entirely by smart contracts. No central server is involved. The coordinator role rotates among players. Maximum decentralization.
Cross-Platform Native Builds
macOS
.app bundle + DMG installer
Keychain integration for key storage
Windows
.exe + MSI installer
Credential Manager for key storage
Linux
AppImage
Secret Service for key storage
Bot DNA
Every bot is defined by its DNA — a configuration that controls its personality and decision-making rules. Bot DNA is a portable JSON structure that can be created visually in Bot Studio, generated by AI, or hand-crafted. It consists of two parts: personality traits and a priority-based rule system.
Personality Traits
Baseline Behavior
Three sliders define the bot's baseline temperament. These traits act as fallback behavior — when no specific rule matches a situation, the bot's personality determines its default action.
Priority-Based Rule System
Decision Tree
Rules override personality. Each rule has a priority (higher = evaluated first), a set of conditions that must ALL match (AND logic), and an action to take. The first matching rule wins.
AI-Assisted Creation
Don't want to craft rules by hand? Describe your strategy in plain English and the AI assistant generates a complete bot configuration. Say "I want an aggressive button opener that 3-bets light from late position" and get a fully structured bot DNA with tuned personality traits and prioritized rules. You can then refine it iteratively through conversation or manual editing.
Learning & Adaptation
How Bots Evolve Over Time
Bots don't just follow static rules — they learn and adapt based on real game data. Every hand played generates data that feeds back into the bot's strategy, creating a continuous improvement loop.
1. Play Hands
Bot plays at tables using current DNA rules and personality traits
2. Track Results
Win rates, showdown data, positional stats, and opponent tendencies are recorded
3. Analyze Patterns
AI reviews hand histories, identifies leaks, and suggests DNA adjustments
4. Evolve DNA
Bot DNA is updated — traits adjusted, rules added/modified, strategies refined
Adaptation Mechanisms
Tracks each opponent's VPIP (voluntarily puts $ in pot), PFR (pre-flop raise), 3-bet %, and fold-to-continuation-bet. The bot adjusts exploitation strategy per-player — tightening against maniacs and bluffing more against nits.
Every decision is tracked against expected value. If the bot consistently loses money in specific spots (e.g., calling 3-bets OOP with medium hands), the AI flags it as a leak and suggests tighter ranges for those situations.
Personality traits aren't static. If data shows the bot is bleeding chips from too-frequent bluffs, the bluff frequency automatically decreases. If it's leaving value on the table by being too passive, aggression ramps up. Changes are gradual to prevent overcorrection.
New rules are generated from patterns in winning and losing hands. If the bot notices it profits heavily from 3-betting in the cutoff with suited connectors, a new high-priority rule is created to codify that pattern. Underperforming rules get deprioritized or removed.
Example: 10,000 Hands Performance
After 10,000 hands, this bot evolved from a generic TAG profile to a specialized exploitative strategy tuned to the micro-stakes player pool.
Bot Brain
The Bot Brain is the runtime decision engine that translates Bot DNA into actions at the table. Written in Rust for performance and safety, it evaluates the current game state against the bot's rules and personality to produce optimal actions in real-time.
Decision Pipeline
Receive Game State
Server sends action request with complete game state: hole cards, board, pot, position, opponent actions, stack sizes
Classify Hand
Hole cards are categorized: Premium (AA-TT, AK, AQs), Strong (99-77, AJs+, KQs), Medium (66-22, suited connectors), or Weak (everything else)
Determine Position
Seat number mapped to positional name: BTN, CO, MP, UTG, SB, BB — position heavily influences optimal play
Evaluate Rules
Rules sorted by priority (highest first). Each rule's conditions checked against current state. First complete match wins. All conditions must be true (AND logic).
Calculate Sizing
Matched rule's sizing applied: min-bet, half-pot, full-pot, all-in, or percentage of stack. Clamped to legal bet limits.
Execute Action
Action sent back to server/contract. Event emitted to UI for spectator display. Stats updated (VPIP, PFR, action counts).
Decision Flowchart
How the bot brain resolves every decision point
Hand Classification System
Premium
AA, KK, QQ, JJ, TT, AKs, AKo, AQs
Always playable. Raise or re-raise from any position.
Strong
99-77, AJs-ATs, KQs, AQo
Playable from most positions. Open-raise or call raises.
Medium
66-22, suited connectors, suited aces, KQo
Position-dependent. Profitable from late position.
Weak
Everything else
Fold unless getting excellent pot odds or on the button.
Real-Time Statistics
The bot engine tracks every decision for analysis and optimization:
Voluntarily Put In Pot %
Pre-Flop Raise %
Hands won / hands played
Cumulative session P&L
The Spectator Experience
The web UI is designed for spectating, not playing. Humans watch as bots battle. The interface provides real-time game visualization, live commentary, hand analysis, and broadcast-quality viewing of every table.
Live Broadcast
Watch any active table in real-time. See community cards dealt, bets placed, and showdowns unfold. The broadcast view supports both heads-up and 6-max formats with automatic detection.
Hand History
Every hand is recorded with full action history. Replay any hand, analyze decision points, and verify the shuffle proof. The hand explorer shows the complete audit trail from shuffle commitment to final settlement.
Bot Profiles
Each bot has a public profile showing its performance stats, hand history, win rate, and profit/loss over time. Compare bot strategies and find the most successful archetypes on the leaderboard.
Bot Studio
The visual bot builder lets you design bot DNA through an intuitive interface. Adjust personality sliders, create rules, and backtest your strategy against historical data — all in the browser before deploying to the arena.
Verification Explorer
Every hand includes a verification panel. Click to see the on-chain shuffle commitments, the encrypted deck checkpoints, the protocol transcript hashes, and the settlement transaction. You can independently verify that every protocol phase was executed correctly — trustless verification, right from the spectator view.
End-to-End Game Flow
Here's what happens from the moment a hand begins to the final payout — every step of the pipeline.
Bots Join Table
Bots sit at a table and post buy-ins. In on-chain mode, funds are deposited into the PokerEscrow contract.
Blinds Posted
Small blind and big blind posted automatically. All-in handling for short stacks.
Key Commitment
Each player generates deck key + 52 card keys + X25519 keypair. SHA-256 commitment hash published on-chain — keys are locked in.
Encrypt & Shuffle
Players take turns: each encrypts the deck with their deck key (EC scalar multiply), then shuffles with a secret permutation. Encrypted deck passed to next player.
Lock & Commit
Each player removes deck-level encryption and applies per-card keys. Encrypted deck checkpoint recorded on MegaETH — immutable before any cards are dealt.
Hole Cards Dealt
Other players E2E-encrypt their card keys for the recipient via X25519. Recipient collects all keys, decrypts locally. Server only relays encrypted blobs — never sees cards.
Preflop Betting
Bots evaluate their hands and rules, submit actions. 30-second timeout with auto-fold.
Community Cards
Flop (3 cards), Turn (1 card), River (1 card) — each followed by a betting round.
Showdown
Remaining players reveal hands. PokerHandEvaluator scores each hand using base-13 system.
Winner Determined
PokerGameResolver identifies winners, handles ties with split pots, calculates side pots.
Payout Distributed
PokerEscrow distributes winnings minus rake. Players can withdraw at any time.
Protocol Transcript Published
Full protocol transcript (commitment hashes, encrypted deck checkpoints, card reveals) published on-chain. Anyone can independently verify every step.
Technology Stack
TrueShuffle is built on a modern, modular stack spanning blockchain, backend, frontend, desktop, and cryptography. Every layer is open-source and independently auditable.
Blockchain & Settlement
Backend & Server
Cryptography
Frontend & Web
Desktop Bot Application
Testing & Infrastructure
Frequently Asked Questions
Common questions about TrueShuffle, the protocol, and why it matters.
Ready to Compete?
Design your bot's DNA in Bot Studio, deploy it to the arena, and watch it battle. Every shuffle verified. Every hand on-chain.