@xgamesfun/solana 0.20.1 → 0.24.0

package/js/play/keys.js

@@ -0,0 +1,167 @@
+// The throwaway keys js/play settles with (the key job rule, AGENTS.md), made so a page that closes in the middle of a
+// job can find them again and finish it, or send their SOL back.
+//
+// A key is named by the account its job is about (an order, a hold). With a wallet that signs messages, every key comes
+// from one signature of the wallet's over a fixed text naming the project and the wallet, asked once a session: the
+// key's seed is sha256("loot settle key" | that signature | the name). Ed25519 signatures are deterministic, so after a
+// reload the same signature gives the same keys. A wallet that signs no messages, or whose signature of the text
+// changes from one session to the next (some MPC wallets), gets a random key instead, kept in the page's storage
+// encrypted with a device key the page can use but never read out (WebCrypto, IndexedDB); with no such storage, in
+// memory only, as before.
+import { addressBytes, encodeBase58 } from '../chain/base58.js';
+import { concat, fromBase64, randomBytes, toBase64, toHex, utf8 } from '../chain/bytes.js';
+import { sha256 } from '../chain/sha256.js';
+
+/** The PKCS #8 header of a raw 32-byte Ed25519 seed (RFC 8410). */
+const PKCS8_ED25519 = Uint8Array.from([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20]);
+
+const DERIVED = 'derived';
+const fromBase64Url = (text) => fromBase64(text.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(text.length / 4) * 4, '='));
+
+/** An Ed25519 key from its 32-byte seed: { address, sign(message) }. */
+export async function keyFromSeed(seed, name = null) {
+  const subtle = globalThis.crypto.subtle;
+  const pkcs8 = concat(PKCS8_ED25519, seed);
+  const jwk = await subtle.exportKey('jwk', await subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']));
+  const signer = await subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, false, ['sign']);
+  return { address: encodeBase58(fromBase64Url(jwk.x)), name, sign: async (message) => new Uint8Array(await subtle.sign('Ed25519', signer, message)) };
+}
+
+/** The text a wallet signs once a session for its settle keys. It moves nothing and says so. */
+export const settleKeysText = (project, wallet) =>
+  `loot: the keys that settle your orders\nproject ${project}\nwallet ${wallet}\n\nSigning this moves nothing. A page that closes before it settles makes the same key again from it, to finish or send your SOL back.`;
+
+/**
+ * The page's storage of keys that can't be made again (`localStorage`), and a device key that encrypts them, kept in
+ * IndexedDB as a non-extractable AES-GCM key. Null where either is missing (then keys live in memory only).
+ */
+export function browserStore() {
+  const ls = globalThis.localStorage;
+  if (!ls || !globalThis.indexedDB) return null;
+  let device = null;
+  return {
+    get: (k) => ls.getItem(k),
+    set: (k, v) => ls.setItem(k, v),
+    remove: (k) => ls.removeItem(k),
+    keys: () => Array.from({ length: ls.length }, (_, i) => ls.key(i)).filter(Boolean),
+    cryptoKey: () => (device ??= deviceKey().catch(() => null)),
+  };
+}
+
+async function deviceKey() {
+  const db = await new Promise((resolve, reject) => {
+    const r = globalThis.indexedDB.open('loot-keys', 1);
+    r.onupgradeneeded = () => r.result.createObjectStore('keys');
+    r.onsuccess = () => resolve(r.result);
+    r.onerror = () => reject(r.error);
+  });
+  const found = await new Promise((resolve, reject) => {
+    const r = db.transaction('keys').objectStore('keys').get('device');
+    r.onsuccess = () => resolve(r.result ?? null);
+    r.onerror = () => reject(r.error);
+  });
+  if (found) return found;
+  const key = await globalThis.crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+  await new Promise((resolve, reject) => {
+    const tx = db.transaction('keys', 'readwrite');
+    tx.objectStore('keys').put(key, 'device');
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+  return key;
+}
+
+/**
+ * The keys of `wallet` ({ address, signMessage? }) in `project`. `store`: `browserStore()`'s shape ({ get, set, remove,
+ * keys, cryptoKey }), or null. `key(name)` makes the key named by an address (asking the wallet for its signature the
+ * first time in a session); `again(name)` makes it again for a job left unfinished, or finds it stored, or null;
+ * `stored()` lists the names of keys stored; `forget(name)` drops a stored key once its job is done and it is empty.
+ * `how()` says how keys are made: 'derived', 'stored' or 'memory'.
+ */
+export function keyring({ wallet, project, store = null }) {
+  let root = null;
+  const prefix = () => `loot-key:${project}:${wallet.address}:`;
+  const checkName = () => `loot-key-check:${project}:${wallet.address}`;
+  const safe = (f, fallback = null) => {
+    try {
+      return f();
+    } catch {
+      return fallback;
+    }
+  };
+
+  /** The wallet's signature of `settleKeysText`, once a session; null when it signs no messages, refuses, or signs the
+   * text differently from an earlier session (then nothing it signed could be made again). */
+  function signature() {
+    if (!wallet?.signMessage) return Promise.resolve(null);
+    root ??= (async () => {
+      const sig = new Uint8Array(await wallet.signMessage(utf8(settleKeysText(project, wallet.address))));
+      if (sig.length !== 64) return null;
+      const mark = toHex(sha256(sha256(sig))).slice(0, 32);
+      const had = store ? safe(() => store.get(checkName())) : null;
+      if (had && had !== mark) return null;
+      if (!had && store) safe(() => store.set(checkName(), mark));
+      return sig;
+    })().catch(() => null);
+    return root;
+  }
+
+  const derived = (sig, name) => keyFromSeed(sha256(concat(utf8('loot settle key'), sig, addressBytes(name))), name);
+
+  async function seal(seed) {
+    const device = await store?.cryptoKey?.();
+    if (!device) return null;
+    const iv = randomBytes(12);
+    const sealed = new Uint8Array(await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv }, device, seed));
+    return toBase64(concat(iv, sealed));
+  }
+
+  async function open(text) {
+    const device = await store?.cryptoKey?.();
+    if (!device || !text) return null;
+    const bytes = fromBase64(text);
+    return new Uint8Array(await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: bytes.subarray(0, 12) }, device, bytes.subarray(12)));
+  }
+
+  return {
+    async how() {
+      if (await signature()) return 'derived';
+      return store && (await store.cryptoKey?.()) ? 'stored' : 'memory';
+    },
+
+    /** The key named `name` (an address) for a new job. */
+    async key(name) {
+      const sig = await signature();
+      if (sig) {
+        // Its name is kept, so `recover` finds it once its job's account is gone.
+        if (store) safe(() => store.set(prefix() + name, DERIVED));
+        return derived(sig, name);
+      }
+      const seed = randomBytes(32);
+      const sealed = store ? await seal(seed).catch(() => null) : null;
+      if (sealed) safe(() => store.set(prefix() + name, sealed));
+      return keyFromSeed(seed, name);
+    },
+
+    /** The key named `name` again, for a job left unfinished: made again from the wallet's signature, or read from
+     * storage; null when neither can. `ask`: false to make it only from a signature already given this session. */
+    async again(name, { ask = true } = {}) {
+      const sig = ask || root ? await signature() : null;
+      if (sig) return derived(sig, name);
+      const text = store ? safe(() => store.get(prefix() + name)) : null;
+      const seed = text && text !== DERIVED ? await open(text).catch(() => null) : null;
+      return seed ? keyFromSeed(seed, name) : null;
+    },
+
+    /** The names of the keys this page stored for the wallet (none when keys are made from its signature). */
+    stored() {
+      if (!store) return [];
+      const p = prefix();
+      return safe(() => store.keys(), []).filter((k) => k.startsWith(p)).map((k) => k.slice(p.length));
+    },
+
+    forget(name) {
+      if (store && name) safe(() => store.remove(prefix() + name));
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgamesfun/solana",
-  "version": "0.20.1",
+  "version": "0.24.0",
   "mcpName": "io.github.XGamesFun/solana-kit",
   "description": "One shared Solana program for game and community economies, its JS client, and the tools that let an AI agent design, check, simulate and launch an economy on it.",
   "license": "Apache-2.0",

package/release.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.20.1",
+  "version": "0.24.0",
   "programId": "9cwqM1TXytPnFZsLfmUyv2dg4uW6Ch9C6UJVPns7NFQ",
-  "sbfBytes": 1457936,
-  "sbfSha256": "358805a85fd32ba7b5b6bee9dd88e063bda6f854820d978265bca6683790aee7",
-  "idlSha256": "0f75fb422c2e8eca80cfd4fd5ccc1cd8805df9cc12e981bfd0297810c772aca2",
-  "clientSha256": "91537742722a9b31da8afd1f1a2af1bfeea389ad74981e740a41917f81ebecce"
+  "sbfBytes": 1727272,
+  "sbfSha256": "1bf01fbceb390c8888921df95f711d32e805554401e2c128e83eb16fcb11098c",
+  "idlSha256": "32dc0d5ed56fa7fb2ef8e90ef8d96d1d8bbe940b624d3d5b636933af20ae56b4",
+  "clientSha256": "f2a0f00386a08ecbd1fd939d53889d1a7a151997bf16684c641dd98a838b8d72"
 }

package/skills/xsolana-economy/SKILL.md

@@ -9,8 +9,8 @@ An economy is one JSON spec (`xsolana.json` in the project) on **loot**, a Solan
 writes or deploys a contract: the spec is checked, simulated and priced by the `xsolana_*` tools, and the project's
 owner puts it live by approving in their own wallet. It runs on **devnet** until the program is audited.
 
-The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.20.1 <guide|examples|check|simulate|cost|explain|publish|status> [xsolana.json]`,
-or `npx -y @xgamesfun/solana@0.20.1 tool <name> '<json>'` for any tool (always with the exact version).
+The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.24.0 <guide|examples|check|simulate|cost|explain|publish|status> [xsolana.json]`,
+or `npx -y @xgamesfun/solana@0.24.0 tool <name> '<json>'` for any tool (always with the exact version).
 
 ## Rules (always)
 
@@ -33,7 +33,7 @@ or `npx -y @xgamesfun/solana@0.20.1 tool <name> '<json>'` for any tool (always w
    economy is legal where it is offered is theirs. Never promise it is safe, and never give legal advice.
 7. **Take addresses from the tools, never from memory**: the program, its accounts, the IDL. Every answer names them.
 8. **Public data only in a spec**: names, prices, percents, public addresses. Leave out `id`, `index`, `shopBox`,
-   `rewardsIndex` and `live`: they are written when it goes live.
+   and `live`: they are written when it goes live.
 9. **Compose before you say no.** Most ideas are several parts working together, not one part. Before calling
    anything a limit, break the idea into its pieces (what players pay, what they get, what is random, what the chain
    can't see, what is held and for how long, who is paid) and find the part for each (`references/sentence-to-spec.md`).
@@ -50,9 +50,9 @@ or `npx -y @xgamesfun/solana@0.20.1 tool <name> '<json>'` for any tool (always w
      table.
 
 10. **People finish what follows; build the button, not a server.** Every step after a player's ask (settle a roll,
-   draw a lottery, complete its tickets and pay its places, refund a draw the oracle never answered, claim a win, end
-   an auction, take unbonded tokens out, run a sealed schedule, take a rental's NFT home) can be sent by anyone, and
-   the person who gains from it sends it from the page (`app.claims()` lists them, `app.claim(c)` sends one). A
+   draw a lottery, pull its parts (each place, a refund, a share), refund a draw the oracle never answered, claim a
+   win, end an auction, run a sealed schedule, take a rental's NFT home) can be sent by the person who
+   gains from it, from the page (`app.claims()` lists them, `app.claim(c)` sends one). A
    grant's claim is the winner's alone: the winning wallet signs it, whatever proves it won; anyone may pay its fees,
    nobody claims for a player. loot needs no server to finish anything. Never make a key in a page or a server for
    the owner to fund: whoever signs pays.
@@ -74,13 +74,17 @@ or `npx -y @xgamesfun/solana@0.20.1 tool <name> '<json>'` for any tool (always w
    sends each step while it runs (a draw, a payout, a contest's result) and what happens if nobody does:
    `references/after-launch.md`.
    Prizes: give a known prize directly on whatever route wins it (a grant, a lottery place, a contest, a mission, a
-   recipe): one step, no oracle. Use a roll of a box only for chance. Every other shape (bundles, an NFT as the price,
-   stashes, gates, no-loss lotteries, amounts by rank) is in `references/sentence-to-spec.md` and `xsolana_guide`.
+   recipe): one step, no oracle. Use a roll of a box only for chance. A pack of cards is one box with `slots` (five
+   draws an open, a guaranteed rare), opened several at once from the page; cards whose traits differ are a fresh
+   item drawing from `tables`. Every other shape (bundles, an NFT as the price, stashes, gates, no-loss lotteries,
+   amounts by rank) is in `references/sentence-to-spec.md` and `xsolana_guide`.
+   Then say what stays the project's job (`references/telling-the-person.md`): the files behind every item's link
+   (every value of a fresh item's `{attribute}`), a table's rent, and the collectible rent a pack's settle pays.
 6. **Iterate on what they say.** "Make legendaries 0.5%", "a bigger seed": change, check, simulate, explain again.
 7. **Save it**: `xsolana_save {"spec": …}` writes `xsolana.json`, only if it checks. A live file keeps its program numbers.
 8. **When they say "put it live"**: `xsolana_publish` lists every step and its cost and gives the command. Tell them to
    run it themselves in the project folder, exactly as `xsolana_publish` gives it (it names the exact version:
-   `npx -y @xgamesfun/solana@0.20.1 approve xsolana.json`; never drop the version). It opens a page on their computer where
+   `npx -y @xgamesfun/solana@0.24.0 approve xsolana.json`; never drop the version). It opens a page on their computer where
    they connect a devnet wallet and approve; what lands is written back into `xsolana.json`. You publish nothing.
 9. **After it is live**: `xsolana_status` shows each part on chain; read it before acting on what the person says
    happened. A later change is the same loop: save, publish, and the approval sends only what changed. What only the
@@ -90,7 +94,7 @@ or `npx -y @xgamesfun/solana@0.20.1 tool <name> '<json>'` for any tool (always w
 ## Building the app around it
 
 A game, a site or a bot calls the live economy with the player's own wallet, through the package's player module
-(`@xgamesfun/solana/play`: buy, open a box and collect the roll, pay, stake, compound and withdraw, craft, bid and end an
+(`@xgamesfun/solana/play`: buy, open a box and collect the roll, pay, stake, compound and unstake, craft, bid and end an
 auction, list an NFT for sale or for rent and read who rents it, raffle an NFT, claim what a player is owed, run what
 is due, list what a player owns). Pages call `claims()` when they open and show each as a button.
 `references/apps.md` shows a whole page; `xsolana_client` gives the program and the calls. Never invent account layouts,
@@ -100,6 +104,6 @@ For staking an NFT of another collection, show what custody means and get explic
 ## More
 
 - From a sentence to a spec, with a worked example: `references/sentence-to-spec.md`
-- Telling the person what they get: `references/telling-the-person.md`
+- Telling the person what they get, and what stays the project's job: `references/telling-the-person.md`
 - Building the app for a live economy: `references/apps.md`
 - After it goes live (who sends each step, owner pages, results from a game, a results server): `references/after-launch.md`

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

@@ -8,32 +8,38 @@ winner nobody pays.
 
 | 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 |
+| 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, each pool's prize) and opens the next round at once. 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 pot gets back) | 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 |
 | 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 |
+| 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 **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 |
+| 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. 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 +53,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.
 
@@ -101,11 +109,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

@@ -26,7 +26,7 @@ const app = solanaApp({ spec, rpcUrl: 'https://api.devnet.solana.com', wallet: w
 
 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
+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, … }]
@@ -40,7 +40,7 @@ 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.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 }]
@@ -49,7 +49,9 @@ const loan = await app.loanOffer(lender, 1); // a lender's offer: { amount, repa
 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.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
 ```
@@ -66,12 +68,31 @@ await app.balances();                     // what they hold of each of the econo
   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`,
@@ -84,10 +105,13 @@ await app.balances();                     // what they hold of each of the econo
   }])` 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 +119,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 +147,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