@xgamesfun/solana 0.0.0-stage → 0.24.0

package/js/client/pda.js

@@ -0,0 +1,114 @@
+// Every address the loot program derives, with the seeds the program uses. Each takes base58
+// addresses and numbers and returns a base58 address. Browser-safe.
+import { addressBytes } from '../chain/base58.js';
+import { intLE, utf8, uintLE } from '../chain/bytes.js';
+import { associatedTokenAddress, findProgramAddress, MPL_CORE_PROGRAM, TOKEN_PROGRAM } from '../chain/pda.js';
+import IDL from './idl/loot.js';
+
+export const LOOT_PROGRAM = IDL.address;
+/** MagicBlock's VRF program and its default queue, the only queue the program accepts. */
+export const VRF_PROGRAM = 'Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz';
+export const VRF_QUEUE = 'Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh';
+export { MPL_CORE_PROGRAM };
+export const BPF_LOADER_UPGRADEABLE = 'BPFLoaderUpgradeab1e11111111111111111111111';
+/** Compressed NFTs: Bubblegum, and the account compression program and noop of its v2 trees. */
+export const BUBBLEGUM_PROGRAM = 'BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY';
+export const COMPRESSION_PROGRAM = 'mcmt6YrQEMKw8Mw43FmpRLmf7BqRnFMKmAcbxE3xkAW';
+export const NOOP_PROGRAM = 'mnoopTCrg4p8ry25e4bcWA9XZjbNjMTfgYVGGEdRsf3';
+
+const seed = (s) => utf8(s);
+const key = (a) => addressBytes(a);
+const u8 = (n) => uintLE(n, 1);
+const u16 = (n) => uintLE(n, 2);
+const u32 = (n) => uintLE(n, 4);
+const u64 = (n) => uintLE(n, 8);
+const i64 = (n) => intLE(n, 8);
+
+/** The PDA of these seeds under the loot program, with its bump. */
+export const lootAddress = (seeds, program = LOOT_PROGRAM) => findProgramAddress(seeds, program);
+const at = (...seeds) => lootAddress(seeds)[0];
+
+export const pda = {
+  platform: () => at(seed('platform')),
+  /** A project: any wallet (its creator) opens as many as it likes, each with a number of its own (`id`, a u64). A
+   * new owner keeps the address. */
+  project: (creator, id = 0) => at(seed('project'), key(creator), u64(id)),
+  /** The project's fee box: where the platform's fees on its transactions wait. */
+  fees: (project) => at(seed('fees'), key(project)),
+  pool: (project, index) => at(seed('pool'), key(project), u16(index)),
+  item: (project, id) => at(seed('item'), key(project), u32(id)),
+  box: (project, id) => at(seed('box'), key(project), u32(id)),
+  /** NFTs the project holds to give away as prizes: a box entry of a stash gives one of them at random. */
+  stash: (project, id) => at(seed('stash'), key(project), u32(id)),
+  /** A table of weighted rows the project writes and seals (a card among thousands, a trait's values), or commits by a Merkle root. */
+  table: (project, id) => at(seed('table'), key(project), u32(id)),
+  /** What the project keeps about a wallet (its player's profile: XP, level, rank). */
+  profile: (project, wallet) => at(seed('profile'), key(project), key(wallet)),
+  schedule: (project, id) => at(seed('schedule'), key(project), u32(id)),
+  lottery: (project, id) => at(seed('lottery'), key(project), u32(id)),
+  recipe: (project, id) => at(seed('recipe'), key(project), u32(id)),
+  contest: (project, id) => at(seed('contest'), key(project), u32(id)),
+  /** An auction: an id is its seller's own. Its bids wait in the project's vault for its mint (`vault`). */
+  auction: (project, seller, id) => at(seed('auction'), key(project), key(seller), u32(id)),
+  farm: (project, id) => at(seed('farm'), key(project), u32(id)),
+  grant: (project, id) => at(seed('grant'), key(project), u16(id)),
+  order: (project, player, nonce) => at(seed('order'), key(project), key(player), u64(nonce)),
+  /** Every collectible the program mints of its own accord (an order's, a prize's, an auction's lot): its address
+   * names its item and its serial, minted once at most. */
+  itemAsset: (item, serial) => at(seed('asset'), key(item), u32(serial)),
+  /** A contest's pot, or a lottery's: `["pot", contest or lottery]`. */
+  pot: (record) => at(seed('pot'), key(record)),
+  /** One round of a lottery: its record, opened by the round's first purchase (`["round", lottery, incarnation, round]`). */
+  round: (lottery, incarnation, round) => at(seed('round'), key(lottery), u64(incarnation), u32(round)),
+  /** A lottery round's own token account of `mint`, which the round's record owns. */
+  roundTokens: (round, mint) => at(seed('round-tokens'), key(round), key(mint)),
+  /** A contest's list of entries, one record a player (page 0). */
+  entries: (contest, incarnation, page = 0) => at(seed('entries'), key(contest), u64(incarnation), u8(page)),
+  /** A hold names its NFT and its end (Unix seconds): a release sent late never finds a later hold of the NFT. */
+  hold: (asset, freeAt) => at(seed('hold'), key(asset), i64(freeAt)),
+  /** An offer: an id is its maker's own. Its money waits in the project's vault for its mint (`vault`). */
+  offer: (project, maker, id) => at(seed('offer'), key(project), key(maker), u32(id)),
+  /** A lottery's own stash: the NFTs its places promise (`Prize::Held`), which leave only as its prizes. */
+  lotteryStash: (lottery) => at(seed('lottery_stash'), key(lottery)),
+  /** A contest's prize split by stake, set aside when it is decided: `["prize", contest]`. */
+  prizeVault: (contest) => at(seed('prize'), key(contest)),
+  /** A sealed schedule's own vault, which only its runs pay out of: `["vest", schedule]`. */
+  vest: (schedule) => at(seed('vest'), key(schedule)),
+  /** A listing of an NFT for sale or for rent: one per NFT a project holds, so its address names the NFT. */
+  listing: (project, asset) => at(seed('listing'), key(project), key(asset)),
+  staked: (farm) => at(seed('staked'), key(farm)),
+  rewards: (farm) => at(seed('rewards'), key(farm)),
+  /** A farm's record of when its seats stop earning, for a farm that keeps one (`Farm.keeps_ends`). */
+  ends: (farm) => at(seed('ends'), key(farm)),
+  /** A seat: a player's in a farm of tokens, a collectible's (its asset) in a farm of collectibles. */
+  seat: (farm, by) => at(seed('seat'), key(farm), key(by)),
+  /** What the project writes about an NFT it has no authority over (its Sheet): `nft` is a Core asset, a Token Metadata mint or a compressed NFT's asset id. */
+  sheet: (project, nft) => at(seed('sheet'), key(project), key(nft)),
+  /** A compressed NFT as last proven (`prove_leaf`), read while the leaf is unchanged and its root is still in the tree's change log. */
+  leaf: (asset) => at(seed('leaf'), key(asset)),
+  /** The root of the traits the project vouches for, under its own `key` (a collection's address, by convention). */
+  traits: (project, key_) => at(seed('traits'), key(project), key(key_)),
+  /** Bubblegum's config of a tree: `[tree]`. */
+  treeConfig: (tree) => findProgramAddress([key(tree)], BUBBLEGUM_PROGRAM)[0],
+  /** A compressed NFT's asset id: Bubblegum's `["asset", tree, nonce]`, `nonce` the count minted before it. */
+  compressedAsset: (tree, nonce) => findProgramAddress([seed('asset'), key(tree), u64(nonce)], BUBBLEGUM_PROGRAM)[0],
+  /** A wallet's counts in a project: how many times it bought from each box, crafted each recipe or held tickets in
+   * a lottery's round that limits it (`decodeCounts`). */
+  counts: (project, wallet) => at(seed('counts'), key(project), key(wallet)),
+  /** Shard `shard` of a grant's limit records: what each wallet, person, badge and voucher key claimed. */
+  claims: (grant, incarnation, shard) => at(seed('claims'), key(grant), u64(incarnation), u8(shard)),
+  /** Shard `shard` of the rounds a grant paid. */
+  rounds: (grant, incarnation, shard) => at(seed('rounds'), key(grant), u64(incarnation), u8(shard)),
+  /** The program's identity, which signs its requests to the oracle. */
+  identity: () => at(seed('identity')),
+  /** The identity the oracle signs callbacks with: the VRF program's PDA for this program. */
+  oracleIdentity: () => findProgramAddress([seed('identity'), key(LOOT_PROGRAM)], VRF_PROGRAM)[0],
+  /** The program's ProgramData account (its upgrade authority signs `init_platform`). */
+  programData: () => findProgramAddress([key(LOOT_PROGRAM)], BPF_LOADER_UPGRADEABLE)[0],
+};
+
+/** `owner`'s associated token account of `mint` (owner may be a PDA: a project's vault, a pool is not one). */
+export const ata = (owner, mint, tokenProgram = TOKEN_PROGRAM) => associatedTokenAddress(owner, mint, tokenProgram);
+
+/** A project's vault for `mint`: its associated token account, where every open order's payment is held. */
+export const vault = (project, mint, tokenProgram = TOKEN_PROGRAM) => ata(project, mint, tokenProgram);

