Expand description
A trustless (“mental poker”) shuffle: the deck is encrypted and shuffled by every player and the host in turn, so no single party controls or sees the deal (allenpiscitello/ducy#134, step 2: #136).
§How it works
Each card is a fixed point on Ristretto255 (card_point). Every party
makes a fresh Secret per hand. Locking a card multiplies its point by
the secret, unlocking by the secret’s inverse. Scalar multiplication
commutes, so locks can be added and removed in any order:
- Shuffle rounds (
shuffle_round): starting fromopen_deck, each party in turn (players in seat order, then the host) locks every card and applies a secret random permutation, and passes the deck on. Once every party has gone, no one knows which position holds which card. - Lock removal (
Layout): for each player’s hole-card positions, every other party removes its lock (Secret::unlock), leaving only the owner’s; the owner unlocks their own anddecodes them. For the board positions, every player removes their lock, leaving only the host’s. - Streets: the host removes its last lock from one street’s positions at a time, so the board is public only when it’s dealt.
- Showdown: a player publishes their secret; anyone can unlock that player’s hole positions with it and see their cards.
- Audit (
audit): after the hand, every party publishes its secret and permutation, and anyone can re-check the whole deal.
The host never sees anyone’s hole cards. The host does see the board before it’s dealt (decided on #134: the host has no seat at club tables).
Every step can carry a zero-knowledge proof (proof, #140), checked
before the deal goes on, and setup runs a whole deck’s setup that way
for the host, leaving out anyone who drops out (#137).
This is the cryptographic core only: no networking or table logic. It should be reviewed by someone with cryptography expertise before it’s trusted with real games.
use ducy_shuffle::{decode, open_deck, shuffle_round, Layout, Secret};
// Two players and the host, Hold'em.
let layout = Layout::new(2, 2, 5);
let secrets: Vec<Secret> = (0..3).map(|_| Secret::random()).collect();
let mut rng: rand::rngs::StdRng = rand::make_rng();
let mut deck = open_deck();
for s in &secrets {
deck = shuffle_round(&deck, s, &mut rng).0;
}
// Everyone but player 0 (the host is party 2) removes their lock from
// player 0's hole cards; then player 0 opens them.
let mut mine: Vec<_> = layout.hole(0).map(|p| deck[p]).collect();
for party in [1, 2] {
mine = mine.iter().map(|c| secrets[party].unlock(c)).collect();
}
let cards: Vec<_> = mine.iter().map(|c| decode(&secrets[0].unlock(c)).unwrap()).collect();
assert_eq!(cards.len(), 2);Re-exports§
pub use proof::PublicKey;pub use proof::ShuffleProof;pub use proof::UnlockProof;pub use setup::DeckSetup;pub use setup::Ready;pub use setup::Request;pub use setup::SetupParty;pub use setup::Step;
Modules§
- proof
- Zero-knowledge proofs (allenpiscitello/ducy#140, phase 2): each step of
the deal comes with a proof that it was done right, checked before the
deal goes on, so cheating is refused when it happens rather than found
by the audit afterwards (
auditstays as a second check). - setup
- Setting up a hand’s deck, run by the host while the previous hand is still being played (allenpiscitello/ducy#137), so a disconnect never stops or replays a hand: whoever drops out during setup just isn’t in the next hand.
Structs§
- Fault
- Who cheated, and how.
- Layout
- Which deck positions are whose once the shuffle is done: each player’s
hole cards in seat order, then the board. Parties are numbered players
0..players, then the host (Layout::host). - Masked
- A card as the parties see it: a point on Ristretto255, plain (a card’s
card_point) or under any number of locks. - Party
Round - One party’s shuffle round as published after the hand.
- Secret
- One party’s key for one hand. Never reuse it: after the hand it’s published for the audit.
- Transcript
- Everything a hand’s deal published: the rounds in shuffle order (party
iisrounds[i]: players, then the host), the lock removals in the order they happened, and the cards shown during the hand (board streets and showdowns) with who showed them. - Unlock
- One lock removal during the hand:
partyturnedinput(the card atpositionas they received it) intooutput.
Enums§
- Fault
Kind - The ways a deal can fail the audit.
Functions§
- apply_
round - A shuffle round from its published secret and permutation: what the
party should have sent.
Noneifpermisn’t a permutation of the deck. - audit
- Re-checks a hand’s deal.
Okif everyone played it straight; otherwise the first fault found, naming the party. - card_
point - The fixed point for
card: a hash of its name onto the curve, so no one knows any relation between two cards’ points. - decode
- The card an unlocked point stands for, or
Noneif it isn’t one (some lock is still on it, or it was tampered with). - open_
deck - The 52 cards, unlocked, in ducy’s order: where every shuffle starts.
- shuffle_
round - One party’s turn: lock every card and shuffle. Returns the new deck and
the permutation used (
out[i]isdeck[perm[i]], locked), which the party keeps secret until the audit.