@sportsbroker/firebase-structure 8.0.0 → 8.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -46,13 +46,23 @@ export type CoinEvent = {
46
46
 
47
47
  export type CoinEventState = {
48
48
  /** Seats per table. A full table opens the next one. */
49
- tableSize: number;
49
+ maxTableSize: number;
50
+ /**
51
+ * Fewest occupied seats for a table to be played. A table that stays below it when the match ends
52
+ * refunds every stake in full instead of paying a coin holder, so a player can see the threshold
53
+ * before paying. Together with `maxTableSize` this is the min and max of a table.
54
+ */
55
+ minTableSize: number;
50
56
  /** The live stats that pass the coin. Any confirmed increment across them advances it. */
51
57
  triggerStats: string[];
52
- /** Seats the coin advances per confirmed trigger. */
53
- advanceStep: number;
54
58
  /** Percent of the pot the half-time holder takes; the full-time holder takes the remainder. */
55
59
  halfTimeSplitPercent: number;
60
+ /**
61
+ * What the half-time share is worth when no trigger fired before the interval, so a player can see the
62
+ * rule before paying. `pay-holder` pays the seat the coin was drawn onto; `roll-to-full-time` adds that
63
+ * share to the full-time holder instead.
64
+ */
65
+ halfTimeShareWithoutTrigger: "pay-holder" | "roll-to-full-time";
56
66
  /** Confirmed triggers so far in the match. */
57
67
  passCount: number;
58
68
  /** The count captured at half time, or null until the half-time fact arrives. */
@@ -14,6 +14,13 @@ export enum PrizeDistributionStrategyEnum {
14
14
  WINNER_TAKES_ALL = "winner-takes-all",
15
15
  TOP_3 = "top-3",
16
16
  TOP_5 = "top-5",
17
+ /**
18
+ * Golden Coin's only distribution: the half-time holder takes a configured percent of the pot and the
19
+ * full-time holder takes the remainder. Never operator-selectable - the split is a game setting, and
20
+ * which positions it pays is fixed by the engine. `payoutStructure` carries the two amounts, position
21
+ * `"1"` being the half-time share and `"2"` the full-time one.
22
+ */
23
+ COIN_HT_FT_SPLIT = "coin-ht-ft-split",
17
24
  }
18
25
 
19
26
  export type PoolEvent = {
@@ -52,21 +59,80 @@ export type CoinPool = Pool & { coin: CoinTable };
52
59
  * A Golden Coin table. The pool IS the table: seats are taken in join order, the coin starts on a seat
53
60
  * drawn from the table's own seed, and each confirmed trigger advances it. Present only on pools of the
54
61
  * `coin-pass` engine.
62
+ *
63
+ * How many tables an operator has open on an event, and how many players sit at them across all of
64
+ * them, is read from these documents: query `Pools` by `betEventId` and `operatorId`, and the result
65
+ * count is the number of tables while the sum of `participants` is the number of players. Every join
66
+ * reprojects the pool document, so both stay live and can never disagree with the seats a player is
67
+ * shown on a table.
55
68
  */
69
+ /**
70
+ * How a Golden Coin round ended, stated by the engine so no client works it out from pass counts.
71
+ * `running` = not settled yet; `paid` = the pot went to its holders; `refunded` = every stake went back
72
+ * in full (the coin never moved, or the table stayed below `minTableSize`); `no-payout` = there was
73
+ * nobody to pay.
74
+ */
75
+ export type CoinRoundOutcome = "running" | "paid" | "refunded" | "no-payout";
76
+
77
+ /**
78
+ * A Golden Coin table's provable-fairness record. The three values a player needs to check the draw:
79
+ *
80
+ * 1. `commitHash` is published when the table opens, before anybody pays. It is `sha256(serverSeed)`.
81
+ * 2. `serverSeed` appears only once the round has settled. Hash it and it must equal `commitHash`.
82
+ * 3. Re-run `algorithm` over the seed, the pool id and `seatCountBasis`; the index it yields must be the
83
+ * position of `startSeatNumber` in `seats`.
84
+ *
85
+ * Both steps run in a browser with WebCrypto (`crypto.subtle.digest` and `crypto.subtle.sign` with HMAC),
86
+ * so verification needs no library and no call back to us.
87
+ */
88
+ export type CoinFairness = {
89
+ /** Which ruleset this table was drawn under. Pinned per table, so an old table stays verifiable. */
90
+ version: string;
91
+ /** The formula to re-run, spelled out. */
92
+ algorithm: string;
93
+ /** The commitment. Null only on a table created before this record existed. */
94
+ commitHash: string | null;
95
+ /** How many occupied seats the draw ran against: the modulo base. Null until the draw is taken. */
96
+ seatCountBasis: number | null;
97
+ /** The revealed seed. Null while the round is running - revealing it early would give the draw away. */
98
+ serverSeed: string | null;
99
+ };
100
+
56
101
  export type CoinTable = {
57
102
  /** Which table of this operator and event this is, counting from 1. */
58
103
  tableNumber: number;
59
- tableSize: number;
104
+ maxTableSize: number;
105
+ /** Fewest occupied seats for this table to pay a holder; below it every stake is refunded in full. */
106
+ minTableSize: number;
107
+ /**
108
+ * Does the table meet `minTableSize` right now? Decided by the engine, not by the client, so every
109
+ * screen states the same verdict: false means that as things stand this table refunds instead of
110
+ * paying a coin holder.
111
+ */
112
+ meetsMinimum: boolean;
60
113
  /** Confirmed triggers so far in the match, mirrored from the event for a self-contained table view. */
61
114
  passCount: number;
62
- /** Occupied seats in join order. Seat numbers count from 1 and never leave a gap. */
115
+ /**
116
+ * Occupied seats in join order. Seat numbers count from 1 and MAY leave a gap: the number a player
117
+ * joined on is theirs for the round, so a seat given up before kickoff goes missing from this list
118
+ * rather than renumbering the players behind it. Render by `seatNumber`, not by array position.
119
+ */
63
120
  seats: CoinSeat[];
64
- /** The seat holding the coin right now, or null while the table has no bet. */
121
+ /**
122
+ * The seat the coin was drawn onto, or null until the match starts. The draw is taken at the first
123
+ * whistle and written down, so this value never changes afterwards.
124
+ */
125
+ startSeatNumber: number | null;
126
+ /** The seat holding the coin right now, or null while the coin has not been drawn or nobody sits. */
65
127
  holdingSeatNumber: number | null;
66
128
  /** Who held the coin at half time, or null until the half-time fact arrives. */
67
129
  halfTimeHolder: CoinHolder | null;
68
130
  /** Who held the coin at full time, or null until the match finishes. */
69
131
  fullTimeHolder: CoinHolder | null;
132
+ /** How the round ended. `running` until the table settles. */
133
+ outcome: CoinRoundOutcome;
134
+ /** Everything needed to verify the draw. */
135
+ fairness: CoinFairness;
70
136
  };
71
137
 
72
138
  export type CoinSeat = {
@@ -80,6 +146,12 @@ export type CoinHolder = {
80
146
  seatNumber: number;
81
147
  betId: UUID;
82
148
  userId: UUID;
149
+ /**
150
+ * What this share is worth, in the pool's currency. Before the match ends it is the live answer ("you
151
+ * are holding a share worth this much"); once the table has settled it is exactly what was credited.
152
+ * Null when the amount is not resolvable yet.
153
+ */
154
+ prize: number | null;
83
155
  };
84
156
 
85
157
  export type Pool = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sportsbroker/firebase-structure",
3
- "version": "8.0.0",
3
+ "version": "8.2.0",
4
4
  "description": "Firebase structure typings",
5
5
  "main": "index.d.ts",
6
6
  "repository": {