@xgamesfun/solana 0.28.1 → 0.28.3

package/js/client/cluster.js

@@ -0,0 +1,136 @@
+// The cluster the client works on, and loot's address there. loot has an address of its own on each cluster, so what
+// is signed for one (a voucher, a verdict) never counts on the other, and every address this client derives, every
+// instruction it builds and everything it signs follows the cluster's address.
+//
+// A process works on one cluster. It is devnet unless the process names another: the environment variable
+// XSOLANA_CLUSTER, or `useCluster` before anything is derived or built. Once an address has been derived the
+// cluster is settled, and naming another is refused: addresses of two clusters never mix by accident.
+//
+// A server that answers for both clusters gives each piece of work its own: `withCluster` (js/mcp/with-cluster.mjs, Node)
+// runs a function, and everything it awaits, on the cluster named; inside it the client is on that cluster whatever
+// the process's own is. Browser-safe.
+import { checkCluster, rightCluster } from '../chain/rpc.js';
+import IDL from './idl/loot.js';
+
+/**
+ * Each cluster: loot's program there (devnet's is the IDL's own address), the chain as a wallet names it (Wallet
+ * Standard), and the RPC used when none is given. Mainnet has none: its public RPC refuses or limits what loot reads
+ * (a program's accounts, a compressed NFT's proof), so a mainnet RPC is always named (XSOLANA_RPC_URL, or `rpcUrl`).
+ */
+export const CLUSTERS = Object.freeze({
+  devnet: Object.freeze({ program: IDL.address, chain: 'solana:devnet', rpc: 'https://api.devnet.solana.com' }),
+  mainnet: Object.freeze({
+    program: 'xgames8C758PyweWB9sDw8evvwsTVwyA2fGRUeAXVPy',
+    chain: 'solana:mainnet',
+    rpc: null,
+  }),
+});
+
+const known = name => {
+  if (!Object.hasOwn(CLUSTERS, name))
+    throw new Error(`"${name}" is not a cluster loot knows: ${Object.keys(CLUSTERS).join(' or ')}.`);
+  return name;
+};
+
+const fromEnv = globalThis.process?.env?.XSOLANA_CLUSTER?.trim() || null;
+let name = known(fromEnv ?? 'devnet');
+// Settled: named by the environment or by `useCluster`, or already used to derive an address.
+let settled = Boolean(fromEnv);
+// The cluster of the work being done now, when a server gives each piece of work its own (`scopeClusters`).
+let scoped = null;
+const within = () => {
+  const cluster = scoped?.();
+  return cluster ? known(cluster) : null;
+};
+
+/**
+ * loot's program on this process's own cluster. A live binding: it follows `useCluster`. It knows nothing of
+ * `withCluster`: code that may run for either cluster asks `lootProgram()`, as the client itself does.
+ * @type {string}
+ */
+export let LOOT_PROGRAM = CLUSTERS[name].program;
+
+/**
+ * For a server's own set-up (js/mcp/with-cluster.mjs does it): `current()` answers the cluster of the work being done now,
+ * or nothing outside any. While it answers one, the client is on that cluster.
+ * @param {(() => string | undefined | null) | null} current
+ */
+export function scopeClusters(current) {
+  scoped = current;
+}
+
+/**
+ * Names the cluster this process works on (`devnet` or `mainnet`) and returns it. Call it first, before any address
+ * is derived: it throws when the process already works on another cluster. Inside `withCluster` it names nothing: it
+ * throws unless the cluster named is the one that work is on.
+ * @param {'devnet' | 'mainnet'} cluster
+ * @returns {'devnet' | 'mainnet'}
+ */
+export function useCluster(cluster) {
+  known(cluster);
+  const here = within();
+  if (here) {
+    if (cluster !== here) throw new Error(`This is being done on ${here}; it can't also be done on ${cluster}.`);
+    return here;
+  }
+  if (cluster !== name) {
+    if (settled)
+      throw new Error(
+        `This process already works on ${name}; it can't also work on ${cluster}. Start one for ${cluster} (XSOLANA_CLUSTER=${cluster}).`,
+      );
+    name = cluster;
+    LOOT_PROGRAM = CLUSTERS[name].program;
+  }
+  settled = true;
+  return name;
+}
+
+/**
+ * The cluster the client works on now: inside `withCluster` that work's, else the process's own (asking settles it).
+ * @returns {'devnet' | 'mainnet'}
+ */
+export function cluster() {
+  const here = within();
+  if (here) return here;
+  settled = true;
+  return name;
+}
+
+/**
+ * loot's program on the cluster the client works on now (`cluster()`): what derives an address, builds an
+ * instruction or reads who owns an account calls this.
+ * @returns {string}
+ */
+export function lootProgram() {
+  return CLUSTERS[cluster()].program;
+}
+
+/** Whether the client works on mainnet now: what is paid and won there is real money. */
+export const realMoney = () => cluster() === 'mainnet';
+
+// The tests' own switch, set by js/test/on-mainnet.mjs before a run of the whole suite on mainnet's address and by
+// nothing else: the tests' economies, which say devnet or name no network, are then read as mainnet's.
+const TEST_NETWORK = Symbol.for('xsolana.test.network');
+
+/** The cluster an economy is on: the `network` its file names, devnet when it names none. */
+export const networkOf = economy => globalThis[TEST_NETWORK] ?? economy?.network ?? 'devnet';
+
+/**
+ * The RPC URL this process reads and sends through: the one given, else XSOLANA_RPC_URL, else the cluster's own
+ * (devnet's public RPC; mainnet has none). A URL that names another cluster is refused.
+ */
+export function clusterRpcUrl(url = globalThis.process?.env?.XSOLANA_RPC_URL || null) {
+  const on = cluster();
+  const chosen = url || CLUSTERS[on].rpc;
+  if (!chosen)
+    throw new Error(
+      `No RPC for ${on}: name one (XSOLANA_RPC_URL, or rpcUrl). ${on === 'mainnet' ? 'Mainnet’s public RPC does not serve what loot reads, so there is no default.' : ''}`.trim(),
+    );
+  return rightCluster(chosen, on);
+}
+
+/** Refuses a chain that is not this process's cluster, by its genesis block (`rpc.js`, `checkCluster`). */
+export const checkOnCluster = rpc => checkCluster(rpc, cluster());
+
+/** This process's cluster as a wallet names it (Wallet Standard): `solana:devnet` or `solana:mainnet`. */
+export const walletChain = () => CLUSTERS[cluster()].chain;

