@xgamesfun/solana 0.25.0 → 0.25.2

package/js/economy/schema.json

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

package/js/economy/trust.mjs

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

package/js/index.js

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

package/js/mcp/http.mjs

@@ -0,0 +1,136 @@
+// The xsolana MCP server over HTTP (MCP's Streamable HTTP transport), for a hosted endpoint that chat apps add by URL
+// (claude.ai, ChatGPT, Claude Desktop), where a local stdio server can't run. It speaks Request and Response, so a
+// Next.js route handler, a Worker or `xsolana mcp --http` all serve it the same way.
+//
+// It is the stdio server's own handler (server.mjs `handle`) in remote mode: only the tools in REMOTE_TOOLS, every spec
+// passed whole as an argument, no file read or written, nothing signed. Each request stands alone (no session), and
+// every answer is one JSON body: no event stream, so GET is refused as the transport allows.
+import { createServer } from 'node:http';
+import { handle } from './server.mjs';
+
+/** The largest request body read: a spec is a few kilobytes; a megabyte is far more than any. */
+export const MAX_BODY_BYTES = 1_000_000;
+
+const CORS = {
+  'access-control-allow-origin': '*',
+  'access-control-allow-methods': 'POST, OPTIONS',
+  'access-control-allow-headers': 'content-type, accept, authorization, mcp-protocol-version, mcp-session-id',
+  'access-control-max-age': '86400',
+};
+
+const json = (body, status = 200) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json', 'cache-control': 'no-store', ...CORS },
+  });
+const empty = (status, headers = {}) => new Response(null, { status, headers: { ...CORS, ...headers } });
+const rpcError = (code, message, status = 400) => json({ jsonrpc: '2.0', id: null, error: { code, message } }, status);
+
+/** The body as text, or null once it is longer than `limit` bytes. */
+async function bodyText(request, limit) {
+  const said = Number(request.headers.get('content-length'));
+  if (said > limit) return null;
+  if (!request.body) return '';
+  const reader = request.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.length;
+    if (size > limit) {
+      await reader.cancel();
+      return null;
+    }
+    chunks.push(value);
+  }
+  const all = new Uint8Array(size);
+  let at = 0;
+  for (const c of chunks) {
+    all.set(c, at);
+    at += c.length;
+  }
+  return new TextDecoder().decode(all);
+}
+
+/**
+ * One HTTP request to the MCP endpoint, answered. `allowOrigin(origin)` decides which browser origins may call it (a
+ * request with no Origin header, from a server or a desktop app, always may); by default every origin, since the
+ * endpoint holds no session, no cookie and nothing private.
+ * @param {Request} request
+ * @param {{ allowOrigin?: (origin: string) => boolean, maxBodyBytes?: number, ctx?: object }} [options]
+ * @returns {Promise<Response>}
+ */
+export async function mcpHttp(request, { allowOrigin = () => true, maxBodyBytes = MAX_BODY_BYTES, ctx = {} } = {}) {
+  const origin = request.headers.get('origin');
+  if (origin && !allowOrigin(origin)) return rpcError(-32000, 'This origin may not call this server.', 403);
+  if (request.method === 'OPTIONS') return empty(204);
+  if (request.method !== 'POST') return empty(405, { allow: 'POST, OPTIONS' });
+  const text = await bodyText(request, maxBodyBytes);
+  if (text === null) return rpcError(-32600, `The request is larger than ${maxBodyBytes} bytes.`, 413);
+  let message;
+  try {
+    message = JSON.parse(text);
+  } catch {
+    return rpcError(-32700, 'Not JSON.');
+  }
+  const answer = m =>
+    handle(m, { ...ctx, remote: true }).catch(e => ({
+      jsonrpc: '2.0',
+      id: m?.id ?? null,
+      error: { code: -32603, message: e.message },
+    }));
+  if (Array.isArray(message)) {
+    const replies = (await Promise.all(message.map(answer))).filter(Boolean);
+    return replies.length ? json(replies) : empty(202);
+  }
+  const reply = await answer(message);
+  // A notification or a client's response gets no body.
+  return reply ? json(reply) : empty(202);
+}
+
+/**
+ * Serves mcpHttp at `path` on this machine (`xsolana mcp --http`). It listens on 127.0.0.1 unless told otherwise, and
+ * then answers only pages on localhost: a site in the browser can't reach it by renaming its host (DNS rebinding).
+ * @returns {Promise<{ address(): { port: number } | string | null, close(done?: () => void): unknown }>} the node:http server
+ */
+export function serveHttp({ port = 8787, host = '127.0.0.1', path = '/mcp' } = {}) {
+  const local = host === '127.0.0.1' || host === 'localhost' || host === '::1';
+  const allowOrigin = origin => {
+    if (!local) return true;
+    try {
+      return ['localhost', '127.0.0.1', '[::1]'].includes(new URL(origin).hostname);
+    } catch {
+      return false;
+    }
+  };
+  const server = createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      if (url.pathname !== path) {
+        res.writeHead(404, { 'content-type': 'text/plain' }).end(`The MCP endpoint is ${path}.`);
+        return;
+      }
+      const request = new Request(url, {
+        method: req.method,
+        headers: Object.entries(req.headers).flatMap(([k, v]) =>
+          v === undefined ? [] : (Array.isArray(v) ? v : [v]).map(one => [k, one]),
+        ),
+        body: req.method === 'GET' || req.method === 'HEAD' ? undefined : req,
+        duplex: 'half',
+      });
+      const response = await mcpHttp(request, { allowOrigin });
+      res.writeHead(response.status, Object.fromEntries(response.headers));
+      res.end(response.body ? Buffer.from(await response.arrayBuffer()) : undefined);
+    } catch (e) {
+      res.writeHead(500, { 'content-type': 'text/plain' }).end(e.message);
+    }
+  });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      console.error(`xsolana MCP server over HTTP: http://${host}:${server.address().port}${path}`);
+      resolve(server);
+    });
+  });
+}

