Integration DocsSpec v1

Bring Provably Fair
to your platform.

Works for thirteen draw types, including Oripa, Ichiban Kuji, Gacha, Blind Box and Card Upgrade. The platform shows the Server Seed, Client Seed, Nonce and Probability on every record; players paste them into the verifier and check each draw themselves.

Overview

JACKZ.AI Fair Verify is an independent verification page. The platform publishes the data each draw needs, players paste it into the verifier, and the page recalculates that draw in the browser and shows the result. Because players enter the data and press Verify themselves, they check the result with their own hands.

Platforms need no SDK and no API. Every calculation runs in the player’s browser, and no data is sent to a server. To save players typing, you can add a one-click link (see “Verify Link v1”), but it isn’t required.

CommitPublish the Server Seed Hash before the draw
RollRecord the Client Seed, Nonce and result of every draw
RevealReveal the old Server Seed at rotation
VerifyPlayers paste the data into the verifier

Terms

The docs and the verifier both use the English terms below.

Server Seed
A random string generated by the platform. We recommend 32 bytes from a cryptographic RNG, in hex. Keep it secret until rotation.
Server Seed Hash
The lowercase hex string of SHA-256(Server Seed), published before the draw.
Client Seed
The player’s seed, set by the player or generated at random by the platform. Case-sensitive.
Nonce
The draw counter under one set of seeds. A decimal integer that goes up by one with each draw.
Draw
The draw’s index within one Nonce, starting from 0. A 10-pull can share one Nonce and use Draw 0 to 9.
Roll
A 32-bit unsigned integer calculated from the data above, from 0 to 4,294,967,295.
Probability (weights)
The integer weight of each prize in the Pick method. Ichiban Kuji uses the tickets left in each tier at the moment of the draw.
Threshold
The success zone upper bound in the Threshold method. A Roll below it succeeds.
Seed Rotation
Rotating seeds: reveal the old Server Seed and publish the Hash of the new one at the same time. Later draws use the new seed.
Platform Margin
The platform margin, set per draw product and adjustable at any time. Written as a decimal: 8% is 0.08, no margin is 0. Card Upgrade uses it to calculate the success rate. It is only passed to the verifier in the optional verification link; players never enter it.

Integration steps

Complete all seven steps so players can check every draw on their own.

  1. Publish the Server Seed Hash before the drawGenerate a Server Seed and show its Hash before the player draws. If possible, also write it on-chain or to a timestamped record so it can’t be changed later.
  2. Let players set the Client SeedIt can be random by default, but players must be able to change it. When a player changes the Client Seed, we recommend switching to a new Server Seed too.
  3. Use the next Nonce for every drawIncrease the Nonce by one per draw. No reuse, no skipped numbers, and no redraws based on the result. Every Nonce needs a record.
  4. Publish the probabilities before the drawFor Pick, publish each prize’s weight, or for Ichiban Kuji the tickets left per tier. For Threshold, publish the success rate or how it’s calculated.
  5. Keep a record of every drawclient_seed, nonce, draw, weights, ranges or threshold, roll and result, stored together with the record ID.
  6. Reveal the old seed at Seed RotationWhen the player rotates seeds or the seed expires, reveal the old Server Seed and start using the new one.
  7. Show the verification data on each recordEvery record shows the Server Seed Hash, the Server Seed (after rotation), Client Seed, Nonce, Draw and the draw’s Probability or success rate, ideally each with a copy button. Next to them, add a plain link to the verifier; it doesn’t need to carry any data.

Algorithm

Every method first calculates a Roll, then turns it into a result. All math uses integers, never floating point.

Roll

Roll derivationHMAC-SHA256
block = HMAC-SHA256(key = server_seed, message = "{client_seed}:{nonce}:{floor(draw / 8)}")
roll  = block[4 × (draw mod 8) .. +4] read as a big-endian unsigned 32-bit integer
Live · server_seed = test vectorEdit the numbers to recalculate live
message block roll
  • Use server_seed directly as a UTF-8 text key. Don’t decode it from hex into bytes first.
  • Colons are ASCII. Write nonce and floor(draw / 8) in decimal with no zero padding.
  • Each HMAC block has 32 bytes, enough for 8 Draws. Draws 8 to 15 use the second block, and so on.

