@xgamesfun/solana 0.25.0 → 0.25.1

package/DISCLAIMER.md

@@ -35,7 +35,7 @@ Read this before you use this package, its tools or the loot program. Using them
 
 ## Limitation of liability
 
-To the fullest extent the law allows, games.fun, XGamesFun and the contributors to this package are not liable for any
+To the fullest extent the law allows, xgames.fun, XGamesFun and the contributors to this package are not liable for any
 loss or damage of any kind, direct or indirect, including lost funds, tokens, NFTs, profits or data, arising from the
 use of, or inability to use, this package, the loot program, the results server or anything built with them, even if
 told such loss was possible.

package/NOTICE

@@ -1,10 +1,10 @@
 loot
-Copyright 2026 games.fun
+Copyright 2026 xgames.fun
 
-This product includes software developed at games.fun.
+This product includes software developed at xgames.fun.
 
-Parts of the JavaScript client and tools (js/) are adapted from the games.fun kit,
-MIT License, Copyright (c) 2026 games.fun.
+Parts of the JavaScript client and tools (js/) are adapted from the xgames.fun kit,
+MIT License, Copyright (c) 2026 xgames.fun.
 
 The tests run upstream Solana programs (SPL Token, Token-2022, Associated Token, Memo,
 Metaplex Core, Token Metadata, Bubblegum, Account Compression, Noop, MagicBlock VRF) as

package/README.md

@@ -6,7 +6,7 @@ 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 ten `xsolana_*` tools;
+- 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.
 
@@ -35,7 +35,10 @@ An economy is a JSON spec, not a new smart contract. Every project shares the on
 - **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.
+  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
@@ -102,13 +105,13 @@ codex plugin add xsolana@xgamesfun
 ```
 
 **Any agent with MCP** (Cursor, opencode, Cline…): run the server with
-`npx -y --package=@xgamesfun/solana@0.25.0 xsolana mcp`. Or let `npx -y @xgamesfun/solana@0.25.0 connect` register it, with
+`npx -y --package=@xgamesfun/solana@0.25.1 xsolana mcp`. Or let `npx -y @xgamesfun/solana@0.25.1 connect` register it, with
 the skill, for Claude Code and Codex.
 
 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"_.
 
-Going live is always yours: `npx -y @xgamesfun/solana@0.25.0 approve` opens a page on your computer where you connect a
+Going live is always yours: `npx -y @xgamesfun/solana@0.25.1 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.
 
 ## Use it from a terminal
@@ -116,12 +119,13 @@ devnet wallet and approve each transaction. The agent never signs and never asks
 Every tool runs from the CLI too, on a spec file (`xsolana.json` by default):
 
 ```bash
-npx -y @xgamesfun/solana@0.25.0 examples shop with loot boxes   # the nearest worked examples
-npx -y @xgamesfun/solana@0.25.0 check xsolana.json                 # refusals and warnings
-npx -y @xgamesfun/solana@0.25.0 simulate xsolana.json              # where the money goes, day by day
-npx -y @xgamesfun/solana@0.25.0 cost xsolana.json                  # what going live and each action cost
-npx -y @xgamesfun/solana@0.25.0 explain xsolana.json               # the economy in plain words
-npx -y @xgamesfun/solana@0.25.0 approve xsolana.json               # go live, approved in your own wallet
+npx -y @xgamesfun/solana@0.25.1 examples shop with loot boxes   # the nearest worked examples
+npx -y @xgamesfun/solana@0.25.1 check xsolana.json                 # refusals and warnings
+npx -y @xgamesfun/solana@0.25.1 simulate xsolana.json              # where the money goes, day by day
+npx -y @xgamesfun/solana@0.25.1 cost xsolana.json                  # what going live and each action cost
+npx -y @xgamesfun/solana@0.25.1 explain xsolana.json               # the economy in plain words
+npx -y @xgamesfun/solana@0.25.1 review xsolana.json                # what a cheater gets on each route (exits 1 on a high finding)
+npx -y @xgamesfun/solana@0.25.1 approve xsolana.json               # go live, approved in your own wallet
 ```
 
 `xsolana help` lists every command. Every command names the exact version, so `npx` runs that release and never whatever
@@ -138,30 +142,31 @@ import * as loot from '@xgamesfun/solana/client';
 const ix = loot.openBoxIx({ player, project, box, nonce }); // one builder per instruction, no Solana SDK
 ```
 
-| Import                           | What                                                                                 |
-| -------------------------------- | ------------------------------------------------------------------------------------ |
-| `@xgamesfun/solana`              | the economy tools: `check`, `simulate`, `plan`, `cost`, `explainEconomy`, `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                          |
+| 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.
 
 ## Documentation
 
