@xgamesfun/solana 0.28.0 → 0.28.2

package/js/client/pda.js

@@ -3,9 +3,22 @@
 import { addressBytes } from '../chain/base58.js';
 import { intLE, utf8, uintLE } from '../chain/bytes.js';
 import { associatedTokenAddress, findProgramAddress, MPL_CORE_PROGRAM, TOKEN_PROGRAM } from '../chain/pda.js';
-import IDL from './idl/loot.js';
+import { lootProgram } from './cluster.js';
 
-export const LOOT_PROGRAM = IDL.address;
+// loot's program on this process's cluster (`cluster.js`): devnet unless the process names mainnet.
+export {
+  checkOnCluster,
+  CLUSTERS,
+  cluster,
+  clusterRpcUrl,
+  LOOT_PROGRAM,
+  lootProgram,
+  networkOf,
+  realMoney,
+  scopeClusters,
+  useCluster,
+  walletChain,
+} from './cluster.js';
 /** MagicBlock's VRF program and its default queue, the only queue the program accepts. */
 export const VRF_PROGRAM = 'Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz';
 export const VRF_QUEUE = 'Cuj97ggrhhidhbu39TijNVqE74xvKJ69gDervRUXAxGh';
@@ -25,7 +38,7 @@ const u64 = n => uintLE(n, 8);
 const i64 = n => intLE(n, 8);
 
 /** The PDA of these seeds under the loot program, with its bump. */
