Onchain

Odds and randomness

Read the odds from the contracts and check any opening yourself.

Every mystery box rolls its prize from one random number for its opening, mixed with the box's own id, against an odds table stored in the contract. The table a box is sold under is locked into it when it is bought. The number arrives only after the open. All of it can be read onchain and replayed. For the prizes and chances in plain words, see Odds and prizes.

Read the odds

The quick way: GET https://www.giftedstock.com/api/agent/v1/boxes answers each box's odds as it sells today. From the contract itself, on any of the four boxes (addresses on Contracts and addresses):

ReadWhat it gives
params().currentConfigIdThe odds table new boxes are sold under.
cardOf(id).configIdThe table one box was sold under. It never changes.
configOf(configId)The table: scaleBps, jackpotOneIn, jackpotUsd, consolationUsd, prizes[] and cumOdds[].
  • cumOdds are cumulative, out of 10,000: tier t wins when the roll is below cumOdds[t] and not below the tier before. The last is 10,000.
  • prizes, jackpotUsd and consolationUsd are dollars with 6 decimals before scale. A box pays each times scaleBps / 10,000.
  • jackpotOneIn is the bonus pot line's odds: one roll in that many. 0 means none.
  • A table is never edited once a box points at it. New odds are a new table for boxes bought from then on.

How an opening is drawn

  1. Step 1: Open

    open(ids) takes up to 200 sealed boxes as one batch. Its OpenRequested log names the batch id, the owner and the box ids in order; the batch stores a hash of that order.

  2. Step 2: The number (Base)

    Pyth Entropy's contract sends the number in a callback seconds after the open. The box stores it on the batch and logs Revealed(batchId, randomness).

  3. Step 3: The number (Robinhood Chain)

    The open fixes the batch's drand round: the first round of drand's evmnet network published at least 4 seconds after the open, unknown to anyone then. The reveal proves the round's signature through our beacon contract, which checks it against drand's public key. The batch's number is keccak256(abi.encode(drandRandomness, box, batchId)), where drandRandomness is sha256 of the signature, logged as Revealed(batchId, round, randomness).

  4. Step 4: Each box's roll

    r = keccak256(abi.encodePacked(batchRandomness, boxId)).

  5. Step 5: The bonus pot line

    If jackpotOneIn is not 0 and (r >> 200) % jackpotOneIn is 0, the box wins the bonus pot prize when the pot covers it, both now and as it stood at the open; otherwise the smaller consolation prize.

  6. Step 6: The ladder

    Otherwise roll = r % 10,000. The prize is the first tier whose cumOdds is above the roll, times scaleBps / 10,000.

  7. Step 7: The stock

    seed = r >> 128 picks one stock by weight among vaults that can pay the prize at the settle. It depends on the vaults' balances and prices at that block, so replay it at that block.

The settle writes each box's result: Opened(tokenId, stockId, prize, units, jackpot) and cardOf(id).

Why nobody can steer it

  • The number arrives after the open, so the buyer, the opener and we cannot know it when the boxes are opened.
  • The odds are fixed in the box when it is bought.
  • The settle must name the batch's ids in the order they were opened, checked against the stored hash.
  • We can settle a batch at any time. The batch's owner may settle once an hour has passed since the open. Nobody else may: the number is public after the reveal and the settle moment decides which vaults can pay.
  • On Base a batch whose number came can never go back to sealed: that would be a re-roll.

Check an opening yourself

Find the batch: the open transaction's OpenRequested log has the batch id. The Revealed log for that id has its number. Then replay a box's prize:

import { createPublicClient, http, keccak256, encodePacked, parseAbi } from "viem";
import { base } from "viem/chains"; // or robinhood

const BOX = "0x…";        // the box contract
const ID = 2385n;          // the box
const RANDOMNESS = "0x…";  // the batch's number, from Revealed

const pub = createPublicClient({ chain: base, transport: http() });
const abi = parseAbi([
  "function cardOf(uint256) view returns ((uint8 status, uint8 stockId, uint16 configId, uint64 prize, uint96 units, uint32 mintedAt, uint32 openedAt))",
  "function configOf(uint16) view returns (uint32 scaleBps, uint32 jackpotOneIn, uint64 jackpotUsd, uint64 consolationUsd, uint64[] prizes, uint16[] cumOdds)",
]);

const card = await pub.readContract({ address: BOX, abi, functionName: "cardOf", args: [ID] });
const [scaleBps, jackpotOneIn, , , prizes, cumOdds] =
  await pub.readContract({ address: BOX, abi, functionName: "configOf", args: [card.configId] });

const r = BigInt(keccak256(encodePacked(["bytes32", "uint256"], [RANDOMNESS, ID])));
if (jackpotOneIn !== 0 && (r >> 200n) % BigInt(jackpotOneIn) === 0n) {
  console.log("the bonus pot line: the bonus pot prize, or the consolation if the pot was short");
} else {
  const roll = r % 10_000n;
  const tier = cumOdds.findIndex((c) => roll < BigInt(c));
  const prize = (prizes[tier] * BigInt(scaleBps)) / 10_000n;
  console.log({ roll, prize, paid: card.prize }); // dollars with 6 decimals: the two match
}

On Robinhood Chain, check the batch's number came from drand too:

import { encodeAbiParameters, parseAbiParameters, sha256 } from "viem";

// the batch's round: batchOf(batchId).round, or the Revealed log
const { signature } = await (await fetch(`https://api.drand.sh/v2/beacons/evmnet/rounds/${round}`)).json();
const drandRandomness = sha256(`0x${signature}`);
const randomness = keccak256(encodeAbiParameters(parseAbiParameters("bytes32, address, uint256"), [drandRandomness, BOX, batchId]));
// randomness equals the Revealed log's number
Our beacon contract answers verify(round, signature) for any round. randomness(round) answers once a round is proven. Its address is params().beacon on either Robinhood Chain box.