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}