-export const lootAddress = (seeds, program = LOOT_PROGRAM) => findProgramAddress(seeds, program);
+export const lootAddress = (seeds, program = lootProgram()) => findProgramAddress(seeds, program);
 const at = (...seeds) => lootAddress(seeds)[0];
 
 export const pda = {
@@ -104,9 +117,9 @@ export const pda = {
   /** The program's identity, which signs its requests to the oracle. */
   identity: () => at(seed('identity')),
   /** The identity the oracle signs callbacks with: the VRF program's PDA for this program. */
-  oracleIdentity: () => findProgramAddress([seed('identity'), key(LOOT_PROGRAM)], VRF_PROGRAM)[0],
+  oracleIdentity: () => findProgramAddress([seed('identity'), key(lootProgram())], VRF_PROGRAM)[0],
   /** The program's ProgramData account (its upgrade authority signs `init_platform`). */
-  programData: () => findProgramAddress([key(LOOT_PROGRAM)], BPF_LOADER_UPGRADEABLE)[0],
+  programData: () => findProgramAddress([key(lootProgram())], BPF_LOADER_UPGRADEABLE)[0],
 };
 
 /** `owner`'s associated token account of `mint` (owner may be a PDA: a project's vault, a pool is not one). */

package/js/economy/check.mjs

@@ -8,7 +8,7 @@ import IDL from '../client/idl/loot.js';
 import { gateList } from '../client/grant.js';
 import { MAX_BID_NFTS, MAX_SHARES } from '../client/ix.js';
 import { MAX_POTS } from '../client/accounts.js';
-import { vault } from '../client/pda.js';
+import { cluster, CLUSTERS, networkOf, realMoney, useCluster, vault } from '../client/pda.js';
 import { ASSUMED_TRIES, boxBytes, buyFits, drawsFit, MAX_ORDER_BYTES, tableBudget } from '../client/sizes.js';
 import { TOKEN_2022_PROGRAM, TOKEN_PROGRAM } from '../chain/pda.js';
 import { addressBytes, encodeBase58 } from '../chain/base58.js';
@@ -693,10 +693,7 @@ export function dateWords(seconds) {
  * (`ASSUMED_TRIES`).
  * Returns { ok, refusals: [{ code, where, message, fix }], warnings: [{ code, where, message, fix? }] }.
  */
-export function check(
-  economy,
-  { network = 'devnet', now = Math.floor(Date.now() / 1000), project = economy?.live?.project ?? null } = {},
-) {
+export function check(economy, { now = Math.floor(Date.now() / 1000), project = economy?.live?.project ?? null } = {}) {
   const refusals = [];
   const warnings = [];
   const refuse = (code, where, message, fix) => refusals.push({ code, where, message, fix });
@@ -717,13 +714,27 @@ export function check(
       `The economy names ${STAND_IN_OWNER}, the address the setup plan stands in for your wallet before one connects. Nobody holds its key: whatever is sent there is lost.`,
       'Name a real wallet there.',
     );
-  if (network !== 'devnet' || (economy?.network && economy.network !== 'devnet'))
+  // The economy's cluster: the network it names, devnet when it names none. This process works on one cluster, and
+  // the first economy it checks names it when nothing did before.
+  const named = networkOf(economy);
+  if (!Object.hasOwn(CLUSTERS, named))
     refuse(
       'E-NETWORK',
       'economy.network',
-      `The economy names the network “${economy?.network ?? network}”. loot runs on devnet only: mainnet waits for an audit.`,
-      'Set the network to "devnet".',
+      `The economy names the network “${named}”. loot runs on ${Object.keys(CLUSTERS).join(' and on ')}.`,
+      'Set the network to "devnet", or to "mainnet".',
     );
+  else
+    try {
+      useCluster(named);
+    } catch {
+      refuse(
+        'E-NETWORK',
+        'economy.network',
+        `The economy is on ${named}, and this process works on ${cluster()}: one process works on one cluster.`,
+        `Run it where the cluster is ${named}: the xsolana command takes the cluster from the file, and a server or a script is started with XSOLANA_CLUSTER=${named}.`,
+      );
+    }
   const oldVersion = economy?.version === 1;
   if (oldVersion)
     refuse(
@@ -4925,7 +4936,9 @@ export function check(
         'W-REVENUE-SHARE',
         where,
         `${label(f)} pays stakers a share of what players spend (${revenue.map(x => x.by).join(', ')}). Paying holders out of a project’s revenue is what regulators look at when they decide whether a token is a security.`,
-        'Fine on devnet. Before mainnet, ask counsel, or reward stakers from emissions (a schedule that mints a game token) rather than from sales.',
+        realMoney()
+          ? 'This economy is on mainnet, where that is real money: ask counsel first, or reward stakers from emissions (a schedule that mints a game token) rather than from sales.'
+          : 'Fine on devnet. Before mainnet, ask counsel, or reward stakers from emissions (a schedule that mints a game token) rather than from sales.',
       );
   }
 
@@ -5030,7 +5043,9 @@ export function check(
         'W-TOKEN-SALE',
         `${where}.prize`,
         `${label(c)} sells ${sold.symbol ?? sold.key} for ${tok.symbol ?? tok.key}: each backer pays in and takes a share of the tokens by what they put in. Selling a token to raise money is what securities law looks at first, and many places limit who may buy.`,
-        'Fine on devnet. Before mainnet, ask counsel.',
+        realMoney()
+          ? 'This economy is on mainnet, where that is real money: ask counsel first.'
+          : 'Fine on devnet. Before mainnet, ask counsel.',
       );
     // One NFT, the last units of an item, a pool's prize: the winning entries share it in the order they are claimed.
     const scarce =
@@ -5119,7 +5134,7 @@ export function check(
       warn(
         'W-CHANCE-PRIZE',
         where,
-        `${label(c)} lets players put money on an outcome: that is betting, which is regulated in most places once it is real money (state rules on prediction markets are in flux). loot runs on devnet only.`,
+        `${label(c)} lets players put money on an outcome: that is betting, which is regulated in most places once it is real money (state rules on prediction markets are in flux). ${realMoney() ? 'This economy is on mainnet: it is real money.' : 'This economy is on devnet, which is not real money.'}`,
         'Before mainnet: counsel, an age and region gate, and a name that does not call it an investment.',
       );
   }
@@ -5688,14 +5703,14 @@ export function check(
     warn(
       'W-CHANCE-ITEMS',
       'economy',
-      'Players pay for a random collectible they can resell (a loot box or gacha). Some places treat paid loot boxes of tradeable items as gambling, and many require the odds to be shown. loot runs on devnet only; before mainnet, counsel and an age and region gate.',
+      `Players pay for a random collectible they can resell (a loot box or gacha). Some places treat paid loot boxes of tradeable items as gambling, and many require the odds to be shown. ${realMoney() ? 'This economy is on mainnet, so it is real money: counsel and an age and region gate come first.' : 'This economy is on devnet; before mainnet, counsel and an age and region gate.'}`,
       'Tell the person in plain words: paid random items that can be resold may count as gambling in some places; show the odds on the page, and get a lawyer before real money.',
     );
   if (chance)
     warn(
       'W-CHANCE-PRIZE',
       'economy',
-      'Players pay for a chance at money (a box that pays a prize, a lottery). That is gambling in many places once it is real money, and paid packs with a cash buyback are drawing lawsuits. loot runs on devnet only; before mainnet, counsel and an age and region gate.',
+      `Players pay for a chance at money (a box that pays a prize, a lottery). That is gambling in many places once it is real money, and paid packs with a cash buyback are drawing lawsuits. ${realMoney() ? 'This economy is on mainnet, so it is real money: counsel and an age and region gate come first.' : 'This economy is on devnet; before mainnet, counsel and an age and region gate.'}`,
       'Tell the person this in plain words before they go live: paying for a chance at money is gambling in many places, so before real money they need a lawyer and an age and region gate.',
     );
 

package/js/economy/explain.mjs

@@ -28,6 +28,7 @@ import {
 import { farmEnds, playSteps } from './plan.mjs';
 import { TRUST_WORDS } from './trust.mjs';
 import { inAll, poolFate, round, simulate, unnamedExceptions, unnamedWords } from './simulate.mjs';
+import { realMoney } from '../client/cluster.js';
 
 const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 const num = x => (Number.isFinite(x) ? String(round(x, 6)) : String(x));
@@ -613,7 +614,7 @@ export function explainEconomy(economy, { now = Math.floor(Date.now() / 1000) }
   );
   lines.push(
     '',
-    'Devnet only: nothing here is real money. Going live is signed on your own machine by the project’s key file, which is what “your wallet” means above. The command first prints everything it would send and sends nothing; it sends only when run again with the code it printed, which your agent is told to do only after your yes. No seed phrase or wallet key is ever asked for.',
+    `${realMoney() ? 'This economy is on mainnet: what it takes and what it pays is real money, and loot has not been independently audited.' : 'This economy is on devnet: nothing here is real money.'} Going live is signed on your own machine by the project’s key file, which is what “your wallet” means above. The command first prints everything it would send and sends nothing; it sends only when run again with the code it printed, which your agent is told to do only after your yes. No seed phrase or wallet key is ever asked for.`,
   );
   return {
     ok: true,

package/js/economy/guide.mjs

@@ -123,7 +123,7 @@ export const CONVENTIONS = [
   'A box, a shop item and a recipe take `opens` and `closes` (times), and `perWallet` (in all) and `perWalletEach` ({ "count": 1, "every": "1d" }) to limit each wallet.',
   'Leave out `id`, `index`, `shopBox` and `live`: they are written when the economy goes live.',
   'Public data only. A spec never holds a private key or a seed phrase (the checker refuses one, E-SECRET).',
-  'Devnet only: "network": "devnet".',
+  '"network" is "devnet" (what a file that names none is on: nothing there is real money) or "mainnet" (real money). loot has an address of its own on each, and an economy is on one: build and try it on devnet first.',
 ];
 
 /**
@@ -252,8 +252,10 @@ export const CANNOT = [
   {
     what: 'mainnet',
     words: 'mainnet real money production',
-    why: 'the program isn’t audited yet',
-    nearest: ['devnet now; mainnet after the audit'],
+    why: 'loot runs on mainnet, with real money, and has not been independently audited; an economy is on devnet unless its file says "network": "mainnet"',
+    nearest: [
+      'try it on devnet first, then set "network": "mainnet" in a copy of the file and go live again with real SOL',
+    ],
   },
 ];
 
@@ -431,7 +433,7 @@ export function guideText(only) {
   return [
     only
       ? `The part “${only}” of a loot economy (* = required):`
-      : `A loot economy is one JSON spec (xsolana.json) on the shared loot program ${IDL.metadata.version}, devnet only. Nobody writes a contract: the spec is checked, simulated, and put live on the owner’s own machine, signed by the project’s key file once they have said yes. Its parts (* = required field):`,
+      : `A loot economy is one JSON spec (xsolana.json) on the shared loot program ${IDL.metadata.version}, on devnet or on mainnet (its "network"; devnet when it names none). Nobody writes a contract: the spec is checked, simulated, and put live on the owner’s own machine, signed by the project’s key file once they have said yes. Its parts (* = required field):`,
     ...parts.flatMap(p => [
       `\n${p.part} (${p.type}): ${p.says}${p.atPlayTime ? `\n  At play time: ${p.atPlayTime}.` : ''}`,
       ...p.fields.map(fieldLine),

package/js/economy/live.mjs

@@ -2,7 +2,7 @@
 // the approval page (js/approve) has the owner's wallet sign, and the full simulation sends them to a local chain.
 import { encodeBase58 } from '../chain/base58.js';
 import { randomBytes } from '../chain/bytes.js';
-import { LOOT_PROGRAM } from '../client/pda.js';
+import { lootProgram } from '../client/pda.js';
 import { compressedTree, listOf, model, tokenLabels } from './model.mjs';
 import { auctionSeller, plan, setupContext } from './plan.mjs';
 
@@ -95,7 +95,7 @@ export function recordLanded(economy, { ctx, signatures = [], at = new Date().to
   };
   const { live: _, previous: __, ...published } = out;
   out.live = {
-    program: LOOT_PROGRAM,
+    program: lootProgram(),
     project: ctx.project,
     // A project made with no collection (`"collection": false`) has none to write: the schema takes an address only.
     ...(ctx.collection ? { collection: ctx.collection } : {}),

package/js/economy/plan.mjs

@@ -1649,7 +1649,7 @@ const TABLE_GROUP = 24;
  */
 export function standingAddresses(m) {
   const fixed = [
-    loot.LOOT_PROGRAM,
+    loot.lootProgram(),
     loot.pda.platform(),
     loot.pda.identity(),
     loot.VRF_PROGRAM,
@@ -1892,8 +1892,8 @@ export const SETUP_UNIT_PRICE = 1n;
 /**
  * A setup transaction's instructions as the owner's wallet is handed them: led by a compute unit limit and a compute
  * unit price, each once. A wallet that adds its own priority fee (Phantom does) adds it only to a transaction that
- * sets neither, and the approval page sends a transaction only as it prepared it, so every setup transaction sets both
- * itself. The limit is all a transaction can have (1,400,000 units): nothing here measures what a step takes, a box's
+ * sets neither, and the approval page takes no price a wallet puts on a transaction that has one, so every setup
+ * transaction sets both itself: its fee is the plan's own, whatever the wallet. The limit is all a transaction can have (1,400,000 units): nothing here measures what a step takes, a box's
  * write needs it, and no step may fail for want of compute. A limit or a price the instructions already carry is
  * kept.
  */

package/js/economy/schema.json

@@ -12,8 +12,8 @@
       "description": "The spec format: 2 is loot 0.7 and later."
     },
     "network": {
-      "const": "devnet",
-      "description": "Devnet only until the program is audited."
+      "enum": ["devnet", "mainnet"],
+      "description": "The cluster the economy is on: devnet when it names none. loot has an address of its own on each."
     },
     "name": {
       "type": "string",

package/js/mcp/server.mjs

@@ -5,13 +5,20 @@
 // (`xsolana tool`), with the same words. Answers go out as text and as structuredContent.
 //
 // stdout is the protocol: everything else goes to stderr.
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { validate } from '../economy/validate.mjs';
-import { PACKAGE_VERSION, PROGRAM_INFO, REMOTE_TOOLS, tools, VERSION } from './tools.mjs';
+import { CLUSTERS, cluster, networkOf } from '../client/cluster.js';
+import { PACKAGE_VERSION, REMOTE_TOOLS, tools, VERSION } from './tools.mjs';
+import { withCluster } from './with-cluster.mjs';
+
+/** Where loot runs, for every agent that connects. */
+const WHERE = `loot ${VERSION} runs on devnet (program ${CLUSTERS.devnet.program}) and on mainnet (program ${CLUSTERS.mainnet.program}). An economy is on devnet, where nothing is real money, unless its file says "network": "mainnet", where everything is. Build and try an economy on devnet first. loot has not been independently audited.`;
 
 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_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. Going live is signed by a key file on their own machine (xsolana keygen makes one; never ask for, read or print a key) with xsolana approve --keypair, which prints everything it would send and sends nothing until it is run again with the code it printed: do that only after they have read the printout and said yes. That key owns the project for good: a change to an economy that is already live is signed by the key that owns it, never by a new one. A browser wallet’s signing page (approve --browser) only if they ask for one, and they run it themselves.',
-  `Program ${PROGRAM_INFO.program} on ${PROGRAM_INFO.cluster} (loot ${VERSION}). Devnet only until audited.`,
+  WHERE,
 ].join(' ');
 
 /**
@@ -22,7 +29,7 @@ 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, the spec goes in a file named xsolana.json on the person’s own computer and is signed there by a key file. In that folder: npx -y @xgamesfun/solana@${PACKAGE_VERSION} keygen ~/.config/xsolana/<name>.json makes the key file (it prints the address, never the key; the person sends that address devnet SOL), then npx -y @xgamesfun/solana@${PACKAGE_VERSION} approve xsolana.json --keypair <that file> prints everything that would be sent and sends nothing. When the person has read that and said yes, the same command with --yes <the code it printed> sends it. Run them yourself if you have a terminal there; otherwise hand them to the person. Never ask for, read or print a key. Say once what the key file is: the project’s owner for good (whoever can read it controls the project; they back it up themselves; nothing restores a lost one) and, unless the spec names a treasury, where what the economy earns lands. A change to an economy that is already live is signed by the key that owns it: never make a new key for it. A browser wallet’s signing page (the same approve command with --browser in place of --keypair), which the person runs themselves, only if they ask for one or a browser wallet owns the project. (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.`,
+  WHERE,
 ].join(' ');
 
 /** A tool as tools/list shows it; on a hosted server, without the `file` argument it can't take. */
@@ -67,12 +74,36 @@ export async function runTool(name, input = {}, ctx = {}) {
   const bad = inputProblems(tool.inputSchema, input);
   if (bad.length) return { isError: true, text: bad.join('; ') };
   try {
-    return await tool.handler(input, ctx);
+    // Each tool runs on the cluster of the economy it is given, so one server answers for devnet and mainnet alike.
+    return await withCluster(await clusterOfInput(input, ctx), () => tool.handler(input, ctx));
   } catch (e) {
     return { isError: true, text: e.message };
   }
 }
 
+/**
+ * The cluster a tool's call is for: the "network" of the economy it is given (passed whole as `spec`, or read from its
+ * `file`, which is xsolana.json when none is named), devnet when the economy names none. With no economy to read (no
+ * file there, a file that is not JSON, a tool that takes none) or a network loot does not know, it is the server's
+ * own cluster, and the tool says what is wrong in its own words.
+ */
+async function clusterOfInput(input, ctx) {
+  let economy = input?.spec && typeof input.spec === 'object' ? input.spec : null;
+  if (!economy && !ctx.remote) {
+    try {
+      const file = path.resolve(
+        ctx.cwd ?? process.cwd(),
+        typeof input?.file === 'string' ? input.file : 'xsolana.json',
+      );
+      economy = JSON.parse(await readFile(file, 'utf8'));
+    } catch {
+      economy = null;
+    }
+  }
+  const named = economy && typeof economy === 'object' ? networkOf(economy) : null;
+  return named && Object.hasOwn(CLUSTERS, named) ? named : cluster();
+}
+
 const jsonable = value =>
   JSON.parse(
     JSON.stringify(value, (_, v) =>