@octane-rgs/fairness 1.0.9

package/README.md

@@ -0,0 +1,65 @@
+# @octane-rgs/fairness
+
+SDK for provably fair RNG generation, seed reveal, and audit tooling for Octane RGS. It also keeps the lightweight round-operation helpers used by live or external services that need explicit settlement.
+
+## Install
+
+```bash
+npm install @octane-rgs/fairness
+```
+
+## Quick Start — Live Games
+
+For live games where the external game server controls the round lifecycle:
+
+```typescript
+import { OctaneFairnessClient } from "@octane-rgs/fairness";
+
+const rgs = new OctaneFairnessClient({
+  baseUrl: "https://staging.octanestudios.ai",
+  apiKey: "your-api-key",
+});
+
+// Fetch floats from the RGS
+const { values } = await rgs.fetchRng({ roundId, count: 6 });
+
+// Update round data with game results
+await rgs.updateRoundOutcome(roundId, { grid: [[1, 2, 3]], winLines: [0] });
+
+// Settle the round explicitly
+await rgs.settle({
+  roundId,
+  gameType: "roulette",
+  closeRound: true,
+  multipliers: [{ betOption: "red", multiplier: 2 }],
+});
+```
+
+## API
+
+### OctaneFairnessClient
+
+| Method | Description |
+|--------|-------------|
+| `settle(params)` | Settle a round explicitly (live games) |
+| `updateRoundOutcome(roundId, data)` | Store game outcome data on a round |
+| `fetchRng(params)` | Fetch provably fair random numbers from the RGS (live games) |
+| `revealSeed(params)` | Reveal server seed for verification |
+
+### RNG (re-exported from `@octane-rgs/rng`)
+
+| Function | Description |
+|----------|-------------|
+| `createFloatGenerator(serverSeed, clientSeed, nonce)` | Create a stateful generator yielding floats in `[0, 1)` |
+| `createFloatGenerator(seed)` | Same, accepts a `Seed` object |
+| `verify(serverSeed, clientSeed, nonce, count)` | Reproduce N floats + server seed hash for verification |
+| `hashSeed(serverSeed)` | SHA-256 hash of a server seed |
+
+### Types (re-exported from `@octane-rgs/rng`)
+
+| Type | Description |
+|------|-------------|
+| `Seed` | `{ serverSeed, clientSeed, nonce }` |
+| `FloatGenerator` | `{ generateFloat(), generateFloats(count) }` |
+| `VerifyResult` | `{ values, serverSeedHash }` |
+

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+import type { RgsClientOptions, SettleParams, SettleResult, RoundRecord, RngParams, RngResult, RevealSeedParams } from "./types.js";
+export declare class RgsError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare class OctaneFairnessClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchInit;
+    constructor(options: RgsClientOptions);
+    private post;
+    settle(params: SettleParams): Promise<SettleResult>;
+    updateRoundOutcome(roundId: string, gameRoundData: Record<string, unknown>): Promise<{
+        round: RoundRecord;
+    }>;
+    fetchRng(params: RngParams): Promise<RngResult>;
+    revealSeed(params: RevealSeedParams): Promise<{
+        serverSeed: string;
+        clientSeed: string;
+        nonce: number;
+    }>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,gBAAgB,EAChB,YAAY,EAAE,YAAY,EAAE,WAAW,EACvC,SAAS,EAAE,SAAS,EAAE,gBAAgB,EACzC,MAAM,YAAY,CAAC;AAEpB,qBAAa,QAAS,SAAQ,KAAK;aAEc,MAAM,EAAE,MAAM;gBAA/C,OAAO,EAAE,MAAM,EAAkB,MAAM,EAAE,MAAM;CAC9D;AAED,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAE5B,OAAO,EAAE,gBAAgB;YAOvB,IAAI;IAqBlB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAOnD,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,CAAC;IAO5G,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAK/C,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAI3G"}

package/dist/client.js

