@xgamesfun/solana 0.0.0-stage → 0.20.1

package/js/economy/txsize.mjs

@@ -0,0 +1,45 @@
+// How many bytes a Solana transaction takes, from what is in it, without building it. Pure.
+//
+// A legacy transaction is: the signatures (a count, then 64 bytes each), a 3-byte header, the account keys (a
+// count, then 32 bytes each, every account once), a 32-byte blockhash, and the instructions (a count, then for
+// each: its program's index, a count and one byte per account, a length and the data). Counts are compact-u16
+// (1 byte below 128, 2 below 16,384).
+//
+// Why the estimate never comes out smaller than the real transaction:
+// - accounts are counted once per distinct name, and two names never stand for one address less often than the
+//   real transaction would share them (two names for one address only makes the real one smaller);
+// - instruction data is sized byte for byte from the program's IDL (idl.mjs), and other programs' data from their
+//   documented layouts at its longest;
+// - no address lookup tables are assumed.
+// A wallet may add its own compute-budget instructions (a price and a limit: about 52 bytes), so the plan keeps
+// WALLET_ROOM free below the network's 1,232-byte limit.
+
+export const MAX_TRANSACTION_BYTES = 1232;
+export const WALLET_ROOM = 64;
+export const BUDGET = MAX_TRANSACTION_BYTES - WALLET_ROOM;
+
+export const compact = (n) => (n < 0x80 ? 1 : n < 0x4000 ? 2 : 3);
+
+/**
+ * instructions: [{ program: name, accounts: [names], data: bytes }]; signers: [names] (the fee payer first).
+ * Returns the estimated wire size in bytes.
+ */
+export function transactionSize({ instructions, signers }) {
+  const keys = new Set(signers);
+  for (const ix of instructions) {
+    for (const a of ix.accounts) keys.add(a);
+    keys.add(`program:${ix.program}`);
+  }
+  const body = instructions.reduce((n, ix) => n + 1 + compact(ix.accounts.length) + ix.accounts.length + compact(ix.data) + ix.data, 0);
+  return compact(signers.length) + 64 * signers.length + 3 + compact(keys.size) + 32 * keys.size + 32 + compact(instructions.length) + body;
+}
+
+/** How many accounts the transaction locks: each account once, its programs and signers included. */
+export function transactionLocks({ instructions, signers }) {
+  const keys = new Set(signers);
+  for (const ix of instructions) {
+    for (const a of ix.accounts) keys.add(a);
+    keys.add(`program:${ix.program}`);
+  }
+  return keys.size;
+}

package/js/economy/validate.mjs