package/js/client/policy.js

@@ -0,0 +1,69 @@
+// Lifecycle rules shared by browsers and optional keepers, read from the decoded accounts. The program still checks
+// every transition; these say when one is worth sending.
+import IDL from './idl/loot.js';
+
+const constant = name => BigInt(IDL.constants.find(value => value.name === name).value);
+/** How long the oracle has to answer before a roll or a draw may be asked again, and a pending order refunded (seconds). */
+export const STALE_SECONDS = constant('STALE_SECONDS');
+/** How long after a lottery's first ask the next ask cancels its round, and an asked order holding a payment or an NFT
+ * may be refunded (seconds). */
+export const LOTTERY_TIMEOUT_SECONDS = constant('LOTTERY_TIMEOUT_SECONDS');
+
+/**
+ * The earliest an order can be refunded, as `{ slot, at }` (the program wants a later slot than `slot` and a later
+ * second than `at`), or null when it never can be as it stands: a failed order from the next slot; a paid order the
+ * oracle never answered 10 minutes after it was asked (`STALE_SECONDS`); an asked roll holding a payment or an NFT 7 days
+ * after its first ask. A rolled order has an outcome to carry out, and is settled. A waiting roll, or an asked one holding
+ * nothing, is asked (again): `rollAskable`.
+ */
+export function orderRefundAt(order) {
+  const slot = BigInt(order.requested_slot);
+  if (order.status === 'Failed') return { slot, at: null };
+  if (order.status === 'Pending') return { slot, at: BigInt(order.asked_at) + STALE_SECONDS };
+  if (order.status === 'Asked' && (BigInt(order.paid ?? 0) > 0n || order.held)) return { slot: null, at: BigInt(order.first_asked_at) + LOTTERY_TIMEOUT_SECONDS };
+  if (['Rolled', 'Waiting', 'Asked'].includes(order.status)) return null;
+  throw new Error('Unknown order status.');
+}
+
+/** Whether an order can be refunded at `slot` and `now` (Unix seconds, the chain's clock): `orderRefundAt`. */
+export function orderRefundable(order, slot, now) {
+  const due = orderRefundAt(order);
+  if (!due) return false;
+  return (due.slot === null || BigInt(slot) > due.slot) && (due.at === null || BigInt(now) > due.at);
+}
+
+/**
+ * Whether its player or the project's keys may ask the oracle for a mission's or a recipe's roll at `slot` and `now`
+ * (Unix seconds, the chain's clock): never asked, or never answered within `STALE_SECONDS`. Once asked, a later ask comes
+ * in a later slot than the last (`SameSlot`: never the same seed twice), so a roll that found nothing in stock and waits
+ * again is asked from the next slot on.
+ */
+export const rollAskable = (order, slot, now) =>
+  (order.status === 'Waiting' && (BigInt(order.asked_first ?? 0) === 0n || BigInt(slot) > BigInt(order.requested_slot))) ||
+  (order.status === 'Asked' && BigInt(now) > BigInt(order.asked_at) + STALE_SECONDS);
+
+/**
+ * Whether a contest is off at `now` (Unix seconds), as the program reads its verdict: called off, its result
+ * overdue, or short of its least pot once entries closed. Every entry of one that is off takes its money back.
+ */
+export function contestOff(contest, now) {
+  if (contest.verdict === 'Off') return true;
+  if (contest.verdict !== 'Open') return false;
+  const total = contest.sides.reduce((sum, side) => sum + BigInt(side), 0n);
+  return BigInt(now) > BigInt(contest.result_by) || (BigInt(now) >= BigInt(contest.closes_at) && total < BigInt(contest.min_pot ?? 0));
+}
+
+/** Whether a lottery round's draw (`round`: its decoded record) was asked for and the oracle has not answered within
+ * `STALE_SECONDS` by `now` (Unix seconds, the chain's clock): anyone may ask again. */
+export const lotteryDrawStuck = (round, now) => round?.status === 'Drawing' && BigInt(now) > BigInt(round.asked_at) + STALE_SECONDS;
+
+/**
+ * Whether a lottery round's draw (`round`: its decoded record) was asked for and the oracle has not answered within
+ * `LOTTERY_TIMEOUT_SECONDS` of the first ask (asking again doesn't move it) by `now` (Unix seconds, the chain's clock):
+ * the next ask of that round (`drawLotteryIx` with its address) cancels it, and every entry is refunded. A round nobody
+ * asked to draw is never cancelled.
+ */
+export const lotteryCancellable = (round, now) => round?.status === 'Drawing' && BigInt(now) > BigInt(round.first_asked_at) + LOTTERY_TIMEOUT_SECONDS;
+
+/** A farm seat's `earns_until` when nothing ends its earning (i64::MAX): no tier term and no fuel it reads. */
+export const NO_END = (1n << 63n) - 1n;

