@xgamesfun/solana 0.28.1 → 0.28.3

package/DISCLAIMER.md

@@ -19,7 +19,9 @@ Read this before you use this package, its tools or the loot program. Using them
   wallets, token and NFT programs, npm and any results server. Any of them can fail, change or stop.
 - The public results server (`https://play.xgames.fun/xsolana`) is offered as is, may change or stop at any time, and
   carries no promise of uptime or of what it vouches for.
-- **Devnet only.** Nothing here is meant for real money until the program has been independently audited.
+- **Mainnet is real money, and the program has not been independently audited.** loot runs on devnet, where nothing
+  has value, and on mainnet, where everything does. An economy is on devnet unless its file says
+  `"network": "mainnet"`. What is sent to the program on mainnet can be lost, and you use it there at your own risk.
 
 ## Use it legally
 

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm](https://img.shields.io/npm/v/@xgamesfun/solana?color=b9f26c&label=npm)](https://www.npmjs.com/package/@xgamesfun/solana)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
-[![network](https://img.shields.io/badge/network-devnet-orange)](#good-to-know)
+[![network](https://img.shields.io/badge/network-devnet%20%7C%20mainnet-orange)](#good-to-know)
 [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.XGamesFun%2Fsolana--kit-8a2be2)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.XGamesFun/solana-kit)
 
 You describe your game's or community's economy in a small JSON file: what players buy, open, stake, win or craft.
@@ -15,8 +15,9 @@ write, deploy or audit yourself.
 Most people never touch the JSON: they ask an AI agent (Claude Code, Codex, Cursor, ChatGPT or Claude) for _"a fishing
 game where each cast costs 0.02 SOL, with a rare golden fish and a monthly draw"_ and the agent does the rest.
 
-> **Devnet only for now.** The program is not yet independently audited, so nothing here is for real money. The
-> tools are provided as is: read [DISCLAIMER.md](DISCLAIMER.md) before you use them.
+> **On devnet and on mainnet.** An economy runs on devnet, where nothing is real money, unless its file says
+> `"network": "mainnet"`, where everything is. The program is not independently audited and the tools are provided as
+> is: read [DISCLAIMER.md](DISCLAIMER.md) before you use them, and before real money above all.
 
 ## What you can build
 
@@ -76,7 +77,7 @@ codex plugin add xsolana@xgamesfun
 
 **claude.ai, ChatGPT or Claude Desktop:** add `https://xgames.fun/mcp` as a custom connector. Nothing to install.
 
-**Cursor, Cline, opencode or any MCP client:** run `npx -y --package=@xgamesfun/solana@0.28.1 xsolana mcp`.
+**Cursor, Cline, opencode or any MCP client:** run `npx -y --package=@xgamesfun/solana@0.28.3 xsolana mcp`.
 
 **Any agent that reads skills** (Copilot, Gemini CLI, Windsurf…): `npx skills add XGamesFun/solana-kit`.
 
@@ -87,26 +88,26 @@ are in [docs/harnesses.md](docs/harnesses.md).
 
 ```bash
 # find a worked example close to your idea
-npx -y @xgamesfun/solana@0.28.1 examples shop with loot boxes
+npx -y @xgamesfun/solana@0.28.3 examples shop with loot boxes
 
 # using a coin you already launched? read it from the chain into its "tokens" entry
-npx -y @xgamesfun/solana@0.28.1 token <its mint address>
+npx -y @xgamesfun/solana@0.28.3 token <its mint address>
 
 # does it work? where does the money go? what does it cost?
-npx -y @xgamesfun/solana@0.28.1 check xsolana.json
-npx -y @xgamesfun/solana@0.28.1 simulate xsolana.json
-npx -y @xgamesfun/solana@0.28.1 cost xsolana.json
+npx -y @xgamesfun/solana@0.28.3 check xsolana.json
+npx -y @xgamesfun/solana@0.28.3 simulate xsolana.json
+npx -y @xgamesfun/solana@0.28.3 cost xsolana.json
 
 # the whole economy in plain words, and what a cheater could get
-npx -y @xgamesfun/solana@0.28.1 explain xsolana.json
-npx -y @xgamesfun/solana@0.28.1 review xsolana.json
+npx -y @xgamesfun/solana@0.28.3 explain xsolana.json
+npx -y @xgamesfun/solana@0.28.3 review xsolana.json
 
-# go live: a key file for the project (it prints the address to send devnet SOL to, never the key)…
-npx -y @xgamesfun/solana@0.28.1 keygen ~/.config/xsolana/my-game.json
+# go live: a key file for the project (it prints the address to send SOL to, never the key)…
+npx -y @xgamesfun/solana@0.28.3 keygen ~/.config/xsolana/my-game.json
 # …then everything going live would send, and a code; nothing is sent
-npx -y @xgamesfun/solana@0.28.1 approve xsolana.json --keypair ~/.config/xsolana/my-game.json
+npx -y @xgamesfun/solana@0.28.3 approve xsolana.json --keypair ~/.config/xsolana/my-game.json
 # …and with that code, exactly what it listed is sent
-npx -y @xgamesfun/solana@0.28.1 approve xsolana.json --keypair ~/.config/xsolana/my-game.json --yes <code>
+npx -y @xgamesfun/solana@0.28.3 approve xsolana.json --keypair ~/.config/xsolana/my-game.json --yes <code>
 ```
 
 Each command names an exact version, so you always run the release you meant to. `xsolana help` lists them all.
@@ -149,7 +150,8 @@ Using `@solana/kit`? `loot.toKitInstruction(ix)` turns any builder's instruction
 
 ## Good to know
 
-- **Devnet only, not yet audited.** Mainnet waits for an independent audit.
+- **Devnet and mainnet, not independently audited.** An economy is on devnet unless its file says
+  `"network": "mainnet"`. Mainnet is real money: try everything on devnet first.
 - **Upgrades can mean setting up again.** No program version so far has carried accounts over. Pin the package version.
 - **Players trust the project.** Your keys can mint and move your project's pools. The program protects players from
   each other and from mistakes, not from the project they chose.

package/bin/xsolana.mjs

@@ -141,6 +141,29 @@ async function main(argv) {
 
   const fileInput = () => (positional[0] ? { file: positional[0] } : {});
 
+  /**
+   * Names the cluster this command works on from the economy it is given (a file, or a spec passed whole): its
+   * "network", devnet when it names none. A file that is missing or not JSON, and a network loot does not know, are
+   * left to the tool, which says so in its own words.
+   */
+  async function clusterOf({ file = 'xsolana.json', spec = null } = {}) {
+    const { CLUSTERS, networkOf, useCluster } = await import('../js/client/cluster.js');
+    let network;
+    try {
+      network = networkOf(spec ?? JSON.parse(await readFile(file, 'utf8')));
+    } catch {
+      return;
+    }
+    if (!Object.hasOwn(CLUSTERS, network)) return;
+    try {
+      useCluster(network);
+    } catch {
+      throw new UsageError(
+        `${spec ? 'The economy' : file} is on ${network}, and XSOLANA_CLUSTER says ${process.env.XSOLANA_CLUSTER}: unset it, or change the economy’s "network".`,
+      );
+    }
+  }
+
   switch (command) {
     case 'mcp': {
       if (flags.has('--http')) {
@@ -166,6 +189,7 @@ async function main(argv) {
     case 'review':
     case 'publish':
     case 'status':
+      await clusterOf(fileInput());
       await tool(`xsolana_${command}`, fileInput());
       break;
     case 'token':
@@ -193,13 +217,14 @@ async function main(argv) {
           `A new key is in ${made.file}${process.platform === 'win32' ? '' : ', readable by you alone'}. Its address:`,
           `  ${made.address}`,
           'Whatever is set up with it, it owns, for good: anyone who can read that file controls the project, and every later change is signed by it. Keep the file where it is and never paste it into a chat, a spec, a repository or a page. Back it up yourself (a USB stick, a password manager): if it is lost, nothing can change the project or move what its address holds.',
-          `It holds nothing yet. Send it devnet SOL (\`xsolana cost\` says what going live takes; https://faucet.solana.com gives some), then: npx -y @xgamesfun/solana@${PACKAGE_VERSION} approve xsolana.json --keypair ${word}`,
+          `It holds nothing yet. Send it SOL (\`xsolana cost\` says what going live takes): devnet SOL for an economy on devnet (https://faucet.solana.com gives some), real SOL for one whose file says "network": "mainnet". Then: npx -y @xgamesfun/solana@${PACKAGE_VERSION} approve xsolana.json --keypair ${word}`,
         ].join('\n'),
       );
       break;
     }
     case 'approve': {
       const file = positional[0] ?? 'xsolana.json';
+      await clusterOf({ file });
       const keyFile = values.get('--keypair');
       const page = flags.has('--browser');
       if (keyFile !== undefined && page)
@@ -252,6 +277,7 @@ async function main(argv) {
           { cause: e },
         );
       }
+      if (input && typeof input === 'object' && (input.file !== undefined || input.spec)) await clusterOf(input);
       await tool(positional[0], input);
       break;
     }

package/js/approve/details.mjs

@@ -5,7 +5,7 @@
 import { decodeBorsh } from '../chain/borsh.js';
 import { equalBytes, toHex } from '../chain/bytes.js';
 import { accountKind, decode, IDL, instructionOf, keyLeaf, merkleRoot } from '../client/index.js';
-import { LOOT_PROGRAM, pda } from '../client/pda.js';
+import { lootProgram, pda } from '../client/pda.js';
 import { dateWords, FAR_SECONDS } from '../economy/check.mjs';
 import { fromUnits } from '../economy/model.mjs';
 import { grantArgs } from '../economy/plan.mjs';
@@ -38,7 +38,7 @@ const leafNames = list => list.flatMap(a => (a.accounts ? leafNames(a.accounts)
 
 /** A loot instruction read back: { name, args, accounts: { name: address } }, or null for another program's. */
 function readLootInstruction(ix) {
-  if (ix.programId !== LOOT_PROGRAM) return null;
+  if (ix.programId !== lootProgram()) return null;
   const def = instructionOf(ix.data);
   if (!def) return null;
   const args = {};
@@ -104,7 +104,7 @@ export async function liveStepDetails(instructions, names, chain) {
       reads.push(null);
       continue;
     }
-    if (account.owner !== LOOT_PROGRAM || accountKind(account.data) !== RECORD_ACCOUNT[kind])
+    if (account.owner !== lootProgram() || accountKind(account.data) !== RECORD_ACCOUNT[kind])
       throw new Error(`${read.accounts.target} is not the ${kind.toLowerCase()} it should be.`);
     reads.push({
       ...read,

package/js/approve/live-check.mjs

@@ -10,7 +10,7 @@ import { METADATA_LIMITS, metadataAddress, parseRecord } from '../chain/metadata
 import { parseMint } from '../chain/mint.js';
 import { mintState, powersOf } from '../chain/token2022.js';
 import { accountKind, decode } from '../client/accounts.js';
-import { BUBBLEGUM_PROGRAM, LOOT_PROGRAM, pda } from '../client/pda.js';
+import { BUBBLEGUM_PROGRAM, lootProgram, pda } from '../client/pda.js';
 import { METAPLEX_METADATA_PROGRAM, SYSTEM_PROGRAM } from '../chain/pda.js';
 import { tokenLabels } from '../economy/model.mjs';
 import { madeSoFar } from '../economy/plan.mjs';
@@ -43,7 +43,7 @@ export async function checkLive({ live, m, wallet, chain }) {
   let project = own;
   if (made.project) {
     const account = await read(made.project);
-    if (!account || account.owner !== LOOT_PROGRAM || accountKind(account.data) !== 'Project')
+    if (!account || account.owner !== lootProgram() || accountKind(account.data) !== 'Project')
       throw new LiveMismatch(
         `The file names the project ${made.project}, and there is no loot project at that address.`,
       );

package/js/approve/page.html

@@ -161,7 +161,7 @@
   <body>
     <main>
       <header>
-        <p class="muted mono flush">loot · devnet · runs on your computer only</p>
+        <p class="muted mono flush">loot · <span id="cluster">devnet</span> · runs on your computer only</p>
         <h1 id="title">Approve going live</h1>
         <p class="muted" id="sub">Loading…</p>
       </header>
@@ -173,8 +173,8 @@
         </div>
         <div class="row" id="wallets" hidden></div>
         <p class="muted note">
-          Set the wallet to <b>devnet</b>. Each approval shows you the transactions before you sign; nothing leaves your
-          wallet without it. Nobody else ever sees your key.
+          Set the wallet to <b id="walletcluster">devnet</b>. Each approval shows you the transactions before you sign;
+          nothing leaves your wallet without it. Nobody else ever sees your key.
         </p>
       </section>
 
@@ -202,8 +202,8 @@
         <ul class="warn gap" id="legal" hidden></ul>
         <p class="muted note">The full text is in DISCLAIMER.md, in the package.</p>
         <label class="row gap"
-          ><input type="checkbox" id="legalok" /> I have read this and accept it. Devnet is not real money; real money
-          needs every point above answered first.</label
+          ><input type="checkbox" id="legalok" /> I have read this and accept it.
+          <span id="money">Devnet is not real money; real money needs every point above answered first.</span></label
         >
       </section>
 

package/js/approve/page.js

@@ -5,7 +5,8 @@
 // session's token from its <meta name="xsolana-token"> (the page allows no inline script).
 import { fromBase64, toBase64 } from '/js/chain/bytes.js';
 
-const CHAIN = 'solana:devnet';
+// The cluster of this approval (the economy's own), as the server says it: devnet until the first answer.
+let onCluster = 'devnet';
 const $ = id => document.getElementById(id);
 
 function walletRegistry() {
@@ -65,6 +66,13 @@ export function approvalPage(token) {
   // How many of the lines about what the wallet added have been said on this page.
   let addedSaid = 0;
   function render(state) {
+    onCluster = state.cluster ?? 'devnet';
+    $('cluster').textContent = onCluster;
+    $('walletcluster').textContent = onCluster;
+    $('money').textContent =
+      onCluster === 'mainnet'
+        ? 'This is mainnet: everything sent here is real money, and every point above is yours to have answered first.'
+        : 'Devnet is not real money; real money needs every point above answered first.';
     last = state;
     // What the wallet added to transactions that landed (its own checks): they were sent as it signed them. Said
     // whenever a state arrives, so one that landed in a batch that then stopped is said too.
@@ -84,7 +92,7 @@ export function approvalPage(token) {
     $('sub').textContent = state.done
       ? nothingSent
         ? `The only change in ${state.file} is a token’s name, and it can’t be written on chain: nothing was sent, and the file is as it was. See below.`
-        : `Every step landed on devnet. ${state.file} now holds the project’s addresses: you can close this page.`
+        : `Every step landed on ${state.cluster}. ${state.file} now holds the project’s addresses: you can close this page.`
       : `${state.mode === 'change' ? 'A change to a live economy' : state.mode === 'resume' ? 'A setup that was cut short goes on' : 'A new economy'} from ${state.file}, on the shared loot program ${state.program.slice(0, 6)}…${state.project ? `, in the project ${state.project}${state.wallet ? `, made from your wallet ${state.wallet}` : ''}` : ''}`;
     $('cost').textContent = state.setupSol !== null && state.mode === 'new' ? `about ${state.setupSol} SOL` : '';
     const steps = $('steps');
@@ -205,7 +213,7 @@ export function approvalPage(token) {
     const found = list();
     if (!found.length) {
       log(
-        'No Solana wallet in this browser. Install one (Phantom, Solflare, Backpack), set it to devnet, then reload.',
+        `No Solana wallet in this browser. Install one (Phantom, Solflare, Backpack), set it to ${onCluster}, then reload.`,
         'bad',
       );
       return;
@@ -245,7 +253,11 @@ export function approvalPage(token) {
         `Asking your wallet to approve ${batch.transactions.length} transaction${batch.transactions.length === 1 ? '' : 's'} in the project ${batch.project}: ${batch.says.join(' | ')}${details.length ? `. ${details.join('. ')}` : ''}`,
       );
       const sign = signingWallet.features['solana:signTransaction'];
-      const inputs = batch.transactions.map(t => ({ account: signer, transaction: fromBase64(t), chain: CHAIN }));
+      const inputs = batch.transactions.map(t => ({
+        account: signer,
+        transaction: fromBase64(t),
+        chain: `solana:${onCluster}`,
+      }));
       const outputs = await sign.signTransaction(...inputs);
       const signed = outputs.map(o => toBase64(o.signedTransaction));
       $('status').textContent = 'Sending and confirming…';

package/js/approve/server.mjs

@@ -14,14 +14,14 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
 import { equalBytes, fromBase64, toBase64 } from '../chain/bytes.js';
-import { alreadyProcessed, checkCluster, notMainnet, rpcClient } from '../chain/rpc.js';
+import { alreadyProcessed, rpcClient } from '../chain/rpc.js';
 import { addressBytes, encodeBase58 } from '../chain/base58.js';
 import { slotHashes, tableAddress } from '../chain/lookup.js';
 import { SYSVAR_SLOT_HASHES } from '../chain/pda.js';
 import { MINT_BYTES } from '../chain/token.js';
 import { compileMessage, readTransaction, wireTransaction } from '../chain/tx.js';
 import { accountKind, decode } from '../client/accounts.js';
-import { LOOT_PROGRAM, pda } from '../client/pda.js';
+import { checkOnCluster, cluster, CLUSTERS, clusterRpcUrl, lootProgram, pda } from '../client/pda.js';
 import { check, describe } from '../economy/check.mjs';
 import { cost } from '../economy/cost.mjs';
 import { LEGAL, legalFlags } from '../economy/legal.mjs';
@@ -35,7 +35,6 @@ import { walletAdded } from './wallet-adds.mjs';
 
 const PREPARE_TTL_MS = 90_000;
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const DEVNET = 'https://api.devnet.solana.com';
 
 /** A refusal with the HTTP status the page gets. */
 class ApproveError extends Error {
@@ -46,37 +45,43 @@ class ApproveError extends Error {
 }
 
 /**
- * The chain the approval sends to: devnet by default (XSOLANA_RPC_URL to use another devnet RPC, or a local validator).
- * A mainnet URL is refused at once, and before anything is sent the chain's genesis block is checked: mainnet and
- * testnet are refused whatever the URL says.
+ * The chain the approval sends to: this process's cluster (`client/cluster.js`), through XSOLANA_RPC_URL or, on
+ * devnet, its public RPC (a local validator passes for devnet). A URL that names another cluster is refused at once,
+ * and before anything is sent the chain's genesis block is checked: another cluster is refused whatever the URL says.
  */
-export function devnetChain(url = process.env.XSOLANA_RPC_URL || DEVNET) {
-  const rpc = rpcClient(notMainnet(url));
-  let cluster = null;
+export function clusterChain(url) {
+  // A URL that names another cluster is refused here. With none to use (mainnet has no RPC of its own), the refusal
+  // waits for the first request, so what is wrong with the economy's file is said first.
+  let made = null;
+  const client = () => (made ??= rpcClient(clusterRpcUrl(url)));
+  if (url || process.env.XSOLANA_RPC_URL || CLUSTERS[cluster()].rpc) client();
+  let genesis = null;
   const checked = () =>
-    (cluster ??= checkCluster(rpc).catch(e => {
-      cluster = null;
+    (genesis ??= checkOnCluster(client()).catch(e => {
+      genesis = null;
       throw e;
     }));
   return {
-    url,
+    get url() {
+      return client().url ?? url;
+    },
     latestBlockhash: async () => {
       await checked();
-      return rpc.latestBlockhash();
+      return client().latestBlockhash();
     },
-    rent: async bytes => BigInt(await rpc.call('getMinimumBalanceForRentExemption', [bytes])),
+    rent: async bytes => BigInt(await client().call('getMinimumBalanceForRentExemption', [bytes])),
     send: async wire => {
       await checked();
-      return rpc.send(wire);
+      return client().send(wire);
     },
-    confirm: (signature, options) => rpc.confirm(signature, options),
-    account: address => rpc.account(address),
+    confirm: (signature, options) => client().confirm(signature, options),
+    account: address => client().account(address),
     /** A sent transaction's status from the whole history: { err, confirmationStatus }, or null when unseen. */
     signatureStatus: async signature =>
-      (await rpc.call('getSignatureStatuses', [[signature], { searchTransactionHistory: true }])).value[0],
-    blockHeight: () => rpc.blockHeight(),
+      (await client().call('getSignatureStatuses', [[signature], { searchTransactionHistory: true }])).value[0],
+    blockHeight: () => client().blockHeight(),
     /** The chain's current epoch (a mint's transfer fee changes on one). */
-    epoch: async () => Number((await rpc.call('getEpochInfo')).epoch),
+    epoch: async () => Number((await client().call('getEpochInfo')).epoch),
   };
 }
 
@@ -128,7 +133,7 @@ function walletAddress(wallet) {
  */
 export async function createApproval({
   file,
-  chain = devnetChain(),
+  chain = clusterChain(),
   now = () => Math.floor(Date.now() / 1000),
   clock = Date.now,
   write = writeWhole,
@@ -389,8 +394,8 @@ export async function createApproval({
       name: spec.name ?? path.basename(file),
       file: path.basename(file),
       mode,
-      program: LOOT_PROGRAM,
-      cluster: 'devnet',
+      program: lootProgram(),
+      cluster: cluster(),
       setupSol: cost(spec, { now: at, live: live(), ...scope() }).setup?.totalSol ?? null,
       warnings: [
         ...(extra.refused ? [extra.refused] : []),
@@ -738,7 +743,7 @@ export async function createApproval({
   async function projectOwner(project) {
     if (!project || !chain.account) return null;
     const account = await chain.account(project).catch(() => null);
-    return account && account.owner === LOOT_PROGRAM && accountKind(account.data) === 'Project'
+    return account && account.owner === lootProgram() && accountKind(account.data) === 'Project'
       ? decode('Project', account.data).owner
       : null;
   }
@@ -811,7 +816,7 @@ export async function createApproval({
       }
     const progress = {
       ...was,
-      program: LOOT_PROGRAM,
+      program: lootProgram(),
       ...(made.has('project') ? { project: ctx.project, treasury: ctx.treasury, authority: ctx.authority } : {}),
       ...(made.has('collection') && ctx.collection ? { collection: ctx.collection } : {}),
       ...(made.has('tree') && ctx.tree ? { tree: ctx.tree } : {}),
@@ -1076,7 +1081,7 @@ export async function approve({
   file = 'xsolana.json',
   port,
   open = true,
-  chain = devnetChain(),
+  chain = clusterChain(),
   log = (...a) => console.error(...a),
   openLink = openBrowser,
 } = {}) {

package/js/approve/with-key.mjs

@@ -11,7 +11,8 @@ import path from 'node:path';
 import { fromBase64, toBase64 } from '../chain/bytes.js';
 import { readTransaction, wireTransaction } from '../chain/tx.js';
 import { readKeyFile } from './keyfile.mjs';
-import { createApproval, devnetChain } from './server.mjs';
+import { clusterChain, createApproval } from './server.mjs';
+import { realMoney } from '../client/cluster.js';
 
 /** The notice the page has its owner tick before Approve (js/approve/page.html, "Read this first"), word for word. */
 export const NOTICE = [
@@ -122,7 +123,7 @@ export function approvalText(state, { keyFile, balance = null }) {
   lines.push('', 'Read this first');
   for (const line of [...NOTICE, ...state.legal.map(f => f.says)]) lines.push(`- ${line}`);
   lines.push(
-    'The full text is in DISCLAIMER.md, in the package. Devnet is not real money; real money needs every point above answered first.',
+    `The full text is in DISCLAIMER.md, in the package. ${realMoney() ? 'This is mainnet: everything sent here is real money, and every point above is yours to have answered first.' : 'Devnet is not real money; real money needs every point above answered first.'}`,
   );
 
   if (state.warnings.length) {
@@ -156,7 +157,7 @@ export async function approveWithKey({
   keyFile,
   yes = null,
   confirm = null,
-  chain = devnetChain(),
+  chain = clusterChain(),
   out = line => console.log(line),
   now,
   keyReader = readKeyFile,
@@ -204,7 +205,9 @@ export async function approveWithKey({
     out('');
     if (balance === 0n) {
       out(
-        `Nothing was sent: the key holds no SOL. Send devnet SOL to ${key.address} first (https://faucet.solana.com gives some), then run this again.`,
+        realMoney()
+          ? `Nothing was sent: the key holds no SOL. This economy is on mainnet: send SOL to ${key.address} first, then run this again.`
+          : `Nothing was sent: the key holds no SOL. Send devnet SOL to ${key.address} first (https://faucet.solana.com gives some), then run this again.`,
       );
       return { ok: false, sent: 0, done: false, code };
     }

package/js/chain/borsh.js

@@ -242,9 +242,11 @@ export function isAccount(idl, name, data) {
  * [{ name, data }]. Only lines the program itself printed count: the log names which program each line comes from
  * (`Program <id> invoke [n]` … `success`), and any program can print a line that looks like an event. Logs alone
  * cannot say whether the transaction succeeded (the runtime can fail it after every instruction logged success), so
- * the caller decides that from the transaction's `meta.err` and reads events only when it is null.
+ * the caller decides that from the transaction's `meta.err` and reads events only when it is null. `program` is the
+ * address the program runs at: the IDL's own unless the caller names another (the program has an address of its own on
+ * each cluster, and an IDL holds one).
  */
-export function decodeEvents(idl, logs) {
+export function decodeEvents(idl, logs, program = idl.address) {
   const out = [];
   const stack = [];
   for (const line of logs ?? []) {
@@ -259,7 +261,7 @@ export function decodeEvents(idl, logs) {
       continue;
     }
     const m = /^Program data: (.+)$/.exec(line);
-    if (!m || stack[stack.length - 1] !== idl.address) continue;
+    if (!m || stack[stack.length - 1] !== program) continue;
     let bytes;
     try {
       bytes = fromBase64(m[1]);

package/js/chain/rpc.js

@@ -47,23 +47,39 @@ export const GENESIS = Object.freeze({
   testnet: '4uhcVJyU9pJkvQyS88uRDiswHXSCkY3zQawwpjk2NsNY',
 });
 
-const DEVNET_ONLY =
-  'loot runs on devnet only: mainnet waits for an audit. Unset XSOLANA_RPC_URL, or point it at a devnet RPC.';
+const ON_DEVNET =
+  'This works on devnet (an economy that names no network is on devnet). Unset XSOLANA_RPC_URL, or point it at a devnet RPC.';
+const ON_MAINNET = 'This works on mainnet. Point XSOLANA_RPC_URL at a mainnet RPC.';
 
-/** Refuses an RPC URL that names mainnet. Returns the URL. */
-export function notMainnet(url) {
-  if (/mainnet/i.test(String(url))) throw new RpcError(`${url} is a mainnet RPC. ${DEVNET_ONLY}`);
+/**
+ * Refuses an RPC URL that names another cluster than the one the caller works on (`devnet` or `mainnet`). Returns the
+ * URL. A URL names nothing for certain: `checkCluster` reads the chain itself.
+ */
+export function rightCluster(url, cluster = 'devnet') {
+  const text = String(url);
+  if (cluster === 'mainnet') {
+    if (/devnet|testnet/i.test(text)) throw new RpcError(`${url} is not a mainnet RPC. ${ON_MAINNET}`);
+  } else if (/mainnet/i.test(text)) throw new RpcError(`${url} is a mainnet RPC. ${ON_DEVNET}`);
   return url;
 }
 
+/** Refuses an RPC URL that names mainnet. Returns the URL. */
+export const notMainnet = url => rightCluster(url, 'devnet');
+
 /**
- * Refuses a chain that is mainnet or testnet, by its genesis block, whatever its URL says (a local validator is
- * let through). `rpc` has `call`. Returns the genesis hash.
+ * Refuses a chain that is not the cluster the caller works on, by its genesis block, whatever its URL says. On
+ * devnet, mainnet and testnet are refused and a local validator is let through; on mainnet, only mainnet itself
+ * passes. `rpc` has `call`. Returns the genesis hash.
  */
-export async function checkCluster(rpc) {
+export async function checkCluster(rpc, cluster = 'devnet') {
   const genesis = await rpc.call('getGenesisHash');
-  if (genesis === GENESIS.mainnet) throw new RpcError(`${rpc.url ?? 'This RPC'} is on mainnet. ${DEVNET_ONLY}`);
-  if (genesis === GENESIS.testnet) throw new RpcError(`${rpc.url ?? 'This RPC'} is on testnet. ${DEVNET_ONLY}`);
+  const here = rpc.url ?? 'This RPC';
+  if (cluster === 'mainnet') {
+    if (genesis !== GENESIS.mainnet) throw new RpcError(`${here} is not on mainnet. ${ON_MAINNET}`);
+    return genesis;
+  }
+  if (genesis === GENESIS.mainnet) throw new RpcError(`${here} is on mainnet. ${ON_DEVNET}`);
+  if (genesis === GENESIS.testnet) throw new RpcError(`${here} is on testnet. ${ON_DEVNET}`);
   return genesis;
 }
 const decodeAccount = raw =>

package/js/client/accounts.js

@@ -7,7 +7,7 @@ import { decodeAccount, decodeBorsh, decodeEvents } from '../chain/borsh.js';
 import { compareBytes, concat, readUintLE, toHex, uintLE } from '../chain/bytes.js';
 import { sha256 } from '../chain/sha256.js';
 import { SYSTEM_PROGRAM } from '../chain/pda.js';
-import { LOOT_PROGRAM, pda } from './pda.js';
+import { lootProgram, pda } from './pda.js';
 import IDL from './idl/loot.js';
 
 /** The bytes of one time in a farm's record of ends (`decodeEnds`): rent its writer pays, not refunded when a seat leaves. */
@@ -243,7 +243,7 @@ export function readListAccount(account) {
     !account.executable
   )
     return null;
-  if (account.owner !== LOOT_PROGRAM || account.executable) throw new Error('The list has an invalid owner.');
+  if (account.owner !== lootProgram() || account.executable) throw new Error('The list has an invalid owner.');
   return decodeList(account.data);
 }
 
@@ -855,14 +855,14 @@ export function receipts(tx, err) {
       throw new Error(
         "loot.receipts(logs, err) needs the transaction's meta.err (null when it succeeded): a failed transaction keeps its logs",
       );
-    return err === null ? decodeEvents(IDL, tx) : [];
+    return err === null ? decodeEvents(IDL, tx, lootProgram()) : [];
   }
   const meta = tx?.meta;
   if (!meta || meta.err === undefined)
     throw new Error(
       'loot.receipts(tx) needs the transaction getTransaction returns, with its meta.err and meta.logMessages',
     );
-  return meta.err === null ? decodeEvents(IDL, meta.logMessages ?? []) : [];
+  return meta.err === null ? decodeEvents(IDL, meta.logMessages ?? [], lootProgram()) : [];
 }
 
 /** The program's errors by code: { code: { name, msg } }. */
@@ -886,7 +886,7 @@ export function lootError(logs) {
     }
     const failed = /^Program (\w+) failed: (.*)$/.exec(line);
     if (failed) {
-      if (failed[1] !== LOOT_PROGRAM) return null;
+      if (failed[1] !== lootProgram()) return null;
       const m = /custom program error: 0x([0-9a-f]+)/i.exec(failed[2]);
       const code = m ? parseInt(m[1], 16) : null;
       return code !== null && ERRORS[code] ? { code, ...ERRORS[code] } : null;
@@ -896,7 +896,7 @@ export function lootError(logs) {
       continue;
     }
     // A line that names no program (a log line, or an error's own text) is the running program's, when it is known.
-    if (running.length && running.at(-1) !== LOOT_PROGRAM) continue;
+    if (running.length && running.at(-1) !== lootProgram()) continue;
     const named = /Error Code: (\w+)\. Error Number: (\d+)\. Error Message: (.+?)\.?$/.exec(line);
     if (named)
       return {