@xgamesfun/solana 0.20.1 → 0.24.0

package/js/economy/simulate.mjs

@@ -4,10 +4,14 @@
 //
 // It assumes the scenario's counts (`scenario.perDay`, default 100 of each player action a day) arrive evenly,
 // odds as written (stock odds start where the table starts), and one ticket per lottery purchase. Shares of a
-// pool are worked out continuously, so a pool that pays a share of itself settles at a level instead of emptying.
-// It is a guide, not a promise: the full simulation (js/sim) runs the real program.
-import { ACCOUNT_BYTES, receiptBytes } from '../client/index.js';
-import { boxBuys, boxRolls, COLLECTIBLE_RENT as COLLECTIBLE_RENT_LAMPORTS, outcomeBurns, outcomeParts, ESCROW_LAMPORTS, FEES, LAMPORTS_PER_SOL, ORACLE_FEE, RENT_PER_BYTE, SIGNATURE_FEE, destination, listOf, lotterySplit, model, placeOf, prizeLine, prizePool, prizeToken, farmEndWords, prizeWords, releaseWords, sharesOf, toBps, toSeconds, toTime, weights } from './model.mjs';
+// pool (a schedule's, a decision's) are worked out continuously, so a pool that pays a share of itself settles at a level
+// instead of emptying. A prize is a fixed amount, all of it or none. Money is counted per day while a box sells; when
+// its items, stashes or named NFTs run out (its own opens alone), a box that stops selling (`whenOut` "stopSales") says
+// the day it stops, and one that draws among what is left ("drawLeft") the day each outcome runs out and the odds of
+// the rest from then (`stockWalk`). It is a guide, not a promise: the full simulation (js/sim) runs the real program.
+import { entryWidth, LIMIT_RECORD_BYTES, ROUND_RECORD_BYTES } from '../client/index.js';
+import { boxOrderBytes, roundRentOf } from './plan.mjs';
+import { boxBuys, COLLECTIBLE_RENT as COLLECTIBLE_RENT_LAMPORTS, drawsOf, settleUnits, holdsRent, outcomeParts, SETTLE_RENT_UNIT, FEES, LAMPORTS_PER_SOL, ORACLE_FEE, RENT_PER_BYTE, SIGNATURE_FEE, destination, listOf, lotterySplit, model, placeOf, prizeLine, prizePool, prizeToken, farmEndWords, lateRunWords, prizeWords, releaseWords, sharesOf, toBps, toSeconds, toTime, weights, whenOutWords } from './model.mjs';
 
 const DAY = 86_400;
 const DEFAULT_PER_DAY = 100;
@@ -19,19 +23,21 @@ const PROJECT_FEE = sol(FEES.project);
 const NETWORK_FEE = sol(SIGNATURE_FEE);
 /** MagicBlock's oracle, per random number: a box's open (the player), a lottery's draw, a `roll` (model.mjs ORACLE_FEE). */
 const ORACLE = sol(ORACLE_FEE);
-/** A lottery purchase's record: rent the buyer pays and gets back once the round is done with it (lottery.rs). */
-const TICKET_LINE = sol((BigInt(ACCOUNT_BYTES.LotteryContribution) + 128n) * RENT_PER_BYTE);
+/** A lottery purchase's entry in its round: the bytes the buyer adds (not refunded: they go to the treasury when the
+ * round closes), with a wallet kept for each share the buyer's own entry names (lottery.rs `entry_width`). */
+const ticketLine = (l) => sol(BigInt(entryWidth(lotterySplit(l).some((x) => String(x.to).startsWith('chosen')), Boolean(l.ticketNft))) * RENT_PER_BYTE);
 /** A collectible's Core account, paid from the SOL the order holds: its rent and Core's creation fee (model.mjs). */
 const COLLECTIBLE_RENT = sol(COLLECTIBLE_RENT_LAMPORTS);
 /** What a collectible a recipe burns gives back: its rent less one byte's (Core leaves a 1-byte account that keeps
  * the creation fee). 189 bytes × 5,080 lamports, measured by the full simulation. */
 const BURN_REFUND = 0.00096;
-/** A grant's wallet receipt at its first voucher: the current header plus one round hash. */
-const RECEIPT_RENT = sol((BigInt(receiptBytes(1)) + 128n) * RENT_PER_BYTE);
+/** What a grant's claim adds to its lists: the wallet's limit record (its first claim) and a record of the round paid
+ * (none for an open grant's claim). Back to the owner when the shards close after the grant. */
+const claimRecordsRent = (g) => sol(BigInt(LIMIT_RECORD_BYTES + ((g.vouchers ?? []).length || (g.keys ?? []).length || (g.list ?? []).length ? ROUND_RECORD_BYTES : 0)) * RENT_PER_BYTE);
 /** A wallet's token account, which a grant that pays tokens opens from its funds when the winner has none. */
 const TOKEN_ACCOUNT_RENT = sol((165n + 128n) * RENT_PER_BYTE);
-/** The order's fixed allocation, returned at settle or refund. */
-const ORDER_RENT = sol((BigInt(ACCOUNT_BYTES.Order) + 128n) * RENT_PER_BYTE);
+/** An order of box `b`'s rent (`orderBytes`), returned at settle or refund: an open's (`opened`, sized as `open_box` sizes it), or a roll's made inside another call. */
+const orderRent = (b, m, opened = false) => sol((BigInt(boxOrderBytes(b, m, 1, { opened })) + 128n) * RENT_PER_BYTE);
 const num = (v) => (v === undefined || v === null ? 0 : Number(v));
 export const round = (x, digits = 9) => (Number.isFinite(x) ? Number(x.toFixed(digits)) : x);
 
