@xgamesfun/solana 0.25.3 → 0.26.0

package/README.md

@@ -1,96 +1,52 @@
-# solana-kit: Solana game and NFT economies without a smart contract
-
-Loot boxes and gacha, shops, lotteries and raffles, auctions, NFT staking farms, crafting, quests and capped rewards on
-Solana, written as a JSON spec instead of a new Anchor program. They all run on **loot**, one shared, open Solana
-program, and an AI coding agent (Claude Code, Codex, Cursor or any MCP client) can design, check, simulate and price
-one from a sentence. This repository is the npm package `@xgamesfun/solana`:
-
-- a JavaScript client with no Solana SDK (`@xgamesfun/solana/client`), a player module for apps (`/play`) and a results
-  client (`/results`);
-- the economy spec and its checker, quick simulation, cost and plain-words explainer;
-- the `xsolana` CLI and an MCP server with eleven `xsolana_*` tools;
-- the `xsolana-economy` skill, and one plugin that carries the tools and the skill to Claude Code and Codex;
-- a local approval page where a project's owner approves going live in their own wallet.
-
-An economy is a JSON spec, not a new smart contract. Every project shares the one program, and none writes its own.
-
-> **Status:** these tools are for loot 0.25.0, program ID `9cwqM1TXytPnFZsLfmUyv2dg4uW6Ch9C6UJVPns7NFQ`, **devnet
-> only** (deployed 2026-11-08, slot 519,994,814). The program is not independently audited, and nothing runs
-> on mainnet until it is. See [SECURITY.md](SECURITY.md).
-
-> **Disclaimer:** provided as is, with no warranty and no guarantee that the program or the tools are safe. Use them
-> at your own risk; you are responsible for every transaction you approve and for making sure what you build is legal
-> where it runs. Nothing here is legal or financial advice. Read [DISCLAIMER.md](DISCLAIMER.md) before you use it.
-
-## Before you use it
-
-- **Devnet only, and not independently audited.** Nothing here is for real money yet. Use a devnet wallet.
-- **The program can be upgraded, and an upgrade can mean starting again.** Its upgrade authority can replace the
-  program's code, which is power over every economy on it (on mainnet that key is to be a multisig). No version so far
-  has carried accounts over from the one before: an economy made on 0.23 was made again for 0.24. Pin the package
-  version (each one names the program build it is for in `release.json`) and expect to set an economy up again after an
-  upgrade.
-- **Players trust the project.** Its owner and authority are trusted keys with no caps: the authority mints, moves the
-  project's pool funds, decides contests and writes its NFTs. The program protects players from each other, from the
-  platform and from mistakes, not from the project they chose to play. Money held for a record (an order, a bid, a
-  farm's stakes, a contest's or lottery's pot) leaves only by that record's rules.
-- **Players also trust the token and the collection.** A mint's issuer (a freeze authority, a pause, a transfer hook, a
-  permanent delegate) or a collection's controller can stop or move what loot holds. USDC has a freeze authority.
-- **The chain can't see a game.** Results a game reports (a win, a score, a clear) are vouched for by a key the project
-  trusts, a results server or deciders. Checking that a player really did it is the project's job, on its own server:
-  a server that decides the result, replays it, or only bounds what the page reports leaves a cheater very different
-  amounts. A grant says which in `trust`, and `xsolana review` says what a cheater gets on every route
-  ([trust and cheating](skills/xsolana-economy/references/trust-and-cheating.md)).
-- **The hosted results server is optional.** `https://play.xgames.fun/xsolana` (`@xgamesfun/solana/results`'s
-  default) signs vouchers for games without a server of their own. It can only pay what a grant allows, and only for a
-  grant whose owner named its key in `vouchers`. It sends nothing on chain, and it is offered as is: it can be down, and
-  it is behind for a while after each program upgrade. A game with its own server signs its own vouchers
-  (`signVoucher`), which is the better choice once it has one.
-- **Nothing runs by itself.** Someone sends every step: settles (the player, the project's keys, or a key the player
-  named), lottery draws, auction ends, refunds (anyone), contest results (the authority or its deciders) and schedule
-  runs (the project's keys). A run nobody sends on time is missed, except a sealed schedule's fixed amount. Apps built
-  with `@xgamesfun/solana/play` send the steps a player needs. Don't count on a hosted keeper.
-- **The rules are strict.** A prize is a fixed amount: a jackpot that grows is a lottery's pot. A lottery says where its
-  places are paid from: a pot that carries over (gifts and what earlier rounds left count), or each round's own ticket
-  money, which nothing from outside can change. A prize never shifts to a later round. A draw uses the odds
-  as written. When an outcome runs out, a box either stops selling (`stopSales`, the default) or keeps selling and
-  draws among what's left (`drawLeft`, which lets a player empty a common outcome to make a rare one likelier).
-- **Chance comes from an oracle.** MagicBlock's VRF answers every random roll and draw. If it stops answering, rolls wait. An
-  order still unanswered after 7 days can be refunded. Once a roll has waited 10 minutes, a buyer who sees a late
-  answer coming can take a refund instead.
-- **Fees and rent.** The platform sets two flat fees: by default 0.002 SOL a player action and 0.00001 SOL a project
-  action. Each is capped at 0.01 SOL, and a raise waits 7 days. Accounts cost rent: going live, and each settle that
-  opens or mints something. `xsolana cost` gives the totals. The platform can suspend purchases, but it never stops
-  payouts, refunds or unstakes (the one exception is a recipe that charges).
-- **Some things aren't built,** and some limits are kept by design. Read
-  [Known limits](docs/program.md#known-limits) before promising players something unusual.
-- **The law is yours to check.** The checker's legal flags (chance at money, resellable random items, revenue
-  sharing) are reminders, not advice. A spec with no flag isn't therefore legal.
-
-## What an economy can be made of
-
-- payments and splits, in tokens or with an NFT
-- shops (a purchase in one transaction) and loot boxes
-- pools and timed schedules, sealed or not
-- lotteries and raffles, including no-loss lotteries
-- prizes of any kind on every route, random or not: items, tokens, and NFTs the project holds in a stash
-- an NFT as the price on every route that takes money
-- staking farms with lock tiers, boosts, early exits, fixed or shared rates and terms
-- crafting recipes
-- holds and contests, with prizes by rank or by stake
-- auctions: the highest bid wins, the outbid refunded at once
-- listings for sale or rent, and bids and loans between players
-- perks, staking and holds for any NFT, whether the project has authority over it or not
-- allowlists of any size (a Merkle list) on every gated route
-- capped rewards and grants that a server vouches for
-- rules on what a collectible says
-
-Every move leaves a public receipt. [`docs/program.md`](docs/program.md) describes how the program behaves.
-
-## Use it from an AI coding agent
-
-The MCP server and the skill let Claude Code, Codex or any MCP agent turn a one-line idea into a checked, simulated
-economy and hand you the command that puts it live in your own wallet.
+# solana-kit
+
+**Build loot boxes, shops, lotteries, auctions, NFT staking and rewards on Solana without writing a smart contract.**
+
+[![npm](https://img.shields.io/npm/v/@xgamesfun/solana?color=b9f26c&label=npm)](https://www.npmjs.com/package/@xgamesfun/solana)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![network](https://img.shields.io/badge/network-devnet-orange)](#good-to-know)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.XGamesFun%2Fsolana--kit-8a2be2)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.XGamesFun/solana-kit)
+
+You describe your game's or community's economy in a small JSON file: what players buy, open, stake, win or craft.
+The tools check it, show you where the money goes, tell you what it costs, and then you put it live by approving it in
+your own wallet. It runs on **loot**, one Solana program that every project shares, so there is no Anchor or Rust to
+write, deploy or audit yourself.
+
+Most people never touch the JSON: they ask an AI agent (Claude Code, Codex, Cursor, ChatGPT or Claude) for _"a fishing
+game where each cast costs 0.02 SOL, with a rare golden fish and a monthly draw"_ and the agent does the rest.
+
+> **Devnet only for now.** The program is not yet independently audited, so nothing here is for real money. The
+> tools are provided as is: read [DISCLAIMER.md](DISCLAIMER.md) before you use them.
+
+## What you can build
+
+| Build                         | For example                                                                      |
+| ----------------------------- | -------------------------------------------------------------------------------- |
+| **Shops**                     | A potion for 0.01 SOL, a skin paid in your own token, an item that costs an NFT  |
+| **Loot boxes, gacha, packs**  | A crate with a 1% legendary, a five-card pack with a guaranteed rare, gacha pity |
+| **Lotteries and raffles**     | A weekly draw, a no-loss lottery, a raffle for an NFT with an allowlist          |
+| **Auctions**                  | Highest bid wins, and anyone outbid gets their money back at once                |
+| **NFT staking**               | Lock tiers and boosts, for your collection or any collection you didn't mint     |
+| **Crafting**                  | Burn three common gems to forge a rare one                                       |
+| **Contests and predictions**  | Pick a side, prizes by rank or by stake                                          |
+| **Rewards, quests, airdrops** | Capped rewards your game's server vouches for, daily chests, holder-only drops   |
+| **Trading between players**   | Listings for sale or rent, offers, and loans against an NFT                      |
+
+Every move leaves a public receipt on chain. Random rolls come from MagicBlock's verifiable randomness.
+
+## How it works
+
+1. **Describe it.** In a sentence to your agent, or as a spec file (`xsolana.json`).
+2. **Check it.** `check` refuses anything the program would refuse; `simulate` shows where the money goes, day by
+   day; `cost` prices going live and each player action; `review` shows what a cheater could get.
+3. **Approve it.** A page opens on your own computer, lists every transaction, and you approve them in your wallet.
+   Nothing here ever signs for you or asks for a key.
+
+New here? The [loot box tutorial](docs/tutorial-loot-box.md) walks through all three with real output.
+
+## Get started
+
+### With an AI agent
 
 **Claude Code**
 
@@ -106,165 +62,126 @@ codex plugin marketplace add XGamesFun/solana-kit
 codex plugin add xsolana@xgamesfun
 ```
 
-**Chat apps** (claude.ai, ChatGPT, Claude Desktop): add `https://xgames.fun/mcp` as a custom connector (an MCP server
-by URL). It is the hosted server (below, "Over HTTP"): nothing to install, and going live stays your own approval on your
-computer. More at [xgames.fun/solana](https://xgames.fun/solana).
+**claude.ai, ChatGPT or Claude Desktop:** add `https://xgames.fun/mcp` as a custom connector. Nothing to install.
 
-**Any agent with MCP** (Cursor, opencode, Cline…): run the server with
-`npx -y --package=@xgamesfun/solana@0.25.3 xsolana mcp`. Or let `npx -y @xgamesfun/solana@0.25.3 connect` register it, with
-the skill, for Claude Code and Codex.
+**Cursor, Cline, opencode or any MCP client:** run `npx -y --package=@xgamesfun/solana@0.26.0 xsolana mcp`.
 
-**The skill alone, in any agent that reads skills** (Claude Code, Codex, Copilot, Gemini CLI, Cursor, Windsurf, Cline,
-opencode…): `npx skills add XGamesFun/solana-kit` finds it and installs it for the agents you have. Without the MCP
-server it runs the same tools through `npx`. Each GitHub release also carries `xsolana-economy.zip`, the skill as one
-file for apps that take a skill as an upload (the Claude and ChatGPT desktop apps).
+**Any agent that reads skills** (Copilot, Gemini CLI, Windsurf…): `npx skills add XGamesFun/solana-kit`.
 
-**Over HTTP**: `npx -y --package=@xgamesfun/solana@0.25.3 xsolana mcp --http` serves the tools that read nothing but
-their arguments (guide, examples, check, simulate, cost, explain, review, status, client) at
-`http://127.0.0.1:8787/mcp`, MCP's Streamable HTTP transport. `@xgamesfun/solana/mcp/http` exports the same handler
-(`mcpHttp(request) → response`) for a hosted endpoint: it reads no files, and the agent hands the person the spec and the
-`approve` command to go live.
+Then ask for the economy you want. More ways in, such as the skill as a zip for desktop apps or the server over HTTP,
+are in [docs/harnesses.md](docs/harnesses.md).
 
-Then ask for an economy, for example _"a fishing game where each cast costs 0.02 SOL, with a rare golden fish and a
-monthly draw"_.
+### From a terminal
 
-Going live is always yours: `npx -y @xgamesfun/solana@0.25.3 approve` opens a page on your computer where you connect a
-devnet wallet and approve each transaction. The agent never signs and never asks for a key.
+```bash
+# find a worked example close to your idea
+npx -y @xgamesfun/solana@0.26.0 examples shop with loot boxes
 
-## Use it from a terminal
+# does it work? where does the money go? what does it cost?
+npx -y @xgamesfun/solana@0.26.0 check xsolana.json
+npx -y @xgamesfun/solana@0.26.0 simulate xsolana.json
+npx -y @xgamesfun/solana@0.26.0 cost xsolana.json
 
-Every tool runs from the CLI too, on a spec file (`xsolana.json` by default):
+# the whole economy in plain words, and what a cheater could get
+npx -y @xgamesfun/solana@0.26.0 explain xsolana.json
+npx -y @xgamesfun/solana@0.26.0 review xsolana.json
 
-```bash
-npx -y @xgamesfun/solana@0.25.3 examples shop with loot boxes   # the nearest worked examples
-npx -y @xgamesfun/solana@0.25.3 check xsolana.json                 # refusals and warnings
-npx -y @xgamesfun/solana@0.25.3 simulate xsolana.json              # where the money goes, day by day
-npx -y @xgamesfun/solana@0.25.3 cost xsolana.json                  # what going live and each action cost
-npx -y @xgamesfun/solana@0.25.3 explain xsolana.json               # the economy in plain words
-npx -y @xgamesfun/solana@0.25.3 review xsolana.json                # what a cheater gets on each route (exits 1 on a high finding)
-npx -y @xgamesfun/solana@0.25.3 approve xsolana.json               # go live, approved in your own wallet
+# go live, approved in your own wallet
+npx -y @xgamesfun/solana@0.26.0 approve xsolana.json
 ```
 
-`xsolana help` lists every command. Every command names the exact version, so `npx` runs that release and never whatever
-is newest under the name.
+Each command names an exact version, so you always run the release you meant to. `xsolana help` lists them all.
 
-## Use it from code
+### In your app
 
 ```bash
 npm install @xgamesfun/solana
 ```
 
 ```js
-import * as loot from '@xgamesfun/solana/client';
-const ix = loot.openBoxIx({ player, project, box, nonce }); // one builder per instruction, no Solana SDK
-```
+import { solanaApp, walletStandardSigner } from '@xgamesfun/solana/play';
 
-Players with no SOL can still play when the project sponsors their fees: `solanaApp({ sponsor })` has a key on the
-project's own server pay each step's fees and rent (never its price), and `@xgamesfun/solana/sponsor` is that server's
-side: `sponsorSigner` dry-runs and checks every transaction before it signs, under the project's own per-player budget.
-
-Building on `@solana/kit`? `loot.toKitInstruction(ix)` gives any builder's instruction in Kit's shape
-(`{ programAddress, accounts, data }`), and `loot.fromKitInstruction` turns one back.
-
-| Import                           | What                                                                                        |
-| -------------------------------- | ------------------------------------------------------------------------------------------- |
-| `@xgamesfun/solana`              | the economy tools: `check`, `simulate`, `plan`, `cost`, `explainEconomy`, `review`, `model` |
-| `@xgamesfun/solana/client`       | every PDA, one builder per instruction, account and receipt decoders, grant vouchers        |
-| `@xgamesfun/solana/play`         | `solanaApp`: what a player does with a live economy, from a browser app                     |
-| `@xgamesfun/solana/results`      | results and vouchers a game's server signs                                                  |
-| `@xgamesfun/solana/chain/*`      | browser-safe Solana primitives: base58, Borsh, transactions, PDAs, tokens, Core             |
-| `@xgamesfun/solana/idl.json`     | the program's IDL, the authority for account and argument layouts                           |
-| `@xgamesfun/solana/release.json` | the program build, IDL and client this release is pinned to                                 |
-
-The client, chain and play modules run in browsers and Node 22 or later, with no bundler required. The package
-ships TypeScript declarations for every entry point.
-
-## Questions people ask
-
-**How do I make a loot box, gacha or pack opening on Solana without writing a smart contract?** Describe it as a box
-in a spec (its price, its outcomes and their odds, what each one pays), run `xsolana check` and `xsolana simulate`, then
-approve it in your wallet with `xsolana approve`. Rolls come from MagicBlock's VRF, and a buyer is refunded if the
-oracle never answers. [`examples/`](examples) has whole worked economies.
-
-**How do I add staking to an NFT collection, even one I didn't mint?** A staking farm takes any collection, with lock
-tiers, boosts and fixed or shared reward rates. The project needs no authority over the NFTs: see
-[`docs/nfts.md`](docs/nfts.md).
-
-**Can I run a lottery, raffle or auction on Solana without deploying a program?** Yes: lotteries (including no-loss
-ones), raffles with a Merkle allowlist, and auctions that refund the outbid at once are all routes in the same spec.
-
-**Is there an MCP server or Claude Code plugin for building on Solana?** Yes: the `xsolana` plugin for Claude Code and
-Codex, the hosted server at `https://xgames.fun/mcp` for chat apps, and `npx -y --package=@xgamesfun/solana@0.25.3 xsolana mcp` for any MCP client. It is listed in the MCP
-Registry as `io.github.XGamesFun/solana-kit`.
-
-**How is this different from writing my own Anchor program?** Nothing is written, deployed or upgraded per project:
-every project's rules are checked by the one program, and its tests run every instruction against that program in
-LiteSVM. The trade-off is that an economy can only be what the spec can say ([known limits](docs/program.md#known-limits)).
-
-**Does it run on mainnet?** Not yet: devnet only until the program is independently audited.
-
-## Documentation
-
-|                                                                                    |                                                                                             |
-| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| [`docs/tutorial-loot-box.md`](docs/tutorial-loot-box.md)                           | a loot box from one sentence to going live, step by step                                    |
-| [`docs/program.md`](docs/program.md)                                               | the program: who signs, accounts, every instruction, fees, limits, receipts, costs          |
-| [`docs/nfts.md`](docs/nfts.md)                                                     | NFTs and tokens, with and without the project's authority                                   |
-| [`docs/harnesses.md`](docs/harnesses.md)                                           | how the plugin reaches Claude Code and Codex, and the release checklist                     |
-| [`skills/xsolana-economy`](skills/xsolana-economy/SKILL.md)                        | the skill an agent follows                                                                  |
-| [`trust-and-cheating.md`](skills/xsolana-economy/references/trust-and-cheating.md) | what a server decides, replays or bounds; who gets paid; an exploit checklist               |
-| [`examples/`](examples)                                                            | whole economies that check and go live in the tests; `ideas.json`, 112 real economies rated |
-| [`evals/`](evals/README.md)                                                        | fresh-session evals of agents building on loot                                              |
-| [`CHANGELOG.md`](CHANGELOG.md), [`SECURITY.md`](SECURITY.md)                       | versions, the trust model, reporting a vulnerability                                        |
-
-## Layout
-
-| Path                                    | What                                                                                                 |
-| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `js/chain/`                             | browser-safe Solana primitives, no SDK                                                               |
-| `js/client/`                            | the client; `idl/` is the program's IDL                                                              |
-| `js/economy/`                           | the economy spec (version 2, `schema.json`), checker, simulation, setup plan, cost, explainer, guide |
-| `js/play/`, `js/results/`               | a player's side of a live economy; results a server vouches for                                      |
-| `js/approve/`, `js/mcp/`, `js/connect/` | the approval page, the MCP server and its tools, `xsolana connect`                                   |
-| `js/sim/`, `js/test/`                   | LiteSVM running the real program; the tests and their pinned fixtures                                |
-| `bin/xsolana.mjs`                       | the CLI                                                                                              |
-| `skills/`, `plugin/`                    | the skill (copied to `plugin/skills`, `.claude/skills`, `.agents/skills`) and the plugin             |
-| `scripts/`                              | fixtures, skill sync, IDL sync, release manifest, a devnet end-to-end run                            |
-| `release.json`                          | the program binary, IDL and client hashes this version is pinned to                                  |
-
-## Development
-
-Node 22 or later.
+// spec: your live xsolana.json; wallet: the player's own (Phantom, Solflare, Backpack…)
+const app = solanaApp({ spec, wallet: walletStandardSigner(wallet, account) });
 
-```bash
-npm ci
-npm run fixtures   # downloads the loot program from devnet and the programs it calls from mainnet, each checked by hash
-npm test           # every instruction the client builds, and every example's whole setup, against the real program in LiteSVM
-npm run lint       # ESLint and Prettier (npm run format fixes the formatting)
-npm run check      # fixtures, skill copies and release.json in step, lint, then the tests
+// the player sees the price, then approves the purchase in their wallet
+const shop = await app.shop();
+await app.buy('potion', { listing: shop.find(item => item.key === 'potion') });
 ```
 
-Nothing in the tests deploys or spends SOL.
-
-| Variable                                                                                                             | What it does                                                                                   |
-| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `XSOLANA_RPC_URL`                                                                                                    | a devnet RPC of your own for `xsolana approve` and `xsolana status` (a mainnet URL is refused) |
-| `XSOLANA_NO_OPEN`                                                                                                    | `xsolana approve` prints its link without opening a browser                                    |
-| `XSOLANA_DEBUG`                                                                                                      | the CLI prints a failure's whole stack, not one line                                           |
-| `XSOLANA_PROGRAM_DIR`                                                                                                | the tests run that program build's `target/deploy/loot.so`, and check the IDL against it       | To try the tools in your own agent from a clone, |
-| `node bin/xsolana.mjs connect --local` registers this checkout's MCP server and the skill with Claude Code and Codex |
-| (`--remove` takes them out again).                                                                                   |
-
-After editing `skills/`, run `npm run sync-skills`. Changes to tool texts, the skill or the plugin are best measured
-with the evals before and after ([`evals/README.md`](evals/README.md)). [`AGENTS.md`](AGENTS.md) has the rules for
-working in this repository, for people and coding agents alike.
+No Solana SDK needed: it runs in the browser and in Node 22 or later, with TypeScript types included. The player
+module covers buying, opening boxes, staking, crafting, tickets, bids and claims;
+[apps.md](skills/xsolana-economy/references/apps.md) shows a whole page.
+
+| Import                           | What it gives you                                                                     |
+| -------------------------------- | ------------------------------------------------------------------------------------- |
+| `@xgamesfun/solana/play`         | everything a player does with a live economy, from a web page                         |
+| `@xgamesfun/solana/client`       | one builder per instruction, every address, account and receipt decoders              |
+| `@xgamesfun/solana/sponsor`      | your server pays players' fees (never their price), so players with no SOL can play   |
+| `@xgamesfun/solana/results`      | results and vouchers your game's server signs                                         |
+| `@xgamesfun/solana`              | the tools themselves: `check`, `simulate`, `cost`, `review`, `explainEconomy`, `plan` |
+| `@xgamesfun/solana/mcp/http`     | the MCP server as a web handler, to host it yourself                                  |
+| `@xgamesfun/solana/chain/*`      | small browser-safe Solana building blocks: base58, Borsh, transactions, tokens, Core  |
+| `@xgamesfun/solana/idl.json`     | the program's IDL                                                                     |
+| `@xgamesfun/solana/release.json` | the exact program build this release is for                                           |
+
+Using `@solana/kit`? `loot.toKitInstruction(ix)` turns any builder's instruction into Kit's shape.
+
+## Good to know
+
+- **Devnet only, not yet audited.** Use a devnet wallet. Mainnet waits for an independent audit.
+- **Upgrades can mean setting up again.** No program version so far has carried accounts over. Pin the package version.
+- **Players trust the project.** Your keys can mint and move your project's pools. The program protects players from
+  each other and from mistakes, not from the project they chose.
+- **The chain can't see your game.** Wins and scores are vouched for by your server; checking that a player really did
+  it is your job. `review` shows what a cheater gets on each route.
+- **Nothing runs by itself.** Draws, settles and schedule runs are sent by someone, usually your app.
+- **Fees:** 0.002 SOL per player action and 0.00001 SOL per project action, plus rent. `cost` gives the totals.
+
+The full list, with the details behind each, is in [Before you use it](docs/before-you-use.md). Some things aren't
+built yet: read the [known limits](docs/program.md#known-limits) before promising players something unusual.
+
+## Questions
+
+**How do I make a loot box or gacha on Solana without writing a smart contract?** Describe it as a box (its price,
+its outcomes and their odds), run `check` and `simulate`, then `approve` it in your wallet. If the randomness oracle
+never answers, the buyer can get a refund. See the [tutorial](docs/tutorial-loot-box.md) and the
+[examples](examples).
+
+**Can I add staking to an NFT collection I didn't mint?** Yes. A staking farm takes any collection, with lock tiers,
+boosts and reward rates, and needs no authority over the NFTs. See [NFTs and tokens](docs/nfts.md).
+
+**Can I run a lottery, raffle or auction without deploying a program?** Yes: lotteries (no-loss ones too), raffles
+with allowlists, and auctions that refund the outbid at once are all part of the same spec.
+
+**Is there an MCP server or Claude Code plugin for this?** Yes: the `xsolana` plugin for Claude Code and Codex, the
+hosted server at `https://xgames.fun/mcp`, and the local server for any MCP client. It's in the MCP Registry as
+`io.github.XGamesFun/solana-kit`.
+
+**How is this different from writing my own Anchor program?** Nothing is written or deployed per project: one shared
+program enforces every project's rules, and it is tested instruction by instruction. The trade-off is that you can
+build what the spec can describe, which is a lot, but not everything.
+
+**Can players with no SOL play?** Yes, if you sponsor their fees from your own server
+(`@xgamesfun/solana/sponsor`). They still pay any price themselves.
+
+## Learn more
+
+- [Loot box tutorial](docs/tutorial-loot-box.md): one sentence to going live, step by step
+- [Examples](examples): whole economies that are checked and put live in the tests
+- [How the program works](docs/program.md): who signs, every instruction, fees, limits, receipts
+- [NFTs and tokens](docs/nfts.md): with and without the project's authority
+- [Trust and cheating](skills/xsolana-economy/references/trust-and-cheating.md): what your server must check
+- [The agent skill](skills/xsolana-economy/SKILL.md): what an AI agent follows to build an economy
+- [Agents and harnesses](docs/harnesses.md): every way to reach the tools, and how releases are made
+- [Changelog](CHANGELOG.md) · [Security](SECURITY.md) · [xgames.fun/solana](https://xgames.fun/solana)
 
 ## Contributing
 
-Issues and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Please run `npm run check` before
-sending a change, and report a vulnerability privately as [SECURITY.md](SECURITY.md) describes.
+Issues and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) has the setup (`npm ci`, `npm run fixtures`,
+`npm run check`), the repository's layout and how to send a change. Report a vulnerability privately, as
+[SECURITY.md](SECURITY.md) describes.
 
 ## License
 
-[Apache-2.0](LICENSE). See [NOTICE](NOTICE) and [DISCLAIMER.md](DISCLAIMER.md): provided as is, without warranty, at your
-own risk.
+[Apache-2.0](LICENSE). See [NOTICE](NOTICE) and [DISCLAIMER.md](DISCLAIMER.md).

package/js/approve/details.mjs

@@ -6,10 +6,31 @@ import { decodeBorsh } from '../chain/borsh.js';
 import { equalBytes, toHex } from '../chain/bytes.js';
 import { accountKind, decode, IDL, instructionOf, keyLeaf, merkleRoot } from '../client/index.js';
 import { LOOT_PROGRAM, pda } from '../client/pda.js';
+import { dateWords, FAR_SECONDS } from '../economy/check.mjs';
 import { fromUnits } from '../economy/model.mjs';
 import { grantArgs } from '../economy/plan.mjs';
 
 const NOBODY = '11111111111111111111111111111111';
+/** What places of tokens from a short pool get, by their `when_short`. */
+const SHORT = {
+  InOrder: 'whole prizes, first place first, while the pool covers one',
+  InProportion: 'every place the same share of its prize',
+  Nothing: 'no place gets anything, and the pool keeps it',
+};
+/** What a far time is, by the field that holds it. */
+const FAR = {
+  draws_at: 'The first draw',
+  ends_at: 'The auction ends',
+  result_by: 'The result is due',
+  next_at: 'The first run',
+};
+/** A number of seconds in words: "1 day", "36 hours", "90 seconds". */
+const duration = v => {
+  const n = Number(v);
+  if (n % 86_400 === 0) return `${n / 86_400} day${n === 86_400 ? '' : 's'}`;
+  if (n % 3_600 === 0) return `${n / 3_600} hours`;
+  return `${n} seconds`;
+};
 const ZERO = new Uint8Array(32);
 
 /** An instruction's accounts by name, nested groups flattened, in the order the program takes them. */
@@ -32,11 +53,12 @@ function readLootInstruction(ix) {
  * connected; `treasury`: the treasury's address when it is known (else "your wallet" stands for it, as the setup
  * makes it).
  */
-export function namesOf(m, { owner = null, treasury = null } = {}) {
+export function namesOf(m, { owner = null, treasury = null, now = null } = {}) {
   return {
     m,
     owner,
     treasury,
+    now,
     pools: new Map(m.pools.map(p => [p.index, p.key])),
     stashes: new Map(m.stashes.map(s => [s.id, s.name ?? s.key])),
     grants: new Map(m.grants.map(g => [g.id, g])),
@@ -151,6 +173,8 @@ function readDetails(reads, names) {
           : treasury()
         : treasury();
     const to = v => (v === 'Burn' ? 'burned' : `to ${where(v)}`);
+    // A time more than three years after now: the program takes it, and the owner sees its date before signing.
+    const far = v => Number(v) - (names.now ?? Math.floor(Date.now() / 1000)) > FAR_SECONDS;
     const isTo = v =>
       v === 'Burn' ||
       v === 'Treasury' ||
@@ -176,7 +200,33 @@ function readDetails(reads, names) {
               ? `Places paid from: its pot ${v.Pot[0]}, kept from round to round (what anyone sends it, yield and what earlier rounds left all count)`
               : `Places paid from: each round’s own ticket money alone; what they leave is ${v.Round.rest === 'Burn' ? 'burned' : `sent to ${where(v.Round.rest)}`}`,
           );
-        } else if (k === 'to' && isTo(v))
+        } else if (k === 'when_out' && v === 'GiveNothing')
+          lines.push(
+            'When an outcome is out: a draw on it gives nothing, and a paid draw is not refunded (the box keeps selling)',
+          );
+        else if (k === 'closes_before' && BigInt(v ?? 0) > 0n)
+          lines.push(`Sales close ${duration(v)} before each draw`);
+        else if (k === 'time_weighted' && v === true)
+          lines.push(
+            'Tickets weighed by time: each purchase counts its tickets times the seconds left until sales close, so a ticket bought early has a better chance',
+          );
+        else if (k === 'places' && Array.isArray(v)) {
+          // What places of tokens from a pool get when it is short, read once when the draw is asked.
+          const short = [...new Set(v.filter(p => p?.prize?.Tokens?.from?.Pool).map(p => p.when_short))];
+          if (short.length)
+            lines.push(
+              `If a pool its places are paid from holds less than they win: ${short.map(x => SHORT[x] ?? x).join('; ')}`,
+            );
+          walk(v);
+        } else if (['draws_at', 'ends_at', 'result_by', 'next_at'].includes(k) && far(v))
+          lines.push(
+            `${FAR[k]} on ${dateWords(Number(v))}, ${Math.floor((Number(v) - (names.now ?? Math.floor(Date.now() / 1000))) / 31_536_000)} years from now: what waits on it is locked until then. Check the unit before approving`,
+          );
+        else if (k === 'extend' && read.name === 'open_auction' && Number(v) > FAR_SECONDS)
+          lines.push(
+            `A late bid moves the end by ${duration(v)}: one bid holds the lot and itself that long. Check the unit before approving`,
+          );
+        else if (k === 'to' && isTo(v))
           lines.push(v === 'Burn' ? 'Burns the tokens it takes' : `Sends tokens to ${where(v)}`);
         else if (k === 'Give' && Array.isArray(v) && typeof v[0] === 'string')
           lines.push(`Gives the NFT to ${address(v[0])}`);

package/js/approve/live-check.mjs

@@ -6,7 +6,6 @@
 import { encodeBase58 } from '../chain/base58.js';
 import { parseCoreCollection, MPL_CORE_PROGRAM } from '../chain/core.js';
 import { parseMint } from '../chain/mint.js';
-import { mayStartFrozen } from '../chain/token2022.js';
 import { accountKind, decode } from '../client/accounts.js';
 import { BUBBLEGUM_PROGRAM, LOOT_PROGRAM, pda } from '../client/pda.js';
 import { SYSTEM_PROGRAM } from '../chain/pda.js';
@@ -128,16 +127,6 @@ export class MintMismatch extends Error {}
  */
 export async function checkMints({ m, chain }) {
   const named = [...m.tokens.values()].filter(t => t.mint && !t.mint.startsWith('@'));
-  // The routes that read a mint's default account state once, as they open, and refuse one that can start frozen.
-  const once = new Map();
-  const reads = (key, what) => key && !once.has(key) && once.set(key, what);
-  for (const l of m.lotteries)
-    (reads(l.currency ?? m.currencyKey, `the lottery ${l.name ?? l.key}`),
-      reads(l.ticketCurrency, `the lottery ${l.name ?? l.key}`));
-  for (const c of m.contests) reads(c.currency ?? m.currencyKey, `the contest ${c.name ?? c.key}`);
-  for (const a of m.auctions) reads(a.currency ?? m.currencyKey, `the auction ${a.name ?? a.key}`);
-  for (const s of m.schedules.filter(x => x.sealed))
-    reads(s.currency ?? m.currencyKey, `the sealed schedule ${s.name ?? s.key}`);
   for (const t of named) {
     const what = `the token ${t.symbol ?? t.key} (“${t.key}”)`;
     if (t.wsol) {
@@ -162,10 +151,6 @@ export async function checkMints({ m, chain }) {
       throw new MintMismatch(
         `The spec says ${what} is a ${t.program} token; its mint ${t.mint} is ${mint.program}. Write "program": "${mint.program}".`,
       );
-    if (once.has(t.key) && mayStartFrozen(account))
-      throw new MintMismatch(
-        `The mint ${t.mint} of ${what} has a default account state that starts new accounts frozen, or that its freeze authority can switch to frozen, so ${once.get(t.key)} would be refused as it opens (the program refuses such a mint wherever a refund or a payout goes into an account opened for it). Use another token there.`,
-      );
   }
   await checkTreasury({ m, chain });
 }

package/js/approve/server.mjs

@@ -221,6 +221,7 @@ export async function createApproval({
    */
   const names = () =>
     namesOf(model(spec, { now: at }), {
+      now: at,
       treasury: madeSoFar(live())?.treasury ?? model(spec, { now: at }).treasuryWallet ?? null,
     });
   /**
@@ -232,7 +233,7 @@ export async function createApproval({
   async function readLive(p) {
     if (!spec.live?.published || typeof chain.account !== 'function') return;
     // The names a published list or key list goes by: the published spec's, each held against the root on chain.
-    const n = namesOf(model(spec.live.published, { now: at }), { treasury: p.ctx.treasury });
+    const n = namesOf(model(spec.live.published, { now: at }), { now: at, treasury: p.ctx.treasury });
     const was = new Map();
     for (const t of p.transactions) {
       for (const [i, step] of t.steps.entries()) {
@@ -381,14 +382,14 @@ export async function createApproval({
       trusted = await trust(wallet);
     } catch (e) {
       if (!(e instanceof ApproveError)) throw e;
-      const v = view(p0, namesOf(model(spec, { now: at }), { owner: wallet }), { refused: e.message });
+      const v = view(p0, namesOf(model(spec, { now: at }), { now: at, owner: wallet }), { refused: e.message });
       return { ...v, remaining: p0.ok ? p0.transactions.length : 0, done: false };
     }
     if (!p0.ok || !p0.transactions.length)
       return { ...view(p0, names(), { project: trusted.project }), remaining: 0, done: p0.ok };
     const p = await build(trusted.owner);
     await readLive(p);
-    const v = view(p, namesOf(model(spec, { now: at }), { owner: wallet, treasury: p.ctx.treasury }), {
+    const v = view(p, namesOf(model(spec, { now: at }), { now: at, owner: wallet, treasury: p.ctx.treasury }), {
       project: p.ctx.project,
     });
     return { ...v, remaining: p.transactions.length, done: false };
@@ -435,7 +436,7 @@ export async function createApproval({
       return wireTransaction(message, sigs);
     });
     // What each transaction pays to whom, read back from the very instructions the wallet signs.
-    const n = namesOf(model(spec, { now: at }), { owner: wallet, treasury: p.ctx.treasury });
+    const n = namesOf(model(spec, { now: at }), { now: at, owner: wallet, treasury: p.ctx.treasury });
     // Every line names the project it goes to first: always the wallet's own, or the one it is the authority of.
     const details = batch.map(t => [
       `Project: ${p.ctx.project}${p.ctx.owner === wallet ? ' (your own)' : ` (owned by ${p.ctx.owner})`}`,

package/js/chain/token2022.js

@@ -60,8 +60,9 @@ export function hookProgramOf(mintData) {
 /**
  * Whether a mint's new accounts start frozen, or can be made to (as the program judges it): a Token-2022
  * mint carrying `DefaultAccountState` set to frozen, or set to anything while it has a freeze authority, which can switch
- * it to frozen whenever it likes. An auction, a contest, a lottery, an offer and a sealed schedule refuse such a mint:
- * each reads the setting once, as it opens, and a refund or payout opened into a frozen account would never land.
+ * it to frozen whenever it likes. The program takes such a mint everywhere: it is the project's choice. A refund or a
+ * payout opened into an account that starts frozen does not land until its issuer thaws it, so the tools warn the
+ * project, and a bidder or a borrower before they sign.
  */
 export function mayStartFrozen({ owner, data }) {
   if (