@xgamesfun/solana 0.24.0 → 0.25.1

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/economy/txsize.mjs

@@ -18,7 +18,7 @@ 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);
+export const compact = n => (n < 0x80 ? 1 : n < 0x4000 ? 2 : 3);
 
 /**
  * instructions: [{ program: name, accounts: [names], data: bytes }]; signers: [names] (the fee payer first).
@@ -30,8 +30,20 @@ export function transactionSize({ instructions, signers }) {
     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;
+  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. */

package/js/economy/validate.mjs

@@ -5,41 +5,67 @@ 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 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);
+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}`);
+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));
+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);
+  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 });
+  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 ');
+    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.
+  // Exactly one of the shapes: none is not allowed, and two at once would be read two ways. Shapes that only name a
+  // field each (`required`) are one choice among fields of an object, whose other keywords still apply.
   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})`);
+    const fields = schema.oneOf.every(s => Object.keys(s).length === 1 && s.required?.length === 1)
+      ? schema.oneOf.map(s => s.required[0])
+      : null;
+    const results = schema.oneOf.map(s => validate(value, s, root, path));
+    const fits = results.filter(r => r.length === 0).length;
+    if (fields && typeOf(value) === 'object') {
+      if (fits !== 1) add(`needs exactly one of ${fields.map(f => `"${f}"`).join(' or ')}${fits ? ', not both' : ''}`);
+    } else {
+      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;
     }
-    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)}`);
@@ -50,13 +76,16 @@ export function validate(value, schema = SCHEMA, root = schema, path = 'economy'
   }
   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 (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 (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}`);
@@ -65,7 +94,11 @@ export function validate(value, schema = SCHEMA, root = schema, path = 'economy'
       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` });
+        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);
       });
     }
@@ -75,10 +108,14 @@ export function validate(value, schema = SCHEMA, root = schema, path = 'economy'
     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));
+      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

@@ -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/server.mjs

@@ -10,7 +10,7 @@ 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).',
+  '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(' ');
 
@@ -23,15 +23,18 @@ 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}`);
+  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);
+  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 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('; ') };
@@ -42,27 +45,48 @@ export async function runTool(name, input = {}, ctx = {}) {
   }
 }
 
-const jsonable = (value) => JSON.parse(JSON.stringify(value, (_, v) => (typeof v === 'bigint' ? v.toString() : v instanceof Uint8Array ? Buffer.from(v).toString('hex') : v)));
+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 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 });
+      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 })) });
+      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 } });
+      return reply({
+        ...(isError ? { isError: true } : {}),
+        content: [{ type: 'text', text }],
+        structuredContent: { text, ...data },
+      });
     }
     default:
       if (method?.startsWith('notifications/')) return null;
@@ -74,15 +98,19 @@ export async function handle(message, ctx = {}) {
  * 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) } = {}) {
+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`);
+  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) => {
+  input.on('data', chunk => {
     buffer += chunk;
     let at;
     while ((at = buffer.indexOf('\n')) >= 0) {
@@ -98,7 +126,7 @@ export async function serveStdio({ input = process.stdin, output = process.stdou
       }
       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 } }))
+          .then(write, e => write({ jsonrpc: '2.0', id: m?.id ?? null, error: { code: -32603, message: e.message } }))
           .finally(() => pending.delete(done));
         pending.add(done);
       }
@@ -109,5 +137,5 @@ export async function serveStdio({ input = process.stdin, output = process.stdou
     // (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(', ')})`);
+  console.error(`xsolana MCP server ${VERSION}: ${tools.length} tools (${tools.map(t => t.name).join(', ')})`);
 }