package/js/client/random.js

@@ -0,0 +1,70 @@
+// The loot program's rolling module (`src/random`), mirrored: every random choice it makes is drawn from a stream of
+// the oracle's answer, by a path that names what is drawn, with one unbiased sampler. A page shows from an order's
+// answer what each draw gave (and a fresh unit's range traits) exactly as the program drew them. Held to the
+// program's own vectors (`js/test/fixtures/roll-vectors.json`, from gamesfun-loot's `tests/fixtures`).
+import { concat, uintLE } from '../chain/bytes.js';
+import { sha256 } from '../chain/sha256.js';
+
+/** What a path's first word names (`random::tag`): an entry of a box, a stash's NFT, a lottery's ticket, a fresh trait. */
+export const TAG = Object.freeze({ ENTRY: 1, STASH: 2, LOTTERY: 3, TRAIT: 4 });
+/** The most words a path holds. */
+export const MAX_PATH = 8;
+const U64 = (1n << 64n) - 1n;
+const PREFIX = new TextEncoder().encode('loot-roll-v1');
+
+/** A stream of the oracle's 32-byte `answer` at `path` (whole numbers): seed = sha256("loot-roll-v1" | answer | path as
+ * u32 little-endian words); its nth number the first 8 bytes, little-endian, of sha256(seed | n as u64 little-endian). */
+export function stream(answer, path = []) {
+  const words = path.slice(0, MAX_PATH).map((w) => uintLE(w, 4));
+  const seed = sha256(concat(PREFIX, Uint8Array.from(answer), ...words));
+  let counter = 0n;
+  return {
+    next() {
+      const block = sha256(concat(seed, uintLE(counter, 8)));
+      counter += 1n;
+      return block.subarray(0, 8).reduceRight((n, b) => (n << 8n) | BigInt(b), 0n);
+    },
+  };
+}
+
+/** A number from 0 to `n` - 1, every one as likely: a draw past the last whole multiple of `n` is drawn again. null for
+ * `n` 0. */
+export function uniform(s, n) {
+  n = BigInt(n);
+  if (n === 0n) return null;
+  const limit = U64 - (((1n << 64n) - n) % n);
+  for (;;) {
+    const roll = s.next();
+    if (roll <= limit) return roll % n;
+  }
+}
+
+/** The row `at` lands on, the weights walked in order. null past the last. */
+export function walk(weights, at) {
+  let left = BigInt(at);
+  for (const [i, w] of weights.entries()) {
+    if (left < BigInt(w)) return i;
+    left -= BigInt(w);
+  }
+  return null;
+}
+
+/** A row by weight (a weight of 0 never drawn); null when none weighs anything, or they sum past 64 bits. */
+export function weighted(s, weights) {
+  const total = weights.reduce((n, w) => n + BigInt(w), 0n);
+  if (total > U64) return null;
+  const at = uniform(s, total);
+  return at === null ? null : walk(weights, at);
+}
+
+/** A number from `min` to `max`, both included, every one as likely (either order). */
+export function range(s, min, max) {
+  let [lo, hi] = [BigInt(min), BigInt(max)];
+  if (lo > hi) [lo, hi] = [hi, lo];
+  const n = hi - lo + 1n;
+  return n > U64 ? s.next() : lo + uniform(s, n);
+}
+
+/** A fresh unit's range trait `t` (its place among the item's traits) as the program draws it at the mint: from the
+ * order's `answer`, `at` the unit's place in the order's `won`. */
+export const rangeTrait = (answer, at, t, min, max) => range(stream(answer, [TAG.TRAIT, at, t]), min, max);