@@ -146,6 +152,8 @@ export function simulate(economy, { now = 0 } = {}) {
   const pools = new Map(m.pools.map((p) => [p.key, { key: p.key, currency: p.currency, seed: num(p.seed), in: [], out: [], rate: [], variance: 0 }]));
   // Each lottery's pot is an account of its own, counted here as a pool named "lottery:<key>".
   for (const l of m.lotteries) pools.set(`lottery:${l.key}`, { key: `lottery:${l.key}`, pot: l.name, currency: l.currency ?? game, seed: num(l.seed), in: [], out: [], rate: [], variance: 0 });
+  // Each farm's rewards vault is an account of its own too, counted as a pool named "farm:<key>".
+  for (const f of m.farms) pools.set(`farm:${f.key}`, { key: `farm:${f.key}`, farm: f.name, currency: f.rewardsToken, seed: num(f.seed), in: [], out: [], rate: [], variance: 0 });
   const flowIn = (pool, by, amount) => amount && pools.get(pool)?.in.push({ by, perDay: amount });
   const flowOut = (pool, by, amount) => amount && pools.get(pool)?.out.push({ by, perDay: amount });
   const rateOut = (pool, by, perDayShare, to) => perDayShare && pools.get(pool)?.rate.push({ by, perDay: perDayShare, ...(to ? { to } : {}) });
@@ -156,15 +164,16 @@ export function simulate(economy, { now = 0 } = {}) {
   const accounts = {};
   const platform = { player: 0, project: 0 };
   const notes = [];
-  /** Prizes that are a share of a pool: counted for players once each pool's level is known. */
+  /** What a schedule or a decision pays out as a share of a pool: counted for players once each pool's level is known. */
   const sharePrizes = [];
   /** Shares of a pool that are burned (a schedule, a decision): counted once each pool's level is known. */
   const shareBurns = [];
   /** NFTs taken out of a stash a day, by each box that gives one; and the rolls of a box prizes give a day. */
   const stashTakes = [];
   const prizeTakes = [];
-  /** The SOL a prize's order holds while it waits (its rent, and the SOL for a collectible when the box can give one), back to the winner at settle. */
-  const orderHeld = (box) => ORDER_RENT + sol(ESCROW_LAMPORTS) * Math.max(0, ...(m.box.get(box)?.outcomes ?? []).map((o) => outcomeParts(o).filter((x) => x.gives === 'item').length));
+  /** The SOL a prize's order holds while it waits (its rent), back to the winner at settle. Whoever settles it pays a
+   * collectible's rent. */
+  const orderHeld = (box) => orderRent(m.box.get(box), m);
   /**
    * A route gives prize line `line` `times` a day (prize.rs), `payer` ({ rent, oracle }) paying what it opens: a
    * collectible's rent, the winner's token account (the bound, not the average), a roll's order (back to the winner at
@@ -183,10 +192,6 @@ export function simulate(economy, { now = 0 } = {}) {
       const token = prizePool(line) ? m.pool.get(prizePool(line))?.currency : line.currency ?? game;
       if (prizePool(line)) flowOut(prizePool(line), by, times * num(line.amount));
       add(players.get, token, times * num(line.amount));
-    } else if (line.gives === 'share') {
-      each = TOKEN_ACCOUNT_RENT;
-      rateOut(line.pool, by, times * ((toBps(line.percent) ?? 0) / 10_000));
-      sharePrizes.push({ pool: line.pool, rate: times * ((toBps(line.percent) ?? 0) / 10_000) });
     } else if (line.gives === 'nft') {
       stashTakes.push({ stash: line.stash, perDay: times, by });
     } else if (line.gives === 'roll') {
@@ -212,10 +217,11 @@ export function simulate(economy, { now = 0 } = {}) {
     notes.push(sold.last >= 10 * num(part.price) ? `${said} It ends ${sold.last >= PRICE_CAP ? 'beyond any price' : `${round(sold.last / num(part.price), 1)} times`} where it started: players stop buying long before that. A smaller growth keeps it in reach.` : said);
   };
 
-  /** Sends `amount` of `token` a day to one destination (model `destination`): a pool, a lottery's pot, a burn, the treasury or an account. */
+  /** Sends `amount` of `token` a day to one destination (model `destination`): a pool, a lottery's pot, a farm's rewards vault, a burn, the treasury or an account. */
   const sendTo = (d, token, amount, by) => {
     if (d.kind === 'pool') flowIn(d.key, by, amount);
     else if (d.kind === 'lottery') flowIn(`lottery:${d.key}`, by, amount);
+    else if (d.kind === 'farm') flowIn(`farm:${d.key}`, by, amount);
     else if (d.kind === 'burn') add(burned, token, amount);
     else if (d.kind === 'treasury') add(creator.treasury, token, amount);
     else if (d.kind === 'chosen') add(accounts, d.key ? `the holder of the ${m.item.get(d.key)?.name ?? d.key} the buyer names` : `the wallet the ${String(by).startsWith('payment:') ? 'payer' : 'buyer'} names`, amount);
@@ -238,6 +244,76 @@ export function simulate(economy, { now = 0 } = {}) {
     players.network += count * signatures * NETWORK_FEE;
   };
 
+  /**
+   * What box `b`'s items with a supply, stashes and named NFTs come to over the scenario, with `opens` opens a day and
+   * its own opens alone taking from them (pools are walked with their own rows): when an outcome runs out, a box that
+   * stops selling stops (`stopsSellingInDays`), and one that draws among what is left goes on with the rest's chances
+   * rising (`runsOut`: each outcome's day, and every chance from then), until nothing in it is left. An item whose odds
+   * follow its stock (`stockOdds`) never runs out here: its chance shrinks instead. Null when nothing it gives runs out.
+   */
+  const stockWalk = (b, opens) => {
+    const w = weights(b);
+    const draws = drawsOf(b);
+    // What each stock holds at the start, and what one draw of each outcome takes from it.
+    const left = new Map();
+    const stockOf = (x) => {
+      const supply = Number(m.item.get(x.item)?.supply ?? 0);
+      if (x.gives === 'item' && supply > 0 && !b.stockOdds) return [`item:${x.item}`, supply];
+      if (x.gives === 'stash' && m.stash.get(x.stash)) return [`stash:${x.stash}`, (m.stash.get(x.stash).nfts ?? []).length];
+      if (x.gives === 'nft') return [`nft:${x.nft}`, 1];
+      return null;
+    };
+    const needs = (b.outcomes ?? []).map((o) => {
+      const need = new Map();
+      for (const [key, holds] of outcomeParts(o).map(stockOf).filter(Boolean)) {
+        left.set(key, holds);
+        need.set(key, (need.get(key) ?? 0) + 1);
+      }
+      return need;
+    });
+    if (!left.size || !(opens > 0)) return null;
+    const stops = b.whenOut !== 'drawLeft';
+    const there = (i) => [...needs[i]].every(([k, n]) => left.get(k) >= n);
+    const chances = (alive) => {
+      const sum = alive.reduce((n, i) => n + w[i], 0);
+      return w.map((x, i) => (sum && alive.includes(i) ? round((x / sum) * 100, 6) : 0));
+    };
+    let alive = w.map((_, i) => i).filter(there);
+    let day = 0;
+    const runsOut = [];
+    const out = (i) => ({ outcome: i, gives: (b.outcomes[i].gives === 'bundle' ? (b.outcomes[i].prizes ?? []).map((x) => x.item ?? x.stash ?? x.gives) : [b.outcomes[i].item ?? b.outcomes[i].stash ?? b.outcomes[i].gives]).join(' + ') });
+    const gone = w.map((_, i) => i).filter((i) => !alive.includes(i));
+    if (gone.length) {
+      if (stops) return { whenOut: 'stopSales', stopsSellingInDays: 0, by: gone.map(out) };
+      runsOut.push({ inDays: 0, outcomes: gone.map(out), chancesAfter: chances(alive) });
+    }
+    while (alive.length) {
+      const sum = alive.reduce((n, i) => n + w[i], 0);
+      // Each stock's take a day, by the outcomes still there.
+      const rate = new Map();
+      for (const i of alive) for (const [k, n] of needs[i]) rate.set(k, (rate.get(k) ?? 0) + (opens * draws * w[i] * n) / sum);
+      const next = [...rate].map(([k, r]) => ({ k, t: left.get(k) / r })).sort((a, z) => a.t - z.t)[0];
+      if (!next || day + next.t > days) break;
+      day += next.t;
+      for (const [k, r] of rate) left.set(k, Math.max(0, left.get(k) - r * next.t));
+      left.set(next.k, 0);
+      const ended = alive.filter((i) => !there(i));
+      alive = alive.filter(there);
+      if (stops) return { whenOut: 'stopSales', stopsSellingInDays: round(day, 4), by: ended.map(out) };
+      runsOut.push({ inDays: round(day, 4), outcomes: ended.map(out), chancesAfter: chances(alive) });
+    }
+    if (stops) return null;
+    return runsOut.length ? { whenOut: 'drawLeft', runsOut, ...(alive.length ? {} : { stopsSellingInDays: runsOut.at(-1).inDays }) } : null;
+  };
+  /** The walk of a box's stock in words (`stockWalk`). */
+  const stockNote = (b, walk) => {
+    const named = (list) => list.map((x) => `outcome ${x.outcome} (${x.gives})`).join(', ');
+    if (walk.whenOut === 'stopSales')
+      return `“${b.name}” stops selling ${walk.stopsSellingInDays ? `in about ${walk.stopsSellingInDays} days` : 'from the start'}, when ${named(walk.by)} runs out (its own opens alone): it isn’t sold while any outcome couldn’t cover a purchase and those still waiting for the oracle ("whenOut": "stopSales"), so every roll is on the odds as written. Restock it, or edit the box, to sell again; "drawLeft" would keep selling, the rest’s chances rising.`;
+    const steps = walk.runsOut.map((r) => `${named(r.outcomes)} ${r.inDays ? `in about ${r.inDays} days` : 'from the start'}${r.chancesAfter.some((c) => c > 0) ? `, then ${r.chancesAfter.map((c, i) => (c > 0 ? `outcome ${i} ${round(c, 2)}%` : null)).filter(Boolean).join(', ')}` : ''}`);
+    return `“${b.name}” keeps selling as its outcomes run out ("whenOut": "drawLeft"; its own opens alone): ${steps.join('; ')}${walk.stopsSellingInDays !== undefined ? `; with nothing left, it stops selling` : ''}. Each roll draws among what is left by the written weights, so a player can empty a common outcome to make a rare one likelier; "stopSales" keeps the odds as written.`;
+  };
+
   // ---- boxes
   const boxes = m.boxes.map((b) => {
     const token = b.currency ?? game;
@@ -248,7 +324,6 @@ export function simulate(economy, { now = 0 } = {}) {
     const w = weights(b);
     const total = w.reduce((a, x) => a + x, 0) || 1;
     let value = 0;
-    let burnChance = 0;
     const unpriced = [];
     const other = {};
     // One part of what an outcome gives (model `outcomeParts`), landing with chance `p`: its row, and its flows.
@@ -266,13 +341,6 @@ export function simulate(economy, { now = 0 } = {}) {
         Object.assign(row, { amount: num(o.amount), token: prizeToken, minted: true });
         if (prizeToken === token) value += p * num(o.amount);
         else add(other, prizeToken, p * num(o.amount));
-      } else if (o.gives === 'share') {
-        const bps = toBps(o.percent) ?? 0;
-        const prizeToken = m.pool.get(o.pool)?.currency;
-        Object.assign(row, { pool: o.pool, percent: o.percent, token: prizeToken });
-        rateOut(o.pool, `box:${b.key}`, opens * p * (bps / 10_000));
-        sharePrizes.push({ pool: o.pool, rate: opens * p * (bps / 10_000), box: b.key, perOpen: p * (bps / 10_000) });
-        row.shareOfPool = true;
       } else if (o.gives === 'item') {
         const it = m.item.get(o.item);
         const worth = it?.value !== undefined ? num(it.value) : num(it?.price) > 0 ? num(it.price) : null;
@@ -297,13 +365,11 @@ export function simulate(economy, { now = 0 } = {}) {
     const outcomes = (b.outcomes ?? []).map((o, i) => {
       const p = w[i] / total;
       const parts = outcomeParts(o).map((part) => partRow(part, p));
-      if (outcomeBurns(o)) burnChance += p;
-      if (o.gives === 'bundle') return { gives: 'bundle', chance: round(p * 100, 6), prizes: parts, ...(o.burns ? { burns: true } : {}) };
+      if (o.gives === 'bundle') return { gives: 'bundle', chance: round(p * 100, 6), prizes: parts };
       return parts[0] ?? { gives: o.gives, chance: round(p * 100, 6) };
     });
     // Every part of every outcome, each with its outcome's chance.
     const partsOf = outcomes.flatMap((o) => (o.gives === 'bundle' ? o.prizes : [o]));
-    const shares = partsOf.filter((o) => o.shareOfPool);
     // How much the prizes swing from day to day, per pool: opens × (E[prize²] − E[prize]²).
     for (const key of new Set(partsOf.filter((o) => o.gives === 'pay').map((o) => o.pool))) {
       const rows = partsOf.filter((o) => o.gives === 'pay' && o.pool === key);
@@ -311,31 +377,30 @@ export function simulate(economy, { now = 0 } = {}) {
       const square = rows.reduce((n, o) => n + (o.chance / 100) * o.amount ** 2, 0);
       if (pools.has(key)) pools.get(key).variance += opens * (square - mean ** 2);
     }
-    // Money: the payment is split unless the roll burns it all.
-    carryOut(b.split, token, opens * price * (1 - burnChance), `box:${b.key}`);
-    add(burned, token, opens * price * burnChance);
+    // Money: the payment is split (a share may burn it).
+    carryOut(b.split, token, opens * price, `box:${b.key}`);
     add(players.pay, token, opens * price);
     add(players.get, token, opens * value);
     for (const [t, v] of Object.entries(other)) add(players.get, t, opens * v);
-    // Two signatures: the open, then the settle that carries the outcome out, both from the player's wallet. A box
-    // that needs no roll is bought in one (`buy`), with no order; one of one entry that rolls on an NFT opens an order
-    // that needs no oracle.
-    const rolled = boxRolls(b);
-    const bought = boxBuys(b);
+    // Two signatures: the open, then the settle that carries the outcome out (a throwaway key the open funds sends it).
+    // A box that needs no roll is bought in one (`buy`), with no order; every open asks the oracle.
+    const bought = boxBuys(b, m);
     const signatures = bought ? 1 : 2;
     playerAction(opens, signatures);
-    if (rolled) players.oracle += opens * ORACLE;
-    const collectibles = partsOf.filter((o) => o.gives === 'item' && m.item.get(o.item)?.kind !== 'normal').reduce((n, o) => n + o.chance / 100, 0);
+    if (!bought) players.oracle += opens * ORACLE;
+    const collectibles = drawsOf(b) * partsOf.filter((o) => holdsRent(o, m) && m.item.get(o.item)?.kind !== 'normal').reduce((n, o) => n + o.chance / 100, 0);
     players.rent += opens * collectibles * COLLECTIBLE_RENT;
-    const known = !unpriced.length && !shares.length && !Object.keys(other).length;
+    const known = !unpriced.length && !Object.keys(other).length;
     // What one open really takes from the player's wallet: the price, the platform's fee, the oracle's and the network's.
     const isSol = Boolean(m.tokens.get(token)?.wsol);
-    const oracle = rolled ? ORACLE : 0;
-    // A collectible's rent comes out of the SOL the order holds when it settles: on average, the chance of one.
-    const items = Math.max(0, ...(b.outcomes ?? []).map((o) => outcomeParts(o).filter((x) => x.gives === 'item').length));
-    const realCost = realCostOf({ price, token, isSol, oracle, signatures, rent: collectibles * COLLECTIBLE_RENT, rentIs: collectibles < 1 ? 'the collectible’s rent, when it gives one' : 'the collectible’s rent', held: bought ? 0 : sol(ESCROW_LAMPORTS) * items + ORDER_RENT });
+    const oracle = bought ? 0 : ORACLE;
+    // A collectible's rent comes out of the SOL the open lends its settle key: on average, the chance of one.
+    const realCost = realCostOf({ price, token, isSol, oracle, signatures, rent: collectibles * COLLECTIBLE_RENT, rentIs: collectibles < 1 ? 'the collectible’s rent, when it gives one' : 'the collectible’s rent', held: bought ? 0 : sol(SETTLE_RENT_UNIT) * settleUnits(b, m) + orderRent(b, m, true) });
     const extrasSol = realCost.extrasSol;
     priceNote(b, sold);
+    // What it gives that runs out, as the box says (`whenOut`): it stops selling, or draws among what is left.
+    const walk = !bought && b.active !== false ? stockWalk(b, opens) : null;
+    if (walk) notes.push(stockNote(b, walk));
     return {
       key: b.key,
       name: b.name,
@@ -352,6 +417,10 @@ export function simulate(economy, { now = 0 } = {}) {
       playerFee: PLAYER_FEE,
       oracleFee: oracle,
       realCost,
+      // What it gives can run out, and what the box does then (`whenOut`, `whenOutWords`).
+      ...(!bought && outcomes.flatMap((o) => (o.gives === 'bundle' ? o.prizes : [o])).some((o) => o.gives === 'pay' || o.gives === 'stash' || o.gives === 'nft' || (o.gives === 'item' && Number(m.item.get(o.item)?.supply ?? 0) > 0)) ? { limitedStock: true } : {}),
+      ...(!bought ? { whenOut: b.whenOut === 'drawLeft' ? 'drawLeft' : 'stopSales' } : {}),
+      ...(walk ? { stock: walk } : {}),
       ...(isSol && known && price ? { returnOfRealCostPercent: round((value / (price + extrasSol)) * 100, 4) } : {}),
     };
   });
@@ -428,10 +497,6 @@ export function simulate(economy, { now = 0 } = {}) {
       } else if (line.gives === 'nft') {
         gives.push(prizeWords(line, m));
         stashTakes.push({ stash: line.stash, perDay: crafts, by: `recipe:${r.key}` });
-      } else if (line.gives === 'share') {
-        gives.push(`${line.percent}% of ${line.pool}`);
-        rateOut(line.pool, `recipe:${r.key}`, crafts * ((toBps(line.percent) ?? 0) / 10_000));
-        sharePrizes.push({ pool: line.pool, rate: crafts * ((toBps(line.percent) ?? 0) / 10_000) });
       }
     }
     // The player's is the only signature: what a craft makes is at its item's and serial's address.
@@ -448,7 +513,7 @@ export function simulate(economy, { now = 0 } = {}) {
       creator.network += runs * NETWORK_FEE; // run_schedule is free of the program's fee; whoever sends it pays the network
       if (s.does === 'issue') {
         const amount = num(s.amount);
-        flowIn(s.pool, `schedule:${s.key}`, runs * amount);
+        flowIn(destination(s.to ?? '').kind === 'farm' ? s.to : s.pool, `schedule:${s.key}`, runs * amount);
         const halving = s.halveEvery ? `, halving every ${s.halveEvery} runs (every ${round((s.halveEvery * every) / DAY, 2)} days)` : '';
         // Halving every h runs: h runs at the amount, h at half, … (2 × h × amount in all, with no end); with
         // maxRuns, the full halvings it reaches and the runs after the last.
@@ -496,7 +561,7 @@ export function simulate(economy, { now = 0 } = {}) {
       return { key: s.key, does: s.does, percentPerDay: round(runs * s.percent, 6), says: `${where} ${s.percent}% of ${from} every ${round(every / 3600, 3)} h` };
     });
 
-  // ---- stakes: everything that arrives in the rewards pool goes to stakers
+  // ---- stakes: everything that arrives in a farm’s rewards vault goes to its stakers
   // ---- lotteries: in steady state each round pays out what came in (what the places leave rolls over). One that draws
   // once (no `every`) has one round, from going live to its first draw (the scenario's end at the latest): its tickets,
   // its draw and its pot happen once, spread over the scenario's days like an auction's sale.
@@ -525,7 +590,9 @@ export function simulate(economy, { now = 0 } = {}) {
       carryOut(split, potToken, tickets * price, `lottery:${l.key}`, `lottery:${l.key}`);
     }
     playerAction(tickets);
-    players.rent += tickets * TICKET_LINE;
+    // A lottery that holds SOL for its rounds (`roundRent`, on by default) pays each entry's bytes: the buyer pays none.
+    const entryRent = roundRentOf(l, m) > 0n ? 0 : ticketLine(l);
+    players.rent += tickets * entryRent;
     const placed = (l.places ?? [100]).map(placeOf);
     const places = placed.map((p) => Number(p.percent));
     creator.network += (1 + places.length) * NETWORK_FEE * drawsPerDay; // the draw and each place's payment
@@ -542,8 +609,8 @@ export function simulate(economy, { now = 0 } = {}) {
     const prized = placed.filter((p) => prizeLine(p.prize)).map((p) => worthOf(prizeLine(p.prize)));
     // One ticket bought on its own: the fee and the record are per purchase, so a bundle of tickets shares them. The
     // record's rent comes back once the round is done with it, and a no-loss ticket's price after the draw: both held.
-    const realCost = realCostOf({ price, token: ticketToken, isSol: Boolean(m.tokens.get(ticketToken)?.wsol), held: TICKET_LINE, heldIs: l.noLoss ? 'the ticket’s price and the purchase record’s rent' : 'the purchase record’s rent', priceBack: Boolean(l.noLoss) });
-    return { key: l.key, name: l.name, price, token: ticketToken, potToken, ...(l.minSold ? { minSold: l.minSold } : {}), ticketsPerDay: round(tickets, 6), ticketsPerRound: round(perRound, 4), roundDays: round(every / DAY, 4), places, placePrizes: placed.map((p) => (p.prize ? prizeWords(p.prize, m) : null)), prizeWorthPerRound: round(prized.reduce((n, w) => n + (w ?? 0), 0)), ...(prized.includes(null) ? { unpricedPrizes: true } : {}), cutPercent: num(l.cutPercent), splitPercent: round(cut * 100, 4), drawsOnce: once, ...(l.ticketNft ? { ticketNft: true } : {}), ...(l.noLoss ? { noLoss: true } : {}), realCost };
+    const realCost = realCostOf({ price, token: ticketToken, isSol: Boolean(m.tokens.get(ticketToken)?.wsol), rent: entryRent, rentIs: 'the purchase’s entry in the round', ...(l.noLoss ? { heldIs: 'the ticket’s price' } : {}), priceBack: Boolean(l.noLoss) });
+    return { key: l.key, name: l.name, price, token: ticketToken, potToken, ...(l.minSold ? { minSold: l.minSold } : {}), ticketsPerDay: round(tickets, 6), ticketsPerRound: round(perRound, 4), roundDays: round(every / DAY, 4), places, placePrizes: placed.map((p) => (p.prize ? prizeWords(p.prize, m) : null)), prizeWorthPerRound: round(prized.reduce((n, w) => n + (w ?? 0), 0)), ...(prized.includes(null) ? { unpricedPrizes: true } : {}), cutPercent: num(l.cutPercent), splitPercent: round(cut * 100, 4), drawsOnce: once, roundRentSol: round(Number(roundRentOf(l, m)) / 1e9), ...(l.ticketNft ? { ticketNft: true } : {}), ...(l.noLoss ? { noLoss: true } : {}), realCost };
   });
 
   // ---- decisions with a known rate
@@ -619,15 +686,15 @@ export function simulate(economy, { now = 0 } = {}) {
     };
   });
   for (const f of m.farms) playerAction(perDay('farm', f.key));
-  // Grants: each claim's sender pays the player fee; its receipt's rent comes from the grant's funds (the owner's SOL).
+  // Grants: each claim's sender pays the player fee; its records' rent comes from the grant's funds (the owner's SOL, back when its shards close).
   const grants = m.grants.map((g) => {
     const claims = num(m.scenario.perDay?.[`grant:${g.key}`]);
     playerAction(claims);
-    creator.rent = (creator.rent ?? 0) + claims * RECEIPT_RENT;
+    creator.rent = (creator.rent ?? 0) + claims * claimRecordsRent(g);
     // Its prize, paid for by the grant's funds; a roll's order goes back to the winner at settle.
     const line = prizeLine(g.prize ?? g.gives);
     const each = givePrize(line, claims, `grant:${g.key}`, creator);
-    return { key: g.key, name: g.name, claimsPerDay: claims, gives: prizeWords(line, m), fundsPerClaimSol: round(RECEIPT_RENT + each), ...(line?.gives === 'roll' ? { orderHeldSol: round(orderHeld(line.box)) } : {}) };
+    return { key: g.key, name: g.name, claimsPerDay: claims, gives: prizeWords(line, m), fundsPerClaimSol: round(claimRecordsRent(g) + each), ...(line?.gives === 'roll' ? { orderHeldSol: round(orderHeld(line.box)) } : {}) };
   });
   for (const h of m.holds) playerAction(perDay('hold', h.key));
   for (const c of m.contests) playerAction(perDay('contest', c.key));
@@ -653,48 +720,48 @@ export function simulate(economy, { now = 0 } = {}) {
       p.inflow = inflow;
     }
 
-  // Farms: everything that arrives in the rewards pool is released to the seats over the farm's release span (its
-  // longest lock, a day at least), by weight (stake × tier × boosts) as it is released; or a fixed rate for each seat
-  // (minted, or from the pool while it lasts). In a steady state the release pays what arrives, a day at a time.
-  /** A farm's ways out and tolls, in words (farm.rs): an early-exit fee, an unbonding wait, a toll; or null. */
+  // Farms: everything that arrives in a farm's rewards vault is released to the seats over the farm's release span (its
+  // longest lock, a day at least), by weight (stake × tier × boosts) as it is released; or a fixed rate for each seat,
+  // or with `shared` for the whole farm (minted, or from the vault while it lasts). In a steady state the release pays
+  // what arrives, a day at a time.
+  /** A farm's ways out, in words (farm.rs): an early-exit fee, compounding; or null. */
   const farmExtras = (f) => {
-    const exits = (f.tiers ?? []).map((t, i) => (t.exitFee ? `tier ${i + 1} may leave before its ${t.lock} lock by leaving ${t.exitFee}% of what it takes out (${f.exitFeeTo === 'burn' ? 'burned' : `to ${String(f.exitFeeTo).replace(/^pool:/, '')}`})` : null)).filter(Boolean);
+    const exits = (f.tiers ?? []).map((t, i) => (t.exitFee ? `tier ${i + 1} may leave before its ${t.lock} lock by leaving ${t.exitFee}% of what it takes out (${f.exitFeeTo === 'burn' ? 'burned' : f.exitFeeTo === 'rewards' ? 'into its own rewards vault' : `to ${String(f.exitFeeTo).replace(/^pool:/, '')}`}), keeping the rewards it was credited` : null)).filter(Boolean);
     const parts = [
       ...exits,
-      f.unbond && `what is taken out waits ${f.unbond}, earning nothing, before it can leave`,
-      f.toll && `${f.toll.percent}% of every payout of rewards is ${f.toll.to === 'burn' ? 'burned' : `sent to ${String(f.toll.to).replace(/^pool:/, '')}`}`,
-      f.stakes !== 'collectibles' && m.pool.get(f.rewards)?.currency === f.stakes && 'its rewards can be compounded into the stake without restarting the lock',
-      f.unpaid && 'it pays nothing: staking there only counts (a stake gate reads it)',
+      f.stakes !== 'collectibles' && f.rewardsToken === f.stakes && 'its rewards can be compounded into the stake without restarting the lock',
+      (f.tiers ?? []).some((t) => t.earnsFor) && `a seat earns only for its tier’s term (${(f.tiers ?? []).map((t) => t.earnsFor ?? 'no end').join(', ')}) after its lock started`,
     ].filter(Boolean);
     return parts.length ? parts.join('; ') : null;
   };
-  /** What a seat of `f` can give back (farm.rs `Farm::give`): a forfeit, an early exit's waiting rewards, a watched NFT gone, a lapsed upkeep. */
-  const giveBacks = (f) => ['a forfeit', (f.tiers ?? []).some((t) => t.exitFee) && 'an early exit’s waiting rewards', f.custody === 'watch' && 'a watched NFT sold', f.upkeepAttribute && 'what a lapsed upkeep earned'].filter(Boolean).join(', ');
+  /** What a seat of `f` can give up (farm.rs `Farm::give`): a forfeit, a watched NFT gone. */
+  const giveBacks = (f) => ['a forfeit', f.custody === 'watch' && 'a watched NFT sold'].filter(Boolean).join(', ');
   const farmRows = m.farms.map((f) => {
-    const pool = pools.get(f.rewards);
+    const pool = pools.get(`farm:${f.key}`);
     const staked = num(m.scenario.staked?.[f.key]);
     const perUnit = f.rate ? num(f.rate.perDay) : null;
-    const wanted = f.rate ? perUnit * staked : Infinity;
+    const wanted = !f.rate ? Infinity : f.rate.shared ? (staked ? perUnit : 0) : perUnit * staked;
     const free = pool ? Math.max(0, pool.inflow - pool.out.reduce((n, x) => n + x.perDay, 0)) : 0;
     const rewards = f.rate?.minted ? wanted : Math.min(wanted, f.rate ? free + (pool?.seed ?? 0) / Math.max(1, m.scenario.days ?? 30) : free);
     if (pool && !f.rate?.minted) pool.out.push({ by: `farm:${f.key}`, perDay: rewards });
-    const sameToken = pool?.currency === f.stakes;
-    const tiers = (f.tiers ?? [{ lock: 0, multiplier: 1 }]).map((t) => ({ lock: t.lock, multiplier: t.multiplier ?? 1, ...(prizeLine(t.prize) ? { prize: prizeWords(t.prize, m) } : {}) }));
+    const sameToken = f.rewardsToken === f.stakes;
+    const tiers = (f.tiers ?? [{ lock: 0, multiplier: 1 }]).map((t) => ({ lock: t.lock, multiplier: t.multiplier ?? 1, ...(t.earnsFor ? { earnsFor: t.earnsFor } : {}), ...(prizeLine(t.prize) ? { prize: prizeWords(t.prize, m) } : {}) }));
     const unit = f.stakes === 'collectibles' ? 'collectible' : symbol(f.stakes);
     // Growth: the days a collectible at x1 needs for each level.
     const growth = listOf(f.growth).map((g) => {
       const levels = (g.levels ?? []).map((points, i) => ({ level: i + 1, points, days: round(points / g.perDay, 2) }));
       return { attribute: g.attribute ?? 'xp', perDay: g.perDay, ...(levels.length ? { level: g.level ?? 'level', levels } : {}), streak: Boolean(g.streak) };
     });
+    const perSeat = !f.rate ? null : f.rate.shared ? (staked ? perUnit / staked : null) : perUnit;
     return {
       key: f.key,
       name: f.name,
       stakes: f.stakes,
-      rewardsToken: pool?.currency,
+      rewardsToken: f.rewardsToken,
       rewardsPerDay: round(rewards),
-      ...(f.rate ? { rate: { perDay: perUnit, minted: Boolean(f.rate.minted) } } : {}),
+      ...(f.rate ? { rate: { perDay: perUnit, minted: Boolean(f.rate.minted), ...(f.rate.shared ? { shared: true } : {}), ...(f.rate.halveEvery ? { halveEvery: f.rate.halveEvery } : {}) } } : {}),
       tiers,
-      ...(staked ? { staked, perUnitPerDay: round(f.rate ? perUnit : rewards / staked), unit } : f.rate ? { perUnitPerDay: perUnit, unit } : {}),
+      ...(staked ? { staked, perUnitPerDay: round(f.rate ? perSeat : rewards / staked), unit } : f.rate && !f.rate.shared ? { perUnitPerDay: perUnit, unit } : {}),
       ...(staked && sameToken ? { yearlyPercent: round(((rewards * 365) / staked) * 100, 4) } : {}),
       ...(growth.length ? { growth } : {}),
       ...(f.runs ? { runs: f.runs } : {}),
@@ -703,8 +770,8 @@ export function simulate(economy, { now = 0 } = {}) {
       ...(f.upkeepAttribute ? { upkeepAttribute: f.upkeepAttribute } : {}),
       ...(farmExtras(f) ? { extras: farmExtras(f) } : {}),
       says: f.rate
-        ? `each seat earns ${perUnit} a day for each ${unit} at x1, whoever else is in${f.rate.minted ? ' (minted, as far as the mint has room for: what it can’t mint is not owed later)' : ', while the pool lasts'}${perUnit > 0 ? `; what a seat gives back (${giveBacks(f)}) is ${f.rate.minted ? 'burned' : `sent back to “${f.rewards}”`} in the same move, never to the other seats` : ''}`
-        : `what lands in the pool is released over ${releaseWords(f)} to the seats there as it is released, so a stake earns only while it stays; ${tiers.length > 1 || (f.boosts ?? []).length ? 'shares are by weight: a higher tier or a boosted collectible takes more of the same rewards, so the figures are for a seat at x1 among seats at x1' : 'shares are by what each seat stakes'}`,
+        ? `${f.rate.shared ? `the farm pays ${perUnit} a day in all, shared by weight while anything is staked` : `each seat earns ${perUnit} a day for each ${unit} at x1, whoever else is in`}${f.rate.halveEvery ? `, halving every ${f.rate.halveEvery}` : ''}${f.rate.minted ? ' (minted when a seat is paid, as far as the mint has room for: what it can’t mint is not owed later)' : ', while its vault lasts'}${perUnit > 0 ? `; what a seat gives back (${giveBacks(f)}) is ${f.rate.minted ? 'never minted' : 'left free in its vault'}, never to the other seats` : ''}`
+        : `what lands in its rewards vault is released over ${releaseWords(f)} to the seats there as it is released, so a stake earns only while it stays; ${tiers.length > 1 || (f.boosts ?? []).length ? 'shares are by weight: a higher tier or a boosted collectible takes more of the same rewards, so the figures are for a seat at x1 among seats at x1' : 'shares are by what each seat stakes'}`,
     };
   });
   for (const row of farmRows) add(players.get, row.rewardsToken, row.rewardsPerDay);
@@ -739,6 +806,7 @@ export function simulate(economy, { now = 0 } = {}) {
     const row = {
       key: p.key,
       ...(p.pot ? { pot: p.pot } : {}),
+      ...(p.farm ? { farm: p.farm } : {}),
       token: p.currency,
       seed: p.seed,
       inPerDay: round(inflow),
@@ -776,7 +844,7 @@ export function simulate(economy, { now = 0 } = {}) {
       row.swingPerDay = round(Math.sqrt(p.variance), 6);
       const weekly = Math.sqrt(p.variance * 7);
       if (row.lasts !== 'runs dry' && p.seed < 3 * weekly)
-        notes.push(`The pool “${p.key}” ${row.lasts === 'grows' ? 'takes in more than it pays on average' : row.lasts === 'settles' ? 'settles on average' : 'pays even on average'}, but luck moves it by about ±${round(row.swingPerDay, 4)} ${symbol(p.currency)} a day (±${round(weekly, 4)} a week), against a seed of ${p.seed}. While it can’t cover a fixed prize the box stops selling, and a prize rolled while it ran short pays only what it held, so a bad week stalls sales and shrinks wins until it refills. A seed of about ${round(3 * weekly, 2)} (three times a week’s swing) rides out almost any week.`);
+        notes.push(`The pool “${p.key}” ${row.lasts === 'grows' ? 'takes in more than it pays on average' : row.lasts === 'settles' ? 'settles on average' : 'pays even on average'}, but luck moves it by about ±${round(row.swingPerDay, 4)} ${symbol(p.currency)} a day (±${round(weekly, 4)} a week), against a seed of ${p.seed}. While it can’t cover a fixed prize, a box that stops selling when out (the default) sells nothing, and one that draws among what is left never lands on that prize, so a bad week stalls sales or takes the big wins away until it refills. A seed of about ${round(3 * weekly, 2)} (three times a week’s swing) rides out almost any week.`);
     }
     if (row.lasts === 'runs dry') notes.push(`The pool “${p.key}” pays out more than comes in: it lasts about ${row.lastsDays} days from its seed of ${p.seed} ${symbol(p.currency)}.`);
     return row;
@@ -787,10 +855,8 @@ export function simulate(economy, { now = 0 } = {}) {
     const level = row ? (row.settlesAt ?? row.seed) : 0;
     if (prize.account) sendTo(destination(prize.account), row?.token, prize.rate * level, prize.by);
     else add(players.get, row?.token, prize.rate * level);
-    const box = prize.box && boxes.find((b) => b.key === prize.box);
-    if (box) add(box.alsoPays, row?.token, round(prize.perOpen * level));
   }
-  // A share burned is burned at the pool's level, as a share prize is paid.
+  // A share burned is burned at the pool's level, as a share paid out is.
   for (const b of shareBurns) {
     const row = poolRows.find((r) => r.key === b.pool);
     add(burned, row?.token, b.rate * (row ? (row.settlesAt ?? row.seed) : 0));
@@ -819,8 +885,8 @@ export function simulate(economy, { now = 0 } = {}) {
     const holds = (s.nfts ?? []).length;
     const net = perDay - inPerDay;
     const filled = inPerDay > 0 ? `, and takes in about ${round(inPerDay, 4)} a day (${[...new Set(fills.map((t) => t.by))].join(', ')})` : '';
-    if (perDay > 0 && net > 0) notes.push(`The stash “${s.name}” starts with ${holds} NFT${holds === 1 ? '' : 's'} and gives about ${round(perDay, 4)} a day (${[...new Set(takes.map((t) => t.by))].join(', ')})${filled}: ${holds ? `empty in about ${round(holds / net, 2)} days` : 'empty from the start'}, after which its outcome can’t be won until more are put in.`);
-    else if (perDay > 0) notes.push(`The stash “${s.name}” starts with ${holds} NFT${holds === 1 ? '' : 's'}, gives about ${round(perDay, 4)} a day (${[...new Set(takes.map((t) => t.by))].join(', ')})${filled}: it keeps up${holds ? '' : ', once the first come in (until then its outcome can’t be won)'}.`);
+    if (perDay > 0 && net > 0) notes.push(`The stash “${s.name}” starts with ${holds} NFT${holds === 1 ? '' : 's'} and gives about ${round(perDay, 4)} a day (${[...new Set(takes.map((t) => t.by))].join(', ')})${filled}: ${holds ? `empty in about ${round(holds / net, 2)} days` : 'empty from the start'}, after which a draw that lands on its outcome is not made, and gives back that draw’s worth, until more are put in.`);
+    else if (perDay > 0) notes.push(`The stash “${s.name}” starts with ${holds} NFT${holds === 1 ? '' : 's'}, gives about ${round(perDay, 4)} a day (${[...new Set(takes.map((t) => t.by))].join(', ')})${filled}: it keeps up${holds ? '' : ', once the first come in (until then a draw that lands on its outcome is not made)'}.`);
     return { key: s.key, name: s.name, holds, givenPerDay: round(perDay, 6), ...(inPerDay > 0 ? { takenInPerDay: round(inPerDay, 6) } : {}), ...(net > 0 ? { lastsDays: round(holds / net, 4) } : {}) };
   });
   const contestRolls = m.contests.filter((c) => prizeLine(c.prize)?.gives === 'roll');
@@ -851,7 +917,7 @@ export function simulate(economy, { now = 0 } = {}) {
       burned: totals(burned),
       accounts: totals(accounts),
     },
-    fees: { playerSol: PLAYER_FEE, projectSol: PROJECT_FEE, oracleSol: ORACLE, networkPerSignatureSol: NETWORK_FEE, escrowSol: sol(ESCROW_LAMPORTS), ticketLineRentSol: round(TICKET_LINE), collectibleRentSol: COLLECTIBLE_RENT, burnRefundSol: BURN_REFUND },
+    fees: { playerSol: PLAYER_FEE, projectSol: PROJECT_FEE, oracleSol: ORACLE, networkPerSignatureSol: NETWORK_FEE, settleRentUnitSol: sol(SETTLE_RENT_UNIT), ticketLineRentSol: round(ticketLine({})), collectibleRentSol: COLLECTIBLE_RENT, burnRefundSol: BURN_REFUND },
     notes,
   };
 }
@@ -905,9 +971,10 @@ export function explain(sim, economy) {
     const back = b.returnPercent !== null ? `${n(b.expectedBack)} ${sym(b.token)} on average (${n(b.returnPercent)}%)${also.length ? ` and ${also.join(', ')}` : ''}` : `${also.join(', ') || 'nothing'} on average`;
     const all = `; ${inAll(b.realCost)}`;
     lines.push(`Box “${b.name}”: costs ${n(b.price)} ${sym(b.token)} (${all.slice(2)}), gives back ${back}${edge}.`);
-    const part = (o) => (o.gives === 'pay' ? `${n(o.amount)} ${sym(o.token)} from ${o.pool}` : o.gives === 'mint' ? `${n(o.amount)} ${sym(o.token)}, minted` : o.gives === 'share' ? `${o.percent}% of ${o.pool}` : o.gives === 'stash' ? `an NFT of the stash “${o.stash}”, at random` : o.gives === 'nft' ? `the NFT ${String(o.nft).slice(0, 4)}… of “${o.stash}”` : o.gives === 'roll' ? `a roll of “${o.box}”` : o.gives === 'item' ? `${o.item}${o.worth !== null ? ` (worth ${n(o.worth)})` : ' (no value given)'}` : o.gives);
-    for (const o of b.outcomes) lines.push(`  ${n(o.chance)}%: ${o.gives === 'bundle' ? `${o.prizes.map(part).join(' + ')}${o.burns ? ', and the payment burned' : ''}` : part(o)}`);
+    const part = (o) => (o.gives === 'pay' ? `${n(o.amount)} ${sym(o.token)} from ${o.pool}` : o.gives === 'mint' ? `${n(o.amount)} ${sym(o.token)}, minted` : o.gives === 'stash' ? `an NFT of the stash “${o.stash}”, at random` : o.gives === 'nft' ? `the NFT ${String(o.nft).slice(0, 4)}… of “${o.stash}”` : o.gives === 'roll' ? `a roll of “${o.box}”` : o.gives === 'item' ? `${o.item}${o.worth !== null ? ` (worth ${n(o.worth)})` : ' (no value given)'}` : o.gives);
+    for (const o of b.outcomes) lines.push(`  ${n(o.chance)}%: ${o.gives === 'bundle' ? o.prizes.map(part).join(' + ') : part(o)}`);
     if (b.unpriced.length) lines.push(`  Give ${b.unpriced.join(', ')} a "value" to count them in the return.`);
+    if (b.limitedStock) lines.push(`  ${whenOutWords(m.box.get(b.key))}.`);
   }
   for (const it of sim.items) lines.push(`Shop “${it.name}”: ${n(it.price)} ${sym(it.token)}; ${inAll(it.realCost)}.`);
   for (const p of sim.payments) lines.push(`Payment “${p.name}”: ${p.atLeast ? 'at least ' : ''}${n(p.amount)} ${sym(p.token)}; ${inAll(p.realCost)}.`);
@@ -928,10 +995,10 @@ export function explain(sim, economy) {
   for (const g of sim.grants) lines.push(`Grant “${g.name}”: ${n(g.claimsPerDay)} claims a day, each giving ${g.gives}; each claim costs its funds about ${n(g.fundsPerClaimSol)} SOL${g.orderHeldSol ? ` (${n(g.orderHeldSol)} of it the roll’s order, which goes to the winner when it is settled; whoever asks for the roll pays the oracle)` : ''}.`);
   for (const s of sim.stashes ?? []) lines.push(`Stash “${s.name}”: ${s.holds} NFT${s.holds === 1 ? '' : 's'} to start${s.takenInPerDay ? `, about ${n(s.takenInPerDay)} a day come in` : ''}${s.lastsDays !== undefined ? `, given at about ${n(s.givenPerDay)} a day: lasts about ${n(s.lastsDays)} days` : s.givenPerDay ? `, given at about ${n(s.givenPerDay)} a day` : ''}.`);
   for (const r of sim.recipes) lines.push(`Recipe “${r.name}”: ${r.takes.join(' + ') || 'nothing'} → ${r.gives.join(' + ') || 'nothing'}, ${n(r.craftsPerDay)} a day.`);
-  for (const s of sim.schedules) lines.push(`Schedule “${s.key}”: ${s.says}.`);
+  for (const s of sim.schedules) lines.push(`Schedule “${s.key}”: ${s.says}; ${lateRunWords(m.schedules.find((x) => x.key === s.key) ?? {})}.`);
   for (const c of sim.contests) lines.push(`Contest “${c.name}”: ${c.says}.`);
   for (const a of sim.auctions ?? []) lines.push(`Auction “${a.name}”: ${a.says}.`);
-  for (const p of sim.pools) lines.push(`${p.pot ? `The pot of “${p.pot}”` : `Pool “${p.key}”`}: ${n(p.inPerDay)} ${sym(p.token)} in and ${n(p.outPerDay)} out a day from a seed of ${n(p.seed)}; it ${poolFate(p, sim.scenario.days)}.`);
+  for (const p of sim.pools) lines.push(`${p.pot ? `The pot of “${p.pot}”` : p.farm ? `The rewards vault of “${p.farm}”` : `Pool “${p.key}”`}: ${n(p.inPerDay)} ${sym(p.token)} in and ${n(p.outPerDay)} out a day from a seed of ${n(p.seed)}; it ${poolFate(p, sim.scenario.days)}.`);
   const d = sim.perDay;
   const list = (map) => Object.entries(map).map(([k, v]) => `${n(v)} ${sym(k)}`).join(', ') || 'nothing';
   lines.push(`Each day players pay ${list(d.players.pay)} and get back ${list(d.players.getBack)} on average (items at the value you gave them), plus ${n(d.players.playerFeesSol)} SOL in player fees, ${n(d.players.oracleFeesSol)} SOL to MagicBlock’s oracle and ${n(d.players.networkFeesSol)} SOL in network fees.`);

package/js/mcp/tools.mjs

@@ -169,7 +169,7 @@ export function carryIds(previous, next) {
   carry('pools', ['index']);
   for (const list of ['stashes', 'boxes', 'recipes', 'schedules', 'lotteries', 'grants']) carry(list, ['id']);
   // A farm that pays nothing keeps the number of the empty pool made for it; an auction keeps the seller its address names.
-  carry('farms', ['id', 'rewardsIndex']);
+  carry('farms', ['id']);
   carry('auctions', ['id', 'seller']);
   return out;
 }
@@ -449,8 +449,10 @@ export const tools = [
         '  app.collectibles(), app.balances()   what a player does. `listing`: the entry shop(), boxes(), lotteries() or recipes() showed the',
         '  player; its price (or version) is the most they pay: one that moved since is refused, never paid unseen',
         '  a prize (a grant, a lottery place, a contest win, a mission, a recipe) is given in the instruction that wins it,',
-        '  its accounts from loot.prizeMetas({ project, collection, prize, winner, poolMints, items, nft }) (a roll a buy, a craft',
-        '  or a grant claim makes: strict: true, boxes, rollPools, for the box’s prize mints, loot.rollMints); app.claims() finds',
+        '  its accounts from loot.prizeMetas({ project, collection, prize, winner, poolMints, items, nft }) (a roll: its box and',
+        '  its order; ask for it in the same transaction, loot.askRollIx, which fails the whole transaction, SoldOut, when the box',
+        '  has nothing in stock (only the order’s player asks then, a slot later, and that ends the roll with nothing); a write naming a',
+        '  box to roll passes loot.boxesAccounts after it, and the box is written first); app.claims() finds',
         '  what a player is owed. A roll (a prize of a roll, an auction lot, a box) is an order: app.claim / app.collect, or',
         '  loot.askRollIx({ payer, orderAddress, order, box }) then loot.settleIx(...) hands over what it rolled (a stash NFT too)',
         '  loot.stashIx({ signer, project, id, asset, out })           the owner or authority puts an NFT in a stash, or takes one out',
@@ -458,20 +460,24 @@ export const tools = [
         '  app.buyListing(asset, { listing }), app.rentListing(asset, { periods, listing }) (`listing`: what listing() or listings()',
         '  showed the player), app.unlist(asset), app.rentedTo(asset) (one account read)   listings, sale and rent',
         '  app.raffle(id, nft, { price, drawsAt, minSold }), app.unraffle(id, nft)   a raffle from the lottery’s own stash',
-        '  app.compound(key), app.withdraw(key), app.runSchedule(key)   compound, take out unbonded tokens, catch a schedule up',
-        '  app.claims() also lists a raffle’s prize step (given before the money), unbonded tokens, vested runs, a rental over',
+        '  app.compound(key), app.runSchedule(key)   compound, send a schedule that is due (a run missed is missed: only a sealed fixed amount pays every run due)',
+        '  app.farmWalk(key), app.walkFarm(key)   a farm idle past many end times: how many it must walk, and walking them in parts (anyone, free; moves ask for the compute to walk a few themselves)',
+        '  app.claims() also lists a lottery’s parts to pull (a refund, a place, a raffle’s NFT), vested runs, a rental over',
         'Lower level, for what the player module does not cover:',
         '  import * as loot from "@xgamesfun/solana/client";',
         '  loot.pda.project(owner, number), loot.pda.box(project, id), …   every address the program derives',
         '  loot.openBoxIx({ player, project, box, nonce }), loot.buyIx({ player, project, box, items }) …   one builder per instruction; each returns { programId, keys, data }',
         '  loot.payNftIx({ player, project, asset, to })             pay with an NFT (burned, or given to `to`): the app admits by the receipt',
         '  loot.openListingIx / takeListingIx / closeListingIx, loot.listingTerms(listing), loot.pda.listing(project, asset), loot.renterOf(listing, now)',
-        '  loot.lotteryStep(lottery, contribution) then loot.finishLotteryContributionIx(...)   a drawn round’s prizes first, then its money',
-        '  loot.withdrawable(seat, now), loot.runsDue(schedule, now, vaultBalance), loot.pda.vest(schedule), loot.pda.prizeVault(contest), loot.pda.lotteryStash(lottery)',
+        '  a take or a bid signs the record’s terms: loot.listingTerms / offerTerms / auctionTerms(record), the hash of its bytes as read, but what a take changes',
+        '  loot.decodeRound(data), loot.partsOwed(round, entry), loot.commonOwed(round), loot.pullIx(...)   a round’s parts, each pulled in any order (a place’s roll: loot.pullRolls, asked in the same transaction)',
+        '  loot.decodeEnds(data), loot.endsToWalk(farm, ends, now), loot.farmNeedsWalk(farm, ends, now), loot.walkFarmParts({ project, id, farm, ends, now }), loot.pda.ends(farm)   a farm’s record of when seats stop earning',
+        '  loot.orderRefundable(order, slot, now), loot.rollAskable(order, slot, now), loot.lotteryDrawStuck(round, now), loot.lotteryCancellable(round, now)   deadlines, by the chain’s clock',
+        '  loot.runsDue(schedule, now, vaultBalance), loot.scheduleCatchesUp(schedule), loot.pda.vest(schedule), loot.pda.prizeVault(contest), loot.pda.lotteryStash(lottery), loot.pda.rewards(farm)',
         '  loot.decode("LootBox", data), loot.receipts(tx)            accounts, and the receipts of a getTransaction result (none when meta.err is set)',
         'IDL: @xgamesfun/solana/idl.json (Anchor 1.x format).',
         'A page builds the instruction, puts it in a transaction, and asks the player’s wallet (Wallet Standard: Phantom, Solflare, Backpack) to sign and send it. The app never holds a key.',
-        'Reads: the project’s records are plain accounts (loot.decode); every move leaves a receipt in the transaction’s logs (loot.receipts(tx)). A backend delivers only from a finalized transaction whose meta.err is null, once per order or reference: a failed transaction keeps its logs, and they can read as all-success.',
+        'Reads: the project’s records are plain accounts (loot.decode); every move leaves a receipt in the transaction’s logs (loot.receipts(tx)). A backend delivers only from a finalized transaction whose meta.err is null, once per order or reference, and only for a receipt whose data.project is its own (loot.receipts reads every project’s, and anyone can make a project): a failed transaction keeps its logs, and they can read as all-success.',
       ].join('\n');
       return { text: text + footer, ...PROGRAM_INFO };
     },