@xgamesfun/solana 0.25.1 → 0.25.3

package/README.md

@@ -1,7 +1,9 @@
-# solana-kit
+# solana-kit: Solana game and NFT economies without a smart contract
 
-The tools for **loot**, one shared Solana program for game and community economies. This repository is the npm
-package `@xgamesfun/solana`:
+Loot boxes and gacha, shops, lotteries and raffles, auctions, NFT staking farms, crafting, quests and capped rewards on
+Solana, written as a JSON spec instead of a new Anchor program. They all run on **loot**, one shared, open Solana
+program, and an AI coding agent (Claude Code, Codex, Cursor or any MCP client) can design, check, simulate and price
+one from a sentence. This repository is the npm package `@xgamesfun/solana`:
 
 - a JavaScript client with no Solana SDK (`@xgamesfun/solana/client`), a player module for apps (`/play`) and a results
   client (`/results`);
@@ -104,14 +106,29 @@ codex plugin marketplace add XGamesFun/solana-kit
 codex plugin add xsolana@xgamesfun
 ```
 
+**Chat apps** (claude.ai, ChatGPT, Claude Desktop): add `https://xgames.fun/mcp` as a custom connector (an MCP server
+by URL). It is the hosted server (below, "Over HTTP"): nothing to install, and going live stays your own approval on your
+computer. More at [xgames.fun/solana](https://xgames.fun/solana).
+
 **Any agent with MCP** (Cursor, opencode, Cline…): run the server with
-`npx -y --package=@xgamesfun/solana@0.25.1 xsolana mcp`. Or let `npx -y @xgamesfun/solana@0.25.1 connect` register it, with
+`npx -y --package=@xgamesfun/solana@0.25.3 xsolana mcp`. Or let `npx -y @xgamesfun/solana@0.25.3 connect` register it, with
 the skill, for Claude Code and Codex.
 
+**The skill alone, in any agent that reads skills** (Claude Code, Codex, Copilot, Gemini CLI, Cursor, Windsurf, Cline,
+opencode…): `npx skills add XGamesFun/solana-kit` finds it and installs it for the agents you have. Without the MCP
+server it runs the same tools through `npx`. Each GitHub release also carries `xsolana-economy.zip`, the skill as one
+file for apps that take a skill as an upload (the Claude and ChatGPT desktop apps).
+
+**Over HTTP**: `npx -y --package=@xgamesfun/solana@0.25.3 xsolana mcp --http` serves the tools that read nothing but
+their arguments (guide, examples, check, simulate, cost, explain, review, status, client) at
+`http://127.0.0.1:8787/mcp`, MCP's Streamable HTTP transport. `@xgamesfun/solana/mcp/http` exports the same handler
+(`mcpHttp(request) → response`) for a hosted endpoint: it reads no files, and the agent hands the person the spec and the
+`approve` command to go live.
+
 Then ask for an economy, for example _"a fishing game where each cast costs 0.02 SOL, with a rare golden fish and a
 monthly draw"_.
 
-Going live is always yours: `npx -y @xgamesfun/solana@0.25.1 approve` opens a page on your computer where you connect a
+Going live is always yours: `npx -y @xgamesfun/solana@0.25.3 approve` opens a page on your computer where you connect a
 devnet wallet and approve each transaction. The agent never signs and never asks for a key.
 
 ## Use it from a terminal
@@ -119,13 +136,13 @@ devnet wallet and approve each transaction. The agent never signs and never asks
 Every tool runs from the CLI too, on a spec file (`xsolana.json` by default):
 
 ```bash
-npx -y @xgamesfun/solana@0.25.1 examples shop with loot boxes   # the nearest worked examples
-npx -y @xgamesfun/solana@0.25.1 check xsolana.json                 # refusals and warnings
-npx -y @xgamesfun/solana@0.25.1 simulate xsolana.json              # where the money goes, day by day
-npx -y @xgamesfun/solana@0.25.1 cost xsolana.json                  # what going live and each action cost
-npx -y @xgamesfun/solana@0.25.1 explain xsolana.json               # the economy in plain words
-npx -y @xgamesfun/solana@0.25.1 review xsolana.json                # what a cheater gets on each route (exits 1 on a high finding)
-npx -y @xgamesfun/solana@0.25.1 approve xsolana.json               # go live, approved in your own wallet
+npx -y @xgamesfun/solana@0.25.3 examples shop with loot boxes   # the nearest worked examples
+npx -y @xgamesfun/solana@0.25.3 check xsolana.json                 # refusals and warnings
+npx -y @xgamesfun/solana@0.25.3 simulate xsolana.json              # where the money goes, day by day
+npx -y @xgamesfun/solana@0.25.3 cost xsolana.json                  # what going live and each action cost
+npx -y @xgamesfun/solana@0.25.3 explain xsolana.json               # the economy in plain words
+npx -y @xgamesfun/solana@0.25.3 review xsolana.json                # what a cheater gets on each route (exits 1 on a high finding)
+npx -y @xgamesfun/solana@0.25.3 approve xsolana.json               # go live, approved in your own wallet
 ```
 
 `xsolana help` lists every command. Every command names the exact version, so `npx` runs that release and never whatever
@@ -142,6 +159,13 @@ import * as loot from '@xgamesfun/solana/client';
 const ix = loot.openBoxIx({ player, project, box, nonce }); // one builder per instruction, no Solana SDK
 ```
 
+Players with no SOL can still play when the project sponsors their fees: `solanaApp({ sponsor })` has a key on the
+project's own server pay each step's fees and rent (never its price), and `@xgamesfun/solana/sponsor` is that server's
+side: `sponsorSigner` dry-runs and checks every transaction before it signs, under the project's own per-player budget.
+
+Building on `@solana/kit`? `loot.toKitInstruction(ix)` gives any builder's instruction in Kit's shape
+(`{ programAddress, accounts, data }`), and `loot.fromKitInstruction` turns one back.
+
 | Import                           | What                                                                                        |
 | -------------------------------- | ------------------------------------------------------------------------------------------- |
 | `@xgamesfun/solana`              | the economy tools: `check`, `simulate`, `plan`, `cost`, `explainEconomy`, `review`, `model` |
@@ -155,10 +179,35 @@ const ix = loot.openBoxIx({ player, project, box, nonce }); // one builder per i
 The client, chain and play modules run in browsers and Node 22 or later, with no bundler required. The package
 ships TypeScript declarations for every entry point.
 
+## Questions people ask
+
+**How do I make a loot box, gacha or pack opening on Solana without writing a smart contract?** Describe it as a box
+in a spec (its price, its outcomes and their odds, what each one pays), run `xsolana check` and `xsolana simulate`, then
+approve it in your wallet with `xsolana approve`. Rolls come from MagicBlock's VRF, and a buyer is refunded if the
+oracle never answers. [`examples/`](examples) has whole worked economies.
+
+**How do I add staking to an NFT collection, even one I didn't mint?** A staking farm takes any collection, with lock
+tiers, boosts and fixed or shared reward rates. The project needs no authority over the NFTs: see
+[`docs/nfts.md`](docs/nfts.md).
+
+**Can I run a lottery, raffle or auction on Solana without deploying a program?** Yes: lotteries (including no-loss
+ones), raffles with a Merkle allowlist, and auctions that refund the outbid at once are all routes in the same spec.
+
+**Is there an MCP server or Claude Code plugin for building on Solana?** Yes: the `xsolana` plugin for Claude Code and
+Codex, the hosted server at `https://xgames.fun/mcp` for chat apps, and `npx -y --package=@xgamesfun/solana@0.25.3 xsolana mcp` for any MCP client. It is listed in the MCP
+Registry as `io.github.XGamesFun/solana-kit`.
+
+**How is this different from writing my own Anchor program?** Nothing is written, deployed or upgraded per project:
+every project's rules are checked by the one program, and its tests run every instruction against that program in
+LiteSVM. The trade-off is that an economy can only be what the spec can say ([known limits](docs/program.md#known-limits)).
+
+**Does it run on mainnet?** Not yet: devnet only until the program is independently audited.
+
 ## Documentation
 
 |                                                                                    |                                                                                             |
 | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| [`docs/tutorial-loot-box.md`](docs/tutorial-loot-box.md)                           | a loot box from one sentence to going live, step by step                                    |
 | [`docs/program.md`](docs/program.md)                                               | the program: who signs, accounts, every instruction, fees, limits, receipts, costs          |
 | [`docs/nfts.md`](docs/nfts.md)                                                     | NFTs and tokens, with and without the project's authority                                   |
 | [`docs/harnesses.md`](docs/harnesses.md)                                           | how the plugin reaches Claude Code and Codex, and the release checklist                     |

package/bin/xsolana.mjs

@@ -3,6 +3,7 @@
 // the same answer, for an agent (or a person) without MCP.
 //
 //   xsolana mcp                          serve the tools over stdio (what a plugin's MCP config runs)
+//   xsolana mcp --http [--port n] [--host h]   serve the hosted tools over HTTP at /mcp (127.0.0.1:8787 by default)
 //   xsolana guide [part] [--json]        what an economy can be made of, and what loot cannot do
 //   xsolana examples [words…] [--json]   the nearest worked examples and rated economies
 //   xsolana check|simulate|cost|explain|review|publish|status [file] [--json]   one tool on a spec file (default xsolana.json)
@@ -31,6 +32,7 @@ const USAGE = `xsolana: the tools for loot, one shared Solana program for game a
   xsolana status [file]           a live economy on chain
   xsolana connect                 add the xsolana tools to Claude Code or Codex (--agent claude|codex, --scope user|project, --local, --remove, --dry-run)
   xsolana mcp                     serve the tools over MCP (stdio)
+  xsolana mcp --http              serve the hosted tools over HTTP at http://127.0.0.1:8787/mcp (--port n, --host h)
   xsolana tool --list             every tool; xsolana tool <name> '<json>' runs one (--args-file f)
   xsolana version                 this package's xsolana version and program
 
@@ -41,11 +43,11 @@ const USAGE = `xsolana: the tools for loot, one shared Solana program for game a
 class UsageError extends Error {}
 
 /** The flags that take a value: `--name value` or `--name=value`. */
-const VALUED = new Set(['--args-file', '--agent', '--scope', '--port']);
+const VALUED = new Set(['--args-file', '--agent', '--scope', '--port', '--host']);
 /** The flags each command takes; any other is refused. */
 const TOOL_FLAGS = ['--json'];
 const FLAGS = {
-  mcp: [],
+  mcp: ['--http', '--port', '--host'],
   guide: TOOL_FLAGS,
   examples: TOOL_FLAGS,
   check: TOOL_FLAGS,
@@ -119,6 +121,12 @@ async function main(argv) {
 
   switch (command) {
     case 'mcp': {
+      if (flags.has('--http')) {
+        const { serveHttp } = await import('../js/mcp/http.mjs');
+        await serveHttp({ port: portOf(values.get('--port')) ?? 8787, host: values.get('--host') ?? '127.0.0.1' });
+        break;
+      }
+      if (flags.has('--port') || flags.has('--host')) throw new UsageError('--port and --host go with --http.');
       const { serveStdio } = await import('../js/mcp/server.mjs');
       await serveStdio();
       break;

package/js/client/index.js

@@ -7,4 +7,5 @@ export * from './sizes.js';
 export * from './policy.js';
 export * from './compressed.js';
 export * from './traits.js';
+export * from './kit.js';
 export * as random from './random.js';

package/js/client/kit.js

@@ -0,0 +1,36 @@
+// Instructions in @solana/kit's shape. The builders here return { programId, keys, data } (the shape of
+// @solana/web3.js 1.x, which js/chain/tx.js compiles); an app built on @solana/kit takes { programAddress, accounts,
+// data } instead, with each account's role as a number. These convert one to the other, with no dependency on Kit.
+
+/** @solana/kit's AccountRole: bit 1 is a signer, bit 0 is writable. */
+export const KIT_ACCOUNT_ROLE = Object.freeze({ READONLY: 0, WRITABLE: 1, READONLY_SIGNER: 2, WRITABLE_SIGNER: 3 });
+
+/**
+ * One instruction from a builder here, as @solana/kit takes it: `appendTransactionMessageInstruction(toKitInstruction(ix), m)`.
+ * @param {{ programId: string, keys: { pubkey: string, isSigner: boolean, isWritable: boolean }[], data: Uint8Array }} ix
+ * @returns {{ programAddress: string, accounts: { address: string, role: number }[], data: Uint8Array }}
+ */
+export function toKitInstruction(ix) {
+  return {
+    programAddress: ix.programId,
+    accounts: ix.keys.map(k => ({ address: k.pubkey, role: (k.isSigner ? 2 : 0) | (k.isWritable ? 1 : 0) })),
+    data: ix.data,
+  };
+}
+
+/**
+ * A @solana/kit instruction in the shape this package's transactions take (js/chain/tx.js, js/play).
+ * @param {{ programAddress: string, accounts?: { address: string, role: number }[], data?: Uint8Array }} ix
+ * @returns {{ programId: string, keys: { pubkey: string, isSigner: boolean, isWritable: boolean }[], data: Uint8Array }}
+ */
+export function fromKitInstruction(ix) {
+  return {
+    programId: ix.programAddress,
+    keys: (ix.accounts ?? []).map(a => ({
+      pubkey: a.address,
+      isSigner: (a.role & 2) !== 0,
+      isWritable: (a.role & 1) !== 0,
+    })),
+    data: ix.data ?? new Uint8Array(),
+  };
+}

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,7 +6,7 @@
 //
 // 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.',
@@ -14,6 +14,27 @@ export const INSTRUCTIONS = [
   `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

@@ -69,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 {
@@ -141,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)) {
@@ -591,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)
@@ -683,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,',
@@ -704,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,