package/js/client/sizes.js

@@ -0,0 +1,297 @@
+// Rent sizes from the current IDL. Fixed allocations reserve the largest enum and option forms,
+// matching Anchor InitSpace. Dynamic records use their actual encoded fields.
+import { encodeAccount, encodeBorsh } from '../chain/borsh.js';
+import IDL from './idl/loot.js';
+
+const scalar = { bool: 1, u8: 1, u16: 2, u32: 4, i32: 4, u64: 8, i64: 8, u128: 16, pubkey: 32 };
+// What a fixed-size account reserves for its lists and strings: a roll's fate (`Fate.shifts`, each key at most 32 bytes).
+const bounds = { 'Fate.shifts': 2 };
+const strings = { 'Shift.key': 32 };
+function maximum(type, path) {
+  if (type === 'string') {
+    if (!(path in strings)) throw new Error(`No allocation bound for ${path}`);
+    return 4 + strings[path];
+  }
+  if (typeof type === 'string') {
+    if (!(type in scalar)) throw new Error(`Unbounded IDL type ${path}: ${type}`);
+    return scalar[type];
+  }
+  if (type.array) return type.array[1] * maximum(type.array[0], path);
+  if (type.option) return 1 + maximum(type.option, path);
+  if (type.vec) {
+    if (!(path in bounds)) throw new Error(`No allocation bound for ${path}`);
+    return 4 + bounds[path] * maximum(type.vec, path);
+  }
+  const name = type.defined.name;
+  const definition = IDL.types.find((entry) => entry.name === name)?.type;
+  if (!definition) throw new Error(`Missing current IDL type ${name}`);
+  const fields = (list) => (list ?? []).reduce((n, field) => n + maximum(field.type ?? field, `${name}.${field.name ?? ''}`), 0);
+  return definition.kind === 'enum' ? 1 + Math.max(...definition.variants.map((variant) => fields(variant.fields))) : fields(definition.fields);
+}
+
+/** The space reserved by a fixed-size account, including its discriminator. */
+export function allocationBytes(name) {
+  const account = IDL.accounts.find((entry) => entry.name === name);
+  if (!account) throw new Error(`Missing current IDL account ${name}`);
+  return account.discriminator.length + maximum({ defined: { name } }, name);
+}
+
+/** The exact bytes of a dynamically allocated account. */
+export const accountBytes = (name, value) => encodeAccount(IDL, name, value).length;
+/** A seat; a loan's hold (with room for its debt); a hold a player asks for, made without one (`Hold::PLAIN`). */
+export const ACCOUNT_BYTES = Object.freeze({
+  Seat: allocationBytes('Seat'),
+  Loan: allocationBytes('Hold'),
+  Hold: allocationBytes('Hold') - maximum({ defined: { name: 'Debt' } }, 'Debt'),
+});
+
+/** A project's bytes with `collections` collections, as the program sizes the account. */
+export const projectBytes = (collections = 0) => 153 + 32 * collections;
+
+/** The most accounts the oracle's answer to a roll carries (`MAX_CALLBACK_ACCOUNTS`). */
+export const MAX_CALLBACK_ACCOUNTS = 21;
+
+/**
+ * The most accounts a roll of `entries` hands the oracle (`catalog::callback_accounts`): the order, the box and the
+ * ticket; one for each prize that needs one at the roll (an item, a pool, a stash); and with tokens, the two token
+ * programs, the project, and a mint and a vault for each source of tokens.
+ */
+export function callbackAccounts(entries) {
+  const sources = new Set();
+  let named = 0;
+  for (const prize of entries.flatMap((e) => e.prizes)) {
+    if (prize.Item || prize.Compressed || prize.Nft || prize.Stash) named += 1;
+    else if (prize.Tokens) {
+      if (prize.Tokens.from.Pool) named += 1;
+      sources.add(JSON.stringify(prize.Tokens.from));
+    }
+  }
+  return 3 + named + (sources.size ? 3 + 2 * sources.size : 0);
+}
+
+/**
+ * How many fresh items' table accounts the oracle's answer to a roll of `entries` can carry (`order::table_budget`):
+ * what the box's own accounts leave of `MAX_CALLBACK_ACCOUNTS`. Negative: the box can't be rolled at all.
+ */
+export const tableBudget = (entries) => MAX_CALLBACK_ACCOUNTS - callbackAccounts(entries);
+
+const draws = (lootBox) => (lootBox.slots?.length ? lootBox.slots.reduce((n, s) => n + Number(s.count), 0) : 1);
+const ZERO = '11111111111111111111111111111111';
+
+/** The most an order can be (`MAX_ORDER_BYTES`, not in the IDL): a box whose one open's order would be more is refused
+ * at its upsert (`BadEntries`). In practice a pack is bounded first by what one oracle answer draws (`drawsFit`). */
+export const MAX_ORDER_BYTES = 10_240;
+
+/** The bytes a draw sets aside for a prize, as the `Won` it becomes (`Order::sized`): an item 14, tokens or an NFT 41,
+ * a roll, a held NFT or a raffled place nothing. */
+const wonBytes = (p) => (p.Item || p.Compressed ? 14 : p.Tokens || p.Nft || p.Stash ? 41 : 0);
+const tableCount = (item) => (item?.traits ?? []).filter((t) => t.from?.Table).length;
+
+/**
+ * The rows of fresh items' tables a draw of each entry writes into its order (`order::rows_of`), walked with the box's
+ * table budget as the roll's accounts are (`entryAccounts`: an item whose tables don't fit what is left draws none).
+ * `items` maps an item's id to its decoded Item; one left out is taken as not fresh.
+ */
+export function entryRows(entries, items = {}) {
+  let budget = Math.max(0, tableBudget(entries));
+  return entries.map(({ prizes }) => prizes.reduce((n, p) => {
+    const id = p.Item?.[0] ?? p.Compressed?.item;
+    const t = id === undefined ? 0 : tableCount(items[id]);
+    if (t > budget) return n;
+    budget -= t;
+    return n + t;
+  }, 0));
+}
+
+/**
+ * The bytes of an order of `lootBox` with `shares` shares and `opens` opens. With `items` (an item's id to its decoded
+ * Item), as `open_box` sizes it (`Order::sized`): each draw at its dearest entry's prizes as the `Won` they become (an
+ * item 14 bytes, tokens or an NFT 41, a roll none) and 4 bytes for each table row its fresh items draw now
+ * (`entryRows`); its odds and its largest fate. Without `items`, as a roll made inside another call sizes it (a craft,
+ * a grant's claim, a mission, a roll lot: `Order::space_for`): the box's whole table budget a draw for a box that
+ * gives items. A pack's order grows with its cards.
+ */
+export function orderBytes(lootBox, shares = 0, opens = 1, items) {
+  const drawn = draws(lootBox) * Math.max(1, opens);
+  const aDraw = Math.max(0, ...lootBox.entries.map((e) => e.prizes.reduce((n, p) => n + wonBytes(p), 0)));
+  const gives = lootBox.entries.some((e) => e.prizes.some((p) => p.Item || p.Compressed));
+  const rows = items ? Math.max(0, ...entryRows(lootBox.entries, items)) : gives ? Math.max(0, tableBudget(lootBox.entries)) : 0;
+  const fates = lootBox.fates ?? [];
+  const fate = fates.reduce((a, f) => (a && encodeBorsh(IDL, { defined: { name: 'Fate' } }, a).length >= encodeBorsh(IDL, { defined: { name: 'Fate' } }, f).length ? a : f), null);
+  const empty = {
+    project: ZERO, player: ZERO, mint: ZERO, loot_box: ZERO, box_version: 0,
+    odds_bps: new Array(lootBox.odds?.length ?? 0).fill(0),
+    status: 'Waiting',
+    won: [],
+    paid: 0n, fee: 0n,
+    shares: new Array(shares).fill({ to: { Account: [ZERO] }, bps: 0 }),
+    opens: 0, settled: 0, undrawn: 0, back: 0n, settler: ZERO, drew: 0, answer: new Uint8Array(32), drawn: [], reserved: 0n,
+    requested_slot: 0n, asked_first: 0n, asked_at: 0n, first_asked_at: 0n, counted: 0, subject: lootBox.subject ? ZERO : null, held: false, fate,
+  };
+  return encodeAccount(IDL, 'Order', empty).length + drawn * (aDraw + rows * 4);
+}
+
+// What one oracle answer's roll spends, counted at no less than each part costs (`order.rs`'s `RollCost`, measured by
+// the program's `tests/roll_costs.rs` and `tests/roll_heap.rs`), against the compute and the heap the oracle gives its
+// answer, less a margin.
+const ROLL_BUDGET = 300_000n;
+const ROLL_HEAP = 32n * 1024n - 512n;
+const COST = { fixed: 20_000n, entry: 3_500n, blank: 1_400n, weigh: 1_000n, weighEntry: 40n, pair: 150n, item: 1_500n, tokens: 6_000n, draw: 9_000n, group: 250n, reread: 1_000n, finish: 15_000n, won: 150n, drawn: 50n, odds: 1_000n, share: 1_000n, fate: 1_000n, slot: 500n, slotEntry: 350n, openSlot: 150n };
+const BYTES = { start: 6_000n, prizeRead: 600n, entryRead: 180n, minted: 700n, pooled: 1_000n, prize: 200n, draw: 40n, finish: 2_000n, won: 120n, boxByte: 2n, gateByte: 3n, odds: 100n, fate: 60n, slot: 64n };
+
+/** The Borsh length of `value` as IDL type `type`, an address counted as 32 bytes whatever stands in for it (a spec's
+ * `@mint:…` before it goes live). */
+function borshLength(type, value) {
+  if (typeof type === 'string') return type === 'string' ? 4 + new TextEncoder().encode(String(value)).length : type === 'bytes' ? 4 + value.length : scalar[type];
+  if (type.array) return type.array[1] * (type.array[0] === 'u8' ? 1 : borshLength(type.array[0], value?.[0]));
+  if (type.vec) return 4 + (value ?? []).reduce((n, v) => n + borshLength(type.vec, v), 0);
+  if (type.option) return value == null ? 1 : 1 + borshLength(type.option, value);
+  const definition = IDL.types.find((entry) => entry.name === type.defined.name).type;
+  if (definition.kind === 'enum') {
+    const name = typeof value === 'string' ? value : Object.keys(value)[0];
+    const fields = definition.variants.find((v) => v.name === name)?.fields ?? [];
+    const payload = typeof value === 'string' ? [] : value[name];
+    return 1 + fields.reduce((n, f, i) => n + (typeof f === 'object' && 'name' in f ? borshLength(f.type, payload[f.name]) : borshLength(f, payload[i])), 0);
+  }
+  return definition.fields.reduce((n, f) => n + borshLength(f.type, value[f.name]), 0);
+}
+
+const defined = (name) => ({ defined: { name } });
+
+/**
+ * The heap reading a box takes beyond its entries (`order::box_bytes`): its odds, gate, shares, subject, slots and
+ * fates, read whole with it, by their bytes and their number. `box`: the box's args, as `upsertBoxIx` takes them.
+ */
+export function boxBytes({ odds = [], gate = null, shares = [], subject = null, slots = [], fates = [] }) {
+  const slotsWritten = slots.map((s) => ({ only: [], distinct: false, share: 0, ...s }));
+  const fatesWritten = fates.map((f) => ({ then: null, ...f, shifts: (f.shifts ?? []).map((x) => ({ from_now: false, ...x })) }));
+  const bytes = borshLength({ vec: defined('Odds') }, odds) + borshLength({ vec: defined('Share') }, shares) + borshLength({ option: defined('Rule') }, subject)
+    + borshLength({ vec: defined('Slot') }, slotsWritten) + borshLength({ vec: defined('Fate') }, fatesWritten);
+  return BYTES.boxByte * BigInt(bytes) + BYTES.gateByte * BigInt(borshLength({ option: defined('Gate') }, gate)) + BYTES.odds * BigInt(odds.length) + BYTES.fate * BigInt(fates.length) + BYTES.slot * BigInt(slots.length);
+}
+
+/** The account a prize reads, as a string, when it reads one the box can name: entries naming the same share it. */
+const accountOf = (p) => {
+  if (p.Item != null) return `item ${p.Item[0] ?? p.Item}`;
+  if (p.Compressed) return `item ${p.Compressed.item}`;
+  if (p.Tokens?.from?.Pool) return `pool ${p.Tokens.from.Pool[0] ?? p.Tokens.from.Pool}`;
+  if (p.Stash != null) return `stash ${p.Stash[0] ?? p.Stash}`;
+  if (p.Nft) return `stash ${p.Nft.stash}`;
+  return null;
+};
+
+/**
+ * Whether all of `opens` opens of `entries` by `slots` fit one oracle answer (`order::draws_fit`), each draw at the
+ * dearest its slot could make, with what is known from the box alone (no table rows, a stash of one group), its `odds`,
+ * `shares` and `fates` counted, and `bytes` (`boxBytes`) of heap reading the box takes beyond its entries. `slots` may
+ * be a number: that many draws among every entry. The answer's heap counts for a box that rolls, or one sold through
+ * the oracle (`oracle`: a box that doesn't roll but one `buy` can't carry, `buyFits`). The program refuses a box whose
+ * one open doesn't fit at its upsert, and a purchase that doesn't at `open_box`, where it also reads what the accounts
+ * hold (`PackTooLarge`).
+ */
+export function drawsFit(entries, slots, opens = 1, { odds = 0, shares = 0, fates = 0, bytes = 0n, oracle = false } = {}) {
+  const list = typeof slots === 'number' || typeof slots === 'bigint' ? [{ count: slots, only: [] }] : (slots ?? []);
+  const draws = list.reduce((n, s) => n + BigInt(s.count), 0n) * BigInt(opens);
+  if (draws <= 1n) return true;
+  const n = BigInt(entries.length);
+  const weigh = COST.weigh + COST.weighEntry * n;
+  const reads = entries.map((e) => e.prizes.map(accountOf));
+  const cost = entries.map((e) => e.prizes.reduce((c, p) => {
+    if (p.Item != null || p.Compressed || p.Nft) return { set: c.set + COST.item, again: c.again + COST.reread, bytes: c.bytes + BYTES.prize };
+    if (p.Tokens) return { set: c.set + COST.tokens, again: c.again + (p.Tokens.from.Pool ? COST.reread : 0n), bytes: c.bytes + (p.Tokens.from.Pool ? BYTES.pooled : BYTES.minted) };
+    if (p.Stash != null) return { set: c.set + COST.draw + COST.group, again: c.again + COST.reread, bytes: c.bytes + BYTES.prize };
+    return { set: c.set + COST.item, again: c.again, bytes: c.bytes + BYTES.prize };
+  }, { set: 0n, again: 0n, bytes: BYTES.draw }));
+  const next = entries.map((_, i) => weigh + cost[i].set + cost.reduce((sum, c, j) => (j === i || reads[i].some((a) => a && reads[j].includes(a)) ? sum + c.again : sum), 0n));
+  const most = BigInt(Math.max(1, ...entries.map((e) => e.prizes.length)));
+  let spent = COST.fixed + COST.pair * n * n * most * most + entries.reduce((c, e) => c + (e.prizes.length ? COST.entry : COST.blank), 0n);
+  let used = BYTES.start + BigInt(bytes) + BYTES.entryRead * n + BYTES.prizeRead * BigInt(entries.reduce((c, e) => c + e.prizes.length, 0));
+  let won = 0n;
+  spent += (COST.slot + COST.slotEntry * n) * BigInt(Math.max(1, list.length)) + COST.openSlot * BigInt(list.length) * BigInt(opens) + COST.odds * BigInt(odds) + COST.share * BigInt(shares) + COST.fate * BigInt(fates);
+  for (const s of list) {
+    const count = BigInt(s.count) * BigInt(opens);
+    const among = entries.map((_, i) => i).filter((i) => !(s.only ?? []).length || (s.only ?? []).includes(i));
+    const dearest = (f) => among.reduce((m, i) => (f(i) > m ? f(i) : m), 0n);
+    spent += count * dearest((i) => next[i]);
+    used += count * dearest((i) => cost[i].bytes);
+    won += count * dearest((i) => BigInt(entries[i].prizes.length));
+  }
+  const rolls = oracle || entries.length > 1 || entries.some((e) => e.prizes.some((p) => p.Stash != null));
+  return spent + COST.finish + COST.won * won + COST.drawn * draws <= ROLL_BUDGET && (!rolls || used + BYTES.finish + BYTES.won * won + draws <= ROLL_HEAP);
+}
+
+// What one `buy` takes, as the program counts it at the box's write (`catalog::buy_fits`): a transaction holds 64
+// accounts, 64 instructions and 1,400,000 compute units.
+const BUY = { accounts: 15, calls: 7, cu: 30_000, most: { accounts: 64, calls: 64, cu: 1_400_000 } };
+const sameJson = (a, b) => JSON.stringify(a, (_, v) => (typeof v === 'bigint' ? String(v) : v)) === JSON.stringify(b, (_, v) => (typeof v === 'bigint' ? String(v) : v));
+
+/**
+ * Whether one `buy` of a box that doesn't roll (one entry, given `draws` times: its slots' counts) fits one transaction
+ * (`catalog::buy_fits`): its accounts, its instructions and its compute, each prize's at the most it takes. A named NFT
+ * is given once at most. A box that doesn't fit sells through the oracle (`open_box`), its answer's heap counted
+ * (`drawsFit` with `oracle`), and can't give a roll (`PackTooLarge`). `box`: the box's args.
+ */
+export function buyFits(box, draws = (box.slots?.length ? box.slots.reduce((n, s) => n + Number(s.count), 0) : 1)) {
+  const entry = box.entries?.[0];
+  if (!entry) return true;
+  let { accounts, calls, cu } = BUY;
+  for (const share of box.shares ?? []) {
+    const to = typeof share.to === 'string' ? share.to : Object.keys(share.to)[0];
+    const [a, c] = to === 'Burn' ? [0, 1] : to === 'Pool' || to === 'Account' ? [1, 1] : to === 'Holder' ? [3, 6] : [2, 6];
+    accounts += a;
+    calls += c;
+    cu += 30_000;
+  }
+  const gate = box.gate ? Object.keys(box.gate)[0] : null;
+  accounts += gate === 'List' ? Number(box.gate.List.depth) : gate === 'Staked' ? 2 : gate === 'Holds' ? 5 : 0;
+  const limit = box.per_wallet ?? {};
+  if (Number(limit.total ?? 0) > 0 || Number(limit.per_window ?? 0) > 0) calls += 1;
+  // A collectible's collection and Metaplex Core, named once for all of them.
+  if (entry.prizes.some((p) => p.Item != null)) accounts += 2;
+  for (const [i, p] of entry.prizes.entries()) {
+    const first = !entry.prizes.slice(0, i).some((q) => (accountOf(q) && accountOf(q) === accountOf(p)) || sameJson(q, p));
+    const gives = p.Tokens ? 1 : draws;
+    let once = 0, each = 0, c = 0, units = 0;
+    if (p.Tokens) [once, c, units] = [p.Tokens.from.Pool ? 3 : 2, 5, 30_000];
+    else if (p.Item != null) [once, each, c, units] = [1, 1, 4, 40_000];
+    else if (p.Compressed) [once, c, units] = [9, 6, 150_000];
+    else if (p.Roll != null) [once, each, c, units] = [1, 1, 1, 20_000];
+    else if (p.Nft) {
+      if (draws > 1) return false;
+      [once, c, units] = [8, 6, 60_000];
+    }
+    accounts += (first ? once : 0) + each * gives;
+    calls += c * gives;
+    cu += units * gives;
+  }
+  return accounts <= BUY.most.accounts && calls <= BUY.most.calls && cu <= BUY.most.cu;
+}
+
+/** The most program rent and fee one order takes from its player, in lamports (0.01 SOL): a client cap (`opensAnOrder`). */
+export const ORDER_COST_CAP = 10_000_000n;
+/** Rent a byte, as devnet and mainnet-beta charge it ((bytes + 128) × 5,080 lamports). */
+const RENT_PER_BYTE = 5_080n;
+/** The player's fee for one order (`fee::PLAYER_FEE`, 0.002 SOL). */
+const PLAYER_FEE = 2_000_000n;
+
+/**
+ * The most opens of `lootBox` a client puts in one order: what one oracle answer draws (`drawsFit`), and what keeps the
+ * order's rent and the player's fee within `ORDER_COST_CAP` (`orderBytes` with `items`, so with the box's shares). At
+ * least one: a box whose one open is over the cap is still bought one open an order. A purchase of more is several
+ * orders, each its own answer.
+ */
+export function opensAnOrder(lootBox, { shares = (lootBox.shares ?? []).length, items = {}, rentPerByte = RENT_PER_BYTE } = {}) {
+  const fits = (n) => drawsFit(lootBox.entries, lootBox.slots?.length ? lootBox.slots : 1, n, { odds: (lootBox.odds ?? []).length, shares, fates: (lootBox.fates ?? []).length, bytes: boxBytes(lootBox), oracle: true }) && (BigInt(orderBytes(lootBox, shares, n, items)) + 128n) * rentPerByte + PLAYER_FEE <= ORDER_COST_CAP;
+  let n = 1;
+  while (n < 4096 && fits(n + 1)) n += 1;
+  return n;
+}
+
+// Lists of records (tag 26, `list.rs`): a tag byte and a 6-byte header, then fixed-width records.
+export const LIST_HEAD_BYTES = 7;
+/** A limit record (a wallet's count of a box, a recipe or a lottery round; a grant's claim count): key, count, window, in it. */
+export const LIMIT_RECORD_BYTES = 28;
+/** A round a grant paid a wallet: its key alone. */
+export const ROUND_RECORD_BYTES = 16;
+/** A contest's entry: of tokens, and of NFTs (the NFT, its place on its side, the picks taken). */
+export const CONTEST_ENTRY_BYTES = Object.freeze({ tokens: 43, nfts: 83 });