package/js/client/grant.js

@@ -20,7 +20,7 @@ import { meta } from '../chain/programs.js';
 import { sha256 } from '../chain/sha256.js';
 import { recordKey16 } from './accounts.js';
 import { ASSOCIATED_TOKEN_PROGRAM, gateAccounts, lootIx, prizeMetas, prizeNonce, shownFor, tailOf } from './ix.js';
-import { LOOT_PROGRAM, pda } from './pda.js';
+import { lootProgram, pda } from './pda.js';
 import IDL from './idl/loot.js';
 
 export const VOUCHER_DOMAIN = 'loot-grant-v5';
@@ -74,7 +74,7 @@ const roundsOf = (rounds, round, amount) =>
 
 /** A voucher's body, which its key signs the sha256 of (`voucherBytes`). */
 export function voucherBody({
-  program = LOOT_PROGRAM,
+  program = lootProgram(),
   grant,
   incarnation,
   wallet,

package/js/client/ix.js

@@ -67,7 +67,7 @@ import {
   ata,
   BUBBLEGUM_PROGRAM,
   COMPRESSION_PROGRAM,
-  LOOT_PROGRAM,
+  lootProgram,
   MPL_CORE_PROGRAM,
   NOOP_PROGRAM,
   pda,
@@ -204,7 +204,7 @@ export function lootIx(
       if (a.pda && !a.pda.program) {
         const seeds = a.pda.seeds.map(s => seedBytes(s, known, args, def));
         if (seeds.every(Boolean)) {
-          known[a.name] = findProgramAddress(seeds, LOOT_PROGRAM)[0];
+          known[a.name] = findProgramAddress(seeds, lootProgram())[0];
           progress = true;
         }
       }
@@ -215,13 +215,13 @@ export function lootIx(
     const key = known[a.name];
     if (key === null || (key === undefined && a.optional)) {
       if (!a.optional) throw new Error(`${name}: ${a.name} is not optional`);
-      return meta(LOOT_PROGRAM, false, false);
+      return meta(lootProgram(), false, false);
     }
     if (key === undefined) throw new Error(`${name}: missing account ${a.group ? `${a.group}.` : ''}${a.name}`);
     const isWritable = (a.writable === true || writable.includes(a.name)) && !readonly.includes(a.name);
     return meta(key, a.signer === true || signer.includes(a.name), isWritable);
   });
-  return { programId: LOOT_PROGRAM, keys: [...keys, ...remaining], data: encodeInstruction(IDL, name, args) };
+  return { programId: lootProgram(), keys: [...keys, ...remaining], data: encodeInstruction(IDL, name, args) };
 }
 
 // ---------------------------------------------------------------- the accounts after an instruction's own
@@ -548,7 +548,7 @@ const PIECE = leaves(instructionDef('hold').accounts).filter(a => a.group === 'p
 function pieceMetas(p) {
   return PIECE.map(a => {
     const key = p.accounts[a.name];
-    if (key == null) return meta(LOOT_PROGRAM, false, false);
+    if (key == null) return meta(lootProgram(), false, false);
     return meta(key, false, a.writable === true || p.writable.includes(a.name));
   });
 }
@@ -1302,7 +1302,7 @@ export function callbackRollIx({
     );
   keys.push(...tailOf(extra));
   return {
-    programId: LOOT_PROGRAM,
+    programId: lootProgram(),
     keys,
     data: encodeInstruction(IDL, 'callback_roll', { randomness: Uint8Array.from(randomness) }),
   };
@@ -1643,7 +1643,7 @@ function orderPiece(project, orderAddress, order, subject = {}, receiver) {
  * own address, a record, a stash, a fee box), where nothing could move it again. A settle's fate and an NFT lottery
  * ticket's price take it as `handBack`.
  */
-export const handsBack = account => account?.owner === LOOT_PROGRAM;
+export const handsBack = account => account?.owner === lootProgram();
 
 /** Where an NFT that is burned but can't be (any kind but Core) is sent: an address nobody holds the key to. */
 export const INCINERATOR = '1nc1nerator11111111111111111111111111111111';
@@ -2079,7 +2079,7 @@ export const VERDICT_DOMAIN = 'loot-verdict-v4';
  * the contest it was signed for, never one opened later at the same id. `decide` rebuilds them from its own accounts
  * and arguments.
  */
-export function verdictBytes({ program = LOOT_PROGRAM, contest, incarnation, side, expires, recipient = null }) {
+export function verdictBytes({ program = lootProgram(), contest, incarnation, side, expires, recipient = null }) {
   if (incarnation == null) throw new Error('A verdict signs the contest’s incarnation (the decoded Contest’s).');
   const named = recipient == null ? new Uint8Array(0) : addressBytes(recipient);
   return concat(
@@ -2169,7 +2169,7 @@ export const rollIx = ({ authority, project, reference: ref }) =>
 
 /** The oracle's answer to a `roll` (for a local simulation). */
 export const callbackRandomIx = ({ project, reference: ref, randomness }) => ({
-  programId: LOOT_PROGRAM,
+  programId: lootProgram(),
   keys: [
     meta(pda.oracleIdentity(), true, false),
     meta(project, false, false),
@@ -2373,7 +2373,7 @@ export function drawLotteryIx({
 
 /** The oracle's answer to a round's draw (for a local simulation): the round's record is its only account. */
 export const callbackLotteryIx = ({ round, randomness }) => ({
-  programId: LOOT_PROGRAM,
+  programId: lootProgram(),
   keys: [meta(pda.oracleIdentity(), true, false), meta(round, false, true)],
   data: encodeInstruction(IDL, 'callback_lottery', { randomness: Uint8Array.from(randomness) }),
 });
@@ -3053,7 +3053,7 @@ export function anotherMetas(p) {
   const writable = new Set([...p.writable, ...PIECE.filter(a => a.writable).map(a => a.name)]);
   return [
     ...ANOTHER[p.kind].map(name =>
-      p.accounts[name] == null ? meta(LOOT_PROGRAM, false, false) : meta(p.accounts[name], false, writable.has(name)),
+      p.accounts[name] == null ? meta(lootProgram(), false, false) : meta(p.accounts[name], false, writable.has(name)),
     ),
     ...p.proof,
   ];
@@ -3310,7 +3310,7 @@ export const closeLeafIx = ({ asset, tree, payer, signs = true }) =>
 
 const PROVE_LEAF = leaves(instructionDef('prove_leaf').accounts).map(a => a.name);
 const CLOSE_LEAF = leaves(instructionDef('close_leaf').accounts).map(a => a.name);
-const isLoot = (ix, name) => ix.programId === LOOT_PROGRAM && instructionOf(ix.data)?.name === name;
+const isLoot = (ix, name) => ix.programId === lootProgram() && instructionOf(ix.data)?.name === name;
 
 /**
  * `instructions` with a `close_leaf` after them for each compressed NFT's record a `prove_leaf` among them makes, its
@@ -3469,8 +3469,8 @@ function nftSeat({
 const seatGroup = (seat, p, box = null, order = null) => [
   meta(seat, false, true),
   ...anotherMetas({ ...p, proof: [] }),
-  meta(box ?? LOOT_PROGRAM, false, false),
-  meta(order ?? LOOT_PROGRAM, false, Boolean(order)),
+  meta(box ?? lootProgram(), false, false),
+  meta(order ?? lootProgram(), false, Boolean(order)),
   ...p.proof,
 ];
 
@@ -3653,8 +3653,8 @@ export const harvestIx = ({
   );
   const groups = rest.flatMap(x => [
     meta(x.seat, false, true),
-    meta(x.held ?? LOOT_PROGRAM, false, false),
-    meta(x.tree ?? LOOT_PROGRAM, false, false),
+    meta(x.held ?? lootProgram(), false, false),
+    meta(x.tree ?? lootProgram(), false, false),
   ]);
   return lootIx(
     'harvest',

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,

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) =>