@casino-core/probably-fair 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# probably-fair
+
+Provably fair gaming module for casino platforms. Shared NPM package for server seed, client seed, nonce (custom, EOS block height, or BSC block height), deterministic random number generation, and verification.
+
+**Important:** Never log or expose the server seed. Only its hash is shown before the round; the seed is revealed after settlement for verification.
+
+## Install
+
+```bash
+npm install probably-fair
+```
+
+## Algorithm (summary)
+
+1. **Commit:** Before the round, show `getServerSeedHash(serverSeed)` to the user.
+2. **Message:** HMAC-SHA256 uses server seed as key and `clientSeed:nonce[:A:B:...]` as message (optional extra params A, B, …).
+3. **Result:** The 32-byte HMAC is converted to float(s) in [0,1] and optionally scaled to a range (e.g. dice 1–6).
+4. **Verify:** After the round, reveal the server seed; the user checks that `hash(serverSeed)` equals the committed hash and that recomputing with the same client seed, nonce, and extra params yields the same result.
+
+## API
+
+### Core (no network)
+
+- **`getServerSeedHash(serverSeed: string): string`**  
+  Returns SHA-256 hash of the server seed (pre-commitment).
+
+- **`getClientSeed(): string`**  
+  Returns the current client seed from the optional in-memory store.
+
+- **`setClientSeed(seed: string): void`**  
+  Sets the client seed in the optional in-memory store. You can also pass the client seed explicitly into other functions.
+
+- **`getNonce(options: NonceSource): number`**  
+  Returns the numeric nonce. Options:
+  - `{ type: 'custom', value: number }`
+  - `{ type: 'eos', blockHeight: number }`
+  - `{ type: 'bsc', blockHeight: number }`
+
+- **`generateRandomNumber(serverSeed, clientSeed, nonce, extraParams?, options?): number | number[]`**  
+  Deterministic random number(s).  
+  - `nonce`: `NonceSource` object or a number.  
+  - `extraParams`: optional `[A, B, ...]` (string or number) included in the HMAC message so the result is bound to these parameters.  
+  - `options`: optional `{ min, max, count, integer }` to scale and shape the output (defaults: one float in [0,1]).
+
+- **`verifyFairness(serverSeed, clientSeed, nonce, committedServerSeedHash, expectedResult, extraParams?, options?): VerifyResult`**  
+  Recomputes the result and checks that the server seed hash matches.  
+  Pass the same `extraParams` and `options` you used when generating the result.
+
+### Optional block fetchers (network)
+
+Use when the nonce is EOS or BSC block height and you want to fetch it from RPC:
+
+```js
+import { getEosBlockHeight, getBscBlockHeight } from 'probably-fair/block-fetchers';
+
+const eosBlock = await getEosBlockHeight(); // default RPC or pass URL
+const bscBlock = await getBscBlockHeight();
+// Then: getNonce({ type: 'eos', blockHeight: eosBlock }) or type: 'bsc', blockHeight: bscBlock
+```
+
+You can also obtain block height from your own backend and pass it into `getNonce` without using these fetchers.
+
+## Usage examples
+
+```js
+const {
+  getServerSeedHash,
+  setClientSeed,
+  getNonce,
+  generateRandomNumber,
+  verifyFairness,
+} = require('probably-fair');
+
+const serverSeed = 'my-secret-server-seed';
+const clientSeed = 'user-client-seed';
+const nonce = getNonce({ type: 'custom', value: 0 });
+
+// Before round: show only the hash
+const committedHash = getServerSeedHash(serverSeed);
+
+// Generate result (e.g. dice 1–6)
+const roll = generateRandomNumber(serverSeed, clientSeed, nonce, undefined, {
+  min: 1,
+  max: 6,
+  integer: true,
+});
+
+// With extra parameters [A, B, ...]
+const custom = generateRandomNumber(serverSeed, clientSeed, nonce, [10, 20], {
+  min: 0,
+  max: 99,
+  integer: true,
+});
+
+// After round: verify
+const verification = verifyFairness(
+  serverSeed,
+  clientSeed,
+  nonce,
+  committedHash,
+  roll
+);
+console.log(verification.isFair); // true
+```
+
+## Types
+
+- **`NonceSource`** – `{ type: 'custom', value } | { type: 'eos', blockHeight } | { type: 'bsc', blockHeight }`
+- **`VerifyResult`** – `{ resultMatches, serverSeedHashMatches, isFair, computedResult? }`
+- **`RandomNumberOptions`** – `{ min?, max?, count?, integer? }`
+
+## Tests
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/dist/block-fetchers/bsc.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Optional BSC block height fetcher. Use when nonce type is BSC block height.
+ * Requires fetch (Node 18+ or browser).
+ */
+export interface BscBlockNumberResponse {
+    result?: string;
+}
+/**
+ * Fetch current BSC block number from RPC. Use this value as nonce (e.g. getNonce({ type: 'bsc', blockHeight })).
+ */
+export declare function getBscBlockHeight(rpcUrl?: string): Promise<number>;
+//# sourceMappingURL=bsc.d.ts.map