@@ -0,0 +1,47 @@
+export class RgsError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export class OctaneFairnessClient {
+    baseUrl;
+    apiKey;
+    fetchInit;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.apiKey = options.apiKey;
+        this.fetchInit = options.fetchInit ?? {};
+    }
+    async post(path, body) {
+        const res = await fetch(`${this.baseUrl}/api/v1${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "X-Api-Key": this.apiKey },
+            body: JSON.stringify(body),
+            ...this.fetchInit,
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            const msg = typeof err.error === "string" ? err.error : JSON.stringify(err.error ?? `RGS ${res.status}`);
+            throw new RgsError(msg, res.status);
+        }
+        return res.json();
+    }
+    // ── Settlement ──────────────────────────────────────────────
+    settle(params) {
+        return this.post("/bets/settle", params);
+    }
+    // ── Round Data ──────────────────────────────────────────────
+    updateRoundOutcome(roundId, gameRoundData) {
+        return this.post("/sessions/update-round-outcome", { roundId, gameRoundData });
+    }
+    // ── RNG ─────────────────────────────────────────────────────
+    fetchRng(params) {
+        return this.post("/rng/generate", params);
+    }
+    revealSeed(params) {
+        return this.post("/rng/reveal", params);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,QAAS,SAAQ,KAAK;IAEc;IAA7C,YAAY,OAAe,EAAkB,MAAc;QAAI,KAAK,CAAC,OAAO,CAAC,CAAC;QAAjC,WAAM,GAAN,MAAM,CAAQ;IAAoB,CAAC;CACnF;AAED,MAAM,OAAO,oBAAoB;IAEZ,OAAO,CAAS;IAChB,MAAM,CAAS;IACf,SAAS,CAAc;IAExC,YAAY,OAAyB;QAEjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IAC7C,CAAC;IAEO,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,IAAa;QAE7C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,UAAU,IAAI,EAAE,EAAE;YACrD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;YACzE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,GAAG,IAAI,CAAC,SAAS;SACpB,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EACX,CAAC;YACG,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;YACtE,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,IAAI,OAAO,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YACzG,MAAM,IAAI,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,GAAG,CAAC,IAAI,EAAgB,CAAC;IACpC,CAAC;IAED,+DAA+D;IAE/D,MAAM,CAAC,MAAoB;QAEvB,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,+DAA+D;IAE/D,kBAAkB,CAAC,OAAe,EAAE,aAAsC;QAEtE,OAAO,IAAI,CAAC,IAAI,CAAC,gCAAgC,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,+DAA+D;IAE/D,QAAQ,CAAC,MAAiB;QAEtB,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED,UAAU,CAAC,MAAwB;QAE/B,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { OctaneFairnessClient, RgsError } from "./client.js";
+export type { RgsClientOptions, SettleParams, SettleResult, SettlementMultiplier, RoundRecord, RngParams, RngResult, RevealSeedParams, } from "./types.js";
+export { hashSeed, createFloatGenerator, verify } from "@octane-rgs/rng";
+export type { Seed, FloatGenerator, VerifyResult } from "@octane-rgs/rng";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EACR,gBAAgB,EAChB,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAChD,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,GACtD,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { OctaneFairnessClient, RgsError } from "./client.js";
+export { hashSeed, createFloatGenerator, verify } from "@octane-rgs/rng";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAM7D,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+export interface RgsClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    fetchInit?: RequestInit;
+}
+export interface SettlementMultiplier {
+    betOption: string;
+    multiplier: number;
+    scale?: number;
+}
+export interface SettleParams {
+    roundId: string;
+    gameType: string;
+    closeRound?: boolean;
+    multipliers: SettlementMultiplier[];
+}
+export interface SettleResult {
+    settled: boolean;
+    status: "settled" | "already_settled" | "not_found" | "no_bets";
+    playerCount?: number;
+    payoutsSucceeded?: number;
+    payoutsFailed?: number;
+}
+export interface RoundRecord {
+    id: string;
+    tableSession: string;
+    roundNumber: number;
+    bettingOpenAt: string;
+    bettingClosedAt: string;
+    createdAt: string;
+    gameRoundData: Record<string, unknown> | null;
+    status: string;
+}
+export interface RngParams {
+    sessionToken?: string;
+    roundId?: string;
+    count?: number;
+    clientSeed?: string;
+}
+export interface RngResult {
+    values: number[];
+    serverSeedHash: string;
+    clientSeed: string;
+    nonce: number;
+}
+export interface RevealSeedParams {
+    sessionToken?: string;
+    roundId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAE7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IAEjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAEzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,oBAAoB,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAEzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,iBAAiB,GAAG,WAAW,GAAG,SAAS,CAAC;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAExB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IAEtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IAEtB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAE7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@octane-rgs/fairness",
+  "version": "1.0.9",
+  "description": "Provably fair RNG and audit tooling for Octane RGS",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@octane-rgs/rng": "1.0.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  },
+  "license": "UNLICENSED"
+}