Integration

One wire contract, two auth profiles

Choose the auth model that fits your platform. The bet, cashout, and round frames are byte-identical across both — so the integration surface never changes with the auth choice.

Seamless wallet (default)

The operator issues an opaque, single-use, ≤60s launch token at deep-link time. The game parses nothing from it and validates it server-side via the operator’s POST /authenticate.

auth_mode: "token"

JWKS (optional)

For operators that mint game-scoped RS256 JWTs: the engine validates the token against the operator’s published JWKS. Additive — configs without it default to the token profile.

auth_mode: "jwks"

Wire Invariant.

auth_mode is invisible on the wire. The auth.ok, bet.*, cashout.*, and round.* frames share one contract across both profiles — user_id is always a JSON number, and auth.ok always carries an rg_flags control set (its fields are operator- and profile-dependent). The auth mode changes only where the engine sources the session's values, not the frame contract.

Public endpoints

Unauthenticated, safe to call from anywhere — used by the fairness verifier and health checks.

Method	Path	Purpose
`GET`	`/rounds/{roundId}/verify`	Provably-fair proof bundle — settled rounds, unauthenticated.
`GET`	`/fairness/pubkey`	Attestation public keys as a JWKS.
`GET`	`/live`	Liveness probe.
`GET`	`/ready`	Readiness probe — drains gracefully (503 while draining).

Runtime topology

Deployed on Kubernetes (AKS) as a small set of pods. Real-time transport is Socket.IO carrying binary MessagePack frames.

Orchestrator: Leader-elected singleton — runs the round lifecycle (lobby → locked → tick → crashed), settlement, and the hash chain.
Bet-ingest worker: Authenticated player WebSocket (Socket.IO + MessagePack); validates the session, places bets, and relays the round feed.
Spectator replicator: Watch-only fan-out of round.* events to unauthenticated viewers — horizontally scalable.
Shared state: Postgres (rounds, bets, ledger, audit), Azure Cache for Redis (hot holds, round state), Azure Blob (hash chain, operator config).
Wallet: Seamless integration to the operator wallet over mTLS — capture on bet, credit on cashout. The engine sends gross payouts.

A build-mode stack (Postgres + Redis + Azurite + the round pipeline + spectator feed) runs from a single docker-compose with no Azure or wallet dependency — the basis for an optional live demo tier.