Skip to main content

ducy_shuffle/
audit.rs

1//! The audit after a hand (allenpiscitello/ducy#138): once the hand is over,
2//! every party publishes its secret and permutation, and anyone can re-run
3//! the whole deal from the record and check that no one cheated.
4
5use ducy::deck::Card;
6
7use crate::{Layout, Masked, Secret, apply_round, decode, open_deck};
8
9/// One party's shuffle round as published after the hand.
10#[derive(Clone, Debug, PartialEq, Eq)]
11pub struct PartyRound {
12    /// The party's secret for this deck.
13    pub secret: Secret,
14    /// The permutation it applied: output position `i` holds input card `perm[i]`.
15    pub perm: Vec<u32>,
16    /// The deck this party sent on.
17    pub output: Vec<Masked>,
18}
19
20/// One lock removal during the hand: `party` turned `input` (the card at
21/// `position` as they received it) into `output`.
22#[derive(Clone, Copy, Debug, PartialEq, Eq)]
23pub struct Unlock {
24    /// Who removed the lock (players, then the host).
25    pub party: usize,
26    /// The deck position.
27    pub position: usize,
28    /// The card before.
29    pub input: Masked,
30    /// The card after.
31    pub output: Masked,
32}
33
34/// Everything a hand's deal published: the rounds in shuffle order (party
35/// `i` is `rounds[i]`: players, then the host), the lock removals in the
36/// order they happened, and the cards shown during the hand (board streets
37/// and showdowns) with who showed them.
38#[derive(Clone, Debug, PartialEq, Eq)]
39pub struct Transcript {
40    /// Whose positions are whose.
41    pub layout: Layout,
42    /// Every party's round, in shuffle order.
43    pub rounds: Vec<PartyRound>,
44    /// Every lock removed, in order.
45    pub unlocks: Vec<Unlock>,
46    /// Cards shown: (position, card, party that showed it).
47    pub revealed: Vec<(usize, Card, usize)>,
48}
49
50/// Who cheated, and how.
51#[derive(Clone, Copy, Debug, PartialEq, Eq)]
52pub struct Fault {
53    /// The party at fault (players, then the host).
54    pub party: usize,
55    /// What it did.
56    pub kind: FaultKind,
57    /// The deck position involved, if it's about one card.
58    pub position: Option<usize>,
59}
60
61/// The ways a deal can fail the audit.
62#[derive(Clone, Copy, Debug, PartialEq, Eq)]
63pub enum FaultKind {
64    /// A party's round is missing from the record.
65    MissingRound,
66    /// The published permutation isn't a permutation of the deck.
67    NotAPermutation,
68    /// The deck a party sent on isn't its secret and permutation applied
69    /// to the deck it got (a fake shuffle, or cards swapped in).
70    WrongShuffle,
71    /// A lock removal that doesn't match the party's secret.
72    WrongUnlock,
73    /// A lock removal on a card that isn't the one at that position.
74    SubstitutedCard,
75    /// A card shown that isn't the one dealt at that position.
76    WrongReveal,
77}
78
79/// Re-checks a hand's deal. `Ok` if everyone played it straight; otherwise
80/// the first fault found, naming the party.
81pub fn audit(t: &Transcript) -> Result<(), Fault> {
82    let fault = |party, kind, position| {
83        Err(Fault {
84            party,
85            kind,
86            position,
87        })
88    };
89    let parties = t.layout.players + 1;
90    if t.rounds.len() < parties {
91        return fault(t.rounds.len(), FaultKind::MissingRound, None);
92    }
93    // The shuffle: each round from the deck before it.
94    let mut deck = open_deck();
95    for (party, r) in t.rounds.iter().take(parties).enumerate() {
96        match apply_round(&deck, &r.secret, &r.perm) {
97            None => return fault(party, FaultKind::NotAPermutation, None),
98            Some(expected) if expected != r.output => {
99                return fault(party, FaultKind::WrongShuffle, None);
100            }
101            Some(_) => {}
102        }
103        deck = r.output.clone();
104    }
105    // Lock removals, in order: each must start from the card as it stood at
106    // that position, and match the party's secret.
107    let mut current = deck.clone();
108    for u in &t.unlocks {
109        if u.party >= parties || u.position >= current.len() {
110            return fault(
111                u.party.min(parties),
112                FaultKind::WrongUnlock,
113                Some(u.position),
114            );
115        }
116        if u.input != current[u.position] {
117            return fault(u.party, FaultKind::SubstitutedCard, Some(u.position));
118        }
119        if u.output != t.rounds[u.party].secret.unlock(&u.input) {
120            return fault(u.party, FaultKind::WrongUnlock, Some(u.position));
121        }
122        current[u.position] = u.output;
123    }
124    // Shown cards: the position with every lock off must be that card.
125    for &(pos, card, by) in &t.revealed {
126        let open = deck.get(pos).map(|m| {
127            t.rounds
128                .iter()
129                .take(parties)
130                .fold(*m, |m, r| r.secret.unlock(&m))
131        });
132        if open.and_then(|m| decode(&m)) != Some(card) {
133            return fault(by, FaultKind::WrongReveal, Some(pos));
134        }
135    }
136    Ok(())
137}