@xgamesfun/solana 0.28.0 → 0.28.2

package/js/approve/wallet-adds.mjs

@@ -0,0 +1,180 @@
+// What a wallet may add to a transaction it was asked to sign as it stood, and nothing else.
+//
+// The approval page prepares each transaction, shows what it does, and sends what the wallet signed. Some wallets add
+// to a transaction before they sign it: Phantom adds its own checks (instructions of the Lighthouse program, which
+// read accounts and fail the transaction when something is not as the wallet expected). The page takes such a
+// transaction only when everything that was prepared and shown is still in it, untouched, and everything else is of
+// the two programs a wallet adds for its own sake: Compute Budget and Lighthouse. Then what is sent is the wallet's
+// own message with the wallet's own signature. Anything else is refused, as any change was before.
+//
+// The rule, each part of which is needed:
+// - Both messages are legacy, with no lookup table: every account is in the message itself, so every account is
+//   compared by its address.
+// - The wallet is the message's one signer and its fee payer, in both. A transaction a fresh key signs too (a new
+//   mint, a new collection) can't be changed: that key signed the prepared message.
+// - The same blockhash.
+// - Every prepared instruction is there, in the prepared order, with the same program, the same accounts and the
+//   same data.
+// - Every account a prepared instruction names (its program too) is a signer or writable in the wallet's message
+//   exactly as it was in the prepared one. Whether an account can be written is the message's word, not one
+//   instruction's: an added instruction that asks to write an account of ours would make it writable for ours too.
+// - Every other instruction is the Lighthouse program's, or a Compute Budget instruction that asks for a heap size
+//   or a limit on loaded data the prepared transaction does not set. Never a unit limit or a unit price: the fee of a
+//   prepared transaction is the one it was shown with.
+// - Nothing added names the loader of upgradeable programs, which would let a program's own account be written.
+import { equalBytes } from '../chain/bytes.js';
+import { COMPUTE_BUDGET_PROGRAM, LIGHTHOUSE_PROGRAM } from '../chain/pda.js';
+import { readMessage } from '../chain/tx.js';
+
+/** What a Compute Budget instruction asks for, by its first byte. */
+const BUDGET_ASKS = {
+  1: 'a heap size',
+  2: 'a compute unit limit',
+  3: 'a compute unit price (a priority fee of its own)',
+  4: 'a limit on the account data loaded',
+};
+
+/** The kinds that set a transaction's fee: its unit limit and its unit price. */
+const FEE_KINDS = new Set([2, 3]);
+/** The loader of upgradeable programs: named anywhere in a transaction, it lets a program's own account be written. */
+const UPGRADEABLE_LOADER = 'BPFLoaderUpgradeab1e11111111111111111111111';
+
+/** A refusal of a wallet's message: `why`, in words that go after "it …". */
+class Refused extends Error {}
+
+/**
+ * A legacy message's accounts and instructions with nothing left as a number:
+ * { blockhash, signers, flags (address → { signer, writable }), instructions: [{ program, accounts: [address], data }] }.
+ * Throws `Refused` for a message that is not legacy, that names an account twice, or whose own numbers do not add up.
+ */
+function laidOut(message) {
+  let m;
+  try {
+    m = readMessage(message);
+  } catch {
+    throw new Refused('returned something that is not a transaction');
+  }
+  if (m.version !== 'legacy' || m.lookups.length)
+    throw new Refused('returned a transaction that loads accounts from a lookup table, which can’t be compared');
+  const { numRequiredSignatures: signed, numReadonlySigned, numReadonlyUnsigned } = m.header;
+  const count = m.keys.length;
+  if (signed < 1 || signed > count || numReadonlySigned >= signed || numReadonlyUnsigned > count - signed)
+    throw new Refused('returned a transaction whose header does not add up');
+  if (new Set(m.keys).size !== count) throw new Refused('returned a transaction that names an account twice');
+  const flags = new Map(
+    m.keys.map((address, i) => [
+      address,
+      {
+        signer: i < signed,
+        writable: i < signed - numReadonlySigned || (i >= signed && i < count - numReadonlyUnsigned),
+      },
+    ]),
+  );
+  const at = i => {
+    if (i >= count) throw new Refused('returned a transaction that names an account it does not list');
+    return m.keys[i];
+  };
+  return {
+    blockhash: m.blockhash,
+    signers: m.keys.slice(0, signed),
+    flags,
+    instructions: m.instructions.map(ix => ({
+      program: at(ix.programIndex),
+      accounts: ix.accountIndexes.map(at),
+      data: ix.data,
+    })),
+  };
+}
+
+const sameInstruction = (a, b) =>
+  a.program === b.program &&
+  a.accounts.length === b.accounts.length &&
+  a.accounts.every((address, i) => address === b.accounts[i]) &&
+  equalBytes(a.data, b.data);
+
+/**
+ * Whether `theirs`, the message a wallet signed, is `ours`, the message prepared for it, with nothing but a wallet's
+ * own additions. `wallet`: the address the transaction was prepared for.
+ * → { ok: true, added: [what it added, in words] } or { ok: false, why: what it did, in words after "it …" }.
+ * Two messages that are the same bytes are not this function's to judge (nothing was added).
+ */
+export function walletAdded(ours, theirs, wallet) {
+  try {
+    // (the prepared message is this package's own: one this can't lay out is one a wallet may not change)
+    let a;
+    try {
+      a = laidOut(ours);
+    } catch {
+      throw new Refused('changed a transaction that can only be sent as it was prepared');
+    }
+    const b = laidOut(theirs);
+    if (a.signers.length !== 1 || a.signers[0] !== wallet)
+      throw new Refused(
+        'changed a transaction that another key signs too (a new account’s own key signed it as it was prepared)',
+      );
+    if (b.signers.length !== 1) throw new Refused('added a signer');
+    if (b.signers[0] !== wallet) throw new Refused('put another fee payer on it');
+    if (a.blockhash !== b.blockhash) throw new Refused('put another blockhash on it');
+
+    // Every prepared instruction, in its order; whatever stands between them is what the wallet added.
+    const added = [];
+    let next = 0;
+    for (const ix of b.instructions) {
+      if (next < a.instructions.length && sameInstruction(ix, a.instructions[next])) next++;
+      else added.push(ix);
+    }
+    if (next !== a.instructions.length) throw new Refused('changed, dropped or moved one of the prepared instructions');
+    if (!added.length) throw new Refused('changed the transaction’s accounts');
+
+    // No account of ours is more, or less, than it was: a signer, or writable.
+    const mine = new Set(a.instructions.flatMap(ix => [ix.program, ...ix.accounts]));
+    for (const address of mine) {
+      const was = a.flags.get(address);
+      const is = b.flags.get(address);
+      if (!is || was.signer !== is.signer || was.writable !== is.writable)
+        throw new Refused(
+          `changed what the account ${address} is in the transaction (${was.writable ? 'it could be written, and no longer can' : 'it could only be read, and can now be written'})`,
+        );
+    }
+
+    // The network lets a program's own account be written only in a transaction that names the upgradeable loader:
+    // without it, an account that is called as a program is read-only whatever the message says. So the loader, named
+    // by anything added, would change what a prepared instruction can write. It is never the wallet's to add.
+    if (b.flags.has(UPGRADEABLE_LOADER) && !a.flags.has(UPGRADEABLE_LOADER))
+      throw new Refused('named the upgradeable loader, which the prepared transaction does not');
+
+    // What it added is a wallet's own: instructions of the Lighthouse program, or a heap size or a limit on loaded
+    // data the transaction did not set. Never a unit limit or a unit price: a prepared transaction's fee is its own
+    // (this package's setups set both), and a wallet's price on top of it is not taken.
+    const set = new Set(
+      a.instructions.filter(ix => ix.program === COMPUTE_BUDGET_PROGRAM).map(ix => (ix.data.length ? ix.data[0] : -1)),
+    );
+    const words = [];
+    let own = 0;
+    for (const ix of added) {
+      if (ix.program === LIGHTHOUSE_PROGRAM) {
+        own++;
+        continue;
+      }
+      if (ix.program !== COMPUTE_BUDGET_PROGRAM) throw new Refused(`added an instruction of the program ${ix.program}`);
+      const kind = ix.data.length ? ix.data[0] : -1;
+      const what = BUDGET_ASKS[kind];
+      if (!what) throw new Refused('added a compute budget instruction of a kind not known here');
+      if (ix.accounts.length)
+        throw new Refused('added a compute budget instruction that names accounts, which none does');
+      if (set.has(kind))
+        throw new Refused(
+          `added ${what.replace(/^a /, 'a second ')}: the transaction sets its own, and the network refuses one that sets it twice`,
+        );
+      if (FEE_KINDS.has(kind))
+        throw new Refused(`added ${what}: the fee of a transaction prepared here is the one it was shown with`);
+      set.add(kind);
+      words.push(what);
+    }
+    if (own) words.push(`${own} instruction${own === 1 ? '' : 's'} of the Lighthouse program (a wallet’s own checks)`);
+    return { ok: true, added: words };
+  } catch (e) {
+    if (!(e instanceof Refused)) throw e;
+    return { ok: false, why: e.message };
+  }
+}

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/pda.js

@@ -10,6 +10,12 @@ export const TOKEN_PROGRAM = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
 export const TOKEN_2022_PROGRAM = 'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb';
 export const ASSOCIATED_TOKEN_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
 export const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111';
+/**
+ * Lighthouse: a program of assertions (it reads accounts and fails the transaction when one is not as expected),
+ * which a wallet may add to a transaction before signing it (Phantom does). The same address on mainnet and devnet:
+ * its source's `declare_id!` and its README, github.com/Jac0xb/lighthouse.
+ */
+export const LIGHTHOUSE_PROGRAM = 'L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95';
 export const METAPLEX_METADATA_PROGRAM = 'metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s';
 /** Metaplex Core: the program of Core assets and collections. */
 export const MPL_CORE_PROGRAM = 'CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d';

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 {

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',