@xgamesfun/solana 0.20.1 → 0.25.0

package/js/results/server.js

@@ -0,0 +1,230 @@
+// What a game's server checks before it pays or grants anything: which of the game's collectibles a wallet holds,
+// that a wallet's owner signed a proof (a sign-in, a link to a player), and promo codes with keys nobody can guess.
+// Browser-safe (Web Crypto and fetch only), so a Cloudflare Worker, a Node server or a page can use it alike; the
+// page's own answers are never trusted for what a server pays.
+//
+//   const mine = await collectiblesOf({ rpc: RPC_URL, spec, wallet })       // [{ asset, item, name, attributes, … }]
+//   if (await holds({ rpc: RPC_URL, spec, wallet, item: 'pass' })) …        // a perk for holders
+//
+//   const ask = proofRequest({ game, wallet, purpose: 'link to player 42' }) // the server keeps ask.nonce until ask.expires
+//   … the page has the wallet sign ask.text (signMessage) and sends back the signature …
+//   const proof = await verifyProof({ text: ask.text, signature, wallet, game, purpose: 'link to player 42' })
+//
+//   const codes = makeCodes(50)                                 // print these on flyers; keep them out of the repository
+//   spec.grants[i].keys = await codeAddresses(codes)            // only public keys go in the spec
+//   const voucher = await codeVoucher({ code, game, grant: 3, incarnation, wallet, now })  // the player typed `code`
+import { decodeBase58, encodeBase58, isAddress } from '../chain/base58.js';
+import { toHex, utf8 } from '../chain/bytes.js';
+import { MPL_CORE_PROGRAM, ownedAssetFilters, parseCoreAsset } from '../chain/core.js';
+import { rpcClient } from '../chain/rpc.js';
+import { sha256 } from '../chain/sha256.js';
+import { signVoucher } from './index.js';
+
+const subtle = () => globalThis.crypto.subtle;
+const rpcOf = rpc => (typeof rpc === 'string' ? rpcClient(rpc) : rpc);
+
+// ---------------------------------------------------------------- what a wallet holds
+
+/**
+ * The game's collectibles `wallet` holds now, read from the chain (Metaplex Core assets of the live spec's collection
+ * and of the collections it names): [{ asset, item (its key in the spec, or null), itemId, name, uri, attributes,
+ * frozen }]. `rpc`: an RPC link or a `rpcClient`. Token Metadata and compressed NFTs are not read here.
+ */
+export async function collectiblesOf({ rpc, spec, wallet }) {
+  if (!isAddress(wallet)) throw new Error('Name the wallet (its public address).');
+  const collections = [spec?.live?.collection, ...(spec?.collections ?? [])].filter(Boolean);
+  if (!collections.length)
+    throw new Error('The spec names no collection: put it live first (its live section names the collection).');
+  const keyOf = new Map((spec.items ?? []).filter(it => Number.isInteger(it.id)).map(it => [it.id, it.key]));
+  const client = rpcOf(rpc);
+  const found = (
+    await Promise.all(collections.map(c => client.programAccounts(MPL_CORE_PROGRAM, ownedAssetFilters(wallet, c))))
+  ).flat();
+  return found.map(({ pubkey, account }) => {
+    const a = parseCoreAsset(account.data);
+    const itemId = a.attributes?.item_id !== undefined ? Number(a.attributes.item_id) : null;
+    return { asset: pubkey, ...a, itemId, item: itemId === null ? null : (keyOf.get(itemId) ?? null) };
+  });
+}
+
+/**
+ * Whether `wallet` holds at least `atLeast` of the game's collectible `item` (its key in the spec), or of any of the
+ * game's collectibles when `item` is left out. With `attribute`, only those whose number under it is at least
+ * `minimum` count (a level, a rarity). → the count it holds when that is enough, else 0.
+ */
+export async function holds({ rpc, spec, wallet, item = null, atLeast = 1, attribute = null, minimum = 0 }) {
+  const mine = (await collectiblesOf({ rpc, spec, wallet })).filter(
+    c =>
+      (item === null || c.item === item) && (attribute === null || Number(c.attributes?.[attribute] ?? 0) >= minimum),
+  );
+  return mine.length >= atLeast ? mine.length : 0;
+}
+
+// ---------------------------------------------------------------- a wallet's signed proof
+
+const PROOF_TITLE = 'loot wallet proof';
+const PROOF_FIELDS = ['cluster', 'game', 'wallet', 'purpose', 'nonce', 'expires'];
+const oneLine = (name, value) => {
+  if (/[\r\n]/.test(String(value))) throw new RangeError(`A proof's ${name} is one line.`);
+  return String(value);
+};
+
+/** The exact text a wallet signs to prove it is its owner's: fixed lines, so nothing else can be passed off as it. */
+export const proofText = ({ cluster = 'devnet', game, wallet, purpose, nonce, expires }) =>
+  [
+    PROOF_TITLE,
+    ...PROOF_FIELDS.map(f => `${f}: ${oneLine(f, { cluster, game, wallet, purpose, nonce, expires }[f])}`),
+    '',
+    'Signing this moves nothing.',
+  ].join('\n');
+
+/**
+ * A proof to ask of `wallet`, made by the server: { text, nonce, expires }. The server keeps `nonce` until `expires`
+ * (unix seconds, `seconds` from now) and takes each nonce once, so a signed proof can't be replayed.
+ */
+export function proofRequest({
+  cluster = 'devnet',
+  game,
+  wallet,
+  purpose = 'sign in',
+  seconds = 300,
+  now = Math.floor(Date.now() / 1000),
+}) {
+  if (!isAddress(wallet)) throw new Error('Name the wallet (its public address).');
+  const nonce = toHex(globalThis.crypto.getRandomValues(new Uint8Array(16)));
+  const expires = Math.floor(now) + Math.floor(seconds);
+  return { text: proofText({ cluster, game, wallet, purpose, nonce, expires }), nonce, expires };
+}
+
+/** A proof text's fields, or null when it is not one. */
+export function readProof(text) {
+  const lines = String(text).split('\n');
+  if (
+    lines[0] !== PROOF_TITLE ||
+    lines.length !== PROOF_FIELDS.length + 3 ||
+    lines.at(-1) !== 'Signing this moves nothing.'
+  )
+    return null;
+  const out = {};
+  for (const [i, f] of PROOF_FIELDS.entries()) {
+    const prefix = `${f}: `;
+    if (!lines[i + 1].startsWith(prefix)) return null;
+    out[f] = lines[i + 1].slice(prefix.length);
+  }
+  out.expires = Number(out.expires);
+  return out;
+}
+
+/**
+ * Checks a wallet's signed proof: the text is a proof for this `game` (and `purpose`, when given), for `wallet`, not
+ * expired at `now`, and `signature` (base58, or 64 bytes) is that wallet's Ed25519 signature of it. → the proof's
+ * fields ({ wallet, nonce, expires, … }), or throws in words. Taking each nonce once is the caller's: check
+ * `fields.nonce` against the ones the server handed out and not yet used.
+ */
+export async function verifyProof({
+  text,
+  signature,
+  wallet,
+  game,
+  purpose = null,
+  cluster = 'devnet',
+  now = Math.floor(Date.now() / 1000),
+}) {
+  const fields = readProof(text);
+  if (!fields) throw new Error('That is not a wallet proof.');
+  if (fields.cluster !== cluster) throw new Error(`The proof is for ${fields.cluster}, not ${cluster}.`);
+  if (game !== undefined && fields.game !== String(game)) throw new Error('The proof is for another game.');
+  if (wallet !== undefined && fields.wallet !== wallet) throw new Error('The proof names another wallet.');
+  if (purpose !== null && fields.purpose !== purpose) throw new Error('The proof is for something else.');
+  if (!(fields.expires > now)) throw new Error('The proof has expired: ask for a new one.');
+  const sig = typeof signature === 'string' ? decodeBase58(signature) : Uint8Array.from(signature ?? []);
+  if (sig.length !== 64) throw new Error('A signature is 64 bytes.');
+  const key = await subtle().importKey('raw', decodeBase58(fields.wallet), { name: 'Ed25519' }, false, ['verify']);
+  if (!(await subtle().verify({ name: 'Ed25519' }, key, sig, utf8(text))))
+    throw new Error("The signature is not that wallet's.");
+  return fields;
+}
+
+// ---------------------------------------------------------------- promo codes
+
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const CODE_DOMAIN = 'loot-promo-code-v1';
+
+/**
+ * `n` fresh promo codes, each `bits` of randomness (80 by default, 16 characters of Crockford base32, in groups of 4).
+ * A code's key is in the spec for anyone to read, so a short code can be found by trying them all offline: fewer than
+ * 64 bits is refused.
+ */
+export function makeCodes(n, { bits = 80, group = 4 } = {}) {
+  if (!(bits >= 64))
+    throw new RangeError(
+      'A promo code needs at least 64 bits (80 by default): its key is public, so a short code can be guessed offline.',
+    );
+  const chars = Math.ceil(bits / 5);
+  return Array.from({ length: n }, () => {
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(chars));
+    const text = Array.from(bytes, b => CROCKFORD[b & 31]).join('');
+    return group ? text.match(new RegExp(`.{1,${group}}`, 'g')).join('-') : text;
+  });
+}
+
+/** A code as typed, read the forgiving way (Crockford): case, spaces and dashes don't matter, O reads 0, I and L read 1. */
+export const normalizeCode = code =>
+  String(code).toUpperCase().replace(/[\s-]/g, '').replace(/O/g, '0').replace(/[IL]/g, '1');
+
+/** The key a code stands for: { address, sign } (Ed25519, its seed sha256 of the domain and the code). */
+export async function codeKey(code, { domain = CODE_DOMAIN } = {}) {
+  const normalized = normalizeCode(code);
+  if (!normalized || [...normalized].some(c => !CROCKFORD.includes(c))) throw new Error('That is not a code.');
+  const seed = sha256(utf8(`${domain}\n${normalized}`));
+  const pkcs8 = new Uint8Array([
+    0x30,
+    0x2e,
+    0x02,
+    0x01,
+    0x00,
+    0x30,
+    0x05,
+    0x06,
+    0x03,
+    0x2b,
+    0x65,
+    0x70,
+    0x04,
+    0x22,
+    0x04,
+    0x20,
+    ...seed,
+  ]);
+  const privateKey = await subtle().importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']);
+  const jwk = await subtle().exportKey('jwk', privateKey);
+  const raw = Uint8Array.from(atob(jwk.x.replace(/-/g, '+').replace(/_/g, '/')), ch => ch.charCodeAt(0));
+  return {
+    address: encodeBase58(raw),
+    sign: async message => new Uint8Array(await subtle().sign({ name: 'Ed25519' }, privateKey, message)),
+  };
+}
+
+/** The public keys for a grant's `keys`, one per code, in order. */
+export const codeAddresses = async (codes, options) =>
+  Promise.all(codes.map(async c => (await codeKey(c, options)).address));
+
+/**
+ * A voucher a typed code signs for `wallet` (the page, or a server, makes it): the grant pays it once per code with
+ * `limits.perKey: 1`. Its round is the code's own, so one wallet can't use one code twice either. `incarnation` is the
+ * grant's, read from the chain; `now` the cluster's clock.
+ */
+export async function codeVoucher({
+  code,
+  game,
+  grant,
+  incarnation,
+  wallet,
+  now,
+  seconds = 86_400,
+  domain = CODE_DOMAIN,
+}) {
+  const key = await codeKey(code, { domain });
+  const round = toHex(sha256(utf8(`${domain}\nround\n${key.address}`))).slice(0, 32);
+  return signVoucher({ signer: key, game, grant, incarnation, wallet, round, now, seconds });
+}

