@xgamesfun/solana 0.20.1 → 0.24.0

package/js/client/accounts.js

@@ -1,17 +1,21 @@
-// Reading the loot program's accounts and receipts. Every account starts with a one-byte tag (1 to 23); the IDL
-// describes most of them, and the ones it doesn't (a receipt, a sheet, a stash, …) are read here by hand. Values come back in the
+// Reading the loot program's accounts and receipts. Every account starts with a one-byte tag (1 to 29); the IDL
+// describes most of them, and the ones it doesn't (a list of records, a lottery round, a sheet, a stash, …) are read
+// here by hand. Values come back in the
 // IDL's shapes (chain/borsh.js).
-import { encodeBase58, NO_ADDRESS } from '../chain/base58.js';
-import { decodeAccount, decodeEvents } from '../chain/borsh.js';
-import { compareBytes, fromHex, readUintLE, toHex } from '../chain/bytes.js';
+import { addressBytes, encodeBase58, NO_ADDRESS } from '../chain/base58.js';
+import { decodeAccount, decodeBorsh, decodeEvents } from '../chain/borsh.js';
+import { compareBytes, concat, readUintLE, toHex, uintLE } from '../chain/bytes.js';
 import { sha256 } from '../chain/sha256.js';
 import { SYSTEM_PROGRAM } from '../chain/pda.js';
-import { LOOT_PROGRAM } from './pda.js';
+import { LOOT_PROGRAM, pda } from './pda.js';
 import IDL from './idl/loot.js';
-import { MAX_RECEIPT_ROUNDS, RECEIPT_BASE_BYTES, RECEIPT_ROUND_BYTES } from './sizes.js';
-export { MAX_RECEIPT_ROUNDS } from './sizes.js';
 
