@xgamesfun/solana 0.0.0-stage → 0.20.1

package/js/results/index.js

@@ -0,0 +1,184 @@
+// `@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
+// 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.
+//
+// A host server (the project's own):
+//   const key = await newKey()                     // once; keep key.secret in the server's secret store
+//   hostCertText({ game, host: key.address, until })   → the owner signs it in their wallet, once
+//   await report({ server, cert, signer: key, game, round: newRound(), endedAt, winners: [{ wallet, place, grant }] })
+//
+// A host server that pays its winners itself, with no server of ours in the way (the owner names the host key among
+// the grant's voucher keys; the program checks every voucher):
+//   const voucher = await signVoucher({ signer: key, game, grant: 1, incarnation, wallet, round, now: clusterNow })
+//   the winner's page: app.claimGrant('prize', { voucher })
+//
+// A giveaway host (a player the owner appointed, signed in with the play host; their page):
+//   const session = await newKey()
+//   await giveaways.open({ server, game, cert: appointment, token, giveaway: newRound(), winners: 3, endsBy, session })
+//   … the game is played …
+//   await giveaways.report({ server, game, giveaway, session, endedAt, winners: [{ wallet, place }], grant })
+import { decodeBase58, encodeBase58 } from '../chain/base58.js';
+import { toHex } from '../chain/bytes.js';
+import { pda, voucherBytes } from '../client/index.js';
+import { canonicalJson, drawText, entryText, lockText, resultBytes, rosterHash } from './wire.js';
+
+export { canonicalJson, CERT_KINDS, CLUSTERS, drawText, entryText, giveawayHostText, hostCertText, lockText, NO_GRANT, RESULT_DOMAIN, resultBytes, revokeGiveawayText, revokeText, rosterHash } from './wire.js';
+
+/** games.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;
+/** A value as a query's value: encoded, so a `&`, `#` or `/` in it is part of the value. */
+const q = (value) => encodeURIComponent(String(value));
+/**
+ * A value as one segment of a URL's path: encoded, so a `/` or `?` in it stays inside the segment. One that is empty,
+ * `.` or `..` (which a URL reads as a step up the path, encoded or not) is refused.
+ */
+const seg = (value) => {
+  const text = String(value);
+  if (text === '' || text === '.' || text === '..') throw new RangeError(`${JSON.stringify(text)} can't be a part of a path.`);
+  return encodeURIComponent(text);
+};
+
+/** A fresh round id: 16 random bytes, in hex. Make it when the round starts. */
+export const newRound = () => toHex(globalThis.crypto.getRandomValues(new Uint8Array(16)));
+
+/**
+ * A fresh Ed25519 key: { address, sign(bytes) → Promise<64 bytes>, secret }. `secret` is its 32-byte seed in base58,
+ * for a host server to keep in its secret store; a page's session key never needs it.
+ */
+export async function newKey() {
+  const pair = await subtle().generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
+  const jwk = await subtle().exportKey('jwk', pair.privateKey);
+  return keyOf(pair.privateKey, base64url(jwk.x), jwk.d);
+}
+
+/** The key a host server kept (`secret`: its seed in base58). */
+export async function keyFromSecret(secret) {
+  const seed = decodeBase58(secret);
+  if (seed.length !== 32) throw new Error('A host key secret is 32 bytes in base58.');
+  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);
+  return keyOf(privateKey, base64url(jwk.x), jwk.d);
+}
+
+function keyOf(privateKey, publicBytes, d) {
+  return {
+    address: encodeBase58(publicBytes),
+    secret: encodeBase58(base64url(d)),
+    sign: async (message) => new Uint8Array(await subtle().sign({ name: 'Ed25519' }, privateKey, message)),
+  };
+}
+
+function base64url(text) {
+  const bin = atob(text.replace(/-/g, '+').replace(/_/g, '/'));
+  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+}
+
+/** One signer's signature of a result: { key, signature }. `signer` is a key from newKey, or anything with sign(). */
+export async function signResult(signer, result, cluster = 'devnet') {
+  return { key: signer.address, signature: encodeBase58(await signer.sign(resultBytes({ ...result, cluster }))) };
+}
+
+/**
+ * A host server reports a round. `cert`: the owner's { text, signature } certifying `signer`, the host key. Retrying
+ * with the same result is safe: it is the same answer. Returns the server's answer, { result, vouchers }, or throws its
+ * { code, why }.
+ */
+export async function report({ server, cert, signer, game, round, endedAt, winners, cluster = 'devnet', fetchImpl = globalThis.fetch }) {
+  const result = { game, round, endedAt, winners };
+  const all = [await signResult(signer, result, cluster)];
+  const response = await fetchImpl(`${server.replace(/\/$/, '')}/v1/results`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ ...result, cert, signatures: all }),
+  });
+  return answerOf(response);
+}
+
+/**
+ * A server's answer: its JSON body when the status is a success. Otherwise it throws the server's own { code, why }
+ * when the body says them, or the status in words (an HTML error page from a proxy, an empty body).
+ */
+async function answerOf(response) {
+  const answer = await response.json().catch(() => null);
+  if (!response.ok) throw Object.assign(new Error(answer?.error?.why ?? `The results server answered ${response.status}${response.statusText ? ` ${response.statusText}` : ''}.`), { code: answer?.error?.code, status: response.status });
+  if (answer === null || typeof answer !== 'object') throw Object.assign(new Error(`The results server answered ${response.status} with no JSON.`), { status: response.status });
+  return answer;
+}
+
+/** A wallet's vouchers for a round it won: [{ grant, publicKey, signature, round, expires, … }]. */
+export async function fetchVouchers({ server, game, round, wallet, fetchImpl = globalThis.fetch }) {
+  const response = await fetchImpl(`${server.replace(/\/$/, '')}/v1/vouchers?game=${q(game)}&round=${q(round)}&wallet=${q(wallet)}`);
+  return (await answerOf(response)).vouchers;
+}
+
+/**
+ * A loot grant voucher the host key signs itself, for a host server whose key the grant names (no results server
+ * involved): the program checks it and pays only `wallet`, within the grant's limits. `round` is the result's round id
+ * (16 bytes hex): the program pays a wallet each round once, ever, so the voucher may be signed again, any time, and
+ * still pays once. `incarnation` is the grant's (`Grant.incarnation`): a voucher pays only the grant it was signed
+ * for, never one written again at the same address. `now` is the cluster's clock (unix s); the voucher lives
+ * `seconds` from it, 30 days at most. `amount`: the tokens this claim gives, in base units, for a grant of a fixed amount
+ * of tokens (a rank's reward), at most the grant's; 0 (the default) gives the grant's prize as it is.
+ * Returns { wallet, grant, incarnation, publicKey, signature, round, expires, personHash, amount } for js/play claimGrant,
+ * plain JSON (`incarnation` and `amount` as decimal text), so a server can send it as it is.
+ */
+export async function signVoucher({ signer, game, grant, incarnation, wallet, round, now, seconds = 7 * 86_400, personHash = null, amount = 0n }) {
+  if (!(Number(seconds) > 0)) throw new RangeError('A voucher lives some seconds from now (`seconds` above 0): one that has run out already pays nothing.');
+  if (Number(seconds) > 30 * 86_400) throw new Error('A voucher lives 30 days at most.');
+  // The cluster's clock comes as a number or a bigint (an RPC's, a decoded Clock's); `expires` is a number either way.
+  const expires = Math.floor(typeof now === 'bigint' ? Number(now) : now) + Number(seconds);
+  if (!Number.isSafeInteger(expires)) throw new RangeError('A voucher needs the cluster\'s clock (`now`, unix seconds).');
+  const message = voucherBytes({ grant: pda.grant(game, grant), incarnation, wallet, personHash, round, expires, amount: BigInt(amount) });
+  return { wallet, grant, incarnation: String(BigInt(incarnation)), publicKey: signer.address, signature: encodeBase58(await signer.sign(message)), round, expires, personHash: personHash ?? '0'.repeat(64), amount: String(BigInt(amount)) };
+}
+
+/** Posts JSON to the server and answers its body, or throws its { code, why }. */
+async function post(server, path, body, fetchImpl) {
+  const response = await fetchImpl(`${server.replace(/\/$/, '')}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+  return answerOf(response);
+}
+
+/** Gets JSON from the server and answers its body, or throws its { code, why }. */
+const fetchJson = async (server, path, fetchImpl) => answerOf(await fetchImpl(`${server.replace(/\/$/, '')}${path}`));
+
+/**
+ * A draw, from the organizer's side and the players'. `signMessage(text) → signature bytes` is the organizer's wallet
+ * (its signMessage) or a host key's sign; `by` its address; `cert` the owner's host certificate when `by` is a host key.
+ */
+export const draws = {
+  open: async ({ server, signMessage, by, cert = null, rates = null, fetchImpl = globalThis.fetch, ...spec }) => {
+    const ratesHash = rates ? Array.from(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonicalJson(rates)))), (b) => b.toString(16).padStart(2, '0')).join('') : 'default';
+    const text = drawText({ ...spec, rates: ratesHash });
+    return post(server, '/v1/draws', { text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))), by, ...(cert ? { cert } : {}), ...(rates ? { rates } : {}) }, fetchImpl);
+  },
+  /** A player enters with their play-host token, or with their wallet's signature (`wallet`, `signMessage`). */
+  enter: async ({ server, game, draw, token = null, wallet = null, signMessage = null, cluster = 'devnet', fetchImpl = globalThis.fetch }) => {
+    if (token) return post(server, `/v1/draws/${seg(game)}/${seg(draw)}/entries`, { token }, fetchImpl);
+    const text = entryText({ cluster, game, draw });
+    return post(server, `/v1/draws/${seg(game)}/${seg(draw)}/entries`, { wallet, text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))) }, fetchImpl);
+  },
+  /** Locks the players the server holds now to `beacon`, a drand round still to come. Checks their hash itself. */
+  lock: async ({ server, game, draw, beacon, signMessage, by, cert = null, cluster = 'devnet', net = 'quicknet', fetchImpl = globalThis.fetch }) => {
+    const { draw: view } = await fetchJson(server, `/v1/draws/${seg(game)}/${seg(draw)}`, fetchImpl);
+    const text = lockText({ cluster, game, draw, roster: await rosterHash(view.entries), players: view.entries.length, beacon, net });
+    return post(server, `/v1/draws/${seg(game)}/${seg(draw)}/lock`, { text, signature: encodeBase58(await signMessage(new TextEncoder().encode(text))), by, ...(cert ? { cert } : {}) }, fetchImpl);
+  },
+  /** The draw as anyone may check it; settled, with its result, once its beacon round is out. */
+  get: async ({ server, game, draw, fetchImpl = globalThis.fetch }) => (await fetchJson(server, `/v1/draws/${seg(game)}/${seg(draw)}`, fetchImpl)).draw,
+};
+
+/** A giveaway, from its appointed host's page. */
+export const giveaways = {
+  /** Opens one: `cert` the owner's appointment, `token` the host's play-host sign-in, `session` a key from newKey(). */
+  open: async ({ server, game, cert, token, giveaway, winners, endsBy, session, fetchImpl = globalThis.fetch }) => post(server, `/v1/giveaways/${seg(game)}`, { cert, token, giveaway, winners, endsBy, session: session.address }, fetchImpl),
+  /** Reports its result, signed by its session key. `grant`: the host's grant (each winner is paid from it). */
+  report: async ({ server, game, giveaway, session, endedAt, winners, grant, cluster = 'devnet', fetchImpl = globalThis.fetch }) => {
+    const signed = winners.map((w) => ({ wallet: w.wallet, place: w.place, grant }));
+    const signature = encodeBase58(await session.sign(resultBytes({ cluster, game, round: giveaway, endedAt, winners: signed })));
+    return post(server, `/v1/giveaways/${seg(game)}/${seg(giveaway)}/result`, { endedAt, winners: winners.map(({ wallet, place }) => ({ wallet, place })), signature }, fetchImpl);
+  },
+};

package/js/results/wire.js

@@ -0,0 +1,90 @@
+// The exact bytes and texts a results server checks (the public one runs at https://play.xgames.fun/xsolana), shared
+// with whoever signs them: a host server, a player's game page, an owner's wallet. Browser-safe: no Node imports.
+import { addressBytes } from '../chain/base58.js';
+import { concat, fromHex, uintLE, utf8 } from '../chain/bytes.js';
+
+export const RESULT_DOMAIN = 'loot-result-v1';
+export const NO_GRANT = 0xffff;
+export const CLUSTERS = Object.freeze({ devnet: 0, mainnet: 1 });
+
+/** Each certificate's first line, and the lines that follow it, in order. */
+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'] },
+  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'] },
+  revokeGiveaway: { title: 'loot revoke giveaway host', fields: ['cluster', 'game', 'who'] },
+});
+
+/** 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.`);
+  return value;
+};
+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 });
+/** The text the owner signs to take `host` back. */
+export const revokeText = ({ cluster = 'devnet', game, host }) => write('revoke', { cluster, game, host });
+
+/**
+ * The text the organizer (the game's owner or authority, or a host key they certified) signs to open a draw: a round
+ * whose winners an engine computes from the locked players and a future beacon value. `prizes`: [{ place, grant }];
+ * `payout`: 'vouchers' (the server vouches for each winner) or 'list' (the owner writes the winners' list on the grant);
+ * `identity`: 'linked' (a play-host sign-in linked to X, one entry a person) or 'wallet' (a wallet's own signature);
+ * `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 });
+/** 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}` });
+/** 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 });
+
+/**
+ * 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 });
+/** 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 });
+
+/** 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('');
+}
+
+/** 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(',')}}`;
+  return JSON.stringify(value);
+}
+
+/**
+ * The bytes a result's signers sign:
+ *   "loot-result-v1" | cluster (1) | game (32) | round (16) | endedAt (u64 LE)
+ *   | winners (u8 count; each wallet (32) | place (u8) | grant id (u16 LE, 0xffff: none))
+ * Every field has one length, so one set of bytes means one result: an unknown cluster, a round that is not 16 bytes, a
+ * 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 (!Array.isArray(winners) || winners.length > 255) throw new RangeError('A result names at most 255 winners.');
+  return concat(
+    utf8(RESULT_DOMAIN),
+    Uint8Array.of(CLUSTERS[cluster]),
+    addressBytes(game),
+    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))),
+  );
+}

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@xgamesfun/solana",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.20.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",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XGamesFun/solana-kit.git"
+  },
+  "homepage": "https://github.com/XGamesFun/solana-kit#readme",
+  "bugs": {
+    "url": "https://github.com/XGamesFun/solana-kit/issues"
+  },
+  "keywords": [
+    "solana",
+    "economy",
+    "loot-box",
+    "staking",
+    "nft",
+    "game",
+    "mcp",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./js/index.js"
+    },
+    "./client": {
+      "types": "./types/client/index.d.ts",
+      "default": "./js/client/index.js"
+    },
+    "./chain/*": {
+      "types": "./types/chain/*.d.ts",
+      "default": "./js/chain/*.js"
+    },
+    "./play": {
+      "types": "./types/play/index.d.ts",
+      "default": "./js/play/index.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"
+  },
+  "sideEffects": [
+    "./bin/xsolana.mjs",
+    "./js/approve/page.js"
+  ],
+  "files": [
+    "js/",
+    "!js/test/",
+    "!js/sim/",
+    "types/",
+    "release.json",
+    "bin/",
+    "skills/",
+    "examples/*.json",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "DISCLAIMER.md"
+  ],
+  "scripts": {
+    "test": "node --test \"js/test/**/*.test.mjs\"",
+    "lint": "eslint .",
+    "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:idl": "node scripts/sync-idl.mjs --check",
+    "sync-idl": "node scripts/sync-idl.mjs",
+    "sync-skills": "node scripts/sync-skills.mjs",
+    "release:manifest": "node scripts/release-manifest.mjs",
+    "prepack": "node scripts/release-manifest.mjs --check && tsc -p tsconfig.types.json"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "ajv": "8.20.0",
+    "eslint": "10.13.0",
+    "globals": "17.13.0",
+    "litesvm": "1.6.1",
+    "playwright-core": "1.64.1",
+    "typescript": "7.0.2"
+  },
+  "bin": {
+    "xsolana": "bin/xsolana.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "types": "./types/index.d.ts"
+}