package/js/results/wire.js

@@ -11,7 +11,10 @@ export const CLUSTERS = Object.freeze({ devnet: 0, mainnet: 1 });
 export const CERT_KINDS = Object.freeze({
   host: { title: 'loot host key', fields: ['cluster', 'game', 'host', 'until'] },
   revoke: { title: 'loot revoke host key', fields: ['cluster', 'game', 'host'] },
-  draw: { title: 'loot draw', fields: ['cluster', 'game', 'draw', 'engine', 'winners', 'prizes', 'payout', 'identity', 'slug', 'rates'] },
+  draw: {
+    title: 'loot draw',
+    fields: ['cluster', 'game', 'draw', 'engine', 'winners', 'prizes', 'payout', 'identity', 'slug', 'rates'],
+  },
   lock: { title: 'loot draw lock', fields: ['cluster', 'game', 'draw', 'roster', 'players', 'beacon'] },
   entry: { title: 'loot entry', fields: ['cluster', 'game', 'draw'] },
   giveaway: { title: 'loot giveaway host', fields: ['cluster', 'game', 'who', 'slug', 'grant', 'until'] },
@@ -20,13 +23,16 @@ export const CERT_KINDS = Object.freeze({
 
 /** One field's value, on its own line: a value with a line break in it (which would read as another field) is refused. */
 const field = (name, value) => {
-  if (/[\r\n]/.test(String(value))) throw new RangeError(`A certificate's ${name} is one line: ${JSON.stringify(String(value))} has a line break.`);
+  if (/[\r\n]/.test(String(value)))
+    throw new RangeError(`A certificate's ${name} is one line: ${JSON.stringify(String(value))} has a line break.`);
   return value;
 };
-const write = (kind, values) => [CERT_KINDS[kind].title, ...CERT_KINDS[kind].fields.map((f) => `${f}: ${field(f, values[f])}`)].join('\n');
+const write = (kind, values) =>
+  [CERT_KINDS[kind].title, ...CERT_KINDS[kind].fields.map(f => `${f}: ${field(f, values[f])}`)].join('\n');
 
 /** The text the owner signs to let `host` report `game`'s results until `until` (unix seconds). */
-export const hostCertText = ({ cluster = 'devnet', game, host, until }) => write('host', { cluster, game, host, until });
+export const hostCertText = ({ cluster = 'devnet', game, host, until }) =>
+  write('host', { cluster, game, host, until });
 /** The text the owner signs to take `host` back. */
 export const revokeText = ({ cluster = 'devnet', game, host }) => write('revoke', { cluster, game, host });
 
@@ -38,10 +44,33 @@ export const revokeText = ({ cluster = 'devnet', game, host }) => write('revoke'
  * `slug`: the game's play-host name (its tokens' audience), or '-'; `rates`: the sha256 of the engine's rates (canonical
  * JSON), or 'default'.
  */
-export const drawText = ({ cluster = 'devnet', game, draw, engine, winners, prizes = [], payout = 'vouchers', identity = 'linked', slug = '-', rates = 'default' }) =>
-  write('draw', { cluster, game, draw, engine, winners, prizes: prizes.length ? prizes.map((p) => `${p.place}:${p.grant}`).join(' ') : 'none', payout, identity, slug, rates });
+export const drawText = ({
+  cluster = 'devnet',
+  game,
+  draw,
+  engine,
+  winners,
+  prizes = [],
+  payout = 'vouchers',
+  identity = 'linked',
+  slug = '-',
+  rates = 'default',
+}) =>
+  write('draw', {
+    cluster,
+    game,
+    draw,
+    engine,
+    winners,
+    prizes: prizes.length ? prizes.map(p => `${p.place}:${p.grant}`).join(' ') : 'none',
+    payout,
+    identity,
+    slug,
+    rates,
+  });
 /** The text the organizer signs to lock a draw's players (`roster`: rosterHash) to a beacon round still to come. */
-export const lockText = ({ cluster = 'devnet', game, draw, roster, players, beacon, net = 'quicknet' }) => write('lock', { cluster, game, draw, roster, players, beacon: `${net} ${beacon}` });
+export const lockText = ({ cluster = 'devnet', game, draw, roster, players, beacon, net = 'quicknet' }) =>
+  write('lock', { cluster, game, draw, roster, players, beacon: `${net} ${beacon}` });
 /** The text a player's wallet signs to enter a draw (identity 'wallet'). */
 export const entryText = ({ cluster = 'devnet', game, draw }) => write('entry', { cluster, game, draw });
 
@@ -49,20 +78,31 @@ export const entryText = ({ cluster = 'devnet', game, draw }) => write('entry',
  * The text the owner (or authority) signs to appoint a giveaway host: `who` is "x:<X account id>" (the host signs in
  * with that X account through the play host) or a wallet address; their giveaways pay from grant `grant` alone.
  */
-export const giveawayHostText = ({ cluster = 'devnet', game, who, slug, grant, until }) => write('giveaway', { cluster, game, who, slug, grant, until });
+export const giveawayHostText = ({ cluster = 'devnet', game, who, slug, grant, until }) =>
+  write('giveaway', { cluster, game, who, slug, grant, until });
 /** The text the owner (or authority) signs to take a giveaway host back. */
-export const revokeGiveawayText = ({ cluster = 'devnet', game, who }) => write('revokeGiveaway', { cluster, game, who });
+export const revokeGiveawayText = ({ cluster = 'devnet', game, who }) =>
+  write('revokeGiveaway', { cluster, game, who });
 
 /** A draw's players, as one hash: each `id<TAB>wallet`, sorted by id, one a line; sha256, hex. */
 export async function rosterHash(entries) {
-  const text = [...entries].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).map((e) => `${e.id}\t${e.wallet}`).join('\n');
-  return Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', utf8(text))), (b) => b.toString(16).padStart(2, '0')).join('');
+  const text = [...entries]
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .map(e => `${e.id}\t${e.wallet}`)
+    .join('\n');
+  return Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', utf8(text))), b =>
+    b.toString(16).padStart(2, '0'),
+  ).join('');
 }
 
 /** JSON with every object's keys sorted: one text for one value, so its hash means one thing. */
 export function canonicalJson(value) {
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
-  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+  if (value && typeof value === 'object')
+    return `{${Object.keys(value)
+      .sort()
+      .map(k => `${JSON.stringify(k)}:${canonicalJson(value[k])}`)
+      .join(',')}}`;
   return JSON.stringify(value);
 }
 
@@ -74,9 +114,17 @@ export function canonicalJson(value) {
  * place past 255 and more than 255 winners are refused, never written as something else.
  */
 export function resultBytes({ cluster = 'devnet', game, round, endedAt, winners }) {
-  if (!Object.hasOwn(CLUSTERS, cluster)) throw new RangeError(`Unknown cluster ${JSON.stringify(cluster)}: a result names ${Object.keys(CLUSTERS).join(' or ')}.`);
-  const roundAt = typeof round === 'string' && /^[0-9a-f]{32}$/i.test(round) ? fromHex(round) : round instanceof Uint8Array && round.length === 16 ? round : null;
-  if (!roundAt) throw new RangeError('A result\'s round is 16 bytes (32 hex characters).');
+  if (!Object.hasOwn(CLUSTERS, cluster))
+    throw new RangeError(
+      `Unknown cluster ${JSON.stringify(cluster)}: a result names ${Object.keys(CLUSTERS).join(' or ')}.`,
+    );
+  const roundAt =
+    typeof round === 'string' && /^[0-9a-f]{32}$/i.test(round)
+      ? fromHex(round)
+      : round instanceof Uint8Array && round.length === 16
+        ? round
+        : null;
+  if (!roundAt) throw new RangeError("A result's round is 16 bytes (32 hex characters).");
   if (!Array.isArray(winners) || winners.length > 255) throw new RangeError('A result names at most 255 winners.');
   return concat(
     utf8(RESULT_DOMAIN),
@@ -85,6 +133,6 @@ export function resultBytes({ cluster = 'devnet', game, round, endedAt, winners
     roundAt,
     uintLE(BigInt(endedAt), 8),
     Uint8Array.of(winners.length),
-    ...winners.map((w) => concat(addressBytes(w.wallet), uintLE(w.place, 1), uintLE(w.grant ?? NO_GRANT, 2))),
+    ...winners.map(w => concat(addressBytes(w.wallet), uintLE(w.place, 1), uintLE(w.grant ?? NO_GRANT, 2))),
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgamesfun/solana",
-  "version": "0.20.1",
+  "version": "0.25.0",
   "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",
@@ -71,10 +71,11 @@
   ],
   "scripts": {
     "test": "node --test \"js/test/**/*.test.mjs\"",
-    "lint": "eslint .",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
     "types": "tsc -p tsconfig.types.json",
     "fixtures": "node scripts/fetch-fixtures.mjs",
-    "check": "node scripts/fetch-fixtures.mjs --check && node scripts/sync-skills.mjs --check && node scripts/release-manifest.mjs --check && eslint . && npm test",
+    "check": "node scripts/fetch-fixtures.mjs --check && node scripts/sync-skills.mjs --check && node scripts/release-manifest.mjs --check && npm run lint && npm test",
     "check:idl": "node scripts/sync-idl.mjs --check",
     "sync-idl": "node scripts/sync-idl.mjs",
     "sync-skills": "node scripts/sync-skills.mjs",
@@ -85,10 +86,11 @@
     "@eslint/js": "10.0.1",
     "@modelcontextprotocol/sdk": "1.32.2",
     "ajv": "8.20.0",
-    "eslint": "10.13.0",
+    "eslint": "10.14.0",
     "globals": "17.13.0",
     "litesvm": "1.6.1",
     "playwright-core": "1.64.1",
+    "prettier": "3.9.10",
     "typescript": "7.0.2"
   },
   "bin": {

package/release.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.20.1",
+  "version": "0.25.0",
   "programId": "9cwqM1TXytPnFZsLfmUyv2dg4uW6Ch9C6UJVPns7NFQ",
-  "sbfBytes": 1457936,
-  "sbfSha256": "358805a85fd32ba7b5b6bee9dd88e063bda6f854820d978265bca6683790aee7",
-  "idlSha256": "0f75fb422c2e8eca80cfd4fd5ccc1cd8805df9cc12e981bfd0297810c772aca2",
-  "clientSha256": "91537742722a9b31da8afd1f1a2af1bfeea389ad74981e740a41917f81ebecce"
+  "sbfBytes": 1741840,
+  "sbfSha256": "ea19d15d03211f7bd0b25179d51f75544342225127fcb631e687eae6750c9ba7",
+  "idlSha256": "41e621990c17b8645f59bb2a170271645ad370d1c1bf9f1dbdd04f817b82d4cf",
+  "clientSha256": "11270da0bd539b1cb79e8c61527e4b0686f2d03a2e2b617c823dcabf97f05f6e"
 }

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.20.1 <guide|examples|check|simulate|cost|explain|publish|status> [xsolana.json]`,
-or `npx -y @xgamesfun/solana@0.20.1 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.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).
 
 ## Rules (always)
 
@@ -25,15 +25,18 @@ or `npx -y @xgamesfun/solana@0.20.1 tool <name> '<json>'` for any tool (always w
 5. **Numbers come from the tools.** What a box gives back, how long a pool lasts, what going live costs: quote
    `xsolana_simulate`, `xsolana_cost` and `xsolana_explain`, never your own arithmetic. What a player pays is the tools'
    "in all" number for that action (price, fee, oracle, network and rent that never comes back): quote it as is.
-6. **Flag the law.** When the checker raises `W-CHANCE-PRIZE` (paid chance at money: boxes with prizes, lotteries,
-   contests), `W-CHANCE-ITEMS` (paid random collectibles a player can resell: loot boxes, gacha) or `W-REVENUE-SHARE` (stakers paid from sales), tell the person in plain words, every time, and never
-   call anything an investment, a return or passive income. For an auction, always say `W-AUCTION-SHILL`: anyone,
-   the seller included, can bid to push the price up. Before they go live, say as well that the program is not
-   independently audited and comes as is, with no warranty: they use it at their own risk, and making sure the
-   economy is legal where it is offered is theirs. Never promise it is safe, and never give legal advice.
+6. **Flag the law once.** The first time the checker raises `W-CHANCE-PRIZE` (paid chance at money: boxes with
+   prizes, lotteries, contests), `W-CHANCE-ITEMS` (paid random collectibles a player can resell: loot boxes, gacha) or
+   `W-REVENUE-SHARE` (stakers paid from sales), say it in one plain sentence. Don't repeat it in later answers, or add
+   legal notes to pages and apps you build, unless the person asks or a flag of a new kind appears. When they ask about
+   the law, answer what you know and leave the rest to their lawyer: you are not one. Never call anything an
+   investment, a return or passive income, and never promise it is safe. The approval page shows the flags and that
+   the program is not independently audited and comes as is, and asks the owner to tick that they read them, so going
+   live needs nothing more from you. For an auction, say once how bidding works (`W-AUCTION-SHILL`): anyone, the
+   seller included, can bid to push the price up.
 7. **Take addresses from the tools, never from memory**: the program, its accounts, the IDL. Every answer names them.
 8. **Public data only in a spec**: names, prices, percents, public addresses. Leave out `id`, `index`, `shopBox`,
-   `rewardsIndex` and `live`: they are written when it goes live.
+   and `live`: they are written when it goes live.
 9. **Compose before you say no.** Most ideas are several parts working together, not one part. Before calling
    anything a limit, break the idea into its pieces (what players pay, what they get, what is random, what the chain
    can't see, what is held and for how long, who is paid) and find the part for each (`references/sentence-to-spec.md`).
@@ -49,13 +52,19 @@ or `npx -y @xgamesfun/solana@0.20.1 tool <name> '<json>'` for any tool (always w
      second step). Don't withdraw a draft that checks, and don't send them elsewhere while a version on loot is on the
      table.
 
-10. **People finish what follows; build the button, not a server.** Every step after a player's ask (settle a roll,
-   draw a lottery, complete its tickets and pay its places, refund a draw the oracle never answered, claim a win, end
-   an auction, take unbonded tokens out, run a sealed schedule, take a rental's NFT home) can be sent by anyone, and
-   the person who gains from it sends it from the page (`app.claims()` lists them, `app.claim(c)` sends one). A
-   grant's claim is the winner's alone: the winning wallet signs it, whatever proves it won; anyone may pay its fees,
-   nobody claims for a player. loot needs no server to finish anything. Never make a key in a page or a server for
-   the owner to fund: whoever signs pays.
+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.
+
+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
+    win, end an auction, run a sealed schedule, take a rental's NFT home) can be sent by the person who
+    gains from it, from the page (`app.claims()` lists them, `app.claim(c)` sends one). A
+    grant's claim is the winner's alone: the winning wallet signs it, whatever proves it won; anyone may pay its fees,
+    nobody claims for a player. loot needs no server to finish anything. Never make a key in a page or a server for
+    the owner to fund: whoever signs pays.
 
 ## The loop
 
@@ -74,13 +83,22 @@ or `npx -y @xgamesfun/solana@0.20.1 tool <name> '<json>'` for any tool (always w
    sends each step while it runs (a draw, a payout, a contest's result) and what happens if nobody does:
    `references/after-launch.md`.
    Prizes: give a known prize directly on whatever route wins it (a grant, a lottery place, a contest, a mission, a
-   recipe): one step, no oracle. Use a roll of a box only for chance. Every other shape (bundles, an NFT as the price,
-   stashes, gates, no-loss lotteries, amounts by rank) is in `references/sentence-to-spec.md` and `xsolana_guide`.
+   recipe): one step, no oracle. Use a roll of a box only for chance. A pack of cards is one box with `slots` (five
+   draws an open, a guaranteed rare), opened several at once from the page; cards whose traits differ are a fresh
+   item drawing from `tables`. Every other shape (bundles, an NFT as the price, stashes, gates, no-loss lotteries,
+   amounts by rank) is in `references/sentence-to-spec.md` and `xsolana_guide`.
+   A lottery always names where its places are paid from, and there is no default: ask the person if their words
+   don't say. `"pot": 0` keeps a pot from round to round: a seed, sponsors, shares of other sales and what earlier
+   rounds left all count, and the next round starts with what the round before left (a jackpot that grows, a no-loss
+   lottery). `"rest": "<destination>"` pays each round from its own ticket money alone, which nothing from outside can
+   change, and sends what the places leave there (`"treasury"`, a wallet, `"burn"`; never a pool or `"chosen"`).
+   Then say what stays the project's job (`references/telling-the-person.md`): the files behind every item's link
+   (every value of a fresh item's `{attribute}`), a table's rent, and the collectible rent a pack's settle pays.
 6. **Iterate on what they say.** "Make legendaries 0.5%", "a bigger seed": change, check, simulate, explain again.
 7. **Save it**: `xsolana_save {"spec": …}` writes `xsolana.json`, only if it checks. A live file keeps its program numbers.
 8. **When they say "put it live"**: `xsolana_publish` lists every step and its cost and gives the command. Tell them to
    run it themselves in the project folder, exactly as `xsolana_publish` gives it (it names the exact version:
-   `npx -y @xgamesfun/solana@0.20.1 approve xsolana.json`; never drop the version). It opens a page on their computer where
+   `npx -y @xgamesfun/solana@0.25.0 approve xsolana.json`; never drop the version). It opens a page on their computer where
    they connect a devnet wallet and approve; what lands is written back into `xsolana.json`. You publish nothing.
 9. **After it is live**: `xsolana_status` shows each part on chain; read it before acting on what the person says
    happened. A later change is the same loop: save, publish, and the approval sends only what changed. What only the
@@ -90,7 +108,7 @@ or `npx -y @xgamesfun/solana@0.20.1 tool <name> '<json>'` for any tool (always w
 ## Building the app around it
 
 A game, a site or a bot calls the live economy with the player's own wallet, through the package's player module
-(`@xgamesfun/solana/play`: buy, open a box and collect the roll, pay, stake, compound and withdraw, craft, bid and end an
+(`@xgamesfun/solana/play`: buy, open a box and collect the roll, pay, stake, compound and unstake, craft, bid and end an
 auction, list an NFT for sale or for rent and read who rents it, raffle an NFT, claim what a player is owed, run what
 is due, list what a player owns). Pages call `claims()` when they open and show each as a button.
 `references/apps.md` shows a whole page; `xsolana_client` gives the program and the calls. Never invent account layouts,
@@ -100,6 +118,6 @@ For staking an NFT of another collection, show what custody means and get explic
 ## More
 
 - From a sentence to a spec, with a worked example: `references/sentence-to-spec.md`
-- Telling the person what they get: `references/telling-the-person.md`
+- Telling the person what they get, and what stays the project's job: `references/telling-the-person.md`
 - Building the app for a live economy: `references/apps.md`
 - After it goes live (who sends each step, owner pages, results from a game, a results server): `references/after-launch.md`