-|                                                              |                                                                                             |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| [`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                                                                  |
-| [`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                                        |
+|                                                                                    |                                                                                             |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [`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
 

package/bin/xsolana.mjs

@@ -5,7 +5,7 @@
 //   xsolana mcp                          serve the tools over stdio (what a plugin's MCP config runs)
 //   xsolana guide [part] [--json]        what an economy can be made of, and what loot cannot do
 //   xsolana examples [words…] [--json]   the nearest worked examples and rated economies
-//   xsolana check|simulate|cost|explain|publish|status [file] [--json]   one tool on a spec file (default xsolana.json)
+//   xsolana check|simulate|cost|explain|review|publish|status [file] [--json]   one tool on a spec file (default xsolana.json)
 //   xsolana approve [file] [--port n] [--no-open]   open the local page where the owner approves going live in their wallet
 //   xsolana connect [--agent claude|codex] [--scope user|project] [--local] [--remove] [--dry-run]   register the MCP server and the skill
 //   xsolana tool --list | xsolana tool <name> '<json>' [--args-file f] [--json]   any tool by name
@@ -25,6 +25,7 @@ const USAGE = `xsolana: the tools for loot, one shared Solana program for game a
   xsolana simulate [file]         the quick simulation
   xsolana cost [file]             what going live and each action cost
   xsolana explain [file]          the economy in plain words
+  xsolana review [file]           what a cheater gets on each route, and what to fix before going live
   xsolana publish [file]          what going live does, and how to approve it
   xsolana approve [file]          approve going live in your own wallet (a local page; --port n, --no-open)
   xsolana status [file]           a live economy on chain
@@ -33,7 +34,8 @@ const USAGE = `xsolana: the tools for loot, one shared Solana program for game a
   xsolana tool --list             every tool; xsolana tool <name> '<json>' runs one (--args-file f)
   xsolana version                 this package's xsolana version and program
 
-  A tool's command (guide, examples, check … status, tool) takes --json for its whole answer as JSON.`;
+  A tool's command (guide, examples, check … status, tool) takes --json for its whole answer as JSON.
+  review exits 1 when it finds something high.`;
 
 /** A failure the person caused (a bad flag, a missing file): said in one line, without a stack. */
 class UsageError extends Error {}
@@ -50,6 +52,7 @@ const FLAGS = {
   simulate: TOOL_FLAGS,
   cost: TOOL_FLAGS,
   explain: TOOL_FLAGS,
+  review: TOOL_FLAGS,
   publish: TOOL_FLAGS,
   status: TOOL_FLAGS,
   approve: ['--port', '--no-open'],
@@ -105,8 +108,10 @@ async function main(argv) {
     const { runTool } = await import('../js/mcp/server.mjs');
     const r = await runTool(name, input, { cwd: process.cwd() });
     const failed = Boolean(r.isError || r.ok === false);
+    // A review is a report whatever it finds: printed on stdout, its exit code saying whether a finding is high.
+    const report = name === 'xsolana_review' && !r.isError && !r.refusals;
     if (flags.has('--json')) console.log(JSON.stringify(r, (_, v) => (typeof v === 'bigint' ? v.toString() : v), 2));
-    else (failed ? console.error : console.log)(r.text ?? JSON.stringify(r, null, 2));
+    else (failed && !report ? console.error : console.log)(r.text ?? JSON.stringify(r, null, 2));
     if (failed) process.exitCode = 1;
   }
 
@@ -128,6 +133,7 @@ async function main(argv) {
     case 'simulate':
     case 'cost':
     case 'explain':
+    case 'review':
     case 'publish':
     case 'status':
       await tool(`xsolana_${command}`, fileInput());

package/examples/stakers-draw.json

@@ -84,6 +84,7 @@
   "grants": [
     {
       "key": "race",
+      "trust": "decides",
       "name": "Weekly race rewards",
       "prize": {
         "gives": "tokens",

package/js/client/random.js

@@ -1,7 +1,7 @@
 // The loot program's rolling module (`src/random`), mirrored: every random choice it makes is drawn from a stream of
 // the oracle's answer, by a path that names what is drawn, with one unbiased sampler. A page shows from an order's
 // answer what each draw gave (and a fresh unit's range traits) exactly as the program drew them. Held to the
-// program's own vectors (`js/test/fixtures/roll-vectors.json`, from gamesfun-loot's `tests/fixtures`).
+// program's own vectors (`js/test/fixtures/roll-vectors.json`, from the program's own tests).
 import { concat, uintLE } from '../chain/bytes.js';
 import { sha256 } from '../chain/sha256.js';
 

package/js/economy/check.mjs

@@ -4909,6 +4909,16 @@ export function check(economy, { network = 'devnet', now = Math.floor(Date.now()
             ? 'Make each claim cost a sybil something: a gate on holding a collectible the game sells or a locked stake, or vouchers from your server that count people ("perPerson", with an outside sign-in such as X). Keep "perDay" and "total" small either way.'
             : 'Give it a gate (a collectible each claimer must hold), or keep "total" small.',
       );
+    // `trust` says what the server holding a voucher key checks: a grant with no voucher key or code has no such server.
+    if (g.trust && !vouchers.length && !keys.length)
+      refuse(
+        'E-GRANT-TRUST',
+        `${where}.trust`,
+        `${label(g)} says its server ${g.trust} the result ("trust"), but it is paid ${open ? 'to any wallet that asks (it is open)' : 'to the wallets on its list'}: no server signs for it, so nothing checks what a claimer did.`,
+        open
+          ? 'Remove "trust", or name the server’s public key in "vouchers" so its claims are signed.'
+          : 'Remove "trust": the list is the owner’s own choice, written in the spec.',
+      );
     for (const [i, v] of vouchers.entries())
       if (!isAddress(v))
         refuse(
@@ -5175,6 +5185,7 @@ export function check(economy, { network = 'devnet', now = Math.floor(Date.now()
       'W-VOUCHERS',
       'economy.grants',
       `A voucher key signs who earned a grant: whatever holds it (your server, a play host) decides who gets rewards, within the limits the program keeps. The program does not check that a player really did what the voucher says. The keys: ${voucherKeys.join(', ')}.`,
+      'Say on each such grant what its server checks before it signs ("trust": "decides", "replays" or "bounds"), run xsolana_review, and tell the person what a cheater gets.',
     );
 
   if (randomItems && !chance)

package/js/economy/cost.mjs

@@ -108,7 +108,7 @@ export function setupCost(plan, economy) {
 }
 
 /**
- * What each action costs whoever signs it while the economy runs: games.fun's fee, the network's, and for anything
+ * What each action costs whoever signs it while the economy runs: xgames.fun's fee, the network's, and for anything
  * that asks MagicBlock's oracle for a random number (a box's open, a lottery's draw, the authority's `roll`) the
  * oracle's own fee (`oracleSol`, model.mjs ORACLE_FEE).
  */

package/js/economy/explain.mjs

@@ -26,6 +26,7 @@ import {
   whenOutWords,
 } from './model.mjs';
 import { farmEnds, playSteps } from './plan.mjs';
+import { TRUST_WORDS } from './trust.mjs';
 import { inAll, poolFate, round, simulate, unnamedExceptions, unnamedWords } from './simulate.mjs';
 
 const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
@@ -75,7 +76,7 @@ const paysWords = (l, treasury) =>
     ? `its places are paid from its pot (an account of its own, which only its winners are paid from): each place takes its percent of what the pot holds when the draw is asked, with the round’s ticket money, so whatever reaches the pot counts (the seed, a sponsor, shares of other sales, yield) and so does what earlier rounds’ places left; what this round’s places leave stays in the pot, and the next round always starts with it`
     : `its places are paid from each round’s own ticket money alone, which nothing sent from outside can change (no seed, no gift, no carry-over); what the places leave, and the part of places nobody won, goes ${toWords(destination(l.rest), treasury)}${l.rest === 'burn' ? ' when the round closes' : ''}`;
 
-const ruleWords = r => {
+export const ruleWords = r => {
   if (!r) return '';
   if (r.wallets) return `they are one of the ${r.wallets.length} wallets it names`;
   if (r.items) return `any of ${r.items.map(k => `“${k}”`).join(', ')}`;
@@ -99,7 +100,7 @@ const stakeWords = (staked, m) => {
   );
 };
 /** A gate in a sentence: "Only players who show …", "Only the wallets it names …", "Only wallets with … staked …". */
-const gateWords = (gate, verb, m) =>
+export const gateWords = (gate, verb, m) =>
   !gate
     ? ''
     : gate.wallets
@@ -464,8 +465,14 @@ export function explainEconomy(economy, { now = Math.floor(Date.now() / 1000) }
     const who = signers.length ? signers.join(' or ') : 'that asks (it is open to any wallet)';
     // A grant of a fixed amount of tokens, paid by voucher or list: each claim may name its own amount, up to the grant's.
     const named = signers.length > 0 && src.prize?.gives === 'tokens';
+    // What the voucher's server checks before it signs (`trust`): the spec's own word, never sent on chain.
+    const trust = src.trust
+      ? ` What its server checks: ${TRUST_WORDS[src.trust]}.`
+      : (src.vouchers ?? []).length
+        ? ' What its server checks before it signs is not said ("trust"): xsolana_review reads it as the weakest, a server that only bounds what the page reports.'
+        : '';
     actions.push(
-      `Claim “${g.name}” (only the winning wallet claims, signing it; anyone may pay its fees): gives ${g.gives}, to a wallet ${who}${limits ? `; limits ${limits}` : '; no limits'}${src.gate ? (src.gate.wallets ? `; only the ${src.gate.wallets.length} wallets it names` : src.gate.list || src.gate.staked ? `; ${gateWords(src.gate, 'claim it', m).replace(/^Only/, 'only')}` : `; the wallet must hold ${ruleWords(src.gate)}${!signers.length ? ', and each one of those claims once too' : ''}`) : ''}${named ? `; a voucher or the list can name each claim’s own amount, up to that (a reward by rank or share)` : ''}. Each claim costs the grant’s funds about ${num(g.fundsPerClaimSol)} SOL of rent, and whoever sends it the ${fee} SOL player fee.`,
+      `Claim “${g.name}” (only the winning wallet claims, signing it; anyone may pay its fees): gives ${g.gives}, to a wallet ${who}${limits ? `; limits ${limits}` : '; no limits'}${src.gate ? (src.gate.wallets ? `; only the ${src.gate.wallets.length} wallets it names` : src.gate.list || src.gate.staked ? `; ${gateWords(src.gate, 'claim it', m).replace(/^Only/, 'only')}` : `; the wallet must hold ${ruleWords(src.gate)}${!signers.length ? ', and each one of those claims once too' : ''}`) : ''}${named ? `; a voucher or the list can name each claim’s own amount, up to that (a reward by rank or share)` : ''}. Each claim costs the grant’s funds about ${num(g.fundsPerClaimSol)} SOL of rent, and whoever sends it the ${fee} SOL player fee.${trust}`,
     );
   }
   for (const st of sim.stashes ?? []) {

package/js/economy/guide.mjs

@@ -139,7 +139,7 @@ export const CONVENTIONS = [
 export const SAFETY = [
   'A wallet is not a person: wallets are free, so a limit per wallet never limits a person. What bounds a reward is its totals ("perDay", "total": the most it can ever pay), and what makes farming cost something: a gate on holding a collectible the game sells or a locked stake, or vouchers from your server that count people ("perPerson": the voucher signer names a person hash, which needs an outside sign-in such as X; a wallet-only player has none).',
   'Open grants (no voucher, keys or list) pay any wallet: keep their prizes small or soulbound, gate them, and set "perDay". `xsolana_simulate` says what a crowd of wallets could take next to one.',
-  'The page can’t be trusted: a game runs in the player’s browser, so a result worth paying is decided or checked by your server, which signs the voucher. A server checks what a wallet holds with `collectiblesOf` / `holds`, pays only wallets a player proved (`proofRequest` / `verifyProof`), and makes promo codes with `makeCodes` (80 bits: a code’s key is public, so a short code can be guessed offline) and `codeAddresses` for the grant’s `keys` (all from `@xgamesfun/solana/results`).',
+  'The page can’t be trusted: a game runs in the player’s browser, so a result worth paying is decided or checked by your server, which signs the voucher. A server checks what a wallet holds with `collectiblesOf` / `holds`, pays only wallets a player proved (`proofRequest` / `verifyProof`), and makes promo codes with `makeCodes` (80 bits: a code’s key is public, so a short code can be guessed offline) and `codeAddresses` for the grant’s `keys` (all from `@xgamesfun/solana/results`). How far a signed result can be trusted is what the server checks: it decides the result (runs the game or match; the page sends only inputs), replays it (re-runs the page’s inputs from randomness it keeps), or only bounds it (pace, order, caps: a script at human speed gets through). Say which on each voucher grant (`"trust"`), and run xsolana_review before going live: it says what a cheater gets on every route.',
   'Bots play well: even a verified result pays a bot what it pays a good player. Keep token rewards for results small and capped (a grant’s limits), give SOL prizes only by chance (the oracle) or by what your server decides, and don’t let a minted farm rate run without end into what its token buys (it compounds: give it an end, a term or an upkeep).',
   'A gate costs a sybil most when it asks for something the game sells: a rule takes any of several items (`{ "items": ["oak", "pine"] }`, up to 16), and can read the attributes only the program writes on every minted collectible, `item_id`, `rarity`, `serial` and `made` (`{ "attribute": "rarity", "atLeast": 2 }`: any of the game’s Rare or better).',
 ];

package/js/economy/live.mjs

@@ -137,7 +137,8 @@ export function changedParts(economy) {
   const only = new Set();
   const fixed = [];
   const removed = [];
-  const strip = ({ id, index, shopBox, seller, ...rest }) => JSON.stringify(rest);
+  // A grant's `trust` is the spec's own note about its server, never sent on chain: changing it publishes nothing.
+  const strip = ({ id, index, shopBox, seller, trust, ...rest }) => JSON.stringify(rest);
   for (const [list, kind] of Object.entries(PART_LISTS)) {
     const before = new Map((published[list] ?? []).map(p => [p.key, p]));
     for (const part of economy[list] ?? []) {