@xgamesfun/solana 0.25.0 → 0.25.1

package/js/economy/schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/XGamesFun/solana-kit/main/js/economy/schema.json",
   "title": "A loot economy (spec version 2)",
-  "description": "One project's economy on the shared loot program: its currencies, collectibles, pools and the mechanics that move them. Kept as xsolana.json in a project (or as the `economy` section of a games.fun game). Amounts are in whole units of their token, percents are percents, durations are like \"7d\".",
+  "description": "One project's economy on the shared loot program: its currencies, collectibles, pools and the mechanics that move them. Kept as xsolana.json in a project (or as the `economy` section of an xgames.fun game). Amounts are in whole units of their token, percents are percents, durations are like \"7d\".",
   "type": "object",
   "required": ["version"],
   "additionalProperties": false,
@@ -363,7 +363,7 @@
       "type": "object",
       "required": ["key", "source"],
       "additionalProperties": false,
-      "description": "A currency. `sol`: SOL (players pay in wrapped SOL). `existing`: any mint by address, launched anywhere, classic or Token-2022, pump.fun included (games.fun takes no share of its fees). `project` (`game` is its older spelling): a token made when the economy goes live: the project mints it as its rules say (points, tickets, shards), or, with `supply`, a fixed supply minted once to the owner (a community token you keep).",
+      "description": "A currency. `sol`: SOL (players pay in wrapped SOL). `existing`: any mint by address, launched anywhere, classic or Token-2022, pump.fun included (xgames.fun takes no share of its fees). `project` (`game` is its older spelling): a token made when the economy goes live: the project mints it as its rules say (points, tickets, shards), or, with `supply`, a fixed supply minted once to the owner (a community token you keep).",
       "properties": {
         "key": {
           "$ref": "#/$defs/key"
@@ -397,8 +397,8 @@
           "$ref": "#/$defs/address"
         },
         "venue": {
-          "enum": ["games.fun", "pump.fun", "meteora", "other"],
-          "description": "Where the token trades, recorded for the app and not read or enforced by the tools: loot doesn't launch or trade tokens. A token launched elsewhere is `existing`, by its mint."
+          "enum": ["xgames.fun", "games.fun", "pump.fun", "meteora", "other"],
+          "description": "Where the token trades, recorded for the app and not read or enforced by the tools: loot doesn't launch or trade tokens. A token launched elsewhere is `existing`, by its mint. `games.fun` is the older spelling of `xgames.fun`."
         },
         "uri": {
           "$ref": "#/$defs/link"
@@ -2462,6 +2462,10 @@
           "type": "integer",
           "minimum": 1,
           "description": "About how many rounds each wallet will be paid over its life. Default 1."
+        },
+        "trust": {
+          "enum": ["decides", "replays", "bounds"],
+          "description": "What the server holding a voucher key checks before it signs, said honestly: \"decides\" (it runs the game or match itself; the page sends only inputs), \"replays\" (it runs the page's inputs again, from randomness it keeps, and reads the result), \"bounds\" (the page runs the game and reports; the server checks only pace, order and daily caps, so a script at human speed gets through). Never sent on chain and changes nothing that goes live: xsolana_review and xsolana_explain read it. Only on a grant with `vouchers` or `keys`."
         }
       }
     },

package/js/economy/trust.mjs

@@ -0,0 +1,15 @@
+// How far a result a voucher's server signs can be trusted: the levels a grant declares in `trust`, and each in
+// words. The spec's own note about its server: never sent on chain. Pure.
+
+/** The trust levels a voucher grant declares, strongest first. */
+export const TRUST_LEVELS = Object.freeze(['decides', 'replays', 'bounds']);
+
+/** Each trust level in words: what the server does, and what a cheater still gets. */
+export const TRUST_WORDS = Object.freeze({
+  decides:
+    'the server decides the result itself (it runs the game or the match; the page sends only inputs): nothing the page says can forge one, though a bot that plays well still earns what a good player does',
+  replays:
+    'the server runs the page’s inputs again and reads the result itself: a forged result fails, though a bot that plays well still earns, and one that knows the run’s randomness up front can search for the best run offline',
+  bounds:
+    'the page runs the game and reports the result, and the server checks only its pace, order and daily caps: a script that waits as long as a person would gets every reward, up to the limits',
+});