package/js/mcp/server.mjs

@@ -6,14 +6,35 @@
 //
 // stdout is the protocol: everything else goes to stderr.
 import { validate } from '../economy/validate.mjs';
-import { PROGRAM_INFO, tools, VERSION } from './tools.mjs';
+import { PACKAGE_VERSION, PROGRAM_INFO, REMOTE_TOOLS, tools, VERSION } from './tools.mjs';
 
 export const INSTRUCTIONS = [
   'loot is one shared Solana program for game and community economies (shops, loot boxes, lotteries, auctions, staking farms, crafting, contests, schedules, perks for holders of any NFT, capped rewards). An economy is a JSON spec, not a new smart contract: never write Anchor or Rust for what loot covers.',
-  'Start with xsolana_guide, then xsolana_examples with the person’s own words; write the spec; xsolana_check after every change; xsolana_simulate and xsolana_explain before telling them what it does; xsolana_save; xsolana_publish when they say to put it live (they approve in their own wallet: you never sign or ask for a key).',
+  'Start with xsolana_guide, then xsolana_examples with the person’s own words; write the spec; xsolana_check after every change; xsolana_simulate and xsolana_explain before telling them what it does; xsolana_review before going live (fix its high findings, say honestly what each voucher server checks, and tell the person what a cheater gets); xsolana_save; xsolana_publish when they say to put it live (they approve in their own wallet: you never sign or ask for a key).',
   `Program ${PROGRAM_INFO.program} on ${PROGRAM_INFO.cluster} (loot ${VERSION}). Devnet only until audited.`,
 ].join(' ');
 