package/dist/block-fetchers/bsc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bsc.d.ts","sourceRoot":"","sources":["../../src/block-fetchers/bsc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,GAAE,MAAwB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAoBjB"}

package/dist/block-fetchers/bsc.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Optional BSC block height fetcher. Use when nonce type is BSC block height.
+ * Requires fetch (Node 18+ or browser).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBscBlockHeight = getBscBlockHeight;
+const DEFAULT_BSC_RPC = "https://bsc-dataseed.binance.org/";
+/**
+ * Fetch current BSC block number from RPC. Use this value as nonce (e.g. getNonce({ type: 'bsc', blockHeight })).
+ */
+async function getBscBlockHeight(rpcUrl = DEFAULT_BSC_RPC) {
+    const res = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            method: "eth_blockNumber",
+            params: [],
+            id: 1,
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`BSC RPC error: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    const hex = data.result;
+    if (typeof hex !== "string") {
+        throw new Error("BSC eth_blockNumber did not return result");
+    }
+    return parseInt(hex, 16);
+}
+//# sourceMappingURL=bsc.js.map

package/dist/block-fetchers/bsc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bsc.js","sourceRoot":"","sources":["../../src/block-fetchers/bsc.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAWH,8CAsBC;AA/BD,MAAM,eAAe,GAAG,mCAAmC,CAAC;AAM5D;;GAEG;AACI,KAAK,UAAU,iBAAiB,CACrC,SAAiB,eAAe;IAEhC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,EAAE;QAC9B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACnB,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,iBAAiB;YACzB,MAAM,EAAE,EAAE;YACV,EAAE,EAAE,CAAC;SACN,CAAC;KACH,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA2B,CAAC;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;IACxB,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC3B,CAAC"}

package/dist/block-fetchers/eos.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Optional EOS block height fetcher. Use when nonce type is EOS block height.
+ * Requires fetch (Node 18+ or browser).
+ */
+export interface EosGetInfoResponse {
+    head_block_num?: number;
+    last_irreversible_block_num?: number;
+}
+/**
+ * Fetch current EOS block height from RPC. Use this value as nonce (e.g. getNonce({ type: 'eos', blockHeight })).
+ */
+export declare function getEosBlockHeight(rpcUrl?: string): Promise<number>;
+//# sourceMappingURL=eos.d.ts.map

package/dist/block-fetchers/eos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eos.d.ts","sourceRoot":"","sources":["../../src/block-fetchers/eos.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2BAA2B,CAAC,EAAE,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,GAAE,MAAwB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/dist/block-fetchers/eos.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Optional EOS block height fetcher. Use when nonce type is EOS block height.
+ * Requires fetch (Node 18+ or browser).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEosBlockHeight = getEosBlockHeight;
+const DEFAULT_EOS_RPC = "https://eos.greymass.com/v1/chain/get_info";
+/**
+ * Fetch current EOS block height from RPC. Use this value as nonce (e.g. getNonce({ type: 'eos', blockHeight })).
+ */
+async function getEosBlockHeight(rpcUrl = DEFAULT_EOS_RPC) {
+    const res = await fetch(rpcUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+    });
+    if (!res.ok) {
+        throw new Error(`EOS RPC error: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    const blockNum = data.head_block_num ?? data.last_irreversible_block_num;
+    if (typeof blockNum !== "number") {
+        throw new Error("EOS get_info did not return block number");
+    }
+    return blockNum;
+}
+//# sourceMappingURL=eos.js.map

