# Casino games — integration docs

[↓ Download Casino SDK (.zip)](/sdk/casino-sdk.zip)

This folder documents how to build **on-chain casino games** (single player vs. the house liquidity
pool) and **iframe guest UIs** for the Chain.wtf / sportsbook platform. It ships inside the
`@chain/casino-sdk` package; the runnable SDK sources live one level up in `../src`.

## Contents

| Item                                                         | Description                                                                                                                                                                            |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`CHAIN_WTF_CASINO_GAMES.md`](./CHAIN_WTF_CASINO_GAMES.md)   | **Primary integration guide**: host/guest model, Penpal bridge, `gameData` / `actionData`, ABI patterns, examples (Mines, etc.). Self-contained for a standalone Vite + Solidity repo. |
| [`CONTRACT_CONSTRAINTS.md`](./CONTRACT_CONSTRAINTS.md)       | `CasinoGameFacet` rules, timeouts, whitelist, portfolio risk, errors that revert.                                                                                                      |
| [`RANDOMNESS_DICE.md`](./RANDOMNESS_DICE.md)                 | **Agents:** unbiased d6 from `bytes32` RNG — rejection sampling (`byte < 252`); never raw `byte % 6`. Canonical Solidity/TS.                                                           |
| [`SLOTS_RISK_AND_RESERVES.md`](./SLOTS_RISK_AND_RESERVES.md) | Why slots need `quoteRiskParams` + tiered jackpot reserve; heavy-tail thresholds; `subJackpotVarianceScaled`.                                                                          |
| [`REPO_STRUCTURE.md`](./REPO_STRUCTURE.md)                   | What’s inside this `@chain/casino-sdk` package.                                                                                                                                        |
| [`VISUAL_AND_UX.md`](./VISUAL_AND_UX.md)                     | Iframe sandbox, theme/locale snapshot, manifest, optional alignment with main web app.                                                                                                 |
| [`CHANGELOG.md`](./CHANGELOG.md)                             | Date-versioned SDK release notes.                                                                                                                                                      |
| \[`../src/`]                                                  | **`@chain/casino-sdk`** sources (`types`, `guest`, `host`, `manifest` validation). Also distributed via the `@chain/ui` shadcn registry as `shadcn add @chain/casino-sdk`.             |
| \[`../solidity/ICasinoGameV2.sol`]                            | Canonical game interface (copy in repo).                                                                                                                                               |
| \[`../examples/coinflip-public/game.manifest.json`]           | Example manifest the host validates (presentation + capabilities).                                                                                                                     |

## Quick integration checklist

1. **Solidity**: Implement `ICasinoGameV2` — especially `quoteCaps`, `quoteRiskParams` (WAD probabilities), `onSessionStart`, `onPlayerAction` (if any), `onRandomness`. Slots usually: one RNG step per spin (`WAITING_RANDOMNESS` → settle) or your chosen step machine; must stay consistent with facet phase rules (see constraints doc). **d6 from bytes:** follow [`RANDOMNESS_DICE.md`](./RANDOMNESS_DICE.md) (rejection sampling).
2. **Frontend**: Guest app uses `connectGameToHost` from `./guest`; no wallet — only `hostApi.openSession` / `submitAction` / `cancelStuckRandomness` with ABI-encoded payloads.
3. **Manifest**: Serve `game.manifest.json` at the **same origin** as the game URL; `gameId` must match canonical id rules (see `manifest.ts` / host validation).
4. **Ops**: Game contract **whitelisted** on `CasinoGameFacet` + registered in indexer/catalog (internal process).

## Full risk math (optional deep read)

The complete portfolio VaR and slots tiered model is in the monorepo at `docs/CASINO_RISK_MANAGEMENT.md` (Section 6.4 — slots). This handoff folder only summarizes; that file is long but authoritative for risk terminology.

## Contact / workflow

Deliverables are typically: audited game contract + static guest build URL + manifest. Main repo owners wire whitelist, indexer rows, and catalog.