package/js/index.js

@@ -4,6 +4,7 @@ export { simulate, explain } from './economy/simulate.mjs';
 export { plan, setupSteps, playSteps } from './economy/plan.mjs';
 export { cost, explainCost } from './economy/cost.mjs';
 export { explainEconomy } from './economy/explain.mjs';
+export { review, describeReview, SEVERITIES, TRUST_LEVELS, TRUST_WORDS } from './economy/review.mjs';
 export { model } from './economy/model.mjs';
 export { prepare, recordLanded, changedParts } from './economy/live.mjs';
 export { guideText, catalog, CANNOT } from './economy/guide.mjs';

package/js/mcp/server.mjs

@@ -10,7 +10,7 @@ import { PROGRAM_INFO, tools, VERSION } from './tools.mjs';
 
 export const INSTRUCTIONS = [
   'loot is one shared Solana program for game and community economies (shops, loot boxes, lotteries, auctions, staking farms, crafting, contests, schedules, perks for holders of any NFT, capped rewards). An economy is a JSON spec, not a new smart contract: never write Anchor or Rust for what loot covers.',
-  'Start with xsolana_guide, then xsolana_examples with the person’s own words; write the spec; xsolana_check after every change; xsolana_simulate and xsolana_explain before telling them what it does; xsolana_save; xsolana_publish when they say to put it live (they approve in their own wallet: you never sign or ask for a key).',
+  'Start with xsolana_guide, then xsolana_examples with the person’s own words; write the spec; xsolana_check after every change; xsolana_simulate and xsolana_explain before telling them what it does; xsolana_review before going live (fix its high findings, say honestly what each voucher server checks, and tell the person what a cheater gets); xsolana_save; xsolana_publish when they say to put it live (they approve in their own wallet: you never sign or ask for a key).',
   `Program ${PROGRAM_INFO.program} on ${PROGRAM_INFO.cluster} (loot ${VERSION}). Devnet only until audited.`,
 ].join(' ');
 

package/js/mcp/tools.mjs

@@ -15,6 +15,7 @@ import { cost, explainCost } from '../economy/cost.mjs';
 import { changedParts } from '../economy/live.mjs';
 import { example, examples, ideas, search, partsUsed } from '../economy/examples.mjs';
 import { explainEconomy } from '../economy/explain.mjs';
+import { describeReview, review } from '../economy/review.mjs';
 import { CANNOT, catalog, guideText, PARTS } from '../economy/guide.mjs';
 import { model, rent as rentOf } from '../economy/model.mjs';
 import { plan } from '../economy/plan.mjs';
