skills·poker Docs

Appearance

2026-06-14 — Custody Layer ​

A table disposition no longer pays players directly. CustodyFacet (a new facet on the EIP-2535 diamond) holds funds in a FREE/DISPUTED holding state between a table and a wallet, and distribution becomes a separate, calmer mode.

Before ​

  • escape paid each player's chips straight to their depositing wallet, with no history anchor, coupling the table's conclusion to N transfers all succeeding, and no recovery if the player had lost that wallet's keys.
  • idle_kick (sit-out timeout) did a forced on-chain withdrawFor to the last-permit-signer wallet — same lost-keys hazard.
  • Contested funds had no holding state.

After ​

  • escape → escapeToCustody: the full pool becomes per-USER FREE custody claims via an internal ledger move (no token transfer at hand-off — atomic, transfer-failure-proof); the table closes.
  • idle_kick → moveToCustody: one player's stack becomes a FREE claim (partial-pool debit), the table stays open, other seats untouched.
  • FREE claim (POST /api/custody/claim) is the verbatim table-withdrawal trust model — JWT + linkage (any linked wallet → lost-keys fix) + server-signed EIP-712 receipt with a chain-time deadline + a terminal position-chain event.
  • DISPUTED is a contract-state hold released only by server + arbiter dual-sig (with a per-entry disputeNonce so a stale arbiter signature can't replay across a re-dispute); the release memorializes like a FREE redeem.
  • A conservation reconciler (E-CUST-8) asserts deposited == diamond.balanceOf(chipToken) + paid-out + rake-collected and alarms on any delta — the system-wide silent-leakage guard.

8 fund-safety invariants (E-CUST-1..8) with greppable Enforces comments + custody.* spans. The claimable balance surfaces in the existing withdraw affordance — no custody-branded UI.

A hardening pass closed three gaps the happy-path tests couldn't see: the conservation model was rebuilt on the diamond's real balance (rake drains a separate counter that never debits tablePoolBalance); the release receipt gained a dispute nonce; and a redeem reconciler finishes the durable write when a mark fails after the on-chain redeem confirms.

Now-current pages ​

  • Custody Layer decision
  • Custody claim stuck / dispute release / conservation runbook
  • Custody conservation alarm runbook
  • Custody Layer lessons