+/**
+ * What a hosted server (js/mcp/http.mjs) tells the agent: the same work, with the spec passed whole in every call,
+ * and going live on the person's own computer, since a hosted server can neither write their files nor open a page there.
+ */
+export const REMOTE_INSTRUCTIONS = [
+  INSTRUCTIONS.split(' Start with')[0],
+  'Start with xsolana_guide, then xsolana_examples with the person’s own words; write the spec and pass it whole as "spec" to every tool (this hosted server reads no files); xsolana_check after every change; xsolana_simulate and xsolana_explain before telling them what it does; xsolana_review before going live (fix its high findings, say honestly what each voucher server checks, and tell the person what a cheater gets).',
+  `To go live, give the person the spec as a file named xsolana.json and this command, run in its folder: npx -y @xgamesfun/solana@${PACKAGE_VERSION} approve xsolana.json. It opens a page on their own computer where they approve each transaction in their own wallet. Nobody else signs, and never ask for a key. (xsolana_save and xsolana_publish, which tool texts may name, run only in the local server.)`,
+  `Program ${PROGRAM_INFO.program} on ${PROGRAM_INFO.cluster} (loot ${VERSION}). Devnet only until audited.`,
+].join(' ');
+
+/** A tool as tools/list shows it; on a hosted server, without the `file` argument it can't take. */
+function listed(t, remote) {
+  let inputSchema = t.inputSchema;
+  if (remote && inputSchema.properties?.file) {
+    const { file: _file, ...properties } = inputSchema.properties;
+    inputSchema = { ...inputSchema, properties };
+  }
+  return { name: t.name, description: t.description, inputSchema, annotations: t.annotations };
+}
+
 /**
  * The protocol versions this server speaks, newest first. A client that asks for one of them gets it; any other ask
  * gets the newest, and the client decides whether it can go on (the spec's version negotiation).
@@ -36,6 +57,13 @@ export async function runTool(name, input = {}, ctx = {}) {
       text: `No tool ${name}.${near.length ? ` Did you mean ${near.join(', ')}?` : ''} Tools: ${tools.map(t => t.name).join(', ')}.`,
     };
   }
+  if (ctx.remote && !REMOTE_TOOLS.has(name))
+    return {
+      isError: true,
+      text: `${name} works on the person’s own files, so it runs only in the local server (npx -y --package=@xgamesfun/solana@${PACKAGE_VERSION} xsolana mcp).`,
+    };
+  if (ctx.remote && 'file' in input)
+    return { isError: true, text: 'This hosted server reads no files: pass the whole spec as "spec".' };
   const bad = inputProblems(tool.inputSchema, input);
   if (bad.length) return { isError: true, text: bad.join('; ') };
   try {
@@ -64,22 +92,18 @@ export async function handle(message, ctx = {}) {
         protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0],
         capabilities: { tools: {} },
         serverInfo: { name: 'xsolana', version: VERSION },
-        instructions: INSTRUCTIONS,
+        instructions: ctx.remote ? REMOTE_INSTRUCTIONS : INSTRUCTIONS,
       });
     }
     case 'ping':
       return reply({});
     case 'tools/list':
       return reply({
-        tools: tools.map(t => ({
-          name: t.name,
-          description: t.description,
-          inputSchema: t.inputSchema,
-          annotations: t.annotations,
-        })),
+        tools: tools.filter(t => !ctx.remote || REMOTE_TOOLS.has(t.name)).map(t => listed(t, ctx.remote)),
       });
     case 'tools/call': {
-      const result = await runTool(params?.name, params?.arguments ?? {}, { ...ctx, cwd: ctx.cwd ?? process.cwd() });
+      const input = params?.arguments ?? {};
+      const result = await runTool(params?.name, input, ctx.remote ? ctx : { ...ctx, cwd: ctx.cwd ?? process.cwd() });
       // A tool that failed says so (isError), and keeps whatever it found (a save's refusals, say) as structuredContent.
       const { text, isError, ...data } = jsonable(result);
       return reply({

package/js/mcp/tools.mjs

@@ -15,6 +15,7 @@ import { cost, explainCost } from '../economy/cost.mjs';
 import { changedParts } from '../economy/live.mjs';
 import { example, examples, ideas, search, partsUsed } from '../economy/examples.mjs';
 import { explainEconomy } from '../economy/explain.mjs';
+import { describeReview, review } from '../economy/review.mjs';
 import { CANNOT, catalog, guideText, PARTS } from '../economy/guide.mjs';
 import { model, rent as rentOf } from '../economy/model.mjs';
 import { plan } from '../economy/plan.mjs';
@@ -68,6 +69,22 @@ const nowOf = ctx => ctx?.now ?? Math.floor(Date.now() / 1000);
 const cwdOf = ctx => ctx?.cwd ?? process.cwd();
 export const DEFAULT_FILE = 'xsolana.json';
 
+/**
+ * The tools a hosted server (js/mcp/http.mjs) offers: those that read nothing but their arguments and the chain.
+ * xsolana_save and xsolana_publish write and read the person's own files, so they run only on the person's machine.
+ */
+export const REMOTE_TOOLS = new Set([
+  'xsolana_guide',
+  'xsolana_examples',
+  'xsolana_check',
+  'xsolana_simulate',
+  'xsolana_cost',
+  'xsolana_explain',
+  'xsolana_review',
+  'xsolana_status',
+  'xsolana_client',
+]);
+
 /** The real path of `p`, or of the nearest folder above it that exists, with the rest added back. */
 function realPath(p) {
   try {
@@ -140,6 +157,11 @@ const SOURCE = {
 async function load(input, ctx) {
   if (input.spec) return { economy: economyOf(input.spec), from: 'the spec given' };
   if (input.example) return { economy: example(input.example).spec, from: `the example ${input.example}` };
+  // A hosted server (js/mcp/http.mjs) reads no file: the machine it runs on is not the person's.
+  if (ctx?.remote)
+    throw new Error(
+      'This hosted server reads no files: pass the whole spec as "spec" (or a worked example by name as "example").',
+    );
   const rel = input.file ?? DEFAULT_FILE;
   const file = projectFile(rel, ctx);
   if (!existsSync(file)) {
@@ -339,7 +361,7 @@ export const tools = [
       const verdict = check(economy, { now: nowOf(ctx) });
       const head = verdict.refusals.length || verdict.warnings.length ? describe(verdict) : 'No problems found.';
       const tail = verdict.ok
-        ? `\nReady (${plural(verdict.warnings.length, 'warning')}). Next: xsolana_simulate and xsolana_explain, and tell the person what it means in plain words.`
+        ? `\nReady (${plural(verdict.warnings.length, 'warning')}). Next: xsolana_simulate and xsolana_explain, and tell the person what it means in plain words; before going live, xsolana_review.`
         : `\n${plural(verdict.refusals.length, 'refusal')}: fix each as its fix says, then check again.`;
       return {
         ok: verdict.ok,
@@ -420,6 +442,30 @@ export const tools = [
       return { ...r, from, text: r.text + footer };
     },
   },
+  {
+    name: 'xsolana_review',
+    annotations: READ,
+    description:
+      'Review an economy the way a cheater reads it, before it goes live (not a validity check: xsolana_check is that). For every route that pays or gives value it says who can trigger it, what the program enforces, what it trusts off the chain, and the most one cheater gets; then findings with stable ids and a severity; then the trade-off to show the person: for each grant paid on vouchers, whether its server decides, replays or only bounds the result (its "trust"), what a cheater gets at that level, and what the next level costs to build. Fix every high finding, declare "trust" honestly on every voucher grant, and tell the person in plain words which level each signed route uses and what a cheater gets, so they choose the trade-off. Give the spec inline (`spec`), a file, or an example. Answers { ok (false when a finding is high, or the spec does not check: then `refusals`), routes: [{ kind ("grant", "farm", "item", "box", "payment", "recipe", "lottery", "contest", "auction", "schedule", "hold", "decision"), key, name, trigger, enforced: [words], trusts: [words], trust ("decides" | "replays" | "bounds" | null), ceiling (words), feeds: ["farm:<key>", …: what its prize is staked in, crafted into or buys] }], findings: [{ id (R-…), severity ("high" | "medium" | "low" | "info"), route ("grant:<key>", "farm:<key>", … or "economy"), message, fix }], tradeoffs (markdown) }.',
+    inputSchema: { type: 'object', properties: SOURCE, additionalProperties: false },
+    async handler(input, ctx) {
+      const { economy, from } = await load(input, ctx);
+      const r = review(economy, { now: nowOf(ctx) });
+      if (r.refusals) return refused({ refusals: r.refusals, warnings: [] }, from);
+      const highs = r.findings.filter(f => f.severity === 'high').length;
+      const tail = highs
+        ? `\n${plural(highs, 'high finding')}: fix ${highs === 1 ? 'it' : 'them'} (or have the person accept ${highs === 1 ? 'it' : 'them'} in plain words) before going live, then review again.`
+        : '\nNo high finding. Tell the person, in plain words, which level each signed route uses and what a cheater gets (the trade-offs above).';
+      return {
+        ok: r.ok,
+        from,
+        routes: r.routes,
+        findings: r.findings,
+        tradeoffs: r.tradeoffs,
+        text: `${describeReview(r, economy.name)}${tail}${footer}`,
+      };
+    },
+  },
   {
     name: 'xsolana_save',
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -566,7 +612,7 @@ export const tools = [
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     description:
       'A live economy as it is on chain: the project, every pool’s balance, every record the spec names (found or missing). Reads devnet (or XSOLANA_RPC_URL).',
-    inputSchema: { type: 'object', properties: { file: SOURCE.file }, additionalProperties: false },
+    inputSchema: { type: 'object', properties: { spec: SOURCE.spec, file: SOURCE.file }, additionalProperties: false },
     async handler(input, ctx) {
       const { economy, from } = await load(input, ctx);
       if (!economy.live?.project)
@@ -658,6 +704,7 @@ export const tools = [
         '  `chosenRecipient` (buy, openBox, pay): the wallet (or collectible) the player names for a "chosen" share of the split (a referrer from the link)',
         '  app.lotteries(), app.buyTickets(key, n, { listing }) (or { maxPrice }: a ticket’s most, in base units),',
         '  app.stake(key, amount), app.harvest(key), app.staked(key) (each seat and what it is owed now), app.recipes(), app.craft(key, assets, 1, { listing }), app.claimGrant(key),',
+        '  solanaApp({ ..., sponsor: httpSponsor({ url, address }) })   the project pays players’ fees (never the price) from a key on its own server: @xgamesfun/solana/sponsor sponsorSigner + sponsorHandler there',
         '  app.collectibles(), app.balances()   what a player does. `listing`: the entry shop(), boxes(), lotteries() or recipes() showed the',
         '  player; its price (or version) is the most they pay: one that moved since is refused, never paid unseen',
         '  a prize (a grant, a lottery place, a contest win, a mission, a recipe) is given in the instruction that wins it,',
@@ -679,6 +726,7 @@ export const tools = [
         '  import * as loot from "@xgamesfun/solana/client";',
         '  loot.pda.project(owner, number), loot.pda.box(project, id), …   every address the program derives',
         '  loot.openBoxIx({ player, project, box, nonce }), loot.buyIx({ player, project, box, items }) …   one builder per instruction; each returns { programId, keys, data }',
+        '  loot.toKitInstruction(ix)   a builder’s instruction in @solana/kit’s shape ({ programAddress, accounts, data }), for an app built on Kit; loot.fromKitInstruction back',
         '  loot.payNftIx({ player, project, asset, to })             pay with an NFT (burned, or given to `to`): the app admits by the receipt',
         '  loot.openListingIx / takeListingIx / closeListingIx, loot.listingTerms(listing), loot.pda.listing(project, asset), loot.renterOf(listing, now)',
         '  a take or a bid signs the record’s terms: loot.listingTerms / offerTerms / auctionTerms(record), the hash of its bytes as read, but what a take changes',

package/js/play/index.js

@@ -57,6 +57,20 @@ import {
 import { compileMessage, readTransaction, wireTransaction } from '../chain/tx.js';
 import * as loot from '../client/index.js';
 import { browserStore, keyring } from './keys.js';
+import { SPONSOR_MAX_LAMPORTS, sponsoredCost, sponsorGiveBack, sponsorTopUp, stepShape, topUpFor } from './sponsor.js';
+
+export {
+  checkSponsored,
+  httpSponsor,
+  sponsoredCost,
+  sponsorGiveBack,
+  sponsorHandler,
+  sponsorSigner,
+  sponsorTopUp,
+  stepShape,
+  topUpFor,
+  SPONSOR_MAX_LAMPORTS,
+} from './sponsor.js';
 
 // The options of a call made without any: read-only, and typed so the generated declarations take any option.
 /** A lottery's steps in `claims()`: each depends on the one before, so `claimAll` takes one of a lottery's a call. */
@@ -190,6 +204,7 @@ export function solanaApp({
   programs = {},
   now = () => Math.floor(Date.now() / 1000),
   keyStore = browserStore(),
+  sponsor = null,
 }) {
   const live = spec?.live;
   if (!live?.project) throw new Error('This economy is not live yet: its xsolana.json has no "live" section.');
@@ -591,6 +606,15 @@ export function solanaApp({
     // A compressed NFT's record is closed in the transaction that used it, its prover signing: its rent comes back.
     instructions = loot.withLeafCloses(instructions);
     if (!keepWrapped) instructions = await unwrapAfter(instructions);
+    if (sponsor) {
+      const sponsored = await sendSponsored(instructions, extra);
+      if (sponsored) return sponsored;
+    }
+    return sendUnsponsored(instructions, extra);
+  }
+
+  /** The player's step as they pay for it themselves: their wallet the fee payer (`sendFitting`). */
+  async function sendUnsponsored(instructions, extra = []) {
     const sign = async message => {
       const { signers } = readTransaction(wireTransaction(message));
       const sigs = await Promise.all(
@@ -616,6 +640,79 @@ export function solanaApp({
 
   const sendNow = (...args) => send(...args);
 
+  /** The most the sponsor pays a transaction (its top-up and network fee), as the app was told. */
+  // It lends the player that, less room for the network fee, and takes back what the step didn't need.
+  const sponsorMax = sponsor ? BigInt(sponsor.maxLamports ?? SPONSOR_MAX_LAMPORTS) - SIGNATURE_FEE * 4n : 0n;
+
+  /** Every account a list of instructions names, its programs too. */
+  const namedIn = instructions => [
+    ...new Set(instructions.flatMap(ix => [ix.programId, ...ix.keys.map(k => k.pubkey)])),
+  ];
+
+  /**
+   * The player's step with the sponsor paying (`sponsor`, js/play/sponsor.js): the sponsor the fee payer and the
+   * player topped up first by what the step costs them in fees and rent (a dry run, as the sponsor's server will
+   * check it), the player's wallet signing, then the sponsor's server. Null when it can't be sponsored as one
+   * transaction (it needs a lookup table of its own, or proofs sent first), or the sponsor refused it and the player
+   * pays instead (`sponsor.playerPaysIfRefused`, the default): the step then goes as the player's own.
+   */
+  async function sendSponsored(instructions, extra) {
+    const me = wallet.address;
+    const tables = await standing();
+    const { blockhash, lastValidBlockHeight } = await client.latestBlockhash();
+    // Lent the most, the step is tried; then sent lent the same, the player giving back last all but what it costs in
+    // fees and rent: a step can need more SOL midway than it costs (a wrapped-SOL account it opens and closes).
+    const compile = (back = 0n) =>
+      compileFitting({
+        payer: sponsor.address,
+        blockhash,
+        instructions: [
+          sponsorTopUp(sponsor.address, me, sponsorMax),
+          ...instructions,
+          ...(back > 0n ? [sponsorGiveBack(sponsor.address, me, back)] : []),
+        ],
+        tables,
+      });
+    const tried = compile();
+    if (!tried) return null;
+    const addresses = namedIn([sponsorTopUp(sponsor.address, me, 0n), ...instructions]);
+    const pre = await client.accounts(addresses);
+    // A step loot refuses is refused in words; one that fails otherwise (the sponsor short of SOL) goes as the player's.
+    const run = await client
+      .simulate(wireTransaction(tried), { accounts: addresses, replaceBlockhash: true })
+      .catch(e => (loot.lootError(e?.logs ?? []) ? inWords(e) : null));
+    if (!run) return null;
+    const post = run.accounts;
+    const at = a => addresses.indexOf(a);
+    const balance = a => (a ? BigInt(a.lamports) : 0n);
+    const cost = sponsoredCost({
+      addresses,
+      pre,
+      post,
+      project,
+      skip: [sponsor.address, me],
+      ...stepShape(instructions),
+    });
+    const spend = balance(pre[at(me)]) + sponsorMax - balance(post[at(me)]);
+    const message = compile(sponsorMax - topUpFor({ spend, cost }));
+    if (!message) return null;
+    const { signers } = readTransaction(wireTransaction(message));
+    const sigs = await Promise.all(
+      signers.map(async s => extra.find(k => k.address === s)?.sign(message) ?? new Uint8Array(64)),
+    );
+    const signed = await wallet.signTransaction(wireTransaction(message, sigs));
+    let wire;
+    try {
+      wire = await sponsor.sign(signed);
+    } catch (e) {
+      if (sponsor.playerPaysIfRefused === false) throw e;
+      return null;
+    }
+    const signature = await client.send(wire).catch(inWords);
+    await client.confirm?.(signature, { lastValidBlockHeight });
+    return signature;
+  }
+
   /**
    * Several independent steps of the player's, each one transaction (`lists`: their instructions), signed in one wallet
    * prompt when the wallet signs several at once (`wallet.signTransactions`), then sent in order; one by one otherwise,
@@ -630,7 +727,7 @@ export function solanaApp({
     let signed = null;
     let messages = [];
     let lastValidBlockHeight = null;
-    if (wallet?.signTransactions && lists.length > 1) {
+    if (wallet?.signTransactions && lists.length > 1 && !sponsor) {
       const latest = await client.latestBlockhash();
       lastValidBlockHeight = latest.lastValidBlockHeight;
       const tables = await standing();
@@ -791,6 +888,12 @@ export function solanaApp({
    * them), and the accounts `watch` as they would be after: { ok, accounts, error }, `error` loot's when it refused
    * ({ code, name, msg }, `loot.lootError`). */
   async function dryRun(payer, instructions, watch = []) {
+    // A sponsored player's step is tried as it will be sent: the sponsor pays, and tops the player up (here by the
+    // most it pays, so a player with no SOL is tried as one the sponsor covers).
+    if (sponsor && payer === wallet?.address) {
+      instructions = [sponsorTopUp(sponsor.address, payer, sponsorMax), ...instructions];
+      payer = sponsor.address;
+    }
     const { blockhash } = await client.latestBlockhash();
     const message = compileFitting({ payer, blockhash, instructions, tables: await standing() });
     if (!message) return { ok: false, accounts: [], error: null };
@@ -848,6 +951,17 @@ export function solanaApp({
       return order.status === 'Waiting' && order.player === wallet.address ? [[address, order]] : [];
     });
     if (!waiting.length) return { signature: await send(instructions), rolls: [] };
+    // Sponsored, a settle key isn't funded (a plain account the player could empty is never sponsored): the step asks
+    // for each roll, and the player's wallet settles it once it is answered (one more prompt, sponsored too).
+    if (sponsor) {
+      const asked = [...instructions];
+      for (const [orderAddress, order] of waiting) asked.push(...(await asksFor(wallet.address, orderAddress, order)));
+      const tried = await dryRun(wallet.address, asked);
+      const signature = await send(tried.ok ? asked : instructions);
+      const rolls = [];
+      if (tried.ok) for (const [orderAddress] of waiting) rolls.push(await collect(orderAddress, { opened: true }));
+      return { signature, rolls };
+    }
     const asks = [];
     const funds = [];
     const burners = [];
@@ -1337,7 +1451,7 @@ export function solanaApp({
       on = null,
       maxPrice,
       listing,
-      oneSignature = true,
+      oneSignature = !sponsor,
       chosenRecipient = null,
       listProof,
       count = 1,