@@ -339,7 +340,7 @@ export const tools = [
       const verdict = check(economy, { now: nowOf(ctx) });
       const head = verdict.refusals.length || verdict.warnings.length ? describe(verdict) : 'No problems found.';
       const tail = verdict.ok
-        ? `\nReady (${plural(verdict.warnings.length, 'warning')}). Next: xsolana_simulate and xsolana_explain, and tell the person what it means in plain words.`
+        ? `\nReady (${plural(verdict.warnings.length, 'warning')}). Next: xsolana_simulate and xsolana_explain, and tell the person what it means in plain words; before going live, xsolana_review.`
         : `\n${plural(verdict.refusals.length, 'refusal')}: fix each as its fix says, then check again.`;
       return {
         ok: verdict.ok,
@@ -420,6 +421,30 @@ export const tools = [
       return { ...r, from, text: r.text + footer };
     },
   },
+  {
+    name: 'xsolana_review',
+    annotations: READ,
+    description:
+      'Review an economy the way a cheater reads it, before it goes live (not a validity check: xsolana_check is that). For every route that pays or gives value it says who can trigger it, what the program enforces, what it trusts off the chain, and the most one cheater gets; then findings with stable ids and a severity; then the trade-off to show the person: for each grant paid on vouchers, whether its server decides, replays or only bounds the result (its "trust"), what a cheater gets at that level, and what the next level costs to build. Fix every high finding, declare "trust" honestly on every voucher grant, and tell the person in plain words which level each signed route uses and what a cheater gets, so they choose the trade-off. Give the spec inline (`spec`), a file, or an example. Answers { ok (false when a finding is high, or the spec does not check: then `refusals`), routes: [{ kind ("grant", "farm", "item", "box", "payment", "recipe", "lottery", "contest", "auction", "schedule", "hold", "decision"), key, name, trigger, enforced: [words], trusts: [words], trust ("decides" | "replays" | "bounds" | null), ceiling (words), feeds: ["farm:<key>", …: what its prize is staked in, crafted into or buys] }], findings: [{ id (R-…), severity ("high" | "medium" | "low" | "info"), route ("grant:<key>", "farm:<key>", … or "economy"), message, fix }], tradeoffs (markdown) }.',
+    inputSchema: { type: 'object', properties: SOURCE, additionalProperties: false },
+    async handler(input, ctx) {
+      const { economy, from } = await load(input, ctx);
+      const r = review(economy, { now: nowOf(ctx) });
+      if (r.refusals) return refused({ refusals: r.refusals, warnings: [] }, from);
+      const highs = r.findings.filter(f => f.severity === 'high').length;
+      const tail = highs
+        ? `\n${plural(highs, 'high finding')}: fix ${highs === 1 ? 'it' : 'them'} (or have the person accept ${highs === 1 ? 'it' : 'them'} in plain words) before going live, then review again.`
+        : '\nNo high finding. Tell the person, in plain words, which level each signed route uses and what a cheater gets (the trade-offs above).';
+      return {
+        ok: r.ok,
+        from,
+        routes: r.routes,
+        findings: r.findings,
+        tradeoffs: r.tradeoffs,
+        text: `${describeReview(r, economy.name)}${tail}${footer}`,
+      };
+    },
+  },
   {
     name: 'xsolana_save',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },

package/js/results/index.js

@@ -1,5 +1,5 @@
 // `@xgamesfun/solana/results`: what a game uses with a results server, in a host server or in a player's game page.
-// Browser-safe: Web Crypto only. `server` is RESULTS_SERVER (the public one, on the games.fun play host), or another
+// Browser-safe: Web Crypto only. `server` is RESULTS_SERVER (the public one, on the xgames.fun play host), or another
 // one's URL. The server confirms who won (from signatures rooted on the chain) and signs grant vouchers; winners claim
 // them with js/play (`claimWins`, `claimGrant`). The program pays a wallet each round once, ever, whatever is signed.
 //
@@ -40,7 +40,7 @@ export {
   rosterHash,
 } from './wire.js';
 
-/** games.fun's results server, on its play host (devnet until the program's audit). */
+/** xgames.fun's results server, on its play host (devnet until the program's audit). */
 export const RESULTS_SERVER = 'https://play.xgames.fun/xsolana';
 
 const subtle = () => globalThis.crypto.subtle;

package/package.json

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

package/release.json

@@ -4,5 +4,5 @@
   "sbfBytes": 1741840,
   "sbfSha256": "ea19d15d03211f7bd0b25179d51f75544342225127fcb631e687eae6750c9ba7",
   "idlSha256": "41e621990c17b8645f59bb2a170271645ad370d1c1bf9f1dbdd04f817b82d4cf",
-  "clientSha256": "11270da0bd539b1cb79e8c61527e4b0686f2d03a2e2b617c823dcabf97f05f6e"
+  "clientSha256": "78b426dc003d261537934856302fe9767db149fd37b814af2569b95cc1333624"
 }

package/skills/xsolana-economy/SKILL.md

@@ -9,8 +9,8 @@ An economy is one JSON spec (`xsolana.json` in the project) on **loot**, a Solan
 writes or deploys a contract: the spec is checked, simulated and priced by the `xsolana_*` tools, and the project's
 owner puts it live by approving in their own wallet. It runs on **devnet** until the program is audited.
 