-/** Account tags: each account's first byte, as the program writes it. */
+/** The bytes of one time in a farm's record of ends (`decodeEnds`): rent its writer pays, not refunded when a seat leaves. */
+export const END_BYTES = 44;
+/** The bytes of a farm's record of ends with no time in it, its owner's rent at `open_farm`. */
+export const ENDS_HEAD_BYTES = 7;
+
+/** Account tags: each account's first byte, as the program writes it; every list of records (`decodeList`) is 26. */
 export const TAGS = Object.freeze({
   Platform: 1,
   Project: 2,
@@ -23,19 +27,23 @@ export const TAGS = Object.freeze({
   Recipe: 8,
   Hold: 9,
   Contest: 10,
-  Entry: 11,
   Sheet: 12,
   Traits: 13,
-  Grant: 14,
-  Receipt: 15,
-  LotteryContribution: 16,
+  LotteryRound: 16,
   Farm: 17,
   Seat: 18,
   Proven: 19,
   Auction: 20,
-  Stash: 21,
   Offer: 22,
   Listing: 23,
+  Profile: 24,
+  Grant: 27,
+  // A table, and a stash: a table of NFTs (21 was a stash's own before 0.22).
+  Table: 25,
+  // A list of records: a wallet's counts, a grant's claims or rounds, a contest's entries.
+  List: 26,
+  // A farm's record of when its seats stop earning (`decodeEnds`).
+  Ends: 29,
 });
 
 const BY_TAG = Object.fromEntries(Object.entries(TAGS).map(([name, tag]) => [tag, name]));
@@ -43,43 +51,141 @@ const BY_TAG = Object.fromEntries(Object.entries(TAGS).map(([name, tag]) => [tag
 /** The kind of a loot account from its first byte, or null. */
 export const accountKind = (data) => (data?.length ? BY_TAG[data[0]] ?? null : null);
 
-/** A loot account of the named kind (one the IDL describes). Throws when the data is not one. */
-export const decode = (name, data) => decodeAccount(IDL, name, data);
+/**
+ * The records the program writes by hand, as IDL types: a lottery round's header and what it keeps (`LotteryRound`,
+ * tag 16), and a contest's entry. The client reads them with the same Borsh codec as any account.
+ */
+const RECORDS = [
+  { name: 'Round', type: { kind: 'enum', variants: ['Open', 'Drawing', 'Drawn', 'Cancelled'].map((name) => ({ name })) } },
+  { name: 'TokenPrize', type: { kind: 'struct', fields: [{ name: 'run', type: 'u16' }, { name: 'mint', type: 'pubkey' }, { name: 'each', type: 'u64' }, { name: 'sent', type: 'u64' }, { name: 'arrived', type: 'u64' }, { name: 'minted', type: 'bool' }] } },
+  { name: 'Opened', type: { kind: 'struct', fields: [{ name: 'mint', type: 'pubkey' }, { name: 'by', type: 'pubkey' }] } },
+  {
+    name: 'LotteryRound',
+    type: {
+      kind: 'struct',
+      fields: [
+        ['project', 'pubkey'], ['lottery', 'pubkey'], ['id', 'u32'], ['incarnation', 'u64'], ['round', 'u32'], ['bump', 'u8'], ['opener', 'pubkey'], ['lent', 'u64'], ['head', 'u32'],
+        ['status', { defined: { name: 'Round' } }],
+        // The terms, as the lottery's revision had them at the round's first purchase; whether its entries keep what
+        // arrived (a payment mint with a transfer fee, or a share the buyer chooses, paid as they buy).
+        ['revision', 'u32'], ['terms', { defined: { name: 'LotteryTerms' } }], ['fee', 'bool'],
+        // The totals, split at each purchase: what each share paid in common takes, the entries that own a part of
+        // their own, and the parts owed now.
+        ['sold', 'u64'], ['to_pot', 'u64'], ['common', { vec: 'u64' }], ['owns', 'u32'], ['owed', 'u32'],
+        // The draw, and the money the ask fixed: the pot's (what the round owes the pot back: `pot_owed`).
+        ['asked_first', 'u64'], ['asked_slot', 'u64'], ['first_asked_at', 'i64'], ['asked_at', 'i64'], ['answer', { array: ['u8', 32] }], ['first', 'u64'],
+        ['pot_total', 'u64'], ['pot_sent', 'u64'], ['pot_arrived', 'u64'], ['pot_owed', 'u64'], ['paid', 'bytes'],
+        ['prizes', { vec: { defined: { name: 'TokenPrize' } } }], ['accounts', { vec: { defined: { name: 'Opened' } } }],
+        // The NFT of the lottery's own stash each place that holds or draws one got, in place order, and how many.
+        ['nfts', { vec: 'pubkey' }], ['assigned', 'u32'],
+      ].map(([name, type]) => ({ name, type })),
+    },
+  },
+  { name: 'ContestEntry', type: { kind: 'struct', fields: [['player', 'pubkey'], ['side', 'u16'], ['amount', 'u64'], ['bits', 'u8'], ['nft', 'pubkey'], ['place', 'u32'], ['taken', 'u32']].map(([name, type]) => ({ name, type })) } },
+];
+const IDLX = { ...IDL, types: [...IDL.types, ...RECORDS], accounts: [...IDL.accounts, { name: 'LotteryRound', discriminator: [TAGS.LotteryRound] }] };
+
+/** A loot account of the named kind (one the IDL describes, or a `LotteryRound`). Throws when the data is not one. */
+export const decode = (name, data) => decodeAccount(IDLX, name, data);
 
 /** Any loot account: { kind, value }, or null for data that is no loot account. */
 export function decodeAny(data) {
   const kind = accountKind(data);
   if (!kind) return null;
-  if (kind === 'Receipt') return { kind, value: decodeReceipt(data) };
+  if (kind === 'Profile') return { kind, value: decodeProfile(data) };
+  if (kind === 'List') return { kind, value: decodeList(data) };
+  if (kind === 'Ends') return { kind, value: decodeEnds(data) };
+  if (kind === 'LotteryRound') return { kind, value: decodeRound(data) };
   if (kind === 'Sheet') return { kind, value: decodeSheet(data) };
+  if (kind === 'Table') return data[37] === PAYLOAD.Nft ? { kind: 'Stash', value: decodeStash(data) } : { kind, value: decodeTable(data) };
   if (kind === 'Proven') return { kind, value: decodeProven(data) };
   if (kind === 'Traits') return { kind, value: decodeTraits(data) };
-  if (kind === 'Stash') return { kind, value: decodeStash(data) };
   return { kind, value: decode(kind, data) };
 }
 
+// ---------------------------------------------------------------- lists of records (M1)
+
 /**
- * A counter (a Receipt): a wallet's on a box, a lottery, a recipe or a grant, a person's or a key's on
- * a grant. { count (lifetime where tracked), window (the window `inWindow` counts), inWindow, rounds (the first 8
- * bytes of sha256 of each round a grant paid it, by voucher or list, in order), claimed(round) }. A round it holds
- * was paid once and can never be paid again.
+ * A list of records (tag 26, `list.rs`): { width, records } in their order: a wallet's counts
+ * (`["counts", project, wallet]`) and a grant's claims are limit records (28 bytes, `readLimit`), a grant's rounds 16
+ * bytes, a contest's entries 43 or 83 (`decodeEntries`).
  */
-export function decodeReceipt(data) {
-  if (!(data instanceof Uint8Array) || data[0] !== TAGS.Receipt || data.length < RECEIPT_BASE_BYTES) throw new Error('Not a Receipt account');
-  const n = Number(readUintLE(data, RECEIPT_BASE_BYTES - 4, 4));
-  if (n > MAX_RECEIPT_ROUNDS) throw new Error('Receipt history exceeds the supported capacity');
-  if (data.length !== RECEIPT_BASE_BYTES + RECEIPT_ROUND_BYTES * n) throw new Error('Receipt length does not match its rounds');
-  const rounds = Array.from({ length: n }, (_, i) => data.slice(RECEIPT_BASE_BYTES + RECEIPT_ROUND_BYTES * i, RECEIPT_BASE_BYTES + RECEIPT_ROUND_BYTES * (i + 1)));
-  if (rounds.some((round, i) => i > 0 && compareBytes(rounds[i - 1], round) >= 0)) throw new Error('Receipt rounds must be unique and sorted');
-  const ids = new Set(rounds.map((r) => toHex(r)));
-  const claimed = (round) => ids.has(toHex(sha256(typeof round === 'string' ? fromHex(round) : Uint8Array.from(round)).subarray(0, 8)));
-  return {
-    count: Number(readUintLE(data, 1, 4)),
-    window: Number(readUintLE(data, 5, 4)),
-    inWindow: Number(readUintLE(data, 9, 4)),
-    rounds,
-    claimed,
-  };
+export function decodeList(data) {
+  if (!(data instanceof Uint8Array) || data[0] !== TAGS.List || data.length < 7) throw new Error('Not a list account');
+  const width = Number(readUintLE(data, 1, 2));
+  const count = Number(readUintLE(data, 3, 4));
+  if (!width || data.length !== 7 + width * count) throw new Error('List account does not match its records');
+  return { width, records: Array.from({ length: count }, (_, i) => data.subarray(7 + width * i, 7 + width * (i + 1))) };
+}
+
+/**
+ * A farm's record of when its seats stop earning (`["ends", farm]`, tag 29; `Farm.keeps_ends`): its times in order, each
+ * `{ at, rewardPerWeight, weight, seats }`: the time (Unix seconds), `reward_per_weight` there once the farm has walked past
+ * it, the weight that stops earning then, and the seats that still need the record.
+ */
+export function decodeEnds(data) {
+  if (!(data instanceof Uint8Array) || data[0] !== TAGS.Ends || data.length < 7) throw new Error('Not a record of ends');
+  const width = Number(readUintLE(data, 1, 2));
+  const count = Number(readUintLE(data, 3, 4));
+  if (width !== END_BYTES || data.length !== 7 + width * count) throw new Error('The record of ends does not match its records');
+  return Array.from({ length: count }, (_, i) => {
+    const at = 7 + width * i;
+    let time = 0n;
+    for (let b = 0; b < 8; b++) time = (time << 8n) | BigInt(data[at + b]);
+    return { at: time, rewardPerWeight: readUintLE(data, at + 8, 16), weight: readUintLE(data, at + 24, 16), seats: Number(readUintLE(data, at + 40, 4)) };
+  });
+}
+
+/** The first 16 bytes of the sha256 of `parts` (addresses, bytes or u64s): a record's key in a list. */
+export const recordKey16 = (...parts) => sha256(concat(...parts.map((p) => (typeof p === 'string' ? addressBytes(p) : p instanceof Uint8Array ? p : uintLE(p, 8))))).subarray(0, 16);
+
+/** The key of a wallet's count for a box, a recipe (incarnation 0) or a lottery (its incarnation), in its counts. */
+export const countKey = (record, incarnation = 0) => recordKey16(record, BigInt(incarnation));
+
+/** What the limit record at `key` counts in a decoded list (`decodeList`, or null for none): { count, window, inWindow }. */
+export function readLimit(list, key) {
+  const record = list?.records.find((r) => compareBytes(r.subarray(0, 16), key) === 0);
+  const n = (i) => (record ? Number(readUintLE(record, 16 + 4 * i, 4)) : 0);
+  return { count: n(0), window: n(1), inWindow: n(2) };
+}
+
+/** A fetched list account, or null for none (or an empty System account someone sent SOL to, which the program opens
+ * as the list). Any other owner or layout is refused. */
+export function readListAccount(account) {
+  if (account == null) return null;
+  if (account.owner === SYSTEM_PROGRAM && account.data instanceof Uint8Array && account.data.length === 0 && !account.executable) return null;
+  if (account.owner !== LOOT_PROGRAM || account.executable) throw new Error('The list has an invalid owner.');
+  return decodeList(account.data);
+}
+
+/**
+ * A contest's entries (`["entries", contest, incarnation, 0]`), in the list's order (by player): [{ player, side,
+ * amount (0 once paid or refunded; 1 while a contest of NFTs holds its NFT), bits (`CLAIMED`, `ENDED`), nft, place (how
+ * many entered its side before it), taken (the losers' NFTs a winner took) }]. A claim names an entry by its index here.
+ */
+export function decodeEntries(data) {
+  const { width, records } = decodeList(data);
+  return records.map((r) => {
+    const full = new Uint8Array(83);
+    full.set(r.subarray(0, Math.min(width, 83)));
+    return decodeBorsh(IDLX, { defined: { name: 'ContestEntry' } }, full)[0];
+  });
+}
+
+/** A winner's first claim came (its prize given or forgone); a winner ended its picks early. */
+export const CLAIMED = 1;
+export const ENDED = 2;
+
+/** How many losers' NFTs a winner of a contest of NFTs takes: the share fixed at the decision, one more for an early
+ * place on its side. */
+export const shareOf = (contest, entry) => Number(contest.share) + (Number(entry.place) < Number(contest.extras) ? 1 : 0);
+
+/** What a count allows `n` more of at `now` under `limit` ({ total, per_window, window }, 0 is no limit; a lottery's
+ * window is its round plus one, given as `window`). */
+export function countAllows(count, limit, now, n = 1, window = Number(limit.window) ? Math.floor(Number(now) / Number(limit.window)) + 1 : 0) {
+  const total = (count?.count ?? 0) + n;
+  const inWindow = (count && count.window === window ? count.inWindow : 0) + n;
+  return (!Number(limit.total) || total <= Number(limit.total)) && (!Number(limit.per_window) || inWindow <= Number(limit.per_window));
 }
 
 /**
@@ -89,11 +195,26 @@ export function decodeReceipt(data) {
 export function decodeSheet(data) {
   if (data == null || data.length === 0) return null;
   if (!(data instanceof Uint8Array) || data[0] !== TAGS.Sheet || data.length < 69) throw new Error('Not a Sheet account');
+  const { attributes, head } = attributesAt(data, 'Sheet');
+  return { project: head(1), nft: head(33), attributes };
+}
+
+/** A player's profile (`["profile", project, wallet]`): { project, wallet, attributes }, what the project keeps about
+ * the wallet (its XP, level, rank). Its layout is a Sheet's, under its own tag. */
+export function decodeProfile(data) {
+  if (data == null || data.length === 0) return null;
+  if (!(data instanceof Uint8Array) || data[0] !== TAGS.Profile || data.length < 69) throw new Error('Not a Profile account');
+  const { attributes, head } = attributesAt(data, 'Profile');
+  return { project: head(1), wallet: head(33), attributes };
+}
+
+/** The attributes after a Sheet's or a profile's two addresses, read with every length checked against the data. */
+function attributesAt(data, name) {
   let at = 65;
   // Every length is checked against the data: a count or a text longer than what is there is a truncated account.
   const text = () => {
     const n = Number(readUintLE(data, at, 4));
-    if (at + 4 + n > data.length) throw new Error('Sheet account is truncated');
+    if (at + 4 + n > data.length) throw new Error(`${name} account is truncated`);
     const value = new TextDecoder().decode(data.subarray(at + 4, at + 4 + n));
     at += 4 + n;
     return value;
@@ -101,19 +222,53 @@ export function decodeSheet(data) {
   const count = Number(readUintLE(data, at, 4));
   at += 4;
   // Each attribute takes 8 bytes at least (two empty texts).
-  if (count * 8 > data.length - at) throw new Error('Sheet account is truncated');
+  if (count * 8 > data.length - at) throw new Error(`${name} account is truncated`);
   const attributes = Array.from({ length: count }, () => ({ key: text(), value: text() }));
-  return { project: encodeBase58(data.subarray(1, 33)), nft: encodeBase58(data.subarray(33, 65)), attributes };
+  return { attributes, end: at, head: (from) => encodeBase58(data.subarray(from, from + 32)) };
+}
+
+/** What a table's rows carry (its payload byte). */
+export const PAYLOAD = Object.freeze({ Number: 0, Label: 1, Nft: 2 });
+const TABLE_HEAD = 51;
+
+/** Where row `r` of a table of `len`-byte rows is: groups of 64 blocks of 64 rows, each led by its weight in stock. */
+export function tableRowAt(len, r) {
+  const block = 8 + 64 * len;
+  const group = 8 + 64 * block;
+  return TABLE_HEAD + Math.floor(r / 4096) * group + 8 + (Math.floor(r / 64) % 64) * block + 8 + (r % 64) * len;
 }
 
-/** A stash (`["stash", project, id]`): { project, id, nfts }, the NFTs the project holds to give away, in no order. */
+/**
+ * A table (`["table", project, id]`, `table.rs`): { project, id, payload ('Number' | 'Label'), sealed, count, total
+ * (the weight in stock), rows: [{ weight, left, label }] }. A row's `left` is `NO_LIMIT` (4294967295) for a stock that
+ * never runs out.
+ */
+export function decodeTable(data) {
+  if (data == null || data.length === 0) return null;
+  if (!(data instanceof Uint8Array) || data[0] !== TAGS.Table || data.length < TABLE_HEAD) throw new Error('Not a Table account');
+  const payload = Object.keys(PAYLOAD).find((k) => PAYLOAD[k] === data[37]);
+  if (!payload || payload === 'Nft') throw new Error('Not a Table account');
+  const count = Number(readUintLE(data, 39, 4));
+  const head = { project: encodeBase58(data.subarray(1, 33)), id: Number(readUintLE(data, 33, 4)), payload, sealed: data[38] === 1, count, total: readUintLE(data, 43, 8) };
+  const len = payload === 'Label' ? 40 : 8;
+  if (count && tableRowAt(len, count - 1) + len > data.length) throw new Error('Table account is truncated');
+  const rows = Array.from({ length: count }, (_, r) => {
+    const at = tableRowAt(len, r);
+    const label = payload === 'Label' ? new TextDecoder().decode(data.subarray(at + 8, at + 40)).replace(/\0+$/, '') : '';
+    return { weight: Number(readUintLE(data, at, 4)), left: Number(readUintLE(data, at + 4, 4)), label };
+  });
+  return { ...head, rows };
+}
+
+/** A stash (`["stash", project, id]`, or a lottery's own): { project, id, nfts, weights }, the NFTs the project holds to
+ * give away and the weight each is drawn by, as a table of NFTs keeps them (a row: its weight, then the NFT). */
 export function decodeStash(data) {
   if (data == null || data.length === 0) return null;
-  if (!(data instanceof Uint8Array) || data[0] !== TAGS.Stash || data.length < 41) throw new Error('Not a Stash account');
-  const count = Number(readUintLE(data, 37, 4));
-  if (41 + 32 * count > data.length) throw new Error('Stash account is truncated');
-  const nfts = Array.from({ length: count }, (_, i) => encodeBase58(data.subarray(41 + 32 * i, 73 + 32 * i)));
-  return { project: encodeBase58(data.subarray(1, 33)), id: Number(readUintLE(data, 33, 4)), nfts };
+  if (!(data instanceof Uint8Array) || data[0] !== TAGS.Table || data[37] !== PAYLOAD.Nft || data.length < TABLE_HEAD) throw new Error('Not a Stash account');
+  const count = Number(readUintLE(data, 39, 4));
+  if (count && tableRowAt(36, count - 1) + 36 > data.length) throw new Error('Stash account is truncated');
+  const rows = Array.from({ length: count }, (_, r) => tableRowAt(36, r));
+  return { project: encodeBase58(data.subarray(1, 33)), id: Number(readUintLE(data, 33, 4)), nfts: rows.map((at) => encodeBase58(data.subarray(at + 4, at + 36))), weights: rows.map((at) => Number(readUintLE(data, at, 4))) };
 }
 
 /**
@@ -180,92 +335,263 @@ export function decodeTokenMetadata(data) {
   return { mint, collection, programmable, ruleSet };
 }
 
-/** A fetched receipt, or null for a missing/prefunded empty System account. Other owners/layouts are refused. */
-export function readReceiptAccount(account) {
-  if (account == null) return null;
-  if (account.owner === SYSTEM_PROGRAM && account.data instanceof Uint8Array && account.data.length === 0 && !account.executable) return null;
-  if (account.owner !== LOOT_PROGRAM || account.executable) throw new Error('The receipt has an invalid owner.');
-  return decodeReceipt(account.data);
-}
+// ---------------------------------------------------------------- a lottery's rounds (M3)
+//
+// A round is a record of its own (`pda.round`), opened by its first purchase: a header with a copy of the terms, the
+// totals, what it still owes and the draw, then one entry a purchase. The ask (`draw_lottery`) fixes its money and moves
+// the lottery on; after the answer, `pull` pays one part at a time, in any order, and the pull that leaves nothing owed
+// closes it.
+
+/** An entry's word: its tickets' end in the low 48 bits, its own part paid in the top bit. */
+const END_BITS = (1n << 48n) - 1n;
+export const OWN_PAID = 1n << 63n;
 
-/** What a counter allows `n` more of at `now` under `limit` ({ total, per_window, window }, 0 is no limit). */
-export function receiptAllows(receipt, limit, now, n = 1) {
-  const window = Number(limit.window) ? Math.floor(Number(now) / Number(limit.window)) + 1 : 0;
-  const count = (receipt?.count ?? 0) + n;
-  const inWindow = (receipt && receipt.window === window ? receipt.inWindow : 0) + n;
-  return (!Number(limit.total) || count <= Number(limit.total)) && (!Number(limit.per_window) || inWindow <= Number(limit.per_window));
+/** The mint a lottery's tickets are paid in (`terms`: a Lottery's or a round's): its ticket mint, burned, or its pot's. */
+export const paymentMint = (terms) => (ticketsBurn(terms) ? terms.ticket_mint : terms.mint);
+/** Whether a lottery's tickets are burned: they are paid in a ticket mint of its own. */
+export const ticketsBurn = (terms) => Boolean(terms.ticket_mint) && terms.ticket_mint !== NO_ADDRESS;
+
+/** A share the buyer chooses (a referrer, a collectible's holder): paid out of the price as they buy, from their own account. */
+export const chosenAtPurchase = (share) => Boolean(share.to?.Chosen);
+
+/** The bytes of one entry of a round: buyer, word, what arrived (`fee`: a fee mint, or a chosen share), the NFT ticket. */
+export const entryWidth = (fee, nft) => 40 + (fee ? 8 : 0) + (nft ? 32 : 0);
+
+/**
+ * A lottery round (`["round", lottery, incarnation, round]`): its header (`status` 'Open' | 'Drawing' | 'Drawn' |
+ * 'Cancelled', the terms it copied, `sold`, `owed`, the draw and the money the ask fixed, `nfts` the NFT of the
+ * lottery's own stash each such place got), and `entries`, one a purchase: { buyer, start, end (its tickets), paid (its
+ * own part's bit), amount (what reached the round), nft (its NFT ticket) }.
+ */
+export function decodeRound(data) {
+  const r = decode('LotteryRound', data);
+  const at = Number(r.head);
+  const width = Number(readUintLE(data, at, 2));
+  const count = Number(readUintLE(data, at + 2, 4));
+  if (width !== entryWidth(r.fee, r.terms.nft_ticket != null) || data.length !== at + 6 + width * count) throw new Error('LotteryRound entries do not match its header');
+  let start = 0n;
+  const entries = Array.from({ length: count }, (_, i) => {
+    const e = data.subarray(at + 6 + width * i, at + 6 + width * (i + 1));
+    const word = readUintLE(e, 32, 8);
+    const end = word & END_BITS;
+    let k = 40;
+    const take = (n) => e.subarray((k += n) - n, k);
+    const amount = r.fee ? readUintLE(take(8), 0, 8) : (end - start) * BigInt(r.terms.price);
+    const entry = { buyer: encodeBase58(e.subarray(0, 32)), start, end, paid: word & ~END_BITS, amount, nft: r.terms.nft_ticket ? encodeBase58(take(32)) : NO_ADDRESS };
+    start = end;
+    return entry;
+  });
+  return { ...r, entries };
 }
 
-// ---------------------------------------------------------------- a lottery's purchases
+/** How many places a lottery's (or a round's) `places` are, every run counted (`Place.times`). */
+export const placeCount = (places) => places.reduce((n, p) => n + Number(p.times ?? 1), 0);
 
-/** The contribution among `contributions` ([{ address, value }], decoded LotteryContributions) that holds `ticket`. */
-export const contributionOf = (contributions, ticket) =>
-  contributions.find(({ value }) => BigInt(value.first_ticket) <= BigInt(ticket) && BigInt(ticket) < BigInt(value.end)) ?? null;
+/** The places of a round that have a winner: every place, but no more than tickets. */
+export const roundWinners = (r) => Math.min(placeCount(r.terms.places), Number(r.sold));
 
-/** Whether a lottery's place wins something: a share of the pot, a roll, or both (as the program counts a place set). */
-export const placeSet = (place) => Number(place.bps) > 0 || place.prize != null;
+/** The ticket that wins `place` of a drawn round: even steps around the list from first place's ticket. */
+export function ticketOfPlace(r, place) {
+  const sold = BigInt(r.sold);
+  const ahead = BigInt(place) * (sold / BigInt(roundWinners(r) || 1));
+  const toEnd = sold - BigInt(r.first);
+  return ahead < toEnd ? BigInt(r.first) + ahead : ahead - toEnd;
+}
 
-/** The places of a lottery that have a winner this round: as many as are set, but no more than tickets. */
-export function lotteryWinners(lottery) {
-  const set = lottery.places.findIndex((p) => !placeSet(p));
-  return Math.min(set === -1 ? lottery.places.length : set, Number(lottery.sold));
+/** The run of places that holds `place`, and its first place. */
+export function runOf(r, place) {
+  let first = 0;
+  for (let run = 0; run < r.terms.places.length; run++) {
+    if (place < first + Number(r.terms.places[run].times)) return [run, first];
+    first += Number(r.terms.places[run].times);
+  }
+  return [r.terms.places.length, first];
 }
 
-/** The ticket that wins `place` of a drawn lottery: even steps around the list from first place's ticket. */
-export function ticketOfPlace(lottery, place) {
-  const sold = BigInt(lottery.sold);
-  const winners = BigInt(lotteryWinners(lottery) || 1);
-  const ahead = BigInt(place) * (sold / winners);
-  const toEnd = sold - BigInt(lottery.first_ticket);
-  return ahead < toEnd ? BigInt(lottery.first_ticket) + ahead : ahead - toEnd;
+/** The places of run `run` with a winner: [first, end). */
+export function runPlaces(r, run) {
+  const first = placeCount(r.terms.places.slice(0, run));
+  const w = roundWinners(r);
+  return [Math.min(first, w), Math.min(first + Number(r.terms.places[run].times), w)];
 }
 
-/** The places of a drawn lottery whose winning ticket is in `first..end` (a contribution's), in order. */
-export function placesWon(lottery, first, end) {
-  const won = [];
-  for (let place = 0; place < lotteryWinners(lottery); place++) {
-    const ticket = ticketOfPlace(lottery, place);
-    if (BigInt(first) <= ticket && ticket < BigInt(end)) won.push(place);
+/** The places of run `run` whose ticket is in `start..end` (an entry's), in order. */
+export function placesIn(r, run, start, end) {
+  const [from, to] = runPlaces(r, run);
+  const out = [];
+  if (from >= to || BigInt(start) >= BigInt(end)) return out;
+  const sold = BigInt(r.sold);
+  const step = sold / BigInt(roundWinners(r));
+  const d = (BigInt(start) + sold - BigInt(r.first)) % sold;
+  const len = BigInt(end) - BigInt(start);
+  for (const [a, b] of [[d, d + len < sold ? d + len : sold], [0n, d + len > sold ? d + len - sold : 0n]]) {
+    let p = Number((a + step - 1n) / step);
+    for (p = Math.max(p, from); p < to && BigInt(p) * step < b; p++) out.push(p);
   }
-  return won;
+  return out.sort((x, y) => x - y);
+}
+
+/** What one place of a pass-through amount takes: `clamp(sent − before, 0, amount) × arrived / sent` (none of nothing sent). */
+const through = (sent, arrived, before, amount) => {
+  if (sent === 0n) return 0n;
+  const part = sent > before ? (sent - before < amount ? sent - before : amount) : 0n;
+  return (part * arrived) / sent;
+};
+
+/**
+ * What place `place` (counted from the first place of `runs`) takes of a pass-through amount, as the program splits it:
+ * runs of `[a, n]` (n places taking `a` each), `sent` what the places are owed and `arrived` what the round holds for
+ * them; the last place with a part takes what the others leave.
+ */
+export function splitPart(runs, sent, arrived, place) {
+  [sent, arrived] = [BigInt(sent), BigInt(arrived)];
+  let [c, at, last, paid, before] = [0n, 0, null, 0n, 0n];
+  for (const [a, n] of runs) {
+    const m = a === 0n ? 0 : Math.min(Number((sent > c ? sent - c + a - 1n : 0n) / a), n);
+    if (m > 0) {
+      const full = through(sent, arrived, 0n, a);
+      [last, before] = [at + m - 1, paid + BigInt(m - 1) * full];
+      paid = before + through(sent, arrived, c + BigInt(m - 1) * a, a);
+    }
+    [c, at] = [c + a * BigInt(n), at + n];
+  }
+  if (last === place) return arrived > before ? arrived - before : 0n;
+  [c, at] = [0n, 0];
+  for (const [a, n] of runs) {
+    if (place < at + n) return through(sent, arrived, c + BigInt(place - at) * a, a);
+    [c, at] = [c + a * BigInt(n), at + n];
+  }
+  return 0n;
 }
 
-/** The places of a drawn round that have a winner and a prize, in order: what it gives before its money moves. */
-export const prizePlaces = (lottery) => [...Array(lotteryWinners(lottery)).keys()].filter((place) => lottery.places[place].prize != null);
+/** A share in basis points of an amount, rounded down. */
+const bpsOf = (amount, bps) => (BigInt(amount) * BigInt(bps)) / 10_000n;
+
+/** Whether place `place`'s part is paid: its pot part's bit (every place's first), or with `prize` its prize's (after
+ * every place's pot bit). */
+export const placePaid = (r, place, prize) => {
+  const at = place + (prize ? placeCount(r.terms.places) : 0);
+  return Boolean((r.paid[at >> 3] ?? 0) & (1 << (at & 7)));
+};
+
+/** Entry `i`'s places in run `run` not paid yet of its pot part or (`prize`) its token prize, lowest first, each with
+ * what it takes: [{ place, amount }]. A pull pays all of them. */
+function unpaidPlaces(r, i, run, prize) {
+  const e = r.entries[i];
+  const k = prize ? r.prizes.findIndex((p) => Number(p.run) === run) : -1;
+  if (prize && k < 0) return [];
+  const runs = k >= 0
+    ? [[BigInt(r.prizes[k].each), runPlaces(r, run)[1] - runPlaces(r, run)[0]]]
+    : r.terms.places.map((p, j) => [bpsOf(r.pot_total, p.bps), runPlaces(r, j)[1] - runPlaces(r, j)[0]]);
+  const [sent, arrived, from] = k >= 0 ? [r.prizes[k].sent, r.prizes[k].arrived, runPlaces(r, run)[0]] : [r.pot_sent, r.pot_arrived, 0];
+  return placesIn(r, run, e.start, e.end).filter((p) => !placePaid(r, p, prize)).map((place) => ({ place, amount: splitPart(runs, sent, arrived, place - from) }));
+}
+
+/** What entry `i`'s places in run `run` take and are not paid yet, of its pot part or (`prize`) its token prize. */
+export const placesOwed = (r, i, run, prize) => unpaidPlaces(r, i, run, prize).reduce((sum, p) => sum + p.amount, 0n);
+
+/** How many of the round's owed parts a pull of `{ Pot: [run] }` or a token `{ Prize: [run] }` for entry `i` settles:
+ * its places there that take more than nothing (one pull pays them all). */
+export const placesPulled = (r, i, run, prize) => unpaidPlaces(r, i, run, prize).filter((p) => p.amount > 0n).length;
 
-/** The places a contribution won whose prize is not given yet (`Lottery.given`): its next step gives them. */
-export function lotteryOwed(lottery, contribution) {
-  if (lottery.status !== 'Drawn') return [];
-  const given = Number(lottery.given ?? 0);
-  const prizes = new Set(prizePlaces(lottery));
-  return placesWon(lottery, contribution.first_ticket, contribution.end).filter((place) => prizes.has(place) && !(given & (1 << place)));
+/** Whether run `run` of a round's places gives tokens (its prize is fixed at the ask, a `TokenPrize`). */
+export const tokenRun = (r, run) => Boolean(r.terms.places[run]?.prize?.Tokens);
+
+/** A place whose prize is an NFT of the lottery's own stash (`Held`, `Raffled`): assigned by the pulls, in place order. */
+export const ownStash = (place) => Boolean(place.prize?.Held) || place.prize === 'Raffled' || place.prize?.Raffled !== undefined;
+
+/** Entry `i`'s places in run `run` whose prize (not tokens) is not given yet, lowest first. */
+export const prizePlacesOwed = (r, i, run) => {
+  const e = r.entries[i];
+  return placesIn(r, run, e.start, e.end).filter((p) => !placePaid(r, p, true));
+};
+
+/** Where in `r.nfts` the NFT of `place` is (a place of a run that holds or draws one of the lottery's own stash). */
+export function nftSlot(r, place) {
+  let [k, first] = [0, 0];
+  for (const p of r.terms.places) {
+    if (place < first + Number(p.times)) return k + place - first;
+    if (ownStash(p)) k += Number(p.times);
+    first += Number(p.times);
+  }
+  return k;
 }
 
-/** Whether every place's prize of a drawn round is given, so its money may move (`PrizesFirst`). */
-export const prizesGiven = (lottery) => prizePlaces(lottery).every((place) => Number(lottery.given ?? 0) & (1 << place));
+/** How many places of a round win an NFT of the lottery's own stash (every such place with a winner). */
+export function stashPlacesWon(r) {
+  const w = roundWinners(r);
+  let [first, won] = [0, 0];
+  for (const p of r.terms.places) {
+    if (ownStash(p)) won += Math.max(0, Math.min(first + Number(p.times), w) - first);
+    first += Number(p.times);
+  }
+  return won;
+}
 
-/** The lowest place of a drawn round whose prize is not given yet, or null: prizes go in place order (`PlacesInOrder`). */
-export const nextPrizePlace = (lottery) => prizePlaces(lottery).find((place) => !(Number(lottery.given ?? 0) & (1 << place))) ?? null;
+/** Whether entry `i`'s places in run `run` (an NFT of the lottery's own stash) wait for their NFTs to be taken out
+ * (`LotteryRound::assign`): a pull with the stash alone does it, and `r.nfts` then names each. */
+export function awaitsNfts(r, i, run) {
+  if (!ownStash(r.terms.places[run])) return false;
+  const places = prizePlacesOwed(r, i, run);
+  return places.some((p) => nftSlot(r, p) >= Number(r.assigned));
+}
 
 /**
- * What a contribution's next `finish_lottery_contribution` does, or null for nothing yet:
- *   'prizes'  give the prize of the next place it won, one place a call (a drawn round gives every prize before any money moves);
- *   'refund'  its tickets back to its buyer (a cancelled round, or a lottery that returns them);
- *   'finish'  its money through the shares into the pot, its tickets burned, or its NFT ticket spent (only once every
- *             prize of the round is given);
- *   'pay'     its places' shares of the pot, once every contribution of the round is finished.
+ * The parts entry `i` of a round is owed now, in the order a keeper pulls them (`pullIx`'s `part`): its own ('Own': a
+ * refund, a no-loss ticket's price, its NFT ticket back or where its price sends it), and with `places`, its places'
+ * parts of the pot ({ Pot: [run] }) and prizes ({ Prize: [run] }). Parts owed in common (a share, the pot's, a pool's
+ * prize back) are no entry's: `commonOwed`.
  */
-export function lotteryStep(lottery, contribution) {
-  // Its prize step comes when the lowest place still owed across the round is one it won; until then it waits.
-  // In a lottery that returns its tickets, a winner's ticket goes back first, then its prizes.
-  const owed = contribution.done || !lottery.returns ? lotteryOwed(lottery, contribution) : [];
-  if (owed.length) return owed[0] === nextPrizePlace(lottery) ? 'prizes' : null;
-  if (contribution.done) return Number(lottery.pending) === 0 ? 'pay' : null;
-  if (lottery.status === 'Cancelled' || (lottery.status === 'Drawn' && lottery.returns)) return 'refund';
-  if (lottery.status === 'Drawn') return prizesGiven(lottery) ? 'finish' : null;
-  return null;
+export function partsOwed(r, i, { places = true } = {}) {
+  const e = r.entries[i];
+  const parts = [];
+  const drawn = r.status === 'Drawn';
+  const back = r.status === 'Cancelled' || (r.terms.returns && drawn);
+  const nft = e.nft !== NO_ADDRESS;
+  if ((e.amount > 0n || nft) && (back || (nft && drawn)) && !(e.paid & OWN_PAID)) parts.push('Own');
+  if (!places || !drawn) return parts;
+  for (let run = 0; run < r.terms.places.length; run++) {
+    const prize = r.terms.places[run].prize;
+    if (placesOwed(r, i, run, false) > 0n) parts.push({ Pot: [run] });
+    if (tokenRun(r, run) ? placesOwed(r, i, run, true) > 0n : prize != null && prizePlacesOwed(r, i, run).length > 0) parts.push({ Prize: [run] });
+  }
+  return parts;
+}
+
+/**
+ * The parts of a round owed in common, of no entry (`{ Common: [i] }`): each share paid in common once drawn (one that
+ * burns is burned at the close), then what the round owes the lottery's pot (`i` = the shares' count), then after a
+ * cancel each pool's token prize back to its pool (past it).
+ */
+export function commonOwed(r) {
+  const n = r.terms.shares.length;
+  const out = [];
+  if (r.status === 'Drawn') r.terms.shares.forEach((s, i) => s.to !== 'Burn' && BigInt(r.common[i] ?? 0) > 0n && out.push({ Common: [i] }));
+  if ((r.status === 'Drawn' || r.status === 'Cancelled') && BigInt(r.pot_owed) > 0n) out.push({ Common: [n] });
+  if (r.status === 'Cancelled') r.prizes.forEach((p, k) => !p.minted && BigInt(p.arrived) > 0n && out.push({ Common: [n + 1 + k] }));
+  return out;
 }
 
+/** The entry of a round holding `ticket`. */
+export const entryOf = (r, ticket) => r.entries.findIndex((e) => e.start <= BigInt(ticket) && BigInt(ticket) < e.end);
+
+/** Whether a round is done and owes nothing: the next pull closes it, given its close's accounts. */
+export const roundFinished = (r) => (r.status === 'Drawn' || r.status === 'Cancelled') && Number(r.owed) === 0;
+
+/** Whether a lottery's place wins something: a share of the pot, a prize, or both. */
+export const placeSet = (place) => Number(place.bps) > 0 || place.prize != null;
+
+/** The address of a lottery's current round's record (there or not). */
+export const roundAddress = (lotteryAddress, lottery) => pda.round(lotteryAddress, lottery.incarnation, lottery.round);
+
+/** Whether a lottery (decoded) drew once and has ended. */
+export const lotteryEnded = (lottery) => Number(lottery.every) === 0 && Number(lottery.round) > 0;
+
+/** The round a lottery's close, its write again and its own stash's moves name (`lottery::check_idle`): its current
+ * round's, or once a lottery that draws once has ended, round 0's (which keeps its stash's NFTs until its places took
+ * them out). */
+export const idleRound = (lotteryAddress, lottery) => pda.round(lotteryAddress, lottery.incarnation, lotteryEnded(lottery) ? 0 : lottery.round);
+
 /**
  * Who rents a listed NFT at `now` (Unix seconds), from its decoded Listing (or null for none): the renter's wallet while
  * a rental runs, else null (a sale listing, or a rental that is over).
@@ -275,10 +601,15 @@ export function renterOf(listing, now) {
   return BigInt(now) < BigInt(listing.until) && listing.user !== SYSTEM_PROGRAM ? listing.user : null;
 }
 
+/** Whether a schedule pays every run due when it is sent late (`schedule::catches_up`): only a sealed fixed amount. */
+export const scheduleCatchesUp = (schedule) => Boolean(schedule.action?.from?.Vest && schedule.action?.amount?.Fixed);
+
 /**
- * How many runs of a schedule are due at `now` (Unix seconds, the chain's clock, never the computer's): each its own
- * `run_schedule`, several in one transaction to catch up; one too many fails the whole transaction. A sealed schedule
- * past its last run is due once whenever its vault holds something (`vaultBalance`), which goes where it always went.
+ * How many runs of a schedule are due at `now` (Unix seconds, the chain's clock, never the computer's). One `run_schedule`
+ * makes them all. A sealed schedule's fixed amount pays each of them (`scheduleCatchesUp`; up to its `upto`, the runs made
+ * after it: `schedule.runs` plus these, and a long backlog takes a few calls). Any other run pays once, for the latest
+ * run due, and those before it lapse. A sealed schedule past its last run is due once whenever its vault holds something
+ * (`vaultBalance`), which goes where it always went.
  */
 export function runsDue(schedule, now, vaultBalance = 0n) {
   const runs = Number(schedule.runs), max = Number(schedule.max_runs);
@@ -312,7 +643,8 @@ export const ERRORS = Object.freeze(Object.fromEntries(IDL.errors.map((e) => [e.
 
 /**
  * The loot error in a failed transaction's logs ("custom program error: 0x…", or Anchor's "Error Code: …" line), or
- * null. Only loot's own: another program the transaction calls (Bubblegum, the VRF program, …) has codes of its own
+ * null: { code, name, msg }, `msg` the IDL's sentence (the program's own log names the error only: its text is
+ * compiled out). Only loot's own: another program the transaction calls (Bubblegum, the VRF program, …) has codes of its own
  * that may be the same numbers, so an error is loot's only when loot is the program that logged it or failed with it.
  * The first program that fails is where the error came from; the programs that called it fail after it with the same
  * code.
@@ -339,7 +671,7 @@ export function lootError(logs) {
     // A line that names no program (a log line, or an error's own text) is the running program's, when it is known.
     if (running.length && running.at(-1) !== LOOT_PROGRAM) continue;
     const named = /Error Code: (\w+)\. Error Number: (\d+)\. Error Message: (.+?)\.?$/.exec(line);
-    if (named) return { code: Number(named[2]), name: named[1], msg: named[3] };
+    if (named) return { code: Number(named[2]), name: named[1], msg: ERRORS[Number(named[2])]?.name === named[1] ? ERRORS[Number(named[2])].msg : named[3] };
     const m = /custom program error: 0x([0-9a-f]+)/i.exec(line);
     if (m && ERRORS[parseInt(m[1], 16)]) return { code: parseInt(m[1], 16), ...ERRORS[parseInt(m[1], 16)] };
   }