@xgamesfun/solana 0.25.0 → 0.25.2

package/js/play/sponsor.js

@@ -0,0 +1,302 @@
+// A project pays its players' fees: a sponsor. The sponsor is a plain key on the project's own server, with no role in
+// the program: it is the transaction's fee payer, and it lends the player SOL in the same transaction, the player
+// giving back, last, all but what the step costs them beyond its price (the platform's player fee, the oracle's fee
+// for a roll, and the rent of what the program opens or mints for them). It lends first and takes back after because a
+// step can need more SOL midway than it costs (a wrapped-SOL account it opens and closes). A player with no SOL can then
+// play with what they hold. The price itself is never sponsored.
+//
+// The app (`solanaApp({ sponsor })`) builds the transaction with the sponsor as payer, the player's wallet signs it,
+// and the project's server checks it (`checkSponsored`) and signs it (`sponsorSigner`, `sponsorHandler`) before the
+// app sends it. The server trusts nothing the page says: it reads the transaction itself and dry-runs it. What it
+// holds to:
+//
+// - the sponsor appears in no instruction but its one loan, a plain transfer to a signer of the transaction (the
+//   player), and plain transfers back to it: no instruction can move the sponsor's SOL but the loan, sign as it, or
+//   name it otherwise;
+// - at least one instruction is this project's (a loot instruction naming the project), and none pays the project's
+//   fee box or the oracle straight from the page;
+// - no priority fee past the server's limit (none by default);
+// - in the dry run, what the sponsor is out (its loan less what came back) leaves the player no richer than they began,
+//   and is at most what the step cost in fees and rent: what the project's fee box and the oracle took, and the rent of
+//   what the program's own moves opened (`sponsoredCost`: a loot account, a token account of a mint the step's loot
+//   instructions name, a Core asset when the page calls Core itself nowhere). An account the page opens for itself (a
+//   plain key, a token account of any mint) is never sponsored: the player could close it and keep the rent;
+// - the loan and the network fee together are at most `maxLamports`, and the project's `budget` (per player, per day)
+//   agrees.
+//
+// What a sponsor can still lose: rent the program later gives back to the player (an order's, when it settles; a token
+// account the player closes), up to `maxLamports` a transaction, and a fee for a transaction that passed its dry run
+// but failed on chain. `budget` is where a project caps those.
+//
+// Browser-safe: the server side needs only an RPC and the sponsor's own `sign`, which the project's server provides
+// (this package never holds a key).
+import { readTable } from '../chain/lookup.js';
+import { COMPUTE_BUDGET_PROGRAM, TOKEN_2022_PROGRAM, TOKEN_PROGRAM } from '../chain/pda.js';
+import { transferLamports } from '../chain/programs.js';
+import { encodeBase58 } from '../chain/base58.js';
+import { fromBase64, toBase64 } from '../chain/bytes.js';
+import { readMessage, readTransaction, withSignature } from '../chain/tx.js';
+import { LOOT_PROGRAM, MPL_CORE_PROGRAM, pda, VRF_PROGRAM } from '../client/index.js';
+
+const SYSTEM_PROGRAM = '11111111111111111111111111111111';
+/** What a signature costs the fee payer, in lamports. */
+export const SIGNATURE_LAMPORTS = 5_000n;
+/** The most a sponsored transaction may cost the sponsor by default: its top-up and its network fee, 0.01 SOL. */
+export const SPONSOR_MAX_LAMPORTS = 10_000_000n;
+
+const lamportsOf = a => (a ? BigInt(a.lamports) : 0n);
+const u64At = (data, at) => new DataView(data.buffer, data.byteOffset).getBigUint64(at, true);
+const u32At = (data, at) => new DataView(data.buffer, data.byteOffset).getUint32(at, true);
+
+/** The top-up: the sponsor's transfer to the player, first in the transaction. */
+export const sponsorTopUp = (sponsor, player, lamports) => transferLamports(sponsor, player, BigInt(lamports));
+
+/** The give-back: what the step didn't need of the top-up, from the player back to the sponsor, last in the transaction. */
+export const sponsorGiveBack = (sponsor, player, lamports) => transferLamports(player, sponsor, BigInt(lamports));
+
+/**
+ * What a step cost in fees and rent, from the accounts it names before and after a dry run (`pre`, `post`: one each
+ * per address, null when there is none): what the project's fee box and the oracle took, and the full rent of each
+ * account it opened that loot, Core or a token program owns. Only what the program's own moves open counts: a token
+ * account counts when its mint is named by one of the step's loot instructions (`lootNamed`), and a Core asset when no
+ * instruction of the step calls Core itself (`programs`: the programs its instructions call), so a player can't open
+ * accounts of their own on the sponsor and close them for the rent. `skip`: the payer and the player.
+ * @param {{ addresses: string[], pre: ({ owner: string, lamports: number | bigint, data?: Uint8Array } | null)[],
+ *   post: ({ owner: string, lamports: number | bigint, data?: Uint8Array } | null)[], project: string, skip?: string[],
+ *   programs?: string[], lootNamed?: string[] }} input
+ * @returns {bigint}
+ */
+export function sponsoredCost({ addresses, pre, post, project, skip = [], programs = [], lootNamed = [] }) {
+  const feeBox = pda.fees(project);
+  const named = new Set(lootNamed);
+  let cost = 0n;
+  for (const [i, address] of addresses.entries()) {
+    if (skip.includes(address)) continue;
+    const before = pre[i];
+    const after = post[i];
+    if (!after) continue;
+    const grew = lamportsOf(after) - lamportsOf(before);
+    if (address === feeBox || after.owner === VRF_PROGRAM) {
+      cost += grew > 0n ? grew : 0n;
+      continue;
+    }
+    if (before) continue;
+    const opened =
+      after.owner === LOOT_PROGRAM ||
+      (after.owner === MPL_CORE_PROGRAM && !programs.includes(MPL_CORE_PROGRAM)) ||
+      ((after.owner === TOKEN_PROGRAM || after.owner === TOKEN_2022_PROGRAM) &&
+        after.data?.length >= 32 &&
+        named.has(encodeBase58(after.data.subarray(0, 32))));
+    if (opened) cost += lamportsOf(after);
+  }
+  return cost;
+}
+
+/** The programs a step's instructions call, and every account its loot instructions name: what `sponsoredCost` reads. */
+export function stepShape(instructions) {
+  return {
+    programs: [...new Set(instructions.map(ix => ix.programId))],
+    lootNamed: [
+      ...new Set(instructions.filter(ix => ix.programId === LOOT_PROGRAM).flatMap(ix => ix.keys.map(k => k.pubkey))),
+    ],
+  };
+}
+
+/**
+ * The top-up a step needs: what it cost the player (`spend`, before any top-up) bounded by its fees and rent
+ * (`cost`), never below 0. A step that leaves the player richer, or costs nothing, needs none.
+ */
+export const topUpFor = ({ spend, cost }) => {
+  const t = spend < cost ? spend : cost;
+  return t > 0n ? t : 0n;
+};
+
+/** The transaction's accounts in order: its static keys, then each lookup table's writable, then read-only ones. */
+async function accountKeys(message, rpc) {
+  const writable = [];
+  const readonly = [];
+  for (const l of message.lookups) {
+    const table = readTable(await rpc.account(l.address));
+    if (!table || table.deactivationSlot !== null) throw new Error(`the lookup table ${l.address} is not active`);
+    const at = i => {
+      if (i >= table.addresses.length) throw new Error(`the lookup table ${l.address} has no address ${i}`);
+      return table.addresses[i];
+    };
+    writable.push(...l.writable.map(at));
+    readonly.push(...l.readonly.map(at));
+  }
+  return [...message.keys, ...writable, ...readonly];
+}
+
+/**
+ * Whether the project's sponsor should sign this transaction (a wire, the player's signature in it): read it, dry-run
+ * it, and hold it to the rules above. Returns { ok: true, player, topUp, cost, lamports, message } (`topUp`: what the
+ * player kept of it, the top-up less the give-back; `lamports`: what it costs the sponsor, that and the network fee)
+ * or { ok: false, reason } in words.
+ * @param {Uint8Array} wire
+ * @param {{ rpc: any, project: string, sponsor: string, maxLamports?: bigint | number, maxPriorityMicroLamports?: bigint | number,
+ *   budget?: ((ask: { player: string, lamports: bigint, topUp: bigint }) => boolean | Promise<boolean>) | null }} options
+ */
+export async function checkSponsored(
+  wire,
+  { rpc, project, sponsor, maxLamports = SPONSOR_MAX_LAMPORTS, maxPriorityMicroLamports = 0n, budget = null },
+) {
+  const no = reason => ({ ok: false, reason });
+  let t;
+  let m;
+  let keys;
+  try {
+    t = readTransaction(wire);
+    m = readMessage(t.message);
+    keys = await accountKeys(m, rpc);
+  } catch (e) {
+    return no(`It is not a transaction this server can read: ${e.message}.`);
+  }
+  if (keys[0] !== sponsor) return no('The sponsor is not its fee payer.');
+  const signers = keys.slice(0, m.header.numRequiredSignatures);
+  if (signers.length < 2) return no('Only the sponsor signs it: a sponsored transaction is a player’s.');
+  let topUp = null;
+  let back = 0n;
+  let ours = false;
+  let units = 200_000n * BigInt(m.instructions.length);
+  let price = 0n;
+  for (const ix of m.instructions) {
+    const program = keys[ix.programIndex];
+    const accounts = ix.accountIndexes.map(i => keys[i]);
+    if (program === sponsor) return no('It calls the sponsor as a program.');
+    const isTransfer = program === SYSTEM_PROGRAM && ix.data.length === 12 && u32At(ix.data, 0) === 2;
+    if (isTransfer && accounts[0] === sponsor && accounts.length === 2) {
+      if (topUp) return no('It tops up more than once.');
+      if (!signers.includes(accounts[1]) || accounts[1] === sponsor)
+        return no('Its top-up goes to someone who doesn’t sign it.');
+      topUp = { to: accounts[1], lamports: u64At(ix.data, 4) };
+      continue;
+    }
+    if (isTransfer && accounts[1] === sponsor && accounts[0] !== sponsor && accounts.length === 2) {
+      back += u64At(ix.data, 4);
+      continue;
+    }
+    if (accounts.includes(sponsor)) return no('The sponsor is named in an instruction other than the top-up.');
+    if (program === COMPUTE_BUDGET_PROGRAM && ix.data[0] === 2 && ix.data.length >= 5)
+      units = BigInt(u32At(ix.data, 1));
+    if (program === COMPUTE_BUDGET_PROGRAM && ix.data[0] === 3 && ix.data.length >= 9) price = u64At(ix.data, 1);
+    if (program === LOOT_PROGRAM && accounts.includes(project)) ours = true;
+  }
+  if (!ours) return no('It does nothing in this project.');
+  if (price > BigInt(maxPriorityMicroLamports)) return no('Its priority fee is more than this sponsor pays.');
+  const fee = SIGNATURE_LAMPORTS * BigInt(signers.length) + (units * price + 999_999n) / 1_000_000n;
+  const player = topUp?.to ?? signers.find(s => s !== sponsor);
+  const lent = topUp?.lamports ?? 0n;
+  if (lent + fee > BigInt(maxLamports))
+    return no(`It would cost the sponsor ${lent + fee} lamports, more than the ${maxLamports} it pays a transaction.`);
+  // What the sponsor is out once the player gives back what the step didn't need.
+  const net = lent > back ? lent - back : 0n;
+  const lamports = net + fee;
+  const addresses = [...new Set(keys)];
+  const at = address => addresses.indexOf(address);
+  let pre;
+  try {
+    pre = await rpc.accounts(addresses);
+  } catch (e) {
+    return no(`Its accounts could not be read: ${e.message}`);
+  }
+  const feeBox = pda.fees(project);
+  const steps = m.instructions.map(ix => ({
+    programId: keys[ix.programIndex],
+    keys: ix.accountIndexes.map(i => ({ pubkey: keys[i] })),
+  }));
+  // The fee box and the oracle are paid by the program's own moves, never straight from an instruction of the page's.
+  for (const ix of steps.filter(x => x.programId === SYSTEM_PROGRAM))
+    if (ix.keys.some(k => k.pubkey === feeBox || pre[at(k.pubkey)]?.owner === VRF_PROGRAM))
+      return no('It pays the fee box or the oracle straight from an instruction of its own.');
+  let post;
+  try {
+    post = (await rpc.simulate(wire, { accounts: addresses })).accounts;
+  } catch (e) {
+    return no(`It would fail: ${e.message}`);
+  }
+  const cost = sponsoredCost({ addresses, pre, post, project, skip: [sponsor, player], ...stepShape(steps) });
+  // A player who keeps none of the top-up (it was all given back) may end richer by what the step itself pays them
+  // (an order's rent, back at its settle): the sponsor paid only the fee.
+  if (net > 0n) {
+    if (lamportsOf(post[at(player)]) > lamportsOf(pre[at(player)]))
+      return no('Its top-up is more than the step costs the player: they would keep some.');
+    if (net > cost) return no('Its top-up is more than the step’s fees and rent: the price is the player’s.');
+  }
+  if (budget && !(await budget({ player, lamports, topUp: net })))
+    return no('This project’s sponsor has paid as much as it pays for now.');
+  return { ok: true, player, topUp: net, cost, lamports, message: t.message };
+}
+
+/**
+ * The project's server side: `sign(wire)` checks a transaction (`checkSponsored`) and, when it passes, returns it with
+ * the sponsor's signature; otherwise it throws the reason (`refused: true`). `sponsor.sign(message)`: the sponsor key's
+ * ed25519 signature of the message bytes, made by the project's server, which alone holds that key.
+ * @param {{ rpc: any, project: string, sponsor: { address: string, sign: (message: Uint8Array) => Uint8Array | Promise<Uint8Array> },
+ *   maxLamports?: bigint | number, maxPriorityMicroLamports?: bigint | number,
+ *   budget?: ((ask: { player: string, lamports: bigint, topUp: bigint }) => boolean | Promise<boolean>) | null }} options
+ */
+export function sponsorSigner({ rpc, project, sponsor, ...limits }) {
+  return {
+    address: sponsor.address,
+    async sign(wire) {
+      const checked = await checkSponsored(wire, { rpc, project, sponsor: sponsor.address, ...limits });
+      if (!checked.ok) throw Object.assign(new Error(checked.reason), { refused: true });
+      return withSignature(wire, sponsor.address, await sponsor.sign(checked.message));
+    },
+  };
+}
+
+/**
+ * The sponsor as an HTTP endpoint (a Next.js route, a Worker): POST { transaction } (base64) answers { transaction }
+ * signed, or 403 { error } in words. `signer`: a `sponsorSigner`.
+ * @param {Request} request
+ * @param {{ address: string, sign: (wire: Uint8Array) => Promise<Uint8Array> }} signer
+ * @returns {Promise<Response>}
+ */
+export async function sponsorHandler(request, signer) {
+  const answer = (body, status = 200) =>
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+  if (request.method !== 'POST') return answer({ error: 'POST a transaction.' }, 405);
+  let wire;
+  try {
+    const body = await request.json();
+    wire = fromBase64(String(body.transaction));
+    if (wire.length > 1232) throw new Error('too long');
+  } catch {
+    return answer({ error: 'Send { "transaction": "<base64>" }.' }, 400);
+  }
+  try {
+    return answer({ transaction: toBase64(await signer.sign(wire)), sponsor: signer.address });
+  } catch (e) {
+    return answer({ error: e.message }, e.refused ? 403 : 500);
+  }
+}
+
+/**
+ * The app's side of a sponsor behind `url` (`sponsorHandler`): what `solanaApp({ sponsor })` takes. `address`: the
+ * sponsor's public key; `maxLamports`: the most it pays a transaction, as its server says.
+ * @param {{ url: string, address: string, maxLamports?: bigint | number, fetchImpl?: typeof fetch }} options
+ */
+export function httpSponsor({ url, address, maxLamports = SPONSOR_MAX_LAMPORTS, fetchImpl = fetch }) {
+  return {
+    address,
+    maxLamports: BigInt(maxLamports),
+    async sign(wire) {
+      const r = await fetchImpl(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ transaction: toBase64(wire) }),
+      });
+      const body = await r.json().catch(() => ({}));
+      if (!r.ok || !body.transaction)
+        throw Object.assign(new Error(body.error ?? `The sponsor answered ${r.status}.`), {
+          refused: r.status === 403,
+        });
+      return fromBase64(body.transaction);
+    },
+  };
+}

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,8 +1,8 @@
 {
   "name": "@xgamesfun/solana",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "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.",
+  "description": "Loot boxes, gacha, shops, lotteries, auctions, NFT staking, crafting and rewards on Solana without writing a smart contract: one shared program, its JS client, a CLI, and an MCP server and skill so Claude Code, Codex or any AI agent can design, check, simulate and launch an economy.",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -15,13 +15,32 @@
   },
   "keywords": [
     "solana",
-    "economy",
-    "loot-box",
-    "staking",
+    "solana-program",
+    "web3",
     "nft",
-    "game",
+    "nft-staking",
+    "staking",
+    "loot-box",
+    "gacha",
+    "lottery",
+    "raffle",
+    "auction",
+    "crafting",
+    "game-economy",
+    "web3-gaming",
+    "gamefi",
+    "token",
+    "spl-token",
+    "metaplex-core",
+    "no-smart-contract",
+    "vrf",
     "mcp",
-    "agent"
+    "mcp-server",
+    "model-context-protocol",
+    "claude-code",
+    "codex",
+    "ai-agent",
+    "agent-skill"
   ],
   "engines": {
     "node": ">=22"
@@ -43,13 +62,21 @@
       "types": "./types/play/index.d.ts",
       "default": "./js/play/index.js"
     },
