@xgamesfun/solana 0.27.1 → 0.27.2

package/js/chain/rpc.js

@@ -2,6 +2,7 @@
 // (devnet: about 100 requests per 10 s per IP, 40 for any one method), so 429s are retried with backoff, and so are a
 // gateway's passing failures (502, 503, 504).
 import { fromBase64, toBase64 } from './bytes.js';
+import { transactionId } from './tx.js';
 
 // The options of a call made without any: read-only, and typed so the generated declarations take any option.
 const NO_OPTIONS = Object.freeze(/** @type {Record<string, any>} */ ({}));
@@ -21,11 +22,19 @@ const BEHIND = [-32005, -32016];
 
 /** A JSON-RPC failure, with the node's own message (and logs for a failed simulation). */
 export class RpcError extends Error {
-  constructor(message, { code, logs } = NO_OPTIONS) {
+  /**
+   * `code`: the node's own error code, when a node answered. `logs`: a failed dry run's program logs. `err`: the
+   * node's own name for why a transaction was refused ("BlockhashNotFound", "AlreadyProcessed", or the program's
+   * error as the chain writes it). `maybeTaken`: a send whose earlier try got no answer, so a node may have taken the
+   * transaction although the last try was refused.
+   */
+  constructor(message, { code, logs, err, maybeTaken } = NO_OPTIONS) {
     super(message);
     this.name = 'RpcError';
     this.code = code;
     this.logs = logs;
+    this.err = err;
+    this.maybeTaken = Boolean(maybeTaken);
   }
 }
 
@@ -72,10 +81,27 @@ export function programError(err, logs) {
   return last ?? (typeof err === 'string' ? err : JSON.stringify(err));
 }
 
+/**
+ * Whether a send was refused because the cluster has this very transaction already (it was sent before): the node's
+ * own word for it (`err`), or, from a node that gives only a sentence, its sentence. Never a program's log line: a
+ * dry run that failed inside a program is that program's refusal, whatever its words.
+ */
+export const alreadyProcessed = error =>
+  error?.err === 'AlreadyProcessed' ||
+  (error?.err === undefined &&
+    !error?.logs?.length &&
+    /this transaction has already been processed/i.test(String(error?.message ?? '')));
+
+/** Whether a send's refusal is the dry run not knowing the transaction's blockhash. */
+const blockhashNotFound = error =>
+  error?.data?.err === 'BlockhashNotFound' || /blockhash not found/i.test(String(error?.message ?? ''));
+
 /** A client for one RPC URL. `fetchImpl` and `sleepImpl` are for tests. */
 export function rpcClient(url, { fetchImpl = globalThis.fetch, sleepImpl = sleep } = {}) {
   let id = 0;
   async function call(method, params = []) {
+    // A try that got no answer (the connection dropped, a gateway failed): a node may have taken what it carried.
+    let unanswered = false;
     for (let attempt = 0; ; attempt++) {
       let response;
       try {
@@ -86,6 +112,7 @@ export function rpcClient(url, { fetchImpl = globalThis.fetch, sleepImpl = sleep
           signal: AbortSignal.timeout(TIMEOUT_MS),
         });
       } catch (error) {
+        unanswered = true;
         if (attempt < RETRIES) {
           await sleepImpl(500 * 2 ** attempt);
           continue;
@@ -98,6 +125,7 @@ export function rpcClient(url, { fetchImpl = globalThis.fetch, sleepImpl = sleep
         continue;
       }
       // Sending the same signed transaction again is safe: it has one signature, so it lands once at most.
+      if (PASSING.includes(response.status)) unanswered = true;
       if (PASSING.includes(response.status) && attempt < RETRIES) {
         await sleepImpl(500 * 2 ** attempt);
         continue;
@@ -115,13 +143,25 @@ export function rpcClient(url, { fetchImpl = globalThis.fetch, sleepImpl = sleep
           await sleepImpl(500 * 2 ** attempt);
           continue;
         }
+        // A send refused in its dry run for a blockhash this node has not seen yet ("Blockhash not found"): the node
+        // that gave the blockhash was a moment ahead of this one. Asked again, it (or another) knows it. A blockhash
+        // that is truly gone is refused the same way each time, and the last refusal is the answer.
+        if (method === 'sendTransaction' && blockhashNotFound(body?.error) && attempt < RETRIES) {
+          await sleepImpl(500 * 2 ** attempt);
+          continue;
+        }
         // A send whose preflight failed ("Transaction simulation failed: … custom program error: 0x17b5") carries the
         // logs, where the program says why in words.
         const logs = body?.error?.data?.logs;
         const said = logs?.length
           ? `The network refused this in a dry run: ${programError(body.error.data.err, logs)}`
           : message;
-        throw new RpcError(said, { code: body?.error?.code, logs });
+        throw new RpcError(said, {
+          code: body?.error?.code,
+          logs,
+          err: body?.error?.data?.err,
+          maybeTaken: method === 'sendTransaction' && unanswered,
+        });
       }
       return body.result;
     }
@@ -211,10 +251,17 @@ export function rpcClient(url, { fetchImpl = globalThis.fetch, sleepImpl = sleep
       };
     },
     async send(wire) {
-      return call('sendTransaction', [
-        toBase64(wire),
-        { encoding: 'base64', preflightCommitment: 'confirmed', maxRetries: 3 },
-      ]);
+      try {
+        return await call('sendTransaction', [
+          toBase64(wire),
+          { encoding: 'base64', preflightCommitment: 'confirmed', maxRetries: 3 },
+        ]);
+      } catch (e) {
+        // A transaction the cluster has taken already is refused as already processed: that is what a second send
+        // gets when the answer to the first was lost on its way back. It was sent; its signature is its first.
+        if (alreadyProcessed(e)) return transactionId(wire);
+        throw e;
+      }
     },
     signatureStatus,
     /** Wait until a sent transaction is confirmed; throws with the program's reason when it failed. */

package/js/economy/check.mjs

@@ -5673,7 +5673,7 @@ export function check(
     warn(
       'W-AUTHORITY',
       'economy.keys.authority',
-      `This economy needs the authority while it runs, for what only the game knows: ${needs.join('; ')}. ${m.authority === 'owner' ? 'That is your wallet, approving each one.' : `That is the key ${m.authority}.`}`,
+      `This economy needs the authority while it runs, for what only the game knows: ${needs.join('; ')}. ${m.authority === 'owner' ? 'That is the project’s owner key, which signs each one.' : `That is the key ${m.authority}.`}`,
     );
   const voucherKeys = [...new Set(m.grants.flatMap(g => [...(g.vouchers ?? []), ...(g.keys ?? [])]))];
   if (voucherKeys.length)
@@ -5802,7 +5802,7 @@ export function check(
       refuse(
         'E-TX-SIZE',
         paths[kind] ? `economy.${paths[kind]}${part ? `.${key}` : ''}` : 'economy',
-        `${named} takes ${bytes} bytes to set up in one transaction, more than the ${BUDGET} a setup transaction may hold (${MAX_TRANSACTION_BYTES}, less ${WALLET_ROOM} kept for what the owner’s wallet adds), so it could never go live.`,
+        `${named} takes ${bytes} bytes to set up in one transaction, more than the ${BUDGET} a setup transaction may hold (${MAX_TRANSACTION_BYTES}, less ${WALLET_ROOM} kept for the compute unit limit and price it leads with), so it could never go live.`,
         fix,
       );
     }

package/js/economy/cost.mjs

@@ -3,7 +3,16 @@
 //
 // Rent is (bytes + 128) × 5,080 lamports (model.mjs); the loot program's own records are sized byte for byte from
 // their Borsh layout, others (a Core collection, a farm) roughly, and marked so.
-import { boxOrderBytes, plan as compile, contestBytes, entryShape, farmEnds, roundRentOf } from './plan.mjs';
+import { priorityFee } from '../chain/programs.js';
+import {
+  boxOrderBytes,
+  plan as compile,
+  contestBytes,
+  entryShape,
+  farmEnds,
+  roundRentOf,
+  withSetupBudget,
+} from './plan.mjs';
 import {
   ACCOUNT_BYTES,
   CONTEST_ENTRY_BYTES,
@@ -63,7 +72,12 @@ export function setupCost(plan, economy) {
   const metadataLamports = accounts.reduce((n, a) => n + BigInt(a.fee ?? 0), 0n);
   const charged = plan.transactions.flatMap(t => t.steps).filter(s => !NO_FEE_STEP.test(s.id));
   const feeLamports = BigInt(charged.length) * FEES.project;
-  const networkLamports = plan.transactions.reduce((n, t) => n + BigInt(t.signers.length) * SIGNATURE_FEE, 0n);
+  // The network's fee: 5,000 lamports a signature, and each transaction's own priority fee (its unit limit times the
+  // unit price the plan sets: 2 lamports; none for a transaction listed without its instructions).
+  const networkLamports = plan.transactions.reduce(
+    (n, t) => n + BigInt(t.signers.length) * SIGNATURE_FEE + priorityFee(t.instructions ?? []),
+    0n,
+  );
   // Only the seeds and grant funds this plan puts in: a change to a live economy doesn't pay its seeds again.
   const steps = new Set(plan.transactions.flatMap(t => t.steps).map(s => s.id));
   const seeds = {};
@@ -101,7 +115,9 @@ export function setupCost(plan, economy) {
     notes.push(
       'The total includes the SOL put in grants’ funds, which pays their claims; what is left goes back to you when a grant closes.',
     );
-  notes.push('The network fee is 5,000 lamports a signature; a wallet may add a priority fee of its own.');
+  notes.push(
+    `The network fee is 5,000 lamports a signature and a priority fee of ${priorityFee(withSetupBudget([]))} lamports a transaction: each sets its own compute unit limit and price, so a wallet that adds a priority fee of its own leaves it as it is.`,
+  );
   return {
     accounts,
     rentSol: sol(rentLamports),
@@ -489,7 +505,7 @@ export function cost(economy, { now = Math.floor(Date.now() / 1000), only = null
 export function explainCost(c) {
   const s = c.setup;
   const lines = [
-    `Going live takes ${s.transactions} transaction${s.transactions === 1 ? '' : 's'} (${s.approvals} wallet approval${s.approvals === 1 ? '' : 's'}) and about ${s.totalSol} SOL:`,
+    `Going live takes ${s.transactions} transaction${s.transactions === 1 ? '' : 's'} and about ${s.totalSol} SOL:`,
   ];
   lines.push(
     `  rent ${s.rentSol} SOL for ${s.accounts.length} accounts; program fees ${s.programFeesSol} SOL; network fees ${s.networkFeesSol} SOL${

package/js/economy/explain.mjs

@@ -560,7 +560,7 @@ export function explainEconomy(economy, { now = Math.floor(Date.now() / 1000) }
   ]);
   const authority = play.filter(s => s.signer.startsWith('authority'));
   section(
-    `What only the authority signs while it runs (${m.authority === 'owner' ? 'your wallet' : `the key ${m.authority}`})`,
+    `What only the authority signs while it runs (${m.authority === 'owner' ? 'the project’s owner key' : `the key ${m.authority}`})`,
     authority.map(s => `${s.says} (${s.part}, ${s.ix}).`),
   );
   if (authority.length)
@@ -571,7 +571,7 @@ export function explainEconomy(economy, { now = Math.floor(Date.now() / 1000) }
   const s = c.setup;
   lines.push('', 'What setting it up costs');
   lines.push(
-    `- About ${num(s.totalSol)} SOL in all, in ${plural(s.transactions, 'transaction')} (${plural(s.approvals, 'wallet approval')}): rent ${num(s.rentSol)} SOL for ${plural(s.accounts.length, 'account')}, program fees ${num(s.programFeesSol)} SOL, network fees ${num(s.networkFeesSol)} SOL${
+    `- About ${num(s.totalSol)} SOL in all, in ${plural(s.transactions, 'transaction')}: rent ${num(s.rentSol)} SOL for ${plural(s.accounts.length, 'account')}, program fees ${num(s.programFeesSol)} SOL, network fees ${num(s.networkFeesSol)} SOL${
       s.metadataFeesSol ? `, Token Metadata’s fees ${num(s.metadataFeesSol)} SOL (a token’s name on chain)` : ''
     }${
       Object.keys(s.seeds).length
@@ -613,7 +613,7 @@ export function explainEconomy(economy, { now = Math.floor(Date.now() / 1000) }
   );
   lines.push(
     '',
-    'Devnet only: nothing here is real money. Going live is your approval in your own wallet: no one else signs, and no key is ever shared.',
+    '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.',
   );
   return {
     ok: true,

package/js/economy/guide.mjs

@@ -230,7 +230,7 @@ export const CANNOT = [
     why: 'loot isn’t a multisig, but any wallet can receive and any key can be the spending key',
     nearest: [
       'payments and sales go to a multisig vault: `"treasury": "wallet:<vault>"` or a `wallet:<vault>` share; spending from it needs the vault’s approvals in the multisig’s own app',
-      'the multisig vault as `keys.authority`, so moving the game’s pools needs its approvals (sent from the multisig’s own app, not the approve page)',
+      'the multisig vault as `keys.authority`, so moving the game’s pools needs its approvals (sent from the multisig’s own app, not by `xsolana approve`)',
     ],
   },
   {
@@ -431,7 +431,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 by the owner approving in their own wallet. Its parts (* = required field):`,
+      : `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):`,
     ...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

@@ -189,4 +189,4 @@ export function changedParts(economy) {
  * of that is decided when the change is approved.
  */
 export const renamesNote = renames =>
-  `The spec changes what ${renames.join(', ')} ${renames.length === 1 ? 'is' : 'are'} called. A token’s name on chain is its name record: approving reads it, and writes the new name, ticker and link there when the token has a record its owner can still change (and nothing when the record says them already). A token that went live before setups named tokens has no record and can’t be given one, and a record handed on, made unchangeable or given a royalty outside these tools is left as it is: the approval page says so, sends nothing for that token, and the change stays listed here until the spec gives its old name back.`;
+  `The spec changes what ${renames.join(', ')} ${renames.length === 1 ? 'is' : 'are'} called. A token’s name on chain is its name record: approving reads it, and writes the new name, ticker and link there when the token has a record its owner can still change (and nothing when the record says them already). A token that went live before setups named tokens has no record and can’t be given one, and a record handed on, made unchangeable or given a royalty outside these tools is left as it is: approving says so, sends nothing for that token, and the change stays listed here until the spec gives its old name back.`;

package/js/economy/plan.mjs

@@ -34,6 +34,7 @@ import {
   createAssociatedTokenAccountIdempotent,
   syncNative,
   transferLamports,
+  withComputeBudget,
 } from '../chain/programs.js';
 import {
   createAccountIx,
@@ -43,7 +44,7 @@ import {
   setAuthorityIx,
   transferCheckedIx,
 } from '../chain/token.js';
-import { compileMessage, transactionSize } from '../chain/tx.js';
+import { compileMessage, MAX_TRANSACTION_BYTES, transactionSize } from '../chain/tx.js';
 import { sha256 } from '../chain/sha256.js';
 import { utf8 } from '../chain/bytes.js';
 import * as loot from '../client/index.js';
@@ -1878,13 +1879,33 @@ export const stepBytes = (instructions, ctx) =>
 const budgeted = (instructions, compute) =>
   compute ? [computeUnitLimit(MAX_COMPUTE_UNITS), ...instructions] : instructions;
 
-/** The bytes of a transaction of `step` alone, as `pack` sends it (its compute limit included). */
+/** The bytes of a transaction of `step` alone, as `pack` holds it against the budget (a box's compute limit included). */
 export const stepAloneBytes = (step, ctx) => stepBytes(budgeted(step.build(ctx), Boolean(step.compute)), ctx);
 
 /**
- * Packs steps into transactions under the size budget, one signer set at a time; each step whole. A transaction that
- * carries a step needing more compute than an instruction has by default (`compute`: a box's write) asks for all a
- * transaction can have, first.
+ * The compute unit price every setup transaction sets, in micro-lamports a unit: 1, the least that is not 0 (a wallet
+ * may read 0 as no price set). With the unit limit below it comes to 1.4 lamports, charged as 2 lamports a transaction
+ * on top of the 5,000 a signature.
+ */
+export const SETUP_UNIT_PRICE = 1n;
+
+/**
+ * A setup transaction's instructions as the owner's wallet is handed them: led by a compute unit limit and a compute
+ * unit price, each once. A wallet that adds its own priority fee (Phantom does) adds it only to a transaction that
+ * sets neither, and the approval page sends a transaction only as it prepared it, so every setup transaction sets both
+ * itself. The limit is all a transaction can have (1,400,000 units): nothing here measures what a step takes, a box's
+ * write needs it, and no step may fail for want of compute. A limit or a price the instructions already carry is
+ * kept.
+ */
+export const withSetupBudget = instructions =>
+  withComputeBudget(instructions, { units: MAX_COMPUTE_UNITS, microLamports: SETUP_UNIT_PRICE });
+
+/**
+ * Packs steps into transactions under the size budget, one signer set at a time; each step whole. Every transaction
+ * leads with its compute budget (`withSetupBudget`): `BUDGET` keeps 64 bytes of a transaction free, and the two
+ * instructions take 52 of them (12 where a box's write, `compute`, had its limit counted with the steps already). So
+ * the steps pack as they did before the plan set a price, and `bytes`, the size of the transaction as it is sent, is
+ * held to what one transaction carries.
  */
 export function pack(steps, ctx) {
   const transactions = [];
@@ -1922,7 +1943,14 @@ export function pack(steps, ctx) {
     };
     transactions.push(current);
   }
-  for (const t of transactions) t.bytes = sizeOf(t.instructions);
+  for (const t of transactions) {
+    t.instructions = withSetupBudget(t.instructions);
+    t.bytes = sizeOf(t.instructions);
+    if (t.bytes > MAX_TRANSACTION_BYTES)
+      throw new Error(
+        `The steps “${t.steps.map(s => s.says).join('”, “')}” take ${t.bytes} bytes with their compute budget: too big for one transaction.`,
+      );
+  }
   return transactions;
 }
 

package/js/economy/review.mjs

@@ -670,7 +670,7 @@ export function review(economy, { now = Math.floor(Date.now() / 1000) } = {}) {
     m.authority === 'owner' ? 'info' : 'low',
     'economy',
     `${owner[0].toUpperCase()}${owner.slice(1)} alone changes every price, rate, grant, limit and voucher key (publishing again), and closes parts. ${m.authority === 'owner' ? 'It is also the authority, which' : `The authority, ${authority},`} mints the project’s tokens, moves what pools hold, names contest results and releases holds, with no caps. ${m.treasuryWallet ? `What sales leave goes to the wallet ${m.treasuryWallet}.` : 'What sales leave goes to the owner’s wallet (the treasury).'} Money held for a record (a farm’s stakes and rewards, a pot, an order) leaves only by its record’s rules: neither key pays it out.`,
-    'Keep these keys in a hardware wallet or a multisig; never on a server that players can reach, unless it is an authority made for that server.',
+    'Keep these keys safe: on devnet, the key file the setup was signed with, readable by you alone and never pasted anywhere; with real money, a hardware wallet or a multisig. Never on a server that players can reach, unless it is an authority made for that server.',
   );
   for (const w of warned('W-MINT-POWERS')) {
     const key = /^economy\.tokens\.([^.]+)/.exec(w.where)?.[1];

package/js/economy/schema.json

@@ -1824,7 +1824,7 @@
         "signedBy": {
           "enum": ["page", "server"],
           "default": "page",
-          "description": "page: the authority approves each one in its own wallet. server: a server you run holds the authority key (keys.authority is its public address)."
+          "description": "page: the authority signs each one itself (a script with its key file, or its browser wallet). server: a server you run holds the authority key (keys.authority is its public address)."
         },
         "proof": {
           "type": "object",

package/js/economy/txsize.mjs

@@ -11,8 +11,9 @@
 // - instruction data is sized byte for byte from the program's IDL (idl.mjs), and other programs' data from their
 //   documented layouts at its longest;
 // - no address lookup tables are assumed.
-// A wallet may add its own compute-budget instructions (a price and a limit: about 52 bytes), so the plan keeps
-// WALLET_ROOM free below the network's 1,232-byte limit.
+// A transaction's compute budget instructions (a unit limit and a unit price) take 52 bytes. A setup transaction
+// leads with its own (plan.mjs `withSetupBudget`), and a player's wallet may add its own to a transaction that sets
+// none. So an estimate keeps WALLET_ROOM free below the network's 1,232-byte limit.
 
 export const MAX_TRANSACTION_BYTES = 1232;
 export const WALLET_ROOM = 64;

package/js/mcp/server.mjs

@@ -10,18 +10,18 @@ import { PACKAGE_VERSION, PROGRAM_INFO, REMOTE_TOOLS, tools, VERSION } from './t
 
 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 (they approve in their own wallet: you never sign or ask for a key).',
+  'Start with xsolana_guide, then xsolana_examples with the person’s own words; write the spec; xsolana_check after every change; xsolana_simulate and xsolana_explain before telling them what it does; xsolana_review before going live (fix its high findings, say honestly what each voucher server checks, and tell the person what a cheater gets); xsolana_save; xsolana_publish when they say to put it live. 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.`,
 ].join(' ');
 
 /**
  * What a hosted server (js/mcp/http.mjs) tells the agent: the same work, with the spec passed whole in every call,
- * and going live on the person's own computer, since a hosted server can neither write their files nor open a page there.
+ * and going live on the person's own computer, since a hosted server can neither write their files nor sign there.
  */
 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, give the person the spec as a file named xsolana.json and this command, run in its folder: npx -y @xgamesfun/solana@${PACKAGE_VERSION} approve xsolana.json. It opens a page on their own computer where they approve each transaction in their own wallet. Nobody else signs, and never ask for a key. (xsolana_save and xsolana_publish, which tool texts may name, run only in the local server.)`,
+  `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.`,
 ].join(' ');
 

package/js/mcp/tools.mjs

@@ -1,5 +1,6 @@
 // The xsolana tools: what an agent needs to turn a person's idea into an economy on the shared loot program, check it,
-// simulate it, price it, explain it, save it and hand the person the step that puts it live in their own wallet.
+// simulate it, price it, explain it, save it and say how it is put live: signed by a key file on the person's own
+// machine, once they have read what would be sent and said yes.
 // Each tool is { name, description, inputSchema, annotations, handler(input, ctx) → { text, ...data } }; the server
 // (server.mjs) and the terminal (`xsolana tool`) run them the same way. No tool signs, holds a key or talks to a wallet.
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
@@ -48,15 +49,30 @@ export function plainName(rel, paths = path) {
 const NOT_PLAIN = rel => `${JSON.stringify(String(rel))} is not a plain file name`;
 const RENAME = 'use letters, digits and . _ - (and / for a folder), as in xsolana.json';
 /**
- * The command an owner runs to approve going live in their own wallet, pinned to this package's exact version, with
- * the spec's file (relative to the project folder, by `paths`' rules: the system's own unless given) as one plain
- * word. A name that is not plain throws.
+ * The command that puts an economy live, pinned to this package's exact version, with the spec's file (relative to the
+ * project folder, by `paths`' rules: the system's own unless given) as one plain word. A name that is not plain
+ * throws. How it is signed goes after it: `--keypair <key file>` (the usual way), or `--browser` when the person
+ * asks for a browser wallet.
  */
 export function approveCommand(file = '', paths = path) {
   const name = file ? plainName(file, paths) : '';
   if (name === null) throw new Error(`${NOT_PLAIN(file)}: rename it (${RENAME}).`);
   return `npx -y @xgamesfun/solana@${PACKAGE_VERSION} approve${name ? ` ${name}` : ''}`;
 }
+/**
+ * Where a project's key file is kept unless the person names another place: outside any repository, under the
+ * economy's own name (`~` is the home folder, in any shell: the commands read it themselves).
+ */
+export function keyFileFor(name) {
+  const slug = String(name ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  return `~/.config/xsolana/${slug || 'project'}.json`;
+}
+/** The command that makes a project's key file (it prints the key's address, never the key). */
+export const keygenCommand = keyFile => `npx -y @xgamesfun/solana@${PACKAGE_VERSION} keygen ${keyFile}`;
 export const CLUSTER = 'devnet';
 export const DEVNET_RPC = 'https://api.devnet.solana.com';
 /** What every answer carries, so an agent never has to remember the program's address. */
@@ -235,7 +251,7 @@ function flagsToTell(economy, now) {
   const flags = legalFlags(check(economy, { now }));
   return flags.length
     ? [
-        "If you haven't told the person these yet, say each once, in a plain sentence (the approval page shows them too, and asks them to tick that they read them; after that, only when they ask):",
+        "If you haven't told the person these yet, say each once, in a plain sentence (what `approve` prints before anything is sent shows them too; after that, only when they ask):",
         ...flags.map(f => `- ${f.says}`),
         '',
       ]
@@ -422,7 +438,7 @@ export const tools = [
     name: 'xsolana_cost',
     annotations: READ,
     description:
-      'What going live costs (each account’s rent, the program’s fees, network fees, the seeds, the transactions and wallet approvals it takes) and what each action costs whoever signs it while it runs.',
+      'What going live costs (each account’s rent, the program’s fees, network fees, the seeds, the transactions it takes) and what each action costs whoever signs it while it runs.',
     inputSchema: { type: 'object', properties: SOURCE, additionalProperties: false },
     async handler(input, ctx) {
       const { economy, from } = await load(input, ctx);
@@ -565,7 +581,7 @@ export const tools = [
   {
     name: 'xsolana_publish',
     annotations: { ...READ, readOnlyHint: true },
-    description: `When the person says to put it live: returns what going live does (every step, in order, and its cost) and the one command they run themselves to approve it in their own wallet (\`${approveCommand()}\`, pinned to this exact version: give it as it is): it opens a local page where they connect a devnet wallet and approve each transaction. You never sign, never ask for a key, and never run the approval for them.`,
+    description: `When the person says to put it live: returns what going live does (every step, in order, and its cost) and the commands that do it (each starts npx -y @xgamesfun/solana@${PACKAGE_VERSION} for this exact version: give them as they are). Going live is signed by a key file on the person’s own machine: \`keygen\` makes one for the project (it prints the address, never the key), and \`approve … --keypair <file>\` prints everything that would be sent and sends nothing until it is run again with the code it printed, which you do only after the person has read that printout and said yes. A live economy is changed only by the key that owns it: never make a new key for one. Never ask for, read or print a key, and open no signing page: the browser-wallet page (\`approve … --browser\`) is for a person who asks for one, or whose browser wallet owns the project, and they run it themselves.`,
     inputSchema: { type: 'object', properties: SOURCE, additionalProperties: false },
     async handler(input, ctx) {
       const { economy, from, file } = await load(input, ctx);
@@ -608,21 +624,41 @@ export const tools = [
           steps: [],
           text: `Not published: ${NOT_PLAIN(target)}, and the approve command carries the file's name as it is. Ask the person to rename it (${RENAME}), then run xsolana_publish again with the new name.${footer}`,
         };
-      const command = approveCommand(target);
+      const live = Boolean(change.scope.live);
+      const keyFile = keyFileFor(economy.name);
+      // (a live project is signed only by the key that owns it: no command here makes another)
+      const keygen = live ? null : keygenCommand(keyFile);
+      const browserCommand = `${approveCommand(target)} --browser`;
+      const command = `${approveCommand(target)} --keypair ${keyFile}`;
       const text = [
         ...flagsToTell(economy, nowOf(ctx)),
-        `${change.scope.live ? 'Publishing this change to the live economy' : 'Going live'}: ${renaming ? 'at most ' : ''}${plural(p.transactions.length, 'transaction')}, ${plural(p.approvals, 'wallet approval')}, about ${c.setup.totalSol} SOL on devnet:`,
+        `${change.scope.live ? 'Publishing this change to the live economy' : 'Going live'}: ${renaming ? 'at most ' : ''}${plural(p.transactions.length, 'transaction')}, about ${c.setup.totalSol} SOL on devnet:`,
         ...steps.map((s, i) => `${i + 1}. ${s}`),
         '',
-        `To put it live, the person runs this in a terminal in the project folder (not you): ${command}`,
-        'It opens a page on their own computer; they connect a wallet set to devnet and approve. What lands is written back into the file.',
-        'The page also says the program is not independently audited and comes as is, with no warranty; they use it at their own risk, and making sure the economy is legal where it is offered is up to them (DISCLAIMER.md in the package). They tick that they read it, so it needs no repeating unless they ask.',
-        ...(file ? [] : [`(Save it first with xsolana_save: the approval reads ${DEFAULT_FILE}.)`]),
+        `${live ? 'To publish it' : 'To put it live'}, in a terminal in the project folder (you run these; nothing opens, and nothing is sent before the person’s yes):`,
+        ...(live
+          ? [
+              `1. Only the key that owns the project can change it: the key file it went live with (${keyFile} if it was made there; give the file’s own path if it is elsewhere). If there is no such file, a browser wallet owns it: use the --browser command below. Never make a new key for a live project (a new key can change nothing), and never remove the file’s live section because a key was refused. If you can’t tell, ask the person how it went live. The owner’s address needs about ${c.setup.totalSol} SOL of devnet SOL.`,
+            ]
+          : [
+              `1. A key file for this project, unless it has one: ${keygen}`,
+              '   It prints the key’s address, never the key. The key file is the project’s owner: whoever can read it controls the project, and which key goes live is for good (every later change is signed by it; these tools can’t hand a project to another owner). It stays where it is: never in a chat, a spec, a repository or a page, and you never open, read or print it. Tell the person to back the file up themselves: if it is lost, nothing can change the economy or move what its address holds.',
+              `   Everything the setup takes from the owner must be at that address first: the devnet SOL (about ${c.setup.totalSol} SOL here; https://faucet.solana.com gives some), any seed in a coin that already exists, and every NFT a stash, a raffle or an auction names (a collection they already have needs that address as its update authority). If they would rather not move those, offer the browser wallet.`,
+              '   The steps above call the owner’s address “your wallet”: with a key file, that is the key’s address. Unless the spec names a treasury, what sales leave lands there, and it signs what only the authority signs. If the economy takes money in, ask for the public address of a wallet the person holds and set "treasury": "wallet:<address>" first: it can’t be changed through the spec once live.',
+            ]),
+        `2. ${command}`,
+        '   It prints every step with what it pays and trusts, the warnings, the notice (the program is not independently audited and comes as is, with no warranty; they use it at their own risk, and making sure the economy is legal where it is offered is up to them: DISCLAIMER.md in the package) and a code. It sends nothing.',
+        '3. Show the person that printout and ask. When they say yes, run the same command with --yes <code>: the code stands for exactly what was printed, and anything else is refused. What lands is written back into the file. If it stops part way, run it again without --yes: it prints what is left and a new code. Go on with that code; if it shows a step or a warning they have not seen, ask again.',
+        `${live ? 'For a project a browser wallet owns' : 'Only if the person asks to sign in a browser wallet instead'}: give them this to run in their own terminal: ${browserCommand} (it serves a page on their own computer where they connect a wallet set to devnet and approve, ${plural(p.approvals, 'approval')}, and keeps running until the page says it is live). Don’t run or open it otherwise.${live ? ' A project a key file owns can’t be signed in a browser wallet.' : ''}`,
+        ...(file ? [] : [`(Save it first with xsolana_save: \`approve\` reads ${DEFAULT_FILE}.)`]),
         ...(change.notes ? [change.notes.trim()] : []),
       ].join('\n');
       return {
         ok: true,
         command,
+        ...(keygen ? { keygen } : {}),
+        keyFile,
+        browserCommand,
         transactions: p.transactions.length,
         approvals: p.approvals,
         setupSol: c.setup.totalSol,
@@ -861,6 +897,7 @@ export const tools = [
       const text = [
         `loot ${VERSION} on ${CLUSTER}: program ${LOOT_PROGRAM}. Never write another address from memory: take it from this package.`,
         'Package: npm install @xgamesfun/solana (plain ES modules, no Solana SDK needed; works in the browser).',
+        '  What only the project’s owner or authority signs (a contest’s result, a payout, a schedule’s run) is not a page’s: a script on the owner’s machine signs it with the project’s key file, `readKeyFile(file)` from "@xgamesfun/solana/keyfile" (an address and a way to sign, never the key; it is also a `wallet` for solanaApp). The skill’s references/after-launch.md has the script.',
         '  import { solanaApp, walletStandardSigner } from "@xgamesfun/solana/play";',
         '  const app = solanaApp({ spec /* the live xsolana.json */, rpcUrl, wallet: walletStandardSigner(wallet, account) });',
         '  app.shop(), app.buy(key, { listing }), app.boxes(), app.openBox(key, { listing }), app.pay(key) (or app.pay(key, { chosenRecipient })),',

package/js/play/index.js

@@ -37,12 +37,14 @@ import {
   requestHeapFrame,
   syncNative,
   transferLamports,
+  withComputeBudget,
   withSolWrap,
 } from '../chain/programs.js';
 import { checkCluster, notMainnet, rpcClient } from '../chain/rpc.js';
 import { extension, mayStartFrozen, mintPowers, resolveTransfers } from '../chain/token2022.js';
 import {
   compileFitting,
+  compileKeepingKind,
   closeTableIx,
   deactivateTableIx,
   readTable,
@@ -74,6 +76,9 @@ export {
 
 // The options of a call made without any: read-only, and typed so the generated declarations take any option.
 /** A lottery's steps in `claims()`: each depends on the one before, so `claimAll` takes one of a lottery's a call. */
+/** The compute units a sponsored step asks for: all a transaction can have. It sets a price of 0, so they cost nothing. */
+const SPONSORED_UNITS = 1_400_000;
+
 const LOTTERY_STEPS = new Set(['reveal', 'cancel-draw', 'pull', 'payout']);
 /** The claims that are one transaction of the wallet's: `claimAll` signs them together. */
 const BATCHED = new Set(['contest', 'release', 'lookup-table', 'close-leaf', ...LOTTERY_STEPS]);
@@ -799,17 +804,26 @@ export function solanaApp({
     const { blockhash, lastValidBlockHeight } = await client.latestBlockhash();
     // Lent the most, the step is tried; then sent lent the same, the player giving back last all but what it costs in
     // fees and rent: a step can need more SOL midway than it costs (a wrapped-SOL account it opens and closes).
-    const compile = (back = 0n) =>
-      compileFitting({
+    // It leads with a compute unit limit (all a transaction can have) and a unit price of 0, the price a sponsor
+    // pays unless its server says more: a wallet that adds its own priority fee only where a transaction sets none
+    // (Phantom does, to one with no signature on it yet) is then handed one it signs as it stands, and the sponsor's
+    // server, which refuses a price it did not agree to, takes it. A step keeps the kind of transaction it had: one
+    // that fits a legacy transaction stays one (without the two where they would not fit), and only a step that
+    // needed the project's lookup tables before goes as v0.
+    const compile = (back = 0n) => {
+      const list = [
+        sponsorTopUp(sponsor.address, me, sponsorMax),
+        ...instructions,
+        ...(back > 0n ? [sponsorGiveBack(sponsor.address, me, back)] : []),
+      ];
+      return compileKeepingKind({
         payer: sponsor.address,
         blockhash,
-        instructions: [
-          sponsorTopUp(sponsor.address, me, sponsorMax),
-          ...instructions,
-          ...(back > 0n ? [sponsorGiveBack(sponsor.address, me, back)] : []),
-        ],
+        led: withComputeBudget(list, { units: SPONSORED_UNITS, microLamports: 0n }),
+        plain: list,
         tables,
       });
+    };
     const tried = compile();
     if (!tried) return null;
     const addresses = namedIn([sponsorTopUp(sponsor.address, me, 0n), ...instructions]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xgamesfun/solana",
-  "version": "0.27.1",
+  "version": "0.27.2",
   "mcpName": "io.github.XGamesFun/solana-kit",
   "description": "Loot boxes, gacha, shops, lotteries, auctions, NFT staking, crafting and rewards on Solana without writing a smart contract: one shared program, its JS client, a CLI, and an MCP server and skill so Claude Code, Codex or any AI agent can design, check, simulate and launch an economy.",
   "license": "Apache-2.0",
@@ -70,6 +70,10 @@
       "types": "./types/results/index.d.ts",
       "default": "./js/results/index.js"
     },
+    "./keyfile": {
+      "types": "./types/approve/keyfile.d.mts",
+      "default": "./js/approve/keyfile.mjs"
+    },
     "./idl.json": "./js/client/idl/loot.json",
     "./package.json": "./package.json",
     "./release.json": "./release.json",

package/release.json

@@ -4,5 +4,5 @@
   "sbfBytes": 1794664,
   "sbfSha256": "3b11c460548a4fec865fd902431a94ac13a71c3a1013e4516783515e5d266bd6",
   "idlSha256": "62364c5fd5be8aa001f4d72fb87b121b045dea07668f9b5ec9856d323d6cf445",
-  "clientSha256": "179b7ff59398a39cce70df059c1781e91a3d0366791797b368d8030169a507ad"
+  "clientSha256": "7790b667386bb981218acc8621088b2f7799c92347193b3a97d59b9332c4ed29"
 }