@@ -0,0 +1,85 @@
+// A small JSON Schema validator for the keywords schema.json uses, so the kit needs no schema library: type, const,
+// enum, pattern, minimum, maximum, exclusiveMinimum, minLength, maxLength, minItems, maxItems, uniqueItems, items,
+// required, properties, additionalProperties, propertyNames, anyOf, oneOf, not and local $ref. Pure.
+import { readFileSync } from 'node:fs';
+
+export const SCHEMA = JSON.parse(readFileSync(new URL('./schema.json', import.meta.url), 'utf8'));
+
+const typeOf = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : Number.isInteger(v) ? 'integer' : typeof v);
+const isType = (v, t) => t === typeOf(v) || (t === 'number' && typeof v === 'number' && Number.isFinite(v));
+const show = (v) => JSON.stringify(v)?.slice(0, 60);
+/** "a" or "an", as the word after it takes: "an object", "an array", "a string". */
+const article = (word) => (/^[aeiou]/.test(word) ? `an ${word}` : `a ${word}`);
+/** A value as text with its objects' keys in order, so two equal values read the same (for uniqueItems). */
+const canonical = (v) => JSON.stringify(v, (_, x) => (x && typeof x === 'object' && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : x));
+
+function resolve(root, ref) {
+  if (!ref.startsWith('#/')) throw new Error(`Only local $ref is supported: ${ref}`);
+  return ref.slice(2).split('/').reduce((node, key) => node?.[key], root);
+}
+
+/** Every way `value` breaks `schema`, as { path, message }. An empty list means it is valid. */
+export function validate(value, schema = SCHEMA, root = schema, path = 'economy') {
+  const errors = [];
+  const add = (message) => errors.push({ path, message });
+  if (schema.$ref) return validate(value, resolve(root, schema.$ref), root, path);
+  if (schema.anyOf) {
+    const results = schema.anyOf.map((s) => validate(value, s, root, path));
+    if (!results.some((r) => r.length === 0)) {
+      const wanted = schema.description ?? results.flat().map((e) => e.message).join('; or ');
+      add(`${show(value)} is not allowed here (${wanted})`);
+    }
+    return errors;
+  }
+  // Exactly one of the shapes: none is not allowed, and two at once would be read two ways.
+  if (schema.oneOf) {
+    const results = schema.oneOf.map((s) => validate(value, s, root, path));
+    const fits = results.filter((r) => r.length === 0).length;
+    if (fits !== 1) {
+      const wanted = schema.description ?? results.flat().map((e) => e.message).join('; or ');
+      add(`${show(value)} is not allowed here (${fits ? 'it fits more than one of its forms: ' : ''}${wanted})`);
+    }
+    return errors;
+  }
+  if (schema.not && validate(value, schema.not, root, path).length === 0) add(`${show(value)} is not allowed here`);
+  if ('const' in schema && value !== schema.const) add(`must be ${show(schema.const)}`);
+  if (schema.enum && !schema.enum.includes(value)) add(`must be one of ${schema.enum.map(show).join(', ')}`);
+  if (schema.type && !isType(value, schema.type)) {
+    add(`must be ${schema.type === 'integer' ? 'a whole number' : article(schema.type)}`);
+    return errors;
+  }
+  if (typeof value === 'string') {
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) add(`${show(value)} is not in the expected form`);
+    if (schema.minLength !== undefined && value.length < schema.minLength) add(`must have at least ${schema.minLength} characters`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) add(`must have at most ${schema.maxLength} characters`);
+  }
+  if (typeof value === 'number') {
+    if (schema.minimum !== undefined && value < schema.minimum) add(`must be at least ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) add(`must be at most ${schema.maximum}`);
+    if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) add(`must be more than ${schema.exclusiveMinimum}`);
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) add(`needs at least ${schema.minItems}`);
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) add(`can have at most ${schema.maxItems}`);
+    if (schema.uniqueItems) {
+      const seen = new Map();
+      value.forEach((v, i) => {
+        const text = canonical(v);
+        if (seen.has(text)) errors.push({ path: `${path}[${i}]`, message: `is the same as ${path}[${seen.get(text)}]: each is listed once` });
+        else seen.set(text, i);
+      });
+    }
+    if (schema.items) value.forEach((v, i) => errors.push(...validate(v, schema.items, root, `${path}[${i}]`)));
+  }
+  if (typeOf(value) === 'object') {
+    for (const key of schema.required ?? []) if (!(key in value)) add(`needs "${key}"`);
+    for (const [key, v] of Object.entries(value)) {
+      const where = `${path}.${key}`;
+      if (schema.propertyNames?.pattern && !new RegExp(schema.propertyNames.pattern).test(key)) errors.push({ path: where, message: 'is not a name this place takes' });
+      if (schema.properties && key in schema.properties) errors.push(...validate(v, schema.properties[key], root, where));
+      else if (schema.additionalProperties === false) errors.push({ path: where, message: 'is not a field this place takes' });
+      else if (typeOf(schema.additionalProperties) === 'object') errors.push(...validate(v, schema.additionalProperties, root, where));
+    }
+  }
+  return errors;
+}

package/js/index.js

@@ -0,0 +1,10 @@
+// @xgamesfun/solana: the economy tools (Node). The client is '@xgamesfun/solana/client' (browser-safe).
+export { check, describe } from './economy/check.mjs';
+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 { model } from './economy/model.mjs';
+export { prepare, recordLanded, changedParts } from './economy/live.mjs';
+export { guideText, catalog, CANNOT } from './economy/guide.mjs';
+export { tools, PROGRAM_INFO, VERSION } from './mcp/tools.mjs';

package/js/mcp/server.mjs

@@ -0,0 +1,113 @@
+// The xsolana MCP server (stdio): the tools in tools.mjs for any agent that speaks MCP (Claude Code, Codex, Cursor,
+// opencode, Cline). It has no dependencies, so `npx -y --package=@xgamesfun/solana@<version> xsolana mcp` starts in the
+// time an agent allows for it on a first install: MCP over stdio is newline-delimited JSON-RPC 2.0, and arguments are checked against each tool's
+// input schema with the economy's own validator (js/economy/validate.mjs), here and on the terminal path
+// (`xsolana tool`), with the same words. Answers go out as text and as structuredContent.
+//
+// stdout is the protocol: everything else goes to stderr.
+import { validate } from '../economy/validate.mjs';
+import { PROGRAM_INFO, 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).',
+  `Program ${PROGRAM_INFO.program} on ${PROGRAM_INFO.cluster} (loot ${VERSION}). Devnet only until audited.`,
+].join(' ');
+
+/**
+ * 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).
+ */
+export const PROTOCOLS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+
+/** Every way `input` does not fit a tool's input schema, in words; [] when it fits. */
+export function inputProblems(schema, input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return ['arguments must be an object'];
+  return validate(input, schema, schema, 'arguments').map((e) => `${e.path} ${e.message}`);
+}
+
+/** Runs one tool by name: the same checks and answer on the server and in the terminal. */
+export async function runTool(name, input = {}, ctx = {}) {
+  const tool = tools.find((t) => t.name === name);
+  if (!tool) {
+    const near = tools.filter((t) => t.name.includes(String(name).replace(/^xsolana_/, ''))).map((t) => t.name);
+    return { isError: true, text: `No tool ${name}.${near.length ? ` Did you mean ${near.join(', ')}?` : ''} Tools: ${tools.map((t) => t.name).join(', ')}.` };
+  }
+  const bad = inputProblems(tool.inputSchema, input);
+  if (bad.length) return { isError: true, text: bad.join('; ') };
+  try {
+    return await tool.handler(input, ctx);
+  } catch (e) {
+    return { isError: true, text: e.message };
+  }
+}
+
+const jsonable = (value) => JSON.parse(JSON.stringify(value, (_, v) => (typeof v === 'bigint' ? v.toString() : v instanceof Uint8Array ? Buffer.from(v).toString('hex') : v)));
+
+/** The answer to one JSON-RPC request, or null for a notification. */
+export async function handle(message, ctx = {}) {
+  const { id, method, params } = message ?? {};
+  const reply = (result) => (id === undefined ? null : { jsonrpc: '2.0', id, result });
+  const fail = (code, text) => (id === undefined ? null : { jsonrpc: '2.0', id, error: { code, message: text } });
+  switch (method) {
+    case 'initialize': {
+      const asked = params?.protocolVersion;
+      return reply({ protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0], capabilities: { tools: {} }, serverInfo: { name: 'xsolana', version: VERSION }, 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 })) });
+    case 'tools/call': {
+      const result = await runTool(params?.name, params?.arguments ?? {}, { ...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({ ...(isError ? { isError: true } : {}), content: [{ type: 'text', text }], structuredContent: { text, ...data } });
+    }
+    default:
+      if (method?.startsWith('notifications/')) return null;
+      return fail(-32601, `No method ${method}.`);
+  }
+}
+
+/**
+ * Serves the tools over stdio until stdin closes. Once it closes, every request already read is answered before
+ * `exit` runs, so a client that sends its last request and closes still gets the reply.
+ */
+export async function serveStdio({ input = process.stdin, output = process.stdout, exit = () => process.exit(0) } = {}) {
+  console.log = (...a) => console.error(...a);
+  console.info = (...a) => console.error(...a);
+  let buffer = '';
+  const write = (m) => m && output.write(`${JSON.stringify(m)}\n`);
+  // The requests read and not yet answered.
+  const pending = new Set();
+  input.setEncoding('utf8');
+  input.on('data', (chunk) => {
+    buffer += chunk;
+    let at;
+    while ((at = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, at).trim();
+      buffer = buffer.slice(at + 1);
+      if (!line) continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Not JSON.' } });
+        continue;
+      }
+      for (const m of Array.isArray(message) ? message : [message]) {
+        const done = handle(m)
+          .then(write, (e) => write({ jsonrpc: '2.0', id: m?.id ?? null, error: { code: -32603, message: e.message } }))
+          .finally(() => pending.delete(done));
+        pending.add(done);
+      }
+    }
+  });
+  input.on('end', async () => {
+    while (pending.size) await Promise.allSettled([...pending]);
+    // (the last reply is written out before the process goes)
+    output.write('', () => exit());
+  });
+  console.error(`xsolana MCP server ${VERSION}: ${tools.length} tools (${tools.map((t) => t.name).join(', ')})`);
+}