package/dist/block-fetchers/eos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eos.js","sourceRoot":"","sources":["../../src/block-fetchers/eos.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAYH,8CAiBC;AA3BD,MAAM,eAAe,GAAG,4CAA4C,CAAC;AAOrE;;GAEG;AACI,KAAK,UAAU,iBAAiB,CACrC,SAAiB,eAAe;IAEhC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,EAAE;QAC9B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;KACzB,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,2BAA2B,CAAC;IACzE,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/block-fetchers/index.d.ts

@@ -0,0 +1,5 @@
+export { getEosBlockHeight } from "./eos";
+export type { EosGetInfoResponse } from "./eos";
+export { getBscBlockHeight } from "./bsc";
+export type { BscBlockNumberResponse } from "./bsc";
+//# sourceMappingURL=index.d.ts.map

package/dist/block-fetchers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/block-fetchers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAC1C,YAAY,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAC1C,YAAY,EAAE,sBAAsB,EAAE,MAAM,OAAO,CAAC"}

package/dist/block-fetchers/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBscBlockHeight = exports.getEosBlockHeight = void 0;
+var eos_1 = require("./eos");
+Object.defineProperty(exports, "getEosBlockHeight", { enumerable: true, get: function () { return eos_1.getEosBlockHeight; } });
+var bsc_1 = require("./bsc");
+Object.defineProperty(exports, "getBscBlockHeight", { enumerable: true, get: function () { return bsc_1.getBscBlockHeight; } });
+//# sourceMappingURL=index.js.map

package/dist/block-fetchers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/block-fetchers/index.ts"],"names":[],"mappings":";;;AAAA,6BAA0C;AAAjC,wGAAA,iBAAiB,OAAA;AAE1B,6BAA0C;AAAjC,wGAAA,iBAAiB,OAAA"}

package/dist/crypto.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SHA-256 hash of the server seed (for pre-commitment).
+ */
+export declare function sha256Hex(input: string): string;
+/**
+ * HMAC-SHA256 with server seed as key and message as data.
+ */
+export declare function hmacSha256Hex(key: string, message: string): string;
+/**
+ * HMAC-SHA256 raw bytes (32 bytes).
+ */
+export declare function hmacSha256Bytes(key: string, message: string): Buffer;
+/**
+ * Convert 32 bytes to floats in [0, 1] by taking 4-byte chunks (big-endian) and dividing by 2^32.
+ */
+export declare function bytesToFloats(bytes: Buffer, count: number): number[];
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAOpE"}

