@xgamesfun/solana 0.0.0-stage → 0.24.0

package/js/economy/cost.mjs

@@ -0,0 +1,185 @@
+// What an economy costs: going live (each account's rent, the program's fees, network fees, the seeds), and each
+// action while it runs, for whoever signs it. In SOL unless a seed is in another token. Pure.
+//
+// Rent is (bytes + 128) × 5,080 lamports (model.mjs); the loot program's own records are sized byte for byte from
+// their Borsh layout, others (a Core collection, a farm) roughly, and marked so.
+import { boxOrderBytes, plan as compile, contestBytes, farmEnds, roundRentOf } from './plan.mjs';
+import { ACCOUNT_BYTES, CONTEST_ENTRY_BYTES, END_BYTES, entryWidth, LIMIT_RECORD_BYTES, ROUND_RECORD_BYTES } from '../client/index.js';
+import { boxBuys, COLLECTIBLE_RENT, drawsOf, settleUnits, holdsRent, outcomeParts, SETTLE_RENT_UNIT, FEES, LAMPORTS_PER_SOL, ORACLE_FEE, RENT_PER_BYTE, SIGNATURE_FEE, model, lotterySplit, prizeLine, prizeRolls, prizes, prizeWords, rent, toUnits } from './model.mjs';
+import { inAll, round, simulate } from './simulate.mjs';
+
+// The options of a call made without any: read-only, and typed so the generated declarations take any option.
+const NO_OPTIONS = Object.freeze(/** @type {Record<string, any>} */ ({}));
+
+const sol = (lamports) => round(Number(lamports) / Number(LAMPORTS_PER_SOL));
+/** Setup steps that are no loot instruction, and so charge no fee: a token minted, the collection made, SOL put in a
+ * grant's funds. Every other step is the owner or the authority calling loot, which charges the project fee. */
+const NO_FEE_STEP = /^(token:|collection$|fund:|rent:)/;
+/** Setup cost from a plan (plan.mjs `plan`). */
+export function setupCost(plan, economy) {
+  const m = model(economy);
+  // An account that grows (a live stash taking more NFTs) pays rent for its new bytes only.
+  const rentOf = (c) => (c.grows ? BigInt(c.bytes) * RENT_PER_BYTE : rent(c.bytes));
+  const accounts = plan.transactions.flatMap((t) => t.steps).flatMap((s) => s.creates ?? []).map((c) => ({ ...c, lamports: rentOf(c).toString(), sol: sol(rentOf(c)) }));
+  const rentLamports = accounts.reduce((n, a) => n + BigInt(a.lamports), 0n);
+  const charged = plan.transactions.flatMap((t) => t.steps).filter((s) => !NO_FEE_STEP.test(s.id));
+  const feeLamports = BigInt(charged.length) * FEES.project;
+  const networkLamports = plan.transactions.reduce((n, t) => n + BigInt(t.signers.length) * SIGNATURE_FEE, 0n);
+  // Only the seeds and grant funds this plan puts in: a change to a live economy doesn't pay its seeds again.
+  const steps = new Set(plan.transactions.flatMap((t) => t.steps).map((s) => s.id));
+  const seeds = {};
+  let seedLamports = 0n;
+  const funded = m.grants.filter((g) => Number(g.fund ?? 0) > 0 && steps.has(`fund:${g.key}`));
+  for (const g of funded) seedLamports += toUnits(g.fund, 9);
+  // What the owner puts in from their own wallet: a pool's seed, a lottery's seed (into its pot), a farm's seed (into its
+  // rewards vault), a sealed schedule's funds (into its vault, from the wallet).
+  const putIn = (key, amount, step) => {
+    if (!(Number(amount ?? 0) > 0) || !steps.has(step)) return;
+    const t = m.tokens.get(key ?? m.currencyKey);
+    seeds[t.symbol] = round((seeds[t.symbol] ?? 0) + Number(amount));
+    if (t.wsol) seedLamports += toUnits(amount, 9);
+  };
+  for (const p of m.pools) putIn(p.currency, p.seed, `seed:${p.key}`);
+  for (const l of m.lotteries) putIn(l.currency, l.seed, `seed:lottery:${l.key}`);
+  for (const f of m.farms) putIn(f.rewardsToken, f.seed, `seed:farm:${f.key}`);
+  // SOL a lottery holds for its rounds' rent: lent to each round, back at its close.
+  for (const l of m.lotteries) if (steps.has(`rent:lottery:${l.key}`)) seedLamports += roundRentOf(l, m);
+  for (const sc of m.schedules) if (sc.sealed && (sc.fundFrom ?? 'wallet') === 'wallet') putIn(sc.currency, sc.fund, `fund:${sc.key}`);
+  const total = rentLamports + feeLamports + networkLamports + seedLamports;
+  const notes = [];
+  if (accounts.some((a) => a.approx)) notes.push('Accounts marked “about” are sized roughly (a Core collection or an external token account).');
+  if (Object.entries(seeds).some(([symbol]) => [...m.tokens.values()].some((t) => t.wsol && t.symbol === symbol))) notes.push('The total includes the SOL you put in: pools’, lotteries’ and farms’ seeds, and sealed schedules’ funds.');
+  if (m.lotteries.some((l) => steps.has(`rent:lottery:${l.key}`))) notes.push('The total includes the SOL lotteries hold for their rounds’ rent and their tickets’ entries (`roundRent`, sized by default for the rounds and purchases expected at once): each round borrows it and gives it back when it closes; it comes back to you when the lottery closes.');
+  if (funded.length) notes.push('The total includes the SOL put in grants’ funds, which pays their claims; what is left goes back to you when a grant closes.');
+  notes.push('The network fee is 5,000 lamports a signature; a wallet may add a priority fee of its own.');
+  return {
+    accounts,
+    rentSol: sol(rentLamports),
+    programFeesSol: sol(feeLamports),
+    networkFeesSol: sol(networkLamports),
+    seeds,
+    totalSol: sol(total),
+    transactions: plan.transactions.length,
+    approvals: plan.approvals,
+    notes,
+  };
+}
+
+/**
+ * What each action costs whoever signs it while the economy runs: games.fun's fee, the network's, and for anything
+ * that asks MagicBlock's oracle for a random number (a box's open, a lottery's draw, the authority's `roll`) the
+ * oracle's own fee (`oracleSol`, model.mjs ORACLE_FEE).
+ */
+export function actionCosts(economy, { now } = NO_OPTIONS) {
+  const m = model(economy);
+  // A player's real cost of one action, from the simulation (simulate.mjs realCostOf): the number to quote.
+  const sim = simulate(economy, { now });
+  const real = new Map([...sim.items.map((x) => [`item:${x.key}`, x.realCost]), ...sim.boxes.map((x) => [`box:${x.key}`, x.realCost]), ...sim.payments.map((x) => [`payment:${x.key}`, x.realCost]), ...sim.lotteries.map((x) => [`lottery:${x.key}`, x.realCost])]);
+  const rows = [];
+  const row = (part, action, who, fee, deposits = [], extra, oracle = 0n) => {
+    const r = real.get(part);
+    rows.push({ part, action, who, feeSol: sol(fee), ...(oracle ? { oracleSol: sol(oracle) } : {}), networkSol: sol(SIGNATURE_FEE), deposits, ...(extra ? { note: extra } : {}), ...(r ? { inAllSol: r.totalSol ?? null, onTopSol: r.extrasSol, holdSol: r.holdSol, inAll: inAll(r) } : {}) });
+  };
+  const back = (what, lamports, when) => ({ what, sol: sol(lamports), back: when });
+  // An order holds its rent and the fee; the open lends its throwaway settle key what the settle may open or mint (a
+  // collectible's rent for each item the richest outcome gives, each card of a pack), back unspent.
+  const itemsOf = (b) => drawsOf(b) * Math.max(0, ...(b.outcomes ?? []).map((o) => outcomeParts(o).filter((p) => holdsRent(p, m)).length));
+  const order = (b) => [
+    back('the order', rent(boxOrderBytes(b, m, 1, { opened: true })), 'at settle or refund'),
+    ...(settleUnits(b, m) ? [back(`the SOL the open lends the throwaway key that settles it, for what its settle may open (${settleUnits(b, m)} × ${sol(SETTLE_RENT_UNIT)} SOL: each collectible, NFT of a stash, coin it may pay and NFT it rolls on)`, SETTLE_RENT_UNIT * BigInt(settleUnits(b, m)), `once the key has settled, less what it opened (a collectible’s rent is about ${sol(COLLECTIBLE_RENT)} SOL); all of it when the roll fails`)] : []),
+  ];
+  // A box that needs no roll is bought in one step (`buy`): no order, and a collectible's rent is paid at once.
+  const bought = (b) => (itemsOf(b) ? [back(`${itemsOf(b)} new collectible${itemsOf(b) > 1 ? 's' : ''}`, COLLECTIBLE_RENT * BigInt(itemsOf(b)), `never: it is the collectible’s own rent (about ${sol(COLLECTIBLE_RENT)} SOL each)`)] : []);
+  for (const b of m.shop) row(`item:${b.shopOf}`, `buy “${b.name}”`, 'player', FEES.player, bought(b), 'One transaction: the price is split and the item given at once.');
+  for (const b of m.boxes) {
+    if (boxBuys(b, m)) row(`box:${b.key}`, `buy “${b.name}”`, 'player', FEES.player, bought(b), 'One transaction: the price is split and what it gives handed over at once.');
+    else row(`box:${b.key}`, `open “${b.name}”`, 'player', FEES.player, order(b), 'The oracle’s fee is paid by whoever asks for the roll (the player, at the open) and a refund doesn’t return it.', ORACLE_FEE);
+  }
+  for (const p of m.payments) row(`payment:${p.key}`, `pay “${p.name}”`, 'player', FEES.player);
+  for (const r of m.recipes) {
+    const made = (r.out ?? []).filter((l) => l.gives === 'item' && !l.compressed).length;
+    row(`recipe:${r.key}`, `craft “${r.name}”`, 'player', FEES.player, made ? [back(`${made} new collectible${made > 1 ? 's' : ''}`, COLLECTIBLE_RENT * BigInt(made), `never: it is the collectible’s own rent (about ${sol(COLLECTIBLE_RENT)} SOL each)`)] : []);
+  }
+  for (const l of m.lotteries) {
+    // A purchase adds its entry's bytes to the round. In a round the lottery opened, the SOL it holds for its rounds
+    // (`roundRent`, on by default) pays them, back to it at the close: the buyer pays only the fee and the price. Without
+    // it, or once it runs short, the buyer pays them (to the treasury at the close), and a round's first buyer fronts its
+    // header. A share the buyer chooses makes each entry keep what arrived.
+    const chosen = lotterySplit(l).some((s) => String(s.to).startsWith('chosen'));
+    const entry = BigInt(entryWidth(chosen, Boolean(l.ticketNft))) * RENT_PER_BYTE;
+    const held = roundRentOf(l, m);
+    const funded = held > 0n;
+    row(`lottery:${l.key}`, `buy tickets for “${l.name}”`, 'player', FEES.player, funded ? [] : [back('the purchase’s entry in the round (its bytes)', entry, 'never: it goes to the treasury when the round closes')], funded ? `A round’s record, its token accounts and each purchase’s entry are paid from the SOL the lottery holds for them (${sol(held)} SOL), back to it when the round closes: a buyer pays no program rent. When that runs short, a buyer pays their entry’s bytes (about ${sol(entry)} SOL, to the treasury at the close) and a round’s first buyer fronts its header, back to them at the close.` : 'A round’s first buyer also fronts its record’s header and token accounts (about 0.003 SOL and up, more with many places), back to them when the round closes, once every part is pulled; `roundRent` (on by default) has the lottery pay them, and each entry too.');
+  }
+  for (const f of m.farms) {
+    // A seat that can stop earning writes its end in the farm's record: a new time costs whoever writes it, spare rent first.
+    const endRent = BigInt(END_BYTES) * RENT_PER_BYTE;
+    row(`farm:${f.key}`, `stake in “${f.name}”`, 'player', FEES.player, [back('the seat', rent(ACCOUNT_BYTES.Seat), 'when they take everything out'), ...(farmEnds(f) ? [back(`a new end time in the farm’s record of ends (${END_BYTES} bytes; none when another seat ends at that second, or spare rent in the record covers it)`, endRent, 'never: it stays with the record for the next time written')] : [])], farmEnds(f) ? 'Whatever writes a new end time (a stake, a booster put on, a refresh that reads new upkeep) pays its bytes, its sender’s.' : undefined);
+    row(`farm:${f.key}`, `unstake or harvest from “${f.name}”`, 'player', FEES.player, [], [
+      (f.tiers ?? []).some((t) => t.exitFee) && 'Leaving a tier before its lock leaves its exit fee of what is taken out, and keeps the rewards the seat was credited.',
+    ].filter(Boolean).join(' ') || undefined);
+  }
+  for (const h of m.holds) row(`hold:${h.key}`, `hand in for “${h.name}”`, 'player', FEES.player, [back('the hold', rent(ACCOUNT_BYTES.Hold), 'when it is released')]);
+  // What giving a prize opens, paid by whoever sends the instruction that gives it (prize.rs).
+  const opens = (p) => prizeLine(p)?.compressed ? ', and the compressed NFT, which has no rent' : ({ item: ', plus the collectible’s rent', tokens: ', plus the winner’s token account for the prize when they have none', share: ', plus the winner’s token account for the prize when they have none', nft: ', and the NFT is handed over in the claim (a Token Metadata NFT opens the winner’s token account of it)', roll: ', plus the roll’s order (below)' })[prizeLine(p)?.gives] ?? '';
+  for (const g of m.grants) row(`grant:${g.key}`, `claim “${g.name}”`, 'the winner, who signs every claim (anyone may pay its fees)', FEES.player, [], `Only the winning wallet can claim: it signs, whatever proves it won (a voucher, a list, an open grant). Whoever pays the transaction pays the player fee from its own SOL; its records (${LIMIT_RECORD_BYTES} bytes a wallet, ${ROUND_RECORD_BYTES} a round it is paid)${opens(g.prize ?? g.gives)} come from the grant’s funds (the sender pays what they can’t), and go back to the owner when its shards close after the grant: xsolana_simulate gives what to put in its funds per claim.`);
+  // A prize of a collectible given when a place is paid or a winning entry claimed: its rent, from whoever sends it.
+  for (const p of prizes(m).filter((p) => p.prize.gives === 'item' && !p.prize.compressed && !['grant', 'recipe'].includes(p.route)))
+    row(p.by, `give ${prizeWords(p.prize, m)} (${p.route})`, p.route === 'mission' ? 'the player leaving the mission' : p.route === 'contest' ? 'whoever claims the winning entry' : 'whoever pays the place', 0n, [back('the new collectible', COLLECTIBLE_RENT, 'never: it is the collectible’s own rent')]);
+  for (const c of m.contests) {
+    row(`contest:${c.key}`, `back a side in “${c.name}”`, 'player', FEES.player, [back('the entry’s bytes in the contest’s list', BigInt(c.stakeNft ? CONTEST_ENTRY_BYTES.nfts : CONTEST_ENTRY_BYTES.tokens) * RENT_PER_BYTE, 'never: they go to the treasury when the contest closes')], 'A loser of a contest of tokens sends nothing more; every other entry is paid by a claim anyone may send.');
+    row(`contest:${c.key}`, `open “${c.name}”`, 'authority', FEES.project, [back('the contest and its pot', rent(contestBytes(c, m)) + rent(165), 'when it closes')]);
+    row(`contest:${c.key}`, `decide “${c.name}”`, 'authority', FEES.project);
+  }
+  for (const a of m.auctions) {
+    row(`auction:${a.key}`, `bid on “${a.name}”`, 'player', FEES.player, [], 'Nothing to deposit: the bid waits in the game’s vault, and goes back at once when it is topped.');
+    const minted = a.lot?.item && (m.item.get(a.lot.item)?.kind ?? 'collectible') === 'collectible';
+    row(`auction:${a.key}`, `end “${a.name}”`, 'anyone (the winner, a keeper)', 0n, minted ? [back('the new collectible', COLLECTIBLE_RENT, 'never: it is the collectible’s own rent, paid by whoever ends it')] : [], 'Its own rent goes back to whoever opened it.');
+  }
+  for (const s of m.stashes) row(`stash:${s.key}`, `put an NFT in “${s.name}”, or take one out`, 'the owner or the authority', FEES.project, [back('32 bytes more of the stash for each NFT in it', 32n * RENT_PER_BYTE, 'to whoever takes one out; a roll leaves it with the stash, for the next one put in')]);
+  // A prize that is a roll of a box: whoever sends the claim, the payment, the end (or a grant's funds) makes its order.
+  for (const r of prizeRolls(m).filter((r) => !['mission', 'recipe'].includes(r.route))) {
+    const name = m.box.get(r.box)?.name ?? r.box;
+    const who = r.route === 'grant' ? 'the grant’s funds (the sender, what they can’t)' : r.route === 'auction' ? 'whoever ends it' : r.route === 'contest' ? 'whoever claims the winning entry' : 'whoever pays the place';
+    // Whoever settles it pays a collectible's rent when its box gives one (an item outcome).
+    const mints = (m.box.get(r.box)?.outcomes ?? []).flatMap(outcomeParts).some((o) => holdsRent(o, m));
+    row(r.by, `make a winner’s roll of “${name}” (${r.route})`, who, 0n, [back('the roll’s order', rent(boxOrderBytes(m.box.get(r.box), m)), 'to the winner when it is settled')], `Then the winner or the project’s keys ask the oracle for the roll (its fee, below) and settle it${mints ? `, paying the collectible’s rent when it gives one (about ${sol(COLLECTIBLE_RENT)} SOL)` : ''}.`);
+    row(r.by, `ask for the roll of “${name}”`, 'the winner or the project’s keys', 0n, [], 'It asks MagicBlock’s oracle, which takes its fee from whoever asks; a refund doesn’t return it.', ORACLE_FEE);
+  }
+  for (const d of m.decisions) row(`decision:${d.key}`, d.when, 'authority', FEES.project, [], d.does === 'roll' ? 'The roll asks MagicBlock’s oracle, which takes its own fee from the authority.' : undefined, d.does === 'roll' ? ORACLE_FEE : 0n);
+  if (m.allBoxes.some((b) => !boxBuys(b, m))) row('orders', 'settle an order', 'the player, a key they named, or the project’s keys', 0n, [], 'The sender pays what the settle opens or mints (a collectible’s rent, a token account the player lacks); the order’s rent goes back to the player. js/play’s throwaway key sends it with what the open lent it.');
+  if (m.schedules.length) row('schedules', 'run a schedule when it is due', 'the project’s keys, or who it pays (a sealed one’s recipient, from their page)', 0n, [], `A run missed is missed: one sent late pays once, for the latest run due, and the runs before it lapse.${m.schedules.some((sc) => sc.sealed) ? ' A sealed schedule pays from its own vault, and its fixed amount pays every run due, in one transaction.' : ''}`);
+  if (m.lotteries.length) {
+    row('lotteries', 'ask for a draw', 'anyone (a keeper, or a player)', 0n, [], 'The draw asks MagicBlock’s oracle for the winning numbers, and fixes the round’s money first (the next round sells at once); the oracle takes its fee from whoever sends the draw. An oracle that never answers within about a week: the next ask cancels the round, and every ticket is refunded.', ORACLE_FEE);
+    row('lotteries', 'pull a part: a refund, a place’s part of the pot or its prize, a share owed in common', 'anyone (the winner’s page, a keeper)', 0n, [], 'Each part is pulled by itself, in any order, and the pull that leaves nothing owed closes the round; whoever pulls opens the payee’s token account when it is missing.');
+    if (m.lotteries.some((l) => l.minSold)) row('lotteries', 'a short round', 'anyone', 0n, [], 'A round that sold fewer tickets than its least is cancelled at its draw, with no oracle fee, and every ticket refunded.');
+  }
+  return rows;
+}
+
+/** Setup and play costs for a spec, or its refusals. */
+/** `only` and `live`: a change to a live economy, priced as only what it publishes (live.mjs `changedParts`). */
+export function cost(economy, { now = Math.floor(Date.now() / 1000), only = null, live = null } = {}) {
+  const plan = compile(economy, { now, only, live });
+  if (!plan.ok) return plan;
+  return { ok: true, setup: setupCost(plan, economy), actions: actionCosts(economy, { now }), fees: { playerSol: sol(FEES.player), projectSol: sol(FEES.project), oracleSol: sol(ORACLE_FEE) } };
+}
+
+/** The cost in plain words. */
+export function explainCost(c) {
+  const s = c.setup;
+  const lines = [`Going live takes ${s.transactions} transaction${s.transactions === 1 ? '' : 's'} (${s.approvals} wallet approval${s.approvals === 1 ? '' : 's'}) and about ${s.totalSol} SOL:`];
+  lines.push(`  rent ${s.rentSol} SOL for ${s.accounts.length} accounts; program fees ${s.programFeesSol} SOL; network fees ${s.networkFeesSol} SOL${Object.keys(s.seeds).length ? `; seeds ${Object.entries(s.seeds).map(([k, v]) => `${v} ${k}`).join(', ')}` : ''}.`);
+  for (const a of s.accounts) lines.push(`  ${a.approx ? 'about ' : ''}${a.sol} SOL: ${a.what} (${a.bytes} bytes)`);
+  lines.push('While it runs (for a player, quote the “in all” number: it is what leaves their wallet for good):');
+  for (const r of c.actions) {
+    const deposits = r.deposits.map((d) => `${d.sol} SOL for ${d.what} (back: ${d.back})`).join('; ');
+    if (r.inAll) {
+      lines.push(`  ${r.action} (${r.who}): ${r.inAll}${r.note ? `. ${r.note}` : ''}`);
+      continue;
+    }
+    lines.push(`  ${r.action} (${r.who}): ${r.feeSol ? `${r.feeSol} SOL fee + ` : ''}${r.oracleSol ? `${r.oracleSol} SOL to the oracle + ` : ''}${r.networkSol} SOL network${deposits ? `; ${deposits}` : ''}${r.note ? `. ${r.note}` : ''}`);
+  }
+  for (const n of s.notes) lines.push(n);
+  return lines.join('\n');
+}