+    "./sponsor": {
+      "types": "./types/play/sponsor.d.ts",
+      "default": "./js/play/sponsor.js"
+    },
     "./results": {
       "types": "./types/results/index.d.ts",
       "default": "./js/results/index.js"
     },
     "./idl.json": "./js/client/idl/loot.json",
     "./package.json": "./package.json",
-    "./release.json": "./release.json"
+    "./release.json": "./release.json",
+    "./mcp/http": {
+      "types": "./types/mcp/http.d.mts",
+      "default": "./js/mcp/http.mjs"
+    }
   },
   "sideEffects": [
     "./bin/xsolana.mjs",

package/release.json

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

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.2 <guide|examples|check|simulate|cost|explain|review|publish|status> [xsolana.json]`,
+or `npx -y @xgamesfun/solana@0.25.2 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.2 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
 
@@ -114,6 +129,9 @@ is due, list what a player owns). Pages call `claims()` when they open and show
 `references/apps.md` shows a whole page; `xsolana_client` gives the program and the calls. Never invent account layouts,
 instruction data or addresses, and never put a key or the authority's actions in a page players load.
 For staking an NFT of another collection, show what custody means and get explicit acceptance before sending.
+Players with no SOL can still play when the project sponsors their fees: a key on the project's own server pays them,
+never the price (`references/apps.md`, "Sponsoring players' fees"). Offer it when the person wants free first steps or
+players new to Solana.
 
 ## More
 
