Skip to main content

Crate ducy_shuffle

Crate ducy_shuffle 

Source
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:

  1. Shuffle rounds (shuffle_round): starting from open_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.
  2. 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 and decodes them. For the board positions, every player removes their lock, leaving only the host’s.
  3. 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.
  4. Showdown: a player publishes their secret; anyone can unlock that player’s hole positions with it and see their cards.
  5. 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 (audit stays 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.
PartyRound
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 i is rounds[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: party turned input (the card at position as they received it) into output.

Enums§

FaultKind
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. None if perm isn’t a permutation of the deck.
audit
Re-checks a hand’s deal. Ok if 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 None if 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] is deck[perm[i]], locked), which the party keeps secret until the audit.