@gibs/random

中文文档
0.0.19发布于 2026/07/24AGPL-3.0-only近 30 天下载 2348

a repo for generating randomness on chain

原始使用文档
文档目录3 节
  1. deployment notes
  2. ZK cards contracts
  3. randomness providing

Random Coverage Status

a repo for generating randomness on chain

deployment notes

npx hardhat ignition deploy ignition/modules/Random.ts --network pulsechainV4
npx hardhat ignition deploy ignition/modules/Reader.ts --network pulsechainV4
npx hardhat ignition deploy ignition/modules/Consumer.ts --network pulsechainV4
npx hardhat ignition verify chain-943 --include-unrelated-contracts

ZK cards contracts

A game-agnostic two-party state-channel card table plus the first game's rules and the SNARK verifiers that adjudicate disputes. Deployed together via ignition/modules/ZkCards.ts.

  • ZkTable — escrow + the channel/dispute machine. It is game-agnostic: it verifies EIP-712 co-signed ChannelStates and delegates transition legality to a per-table IGameRules contract chosen at create (the joiner accepts those rules by joining — no owner, no registry governance). The honest path is three transactions (create, join, settle) and never pays proof-verification gas.
  • IGameRules — the rules seam. ZkTable consults one of these per table for hashGameState / whoseTurn / isFinal / applyMove.
  • HiLoWarRules (game id 1) — a pure mirror of @gibs/hilo-war's applyMove, consulted only by the dispute machine. The TS module is normative; HiLoWarParity fuzzes the two against each other.
  • Vendored uzkge verifiers (contracts/vendor/uzkge/, pinned commit 2ae729db) + the calldata-shaped ShuffleVerifier52 wrapper. The pin is a consensus constant — prover wasm and these verifiers must come from the same commit; see contracts/vendor/VENDOR.md for the pin, the GPL-3.0 license posture, and the pre-mainnet blockers.

Disputes are answered by a higher-nonce co-signed state, by the demanded game move (validated by the rules contract), or by the demanded reveal share — the latter is Groth16 snark-reveal only (RevealVerifier); the CP-DL on-chain path is banned at 15.6M gas. Clock expiry forfeits the disputed pot to the disputant and settles balances from the contested co-signed state. The chess clock is creator-set per table (clockBlocks, bounds 30–60480, ~5 min to ~1 week; suggested client default 360 ≈ 1 hour); no dispute bond in v1.

The EIP-712 domain is ("ZkTable", "1", chainId, zkTableAddress), consumed off-chain via makeDomain in @gibs/zk-cards-core. Channel-state and game-state hashes are abi-encoded (not JSON) so the contract can reproduce them — the canonical tuples are mirrored in the TS packages and enforced by parity tests.

randomness providing

Providing randomness, at the end of the day, is a numbers game (excuse the pun).

You need to be able to ensure that validators have a reason to stay online and keep their stack of preimages up to date, but you want it to happen at as little of a cost and complexity as possible so that providers do not have a high barrier to cross to get you the randomness you request.

This game is achieved using the following mechanics:

  • providers stake a number of tokens that they expect to be paid (on average) for providing their seeds this occurs when preimages are written
  • consumers stake an amount to cover the total randomness seeds requested. the prices can be different for each provider's preimages
  • any provider that gets their secret on chain, either via the consumer or by writing it themselves, before the consumer asks for the campaign to end will not be slashed
  • consumers can "slash" any validator by taking the preimages that they requested and were not delivered
  • failing to get all secrets on chain means that providers will not be rewarded with the funds that the consumer staked
  • providers must either put secrets on chain themselves or come up with mechanism to do so in batches if gas is a consideration
  • consumers must request a number of seeds that make the number that is generated credibly neutral, luckily, only one actor must be honest for the seed to be credibly random

consider the following example

alice requests randomness from bob, charlie, and david. bob's preimage costs 90 PLS while charlie's costs 125 and david's costs 100. Alice will have to stake 315 PLS (90+125+100) to properly request randomness inputs from the 3 sources. From here, the following results could occur:

  • all 3 providers expose their secrets to the public and alice, who writes the data on chain, distributes the pot to david who was randomly chosen by the resulting seed.
  • all 3 providers expose their secrets to the public, however alice has faulted and does not write the secrets on chain quickly. at some point, david notes that he is the winner of the pot and notes that the timeline is expiring. he decides to write the randomness on chain, distributing tokens to each of the validators and the pot to himself.
  • all 3 providers expose their secrets, alice faults, then all 3 of the providers fault. in this case, any address that has the appropriate data and secrets can submit them on chain. bob is the first to come back online and he decides to submit all 3 secrets. releasing each of the 3 providers staked tokens back to themselves and distributing the pot to david.
  • providers expose, alice and providers fault. bob comes online and only knows his secret. he submits that secret to make sure that he is not slashed. alice comes online next and has all 3 secrets, but chooses to cancel the timeline because it has expired. she is reimbersed with her stake as well as charlie and david's staked tokens.

版本与发布记录

@gibs/random 共发布 17 个版本,首次发布于 2024/08/27;过去 12 个月发布了 1 个版本。

版本发布日期距今
0.0.19latest2026/07/243 个月前
0.0.182025/02/181.7 年前
0.0.172025/02/181.7 年前
0.0.162024/09/192 年前
0.0.152024/09/112 年前
0.0.142024/09/042 年前

关于 @gibs/random 的常见问题

@gibs/random 是什么?

a repo for generating randomness on chain

如何安装 @gibs/random?

在项目目录运行 npm install @gibs/random,或使用 pnpm add / yarn add / bun add。

@gibs/random 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gibs__random 是否存在。

@gibs/random 可以商用吗?

@gibs/random 使用 AGPL-3.0-only 许可。最严格的 Copyleft:除分发外,通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括,不构成法律意见,请以许可原文为准。

@gibs/random 的下载量有多少?

根据 npm 官方下载统计,@gibs/random 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,348 次,日均约 78 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gibs/random 还在维护吗?

最新版本 0.0.19 发布于 2026/07/24(3 个月前);至今共发布 17 个版本,其中过去 12 个月发布了 1 个;首次发布于 2024/08/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。