@@ -121,3 +139,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/apps.md

@@ -198,6 +198,34 @@ assetId, tree }` after a `loot.proveLeafIx` in the same transaction. `app.stakeN
   `collectibles()`), one read at a time, and keep what is on screen when one read fails.
 - **Errors** come back as plain sentences (a sold-out item, a gate not met, a price above the most they agreed to):
   show them.
+- **Sponsoring players' fees** (players with no SOL, a free item or box as a first step): the project runs a sponsor,
+  a plain key on its own server with no role in the program, funded with SOL. The page passes
+  `solanaApp({ ..., sponsor: httpSponsor({ url: '/sponsor', address: SPONSOR_ADDRESS }) })`; each step then has the
+  sponsor pay the network fee and lend the player SOL for the step, the player giving back, in the same transaction,
+  all but what it costs in fees and rent (the player fee, the oracle's fee for a roll, the rent of what the program
+  opens or mints). The price is never sponsored: a priced step still takes the player's own SOL or tokens. The server
+  route is a few lines:
+
+  ```js
+  import { sponsorHandler, sponsorSigner } from '@xgamesfun/solana/sponsor';
+  const signer = sponsorSigner({
+    rpc, // the client's rpcClient, or any with accounts and simulate
+    project: spec.live.project,
+    sponsor: { address: SPONSOR_ADDRESS, sign: message => signWithServerKey(message) }, // the server's own ed25519 key
+    maxLamports: 10_000_000n, // the most one transaction costs it (0.01 SOL)
+    budget: ({ player, lamports }) => underTodaysCap(player, lamports), // the project's own per-player, per-day limit
+  });
+  export const POST = request => sponsorHandler(request, signer);
+  ```
+
+  The server reads and dry-runs every transaction before it signs (`checkSponsored`): the sponsor may only pay the fee
+  and the one loan, the transaction must be this project's, and the player may keep no more than the step's fees and
+  rent. What a sponsor can still lose is rent the program later gives back to the player (an order's, at its settle)
+  and fees for transactions that fail on chain, so always give it a `budget`, keep only a few days' worth of SOL in
+  it, and never make it the owner or the authority. Sponsored, a box's roll takes two prompts (the open, then the
+  settle) instead of one, and a step too big for one transaction goes as the player's own. Tell the person what a
+  day of their players costs the sponsor (`xsolana_cost`: the player fee, the oracle's fee and rent per step).
+
 - **Never in a page**: a private key, a keyed RPC link, or anything the authority signs (payouts, minting, rewriting
   a collectible). Those are the owner's or the authority's to sign in their own wallet, or on a server they run.
 - **Lower level**: `@xgamesfun/solana/client` has one builder per instruction and the account decoders, for what the

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