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.

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 plays one-draw games such as slots and Limbo. The 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.

Install it from npm, together with the chain command at the same version:

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 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. 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	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	`chain dev casino`: what it runs, what it replicates from production, how to break things on purpose.
Building Casino Games	The complete reference: host/guest model, Penpal bridge, `gameData` / `actionData`, ABI patterns, SDK versions and canaries, frontend examples.
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	Deriving unbiased dice/cards from `bytes32` RNG — rejection sampling, never raw `byte % 6`. Canonical Solidity/TS.
Slots Risk & Reserves	Why heavy-tail games (slots, jackpots) need `quoteRiskParams` + a tiered jackpot reserve.
Slot Engine	Preferred for one-draw games. Ship a slot or threshold game on the shared slot engine, no Solidity.
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	Convert a Stake Engine math export into a slot engine title and port its frontend.
Visual & UX	Iframe sandbox, theme/locale snapshot, manifest presentation, aligning with the main app’s look.
Repo Structure	What the `@chain-protocol/casino-sdk` package ships, and what a game created with `chain init` holds.
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). ./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).

./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:

Title: write the game for the slot engine or the graph engine, and point deployment.ts at it.
Frontend and manifest: as below.
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:

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.
Frontend: call connectGameToHost, render from the host snapshot, place bets via hostApi.openSession / submitAction, and call revealOutcome after your win animation.
Manifest: serve game.manifest.json at the same origin as the game URL.
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 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.