@xgamesfun/solana 0.20.1 → 0.25.0

package/skills/xsolana-economy/references/after-launch.md

@@ -6,34 +6,41 @@ winner nobody pays.
 
 ## Who sends each step
 
-| Step | Who can send it | If nobody does |
-| --- | --- | --- |
-| A box's roll and settle, a shop buy | the player, in their own purchase (`js/play` does both in one prompt) | anyone can settle a rolled order, a normal item too (the app's backend delivers it from the `OrderSettled` receipt of a finalized transaction whose `meta.err` is null, once per order: `loot.receipts(tx)` gives none for a transaction with an error, whose logs can still read as all-success; it reads the transaction again when its log is truncated); a roll that failed or never came refunds (`app.refund`) |
-| A lottery draw, completing its contributions, paying its places | **anyone**: the page (`app.claims()` lists each available step), or a sweep. Paying a winner with no prize account opens it in the same transaction (the sender pays its rent) | selling stops at draw time. A result must be followed by completion of its contributions and payment of every place before the next round. A round nobody draws waits, with no deadline. If the oracle never answers a draw (7 days after it was asked for), anyone can cancel and refund each recorded buyer. An empty round moves on with the next ticket. A one-time lottery ends after its round |
-| A schedule that is due (an emission, rent, a drip) | **anyone**: the page (`app.runSchedule`), a player, a sweep | it waits, and catches up one run at a time |
-| Ending an auction | **anyone**: usually the winner, from the page | it waits: whenever it is ended, the lot goes to the highest bidder |
-| A contest's entries back when it is off, or its winners' claims | **anyone** (each entry's money goes only to its player) | they wait; nothing is lost |
-| Opening a contest | the **authority** (the owner's wallet by default) | nothing happens |
-| Naming its winner, calling it off | the **authority**, or **anyone** sending a verdict one of its `deciders` signed (a results server's key: `decideIx` with `verdict`, after the Ed25519 check of `verdictBytes`) | after `resultDue` it is off by the clock and everyone claims back; a crowdfund short of its `minPot` when entries close is off at once |
-| Moving tokens out of a pool, minting, a `decisions` payout, rewriting a collectible | the **authority** | nothing happens |
-| A grant claim | the **winner** only, from the page: the winning wallet signs every claim, whatever proves it (a voucher, the list, an open grant); anyone may pay its fees, nobody claims for it | the prize waits for them |
-| A prize given directly (a grant's, a lottery place's, a contest's, a mission's, a recipe's: an item, tokens, an NFT of a stash) | the winner's own claim (a grant's: the winner signs it), the place's payment, the winning entry's claim, the unstake or the craft: it is given in that transaction, the sender paying what it opens (a collectible's rent, the winner's token account) | a grant's claim or a craft of a prize it can't give is refused; a lottery's place, a contest's claim or a mission's end goes on without it (an NFT already given, an item sold out or switched off, a pool short pays what it holds) |
-| A prize that is a roll of a box (a grant's, a lottery's place, a contest's winners, an auction's mystery lot, a mission's chest) | the winner's own claim (a grant's), the place's payment or the auction's end makes the winner's order (its rent goes back to the winner at settle); then **anyone** asks the oracle for the roll (`loot.askRollIx`, its fee the asker's) and **anyone** settles it (`loot.settleIx`), which hands over what it rolled, a stash's NFT included; `app.claims()` lists them | it waits, and is never refunded while it waits; asked and never answered, anyone asks again. What the box gives that has run out (an empty stash, a sold-out item) can't be won: the roll lands on its other outcomes, and a fixed prize its pool runs short of pays what the pool holds |
-| Putting more NFTs in a stash, or taking one out | the **owner** (or the authority), holding them: add them to the stash's `nfts` and publish again (only the new ones go in), or `loot.stashIx` with `out` to any wallet | a stash nobody refills just runs out |
+| Step                                                                                                                             | Who can send it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | If nobody does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A box's roll and settle, a shop buy                                                                                              | the player, in their own purchase (`js/play` does both in one prompt)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | the player, a key the player named for the order (`settler`) or the project's owner or authority settle a rolled order, a normal item too (the app's backend delivers it from the `OrderSettled` receipt of a finalized transaction whose `meta.err` is null, once per order: `loot.receipts(tx)` gives none for a transaction with an error, whose logs can still read as all-success; a truncated log stays truncated when read again, so it then goes by the order's account); a roll that failed or never came refunds (`app.refund`)                                                                                                                                                                                                                             |
+| A lottery draw, then each part pulled                                                                                            | **anyone**: the page (`app.claims()` lists each available step), or a sweep. The draw's ask fixes the round's money (what its places take of the pot, or of the round's own ticket money for a lottery with `rest`; each pool's prize) and opens the next round at once; paid from a pot, it first moves in what the round before left that pot, so the next round always sees it, whoever pulls and whenever. A pull pays one part into its owner's account, opened in the same transaction when it is not there (the sender pays its rent): an entry's own (a refund, a ticket back), its places' part of the pot or their prizes (a raffled NFT, an item, tokens, a roll), or a part owed in common (a share, what the places leave: to the pot, or to `rest`; a burned `rest` stays for the close to burn) | selling stops at draw time. A round nobody draws waits, with no deadline. Once drawn, every part waits in the round for its own pull, in any order, holding up nobody else; the pull that leaves nothing owed closes the round, and the rent of its record goes back to whoever fronted it (the lottery's `roundRent`, or its first buyer). An NFT that can't move is made a hold for its winner. If the oracle never answers a draw (7 days after it was first asked for), the next ask cancels it, and every buyer's refund is pulled; the page pulls the sender's own refund in the cancel's own transaction. A due round's draw rides in front of the next ticket purchase. An empty round moves on with the next ticket. A one-time lottery ends after its round |
+| A schedule that is due (an emission, rent, a drip)                                                                               | the project's owner or authority, or who it pays (a wallet, the treasury): `app.runSchedule` signed by one of them, or their sweep (a sealed burn: anyone)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | **a run missed is missed**: one sent late pays once, for the latest run due, and the runs before it lapse, so keep a key of the project's sending it on time. Only a sealed schedule's fixed amount pays every run due (a backlog of years takes a few calls)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| Ending an auction                                                                                                                | **anyone**: usually the winner, from the page                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | it waits: whenever it is ended, the lot goes to the highest bidder. 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 (`app.auctions()`: `delivered`, `proceedsOwed`), and the next end, anyone's, pays and closes it                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Catching a farm up (`walk_farm`), when it has passed more of its seats' end times than a move can walk                           | **anyone**, for free: `app.claims()` lists it, `app.walkFarm(key)` sends it in parts (`app.farmWalk(key)` says how many)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | moves of that farm fail until it is walked; nothing is lost by the wait: what each seat earned by its end is exact                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| A contest's entries back when it is off, or a winner's part of a contest with no prize or picks                                  | **anyone** (each entry's money goes only to its player); a winner's first claim with a prize or picks: the **winner or the project's keys**, and past 30 days the project's keys may pick for them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | they wait; nothing is lost. Each winner's part is written at the decision (the pot then, and a split prize's vault), so the order of claims changes nothing; tokens sent to the pot after it go to nobody (burned at the close), and a split prize's part a winner gives up goes back to its pool, not to later winners                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Opening a contest                                                                                                                | the **authority** (the owner's wallet by default)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | nothing happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Naming its winner, calling it off                                                                                                | the **authority**, or **anyone** sending a verdict one of its `deciders` signed (a results server's key: `decideIx` with `verdict`, after the Ed25519 check of `verdictBytes`); a winner only once entries close, a call-off any time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | after `resultDue` it is off by the clock and everyone claims back; a crowdfund short of its `minPot` when entries close is off at once                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Moving tokens out of a pool, minting, a `decisions` payout, rewriting a collectible                                              | the **authority**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | nothing happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| A grant claim                                                                                                                    | the **winner** only, from the page: the winning wallet signs every claim, whatever proves it (a voucher, the list, an open grant); anyone may pay its fees, nobody claims for it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | the prize waits for them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| A prize given directly (a grant's, a lottery place's, a contest's, a mission's, a recipe's: an item, tokens, an NFT of a stash)  | the winner's own claim (a grant's: the winner signs it), the place's payment, the winning entry's claim, the unstake or the craft: it is given in that transaction, the sender paying what it opens (a collectible's rent, the winner's token account)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | a grant's claim or a craft of a prize it can't give is refused; a lottery's place, a contest's claim or a mission's end goes on without it (an NFT already given, an item sold out or switched off, a pool short pays what it holds)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| A prize that is a roll of a box (a grant's, a lottery's place, a contest's winners, an auction's mystery lot, a mission's chest) | the winner's own claim (a grant's), the place's payment or the auction's end makes the winner's order (its rent goes back to the winner at settle); then the **winner or the project's keys** ask the oracle for the roll (`loot.askRollIx`, its fee the asker's) and the winner, a key the winner named, or the project's keys settle it (`loot.settleIx`), which hands over what it rolled, a stash's NFT included; `app.claims()` lists them                                                                                                                                                                                                                                                                                                                                                                | it waits, and is never refunded while it waits; asked and never answered, they ask again. What the box gives that has run out (an empty stash, a sold-out item) can't be won: the roll lands on its other outcomes, and a fixed prize its pool runs short of pays what the pool holds. With nothing at all in stock, only the winner asks, and that ends the roll with nothing (an auction's mystery lot: the winning bid refunded); a roll whose answer finds nothing at all waits again, for a restock                                                                                                                                                                                                                                                              |
+| Putting more NFTs in a stash, or taking one out                                                                                  | the **owner** (or the authority), holding them: add them to the stash's `nfts` and publish again (only the new ones go in), or `loot.stashIx` with `out` to any wallet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | a stash nobody refills just runs out                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
 "Anyone" means the page can offer a button for it, and any player can press it. Build those buttons with `js/play`:
-`app.claims()` lists what this player can finish now (a draw, its completion or cancellation, a payout, a refund, an
+`app.claims()` lists what this player can finish now (a draw, its cancellation, a pull, a payout, a refund, an
 auction to end), and `app.claim(c)` sends one. A **sweep** is a server that sends overdue public steps for the
 projects it watches. One may or may not be running for the person's project, so never rely on it: the page's buttons
-are what finish them. A sweep never needs anyone's key but its own fee payer.
-
-A lottery's ticket payments stay separate from the prize pot until the draw succeeds: cuts, referrals and burns run
-after it. The buyer's share recipients are fixed when they buy; completing a successful contribution sends its shares
-and its prize funding. Cancelling instead (only for a draw the oracle never answered) returns its entire ticket
-payment and record rent to the recorded buyer, with no ticket split or burn; network and oracle fees stay spent. Prizes and
-outside donations already in the prize pot stay there for the lottery; they are not ticket refunds. Each purchase is
-a record of its own whose rent goes back to its buyer once it is completed (a winning one once its places are paid),
-so a round has no limit on buyers.
+are what finish them. A sweep needs only its own fee payer for draws, refunds and returns; to settle or run a schedule, it needs a project key or a key the player named.
+
+A round of a lottery is a record of its own, opened by its first purchase (the SOL the lottery holds for it,
+`roundRent`, put in at setup by default and sized from the lottery's expected rounds and entries, pays its header, its
+token accounts and each entry's bytes; with too little, its first buyer fronts the header and accounts, about 0.004 SOL
+and up, and each buyer their entry; all back when the round closes, to whoever paid), and it holds its ticket money in
+accounts of its own until each part is pulled: shares in common and burns run after the draw, and the pot holds only
+what nobody is owed. While a round paid from a pot waits for the oracle, the next round's draw waits too: it needs that
+round's answer to know what it left the pot. Each purchase adds an entry: funded by `roundRent`, the buyer pays only the fee and the price; a
+buyer who pays its bytes themselves (about 0.0002 SOL) never gets them back (they go to the treasury when the round
+closes). A share the
+buyer chooses (a referrer) is paid as they buy. Cancelling (only for a draw the oracle never answered, or a round short of its least sale) owes every entry its
+whole ticket payment back, with no split or burn; network and oracle fees stay spent. Prizes and outside donations
+already in the pot stay there for the lottery; they are not ticket refunds. A round holds about 70,000 to 260,000
+purchases, by how wide its entries are.
 
 Every account a payment goes to is opened by the transaction that pays it, and whoever sends it pays the rent: the
 treasury's or a payee's account at a settle, a winner's at a payout, an outbid bidder's at the next bid. Nothing waits
@@ -47,12 +54,14 @@ methods). What the project writes about one (a level, a use) goes in its Sheet (
 the authority with `collectible` `Set`, by a farm's growth, or by anyone proving the traits the project vouched for
 (`app.proveTraits`).
 
-A new mission is a new farm: add it to the spec and publish again; `runs` ends it that long after it goes live. Near the end of a farm that shares its pool, fund it at least its release span (its longest lock, a day at least) before the end and refresh any seat you suspect is dead a span before it: what is not released by the end, and what a seat gives back after it, stays in the pool, the project's. If rewards cannot move, unstaking can explicitly forfeit them.
+A new mission is a new farm: add it to the spec and publish again; `runs` ends it that long after it goes live. Near the end of a farm that shares what lands, fund it at least its release span (its longest lock, a day at least) before the end: what is not released by the end, and what a seat forfeits after it, stays in its rewards vault, where the authority may take back what is free (`loot.moveTokensIx` with `from: { Farm: [id] }`), never what the farm owes its seats. No seat needs a refresh at its end. If rewards cannot move, unstaking can explicitly forfeit them.
 
-Changing a live box's roll (its outcomes, odds, `stockOdds`, `rollsOn`, `then`) fails every roll of it still waiting
-(`W-LIVE-ROLLS`): a purchase gets its payment back, but a roll won on another route (a grant's, a mission's chest, a
-lottery's place, an auction's lot) paid nothing in and refunds 0. Publish such a change once none waits, or make a new
-box. Its price, rise, fall, split, switch, window and gate change freely. A set's way out (the recipe that unbinds it)
+Changing a live box's roll (its outcomes, odds, `stockOdds`, `whenOut`, `rollsOn`, `then`) fails a purchase still waiting for its
+roll, and an auction's roll lot, each of which gets its payment back at once (`W-LIVE-ROLLS`). Any other roll waiting (a
+grant's, a mission's chest, a lottery's place, a recipe's) holds no payment and rolls on the box as edited: nothing spent is
+lost. A roll asked and left unanswered 7 days can be refunded when it holds a payment or an NFT (its refund names the
+box, whose count of draws waiting it leaves: `app.refund` does). A box that stops selling when an outcome runs out (the
+default) sells again once the project restocks it (more units, tokens into its pool, NFTs into its stash) or edits it. Its price, rise, fall, split, switch, window and gate change freely. A set's way out (the recipe that unbinds it)
 should take no `pay` line (`W-UNBIND-PAY`): a recipe with one waits while the project is paused or the platform
 suspends it, and the pieces stay locked in their farm meanwhile.
 
@@ -77,12 +86,21 @@ the winner claims themselves. The grant's limits (per wallet in all and per wind
 total, between two dates) are the most anything can ever pay out, whatever happens to a server.
 
 - **A list** (an airdrop, a known set of winners): the owner writes the wallets in the grant's `list`; no server.
-- **Promo codes, claim links**: the grant's `keys` are the public keys of one keypair per code (made offline from each
-  code; only public keys go in the spec), with `limits.perKey: 1`. The player types the code; the page derives its
-  keypair, signs a voucher for the player's own wallet, and claims (`app.claimGrant(key, { voucher })`). A code pays
-  once in all; a signature someone copies pays only the wallet it names.
+- **Promo codes, claim links**: make the codes with `makeCodes(n)` (`@xgamesfun/solana/results`: 80 bits each, never
+  fewer than 64, since each code's key is public in the spec and a short code can be found by trying them all
+  offline) and put `await codeAddresses(codes)` in the grant's `keys`, with `limits.perKey: 1`. Keep the codes out of
+  the repository. The player types a code; the page makes `codeVoucher({ code, game, grant, incarnation, wallet,
+now })` for the player's own wallet and claims (`app.claimGrant(key, { voucher })`). A code pays once in all; a
+  signature someone copies pays only the wallet it names.
 - **Show a badge, claim once**: an open grant (no `vouchers`, `keys` or `list`) with a `gate` and `limits.perWallet`:
   any wallet that shows the collectible claims, and each collectible shown counts too. No server.
+- **A wallet is not a person.** Wallets are free, so a per-wallet limit never limits a person, and a game runs in the
+  player's browser, so its own claims prove nothing. For a reward worth farming: the server decides or checks the
+  result; it pays only a wallet the player proved (`proofRequest` / `verifyProof` from `@xgamesfun/solana/results`: a
+  text the wallet signs, with the game, a nonce the server takes once, and an expiry); it counts people where it can
+  (`perPerson`, with a person hash the voucher names: that needs an outside sign-in such as X, and a wallet-only
+  player has none); it checks what a wallet holds on the chain, never the page's word (`collectiblesOf`, `holds`); and
+  the grant's `perDay` and `total` bound everything whatever happens to a key. Keep token rewards for results small.
 - **Vouchers from a results server**: the grant names the server's public key in `vouchers`; the server checks the
   game's result and signs a voucher (for a grant of tokens, with each winner's own `amount`, up to the grant's: rewards
   by rank); the winner's page claims with it (`app.claimGrant(key, { voucher })`).
@@ -101,11 +119,13 @@ total, between two dates) are the most anything can ever pay out, whatever happe
 - **A random draw nobody can rig** (a free draw for members): a results server's computed draws (drand), or a lottery.
 
 Per wallet per day ("2 wins a day each") uses `limits.perWalletEach: { "count": 2, "every": "1d" }`;
-`perDay` separately counts all wallets together. A wallet can claim at most 256 distinct signed voucher rounds
-within one grant incarnation, in any order. Plan a new campaign when that bound would be exceeded; changing
-limits or voucher keys does not clear its history. Closing and recreating a grant starts a new campaign with new
-receipts and invalidates old vouchers. A list written in xsolana.json pays each wallet once per grant incarnation: editing it lets newly added wallets
-claim, never a wallet already paid (for repeated payouts, list the wallet again under a new `round`, or use vouchers). A results server must read the current grant incarnation when accepting
+`perDay` separately counts all wallets together. A grant keeps every round it paid each wallet within one incarnation,
+16 bytes a round (from the grant's funds), and each wallet's count in 28: one voucher may name several rounds, each
+paid once, and the same voucher sent again later pays what a limit held back. Changing limits or voucher keys does not
+clear its history. Closing and recreating a grant starts a new campaign with new records and invalidates old vouchers;
+anyone may then close the old records (`loot.closeShardIx`), their rent to the owner. A grant for more than about
+100,000 wallet-rounds names `wallets` (and `rounds`) so its records are kept in enough lists. A list written in xsolana.json pays each wallet once per grant incarnation: editing it lets newly added wallets
+claim, never a wallet already paid (for repeated payouts, list the wallet again under a new `round`, or use vouchers). A list leaf names no grant or incarnation, so a grant closed and made again with the same list pays every listed round again: give a re-made grant a fresh list (new rounds); the approval page warns when a change does that. A results server must read the current grant incarnation when accepting
 a result and include it in the voucher it signs.
 
 ## Before you act on what the person says happened

package/skills/xsolana-economy/references/apps.md

@@ -12,82 +12,117 @@ npm install @xgamesfun/solana
 ```js
 import { solanaApp, walletStandardSigner } from '@xgamesfun/solana/play';
 
-const spec = await (await fetch('./xsolana.json')).json();        // the live spec, served with the page
+const spec = await (await fetch('./xsolana.json')).json(); // the live spec, served with the page
 
 // Connect a wallet (Phantom, Solflare, Backpack all register through the Wallet Standard).
 const wallets = [];
-const api = { register: (...w) => { wallets.push(...w); return () => {}; } };
+const api = {
+  register: (...w) => {
+    wallets.push(...w);
+    return () => {};
+  },
+};
 window.addEventListener('wallet-standard:register-wallet', ({ detail }) => detail(api));
 window.dispatchEvent(Object.assign(new Event('wallet-standard:app-ready'), { detail: api }));
-const wallet = wallets.find((w) => w.chains.some((c) => c.startsWith('solana:')));
-const { accounts: [account] } = await wallet.features['standard:connect'].connect();
+const wallet = wallets.find(w => w.chains.some(c => c.startsWith('solana:')));
+const {
+  accounts: [account],
+} = await wallet.features['standard:connect'].connect();
 
 const app = solanaApp({ spec, rpcUrl: 'https://api.devnet.solana.com', wallet: walletStandardSigner(wallet, account) });
 
-const shop = await app.shop();            // [{ key, name, price, priceUnits, currency, active, left }]
-await app.buy('badge', { listing: shop.find((l) => l.key === 'badge') });  // the price shown is the most it pays
-const boxes = await app.boxes();          // each box's price and outcome chances
-await app.openBox('chest', { listing: boxes.find((l) => l.key === 'chest') }); // pays, waits for the roll, settles
-await app.pay('entry');                   // a payment of the spec
+const shop = await app.shop(); // [{ key, name, price, priceUnits, currency, active, left }]
+await app.buy('badge', { listing: shop.find(l => l.key === 'badge') }); // the price shown is the most it pays
+const boxes = await app.boxes(); // each box's price, outcome chances and whenOut (show it: stops selling, or draws among what is left)
+await app.openBox('chest', { listing: boxes.find(l => l.key === 'chest') }); // pays, waits for the roll, settles
+await app.pay('entry'); // a payment of the spec
 const lotteries = await app.lotteries(); // [{ key, name, price, currency, status, round, sold, drawsAt, nftTicket, … }]
-await app.buyTickets('weekly', 2, { listing: lotteries.find((l) => l.key === 'weekly') }); // an NFT ticket: { nft: asset, listing }
+await app.buyTickets('weekly', 2, { listing: lotteries.find(l => l.key === 'weekly') }); // an NFT ticket: { nft: asset, listing }
 await app.payNft(asset, { to, reference }); // pay with an NFT (burned, or given to `to`): admit the player by the receipt
-await app.stake('farm', '10', 0);         // tokens, at lock tier 0;  app.stakeNft('farm', asset) for a collectible
-await app.harvest('farm');                // rewards;  app.unstake('farm', '10') once the lock has run
-await app.staked('farm');                 // the player's seats: [{ asset, amount, freeAt, boostPercent, waiting, rewards }]
-await app.refresh('guild', asset);        // a farm with growth: writes the NFT's points and level now (anyone may)
-const recipes = await app.recipes();      // [{ key, name, active, version }]
-await app.craft('merge', [assetA, assetB], 1, { listing: recipes.find((r) => r.key === 'merge') });  // a changed recipe is refused
-await app.auctions();                     // each auction: high, nextBid, leading, secondsLeft, open, over, waiting (SOL)
-await app.bid('comet', '0.6');           // the bid it tops goes back to its bidder in the same transaction
-await app.endAuction('comet');           // once it is over, anyone: the lot to the winner { winner, asset? }
-await app.unwrap();                       // SOL back from a bid that was topped, from wrapped SOL to plain SOL
-await app.claimGrant('welcome');          // a wallet on the grant's list (or { voucher } from your server)
-await app.claimWins({ server, token });   // every prize a results server vouched for or listed, claimed by the winner; [{ round, signature | error }]
-                                          // (`token`: the player's sign-in with that server, when it asks for one: a stash drop's NFT is given only at a signed-in claim)
+await app.stake('farm', '10', 0); // tokens, at lock tier 0;  app.stakeNft('farm', asset) for a collectible
+await app.harvest('farm'); // rewards;  app.unstake('farm', '10') once the lock has run
+await app.staked('farm'); // the player's seats: [{ asset, amount, freeAt, boostPercent, waiting, rewards }]
+await app.refresh('guild', asset); // a farm with growth: writes the NFT's points and level now (anyone may)
+const recipes = await app.recipes(); // [{ key, name, active, version }]
+await app.craft('merge', [assetA, assetB], 1, { listing: recipes.find(r => r.key === 'merge') }); // a changed recipe is refused
+await app.auctions(); // each auction: high, nextBid, leading, secondsLeft, open, over, waiting (SOL)
+await app.bid('comet', '0.6'); // the bid it tops goes back to its bidder in the same transaction
+await app.endAuction('comet'); // once it is over, anyone: the lot to the winner { winner, asset?, rolled? }
+await app.unwrap(); // SOL back from a bid that was topped, from wrapped SOL to plain SOL
+await app.claimGrant('welcome'); // a wallet on the grant's list (or { voucher } from your server)
+await app.claimWins({ server, token }); // every prize a results server vouched for or listed, claimed by the winner; [{ round, signature | error }]
+// (`token`: the player's sign-in with that server, when it asks for one: a stash drop's NFT is given only at a signed-in claim)
 const loan = await app.loanOffer(lender, 1); // a lender's offer: { amount, repay, lasts, risks }: show every risk's `says`
 await app.borrow(lender, 1, asset, { acceptRisks: true }); // only once the player saw the risks (refused without it)
-for (const c of await app.claims()) await app.claim(c);   // what this player can finish: a roll to collect, a refund,
-                                          // a contest payout, a due draw, an auction to end
-await app.runSchedule('drip');            // a schedule that is due (anyone may run it); null when not yet
-await app.collectibles();                 // what the player owns: [{ asset, item, name, uri, attributes }] (`item`: its key)
-await app.balances();                     // what they hold of each of the economy's tokens
+for (const c of await app.claims()) await app.claim(c); // what this player can finish: a roll to collect, a refund,
+// a contest payout, a due draw, an auction to end
+await app.runSchedule('drip'); // a schedule that is due (the project's keys or who it pays); null when not yet. A run missed is missed: only a sealed fixed amount pays every run due
+await app.farmWalk('guild'); // { ends, needsWalk, parts }: end times the farm has passed; a move refuses (FarmNeedsWalk) past what it can walk
+await app.walkFarm('guild'); // walks it in parts (anyone, free); claims() lists it when it is needed
+await app.collectibles(); // what the player owns: [{ asset, item, name, uri, attributes }] (`item`: its key)
+await app.balances(); // what they hold of each of the economy's tokens
 ```
 
 - **Serving it**: a plain `index.html` with a `<script type="module">` can't import a bare `@xgamesfun/solana/play` by
   itself. Either use a bundler (Vite: `npm create vite@latest`, then `npm install @xgamesfun/solana`), or put this import
   map before the module script and serve the folder (`npx serve .`):
   ```html
-  <script type="importmap">{ "imports": {
-    "@xgamesfun/solana/play": "./node_modules/@xgamesfun/solana/js/play/index.js",
-    "@xgamesfun/solana/client": "./node_modules/@xgamesfun/solana/js/client/index.js"
-  } }</script>
+  <script type="importmap">
+    {
+      "imports": {
+        "@xgamesfun/solana/play": "./node_modules/@xgamesfun/solana/js/play/index.js",
+        "@xgamesfun/solana/client": "./node_modules/@xgamesfun/solana/js/client/index.js"
+      }
+    }
+  </script>
   ```
   Tell the person the one command that starts it, and that it serves on devnet.
 - **What a roll looks like**: a box of several outcomes is rolled by the oracle a few seconds after the open; `openBox`
   waits for it. Show the player that it is rolling.
+- **A page that closes before the settle**: the SOL its settle key holds is not lost in the same browser (on another device, with nothing stored, it can't be found yet). Build the wallet with
+  `walletStandardSigner(wallet, account)`: with a wallet that signs messages, the page asks once a session for a
+  signature over a fixed text ("loot: the keys that settle your orders…"; it moves nothing), and every settle key comes
+  from it, so a reload makes it again. With one that signs no messages, the key is kept in the page's storage,
+  encrypted. Call `app.recover()` when the page opens (after the wallet connects): it settles what rolled, sends back
+  what a key holds for an order that is gone, and leaves one still rolling for later. Say so to the player in a line
+  ("Finishing an earlier purchase…").
+- **Packs**: `app.openBox(key, { listing, count: 10 })` opens ten packs in one purchase: one wallet prompt, one oracle
+  answer, `maxPrice` a pack's. It returns `won` (every card) and `assets`; a pack too big for one transaction is
+  settled in parts, each its own transaction (`parts`: their signatures), sent by the throwaway key the purchase funds (`oneSignature`, the default),
+  so the player signs once. More packs than one oracle answer draws (or than keep an order's rent and fee within 0.01
+  SOL: `loot.opensAnOrder(box)`) are several orders in that one purchase (`orders`). A pack of fixed cards (one outcome, nothing random) is bought in one step: its cards come
+  in the purchase, no oracle and no settle (one too big for a transaction is opened instead).
+- **A roll a route makes** (a craft, a bundle bought, a grant claimed, an auction won): the page asks for it in the
+  route's own transaction and settles it after with a throwaway key, so the player signs once. When the rolled box has
+  nothing in stock, nothing is sent and the call rejects with SoldOut: tell the player to try again later. A compressed card's id is not in `assets` (it is the tree's count when minted): read it
+  from `claims()` or the player's assets. Show each card as it lands.
 - **What an auction looks like**: show the high bid, the least next bid (`nextBid`) and a countdown (`secondsLeft`;
   a late bid moves the end, so read `auctions()` again after every bid). A player who was outbid has their bid back
   already, nothing to claim: in SOL it waits in their wrapped-SOL account (`waiting`), so say "You were outbid:
   0.5 SOL is back in your wallet" and offer `unwrap()` to turn it into plain SOL (any later purchase does it too).
   When `over` is true, show an "End the auction" button to everyone (the winner usually presses it; it mints or
-  hands over the lot). There is no deadline: however late it is ended, the lot goes to the highest bidder.
+  hands over the lot). There is no deadline: however late it is ended, the lot goes to the highest bidder. An auction with
+  `delivered` has given its lot, and still owes its seller, whose account couldn't take the money (`proceedsOwed`): keep it
+  on the seller's page until an end (`app.endAuction`, anyone's) pays and closes it. Don't treat it as closed at its end.
 - **NFTs the project has no authority over**: a gate or odds that name a collection find the player's Core NFTs of it
   themselves; for a Token Metadata NFT pass `shown: { mint, owner }`, for a compressed one `shown: { compressed:
-  assetId, tree }` after a `loot.proveLeafIx` in the same transaction. `app.stakeNft`, `app.unstakeNft`, `app.refresh`,
+assetId, tree }` after a `loot.proveLeafIx` in the same transaction. `app.stakeNft`, `app.unstakeNft`, `app.refresh`,
   `app.harvest`, `app.hold` and `app.endAuction` take any NFT: a Core asset, a Token Metadata mint (legacy or pNFT),
   or a compressed NFT's asset id; the page finds its kind itself, and proves a compressed one first (its RPC must
   offer DAS: `getAsset`, `getAssetProof`). In a farm that watches, `app.harvest` shows the NFT is still the player's,
   and `app.stakeNft` of an NFT someone else staked and sold takes their seat over. What the project wrote about one is in
   its Sheet (`loot.decodeSheet`).
 - **Off-chain traits** (the spec's `traits`): the project builds the tree with `loot.traitsTree([{ nft, attributes
-  }])` from its NFTs' metadata and publishes each NFT's `attributes` and `proof` with the page; a player (or the page,
+}])` from its NFTs' metadata and publishes each NFT's `attributes` and `proof` with the page; a player (or the page,
   before a stake) calls `app.proveTraits(nft, attributes, proof)` once per NFT, and its boosts and gates read them.
 - **Rolls on an NFT**: `app.openBox(boxKey, { on: asset })` for a box that rolls on one (an enchant). Leaving a
-  mission that rolls, `app.unstakeNft` returns `{ signature, roll }`; a recipe that rolls, `app.craft` returns `roll`.
-  `app.collect(roll)` asks the oracle when nobody has yet (`app.askRoll`), waits and settles it: show what it gave
-  (`won`, each prize the roll set aside, and `order.fate`: the numbers moved and where the NFT went). A page should offer to collect any
-  roll of the player's still waiting.
+  mission that rolls, `app.unstakeNft` returns `{ signature, roll, rolled }`; a recipe that rolls, `app.craft` returns
+  `roll` and `rolled`; a grant that gives a roll, `app.claimGrant` returns `{ signature, rolls }`; the winner ending an
+  auction of a roll, `app.endAuction` returns `rolled`. Each asks the oracle in the player's one transaction, and a
+  throwaway key that transaction funds settles it: one prompt. `rolled` (and each of `rolls`) is what the roll gave
+  (`won`, each prize it set aside, and `order.fate`: the numbers moved and where the NFT went). When the step and its
+  ask can't go together, the roll waits: `app.collect(roll)` asks for it, waits and settles it, and a page should offer
+  to collect any roll of the player's still waiting.
 - **What a staking page shows**: `app.staked(farmKey)` lists the player's seats in a farm, each with what it is owed
   now (`waiting`, in `rewards`), the program's own sum from a dry run of the seat (nothing signed or sent), and
   when its lock is over (`freeAt`). Show that; don't work out rewards from the rate yourself (a sharing farm splits
@@ -95,24 +130,27 @@ await app.balances();                     // what they hold of each of the econo
   or a harvest.
 - **Getting out of a farm**: after the farm lock ends, `app.unstakeNft(farmKey, asset)` releases the collectible;
   `app.unstake(farmKey, amount)` returns tokens. If reward transfers are blocked, offer an explicit choice to give
-  up rewards with `{ forfeit: true }` as the last argument. Remove a token seat's booster before withdrawing all
-  its tokens. Forfeiting does not bypass the lock or the token's or NFT issuer's own controls: say which custody
+  up rewards with `{ forfeit: true }` as the last argument. Remove a token seat's booster before taking out all
+  its tokens. An early exit (a tier's `exitFee`) keeps the rewards the seat was credited; what is taken out leaves at
+  once (no unbonding wait). Forfeiting does not bypass the lock or the token's or NFT issuer's own controls: say which custody
   the farm uses and never promise an unconditional exit (`telling-the-person.md`, NFT custody).
 - **Farm token hooks and Core adapters**: `stake`, `unstake`, `stakeNft`, `unstakeNft`, and `harvest` accept
   `extra` account metas or `transfers` keyed by mint in their options. Static Token-2022 hooks and required memos
   resolve automatically. For dynamic hooks, provide every actual `{ source, destination, authority, amount }`
-  transfer: reward pool to vault, then vault to player when the action pays; token principal too when it moves.
-  Incoming transfer fees reduce reward credit before calculating the payout. Do not guess amounts from the gross
-  pool balance. Without that plan the app fails before signing; refresh the plan if balances or fee terms change.
+  transfer: the farm's rewards vault to the player when the action pays (crediting moves no tokens); token principal
+  too when it moves. Do not guess amounts from the vault's balance. Without that plan the app fails before signing; refresh the plan if balances or fee terms change.
   Explicit `extra` replaces automatic resolution and must include all hook, memo and Core adapter accounts.
   For example, `app.unstakeNft('heroes', asset, { transfers: { [rewardsMint]: rewardTransfers } })`, or
   `app.unstakeNft('heroes', asset, { extra: adapterAndTokenAccounts })`. Harvest takes options third:
   `app.harvest('heroes', asset, { transfers: { [rewardsMint]: rewardTransfers } })`.
   A forfeit exit skips reward-mint reads and reward ATA creation; principal transfers still need their own mint.
-- **Lottery steps**: `claims()` lists a due draw, the completion of its recorded tickets, each place's prize, and,
-  for a draw the oracle never answered, the cancel-and-refund (`after-launch.md` says how the money moves). Show each
-  as a button and read the list again after each one: a drawn round's tickets must be completed before its winners
-  collect.
+- **Lottery steps**: `claims()` lists a due draw (`reveal`), what this player is owed (`pull`), paying everyone else
+  and the shares owed in common (`payout`), and for a draw the oracle never answered, asking again or, after its
+  timeout, the cancel-and-refund (`cancel-draw`; `after-launch.md` says how the money moves). A draw that cancels the
+  round (that one, or a `reveal` of a round short of its least sale) pulls the sender's own refund in the same
+  transaction. A ticket bought when the round's draw is due sends the draw first, in the same prompt, and buys into
+  the next round (the buyer pays the oracle's 0.0008 SOL for it). Show each as a button
+  and read the list again after each one. The parts are pulled in any order: nobody waits on anyone else.
 - **Gates**: a gated buy, ticket, stake, entry, bid or claim finds the player's collectible that passes the gate by
   itself ("You need a Guild Pass to buy this" when there is none). Use `collectibles()` and its `item` key to show
   what a player holds; never match NFTs by name. A list gate (`{ "list": [...] }`) takes the player's proof: the
@@ -120,8 +158,17 @@ await app.balances();                     // what they hold of each of the econo
   power of two as the plan's root does), or takes it from a server that keeps a long list. A stake gate
   (`{ "staked": … }`) needs nothing from the page: js/play passes the player's seat and the farm, and says plainly when
   the stake is too small or its lock is over (show the farm's locked tiers next to the gate).
-- **A no-loss lottery** (`noLoss`): completing the draw sends every ticket back to its buyer (anyone may complete
-  it, so say "your tickets come back after the draw"), and the winners then collect the pot.
+- **A no-loss lottery** (`noLoss`): once the round is drawn every ticket is owed back to its buyer (a pull, which
+  anyone may send, so say "your tickets come back after the draw"), and the winners then collect the pot.
+- **A lottery round** finishes in a few steps whatever its size: `app.claims()` lists the draw (`reveal`, whose ask
+  fixes the round's money and opens the next round at once), what this player is owed (`pull`: a refund, a place's
+  part of the pot, its prize; a raffled NFT; a roll asked for in the same transaction and settled in the same prompt)
+  and paying everyone else and the parts owed in common (`payout`); `app.claim(c)` sends one. The last pull closes
+  the round.
+- **Repaying a loan** (the player's own, or a friend's): `app.loan(asset, due)` reads it; show its `repay` (base units
+  of its `mint`), then `app.repay(asset, due, { repay })` pays exactly that, in the payer's one prompt (a loan whose
+  debt changed since is refused); a throwaway key that transaction funds sends the NFT home to its borrower, a pNFT's
+  or a compressed NFT's too (one prompt). A lender sees an overdue unpaid loan in `claims()` (`release`, to them).
 - **A grant that pays by rank**: a voucher with an `amount` (base units of the grant's token) pays that much, up to
   the grant's; `app.claimGrant(key, { voucher })` passes it, and `{ proof, round, personHash, amount }` for a list.
 - **The price the player saw is the most they pay**: `app.buy` and `app.openBox` need the listing `shop()` or