package/js/client/traits.js

@@ -0,0 +1,44 @@
+// The traits a project vouches for (`set_traits`, `prove_traits`): a Merkle tree of what NFTs' off-chain metadata says
+// of them (a background, a class), whose root the project's owner or authority signs once. Anyone then writes an NFT's
+// traits into its Sheet with its proof. Leaves and nodes are hashed exactly as the program hashes them. Browser-safe.
+import { addressBytes } from '../chain/base58.js';
+import { compareBytes, concat, uintLE, utf8 } from '../chain/bytes.js';
+import { sha256 } from '../chain/sha256.js';
+
+const text = (s) => concat(uintLE(utf8(s).length, 4), utf8(s));
+
+/** A leaf: an NFT's address and its traits ([{ key, value }], in order). */
+export const traitsLeaf = (nft, attributes) =>
+  sha256(concat(Uint8Array.of(0), addressBytes(nft), uintLE(attributes.length, 4), ...attributes.map((a) => concat(text(a.key), text(a.value)))));
+
+/** Two nodes joined, the smaller first, so a proof needs no left or right. */
+export const traitsNode = (a, b) => (compareBytes(a, b) <= 0 ? sha256(concat(Uint8Array.of(1), a, b)) : sha256(concat(Uint8Array.of(1), b, a)));
+
+/**
+ * The tree of `entries` ([{ nft, attributes }]): { root, proof(nft) → [node, …] bottom up }. A node left without a pair
+ * at a level goes up as it is.
+ */
+export function traitsTree(entries) {
+  const levels = [entries.map((e) => traitsLeaf(e.nft, e.attributes))];
+  while (levels.at(-1).length > 1) {
+    const below = levels.at(-1);
+    const up = [];
+    for (let i = 0; i < below.length; i += 2) up.push(i + 1 < below.length ? traitsNode(below[i], below[i + 1]) : below[i]);
+    levels.push(up);
+  }
+  const at = new Map(entries.map((e, i) => [e.nft, i]));
+  return {
+    root: levels.at(-1)[0],
+    proof(nft) {
+      let i = at.get(nft);
+      if (i === undefined) throw new Error(`${nft} is not in this traits tree.`);
+      const out = [];
+      for (const level of levels.slice(0, -1)) {
+        const sibling = i ^ 1;
+        if (sibling < level.length) out.push(level[sibling]);
+        i >>= 1;
+      }
+      return out;
+    },
+  };
+}