package/js/economy/examples.mjs

@@ -0,0 +1,114 @@
+// The worked examples (whole specs in examples/ that check, simulate and go live in the tests), the ideas (real
+// economies rated against the current loot, in examples/ideas.json) and what loot can't do exactly (with its nearest
+// versions), searchable by a person's own words. Node only (reads the files).
+import { readdirSync, readFileSync } from 'node:fs';
+import { CANNOT, HOW } from './guide.mjs';
+
+// The options of a call made without any: read-only, and typed so the generated declarations take any option.
+const NO_OPTIONS = Object.freeze(/** @type {Record<string, any>} */ ({}));
+
+const DIR = new URL('../../examples/', import.meta.url);
+const IDEAS = JSON.parse(readFileSync(new URL('ideas.json', DIR), 'utf8')).ideas;
+
+/** Every worked example: { name, spec }. */
+export function examples() {
+  return readdirSync(DIR)
+    .filter((f) => f.endsWith('.json') && f !== 'ideas.json')
+    .sort()
+    .map((f) => ({ name: f.replace(/\.json$/, ''), spec: JSON.parse(readFileSync(new URL(f, DIR), 'utf8')) }));
+}
+
+/** One example's whole spec, by name. */
+export function example(name) {
+  const n = String(name).replace(/\.json$/, '');
+  const found = examples().find((e) => e.name === n);
+  if (!found) throw new Error(`No example called “${name}”. xsolana_examples lists them.`);
+  return found;
+}
+
+export const ideas = () => IDEAS;
+
+const SYNONYMS = {
+  gacha: ['box', 'boxes', 'pull'], loot: ['box', 'boxes'], mystery: ['box', 'boxes'], pack: ['box', 'boxes'], packs: ['box', 'boxes'], roll: ['box', 'boxes'], chest: ['box', 'boxes'],
+  staking: ['farm', 'farms', 'stake'], stake: ['farm', 'farms'], yield: ['farm', 'farms'], earn: ['farm', 'farms'], boost: ['farm', 'farms', 'odds'],
+  raffle: ['lottery', 'lotteries'], lottery: ['lottery', 'lotteries'], draw: ['lottery', 'lotteries'], jackpot: ['lottery', 'lotteries', 'pot'],
+  craft: ['recipe', 'recipes'], crafting: ['recipe', 'recipes'], merge: ['recipe', 'recipes'], upgrade: ['recipe', 'recipes'], breed: ['recipe', 'recipes', 'life'], breeding: ['recipe', 'recipes', 'life'],
+  season: ['schedule', 'schedules'], seasons: ['schedule', 'schedules'], halving: ['schedule', 'schedules'], emission: ['schedule', 'schedules'], emissions: ['schedule', 'schedules'], vesting: ['schedule', 'schedules'],
+  bet: ['contest', 'contests'], betting: ['contest', 'contests'], duel: ['contest', 'contests'], wager: ['contest', 'contests'], prediction: ['contest', 'contests'], fantasy: ['contest', 'contests'],
+  shop: ['item', 'items'], store: ['item', 'items'], nft: ['item', 'items'], nfts: ['item', 'items'], collectible: ['item', 'items'], burn: ['burn'], deflation: ['burn'], deflationary: ['burn'],
+  airdrop: ['grant', 'grants'], reward: ['grant', 'grants'], rewards: ['grant', 'grants'], quest: ['grant', 'grants'], quests: ['grant', 'grants'], giveaway: ['grant', 'grants'], allowlist: ['grant', 'grants'], whitelist: ['grant', 'grants'],
+  gated: ['gate'], gate: ['gate'], 'no-loss': ['no-loss', 'lottery'], lossless: ['no-loss', 'lottery'], launchpad: ['staked', 'gate'], tiers: ['staked'], rank: ['grant', 'grants'], holders: ['gate', 'holder'], pfp: ['gate', 'collection'], 'bring-your-own': ['gate', 'collection'],
+  auction: ['auction', 'auctions', 'bid'], auctions: ['auction', 'auctions', 'bid'], bid: ['auction', 'auctions'], bids: ['auction', 'auctions'], bidding: ['auction', 'auctions'], highest: ['auction', 'auctions'], outbid: ['auction', 'auctions'], english: ['auction', 'auctions'],
+  dutch: ['fall', 'falling', 'drop'], descending: ['fall', 'falling'],
+  referral: ['chosen', 'referred', 'referrer'], referrals: ['chosen', 'referred', 'referrer'], referrer: ['chosen', 'referred'], affiliate: ['chosen', 'referred'], affiliates: ['chosen', 'referred'], refer: ['chosen', 'referred'],
+  rent: ['holder', 'chosen', 'rent'], landlord: ['holder', 'chosen', 'rent'], royalty: ['holder', 'share'], plot: ['chosen', 'holder', 'plot'],
+  crowdfund: ['contest', 'goal', 'minpot'], crowdfunding: ['contest', 'goal', 'minpot'], pledge: ['contest', 'goal', 'minpot'], kickstarter: ['contest', 'goal', 'minpot'],
+  leaderboard: ['decision', 'decisions'], tournament: ['contest', 'decision', 'decisions'], prize: ['pool', 'pools'], flip: ['coin', 'flip', 'box', 'boxes'],
+};
+const words = (s) => String(s ?? '').toLowerCase().match(/[a-z0-9][a-z0-9.+-]*/g) ?? [];
+const STOP = new Set(['a', 'an', 'the', 'and', 'or', 'of', 'to', 'in', 'for', 'with', 'my', 'our', 'that', 'is', 'it', 'on', 'every', 'each', 'make', 'me', 'game', 'i', 'want', 'like', 'build']);
+
+/** The parts a spec uses, and features it shows. */
+export function partsUsed(spec) {
+  const out = ['items', 'pools', 'boxes', 'payments', 'recipes', 'schedules', 'lotteries', 'farms', 'contests', 'auctions', 'holds', 'grants', 'decisions'].filter((k) => Array.isArray(spec?.[k]) && spec[k].length);
+  const all = JSON.stringify(spec ?? {}).replace(/\s/g, '');
+  for (const [f, re] of [['rise', /"rise"/], ['fall', /"fall"/], ['life', /"life"/], ['holder', /holder:/], ['burn', /"burn"/], ['gate', /"gate"/], ['odds', /"odds"/], ['token-2022', /token-2022/], ['staked', /"staked":\{/], ['no-loss', /"noLoss":true/], ['chosen', /"to":"chosen/], ['minpot', /"minPot":/], ['shared-clock', /"clock":"shared"/]]) if (re.test(all)) out.push(f);
+  return out;
+}
+
+function score(text, query, parts = []) {
+  const have = new Set(words(text));
+  const uses = new Set(parts);
+  let s = 0;
+  for (const w of words(query).filter((x) => !STOP.has(x))) {
+    if (have.has(w)) s += 2;
+    else if ([...have].some((h) => h.length > 3 && w.length > 3 && (h.startsWith(w) || w.startsWith(h)))) s += 1;
+    for (const syn of SYNONYMS[w] ?? []) s += (have.has(syn) ? 1 : 0) + (uses.has(syn) ? 2 : 0);
+  }
+  return s;
+}
+
+const FIT_BONUS = { great: 0.5, some: 0.25, 'a-lot': 0, cannot: 0 };
+
+/** Each entry of `list` scored against `query` by its words, the closest first, keeping those that match well enough. */
+function closest(list, query, limit) {
+  const scored = list.map((e) => ({ e, s: score(e.words.replace(/-/g, ' '), query) })).sort((a, b) => b.s - a.s);
+  const best = scored[0]?.s ?? 0;
+  return scored.filter((x) => x.s >= 2 && x.s * 2 >= best).slice(0, limit);
+}
+
+/**
+ * What loot can't do exactly that `query` asks for, with the nearest versions: the closest few. `atLeast`: only limits
+ * that match at least this well (search passes the best matching capability's score: when a capability matches the
+ * words better, its "how" is the answer and a weaker "can't" beside it only misleads; a tie shows both).
+ */
+export function limits(query, { limit = 3, atLeast = 0 } = {}) {
+  return closest(CANNOT, query, limit)
+    .filter((x) => x.s >= atLeast)
+    .map(({ e }) => ({ what: e.what, why: e.why, nearest: e.nearest }));
+}
+
+/** Asks that look impossible but are one field or a short combination, closest to `query`. */
+export function hows(query, { limit = 3 } = {}) {
+  return closest(HOW, query, limit).map(({ e }) => ({ what: e.what, how: e.how }));
+}
+
+/** The examples, ideas, hows and limits closest to `query`. */
+export function search(query, { limit = 6, fit } = NO_OPTIONS) {
+  const ex = examples().map(({ name, spec }) => ({ name, title: spec.name, prompt: spec.prompt, parts: partsUsed(spec) }));
+  const exampleHits = ex
+    .map((e) => ({ e, s: score(`${e.name} ${e.title} ${e.prompt}`, query, e.parts) }))
+    .filter((x) => x.s > 0)
+    .sort((a, b) => b.s - a.s)
+    .slice(0, limit)
+    .map((x) => x.e);
+  const ideaHits = IDEAS.filter((i) => !fit || i.fit === fit)
+    .map((i) => ({ i, s: score(`${i.name} ${i.section} ${i.how}`, query) + FIT_BONUS[i.fit] }))
+    .filter((x) => x.s > 0.5)
+    .sort((a, b) => b.s - a.s)
+    .slice(0, limit)
+    .map(({ i }) => i);
+  // A "can't" shows only when it matches at least as well as the best matching capability.
+  const how = closest(HOW, query, 3);
+  return { examples: exampleHits, ideas: ideaHits, hows: how.map(({ e }) => ({ what: e.what, how: e.how })), limits: limits(query, { atLeast: how[0]?.s ?? 0 }) };
+}

package/js/economy/explain.mjs

@@ -0,0 +1,239 @@
+// The economy in plain words, from the checker, the simulation, the cost and the play-time steps: what players do
+// and what it costs them, how the pools fill and drain, what runs by itself, what the authority must sign, what
+// going live costs, and what the owner must know. Deterministic. Pure.
+import { check, describe } from './check.mjs';
+import { cost } from './cost.mjs';
+import { boostReadsGrowth, boxBuys, farmEndWords, lateRunWords, listOf, lotterySplit, model, outcomeParts, placeOf, prizeLine, prizeRolls, prizes, prizeWords, rollsOf, sharesOf, stashNfts, toSeconds, whenOutWords } from './model.mjs';
+import { farmEnds, playSteps } from './plan.mjs';
+import { inAll, poolFate, round, simulate, unnamedExceptions, unnamedWords } from './simulate.mjs';
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const num = (x) => (Number.isFinite(x) ? String(round(x, 6)) : String(x));
+
+/**
+ * Where a split's shares send the money, and where what they leave goes: to the treasury (`treasury`: how to name it),
+ * or `rest` ("into the pot" for a lottery's ticket money). `payer`: who names a "chosen" share, and what each one is
+ * ("buyer", "sale"; "payer", "payment").
+ */
+function splitWords(split, treasury = 'your treasury', rest = `to ${treasury}`, payer = ['buyer', 'sale']) {
+  const shares = sharesOf(split);
+  if (!shares.length) return `all of it ${rest}`;
+  const left = 100 - shares.reduce((n, s) => n + Number(s.percent), 0);
+  const to = (s) => (s.kind === 'burn' ? 'burned' : s.kind === 'treasury' ? `to ${treasury}` : s.kind === 'pool' ? `to the pool “${s.key}”` : s.kind === 'holder' ? 'to whoever holds that collectible' : s.kind === 'lottery' ? `into the pot of the lottery “${s.key}”` : s.kind === 'wallet' ? `to the wallet ${s.key.slice(0, 4)}…` : s.kind === 'chosen' ? (s.key ? `to whoever holds the “${s.key}” the ${payer[0]} names (each ${payer[1]} its own)` : `to the wallet the ${payer[0]} names (each ${payer[1]} its own: a referrer; with none named, to ${treasury})`) : `to the account ${s.key.slice(0, 4)}…`);
+  return `${shares.map((s) => `${s.percent}% ${to(s)}`).join(', ')}${left > 0 ? `, ${num(left)}% ${rest}` : ''}`;
+}
+
+const ruleWords = (r) => {
+  if (!r) return '';
+  if (r.wallets) return `they are one of the ${r.wallets.length} wallets it names`;
+  const what = r.item ? `a “${r.item}”` : r.collection ? `an NFT of the collection ${r.collection.slice(0, 4)}… (not a Token Metadata print)` : 'one of the game’s collectibles';
+  const time = { ahead: ` whose ${r.attribute} is a time still to come`, passed: ` whose ${r.attribute} is a time past (or none)` }[r.time];
+  return `${what}${r.atLeast !== undefined ? ` with ${r.attribute} at least ${r.atLeast}` : r.equals !== undefined ? ` whose ${r.attribute} is “${r.equals}”` : time ?? (r.attribute ? ` with a ${r.attribute}` : '')}`;
+};
+/** A stake gate in words: "at least 100 of “Staking” staked …", the farm by its name when `m` has it. */
+const stakeWords = (staked, m) => {
+  const f = m?.farm.get(staked.farm);
+  return `at least ${staked.atLeast} ${f ? m.tokens.get(f.stakes)?.symbol ?? f.stakes : ''} staked and locked in “${f?.name ?? staked.farm}” (a stake counts while its lock runs, from the second after it is made)`.replace('  ', ' ');
+};
+/** A gate in a sentence: "Only players who show …", "Only the wallets it names …", "Only wallets with … staked …". */
+const gateWords = (gate, verb, m) => (!gate ? '' : gate.wallets ? `Only the ${gate.wallets.length} wallets it names can ${verb}` : gate.list ? `Only the ${gate.list.length} wallets on its list can ${verb} (each passes their proof)` : gate.staked ? `Only wallets with ${stakeWords(gate.staked, m)} can ${verb}` : `Only players who show ${ruleWords(gate)} can ${verb}`);
+/** When a part sells, and how many one wallet may: "from …, until …; 1 per wallet, 2 a day per wallet". */
+const limitWords = (part) => {
+  const words = [part.opens && `from ${part.opens}`, part.closes && `until ${part.closes}`, part.perWallet && `${part.perWallet} per wallet`, part.perWalletEach && `${part.perWalletEach.count} per wallet every ${part.perWalletEach.every ?? '1d'}`].filter(Boolean);
+  return words.length ? ` ${words.join(', ')}.` : '';
+};
+/** What one outcome of a box that rolls on an NFT does, in words: "+1 level", "the NFT burned", "nothing changes". */
+const fateWords = (o, b, m) => {
+  const then = o.then ?? b.then;
+  const fate = !then || then === 'back' ? null : then === 'burn' ? 'the NFT burned' : then.stash ? `the NFT kept in “${m.stash.get(then.stash)?.name ?? then.stash}”` : 'the NFT given away';
+  const shifts = (o.shifts ?? []).map((x) => `${typeof x.by === 'string' ? x.by : x.by > 0 ? `+${x.by}` : x.by} ${x.attribute}`);
+  // A part as a prize line (`prizeWords`), or a stash's NFT at random.
+  const won = outcomeParts(o).map((x) => (x.gives === 'stash' ? `an NFT of “${m.stash.get(x.stash)?.name ?? x.stash}”` : prizeWords(x.gives === 'pay' ? { gives: 'tokens', amount: x.amount, from: `pool:${x.pool}` } : x.gives === 'mint' ? { gives: 'tokens', amount: x.amount, currency: x.currency, from: 'mint' } : x, m)));
+  const all = [...shifts, ...won, ...(fate ? [fate] : [])];
+  return all.length ? all.join(' and ') : 'nothing changes';
+};
+const effectWords = (e) => (e?.perPointPercent !== undefined ? `+${e.perPointPercent}% per point${e.upTo ? ` (up to ${e.upTo})` : ''}` : `+${e?.addPercent ?? 0}%`);
+
+export function explainEconomy(economy, { now = Math.floor(Date.now() / 1000) } = {}) {
+  const verdict = check(economy, { now });
+  if (!verdict.ok) return { ok: false, refusals: verdict.refusals, warnings: verdict.warnings, text: describe({ refusals: verdict.refusals, warnings: [] }) };
+  const m = model(economy, { now });
+  /** "your treasury", or the other wallet the spec names as the treasury. */
+  const treasuryWords = m.treasuryWallet ? `the treasury (the wallet ${m.treasuryWallet.slice(0, 4)}…${m.treasuryWallet.slice(-4)})` : 'your treasury';
+  const splitOf = (split, payer) => splitWords(split, treasuryWords, undefined, payer);
+  const sim = simulate(economy, { now });
+  const c = cost(economy, { now });
+  const play = playSteps(economy);
+  const sym = (key) => m.tokens.get(key)?.symbol ?? key;
+  const lines = [];
+  const section = (title, rows) => {
+    if (rows.length) lines.push('', title, ...rows.map((r) => `- ${r}`));
+  };
+
+  const ONE = { tokens: 'token', items: 'item', pools: 'pool', stashes: 'stash', boxes: 'box', payments: 'payment', recipes: 'recipe', schedules: 'schedule', lotteries: 'lottery', farms: 'farm', contests: 'contest', auctions: 'auction', holds: 'hold', grants: 'grant', decisions: 'decision' };
+  const counted = Object.keys(ONE).filter((k) => economy[k]?.length).map((k) => plural(economy[k].length, ONE[k], k));
+  lines.push(`${economy.name ?? 'This economy'}: ${counted.join(', ') || 'nothing yet'}. The project’s currency is ${m.currency?.symbol ?? '(none)'}${m.currency ? ` (${m.currency.source === 'sol' ? 'SOL' : m.currency.source === 'game' ? 'a token the project mints' : `an existing ${m.currency.program === 'token-2022' ? 'Token-2022 ' : ''}mint`})` : ''}. It runs on the shared loot program, devnet only: no contract of its own.`);
+  if (economy.prompt) lines.push(`Asked for: “${economy.prompt}”`);
+
+  const fee = num(sim.fees.playerSol);
+  const actions = [];
+  for (const it of sim.items) {
+    const src = m.item.get(it.key);
+    actions.push(`Buy “${it.name}”: ${num(it.price)} ${sym(it.token)}, ${inAll(it.realCost)}${src.supply ? `; ${src.supply} exist` : ''}${src.rise ? '; the price rises after every sale' : ''}${src.fall ? `; the price falls ${src.fall.step} every ${src.fall.every}${src.fall.floor !== undefined ? ` to at least ${src.fall.floor}` : ''}` : ''}${src.soulbound ? '; soulbound' : ''}${src.gate ? `; ${gateWords(src.gate, 'buy it', m).replace(/^Only/, 'only')}` : ''}. The money: ${splitOf(src.split)}.`);
+  }
+  for (const b of sim.boxes) {
+    const src = m.box.get(b.key);
+    const edge = b.houseEdgePercent !== null ? `; the house keeps ${num(b.houseEdgePercent)}%` : b.unpriced.length ? `, plus what ${b.unpriced.join(', ')} ${b.unpriced.length === 1 ? 'is' : 'are'} worth` : '';
+    const back = b.returnPercent !== null ? `gives back ${num(b.expectedBack)} ${sym(b.token)} on average (${num(b.returnPercent)}% of its price${edge})` : 'gives back what its items are worth to the player';
+    const part = (o) => (o.gives === 'pay' ? `${num(o.amount)} ${sym(o.token)} from “${o.pool}”` : o.gives === 'mint' ? `${num(o.amount)} ${sym(o.token)}, minted` : o.gives === 'stash' ? `an NFT of “${m.stash.get(o.stash)?.name ?? o.stash}”, picked at random` : o.gives === 'nft' ? `the NFT ${String(o.nft).slice(0, 4)}… of “${m.stash.get(o.stash)?.name ?? o.stash}”` : o.gives === 'roll' ? `a roll of “${m.box.get(o.box)?.name ?? o.box}”` : o.gives === 'item' ? `${o.item}` : o.gives === 'burn' ? 'burned' : 'nothing');
+    const outs = b.outcomes.map((o) => `${num(o.chance)}% ${o.gives === 'bundle' ? o.prizes.map(part).join(' + ') : part(o)}`).join(', ');
+    const odds = (src.odds ?? []).map((o) => `outcome ${o.outcome} ${effectWords(o.add)} for a player who shows ${ruleWords(o.when)}`);
+    // A roll on an NFT: what each outcome does to it.
+    const fates = (src.outcomes ?? []).flatMap((o, i) => {
+      const moves = (o.shifts ?? []).map((x) => (x.fromNow ? `${x.attribute} ${String(x.by).startsWith('-') ? `${String(x.by).slice(1)} sooner` : `${x.by} later, counted from now when it is past`}${x.upTo ? `, at most ${x.upTo} from now` : ''}` : `${x.by > 0 ? '+' : ''}${x.by} ${x.attribute}`));
+      const then = o.then ?? src.then;
+      const where = then === 'burn' ? 'it is burned' : then === 'treasury' ? 'it goes to the treasury' : then?.giveTo ? `it goes to ${then.giveTo.slice(0, 4)}…` : then?.stash ? `it goes into the stash “${m.stash.get(then.stash)?.name ?? then.stash}”` : '';
+      const said = [...moves, where].filter(Boolean).join(' and ');
+      return said ? [`outcome ${i}: ${said}`] : [];
+    });
+    const custodial = (src.outcomes ?? []).some((o) => (o.then ?? src.then) && (o.then ?? src.then) !== 'back');
+    const rolls = src.rollsOn
+      ? ` It rolls on ${src.active === false ? 'the NFT' : 'an NFT the player brings'} (${ruleWords(src.rollsOn)})${fates.length ? `: ${fates.join('; ')}` : ''}${custodial ? '; the project holds that NFT from the purchase until it is settled, so nobody can move it away from a bad roll' : '; the NFT stays in its wallet, and the numbers follow it wherever it goes'}.`
+      : '';
+    const named = { grant: 'the grant', contest: 'the contest', auction: 'the auction', mission: 'the mission', recipe: 'the recipe', box: 'the box' };
+    const by = [...new Set(rollsOf(m).filter((r) => r.box === src.key && !r.through).map((r) => {
+      const [kind, key] = r.by.split(':');
+      const part = { grant: m.grant, lottery: m.lottery, contest: m.contest, auction: m.auction, farm: m.farm, recipe: m.recipe, box: m.box }[kind]?.get(key);
+      return kind === 'lottery' ? `${r.route} of the lottery “${part?.name ?? key}”` : `${named[r.route] ?? kind} “${part?.name ?? key}”`;
+    }))];
+    if (src.active === false && (src.rollsOn || by.length)) {
+      actions.push(`“${b.name}” is never sold: ${by.join(' and ') || 'nothing'} rolls it. Odds: ${outs}${odds.length ? `; ${odds.join('; ')}` : ''}.${rolls} The winner or the project’s keys ask the oracle for a roll, and settle it (the oracle's fee is the asker's). A roll that holds no payment is never refunded and never lost: an edit of the box leaves it to roll on the box as it is then; one holding a payment or an NFT that the oracle leaves unanswered for 7 days can be refunded. ${whenOutWords(src, { sold: false })}.`);
+      continue;
+    }
+    const verb = boxBuys(src, m) ? 'Buy' : 'Open';
+    const oneStep = boxBuys(src, m) ? ' It sells in one step: the price is split and what it gives handed over in the same transaction.' : '';
+    actions.push(`${verb} “${b.name}”: ${num(b.price)} ${sym(b.token)}, ${inAll(b.realCost)}; ${back}. ${boxBuys(src, m) ? 'It gives' : 'Odds'}: ${outs}${odds.length ? `; ${odds.join('; ')}` : ''}${src.gate ? `. ${gateWords(src.gate, 'open it', m)}` : ''}.${rolls} The money: ${splitOf(src.split)}.${limitWords(src)}${src.outcomes.flatMap(outcomeParts).some((o) => o.gives === 'pay') ? (boxBuys(src, m) ? ' It sells only while its pools hold every fixed prize.' : ' A prize won is set aside for its winner at once.') : ''}${b.limitedStock ? ` ${whenOutWords(src)}.` : ''}${!boxBuys(src, m) ? ' An edit of the box’s roll fails a purchase still waiting, for its refund.' : ''}${oneStep}`);
+  }
+  for (const p of sim.payments) actions.push(`Pay “${p.name}”: ${p.atLeast ? `whatever the player chooses, at least ${num(p.amount)} ${sym(p.token)} (the page keeps the least; the chain takes any amount)` : `${num(p.amount)} ${sym(p.token)}`}, ${inAll(p.realCost)}. The money: ${splitOf(m.payments.find((x) => x.key === p.key)?.split, ['payer', 'payment'])}.`);
+  for (const r of sim.recipes) actions.push(`Craft “${r.name}”: ${r.takes.join(' + ') || 'nothing'} → ${r.gives.join(' + ') || 'nothing'} (+ ${fee} SOL player fee).`);
+  for (const l of sim.lotteries) {
+    const src = m.lottery.get(l.key);
+    // Its split (and its cut, a share to the treasury) takes its shares, and the rest goes into the pot.
+    const others = (src.split ?? []).length ? `; ticket money goes ${splitWords(lotterySplit(src), treasuryWords, 'into the pot')}` : '';
+    if (src.ticketNft) {
+      const goes = src.noLoss ? 'held until the round is drawn, then goes back to its buyer (no loss)' : `${!src.ticketNft.then || src.ticketNft.then === 'burn' ? 'burned' : src.ticketNft.then.stash ? `put in the stash “${src.ticketNft.then.stash}”` : 'given on'} once the round is drawn (back to its buyer only if the draw is cancelled)`;
+      actions.push(`Buy a ticket for “${l.name}” with one NFT that is ${ruleWords(src.ticketNft.rule)} (+ ${fee} SOL player fee): it is ${goes}. ${l.drawsOnce ? 'Drawn once, then it ends' : `Drawn every ${num(l.roundDays)} days`}; the pot is what the owner seeds and what its places give.${src.gate ? ` ${gateWords(src.gate, 'buy tickets', m)}.` : ''}`);
+      continue;
+    }
+    actions.push(`Buy tickets for “${l.name}”: ${num(l.price)} ${sym(l.token)} a ticket; one ticket bought alone is ${inAll(l.realCost)}, and the fee is per purchase, so several tickets at once share it. ${l.drawsOnce ? 'Drawn once, then it ends' : `Drawn every ${num(l.roundDays)} days`}; the pot (an account of its own, which only its winners are paid from) reaches about ${num(l.potBeforeDraw)} ${sym(l.potToken)} and pays ${l.prizes.map(num).join(' / ')}; ${src.noLoss ? `no loss: every ticket comes back to its buyer once the round is drawn (anyone can pull it), and the winners take only the pot, what is paid into it, so a ticket wins ${num(l.expectedPerTicket)} on average on top of its price coming back (tickets are not weighted by time: someone may buy most of them right before the draw and risk only the fees)` : `a ticket is worth ${num(l.expectedPerTicket)} on average${l.unpricedPrizes ? ', plus its chance at the places’ prizes' : ''}${l.returnPercent !== null ? ` (${num(l.returnPercent)}%)` : ''}`}${l.cutPercent && !(src.split ?? []).length ? `; ${num(l.cutPercent)}% of ticket money goes to ${treasuryWords}, the rest into the pot` : ''}${others}${src.perWallet ? `; at most ${src.perWallet} tickets per wallet a round` : ''}.${src.gate ? ` ${gateWords(src.gate, 'buy tickets', m)}.` : ''}`);
+  }
+  for (const f of sim.farms) {
+    const src = m.farm.get(f.key);
+    const tiers = f.tiers.map((t) => `x${t.multiplier} for ${t.lock}`).join(', ');
+    const boosts = (src.boosts ?? []).map((b) => `${effectWords(b.add)} for ${ruleWords(b.when)}`);
+    const custody = src.stakes !== 'collectibles' && !boosts.length ? '' : {
+      freeze: ' NFTs stay locked in the wallet (a Core freeze, Token Metadata’s lock, a compressed NFT’s freeze); issuer metadata growth can prevent Core from unfreezing ordinary assets.',
+      watch: ' NFTs stay free in the wallet: one sold while staked stops earning for its staker, and its new holder can take the seat over.',
+    }[src.custody] ?? ' NFTs are handed to the game until they leave; issuer-controlled transfer rules can still prevent return.';
+    const earns = f.rate && !(Number(f.rate.perDay) > 0)
+      ? 'no tokens'
+      : f.rate
+      ? `${num(f.rate.perDay)} ${sym(f.rewardsToken)} a day ${f.rate.shared ? 'for the whole farm, shared by weight while anything is staked' : `for each ${f.unit ?? (src.stakes === 'collectibles' ? 'collectible' : sym(src.stakes))} at x1, whoever else is in`}${f.rate.halveEvery ? `, halving every ${f.rate.halveEvery}` : ''} (${f.rate.minted ? 'minted when a seat is paid while the mint has room for it, never owed later past that' : 'from its rewards vault while it lasts'}); what a seat gives back (a forfeit, a watched NFT sold) is ${f.rate.minted ? 'never minted' : 'left free in its vault'}, never to the other seats`
+      : `${num(f.rewardsPerDay)} ${sym(f.rewardsToken)} a day, what lands in its rewards vault, shared by weight${f.perUnitPerDay !== undefined ? ` (${num(f.perUnitPerDay)} a day for each ${f.unit} at x1${f.yearlyPercent !== undefined ? `, ${num(f.yearlyPercent)}% a year` : ''})` : ''}`;
+    const grows = (f.growth ?? []).map((g) => `; staying in earns ${g.perDay} ${g.attribute} a day at x1, written on the collectible${g.levels ? ` with its ${g.level} (${g.levels.map((l) => `${l.level} after ${num(l.days)} days`).join(', ')})` : ''}${g.streak ? ', back to 0 when it leaves' : ', kept when it leaves'}`).join('');
+    const gates = listOf(src.gate);
+    const takes = gates.length ? `; to stake here an NFT must be ${gates.map(ruleWords).join(' and ')}` : '';
+    const end = farmEndWords(src);
+    const runs = src.runs ? `; it runs ${src.runs} from when it goes live, taking no stake at its end or after it, nor one that could not leave by then, and pays and grows nothing after${end ? `; ${end}` : ''}` : '';
+    const lock = src.lockAttribute ? `; each collectible’s lock is written on it under “${src.lockAttribute}” (the time it ends) and it leaves once that time has come, so a recipe or a roll that moves “${src.lockAttribute}” lets it out sooner or keeps it longer (a mission’s prize still needs the tier’s own lock)` : '';
+    const upkeep = src.upkeepAttribute ? `; a collectible earns and grows only until the time under its “${src.upkeepAttribute}” (its upkeep): run dry, it earns nothing more from that time until it is topped up and its seat refreshed` : '';
+    // A farm that keeps its record of ends: what a seat earned by its end is exact, and each new end time has a rent.
+    const ends = farmEnds(src) ? `; what a seat earned by its end (${(src.tiers ?? []).some((t) => t.earnsFor) ? 'its tier’s term' : 'its upkeep'}) is exact however late it is next touched, and nobody has to act at that time: the farm keeps a record of those times, each new one costing whoever writes it 44 bytes of rent (about 0.00022 SOL; spare rent in the record pays first), not refunded on leaving. A farm idle past many ends has them walked in parts first (\`app.walkFarm\`, free and anyone’s)` : '';
+    // A boost that reads a level its own growth writes counts each level from when it is written.
+    const refreshes = boostReadsGrowth(src) ? '; a boost that reads what its own growth writes counts each level from when it is written, by a seat’s refresh, so a seat refreshed often earns more than one refreshed rarely: have the page or a keeper refresh seats (anyone may, for free)' : '';
+    const missions = f.tiers.filter((t) => t.prize).map((t) => `${t.prize} for staying ${t.lock}`);
+    const results = (src.tiers ?? []).filter((t) => t.roll).map((t) => {
+      const box = m.box.get(t.roll);
+      const fates = box ? [...new Set((box.outcomes ?? []).map((o) => fateWords(o, box, m)))] : [];
+      return `leaving after ${t.lock}, the NFT is rolled on “${box?.name ?? t.roll}”${fates.length ? ` (its result: ${fates.length > 1 ? `${fates.slice(0, -1).join('; ')}; or ${fates.at(-1)}` : fates[0]})` : ''}`;
+    });
+    actions.push(`Stake ${src.stakes === 'collectibles' ? `collectibles${src.item ? ` (${src.item})` : ''}` : sym(src.stakes)} in “${f.name}”: ${earns}${grows}${takes}${runs}${lock}${upkeep}${ends}${refreshes}${missions.length ? `; a mission that stays its lock (topped up, not forfeited) brings back ${missions.join(', ')}, given as it leaves (a roll is settled after)` : ''}${results.length ? `; ${results.join('; ')}` : ''}; lock tiers ${tiers}${boosts.length ? `; boosts ${boosts.join(', ')}, at most +${src.maxBoostPercent ?? 0}%` : ''}. After the lock, pause and suspend cannot stop an unstake; external token or NFT controls can still block custody release.${custody}`);
+  }
+  for (const t of m.traits) actions.push(`Prove an NFT’s traits (anyone, once for each NFT, paying its Sheet’s small rent): what the off-chain metadata of the NFTs of ${t.collection.slice(0, 4)}… says, from the root the game vouched for, goes in the NFT’s Sheet, where boosts, gates and odds read it.${t.about ? ` ${t.about}` : ''}`);
+  for (const ct of sim.contests) {
+    const src = m.contest.get(ct.key);
+    const roll = prizeLine(src?.prize) ? ` Each winning entry also gets ${prizeWords(src.prize, m)} when it is claimed${prizeLine(src.prize).gives === 'roll' ? '' : ', in the same transaction'}.` : '';
+    if (src.stakeNft) {
+      actions.push(`Back a side in “${ct.name}” with one NFT that is ${ruleWords(src.stakeNft)} (+ ${fee} SOL player fee): the NFTs are the pot. The authority names the side that won; each winning entry takes its own NFT back and one loser’s, in the order the entries are claimed, and what the winners leave goes to whoever opened it. Called off, or not decided by its deadline, every entry takes its own back.${roll}`);
+      continue;
+    }
+    actions.push(`Back a side in “${ct.name}” (+ ${fee} SOL player fee): ${ct.says}; the authority names the side that won, and a contest not decided by its deadline pays everyone back.${roll}`);
+  }
+  for (const a of sim.auctions ?? []) {
+    const src = m.auction.get(a.key);
+    const lot = src.lot?.item ? `one new “${m.item.get(src.lot.item)?.name ?? src.lot.item}”` : src.lot?.roll ? `a roll of “${m.box.get(src.lot.roll)?.name ?? src.lot.roll}” for the winner (a mystery lot: what it gives is chance, and the price goes to ${treasuryWords})` : `the NFT ${src.lot?.asset?.slice(0, 4)}…`;
+    if (src.bidNfts) {
+      actions.push(`Bid on “${a.name}”, which sells ${lot}, with bundles of up to three Core or Token Metadata NFTs that are ${ruleWords(src.bidNfts)} (+ ${fee} SOL player fee a bid): the bundle with the most wins (at least ${src.reserve ?? 1}); a bundle that is topped goes back to its bidder at once, and the winning NFTs go to ${src.lot?.asset ? 'the seller' : treasuryWords}. It runs ${src.runs}.${src.gate ? ` ${gateWords(src.gate, 'bid', m)}.` : ''}`);
+      continue;
+    }
+    actions.push(`Bid on “${a.name}”, which sells ${lot}: bids in ${sym(a.token)}${a.reserve ? ` from ${num(a.reserve)}` : ''}, each topping the last by at least ${src.minRaise ?? 5}% (+ ${fee} SOL player fee a bid); a bid that is topped goes back to its bidder at once. It runs ${src.runs}${toSeconds(src.extendBy ?? '10m') > 0 ? `, and a bid in the last ${src.extendBy ?? '10m'} moves the end to ${src.extendBy ?? '10m'} after it` : ''}; anyone ends it then, the lot goes to the highest bidder and the money: ${splitOf(src.split)}.${src.lot?.asset ? ' A seller whose account can’t take the money then doesn’t hold up the winner: the lot goes, the auction stays open owing it, and the next end pays and closes it.' : ''} With no bid the lot goes home; an auction nobody ends waits, and sells to the highest bidder whenever anyone ends it.${src.gate ? ` ${gateWords(src.gate, 'bid', m)}.` : ''}`);
+  }
+  for (const h of m.holds) actions.push(`Hand in a ${h.item} for “${h.name}”${h.until ? ` until ${h.until}` : h.for ? ` for ${h.for}` : ''}: the authority says where it goes; after the time is up anyone can send it home.`);
+  if (m.payments.length || m.boxes.length) actions.push('Pay with an NFT, outside the spec (`loot.payNftIx`): any NFT a player holds, burned or given to a wallet; the app admits them by the receipt, as for a payment.');
+  for (const g of sim.grants) {
+    const src = m.grant.get(g.key);
+    const l = src.limits ?? {};
+    const limits = [l.perWallet && `${l.perWallet} per wallet`, l.perWalletEach && `${l.perWalletEach.count} per wallet every ${l.perWalletEach.every ?? '1d'}`, l.perPerson && `${l.perPerson} per person`, l.perKey && `${l.perKey} per key`, l.perDay && `${l.perDay} a day`, l.total && `${l.total} in all`].filter(Boolean).join(', ');
+    const signers = [(src.vouchers ?? []).length && 'a voucher key says earned it', (src.keys ?? []).length && `one of its ${src.keys.length} keys (codes) signed for`, (src.list ?? []).length && `on the list of ${src.list.length}`].filter(Boolean);
+    const who = signers.length ? signers.join(' or ') : 'that asks (it is open to any wallet)';
+    // A grant of a fixed amount of tokens, paid by voucher or list: each claim may name its own amount, up to the grant's.
+    const named = signers.length > 0 && src.prize?.gives === 'tokens';
+    actions.push(`Claim “${g.name}” (only the winning wallet claims, signing it; anyone may pay its fees): gives ${g.gives}, to a wallet ${who}${limits ? `; limits ${limits}` : '; no limits'}${src.gate ? (src.gate.wallets ? `; only the ${src.gate.wallets.length} wallets it names` : src.gate.list || src.gate.staked ? `; ${gateWords(src.gate, 'claim it', m).replace(/^Only/, 'only')}` : `; the wallet must hold ${ruleWords(src.gate)}${!signers.length ? ', and each one of those claims once too' : ''}`) : ''}${named ? `; a voucher or the list can name each claim’s own amount, up to that (a reward by rank or share)` : ''}. Each claim costs the grant’s funds about ${num(g.fundsPerClaimSol)} SOL of rent, and whoever sends it the ${fee} SOL player fee.`);
+  }
+  for (const st of sim.stashes ?? []) {
+    const src = m.stash.get(st.key);
+    const nfts = stashNfts(src);
+    const boxes = m.boxes.filter((b) => (b.outcomes ?? []).flatMap(outcomeParts).some((o) => o.gives === 'stash' && o.stash === st.key)).map((b) => `“${b.name}”`);
+    const direct = prizes(m).filter((p) => p.prize.gives === 'nft' && p.prize.stash === st.key).map((p) => `${p.by} (${prizeWords(p.prize, m)}, given at once)`);
+    actions.push(`The stash “${st.name}” holds ${plural(nfts.length, 'NFT')} the game gives away${boxes.length ? ` through ${boxes.join(', ')}` : ''}${direct.length ? `${boxes.length ? ' and' : ' through'} ${direct.join(', ')}` : ''}, put in by your wallet when it goes live${st.takenInPerDay ? ` and by what players pay with an NFT (about ${num(st.takenInPerDay)} a day in the scenario)` : ''}: a roll that lands on it picks one at random and takes it out at once, so two winners never get the same one, and the roll is then settled to hand it over; a prize that names an NFT hands it over in the instruction that wins it. Empty, a roll that lands on it makes no draw, and gives back that draw’s worth. Your wallet (or the authority) can put more in, or take one out, any time.${st.lastsDays !== undefined ? ` At the scenario’s rate it lasts about ${num(st.lastsDays)} days.` : ''}`);
+  }
+  // Prizes that are a roll of a box: made for the winner, then asked of the oracle and settled by the winner or the project’s keys.
+  const prized = prizeRolls(m).filter((r) => !['mission', 'recipe'].includes(r.route));
+  if (prized.length)
+    actions.push(`Prizes that are a roll of a box (${[...new Set(prized.map((r) => `${r.by} → “${m.box.get(r.box)?.name ?? r.box}”`))].join(', ')}): the winner gets an order of that box, made by whoever sends the claim, the place’s payment or the auction’s end (its rent, back to the winner when it is settled); the winner or the project’s keys then ask the oracle for the roll (its fee is the asker’s) and settle it. A roll that holds no payment is never refunded and never lost: it rolls on the box as it is when it is asked.`);
+  for (const l of m.lotteries) {
+    const rolls = (l.places ?? []).map(placeOf).map((p, i) => (p.prize ? `${p.times > 1 ? `${p.times} places from place ${i + 1} each win` : `place ${i + 1} wins`} ${prizeWords(p.prize, m)}${p.percent ? ` and ${p.percent}% of the pot` : ''}` : null)).filter(Boolean);
+    if (rolls.length) actions.push(`In “${l.name}”, ${rolls.join('; ')}.`);
+  }
+  section('What players do, what it costs and what it is worth', actions);
+
+  section('How the pools fill and drain', sim.pools.map((p) => {
+    const by = (rows) => rows.map((r) => (r.percentPerDay !== undefined ? `${r.by} ${num(r.percentPerDay)}% of what it holds a day` : `${r.by} ${num(r.perDay)} a day`)).join(', ') || 'nothing';
+    return `${p.pot ? `The pot of “${p.pot}”` : `“${p.key}”`} (${sym(p.token)}): starts at ${num(p.seed)}; in: ${by(p.ins)}; out: ${by(p.outs)}; it ${poolFate(p, sim.scenario.days)}.`;
+  }));
+  section('What runs on a timer', [...sim.schedules.map((s) => { const sc = m.schedules.find((x) => x.key === s.key); return `“${sc?.name ?? s.key}” ${s.says}; ${sc?.sealed ? 'its recipient runs it when it is due' : 'you, or a key of the project’s on your server, must send each run when it is due: nothing runs it otherwise'}; ${lateRunWords(sc ?? {})}.`; }), ...sim.lotteries.map((l) => `“${l.name}” is drawn ${l.drawsOnce ? 'once' : `every ${num(l.roundDays)} days`} by MagicBlock’s oracle; anyone can ask for the draw (${num(sim.fees.oracleSol)} SOL to the oracle), move the drawn round on and pull what each entry is owed.`)]);
+  const authority = play.filter((s) => s.signer.startsWith('authority'));
+  section(`What only the authority signs while it runs (${m.authority === 'owner' ? 'your wallet' : `the key ${m.authority}`})`, authority.map((s) => `${s.says} (${s.part}, ${s.ix}).`));
+  if (authority.length) lines.push('- Checking that a player really did what a payout is for is up to you, on your own server: a game runs in the player’s browser, and the program trusts the authority’s signature.');
+
+  const s = c.setup;
+  lines.push('', 'What setting it up costs');
+  lines.push(`- About ${num(s.totalSol)} SOL in all, in ${plural(s.transactions, 'transaction')} (${plural(s.approvals, 'wallet approval')}): rent ${num(s.rentSol)} SOL for ${plural(s.accounts.length, 'account')}, program fees ${num(s.programFeesSol)} SOL, network fees ${num(s.networkFeesSol)} SOL${Object.keys(s.seeds).length ? `, seeds ${Object.entries(s.seeds).map(([k, v]) => `${num(v)} ${k}`).join(', ')}` : ''}.`);
+  for (const n of s.notes) lines.push(`- ${n}`);
+
+  const d = sim.perDay;
+  const list = (map) => Object.entries(map).map(([k, v]) => `${num(v)} ${sym(k)}`).join(', ') || 'nothing';
+  const named = Object.entries(sim.scenario.perDay).map(([k, v]) => `${v} × ${k}`).join(', ');
+  const except = unnamedExceptions(sim);
+  lines.push('', `Each day, if ${named ? `${named} happen (anything else: ${unnamedWords(sim)})` : `${sim.scenario.defaultPerDay} of each thing happen${except.length ? ` (${except.join(', ')})` : ''}`}`);
+  lines.push(`- Players pay ${list(d.players.pay)} and get back ${list(d.players.getBack)} on average, plus ${num(d.players.playerFeesSol)} SOL in player fees${d.players.oracleFeesSol ? ` and ${num(d.players.oracleFeesSol)} SOL to MagicBlock’s oracle` : ''}.`);
+  lines.push(`- Your treasury gets ${list(d.creator.treasury)}; burned: ${list(d.burned)}; the platform’s fees: ${num(d.platform.totalSol)} SOL.`);
+  for (const n of sim.notes) lines.push(`- ${n}`);
+
+  const flagged = verdict.warnings.filter((w) => w.code === 'W-CHANCE-PRIZE' || w.code === 'W-REVENUE-SHARE');
+  const others = verdict.warnings.filter((w) => !flagged.includes(w));
+  if (flagged.length) section('Flagged for the law, once it is real money', [...new Set(flagged.map((w) => w.message))]);
+  section('Know before going live', others.map((w) => `${w.message}${w.fix ? ` ${w.fix}` : ''}`));
+  lines.push('', 'Devnet only: nothing here is real money. Going live is your approval in your own wallet: no one else signs, and no key is ever shared.');
+  return { ok: true, text: lines.join('\n').trim(), warnings: verdict.warnings, needsAuthority: authority.length > 0, chance: verdict.warnings.some((w) => w.code === 'W-CHANCE-PRIZE'), setupSol: s.totalSol };
+}