Threshold: pass or fail (Card Upgrade)

Threshold modeCard Upgrade
success   = roll < threshold
chance    = threshold ÷ 4,294,967,296
threshold = floor(input_value × (1 − edge_rate) × 2^32 ÷ target_market_price)
  • Market prices are decimal strings, calculated as exact fractions and rounded down only once at the end. The cards put in and the target card must use the same currency.
  • A threshold of 4,294,967,296 or more always succeeds.
  • If the platform uses a different upgrade formula, publish only threshold; the market-price parameters are only for the optional verification link.
  • For draw types that publish a success rate directly (such as Enhancement), threshold = floor(rate × 2^32), also using exact fractions. For example, a rate of 0.35 gives a threshold of 1,503,238,553.

Pick: pick a prize (Oripa, Ichiban Kuji, Gacha, Blind Box)

Pick modeWeighted
W      = sum of all weights
ticket = floor(roll × W ÷ 4,294,967,296)
result = index of the first prize whose cumulative weight, summed from item 0, exceeds ticket

Pick (probability ranges)

Use this form if your prize table expresses probabilities as decimal ranges. On the verifier, choose “Prize draw (by probability ranges)”.

Pick modeRanges
f      = round(roll ÷ 4,294,967,296, 12), then round(f, 6)
result = index of the first range with begin ≤ f ≤ end (from 0; begin and end both included)
  • Both roundings are half-up: if the 13th digit is 5 or more, round up; the same at 6 places.
  • Ranges are decimals with up to 6 places, e.g. 0.000000-0.000999,0.001000-0.019999.
  • If the platform computes with floating point, the rare Rolls that land exactly on a 5 at the 12th place can be off by one digit; integer or decimal arithmetic avoids this.

Draw types and methods

Draw typeMethodHow it works
OripaPickDraws cards by the published probabilities.
Ichiban KujiPickWeighted by the tickets left in each tier, updated after every draw.
GachaPickDraws characters or cards by rarity probabilities.
Blind BoxPickDesign probabilities decide which one you get.
GashaponPickEach capsule is drawn by design probabilities.
Lucky BagPickTier probabilities decide what’s in the bag.
Mystery BoxPickDraws the contents from a published prize table.
Pack OpeningPickEach card slot uses one Draw and is drawn by rarity Probability (weights or probability ranges). For tiered packs, publish one set of weights, labels and Draw per tier, all with the same Nonce, numbering Draws consecutively in “slot → tier” order (e.g. 5 slots with 2 tiers each use Draw 0 to 9). The first tier’s weights are the rarity weights; the next tier’s weights and labels are the cards inside the rarity drawn above.
Box BreakPickAssigns teams or slots at random. The next draw’s weights and labels leave out what has already been drawn.
RafflePickEvery entrant has equal weight. Winners get the right to buy. When drawing several winners, leave out those already drawn.
Lucky DrawPickEvent prizes are drawn by quota and weight.
Card UpgradeThresholdSucceeds when the Roll is below the Threshold in the platform’s record; the platform sets and publishes the success rate.
EnhancementThresholdA published success rate decides whether the enhancement succeeds.
  • roll × W can exceed 2^53, so JavaScript needs BigInt.
  • The number of Rolls mapped to each ticket differs by at most 1. With W up to 1,000,000, each prize’s relative probability error is under 0.03%.
  • In Ichiban Kuji, the weights change to the new remaining counts after every ticket; the record must publish the weights at the time that ticket was drawn.

Code samples

All three versions use the same algorithm with built-in language functions only, and have been checked against the test vectors below. The PHP Card Upgrade threshold uses the bcmath extension.

// JACKZ.AI Fair Verify v1: Node.js 18+, built-in modules only
import { createHash, createHmac } from "node:crypto";

const SPACE = 2n ** 32n;

// Published before the draw: SHA-256(Server Seed), lowercase hex
export function seedHash(serverSeed) {
  return createHash("sha256").update(serverSeed, "utf8").digest("hex");
}

