skills·poker Docs

Appearance

Game-Admin Alignment — The Casino Model ​

Decision ​

Game-server manages chips (table-bound database records). Admin-server manages money (on-chain operations and signer addresses). The chip ledger is the interface between them.

The Casino Model ​

  • Admin-server = the cage. Players buy chips (deposits) and cash out (settle + withdraw). Owns every blockchain operation, every signer address, every permit recovery.
  • Game-server = the table. Moves chips based on game rules. Zero blockchain awareness, zero signer-address awareness. chain.ts has been deleted; the structural invariant that game-server holds no wallet data is enforced by the four Phase 7 greps described in chain-of-custody-4.
  • Chips are table-bound. Deposit to a specific table, play, withdraw when done. Standing up keeps your chips. No loose chips between tables.
  • Settlement happens on withdraw, not stand-up.

Option B Deposit / Withdraw Flow (Post chain-of-custody-4) ​

The earlier iteration of this decision routed deposits through game-server (UI → game-server forwarding to admin-server). That forwarding is gone — the UI now talks to admin-server directly, and admin-server notifies game-server over internal HTTP once the on-chain transaction confirms.

Withdraw mirrors this: UI (or service-key caller) hits POST /api/withdraw on admin-server, admin-server signs + submits settle and withdrawFor on-chain, then calls game-server POST /internal/settle-withdrawal so game-server releases the seat and transitions the participant to rail.

The custody-layer follow-up plan will introduce off-pool custody (locked / unlocked bit) for edge cases like forced panic withdrawal where the user no longer controls the deposit wallet.

Key Changes (Historical) ​

  • apps/game-server/src/chain.ts — deleted (game-admin-alignment)
  • Chip ledger is the API boundary: admin-server writes chip integers into game-server via /internal/credit-chips; game-server reports chip deltas back via /settle-withdrawal
  • Four structural invariants enforced in apps/game-server/src/ core modules: no literal wallet/Wallet, no : Hex / : Address types, no non-hash-primitive viem imports, no @numero/contracts imports. Scope boundary documented in chain-of-custody-4.

Tradeoffs ​

  • Extra HTTP hop for every deposit / withdraw (admin-server is in the path of every fund-affecting operation)
  • Admin-server is a single point of failure for funds operations — down means no deposits or withdrawals
  • Settlement is async (the in-memory seat can be released before the on-chain tx confirms; /settle-withdrawal closes the loop)

See also ​