# Casino SDK Build casino games against the house liquidity pool with engines or custom contracts. You bring the rules and the frontend; the host handles wallets, signing, and session state. :::note[Current SDK checkout] - `@chain-protocol/casino-sdk@0.7.0` This guidance reflects this checkout and may include unreleased changes. [Casino changelog](/sdk/casino/changelog/) ::: Build **on-chain casino games** — single player vs. the house liquidity pool — that run inside the Chain.wtf platform as sandboxed iframes. A game is its rules plus a static web frontend that talks to the host app through the `@chain-protocol/casino-sdk` bridge. Your frontend contains no wallet code: the host signs every transaction, streams state snapshots into your iframe, and handles gasless betting, balances and session tracking for you. You focus on game logic and presentation. **Write the rules for an engine whenever your game fits one.** The [slot engine](/sdk/casino/slot-engine/) plays one-draw games such as slots and Limbo. The [graph engine](/sdk/casino/graph-engine/) plays multi-step games such as Hilo, blackjack and roulette. You write no Solidity, the chain checks your game's math when it deploys, and the platform reviews your frontend only. A game at or below the approval ceiling (98% at genesis) joins the offering as soon as it deploys. Write your own `ICasinoGameV2` contract only when neither engine fits. See [Getting Started → Choose how to write your game](/sdk/casino/getting-started/#choose-how-to-write-your-game). Install it from npm, together with the `chain` command at the same version: ```sh npm install @chain-protocol/casino-sdk npm install --save-dev @chain-protocol/cli ``` With Bun: `bun add @chain-protocol/casino-sdk` and `bun add --dev @chain-protocol/cli`. `chain dev casino` runs the [SDK simulator](/sdk/casino/local-simulator/) in your repository: a dev chain, a real VRF node, a minimal casino deployment and a simulator page that behaves like the production host. You build and test the whole game on your machine without any platform access. **New here? Start with [Getting Started](/sdk/casino/getting-started/).** `npx @chain-protocol/cli init casino my-game` creates a game from the coinflip example, and the guide takes you from there to a round played locally. ## Documentation | Guide | What it covers | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [Getting Started](/sdk/casino/getting-started/) | **Start here.** Step-by-step: create a game with `chain init`, play it with `chain dev`, write the contract, build the UI, ship. | | [Local Simulator](/sdk/casino/local-simulator/) | `chain dev casino`: what it runs, what it replicates from production, how to break things on purpose. | | [Building Casino Games](/sdk/casino/building-games/) | **The complete reference**: host/guest model, Penpal bridge, `gameData` / `actionData`, ABI patterns, SDK versions and canaries, frontend examples. | | [Contract Constraints](/sdk/casino/contract-constraints/) | `CasinoGameFacet` rules your contract must respect, and what your quotes decide: your fees, your bet-size cap, the errors a bad quote raises. | | [Randomness → Dice](/sdk/casino/randomness-dice/) | Deriving unbiased dice/cards from `bytes32` RNG — rejection sampling, never raw `byte % 6`. Canonical Solidity/TS. | | [Slots Risk & Reserves](/sdk/casino/slots-risk-and-reserves/) | Why heavy-tail games (slots, jackpots) need `quoteRiskParams` + a tiered jackpot reserve. | | [Slot Engine](/sdk/casino/slot-engine/) | **Preferred for one-draw games.** Ship a slot or threshold game on the shared slot engine, no Solidity. | | [Graph Engine](/sdk/casino/graph-engine/) | **Preferred for multi-step games.** Write the game as a TypeScript state machine; the shared graph engine plays it, no Solidity. | | [Migrating from Stake Engine](/sdk/casino/migrating-from-stake-engine/) | Convert a Stake Engine math export into a slot engine title and port its frontend. | | [Visual & UX](/sdk/casino/visual-and-ux/) | Iframe sandbox, theme/locale snapshot, manifest presentation, aligning with the main app's look. | | [Repo Structure](/sdk/casino/repo-structure/) | What the `@chain-protocol/casino-sdk` package ships, and what a game created with `chain init` holds. | | [Changelog](/sdk/casino/changelog/) | Release notes for every SDK version. | ## What's in the package - `@chain-protocol/casino-sdk/guest`: `connectGameToHost`, for your frontend. - `@chain-protocol/casino-sdk`: shared types, manifest validation, `defineDeployment` and `hostSupports`. - `@chain-protocol/casino-sdk/contracts/ICasinoGameV2.sol`: the canonical on-chain game interface. - `@chain-protocol/casino-sdk/slot-engine`: the slot engine, with its contracts and the title compiler ([docs](/sdk/casino/slot-engine/)). `./slot-engine/threshold` holds the browser-safe threshold helpers. - `@chain-protocol/casino-sdk/graph-engine`: the graph engine, with its contracts, the compiler, the reference walks and the quote helpers ([docs](/sdk/casino/graph-engine/)). `./host`, `./simulator` and `./conformance` are internal: they serve the Chain.wtf host, `chain dev casino` and `game-verify`, sit outside semver and can change in any release. The coinflip example ships inside `@chain-protocol/cli` as the template `chain init casino` copies. ## The short version of shipping a game With an engine: 1. **Title**: write the game for the [slot engine](/sdk/casino/slot-engine/) or the [graph engine](/sdk/casino/graph-engine/), and point `deployment.ts` at it. 2. **Frontend and manifest**: as below. 3. **Submit** through the developer platform. The chain checks the math, the review covers the frontend only, and a game at or below the approval ceiling is whitelisted when it deploys. With your own contract: 1. **Contract**: implement `ICasinoGameV2` — `quoteCaps`, `quoteRiskParams`, `onSessionStart`, `onRandomness`, and `onPlayerAction` for multi-step games. Your quotes set your fees and your maximum wager: see [What your quotes decide](/sdk/casino/contract-constraints/#what-your-quotes-decide). 2. **Frontend**: call `connectGameToHost`, render from the host snapshot, place bets via `hostApi.openSession` / `submitAction`, and call `revealOutcome` after your win animation. 3. **Manifest**: serve `game.manifest.json` at the same origin as the game URL. 4. **Handoff**: deliver the audited contract and the hosted static build. The contract registers as a pending game until the security council approves it, and the Chain.wtf maintainers wire the indexer and catalog. ## Going deeper on risk math [`SLOTS_RISK_AND_RESERVES.md`](/sdk/casino/slots-risk-and-reserves/) describes the portfolio VaR and the slots tiered model, including the body variance your quote must carry. The contracts (`ICasinoGameV2`, `CasinoGameFacet`, `VaultReserveLib`) are the source of truth for field names and units.