// Roll for the given draw: 0 to 4,294,967,295
export function roll(serverSeed, clientSeed, nonce, draw = 0) {
  const block = createHmac("sha256", serverSeed)
    .update(`${clientSeed}:${nonce}:${Math.floor(draw / 8)}`)
    .digest();
  return BigInt(block.readUInt32BE((draw % 8) * 4));
}

// Threshold: success when Roll is below threshold
export function isSuccess(r, threshold) {
  return r < BigInt(threshold);
}

// Card Upgrade threshold. Amounts are decimal strings to avoid floating-point error
export function upgradeThreshold(inputValue, targetPrice, edgeRate) {
  if (!/^0(\.\d+)?$/.test(edgeRate ?? "")) throw new Error("edge_rate is required: a decimal from 0 up to (but not including) 1; use 0 for no margin");
  if (![inputValue, targetPrice].every((s) => /^\d+(\.\d+)?$/.test(s ?? ""))) throw new Error("Market prices must be decimal numbers");
  const frac = (s) => {
    const [i, f = ""] = String(s).split(".");
    return [BigInt(i + f), 10n ** BigInt(f.length)];
  };
  const [a, ad] = frac(inputValue), [t, td] = frac(targetPrice), [e, ed] = frac(edgeRate);
  return (a * (ed - e) * SPACE * td) / (ad * ed * t);
}

// Pick: weights holds each prize’s integer weight (Ichiban Kuji: tickets left per tier). Returns the prize index
export function pick(r, weights) {
  const w = weights.map(BigInt);
  const ticket = (r * w.reduce((x, y) => x + y, 0n)) / SPACE;
  let cum = 0n;
  for (let i = 0; i < w.length; i++) {
    cum += w[i];
    if (ticket < cum) return i;
  }
  throw new Error("weights must sum to more than 0");
}

// One-click verify link (Link Format v1)
export function verifyLink(base, params) {
  return `${base}#${new URLSearchParams({ v: "1", ...params })}`;
}

Test vectors

Before integrating, check your implementation against these numbers. The verifier can recalculate every one of them.

server_seedd790b1978d538dea96a16942291c4efa2d5e631ca48db984c1f2e9e7b738b434
server_seed_hashcae64244e12924e26d2eb5e9dd90820650d6cb377944a13eee82c2df31d56f93
client_seedMySeed2026

Roll

noncedrawroll
102079044362
50441912824
184185532748
192271708478

Threshold

input_valuetarget_market_priceedge_ratethreshold
401000.051632087572
30.00100.000.051224065679
50950.052147483648
401000.081580547964
41.80108.5001654650995
40100(missing)refused
401001refused

Pick

rollweightsresult
4419128241,4,20,752
20790443621,4,20,753

Pick (probability ranges)

rollf (6 places)rangesresult
11631909750.2708270.000000-0.270826, 0.270827-1.0000001
11631909750.2708270.000000-0.270827, 0.270828-1.0000000
21668110.0005050.000000-0.000504, 0.000505-1.0000001

Scope

The verifier checks one thing: that the result came from the committed seeds. Below is what it proves and what it can’t prove alone. Describe it accurately when you explain it publicly.

What verification proves

  • This draw was calculated from the entered Server Seed, the player’s Client Seed and the Nonce, and that Server Seed matches the entered Server Seed Hash.
  • The platform’s recorded Roll and result match the recalculation.
  • When market prices are included, the Card Upgrade success rate matches the one calculated from market prices and Platform Margin.

Needs separate checks

  • Whether the Probability match what was published before the draw: the platform supplies the weights, so players compare them with the Probability they saw beforehand.
  • Skipped nonces or re-rolls: recalculate a run of nonces with Batch Verify, then compare them one by one with the platform’s draw history.
  • Whether the entered Server Seed Hash is the one the player saw before the draw.
  • Whether the market prices themselves are accurate: the platform supplies the prices and the Platform Margin, and the verifier only checks the success rate calculated from those numbers.
  • Whether Ichiban Kuji remaining counts are real, and whether prizes were delivered.

Versions

v in the link is the format version. The current version is 1.

2026-10-24 · v1The Pick (weights and probability ranges) and Threshold methods, verification by the player’s own input, Batch Verify, and the optional one-click verification link.