-The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.25.0 <guide|examples|check|simulate|cost|explain|publish|status> [xsolana.json]`,
-or `npx -y @xgamesfun/solana@0.25.0 tool <name> '<json>'` for any tool (always with the exact version).
+The tools are the `xsolana_*` MCP tools. Without MCP, the same from a terminal: `npx -y @xgamesfun/solana@0.25.1 <guide|examples|check|simulate|cost|explain|review|publish|status> [xsolana.json]`,
+or `npx -y @xgamesfun/solana@0.25.1 tool <name> '<json>'` for any tool (always with the exact version).
 
 ## Rules (always)
 
@@ -41,7 +41,9 @@ or `npx -y @xgamesfun/solana@0.25.0 tool <name> '<json>'` for any tool (always w
    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
+   decider's key, a list. The signer is not the end of the story: the program checks its signature and limits, never
+   what happened, so a signed result is worth what that server checks (it decides the result, replays it, or only
+   bounds what the page reports: rule 12). 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:
@@ -53,10 +55,12 @@ or `npx -y @xgamesfun/solana@0.25.0 tool <name> '<json>'` for any tool (always w
      table.
 
 10. **Design for many wallets and bots.** Wallets are free and bots play well: bound every reward with totals
-    (`perDay`, `total`), gate open rewards on holding something or count people by vouchers (`perPerson`), keep token
-    rewards for results small, and have a server check what the page claims (`@xgamesfun/solana/results`:
-    `collectiblesOf`, `verifyProof`, `makeCodes`). The checker warns about the rest (`W-GRANT-TOTAL`, `W-GRANT-OPEN`,
-    `W-FARM-MINT`); xsolana_guide's "Designing against farming" says why.
+    (`perDay`, `total`), gate open rewards on holding something or count people by vouchers (`perPerson`, with the
+    server naming an X account, never a wallet), keep token rewards for results small, and have a server decide or
+    replay a result worth paying rather than take the page's word (`@xgamesfun/solana/results`: `collectiblesOf`,
+    `verifyProof`, `makeCodes`). Keep entry fees and prize pools for results the server decides and for chance, and
+    give a minted farm an end. The checker warns about the rest (`W-GRANT-TOTAL`, `W-GRANT-OPEN`, `W-FARM-MINT`);
+    `references/trust-and-cheating.md` says why.
 
 11. **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
@@ -66,6 +70,14 @@ or `npx -y @xgamesfun/solana@0.25.0 tool <name> '<json>'` for any tool (always w
     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.
 
+12. **Review before going live, and let the person choose the trade-off.** Run `xsolana_review` before the owner
+    approves. Fix every high finding, or have the person accept it in plain words. Declare `"trust"` honestly on every
+    voucher grant: `"decides"` (the server runs the game or match; the page sends only inputs), `"replays"` (it re-runs
+    the page's inputs from randomness it keeps) or `"bounds"` (it takes the page's word within a pace and caps). Then
+    tell the person, for each signed route, which level it uses, what a cheater gets (the review's ceiling, with what
+    the prize goes on to earn), and what the stronger level would cost to build. They choose; you don't choose for
+    them by leaving it out. `references/trust-and-cheating.md` has the levels, the costs and the checklist.
+
 ## The loop
 
 1. **Read what an economy can be made of**: `xsolana_guide` (every part and field, who acts and what it costs, what
@@ -96,14 +108,17 @@ or `npx -y @xgamesfun/solana@0.25.0 tool <name> '<json>'` for any tool (always w
    (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
+8. **Review it before they approve**: `xsolana_review` (rule 12). Fix the high findings, declare `trust` on every
+   voucher grant, and tell the person which level each signed route uses, what a cheater gets and what the stronger
+   level would cost. Run it again after every change that touches a route that pays.
+9. **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.25.0 approve xsolana.json`; never drop the version). It opens a page on their computer where
+   `npx -y @xgamesfun/solana@0.25.1 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`.
+10. **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
 
@@ -121,3 +136,4 @@ For staking an NFT of another collection, show what custody means and get explic
 - 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`
+- What a server decides, replays or bounds, who gets paid, and the exploit checklist: `references/trust-and-cheating.md`

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

@@ -101,7 +101,8 @@ now })` for the player's own wallet and claims (`app.claimGrant(key, { voucher }
   (`perPerson`, with a person hash the voucher names: that needs an outside sign-in such as X, and a wallet-only
   player has none); it checks what a wallet holds on the chain, never the page's word (`collectiblesOf`, `holds`); and
   the grant's `perDay` and `total` bound everything whatever happens to a key. Keep token rewards for results small.
-- **Vouchers from a results server**: the grant names the server's public key in `vouchers`; the server checks the
+- **Vouchers from a results server**: the grant names the server's public key in `vouchers`, and says in `trust`
+  what the server checks (`"decides"`, `"replays"` or `"bounds"`: `trust-and-cheating.md`); 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

package/skills/xsolana-economy/references/sentence-to-spec.md