package/dist/crypto.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Hex = sha256Hex;
+exports.hmacSha256Hex = hmacSha256Hex;
+exports.hmacSha256Bytes = hmacSha256Bytes;
+exports.bytesToFloats = bytesToFloats;
+const crypto_1 = require("crypto");
+const ENCODING = "hex";
+/**
+ * SHA-256 hash of the server seed (for pre-commitment).
+ */
+function sha256Hex(input) {
+    return (0, crypto_1.createHash)("sha256").update(input, "utf8").digest(ENCODING);
+}
+/**
+ * HMAC-SHA256 with server seed as key and message as data.
+ */
+function hmacSha256Hex(key, message) {
+    return (0, crypto_1.createHmac)("sha256", key).update(message, "utf8").digest(ENCODING);
+}
+/**
+ * HMAC-SHA256 raw bytes (32 bytes).
+ */
+function hmacSha256Bytes(key, message) {
+    return (0, crypto_1.createHmac)("sha256", key).update(message, "utf8").digest();
+}
+/**
+ * Convert 32 bytes to floats in [0, 1] by taking 4-byte chunks (big-endian) and dividing by 2^32.
+ */
+function bytesToFloats(bytes, count) {
+    const out = [];
+    for (let i = 0; i < count && i * 4 + 4 <= bytes.length; i++) {
+        const uint = bytes.readUInt32BE(i * 4);
+        out.push(uint / 4294967296);
+    }
+    return out;
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":";;AAOA,8BAEC;AAKD,sCAEC;AAKD,0CAEC;AAKD,sCAOC;AAnCD,mCAAgD;AAEhD,MAAM,QAAQ,GAAG,KAAc,CAAC;AAEhC;;GAEG;AACH,SAAgB,SAAS,CAAC,KAAa;IACrC,OAAO,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACrE,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,GAAW,EAAE,OAAe;IACxD,OAAO,IAAA,mBAAU,EAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC5E,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,GAAW,EAAE,OAAe;IAC1D,OAAO,IAAA,mBAAU,EAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;AACpE,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,KAAa,EAAE,KAAa;IACxD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACvC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,UAAa,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import type { NonceSource, VerifyResult, RandomNumberOptions } from "./types";
+/**
+ * Returns SHA-256 hash of the server seed (pre-commitment shown to user before round).
+ */
+export declare function getServerSeedHash(serverSeed: string): string;
+/**
+ * Get the current client seed (from optional in-memory store).
+ */
+export declare function getClientSeed(): string;
+/**
+ * Set the client seed (optional in-memory store). Platforms can also pass client seed per call.
+ */
+export declare function setClientSeed(seed: string): void;
+/**
+ * Return the numeric nonce from the given nonce source (custom, EOS block height, or BSC block height).
+ */
+export declare function getNonce(options: NonceSource): number;
+/**
+ * Generate deterministic random number(s). Optional extraParams [A, B, ...] are included in the HMAC message.
+ */
+export declare function generateRandomNumber(serverSeed: string, clientSeed: string, nonce: NonceSource | number, extraParams?: (string | number)[], options?: RandomNumberOptions): number | number[];
+/**
+ * Verify fairness: recompute result and check server seed hash.
+ */
+export declare function verifyFairness(serverSeed: string, clientSeed: string, nonce: NonceSource | number, committedServerSeedHash: string, expectedResult: number | number[], extraParams?: (string | number)[], options?: RandomNumberOptions): VerifyResult;
+export type { NonceSource, VerifyResult, RandomNumberOptions };
+//# 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":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAK9E;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAErD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,GAAG,MAAM,EAC3B,WAAW,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACjC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,MAAM,GAAG,MAAM,EAAE,CAQnB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,GAAG,MAAM,EAC3B,uBAAuB,EAAE,MAAM,EAC/B,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,EACjC,WAAW,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACjC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,YAAY,CAUd;AAED,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getServerSeedHash = getServerSeedHash;
+exports.getClientSeed = getClientSeed;
+exports.setClientSeed = setClientSeed;
+exports.getNonce = getNonce;
+exports.generateRandomNumber = generateRandomNumber;
+exports.verifyFairness = verifyFairness;
+const crypto_1 = require("./crypto");
+const nonce_1 = require("./nonce");
+const verify_1 = require("./verify");
+/** In-memory client seed for getClientSeed/setClientSeed (optional convenience). */
+let clientSeedStore = "";
+/**
+ * Returns SHA-256 hash of the server seed (pre-commitment shown to user before round).
+ */
+function getServerSeedHash(serverSeed) {
+    return (0, crypto_1.sha256Hex)(serverSeed);
+}
+/**
+ * Get the current client seed (from optional in-memory store).
+ */
+function getClientSeed() {
+    return clientSeedStore;
+}
+/**
+ * Set the client seed (optional in-memory store). Platforms can also pass client seed per call.
+ */
+function setClientSeed(seed) {
+    clientSeedStore = seed;
+}
+/**
+ * Return the numeric nonce from the given nonce source (custom, EOS block height, or BSC block height).
+ */
+function getNonce(options) {
+    return (0, nonce_1.getNonce)(options);
+}
+/**
+ * Generate deterministic random number(s). Optional extraParams [A, B, ...] are included in the HMAC message.
+ */
+function generateRandomNumber(serverSeed, clientSeed, nonce, extraParams, options) {
+    return (0, verify_1.generateRandomNumber)(serverSeed, clientSeed, nonce, extraParams, options);
+}
+/**
+ * Verify fairness: recompute result and check server seed hash.
+ */
+function verifyFairness(serverSeed, clientSeed, nonce, committedServerSeedHash, expectedResult, extraParams, options) {
+    return (0, verify_1.verifyFairness)(serverSeed, clientSeed, nonce, committedServerSeedHash, expectedResult, extraParams, options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAcA,8CAEC;AAKD,sCAEC;AAKD,sCAEC;AAKD,4BAEC;AAKD,oDAcC;AAKD,wCAkBC;AA/ED,qCAAqC;AACrC,mCAAoD;AACpD,qCAGkB;AAGlB,oFAAoF;AACpF,IAAI,eAAe,GAAW,EAAE,CAAC;AAEjC;;GAEG;AACH,SAAgB,iBAAiB,CAAC,UAAkB;IAClD,OAAO,IAAA,kBAAS,EAAC,UAAU,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa;IAC3B,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,IAAY;IACxC,eAAe,GAAG,IAAI,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,SAAgB,QAAQ,CAAC,OAAoB;IAC3C,OAAO,IAAA,gBAAa,EAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,SAAgB,oBAAoB,CAClC,UAAkB,EAClB,UAAkB,EAClB,KAA2B,EAC3B,WAAiC,EACjC,OAA6B;IAE7B,OAAO,IAAA,6BAAS,EACd,UAAU,EACV,UAAU,EACV,KAAK,EACL,WAAW,EACX,OAAO,CACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc,CAC5B,UAAkB,EAClB,UAAkB,EAClB,KAA2B,EAC3B,uBAA+B,EAC/B,cAAiC,EACjC,WAAiC,EACjC,OAA6B;IAE7B,OAAO,IAAA,uBAAU,EACf,UAAU,EACV,UAAU,EACV,KAAK,EACL,uBAAuB,EACvB,cAAc,EACd,WAAW,EACX,OAAO,CACR,CAAC;AACJ,CAAC"}

package/dist/nonce.d.ts

@@ -0,0 +1,7 @@
+import type { NonceSource } from "./types";
+/**
+ * Returns the numeric nonce from the given nonce source.
+ * Core module only uses the number; no HTTP. Use block-fetchers for EOS/BSC RPC.
+ */
+export declare function getNonce(options: NonceSource): number;
+//# sourceMappingURL=nonce.d.ts.map

package/dist/nonce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce.d.ts","sourceRoot":"","sources":["../src/nonce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAarD"}

package/dist/nonce.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNonce = getNonce;
+/**
+ * Returns the numeric nonce from the given nonce source.
+ * Core module only uses the number; no HTTP. Use block-fetchers for EOS/BSC RPC.
+ */
+function getNonce(options) {
+    switch (options.type) {
+        case "custom":
+            return options.value;
+        case "eos":
+            return options.blockHeight;
+        case "bsc":
+            return options.blockHeight;
+        default: {
+            const _ = options;
+            throw new Error("Invalid nonce source");
+        }
+    }
+}
+//# sourceMappingURL=nonce.js.map

package/dist/nonce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonce.js","sourceRoot":"","sources":["../src/nonce.ts"],"names":[],"mappings":";;AAMA,4BAaC;AAjBD;;;GAGG;AACH,SAAgB,QAAQ,CAAC,OAAoB;IAC3C,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,QAAQ;YACX,OAAO,OAAO,CAAC,KAAK,CAAC;QACvB,KAAK,KAAK;YACR,OAAO,OAAO,CAAC,WAAW,CAAC;QAC7B,KAAK,KAAK;YACR,OAAO,OAAO,CAAC,WAAW,CAAC;QAC7B,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,CAAC,GAAU,OAAO,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Nonce source: custom number, EOS block height, or BSC block height.
+ */
+export type NonceSource = {
+    type: "custom";
+    value: number;
+} | {
+    type: "eos";
+    blockHeight: number;
+} | {
+    type: "bsc";
+    blockHeight: number;
+};
+/**
+ * Result of verifyFairness().
+ */
+export interface VerifyResult {
+    /** Whether the recomputed result matches the expected result. */
+    resultMatches: boolean;
+    /** Whether the server seed hash matches the committed hash. */
+    serverSeedHashMatches: boolean;
+    /** Whether both checks passed (fair). */
+    isFair: boolean;
+    /** Recomputed result for debugging. */
+    computedResult?: number | number[];
+}
+/**
+ * Options for generating random number(s).
+ */
+export interface RandomNumberOptions {
+    /** Minimum value (inclusive). Default 0. */
+    min?: number;
+    /** Maximum value (inclusive). Default 1. */
+    max?: number;
+    /** Number of values to generate. Default 1. */
+    count?: number;
+    /** If true, return integers; otherwise floats in [min, max]. Default true when min/max are integers. */
+    integer?: boolean;
+}
+//# 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;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,aAAa,EAAE,OAAO,CAAC;IACvB,+DAA+D;IAC/D,qBAAqB,EAAE,OAAO,CAAC;IAC/B,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wGAAwG;IACxG,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# 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/dist/verify.d.ts

@@ -0,0 +1,11 @@
+import type { VerifyResult, RandomNumberOptions } from "./types";
+import type { NonceSource } from "./types";
+/**
+ * Generate deterministic random number(s) from server seed, client seed, nonce, and optional extra params.
+ */
+export declare function generateRandomNumber(serverSeed: string, clientSeed: string, nonce: NonceSource | number, extraParams?: (string | number)[], options?: RandomNumberOptions): number | number[];
+/**
+ * Verify fairness: check server seed hash and recompute result.
+ */
+export declare function verifyFairness(serverSeed: string, clientSeed: string, nonce: NonceSource | number, committedServerSeedHash: string, expectedResult: number | number[], extraParams?: (string | number)[], options?: RandomNumberOptions): VerifyResult;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAgC3C;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,GAAG,MAAM,EAC3B,WAAW,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACjC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,MAAM,GAAG,MAAM,EAAE,CAenB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,WAAW,GAAG,MAAM,EAC3B,uBAAuB,EAAE,MAAM,EAC/B,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,EACjC,WAAW,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACjC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,YAAY,CA8Bd"}

package/dist/verify.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRandomNumber = generateRandomNumber;
+exports.verifyFairness = verifyFairness;
+const crypto_1 = require("./crypto");
+const nonce_1 = require("./nonce");
+/**
+ * Build the HMAC message: clientSeed:nonce[:extraParams...]
+ */
+function buildMessage(clientSeed, nonceValue, extraParams) {
+    const parts = [clientSeed, String(nonceValue)];
+    if (extraParams?.length) {
+        parts.push(...extraParams.map(String));
+    }
+    return parts.join(":");
+}
+/**
+ * Scale float in [0,1] to [min, max]. If integer, round to integer in range.
+ */
+function scaleToRange(float, min, max, integer) {
+    if (integer) {
+        return min + Math.floor(float * (max - min + 1));
+    }
+    return min + float * (max - min);
+}
+/**
+ * Generate deterministic random number(s) from server seed, client seed, nonce, and optional extra params.
+ */
+function generateRandomNumber(serverSeed, clientSeed, nonce, extraParams, options) {
+    const nonceValue = typeof nonce === "number" ? nonce : (0, nonce_1.getNonce)(nonce);
+    const message = buildMessage(clientSeed, nonceValue, extraParams);
+    const bytes = (0, crypto_1.hmacSha256Bytes)(serverSeed, message);
+    const min = options?.min ?? 0;
+    const max = options?.max ?? 1;
+    const count = options?.count ?? 1;
+    const integer = options?.integer ?? (Number.isInteger(min) && Number.isInteger(max));
+    const floats = (0, crypto_1.bytesToFloats)(bytes, count);
+    const scaled = floats.map((f) => scaleToRange(f, min, max, integer));
+    return count === 1 ? scaled[0] : scaled;
+}
+/**
+ * Verify fairness: check server seed hash and recompute result.
+ */
+function verifyFairness(serverSeed, clientSeed, nonce, committedServerSeedHash, expectedResult, extraParams, options) {
+    const computedHash = (0, crypto_1.sha256Hex)(serverSeed);
+    const serverSeedHashMatches = computedHash === committedServerSeedHash;
+    const nonceValue = typeof nonce === "number" ? nonce : (0, nonce_1.getNonce)(nonce);
+    const computedResult = generateRandomNumber(serverSeed, clientSeed, nonceValue, extraParams, options);
+    const computedArr = Array.isArray(computedResult)
+        ? computedResult
+        : [computedResult];
+    const expectedArr = Array.isArray(expectedResult)
+        ? expectedResult
+        : [expectedResult];
+    const resultMatches = computedArr.length === expectedArr.length &&
+        computedArr.every((v, i) => v === expectedArr[i]);
+    return {
+        resultMatches,
+        serverSeedHashMatches,
+        isFair: resultMatches && serverSeedHashMatches,
+        computedResult,
+    };
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@casino-core/probably-fair",
+  "version": "1.0.0",
+  "description": "Provably fair gaming module for casino platforms – server/client seeds, configurable nonce, verification",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./block-fetchers": {
+      "import": "./dist/block-fetchers/index.js",
+      "require": "./dist/block-fetchers/index.js",
+      "types": "./dist/block-fetchers/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/huberco/provably-fair.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "provably-fair",
+    "casino",
+    "gaming",
+    "server-seed",
+    "client-seed",
+    "nonce",
+    "verification"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  }
+}