@xgamesfun/solana 0.20.1 → 0.25.0

package/js/client/pda.js

@@ -16,18 +16,17 @@ 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);
+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];
-const keyReceipt = (grant, incarnation, voucherKey) => at(seed('code'), key(grant), u64(incarnation), key(voucherKey));
 
 export const pda = {
   platform: () => at(seed('platform')),
@@ -35,12 +34,16 @@ export const pda = {
    * 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), u8(index)),
+  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)),
@@ -53,48 +56,51 @@ export const pda = {
   /** 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)),
-  lotteryFunds: (lottery) => at(seed('lottery_funds'), key(lottery)),
-  lotteryReceipt: (lottery, incarnation, wallet) => at(seed('receipt'), key(lottery), u64(incarnation), key(wallet)),
-  /** One purchase of a lottery's tickets, at a nonce of its buyer's. */
-  contribution: (lottery, player, nonce) => at(seed('contribution'), key(lottery), key(player), u64(nonce)),
-  /** A wallet's entry in a contest: one, on one side (another side is `OtherSide`). */
-  entry: (contest, player) => at(seed('entry'), key(contest), key(player)),
+  /** A contest's pot: `["pot", contest]`. */
+  pot: record => at(seed('pot'), key(record)),
+  /** A lottery's pot `id` (below `MAX_POTS`), kept from round to round: `["pot", lottery, id]`. */
+  lotteryPot: (lottery, id) => at(seed('pot'), key(lottery), u8(id)),
+  /** 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)),
+  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)),
+  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)),
+  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)),
+  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)),
+  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],
+  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 counter on a box or recipe. Grants and lotteries also name their incarnation. */
-  receipt: (record, wallet) => at(seed('receipt'), key(record), key(wallet)),
-  grantReceipt: (grant, incarnation, wallet) => at(seed('receipt'), key(grant), u64(incarnation), key(wallet)),
-  person: (grant, incarnation, personHash) => at(seed('person'), key(grant), u64(incarnation), Uint8Array.from(personHash)),
-  /** How many times an NFT shown claimed an open grant its gate asks for one of: an address of its own, never a person's. */
-  badge: (grant, incarnation, nft) => at(seed('badge'), key(grant), u64(incarnation), key(nft)),
-  /** A voucher key's counter on a grant (a promo code's). */
-  code: keyReceipt,
+  /** 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. */

package/js/client/policy.js

@@ -3,28 +3,46 @@
 import IDL from './idl/loot.js';
 
 const constant = name => BigInt(IDL.constants.find(value => value.name === name).value);
-export const STALE_SLOTS = constant('STALE_SLOTS');
-export const LOTTERY_TIMEOUT_SLOTS = constant('LOTTERY_TIMEOUT_SLOTS');
-const U64_MAX = (1n << 64n) - 1n;
+/** 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 slot an order can be refunded in, or null when it never can be: a rolled order has an outcome anyone
- * can carry out, and is settled, never refunded; a roll a mission or a recipe made waits for anyone to ask for it
- * (`Waiting`), and once asked (`Asked`) is asked again if the oracle never answers (`rollAskable`).
+ * 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 orderRefundSlot(order) {
-  let wait;
-  if (order.status === 'Failed') wait = 0n;
-  else if (order.status === 'Pending') wait = STALE_SLOTS;
-  else if (['Rolled', 'Waiting', 'Asked'].includes(order.status)) return null;
-  else throw new Error('Unknown order status.');
-  const deadline = BigInt(order.requested_slot) + wait;
-  // The program requires strictly greater than the saturating deadline; MAX + 1 is unreachable.
-  return (deadline > U64_MAX ? U64_MAX : deadline) + 1n;
+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 anyone may ask the oracle for a mission's or a recipe's roll at `slot`: never asked, or never answered. */
-export const rollAskable = (order, slot) => order.status === 'Waiting' || (order.status === 'Asked' && BigInt(slot) > BigInt(order.requested_slot) + STALE_SLOTS);
+/** 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
@@ -34,15 +52,25 @@ 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));
+  return (
+    BigInt(now) > BigInt(contest.result_by) ||
+    (BigInt(now) >= BigInt(contest.closes_at) && total < BigInt(contest.min_pot ?? 0))
+  );
 }
 
-/** Whether a lottery's draw was asked for and the oracle has not answered within `STALE_SLOTS`: anyone may ask again. */
-export const lotteryDrawStuck = (lottery, slot) => lottery.status === 'Drawing' && BigInt(slot) > BigInt(lottery.asked_slot) + STALE_SLOTS;
+/** 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's draw was asked for and the oracle has not answered within `LOTTERY_TIMEOUT_SLOTS` of the first
- * ask (asking again doesn't move it): anyone may cancel the round and refund it. A round nobody asked to draw is never
- * cancelled.
+ * 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 = (lottery, slot) => lottery.status === 'Drawing' && BigInt(slot) > BigInt(lottery.asked_first) + LOTTERY_TIMEOUT_SLOTS;
+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);