> For the complete documentation index, see [llms.txt](https://docs.fast.poker/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fast.poker/architecture/state-accounts.md). # State accounts The on-chain accounts that hold Fast Poker game state. ## Core gameplay ### Table | | | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Seeds | `["table", table_id]` | | Size (data) | 459 bytes | | Size (alloc) | 478 bytes (459 + 19 shadow bytes) | | Discriminator | `SHA256("account:Table")[0..8]` | | Holds | Phase, pot, current player, button, blinds, max players, game type (Cash / SitAndGo HU / 6max / 9max), tier, vault link, jackpot pointers | The 19 extra bytes are the **shadow field** pattern (`active_mask`, `dealt_mask`, `started_at_slot`, `roster_hand_number`, `sng_setup_mask`). The high `sng_setup_mask` bits identify Flat Bounty duel mode and settlement-record mode. Integrations must preserve those bits when updating setup state. ### Seat (PlayerSeat) | | | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | Seeds | `["seat", table_pda, seat_index]` | | Size (data) | 281 bytes | | Size (alloc) | 284 bytes (281 + `cards_visible` + `session_hands_played`) | | Holds | Player wallet, chips, bet this round, total bet this hand, status, sit-out timestamp, blind/session counters, leaving flag, time-bank fields | `status` values: `Empty`, `Active`, `Folded`, `AllIn`, `SittingOut`, `Busted`, `Leaving`. The ER kick path can remove cash `SittingOut` seats after the sit-out timeout when the seat has played in the current session, with a first-hand waiting-table exception. Legacy orbit removal and 0-chip bust removal are separate cash cleanup paths. ### SeatCards | | | | ---------- | ----------------------------------------------------------------- | | Seeds | `["seat_cards", table_pda, seat_index]` | | Size | 76 bytes | | Holds | Two card bytes (0-51), state flags | | Permission | Has an associated `seat_cards_permission` PDA gating who can read | When no hand is in progress, both card bytes are 255 (sentinel for "no cards"). ### DeckState | | | | ---------- | ------------------------------------------------------------------------------------ | | Seeds | `["deck_state", table_pda]` | | Size | 241 bytes | | Holds | Shuffled deck (52 bytes), reveal pointer, entropy accumulator, commitment hash, salt | | Permission | Private DeckState permission; unreadable externally during live play | The entropy accumulator is **never zeroed**. It carries forward across hands so the dealer cannot reset randomness. ### HandLedger accounts | | | | ---------------------------- | ------------------------------------------------- | | `SlimBuffer` seeds | `["slim_buffer", table_pda]` | | `SlimBuffer` size | 81 bytes data | | `HandReportBuffer` seeds | `["hand_report_buf", table_pda]` | | `HandReportBuffer` size | 52-byte header plus configured capacity | | `HandReportFlushState` seeds | `["hand_report_flush", table_pda]` | | `HandReportFlushState` size | 88 bytes | | Holds | HAND\_REPORT\_V1 payloads and rolling-hash anchor | | Permission | TEE validator | HandLedger is the product name for the hand-report chain. Code-level tooling should use the account names and seeds above. ### PlayerTableMarker | | | | ----- | ---------------------------------------------------------------------------- | | Seeds | `["player_table", player_pubkey, table_pda]` | | Size | 99 bytes | | Holds | Player <-> table linkage, duplicate-join detection, chip lock, kick tracking | Created at deposit. Cashout paths can keep marker data long enough to enforce same-table chip locks and recent-kick rejoin penalties. ## Money and rewards ### Player | | | | ----- | ------------------------------------------------------------------------------ | | Seeds | `["player", player_pubkey]` | | Size | varies | | Holds | Cumulative XP, hands played, tournaments entered/cashed/won, display name slot | One per wallet. Created on first table join. ### TableVault | | | | ----- | ------------------------------------------ | | Seeds | `["vault", table_pda]` | | Size | 113 bytes | | Holds | Buy-ins, top-ups, rake accrual, prize pool | The vault is just a SOL-holding PDA owned by the program. Cashouts and rake distributions transfer out of it under program-enforced rules. ### CrankAction | | | | -------- | ----------------------------------------------------------- | | ER seeds | `["crank_action_er", table_pda, operator_pubkey]` | | L1 seeds | `["crank_action_l1", table_pda, operator_pubkey]` | | Size | 97 bytes | | Holds | Per-(table, operator, lane) action counters | | Weight | ER actions count 1x; L1 actions count 2x during reward sync | Real handlers credit weight into this PDA. The dealer cannot write to it directly. ### OperatorRewardTotal | | | | -------- | ------------------------------------------------- | | ER seeds | `["op_reward_total_er", table_pda]` | | L1 seeds | `["op_reward_total_l1", table_pda]` | | Size | 57 bytes | | Holds | Canonical sum of all operator weights for a table | | Use | Accumulator denominator | ### CrankRewardState | | | | -------- | ---------------------------------------------------------------- | | Seeds | `["crank_reward_state", table_pda]` | | Holds | Per-table accumulator, reward epoch counter, last sync timestamp | | Lifetime | Persistent across SNG matches | The reward\_epoch counter is the per-table isolation key for reusable SNG tables. ### OperatorClaim | | | | ----- | --------------------------------------------------------------- | | Seeds | `["op_claim", table_pda, operator_pubkey]` | | Size | 134 bytes | | Holds | Active epoch weight, reward debt, banked rewards, claimed total | | Use | Permissionless pull-claim destination | Per table and operator. Reusable SNG tables isolate matches through `reward_epoch`. ### TipJar | | | | ---------- | ------------------------------------------------ | | Seeds | `["tip_jar", table_pda]` | | Size | 75 bytes | | Holds | Accrued tip balance, per-hand consumption record | | Permission | L1 only | Cash-only and SOL-only. `deposit_tip` adds SOL to the jar and resets the payout window to 100 hands. After a cash hand settles, `record_cash_hand_tip` can pay one per-hand slice to the credited licensed dealer. ### UnclaimedBalance | | | | ---------- | ----------------------------------------- | | Holds | Pending balances awaiting claim | | Drained by | `claim_unclaimed` / `claim_unclaimed_sol` | ## SNG-specific ### SngPool | | | | ----- | --------------------------------------------------------- | | Seeds | `["sng_pool", game_type, tier_id]` | | Size | 150 bytes | | Holds | Queue, current bitmap, next\_table\_index, tier economics | One per (format, tier) combination. ### SngJackpotSettlement | | | | ----- | ---------------------------------------------------- | | Seeds | `["sng_jackpot_settlement", table_pda, hand_number]` | | Size | 209 bytes | | Holds | Mini / Grand jackpot resolution state | Player-facing copy calls these jackpot paths Lucky and Royal. The account and IDL retain the internal Mini/Grand field names. ### SngDuelState | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Seeds | `["sng_duel", table_pda]` | | Size | 415 bytes | | Applies to | 6-max and 9-max SNG tables only | | Holds | Conserved point units, knockout credits, final blind level, fold counts, active duel seats/choices/deadline/entropy, and canonical ruleset | | Lifecycle | Persistent per table; delegated during play and reset for table reuse | The current ruleset byte is `1` (Flat Bounty). One point is represented by `1_000_000` internal units so tied winners can receive fractional shares. The sidecar must be present for duel-mode hand settlement and prize distribution; missing or invalid state fails closed. ### SngSettlementRecord | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Seeds | `["sng_settlement", table_pda, start_hand: u64 LE]` | | Size | 634 bytes | | Holds | Per-game identity, settlement/finalization/payment flags, wallets, final SOL amounts, final unrefined $FP amounts, fee split, and rent payer | | Lifecycle | Transient per game; initialized/delegated before play and closed after paid table reset | The record binds payout to one table game and preserves final amounts before slower cleanup. Record-enabled tables cannot fall back to an unrecorded payout path. ### EmissionCtrl | | | | --------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Seeds | `["emission_ctrl"]` | | Size | 437 bytes | | Holds | Governance authority, demand target/floor, fast/slow signals, retain rates, idle limits and caps, curve parameters, and timestamps | | Lifecycle | Global persistent governed account | The current mainnet minimum demand multiplier is 1,000 bps (10%). This is a governed value and is separate from the emission curve's 5% liquid-supply floor. ### PoolIdle | | | | ----- | ------------------------------------------------------------------- | | Seeds | `["pool_idle", game_type: u8, tier: u8]` | | Size | 83 bytes | | Count | 21: one for each of 3 SNG formats x 7 tiers | | Holds | Cell identity and last-game timestamp used by the capped idle boost | `EmissionCtrl` and the matching `PoolIdle` are read and updated when an SNG emission snapshot is funded. ### SngQueuePage | | | | --------- | ----------------------------------------------- | | Holds | A page of queued joiners for an SNG pool | | Lifecycle | Init when needed, compacted/closed when drained | ## License and registry (separate programs) | Account | Program | Purpose | | ---------------- | -------------------------------------------------------- | ------------------------------------------------------------ | | `DealerLicense` | Registry (`pokerQBdo685uLSkpVSyZ1vWooPYYTUhGkeKAHyCmax`) | One active wallet-bound dealer license; absent while wrapped | | `DealerRegistry` | Registry | Singleton; tracks total licenses, bonding curve state | | `CrankOperator` | Registry | Per-operator stats, license linkage | ## Token economics (Steel CPI) The Steel tokenomics program (`FASTPjXb68fPW9JRYSBS3EDoaT6inz84GoqkPK52dsA9`) handles: * Burned $FP revenue accounting * SPL reward pool accruals * Pool-deposit CPIs Fast Poker calls into Steel during prize distribution. Historical primary Dealer License purchases also used Steel, but new license issuance is closed. ## Constants worth knowing | Pubkey | Role | | ------------------------- | ----------------------------------------- | | `POOL_PDA` = `TBA` | $FP mint and Burned $FP revenue authority | | `POKER_MINT` = `TBA` | $FP token mint | | `TREASURY` = `TBA` | Platform Fee wallet | | `MAGIC_FEE_VAULT` = `TBA` | MagicBlock fee vault | The program IDs above are published. The PDA, mint, and wallet addresses in this section remain `TBA` until official disclosure; verify them against official release artifacts when published.