package/release.json

@@ -0,0 +1,8 @@
+{
+  "version": "0.20.1",
+  "programId": "9cwqM1TXytPnFZsLfmUyv2dg4uW6Ch9C6UJVPns7NFQ",
+  "sbfBytes": 1457936,
+  "sbfSha256": "358805a85fd32ba7b5b6bee9dd88e063bda6f854820d978265bca6683790aee7",
+  "idlSha256": "0f75fb422c2e8eca80cfd4fd5ccc1cd8805df9cc12e981bfd0297810c772aca2",
+  "clientSha256": "91537742722a9b31da8afd1f1a2af1bfeea389ad74981e740a41917f81ebecce"
+}

package/skills/xsolana-economy/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: xsolana-economy
+description: Build a web3, token or NFT economy on Solana without writing a smart contract, on loot, one shared program every project uses. Covers shops, loot boxes and gacha, packs, random NFT and token prizes from a stash of NFTs the project holds, coin flips and prize pools, lotteries and raffles, auctions where the highest bid wins and the outbid get their money back, staking farms with lock tiers and NFT boosts, crafting and merging, seasons and emissions, prediction pools and contests, quests, airdrops and capped rewards, holder-gated drops, and perks or staking for any NFT, whether the project minted it or not. Turns a person's idea into a JSON spec, then checks, simulates and prices it, explains it in plain words, and hands the person the command that puts it live in their own wallet. Use whenever someone asks for anything onchain that players or members pay, earn, stake, open, craft or win, for a game, a community, a creator or a brand, and before writing any Anchor, Rust or Solidity for it.
+---
+
+# Build an economy on loot
+
+An economy is one JSON spec (`xsolana.json` in the project) on **loot**, a Solana program every project shares. Nobody
+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).
+
+## Rules (always)
+
+1. **Never write, build or deploy a program.** No Anchor, Rust, Solidity or custom program, and no deploy: not by you,
+   not by a command or page you give the person, not even "just on devnet". Unaudited code holding people's money is
+   the risk loot exists to remove. If the idea needs something loot can't do, follow rule 9.
+2. **You never sign, and you never ask for or handle a key.** No private key, seed phrase or keypair file: not in
+   chat, not in a spec, not in a file. Going live is the person running `xsolana approve` and approving in their own
+   wallet. If they paste a key, tell them to treat it as exposed and move its funds; write it nowhere.
+3. **Devnet only.** Nothing here is real money yet; say so.
+4. **The checker decides.** Never save or publish a spec with refusals. Fix each refusal the way its `fix` says.
+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.
+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.
+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`).
+   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
+   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:
+   - say in one line what is missing and why;
+   - offer the nearest versions (`xsolana_examples` with the words of that piece returns them), best first, each with
+     what it gives up and its "in all" cost; recommend one, and build it;
+   - if they push back, offer the next version or a change that brings back what they miss (a price, a bundle, a
+     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.
+
+## The loop
+
+1. **Read what an economy can be made of**: `xsolana_guide` (every part and field, who acts and what it costs, what
+   loot cannot do). `{"part": "farms"}` for one part's nested shapes.
+2. **Start from the nearest example**: `xsolana_examples {"query": "<the person's own words>"}`, then
+   `xsolana_examples {"name": "<example>"}` for a whole spec to copy. The rated economies say how each real economy
+   fits (great, some, a-lot, cannot) and what carries it.
+3. **Write the spec** from their sentence: `references/sentence-to-spec.md` maps their words to parts. Keep their
+   sentence in `prompt`. Add a `scenario` with the counts they expect (how many opens a day).
+4. **Check it**: `xsolana_check {"spec": …}`. Fix every refusal; every warning is something to tell the person, in a
+   sentence of its own.
+5. **Simulate and explain it**: `xsolana_simulate`, then `xsolana_explain`. Tell the person, in a few short lines, what each
+   play costs and is worth, where the money goes, how the pools fill and drain, what going live costs, what the
+   authority must sign while it runs, and the flags: `references/telling-the-person.md`. Before they approve, say who
+   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`.
+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
+   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`.
+
+## 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
+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,
+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.
+
+## 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`
+- 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`

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

@@ -0,0 +1,114 @@
+# After it goes live: who does what
+
+Going live is the start. Before the person approves, tell them who sends each step the economy needs while it runs,
+and what happens if nobody does. Most failures in practice are a raffle nobody draws, a contest nobody decides, or a
+winner nobody pays.
+
+## Who sends each step
+
+| Step | Who can send it | If nobody does |
+| --- | --- | --- |
+| A box's roll and settle, a shop buy | the player, in their own purchase (`js/play` does both in one prompt) | anyone can settle a rolled order, a normal item too (the app's backend delivers it from the `OrderSettled` receipt of a finalized transaction whose `meta.err` is null, once per order: `loot.receipts(tx)` gives none for a transaction with an error, whose logs can still read as all-success; it reads the transaction again when its log is truncated); a roll that failed or never came refunds (`app.refund`) |
+| A lottery draw, completing its contributions, paying its places | **anyone**: the page (`app.claims()` lists each available step), or a sweep. Paying a winner with no prize account opens it in the same transaction (the sender pays its rent) | selling stops at draw time. A result must be followed by completion of its contributions and payment of every place before the next round. A round nobody draws waits, with no deadline. If the oracle never answers a draw (7 days after it was asked for), anyone can cancel and refund each recorded buyer. An empty round moves on with the next ticket. A one-time lottery ends after its round |
+| A schedule that is due (an emission, rent, a drip) | **anyone**: the page (`app.runSchedule`), a player, a sweep | it waits, and catches up one run at a time |
+| Ending an auction | **anyone**: usually the winner, from the page | it waits: whenever it is ended, the lot goes to the highest bidder |
+| A contest's entries back when it is off, or its winners' claims | **anyone** (each entry's money goes only to its player) | they wait; nothing is lost |
+| Opening a contest | the **authority** (the owner's wallet by default) | nothing happens |
+| Naming its winner, calling it off | the **authority**, or **anyone** sending a verdict one of its `deciders` signed (a results server's key: `decideIx` with `verdict`, after the Ed25519 check of `verdictBytes`) | after `resultDue` it is off by the clock and everyone claims back; a crowdfund short of its `minPot` when entries close is off at once |
+| Moving tokens out of a pool, minting, a `decisions` payout, rewriting a collectible | the **authority** | nothing happens |
+| A grant claim | the **winner** only, from the page: the winning wallet signs every claim, whatever proves it (a voucher, the list, an open grant); anyone may pay its fees, nobody claims for it | the prize waits for them |
+| A prize given directly (a grant's, a lottery place's, a contest's, a mission's, a recipe's: an item, tokens, an NFT of a stash) | the winner's own claim (a grant's: the winner signs it), the place's payment, the winning entry's claim, the unstake or the craft: it is given in that transaction, the sender paying what it opens (a collectible's rent, the winner's token account) | a grant's claim or a craft of a prize it can't give is refused; a lottery's place, a contest's claim or a mission's end goes on without it (an NFT already given, an item sold out or switched off, a pool short pays what it holds) |
+| A prize that is a roll of a box (a grant's, a lottery's place, a contest's winners, an auction's mystery lot, a mission's chest) | the winner's own claim (a grant's), the place's payment or the auction's end makes the winner's order (its rent goes back to the winner at settle); then **anyone** asks the oracle for the roll (`loot.askRollIx`, its fee the asker's) and **anyone** settles it (`loot.settleIx`), which hands over what it rolled, a stash's NFT included; `app.claims()` lists them | it waits, and is never refunded while it waits; asked and never answered, anyone asks again. What the box gives that has run out (an empty stash, a sold-out item) can't be won: the roll lands on its other outcomes, and a fixed prize its pool runs short of pays what the pool holds |
+| Putting more NFTs in a stash, or taking one out | the **owner** (or the authority), holding them: add them to the stash's `nfts` and publish again (only the new ones go in), or `loot.stashIx` with `out` to any wallet | a stash nobody refills just runs out |
+
+"Anyone" means the page can offer a button for it, and any player can press it. Build those buttons with `js/play`:
+`app.claims()` lists what this player can finish now (a draw, its completion or cancellation, a payout, a refund, an
+auction to end), and `app.claim(c)` sends one. A **sweep** is a server that sends overdue public steps for the
+projects it watches. One may or may not be running for the person's project, so never rely on it: the page's buttons
+are what finish them. A sweep never needs anyone's key but its own fee payer.
+
+A lottery's ticket payments stay separate from the prize pot until the draw succeeds: cuts, referrals and burns run
+after it. The buyer's share recipients are fixed when they buy; completing a successful contribution sends its shares
+and its prize funding. Cancelling instead (only for a draw the oracle never answered) returns its entire ticket
+payment and record rent to the recorded buyer, with no ticket split or burn; network and oracle fees stay spent. Prizes and
+outside donations already in the prize pot stay there for the lottery; they are not ticket refunds. Each purchase is
+a record of its own whose rent goes back to its buyer once it is completed (a winning one once its places are paid),
+so a round has no limit on buyers.
+
+Every account a payment goes to is opened by the transaction that pays it, and whoever sends it pays the rent: the
+treasury's or a payee's account at a settle, a winner's at a payout, an outbid bidder's at the next bid. Nothing waits
+on an account, and closing one (an unwrap of wrapped SOL) never stops a sale.
+
+An NFT the project has no authority over is used as it is, with no import step, whatever its kind: Core, Token Metadata
+(legacy, pNFT) or compressed (Bubblegum v2). Any of them can be staked, held, auctioned by the owner or authority,
+and shown to gates and odds (a player auctions only an NFT of the project's own collection);
+a compressed one is proven in the same transaction (`prove_leaf`, which the page does by itself from the RPC's DAS
+methods). What the project writes about one (a level, a use) goes in its Sheet (`["sheet", project, nft]`), written by
+the authority with `collectible` `Set`, by a farm's growth, or by anyone proving the traits the project vouched for
+(`app.proveTraits`).
+
+A new mission is a new farm: add it to the spec and publish again; `runs` ends it that long after it goes live. Near the end of a farm that shares its pool, fund it at least its release span (its longest lock, a day at least) before the end and refresh any seat you suspect is dead a span before it: what is not released by the end, and what a seat gives back after it, stays in the pool, the project's. If rewards cannot move, unstaking can explicitly forfeit them.
+
+Changing a live box's roll (its outcomes, odds, `stockOdds`, `rollsOn`, `then`) fails every roll of it still waiting
+(`W-LIVE-ROLLS`): a purchase gets its payment back, but a roll won on another route (a grant's, a mission's chest, a
+lottery's place, an auction's lot) paid nothing in and refunds 0. Publish such a change once none waits, or make a new
+box. Its price, rise, fall, split, switch, window and gate change freely. A set's way out (the recipe that unbinds it)
+should take no `pay` line (`W-UNBIND-PAY`): a recipe with one waits while the project is paused or the platform
+suspends it, and the pieces stay locked in their farm meanwhile.
+
+Leaving a farm needs only the player's wallet, never a server's signature; what can still keep an NFT from coming
+back is the NFT issuer's own controls (`telling-the-person.md`, NFT custody).
+
+## The owner's own steps: an owner page
+
+What only the authority can sign (open or decide a contest, pay out, move a pool) needs a page the owner opens and
+approves in **their own wallet**, like the approve page. Build it with `@xgamesfun/solana/client` builders
+(`openContestIx`, `decideIx`, `moveTokensIx`) and the wallet's `signTransaction`, served locally or on the same site
+behind nothing more than the owner's wallet: the program checks the signature, so a page holds no secret.
+
+- Show what each button does in words before the wallet asks ("Name the Owls the winner: the pot of 0.42 SOL is
+  shared by 7 backers; 5% goes to you").
+- Never put an owner's or authority's key in a page, a file or a server, and never ask the person to export one.
+
+## Results from a game: who won, and paying them
+
+When a game (not the chain) knows who won a match, cleared a quest or placed in a tournament, pay through a **grant**
+the winner claims themselves. The grant's limits (per wallet in all and per window, per person, per key, per day, in
+total, between two dates) are the most anything can ever pay out, whatever happens to a server.
+
+- **A list** (an airdrop, a known set of winners): the owner writes the wallets in the grant's `list`; no server.
+- **Promo codes, claim links**: the grant's `keys` are the public keys of one keypair per code (made offline from each
+  code; only public keys go in the spec), with `limits.perKey: 1`. The player types the code; the page derives its
+  keypair, signs a voucher for the player's own wallet, and claims (`app.claimGrant(key, { voucher })`). A code pays
+  once in all; a signature someone copies pays only the wallet it names.
+- **Show a badge, claim once**: an open grant (no `vouchers`, `keys` or `list`) with a `gate` and `limits.perWallet`:
+  any wallet that shows the collectible claims, and each collectible shown counts too. No server.
+- **Vouchers from a results server**: the grant names the server's public key in `vouchers`; 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
+    voucher key, never the owner's. Set the grant's `total` and `perWallet`: they bound what a stolen voucher key can
+    pay.
+  - Or a **results server** the person runs or names. It checks results signed by the game's host key, which the
+    owner certifies once by signing a text in their wallet; the game server and pages talk to it with
+    `@xgamesfun/solana/results` (`report`, `giveaways`, `draws`), and winners claim what it vouched for with
+    `app.claimWins({ server, token })` (`token`: the player's sign-in with that server, when it asks for one; a drop
+    of NFTs from a stash gives one only at a signed-in claim, first come first served). Its voucher key is per
+    project (`GET <server>/v1/voucher-key?game=<address>`): the project's address exists only once it is live, so go
+    live first, then add the grant with that key and publish again. A grant written before then is saved switched
+    off (`"active": false`, which `xsolana_check` reports as W-OFF): tell the person it waits for that key, and switch it
+    on when the key goes in. Never use a key from `/v1/health`.
+- **A random draw nobody can rig** (a free draw for members): a results server's computed draws (drand), or a lottery.
+
+Per wallet per day ("2 wins a day each") uses `limits.perWalletEach: { "count": 2, "every": "1d" }`;
+`perDay` separately counts all wallets together. A wallet can claim at most 256 distinct signed voucher rounds
+within one grant incarnation, in any order. Plan a new campaign when that bound would be exceeded; changing
+limits or voucher keys does not clear its history. Closing and recreating a grant starts a new campaign with new
+receipts and invalidates old vouchers. A list written in xsolana.json pays each wallet once per grant incarnation: editing it lets newly added wallets
+claim, never a wallet already paid (for repeated payouts, list the wallet again under a new `round`, or use vouchers). A results server must read the current grant incarnation when accepting
+a result and include it in the voucher it signs.
+
+## Before you act on what the person says happened
+
+"It's been an hour", "the Owls won", "the pool is empty": read the chain first (`xsolana_status`, or the account itself), and
+say what you found. The chain's clock and balances decide what can be sent now.