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.
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.
- 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.
- 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.
- 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.
- 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.
- Keep a record of every drawclient_seed, nonce, draw, weights, ranges or threshold, roll and result, stored together with the record ID.
- 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.
- 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
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
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)
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)
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)”.
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 type | Method | How it works |
|---|---|---|
| Oripa | Pick | Draws cards by the published probabilities. |
| Ichiban Kuji | Pick | Weighted by the tickets left in each tier, updated after every draw. |
| Gacha | Pick | Draws characters or cards by rarity probabilities. |
| Blind Box | Pick | Design probabilities decide which one you get. |
| Gashapon | Pick | Each capsule is drawn by design probabilities. |
| Lucky Bag | Pick | Tier probabilities decide what’s in the bag. |
| Mystery Box | Pick | Draws the contents from a published prize table. |
| Pack Opening | Pick | Each 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 Break | Pick | Assigns teams or slots at random. The next draw’s weights and labels leave out what has already been drawn. |
| Raffle | Pick | Every entrant has equal weight. Winners get the right to buy. When drawing several winners, leave out those already drawn. |
| Lucky Draw | Pick | Event prizes are drawn by quota and weight. |
| Card Upgrade | Threshold | Succeeds when the Roll is below the Threshold in the platform’s record; the platform sets and publishes the success rate. |
| Enhancement | Threshold | A 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.
Verify Link v1 (optional)
This section is optional. You only need it if you want players to open the verifier with the data already filled in. If you just show the data on each record and let players enter it, skip this section.
A link is the verifier URL, a # and the parameters. URL-encode every value. The verifier ignores parameters it doesn’t recognize.
The Platform Margin, Probability, prize table and market prices all go into the link as set for that draw product and that draw; the verifier has no defaults. When a setting changes (say the Platform Margin goes from 5% to 8%), later links simply carry the new numbers, and the verifier needs no update.
Required
- v
- Format version, currently 1.
- server_seed_hash
- SHA-256(server_seed) published before the draw, in hex.
- client_seed
- The player’s Client Seed.
- nonce
- Decimal integer.
Required after seed rotation
- server_seed
- The revealed Server Seed as plain text. Leave it out while the seed is in use. The verifier will ask the player to rotate seeds and verify then.
Platform record
- result
- The platform’s recorded result. Threshold: 1 (success) or 0 (fail). Pick: the prize index, from 0. Without result, the verifier only shows the recalculated result, never “Passed”.
- roll
- Optional: the platform’s recorded Roll.
- draw
- Optional: the draw’s index within the Nonce, from 0. Defaults to 0.
Pick method
- game=pick
- If game is omitted, weights means Pick.
- weights
- Pick needs either weights or ranges. weights are the whole-number weights of each prize, comma-separated, up to 1,000 items.
- ranges
- Probability ranges replace weights: write each range as begin-end, separated by commas, with up to 6 decimal places. Ranges must not overlap. Set game to range.
- labels
- Optional: prize names separated by |, in the same order as weights or ranges.
Threshold method
- game=threshold
- Pass or fail.
- threshold
- The upper bound of the success zone, a whole number from 0 to 4,294,967,296; the draw succeeds when the Roll is below threshold. Without threshold, the verifier calculates it from the three market-price parameters below.
- input_value
target_market_price
edge_rate - Card Upgrade: the input cards’ total market price, the target card’s market price and the Platform Margin, sent together. Market prices require edge_rate (write 0 for no margin). If any one is missing, the verifier refuses to verify; it never assumes 0 or any other value. edge_rate must be a decimal from 0 up to (but not including) 1, e.g. 0.05; otherwise it is also refused. input_value and target_market_price are decimal strings with digits and at most one decimal point (e.g. 41.80): no commas, signs or scientific notation, and target_market_price must be above 0. When threshold is also included, the verifier checks that the two agree.
- currency
- Optional: the amount unit, set by the platform and shown as is next to the market prices.
- inputs
target - Input card names (one per card, separated by |) and the target card name, shown on the result.
Display
- game_type
- Draw type, such as Oripa, Ichiban Kuji, Gashapon or Card Upgrade, shown above the result.
- platform
order_id - The platform name and record ID, shown as text above the result.
- chain_url
- On-chain record URL. https only.
- input_ids
target_id - Card IDs, in the same order as inputs.
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 })}`;
}# JACKZ.AI Fair Verify v1: Python 3.8+, standard library only
import hashlib
import hmac
import re
from fractions import Fraction
from math import floor
from urllib.parse import urlencode
SPACE = 2 ** 32
def seed_hash(server_seed: str) -> str:
"""Published before the draw: SHA-256(Server Seed), lowercase hex"""
return hashlib.sha256(server_seed.encode()).hexdigest()
def roll(server_seed: str, client_seed: str, nonce: int, draw: int = 0) -> int:
"""Roll for the given draw: 0 to 4,294,967,295"""
message = f"{client_seed}:{nonce}:{draw // 8}".encode()
block = hmac.new(server_seed.encode(), message, hashlib.sha256).digest()
offset = (draw % 8) * 4
return int.from_bytes(block[offset:offset + 4], "big")
def is_success(r: int, threshold: int) -> bool:
"""Threshold: success when Roll is below threshold"""
return r < threshold
def upgrade_threshold(input_value: str, target_price: str, edge_rate: str) -> int:
"""Card Upgrade threshold. Amounts are decimal strings to avoid floating-point error"""
if not re.fullmatch(r"0(\.\d+)?", edge_rate or ""):
raise ValueError("edge_rate is required: a decimal from 0 up to (but not including) 1; use 0 for no margin")
if not all(re.fullmatch(r"\d+(\.\d+)?", s or "") for s in (input_value, target_price)):
raise ValueError("Market prices must be decimal numbers")
return floor(Fraction(input_value) * (1 - Fraction(edge_rate)) * SPACE / Fraction(target_price))
def pick(r: int, weights: list) -> int:
"""Pick: weights holds each prize’s integer weight (Ichiban Kuji: tickets left per tier). Returns the prize index"""
ticket = r * sum(weights) // SPACE
cum = 0
for i, w in enumerate(weights):
cum += w
if ticket < cum:
return i
raise ValueError("weights must sum to more than 0")
def verify_link(base: str, **params) -> str:
"""One-click verify link (Link Format v1)"""
return base + "#" + urlencode({"v": 1, **params})<?php
// JACKZ.AI Fair Verify v1: PHP 8.5.12+ (64-bit); Card Upgrade needs the bcmath extension
const FV_SPACE = 4294967296; // 2^32
// Published before the draw: SHA-256(Server Seed), lowercase hex
function fv_seed_hash(string $serverSeed): string
{
return hash('sha256', $serverSeed);
}
// Roll for draw $draw: 0 to 4,294,967,295
function fv_roll(string $serverSeed, string $clientSeed, int $nonce, int $draw = 0): int
{
$block = hash_hmac('sha256', $clientSeed . ':' . $nonce . ':' . intdiv($draw, 8), $serverSeed, true);
return unpack('N', substr($block, ($draw % 8) * 4, 4))[1];
}
// Threshold: success when Roll is below threshold
function fv_is_success(int $roll, int $threshold): bool
{
return $roll < $threshold;
}
// Card Upgrade threshold; amounts as decimal strings, needs bcmath. edge_rate is required, 0 to below 1; for no margin pass '0'
// Keep the three amounts to 18 decimal places in total so the product stays exact
function fv_upgrade_threshold(string $inputValue, string $targetPrice, string $edgeRate): string
{
if (!preg_match('/^0(\.\d+)?$/', $edgeRate)) throw new InvalidArgumentException('edge_rate is required: a decimal from 0 up to (but not including) 1; use 0 for no margin');
foreach ([$inputValue, $targetPrice] as $s) if (!preg_match('/^\d+(\.\d+)?$/', $s)) throw new InvalidArgumentException('Market prices must be decimal numbers');
$n = bcmul(bcmul($inputValue, bcsub('1', $edgeRate, 18), 18), '4294967296', 18);
return bcdiv($n, $targetPrice, 0); // scale 0 rounds down (amounts are positive)
}
// Pick: $weights holds each prize’s integer weight (Ichiban Kuji: tickets left per tier). Returns the prize index
// Keep the weight sum below 2^31, otherwise $roll * sum overflows a 64-bit integer. Use GMP or bcmath instead
function fv_pick(int $roll, array $weights): int
{
$ticket = intdiv($roll * array_sum($weights), FV_SPACE);
$cum = 0;
foreach (array_values($weights) as $i => $w) {
$cum += $w;
if ($ticket < $cum) {
return $i;
}
}
throw new InvalidArgumentException('weights must sum to more than 0');
}
// One-click verify link (Link Format v1)
function fv_verify_link(string $base, array $params): string
{
return $base . '#' . http_build_query(['v' => 1] + $params);
}Test vectors
Before integrating, check your implementation against these numbers. The verifier can recalculate every one of them.
Roll
| nonce | draw | roll |
|---|---|---|
| 1 | 0 | 2079044362 |
| 5 | 0 | 441912824 |
| 1 | 8 | 4185532748 |
| 1 | 9 | 2271708478 |
Threshold
| input_value | target_market_price | edge_rate | threshold |
|---|---|---|---|
| 40 | 100 | 0.05 | 1632087572 |
| 30.00 | 100.00 | 0.05 | 1224065679 |
| 50 | 95 | 0.05 | 2147483648 |
| 40 | 100 | 0.08 | 1580547964 |
| 41.80 | 108.50 | 0 | 1654650995 |
| 40 | 100 | (missing) | refused |
| 40 | 100 | 1 | refused |
Pick
| roll | weights | result |
|---|---|---|
| 441912824 | 1,4,20,75 | 2 |
| 2079044362 | 1,4,20,75 | 3 |
Pick (probability ranges)
| roll | f (6 places) | ranges | result |
|---|---|---|---|
| 1163190975 | 0.270827 | 0.000000-0.270826, 0.270827-1.000000 | 1 |
| 1163190975 | 0.270827 | 0.000000-0.270827, 0.270828-1.000000 | 0 |
| 2166811 | 0.000505 | 0.000000-0.000504, 0.000505-1.000000 | 1 |
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.