@@ -40,6 +40,7 @@ maps to a part of the spec (`xsolana_guide` has every field).
 | "the expedition brings back a chest", "missions drop random loot"                                                                          | a farm tier's `prize`: `{ "gives": "roll", "box": "<box>" }`, rolled when the mission is completed (its lock stayed, its upkeep never ran dry, not forfeited) while the NFT goes home; a known reward (tokens, an item, an NFT) is given as it leaves                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | "only pass holders can buy it", "members only"                                                                                             | a `gate` of the item alone: `{ "item": "pass" }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | "only holders can open it", "level 5 and up"                                                                                               | a `gate`: `{ "item": "pass", "attribute": "level", "atLeast": 5 }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| "holders of any of our plots", "any of the three species", "gold or diamond tier"                                                          | a rule of several: `{ "items": ["oak", "pine", "birch"] }` (any of these items, in the game's own collection) or `{ "attribute": "tier", "oneOf": ["gold", "diamond"] }`, up to 16 each; it works wherever a rule does (a gate, a farm's gate or boost, odds, `rollsOn`, a recipe's `show`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | "only these players", "just the two of them", "the tournament's entrants"                                                                  | a `gate` of wallets: `{ "wallets": ["<address>", …] }` (a long list is a `list` gate instead, below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | "stake to enter", "staking tiers for a token sale", "only people who lock 100 of our token can buy"                                        | a farm of a token that nothing funds when staking pays nothing (no `seed`, no share or schedule into `"farm:<key>"`; `W-FARM-DRY` says so), and a `gate` `{ "staked": { "farm": "<farm of a token>", "atLeast": 100 } }`: the wallet's stake in that farm, counted only while its tier's lock runs and from the second after it is made (one stake can't move to another wallet and count again; a tier with no lock never passes, `W-STAKED`). The app passes the seat and the farm                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | "allowlist", "whitelist of 5,000 wallets", "a snapshot of our holders", "early supporters only"                                            | a `gate` `{ "list": ["<address>", …] }` of any size: the program keeps only its root, the page passes each player's proof (`W-LIST`); a new list is a new root, published again                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

package/skills/xsolana-economy/references/telling-the-person.md

@@ -40,6 +40,12 @@ and the spec differ (a limit, an amount, a key not set yet), change one of them
    For a collectible they already hold: "It stays with the project until someone wins it or the auction ends."
 8. **Anything else the checker warned about**, in a sentence each (a mint that can freeze accounts, a free box bots
    can drain, a grant with no limits or no funds).
+9. **What a cheater gets**, from `xsolana_review`, before the owner approves: for each route paid on a server's
+   voucher, which level it uses (the server decides, replays or only bounds the result), what one cheater gets there
+   (its ceiling, and what the prize goes on to earn), and what the stronger level would cost to build: "A script that
+   waits as long as a player would gets each reward NFT once per wallet, and each then earns tokens every day with no
+   end; having the server replay each run would stop forged runs, and needs the game to be deterministic." Then each
+   high finding and its fix. The person chooses the trade-off (`trust-and-cheating.md`).
 
 ## What stays the project's job
 

package/skills/xsolana-economy/references/trust-and-cheating.md

@@ -0,0 +1,126 @@
+# Trust and cheating
+
+The program enforces its own rules: a cheater can't take more than a route's limits, move a voucher to another
+wallet, harvest someone else's seat or mint into the project's collection. What a cheater can still take is what the
+economy's design and its servers leave open: a result the server never really checked, a person counted as many
+wallets, a reward that keeps earning for good. This page is how to read an economy for that, and how to tell the
+person what they are choosing. `xsolana_review` does the reading for a spec; this page says why.
+
+## How far a result can be trusted
+
+A result is worth paying only as far as the server that signs the voucher can tell it happened. Strongest first:
+
+- **The server decides it.** A turn game played on the server, or a room whose server runs the match: the page sends
+  inputs, never results. The result is what the server saw.
+- **The server replays it.** A deterministic game (a fixed time step, seeded randomness): the page sends its inputs,
+  and the server runs them again and reads the result itself. Mind CPU limits: replay short runs, or a long one in
+  pieces as it is played. Never hand the page the whole run's randomness up front: with the seed and the rules, a
+  script searches for the best run offline and sends only that. Reveal randomness as the run goes, or keep the seed on
+  the server; one open run per player, and count abandoned runs toward the day's.
+- **The server bounds it.** Any game the browser simulates: the server starts each run (an id and its own clock),
+  takes each checkpoint in order, refuses what is faster than the game allows, caps what one player earns a day, and
+  can ban. A script that plays at human speed still gets through: this limits what a cheater earns, it does not stop
+  one.
+
+| Level   | What it costs to build                                                                | CPU and latency                                           | What a cheater gets                                                          | Fits                                                                                  |
+| ------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| decides | the most: the game's rules run on the server (or in a room that runs the match)       | every move waits on the server                            | what a bot that plays well earns; nothing forged                             | turn games, card and board games, matches in a room, anything with hidden information |
+| replays | a deterministic game (fixed step, seeded randomness the server keeps) and a replayer  | a replay per run, after the fact; short runs or in pieces | what a bot that plays well earns; with the seed up front, the best run found | puzzles, runners, arcade games with short runs                                        |
+| bounds  | the least: a run id, the server's clock, checkpoints in order, daily caps, a ban list | almost none                                               | every reward a script claims at human speed, up to the limits                | anything the browser simulates; prizes that are cosmetic, small or capped             |
+
+Even a result the server decided is worth what a good bot can earn. Pay a bounded or replayed result only what you would
+accept losing to a patient script (small amounts, capped a day), and keep entry fees and prize pools for results the
+server decided and for chance (the oracle). Tell players which one your game is.
+
+**Say it in the spec.** Every grant paid on vouchers says what its server checks: `"trust": "decides"`, `"replays"` or
+`"bounds"`. It is the spec's own note (it never goes on chain, and changing it publishes nothing), and it must be
+honest: a server that takes the page's word within a pace is `bounds`, whatever else it does. `xsolana_review` reads a
+voucher grant that says nothing as `bounds`, the weakest.
+
+## Who gets paid: wallets are not people
+
+- **A wallet is free.** Any limit per wallet (`perWallet`, a gate's one claim per collectible shown) limits wallets,
+  never a person. What bounds a reward is its totals: `perDay` and `total` are the most it can ever pay, whatever
+  happens to a key or how many wallets come.
+- **Count people through vouchers.** `perPerson` counts the person the voucher names (a person hash), which only the
+  server chooses: the player can't pick or change it, and an open grant has none. So it is exactly as good as the
+  server's choice: a real outside identity (an X account) counts people; a wallet, or a voucher with no person, counts
+  nobody. For rewards worth farming, pay only players signed in with X.
+- **Make farming cost something.** Gate on holding a collectible the game sells or a locked stake (`gate`), pay only
+  wallets a player proved (`proofRequest` / `verifyProof`), and keep prizes for results small.
+- **Bots play well.** Even a verified result pays a bot what it pays a good player.
+
+## What the program guarantees
+
+These were attacked on devnet and refused by the program; there is nothing to build for them:
+
+- **A voucher is bound to its claim.** It signs the program, the grant, the grant's incarnation, the wallet, the person,
+  an expiry and its rounds. It can't be moved to another wallet, or replayed on another grant or a re-made one. A key
+  not among the grant's voucher keys is refused, and so is a claim with no voucher on a grant that isn't open.
+- **The winning wallet signs its own claim.** Anyone may pay its fees; nobody claims for it.
+- **A round pays a wallet once** per grant incarnation, whoever signs it again and whenever; `perWallet`,
+  `perPerson`, `perKey`, `perDay` and `total` are kept by the program.
+- **A farm's gate can't be forged.** It checks the project's collection and the item number the program writes at mint
+  and never lets change: an NFT of another collection, one in no collection, an attribute written by hand, or a mint
+  into the project's collection by anyone but the project are refused. Boosts read the staked NFT's own item number.
+- **One seat per NFT, ever.** In escrow, an NFT can't leave before its lock or be staked twice. Watched, an NFT sold
+  while staked earns its old staker nothing more, and its new holder takes the seat over. Nobody harvests or unstakes
+  someone else's seat.
+- **The project's keys.** A token the project mints has the project as its only minter and no freeze authority. Only
+  the authority mints or moves pool funds; only the owner changes mechanics or closes records. Money held for a
+  record (a farm's stakes and rewards, a pot, an order, a bid) leaves only by that record's rules.
+- **Chance is the oracle's.** Nobody, the project included, steers a roll or a draw.
+
+## What is still yours to get right: the checklist
+
+Run `xsolana_review` and go through what it reports; these are the points behind its findings.
+
+1. **The signer decides who is paid.** The program checks a voucher's signature, wallet and limits, never what
+   happened in the game. Declare `trust` honestly on every voucher grant, and make the server's checks match it.
+2. **Person counting.** `perPerson` holds only when the server names a real person (an X account) in every voucher,
+   never a wallet. Without it, each free wallet claims again: set `perDay` and `total` as if every claim were a new
+   wallet.
+3. **Sybil wallets.** Open grants (no voucher, code or list) pay any wallet that asks: gate them on something a sybil
+   must pay for, keep their prizes small or soulbound, and set `perDay`.
+4. **Voucher key custody.** The key's secret lives only on the server: never in a page, a repository, a spec or a
+   chat. Anyone holding it pays anyone, up to the grant's limits, which is why `perDay` and `total` matter. To rotate
+   it, put the new public key in the grant's `vouchers` and publish. Use a different key on each cluster: a voucher's
+   bytes don't name the cluster.
+5. **Re-made grants pay again.** Closing and making a grant again starts a new incarnation: a new campaign whose
+   limits start from zero, and whose list pays every listed round again. Give a re-made grant fresh rounds.
+6. **Emission without an end.** A farm whose rate is minted, with no `runs`, no term on every tier (`earnsFor`), no
+   upkeep and no halving, mints for as long as anything is staked. Every way to get what it takes is then worth that
+   stream: a cheatable claim of a staked NFT compounds into tokens for good. Give it an end, or pay its rate from its
+   vault.
+7. **Prizes worth farming.** A tradeable prize (tokens, an NFT that can be sold, a roll) on a route a script can reach
+   is what a cheater farms. Keep such prizes for results the server decides, or small and capped.
+8. **Entry fees and prize pools.** Players' money (a payment, a box's or a lottery's share into a pool) paid out on a
+   bounded or replayed result goes to whoever scripts it. Keep those for decided results and chance.
+9. **NFT farm custody.** Escrow moves the NFT to the project while staked; freeze locks it in the wallet; watch leaves
+   it free, so it can be sold while staked and its buyer takes the seat. The issuer's own controls still apply to
+   NFTs of other collections.
+10. **The gate.** A farm or a route gated on the project's items (`items`, `item_id`, `rarity`) is as strong as the
+    ways those items are had. A gate on another collection's attributes trusts whoever can write them.
+11. **The authority and the treasury.** The owner's wallet alone changes every price, rate, grant, limit and voucher
+    key; the authority mints, moves pool funds, decides contests and releases holds, with no caps. Keep them in a
+    hardware wallet or a multisig; a server that signs gets an authority key of its own, never the owner's.
+12. **The page is untrusted.** A page builds the player's transactions, and a cheater builds their own: the program's
+    checks are what count, never the page's. Anything the page decides (a score, a reward amount, who won) is only as
+    good as the server that checks it.
+13. **Ordering.** A lottery's tickets are not weighted by time: one buyer can take most of a round right before the
+    draw. Anyone, the seller included, can bid an auction up. A box that keeps selling when an outcome runs out
+    (`drawLeft`) lets someone watching the stock empty a common outcome to make a rare likelier.
+14. **Contests.** Players' stakes go to the side the authority or a decider key names: keep contests for results the
+    server decides, or that anyone can check outside the game.
+
+## Telling the person
+
+After `xsolana_review`, before the owner approves, say in plain words:
+
+- for each signed route, which level its server uses and what a cheater gets ("A script that waits long enough gets
+  a Legendary per wallet, up to 100 a day, and each earns 50 tokens a day for good");
+- what the next level would cost to build ("replaying runs needs the game to be deterministic and a server that re-runs
+  each run");
+- every high finding, and its fix, or that they accept it.
+
+They choose the trade-off, not you.

package/types/economy/cost.d.mts

@@ -11,7 +11,7 @@ export declare function setupCost(plan: any, economy: any): {
     notes: string[];
 };
 /**
- * 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/types/economy/explain.d.mts

@@ -1,3 +1,6 @@
+export declare const ruleWords: (r: any) => string;
+/** A gate in a sentence: "Only players who show …", "Only the wallets it names …", "Only wallets with … staked …". */
+export declare const gateWords: (gate: any, verb: any, m: any) => string;
 export declare function explainEconomy(economy: any, { now }?: {
     now?: number | undefined;
 }): {

package/types/economy/review.d.mts

@@ -0,0 +1,45 @@
+import { TRUST_LEVELS, TRUST_WORDS } from './trust.mjs';
+/** Severities, most serious first. */
+export declare const SEVERITIES: readonly string[];
+export { TRUST_LEVELS, TRUST_WORDS };
+/**
+ * The review of an economy: { ok, routes, findings, tradeoffs }. `ok` is false when there is a high finding, or when
+ * the spec does not check (then `refusals` says why, and the rest is empty).
+ */
+export declare function review(economy: any, { now }?: {
+    now?: number | undefined;
+}): {
+    ok: boolean;
+    refusals: any[];
+    routes: never[];
+    findings: never[];
+    tradeoffs: string;
+} | {
+    refusals?: undefined;
+    ok: boolean;
+    routes: ({
+        kind: string;
+        key: any;
+        name: any;
+        trigger: string;
+        enforced: any[];
+        trusts: any[];
+        trust: any;
+        ceiling: string;
+        feeds: any[];
+    } | {
+        kind: string;
+        key: any;
+        name: any;
+        trigger: string;
+        enforced: any[];
+        trusts: any;
+        trust: null;
+        ceiling: string;
+        feeds: any[];
+    })[];
+    findings: any[];
+    tradeoffs: string;
+};
+/** A review in words, for the terminal and the tool's text. */
+export declare function describeReview(r: any, name?: string): string;

package/types/economy/trust.d.mts

@@ -0,0 +1,8 @@
+/** The trust levels a voucher grant declares, strongest first. */
+export declare const TRUST_LEVELS: readonly string[];
+/** Each trust level in words: what the server does, and what a cheater still gets. */
+export declare const TRUST_WORDS: Readonly<{
+    decides: "the server decides the result itself (it runs the game or the match; the page sends only inputs): nothing the page says can forge one, though a bot that plays well still earns what a good player does";
+    replays: "the server runs the page’s inputs again and reads the result itself: a forged result fails, though a bot that plays well still earns, and one that knows the run’s randomness up front can search for the best run offline";
+    bounds: "the page runs the game and reports the result, and the server checks only its pace, order and daily caps: a script that waits as long as a person would gets every reward, up to the limits";
+}>;

package/types/index.d.ts

@@ -3,6 +3,7 @@ export { simulate, explain } from './economy/simulate.mjs';
 export { plan, setupSteps, playSteps } from './economy/plan.mjs';
 export { cost, explainCost } from './economy/cost.mjs';
 export { explainEconomy } from './economy/explain.mjs';
+export { review, describeReview, SEVERITIES, TRUST_LEVELS, TRUST_WORDS } from './economy/review.mjs';
 export { model } from './economy/model.mjs';
 export { prepare, recordLanded, changedParts } from './economy/live.mjs';
 export { guideText, catalog, CANNOT } from './economy/guide.mjs';

package/types/mcp/tools.d.mts

@@ -451,6 +451,68 @@ export declare const tools: ({
         from: any;
         text: string;
     }>;
+} | {
+    name: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            spec: {
+                type: string;
+                description: string;
+            };
+            file: {
+                type: string;
+                description: string;
+            };
+            example: {
+                type: string;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+        required?: undefined;
+    };
+    handler(input: any, ctx: any): Promise<{
+        ok: boolean;
+        from: any;
+        refusals: any;
+        warnings: any;
+        text: string;
+    } | {
+        ok: boolean;
+        from: any;
+        routes: ({
+            kind: string;
+            key: any;
+            name: any;
+            trigger: string;
+            enforced: any[];
+            trusts: any[];
+            trust: any;
+            ceiling: string;
+            feeds: any[];
+        } | {
+            kind: string;
+            key: any;
+            name: any;
+            trigger: string;
+            enforced: any[];
+            trusts: any;
+            trust: null;
+            ceiling: string;
+            feeds: any[];
+        })[];
+        findings: any[];
+        tradeoffs: string;
+        text: string;
+    }>;
 } | {
     name: string;
     annotations: {