@xgamesfun/solana 0.0.0-stage → 0.24.0

package/skills/xsolana-economy/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: xsolana-economy
+description: Build a web3, token or NFT economy on Solana without writing a smart contract, on loot, one shared program every project uses. Covers shops, loot boxes and gacha, packs, random NFT and token prizes from a stash of NFTs the project holds, coin flips and prize pools, lotteries and raffles, auctions where the highest bid wins and the outbid get their money back, staking farms with lock tiers and NFT boosts, crafting and merging, seasons and emissions, prediction pools and contests, quests, airdrops and capped rewards, holder-gated drops, and perks or staking for any NFT, whether the project minted it or not. Turns a person's idea into a JSON spec, then checks, simulates and prices it, explains it in plain words, and hands the person the command that puts it live in their own wallet. Use whenever someone asks for anything onchain that players or members pay, earn, stake, open, craft or win, for a game, a community, a creator or a brand, and before writing any Anchor, Rust or Solidity for it.
+---
+
+# Build an economy on loot
+
+An economy is one JSON spec (`xsolana.json` in the project) on **loot**, a Solana program every project shares. Nobody
+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.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)
+
+1. **Never write, build or deploy a program.** No Anchor, Rust, Solidity or custom program, and no deploy: not by you,
+   not by a command or page you give the person, not even "just on devnet". Unaudited code holding people's money is
+   the risk loot exists to remove. If the idea needs something loot can't do, follow rule 9.
+2. **You never sign, and you never ask for or handle a key.** No private key, seed phrase or keypair file: not in
+   chat, not in a spec, not in a file. Going live is the person running `xsolana approve` and approving in their own
+   wallet. If they paste a key, tell them to treat it as exposed and move its funds; write it nowhere.
+3. **Devnet only.** Nothing here is real money yet; say so.
+4. **The checker decides.** Never save or publish a spec with refusals. Fix each refusal the way its `fix` says.
+5. **Numbers come from the tools.** What a box gives back, how long a pool lasts, what going live costs: quote
+   `xsolana_simulate`, `xsolana_cost` and `xsolana_explain`, never your own arithmetic. What a player pays is the tools'
+   "in all" number for that action (price, fee, oracle, network and rent that never comes back): quote it as is.
+6. **Flag the law.** When the checker raises `W-CHANCE-PRIZE` (paid chance at money: boxes with prizes, lotteries,
+   contests), `W-CHANCE-ITEMS` (paid random collectibles a player can resell: loot boxes, gacha) or `W-REVENUE-SHARE` (stakers paid from sales), tell the person in plain words, every time, and never
+   call anything an investment, a return or passive income. For an auction, always say `W-AUCTION-SHILL`: anyone,
+   the seller included, can bid to push the price up. Before they go live, say as well that the program is not
+   independently audited and comes as is, with no warranty: they use it at their own risk, and making sure the
+   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`,
+   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`).
+   What the chain can't see (a match, a score, something done offline) is vouched for by a signer: a results server's voucher, a
+   decider's key, a list. Build the combination and say which part does which piece. When the tools' words and the
+   checker disagree (a field the schema takes that a sentence somewhere calls impossible), the checker and
+   `xsolana_guide`'s parts decide: try it in a spec and run `xsolana_check`.
+   A piece is a limit only when no part or combination does it. Then:
+   - say in one line what is missing and why;
+   - offer the nearest versions (`xsolana_examples` with the words of that piece returns them), best first, each with
+     what it gives up and its "in all" cost; recommend one, and build it;
+   - if they push back, offer the next version or a change that brings back what they miss (a price, a bundle, a
+     second step). Don't withdraw a draft that checks, and don't send them elsewhere while a version on loot is on the
+     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, 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.
+
+## The loop
+
+1. **Read what an economy can be made of**: `xsolana_guide` (every part and field, who acts and what it costs, what
+   loot cannot do). `{"part": "farms"}` for one part's nested shapes.
+2. **Start from the nearest example**: `xsolana_examples {"query": "<the person's own words>"}`, then
+   `xsolana_examples {"name": "<example>"}` for a whole spec to copy. The rated economies say how each real economy
+   fits (great, some, a-lot, cannot) and what carries it.
+3. **Write the spec** from their sentence: `references/sentence-to-spec.md` maps their words to parts. Keep their
+   sentence in `prompt`. Add a `scenario` with the counts they expect (how many opens a day).
+4. **Check it**: `xsolana_check {"spec": …}`. Fix every refusal; every warning is something to tell the person, in a
+   sentence of its own.
+5. **Simulate and explain it**: `xsolana_simulate`, then `xsolana_explain`. Tell the person, in a few short lines, what each
+   play costs and is worth, where the money goes, how the pools fill and drain, what going live costs, what the
+   authority must sign while it runs, and the flags: `references/telling-the-person.md`. Before they approve, say who
+   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. 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.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
+   owner signs (open or decide a contest, pay out) goes on an owner page they approve in their own wallet:
+   `references/after-launch.md`.
+
+## 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 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,
+instruction data or addresses, and never put a key or the authority's actions in a page players load.
+For staking an NFT of another collection, show what custody means and get explicit acceptance before sending.
+
+## More
+
+- From a sentence to a spec, with a worked example: `references/sentence-to-spec.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

@@ -0,0 +1,124 @@
+# After it goes live: who does what
+
+Going live is the start. Before the person approves, tell them who sends each step the economy needs while it runs,
+and what happens if nobody does. Most failures in practice are a raffle nobody draws, a contest nobody decides, or a
+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) | 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`); 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 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 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
+on an account, and closing one (an unwrap of wrapped SOL) never stops a sale.
+
+An NFT the project has no authority over is used as it is, with no import step, whatever its kind: Core, Token Metadata
+(legacy, pNFT) or compressed (Bubblegum v2). Any of them can be staked, held, auctioned by the owner or authority,
+and shown to gates and odds (a player auctions only an NFT of the project's own collection);
+a compressed one is proven in the same transaction (`prove_leaf`, which the page does by itself from the RPC's DAS
+methods). What the project writes about one (a level, a use) goes in its Sheet (`["sheet", project, nft]`), written by
+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 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`, `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.
+
+Leaving a farm needs only the player's wallet, never a server's signature; what can still keep an NFT from coming
+back is the NFT issuer's own controls (`telling-the-person.md`, NFT custody).
+
+## The owner's own steps: an owner page
+
+What only the authority can sign (open or decide a contest, pay out, move a pool) needs a page the owner opens and
+approves in **their own wallet**, like the approve page. Build it with `@xgamesfun/solana/client` builders
+(`openContestIx`, `decideIx`, `moveTokensIx`) and the wallet's `signTransaction`, served locally or on the same site
+behind nothing more than the owner's wallet: the program checks the signature, so a page holds no secret.
+
+- Show what each button does in words before the wallet asks ("Name the Owls the winner: the pot of 0.42 SOL is
+  shared by 7 backers; 5% goes to you").
+- Never put an owner's or authority's key in a page, a file or a server, and never ask the person to export one.
+
+## Results from a game: who won, and paying them
+
+When a game (not the chain) knows who won a match, cleared a quest or placed in a tournament, pay through a **grant**
+the winner claims themselves. The grant's limits (per wallet in all and per window, per person, per key, per day, in
+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.
+- **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.
+- **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 })`).
+  - The server can be the person's own game server (`signVoucher` from `@xgamesfun/solana/results`). It holds only that
+    voucher key, never the owner's. Set the grant's `total` and `perWallet`: they bound what a stolen voucher key can
+    pay.
+  - Or a **results server** the person runs or names. It checks results signed by the game's host key, which the
+    owner certifies once by signing a text in their wallet; the game server and pages talk to it with
+    `@xgamesfun/solana/results` (`report`, `giveaways`, `draws`), and winners claim what it vouched for with
+    `app.claimWins({ server, token })` (`token`: the player's sign-in with that server, when it asks for one; a drop
+    of NFTs from a stash gives one only at a signed-in claim, first come first served). Its voucher key is per
+    project (`GET <server>/v1/voucher-key?game=<address>`): the project's address exists only once it is live, so go
+    live first, then add the grant with that key and publish again. A grant written before then is saved switched
+    off (`"active": false`, which `xsolana_check` reports as W-OFF): tell the person it waits for that key, and switch it
+    on when the key goes in. Never use a key from `/v1/health`.
+- **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 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
+
+"It's been an hour", "the Owls won", "the pool is empty": read the chain first (`xsolana_status`, or the account itself), and
+say what you found. The chain's clock and balances decide what can be sent now.

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

@@ -0,0 +1,193 @@
+# Building the app for a live economy
+
+Once `xsolana.json` has a `live` section, players use the economy through a page (a game screen, a site, a mint page)
+with their own wallet. Use the package's player module, `@xgamesfun/solana/play`: it reads the economy, builds every
+transaction, has the player's wallet sign it, sends it and waits for the result. Don't hand-write instructions,
+account lists or program addresses.
+
+```bash
+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
+
+// Connect a wallet (Phantom, Solflare, Backpack all register through the Wallet Standard).
+const wallets = [];
+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 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, 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.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?, 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 (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>
+  ```
+  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. 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`,
+  `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,
+  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, 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
+  its pool by weight, and an upkeep or the farm's end stops a seat). Read it when the page opens and after a stake
+  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 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: 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 (`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
+  page makes it from the wallets xsolana.json lists (`loot.gateList(list).proofOf(wallet)`, which fills the list to a
+  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`): 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
+  `boxes()` showed (`{ listing }`, or `{ maxPrice }` in base units), `app.craft` the recipe's listing from `recipes()`
+  (or its `version`), `app.buyTickets` the lottery's listing from `lotteries()` (or `{ maxPrice }` a ticket), and
+  `app.buyListing` and `app.rentListing` the `listing` that `app.listing(asset)` or `app.listings()` showed. Without
+  one they refuse; a price (or recipe) that moved since is refused with the new one in words, never paid unseen. Show
+  the new price and let the player click again.
+- **Loans against an NFT** (a lender's offer with `deal: { Lend }`): show `app.loanOffer(maker, id)` first: what is
+  lent, what repays it, by when, and every `risks[i].says`. A loan's token may have a freeze authority, a pause or a
+  transfer hook (or a permanent delegate): whoever holds one can make every repayment fail, and a lender who holds one
+  can take the NFT when it is due. The program takes such tokens, so `app.borrow` refuses one unless the player
+  accepted it (`{ acceptRisks: true }`). Lend in a plain token (SOL, or a mint with no freeze authority) to avoid it.
+- **An NFT as the price** (a recipe's `trade` line, a box's `rollsOn` with `then`, a lottery's `ticketNft`): say on the
+  page which NFT is spent and where it goes before the player signs; it is spent at once and never refunded.
+- **The owner's own wallet on the page**: by default the project's treasury is the owner's wallet. The owner may buy, play
+  and unwrap like anyone: a sale whose treasury account was closed opens it again.
+- **A buyer's choice**: a share the box, lottery or payment lets the buyer name (`"chosen"`, a referrer; `"chosen:<item>"`, the
+  workshop they craft at, not in a payment) comes from the page: `app.buy(key, { listing, chosenRecipient: referrer })`, `app.openBox(key, { listing, chosenRecipient })`,
+  `app.buyTickets(key, n, { listing, chosenRecipient })`, `app.pay(key, { chosenRecipient })`. Take a referrer from the link (`?ref=<wallet>`); never let a buyer name
+  themselves (the program refuses it, and `app.pay` does). Each method refuses an option it doesn't take (`{ choice }` is
+  not `chosenRecipient`). A `"chosen:<item>"` share needs its collectible: offer only ones players hold
+  (the program refuses none, one burned, and one the project holds: staked in escrow, held, up for auction).
+- **A "Claim" or "Collect" area** built on `claims()` is how players finish what is theirs, and how a due draw gets
+  sent. Show it. Read it when the page opens and on a Refresh button, not after every action: it searches the chain
+  several times, and devnet's free RPC turns away bursts. After an action, read only what it changed (a balance,
+  `collectibles()`), one read at a time, and keep what is on screen when one read fails.
+- **Errors** come back as plain sentences (a sold-out item, a gate not met, a price above the most they agreed to):
+  show them.
+- **Never in a page**: a private key, a keyed RPC link, or anything the authority signs (payouts, minting, rewriting
+  a collectible). Those are the owner's or the authority's to sign in their own wallet, or on a server they run.
+- **Lower level**: `@xgamesfun/solana/client` has one builder per instruction and the account decoders, for what the
+  player module doesn't cover.