stake-provably-fair 中文说明

这是一个 Node.js provably fair RNG npm 库，提供可验证随机数核心能力和 Dice 应用层 helper。

安装

npm install stake-provably-fair

要求 Node.js 18 或更新版本。

入口

完整入口：

import {
  generateServerSeed,
  hashServerSeed,
  verifyServerSeed,
  generateClientSeed,
  generateFloats,
  generateDiceRoll,
  simulateDice,
} from 'stake-provably-fair';

分层入口：

import { generateFloats } from 'stake-provably-fair/core';
import { generateDiceRoll } from 'stake-provably-fair/dice';

CommonJS 也支持：

const { generateFloats } = require('stake-provably-fair/core');
const { generateDiceRoll } = require('stake-provably-fair/dice');

包内置 TypeScript 类型，根入口和子路径入口都有 .d.ts 声明。

解决的问题

在线博彩的核心信任问题是：玩家如何确认结果不是平台在下注后篡改的？

Provably fair 的思路是把结果生成拆成两部分：

公平结果 = 平台输入（下注前公开 hash 承诺） + 玩家输入

在本项目中：

• 平台输入是 serverSeed。
• 玩家输入是 clientSeed。
• 每次下注递增 nonce。
• 多结果游戏通过 cursor 从确定性字节流中继续取值。
• 下注前公开 hashServerSeed(serverSeed)，平台不能在之后无痕替换 seed。
• seed 轮换/reveal 后，玩家用 verifyServerSeed(serverSeed, committedHash) 验证公开 hash 是否匹配原始 seed。

这不是"预测未来结果"的系统，而是"下注后可复算、可审计"的系统。

模块设计

stake-provably-fair/core
  ├─ generateServerSeed()
  ├─ hashServerSeed()
  ├─ verifyServerSeed()
  ├─ generateClientSeed()
  ├─ byteGenerator(...)
  ├─ generateFloats(...)
  ├─ floatToIndex(...)
  ├─ pickOutcome(...)
  └─ pickOutcomes(...)

stake-provably-fair/dice
  ├─ diceRollFromFloat(...)
  ├─ generateDiceRoll(...)
  ├─ isDiceWin(...)
  ├─ getDiceWinProbability(...)
  └─ simulateDice(...)

核心原则：

• RNG 核心不依赖具体游戏规则。
• 所有随机结果都由 HMAC-SHA256 确定性生成。
• 相同的 serverSeed + clientSeed + nonce + cursor 永远生成相同结果。
• 应用层只负责把通用 float 映射成具体事件，例如 Dice roll。

随机字节生成

核心字节流使用：

HMAC_SHA256(serverSeed, `${clientSeed}:${nonce}:${round}`)

每个 HMAC round 输出 32 bytes。cursor 用于指定从字节流的哪个位置开始读取：

• round = Math.floor(cursor / 32)
• roundCursor = cursor % 32

Dice 示例

Dice 使用 00.00 到 100.00 的范围，共 10,001 个可能结果。

import {
  generateServerSeed,
  hashServerSeed,
  verifyServerSeed,
  generateClientSeed,
} from 'stake-provably-fair/core';
import { generateDiceRoll, isDiceWin } from 'stake-provably-fair/dice';

const serverSeed = generateServerSeed();
const committedHash = hashServerSeed(serverSeed);
const clientSeed = generateClientSeed();

const roll = generateDiceRoll({
  serverSeed,
  clientSeed,
  nonce: 0,
});

const win = isDiceWin(roll, {
  target: 50,
  condition: 'under',
});

console.log({ committedHash, roll, win });
console.log(verifyServerSeed(serverSeed, committedHash));

100 万次模拟

运行：

npm run simulate:dice

可通过环境变量覆盖：

BETS=1000000 TARGET=50 CONDITION=under npm run simulate:dice

输出包含 wins、losses、winRate、theoreticalWinRate、difference、expectedWins、standardDeviation、zScore、minRoll、maxRoll。

这个模拟只能说明分布没有明显异常，不能替代逐笔 seed reveal 后的可验证复算。

边界

当前包只实现 RNG 核心和 Dice helper，不处理 HTTP API、数据库、用户账户、seed 会话持久化、余额、下注金额、赔率、house edge 或合规问题。

测试

npm test
npm run pack:dry-run