{"_id":"@casino-core/probably-fair","name":"@casino-core/probably-fair","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"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"}},"repository":{"type":"git","url":"git+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"},"_id":"@casino-core/probably-fair@1.0.0","bugs":{"url":"https://github.com/huberco/provably-fair/issues"},"homepage":"https://github.com/huberco/provably-fair#readme","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-fUEG30Zc4HHa1BJKlhjyOUTHKlg8BFSxSAryH+qUeudPDPwlaA57o3FFaINA8AfpkxU6GBM9xkKBX6jRgtOb1w==","shasum":"649db9cbffb12d2f2c1babb7f4ebfad72a0a75ea","tarball":"https://registry.npmjs.org/@casino-core/probably-fair/-/probably-fair-1.0.0.tgz","fileCount":34,"unpackedSize":30979,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAmqm64xqhofQIiIsIwL2QOV1uJmTHBMN8uAyv5pT4hJAiEA8JP1/vvPrL8XfCvzZbHyabK1csTYmSLrmfbloAJ4H1E="}]},"_npmUser":{"name":"mfs-razan","email":"ritesh21633@gmail.com"},"directories":{},"maintainers":[{"name":"mfs-razan","email":"ritesh21633@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/probably-fair_1.0.0_1770150794401_0.8326547978498948"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-03T20:33:14.310Z","1.0.0":"2026-02-03T20:33:14.542Z","modified":"2026-02-03T20:33:14.763Z"},"maintainers":[{"name":"mfs-razan","email":"ritesh21633@gmail.com"}],"description":"Provably fair gaming module for casino platforms – server/client seeds, configurable nonce, verification","homepage":"https://github.com/huberco/provably-fair#readme","keywords":["provably-fair","casino","gaming","server-seed","client-seed","nonce","verification"],"repository":{"type":"git","url":"git+https://github.com/huberco/provably-fair.git"},"bugs":{"url":"https://github.com/huberco/provably-fair/issues"},"license":"MIT","readme":"# probably-fair\r\n\r\nProvably 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.\r\n\r\n**Important:** Never log or expose the server seed. Only its hash is shown before the round; the seed is revealed after settlement for verification.\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install probably-fair\r\n```\r\n\r\n## Algorithm (summary)\r\n\r\n1. **Commit:** Before the round, show `getServerSeedHash(serverSeed)` to the user.\r\n2. **Message:** HMAC-SHA256 uses server seed as key and `clientSeed:nonce[:A:B:...]` as message (optional extra params A, B, …).\r\n3. **Result:** The 32-byte HMAC is converted to float(s) in [0,1] and optionally scaled to a range (e.g. dice 1–6).\r\n4. **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.\r\n\r\n## API\r\n\r\n### Core (no network)\r\n\r\n- **`getServerSeedHash(serverSeed: string): string`**  \r\n  Returns SHA-256 hash of the server seed (pre-commitment).\r\n\r\n- **`getClientSeed(): string`**  \r\n  Returns the current client seed from the optional in-memory store.\r\n\r\n- **`setClientSeed(seed: string): void`**  \r\n  Sets the client seed in the optional in-memory store. You can also pass the client seed explicitly into other functions.\r\n\r\n- **`getNonce(options: NonceSource): number`**  \r\n  Returns the numeric nonce. Options:\r\n  - `{ type: 'custom', value: number }`\r\n  - `{ type: 'eos', blockHeight: number }`\r\n  - `{ type: 'bsc', blockHeight: number }`\r\n\r\n- **`generateRandomNumber(serverSeed, clientSeed, nonce, extraParams?, options?): number | number[]`**  \r\n  Deterministic random number(s).  \r\n  - `nonce`: `NonceSource` object or a number.  \r\n  - `extraParams`: optional `[A, B, ...]` (string or number) included in the HMAC message so the result is bound to these parameters.  \r\n  - `options`: optional `{ min, max, count, integer }` to scale and shape the output (defaults: one float in [0,1]).\r\n\r\n- **`verifyFairness(serverSeed, clientSeed, nonce, committedServerSeedHash, expectedResult, extraParams?, options?): VerifyResult`**  \r\n  Recomputes the result and checks that the server seed hash matches.  \r\n  Pass the same `extraParams` and `options` you used when generating the result.\r\n\r\n### Optional block fetchers (network)\r\n\r\nUse when the nonce is EOS or BSC block height and you want to fetch it from RPC:\r\n\r\n```js\r\nimport { getEosBlockHeight, getBscBlockHeight } from 'probably-fair/block-fetchers';\r\n\r\nconst eosBlock = await getEosBlockHeight(); // default RPC or pass URL\r\nconst bscBlock = await getBscBlockHeight();\r\n// Then: getNonce({ type: 'eos', blockHeight: eosBlock }) or type: 'bsc', blockHeight: bscBlock\r\n```\r\n\r\nYou can also obtain block height from your own backend and pass it into `getNonce` without using these fetchers.\r\n\r\n## Usage examples\r\n\r\n```js\r\nconst {\r\n  getServerSeedHash,\r\n  setClientSeed,\r\n  getNonce,\r\n  generateRandomNumber,\r\n  verifyFairness,\r\n} = require('probably-fair');\r\n\r\nconst serverSeed = 'my-secret-server-seed';\r\nconst clientSeed = 'user-client-seed';\r\nconst nonce = getNonce({ type: 'custom', value: 0 });\r\n\r\n// Before round: show only the hash\r\nconst committedHash = getServerSeedHash(serverSeed);\r\n\r\n// Generate result (e.g. dice 1–6)\r\nconst roll = generateRandomNumber(serverSeed, clientSeed, nonce, undefined, {\r\n  min: 1,\r\n  max: 6,\r\n  integer: true,\r\n});\r\n\r\n// With extra parameters [A, B, ...]\r\nconst custom = generateRandomNumber(serverSeed, clientSeed, nonce, [10, 20], {\r\n  min: 0,\r\n  max: 99,\r\n  integer: true,\r\n});\r\n\r\n// After round: verify\r\nconst verification = verifyFairness(\r\n  serverSeed,\r\n  clientSeed,\r\n  nonce,\r\n  committedHash,\r\n  roll\r\n);\r\nconsole.log(verification.isFair); // true\r\n```\r\n\r\n## Types\r\n\r\n- **`NonceSource`** – `{ type: 'custom', value } | { type: 'eos', blockHeight } | { type: 'bsc', blockHeight }`\r\n- **`VerifyResult`** – `{ resultMatches, serverSeedHashMatches, isFair, computedResult? }`\r\n- **`RandomNumberOptions`** – `{ min?, max?, count?, integer? }`\r\n\r\n## Tests\r\n\r\n```bash\r\nnpm test\r\n```\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md","_rev":"1-8903d7c7bf4da3eeed64ba36ad488883"}