@xgamesfun/solana 0.27.1 → 0.27.2

package/js/approve/server.mjs

@@ -1,4 +1,6 @@
-// `xsolana approve`: a page on 127.0.0.1 where the owner of an economy approves going live in their own wallet. The
+// `xsolana approve --browser`: a page on 127.0.0.1 where the owner of an economy approves going live in a browser
+// wallet, served only when asked for (`xsolana approve --keypair`, js/approve/with-key.mjs, drives this same approval
+// with a key file and no page). The
 // server builds each transaction (js/economy/plan.mjs), has the fresh keys a setup makes sign their part, and sends
 // only what it prepared: a wallet's answer must carry the exact message prepared for it and that wallet's valid
 // signature. Each prepared batch answers once and expires after 90 seconds. What lands is written back into the spec
@@ -11,12 +13,12 @@ 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 { checkCluster, notMainnet, rpcClient } from '../chain/rpc.js';
+import { alreadyProcessed, checkCluster, notMainnet, 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 { COMPUTE_BUDGET_PROGRAM, SYSVAR_SLOT_HASHES } from '../chain/pda.js';
 import { MINT_BYTES } from '../chain/token.js';
-import { compileMessage, readTransaction, wireTransaction } from '../chain/tx.js';
+import { compileMessage, readMessage, readTransaction, wireTransaction } from '../chain/tx.js';
 import { accountKind, decode } from '../client/accounts.js';
 import { LOOT_PROGRAM, pda } from '../client/pda.js';
 import { check, describe } from '../economy/check.mjs';
@@ -221,7 +223,7 @@ export async function createApproval({
       if (!(e instanceof MintMismatch)) throw e;
       throw new ApproveError(
         409,
-        `${e.message} Nothing was sent: correct ${path.basename(file)}, then run \`xsolana approve\` again.`,
+        `${e.message} Nothing was sent: correct ${path.basename(file)}, then run the same approve command again.`,
       );
     }
     try {
@@ -242,9 +244,16 @@ export async function createApproval({
       return trusted;
     } catch (e) {
       if (!(e instanceof LiveMismatch)) throw e;
-      throw new ApproveError(
-        409,
-        `${e.message} Nothing was sent. ${path.basename(file)}’s live section is not what the chain says: restore the file \`xsolana approve\` wrote, or remove its live section to start a new setup.`,
+      // Another key's project: the owner with the wrong key, or a file that came with someone else's live section
+      // (the two look the same from here). Anything else: the file is not what the chain says.
+      throw Object.assign(
+        new ApproveError(
+          409,
+          e.notOwner
+            ? `${e.message} Nothing was sent. If the project is yours, sign with the key that owns it (its key file, or \`approve --browser\` when a browser wallet owns it): ${path.basename(file)} needs no change, and a new key can change nothing. If it is not yours (the file came from someone else with their live section in it), that section is theirs: only then is it removed, to set up a project of your own.`
+            : `${e.message} Nothing was sent. ${path.basename(file)}’s live section is not what the chain says: restore the file as approve wrote it. (Its live section is removed only to start a separate setup of one’s own, which leaves the live project as it is on chain.)`,
+        ),
+        { notOwner: Boolean(e.notOwner) },
       );
     }
   }
@@ -408,6 +417,9 @@ export async function createApproval({
       // authority of).
       project: extra.project ?? null,
       wallet: n.owner ?? null,
+      // The accounts this session made new keys for (a token's mint, the collection, the tree): their addresses are
+      // this session's own, new each time, so what is shown twice differs in them and in nothing else.
+      fresh: [...keys].map(([name, k]) => ({ name: name.replace(/^new:/, ''), address: k.address })),
       ...(extra.refused ? { refused: extra.refused } : {}),
     };
   }
@@ -474,7 +486,12 @@ export async function createApproval({
     } catch (e) {
       if (!(e instanceof ApproveError)) throw e;
       const v = view(p0, namesOf(model(spec, { now: at }), { now: at, owner: wallet }), { refused: e.message });
-      return { ...v, remaining: p0.ok ? p0.transactions.length : 0, done: false };
+      return {
+        ...v,
+        ...(e.notOwner ? { notOwner: true } : {}),
+        remaining: p0.ok ? p0.transactions.length : 0,
+        done: false,
+      };
     }
     if (!p0.ok || !p0.transactions.length)
       return { ...view(p0, names(), { project: trusted.project }), remaining: 0, done: p0.ok };
@@ -599,9 +616,26 @@ export async function createApproval({
         try {
           await chain.send(wire);
         } catch (e) {
-          // The node answered and refused it: it was never taken, so it can never land.
-          if (e.code !== undefined || !chain.signatureStatus) await forget(signature);
-          throw e;
+          // A refusal alone does not say it was never taken: when the answer to a first send is lost, the same
+          // transaction sent again is refused as already processed, and it has landed; or the second try reaches a
+          // node a moment behind, which refuses it for a blockhash or an account it has not seen yet. So the chain
+          // is asked before the signature is forgotten, and it is forgotten only when it can never land: the chain
+          // says it failed, or a node answered this send with a refusal and no earlier try of it went unanswered
+          // (`maybeTaken`). Anything else is kept, and looked up before anything is sent again.
+          let status = null;
+          let read = Boolean(chain.signatureStatus);
+          if (read)
+            try {
+              status = await chain.signatureStatus(signature);
+            } catch {
+              read = false;
+            }
+          const taken = landedStatus(status) || (!status?.err && (Boolean(status) || alreadyProcessed(e)));
+          if (!taken) {
+            if (!chain.signatureStatus || status?.err || (read && e.code !== undefined && !e.maybeTaken))
+              await forget(signature);
+            throw e;
+          }
         }
         try {
           await chain.confirm(signature, { lastValidBlockHeight: batch.lastValidBlockHeight });
@@ -635,6 +669,8 @@ export async function createApproval({
       project: b.ctx.project,
       transactions: b.wires.map(toBase64),
       says: b.batch.map(t => t.steps.map(s => s.says).join('; ')),
+      // each transaction's steps, by id and in words: what a signer that showed the steps first holds them against
+      steps: b.batch.map(t => t.steps.map(s => ({ id: s.id, says: s.says }))),
       details: b.details,
     };
   }
@@ -892,6 +928,48 @@ const sameText = (a, b) => {
   return x.length === y.length && timingSafeEqual(x, y);
 };
 
+/** 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',
+};
+
+/**
+ * What a wallet did to a message it was to sign as it stood, in words for the refusal: " (it added …)" when the
+ * message it signed is the prepared one with instructions added (a wallet that adds its own priority fee, or checks
+ * of its own), " (it put another blockhash on it)", or '' when the change is anything else or can't be read.
+ */
+export function walletChange(ours, theirs) {
+  try {
+    const [a, b] = [readMessage(ours), readMessage(theirs)];
+    const told = m =>
+      m.instructions.map(ix => ({
+        program: m.keys[ix.programIndex],
+        kind: ix.data[0],
+        text: `${m.keys[ix.programIndex]} ${ix.accountIndexes.map(i => m.keys[i] ?? `#${i}`).join(',')} ${toBase64(ix.data)}`,
+      }));
+    const mine = told(a);
+    const added = [];
+    let at = 0;
+    for (const ix of told(b)) {
+      if (at < mine.length && ix.text === mine[at].text) at++;
+      else added.push(ix);
+    }
+    if (at !== mine.length || !added.length)
+      return a.blockhash !== b.blockhash ? ' (it put another blockhash on it)' : '';
+    const what = added.map(ix =>
+      ix.program === COMPUTE_BUDGET_PROGRAM
+        ? (BUDGET_ASKS[ix.kind] ?? 'a compute budget instruction')
+        : `an instruction of the program ${ix.program}`,
+    );
+    return ` (it added ${[...new Set(what)].join(', ')})`;
+  } catch {
+    return '';
+  }
+}
+
 /** The wallet's signed copies: each the exact prepared message, each with the wallet's valid signature. */
 function checkSigned(prepared, signed, wallet) {
   if (!Array.isArray(signed) || signed.length !== prepared.length)
@@ -906,7 +984,10 @@ function checkSigned(prepared, signed, wallet) {
       throw new ApproveError(400, 'The wallet returned something that is not a transaction.');
     }
     if (!equalBytes(mine.message, theirs.message))
-      throw new ApproveError(400, 'The wallet changed the transaction before signing it, so nothing was sent.');
+      throw new ApproveError(
+        400,
+        `The wallet changed the transaction before signing it${walletChange(mine.message, theirs.message)}, so nothing was sent: only what was prepared and shown here is ever sent. A wallet that adds to what it signs can’t approve this way: use one that signs a transaction as it stands. (A setup that has not started can be signed by a key file instead: xsolana approve --keypair. One that has started is finished by the key that started it.)`,
+      );
     const slot = mine.signers.indexOf(wallet);
     if (slot < 0) throw new ApproveError(400, 'This transaction was not prepared for that wallet.');
     const signature = theirs.signatures[slot];

package/js/approve/with-key.mjs

@@ -0,0 +1,298 @@
+// `xsolana approve --keypair <file>`: going live signed by a key file on this machine, with no browser and no page.
+// It is the same approval the page serves (`createApproval`: the same plan, the same reads of the chain, the same
+// check of every signed transaction, the same record in the spec file), driven from the terminal. What the page shows
+// before its Approve button is printed here first, whole: every step with what it pays and trusts, the warnings, the
+// notice and the legal flags, and then nothing is sent. It is sent when the command is run again with the code the
+// printout ends with (`--yes <code>`), which stands for that printout and no other: whoever runs it (a person, or an
+// agent after the person's yes) sends exactly what was shown. The command never stops to ask: an agent's terminal
+// would hang on a question, or answer it.
+import { createHash } from 'node:crypto';
+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';
+
+/** The notice the page has its owner tick before Approve (js/approve/page.html, "Read this first"), word for word. */
+export const NOTICE = [
+  'The loot program has not been independently audited. It and these tools come as is, with no warranty and no guarantee that they are safe: what is sent to the program can be lost. You use them at your own risk.',
+  'Transactions can’t be undone. You are responsible for every one you approve.',
+  'Making sure your economy is legal everywhere it is offered is up to you. Nothing here is legal or financial advice.',
+];
+
+const LAMPORTS = 1_000_000_000n;
+/** Lamports as SOL, to the lamport, with no trailing zeros. */
+function sol(lamports) {
+  const n = BigInt(lamports);
+  const frac = String(n % LAMPORTS)
+    .padStart(9, '0')
+    .replace(/0+$/, '');
+  return `${n / LAMPORTS}${frac ? `.${frac}` : ''}`;
+}
+
+/** SOL as the tools write it ("5.33360349", 5.3336) in lamports. */
+function solToLamports(text) {
+  const [whole, frac = ''] = String(text).split('.');
+  return BigInt(whole || '0') * LAMPORTS + BigInt(frac.padEnd(9, '0').slice(0, 9) || '0');
+}
+
+const count = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** The key's own signature put into its slot of a prepared transaction, as a wallet's signTransaction does. */
+function signWire(key, b64) {
+  const t = readTransaction(fromBase64(b64));
+  const slot = t.signers.indexOf(key.address);
+  if (slot < 0) throw new Error('A transaction was prepared that this key does not sign: nothing was sent.');
+  const signatures = [...t.signatures];
+  signatures[slot] = key.sign(t.message);
+  return toBase64(wireTransaction(t.message, signatures));
+}
+
+/**
+ * A time as the steps' lines write one: to the second ("2026-11-11T08:34:11Z"), or, for one years off, by the day and
+ * the years it is away ("11 November 2030, 4 years from now").
+ */
+const WRITTEN_TIME =
+  /\b\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\b|\b\d{1,2} (?:January|February|March|April|May|June|July|August|September|October|November|December) \d{4,}\b|\b[\d,]+ years (?:from now|after go-live)\b/g;
+
+/**
+ * The code that stands for one printout: the whole file (the spec, and its live section with every address it gives
+ * the steps: the project, the mints, the collection), the key, every step still to send with what it pays and trusts,
+ * and every line the person is to read first. Anything of that changing (an edit to the file, a step landing, the
+ * chain saying something new of a token) gives another code, so a yes is never carried over to something that was
+ * not shown. Two things in the lines are left out, because they are new at each run and say nothing a person can
+ * check: the addresses of the accounts the setup makes new, and a time counted from "publish" (the file's own words
+ * for it, "publish+30d", are in the code).
+ */
+export function approvalCode(state, spec) {
+  let shown = JSON.stringify([
+    'xsolana approve',
+    state.cluster,
+    state.program,
+    state.wallet,
+    state.project,
+    state.mode,
+    state.steps.map(s => [s.id, s.says, s.signer, s.details ?? []]),
+    state.warnings,
+    state.legal.map(f => f.says),
+    state.unwritten,
+    state.read ?? null,
+  ]);
+  // (a new account's address is made anew for each printout: it is named by what it is)
+  for (const f of state.fresh ?? []) shown = shown.replaceAll(f.address, `<new ${f.name}>`);
+  shown = shown.replace(WRITTEN_TIME, '<a time>');
+  // The file as it is, live section and all: what the steps are built from, whether or not a line names it.
+  return createHash('sha256').update(JSON.stringify(spec)).update('\n').update(shown).digest('hex').slice(0, 8);
+}
+
+/** A new account of the setup in words: "mint/gold" is the mint of the token “gold”. */
+const freshName = name =>
+  /^mint[/:]/.test(name)
+    ? `the mint of the token “${name.slice(5)}”`
+    : name === 'collection'
+      ? 'the collection'
+      : name === 'tree'
+        ? 'the tree of compressed NFTs'
+        : name;
+
+/** What the page shows before Approve, as lines of text. `balance`: the key's lamports, or null when not read. */
+export function approvalText(state, { keyFile, balance = null }) {
+  const lines = [];
+  const kind =
+    state.mode === 'change'
+      ? 'a change to a live economy'
+      : state.mode === 'resume'
+        ? 'a setup that was cut short goes on'
+        : 'a new economy';
+  lines.push(
+    `“${state.name}” (${state.file}): ${kind}, on ${state.cluster}, on the shared loot program ${state.program}.`,
+  );
+  lines.push(
+    `Signed by the key file ${keyFile}, whose address is ${state.wallet}. The lines below call that address “your wallet”.`,
+  );
+  if (state.project) lines.push(`Project: ${state.project}`);
+  for (const f of state.fresh ?? [])
+    lines.push(
+      `New, made by this setup: ${freshName(f.name)}, at ${f.address} (a new address each time this is shown).`,
+    );
+  const about = state.setupSol !== null && state.mode === 'new' ? ` Going live takes about ${state.setupSol} SOL.` : '';
+  if (balance !== null) lines.push(`The key holds ${sol(balance)} SOL.${about}`);
+  else if (about) lines.push(about.trim());
+
+  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.',
+  );
+
+  if (state.warnings.length) {
+    lines.push('', 'Before you approve');
+    for (const w of state.warnings) lines.push(`- ${w}`);
+  }
+  if (state.landed.length) {
+    lines.push('', 'Landed already');
+    for (const l of state.landed) lines.push(`- ${l.says}`);
+  }
+  lines.push('', `To send: ${count(state.steps.length, 'step')} in ${count(state.remaining, 'transaction')}`);
+  state.steps.forEach((s, i) => {
+    const who = s.signer === 'authority' ? ` (the authority signs: ${state.authority})` : '';
+    lines.push(`${i + 1}. ${s.says}${who}`);
+    for (const d of s.details ?? []) lines.push(`   - ${d}`);
+  });
+  return lines;
+}
+
+/**
+ * Puts the economy in `file` live with the key in `keyFile`, or goes on with a setup that was cut short, or sends a
+ * live economy's change. `yes`: null shows what would be sent and sends nothing (or asks `confirm`, when a caller
+ * that has the person in front of it gives one; the command line never does); a code sends when it is the code of
+ * what is shown now, and is refused otherwise; true sends without asking (for a script that has shown it its own
+ * way). `out(line)` prints. Returns { ok, sent, done, code }:
+ * `ok` false when something was refused or failed, `sent` how many transactions landed, `done` whether the file is
+ * recorded as live.
+ */
+export async function approveWithKey({
+  file = 'xsolana.json',
+  keyFile,
+  yes = null,
+  confirm = null,
+  chain = devnetChain(),
+  out = line => console.log(line),
+  now,
+  keyReader = readKeyFile,
+  approval = createApproval,
+}) {
+  const key = await keyReader(keyFile);
+  const session = await approval({ file: path.resolve(file), chain, ...(now ? { now } : {}) });
+  // How many transactions this run saw land (its own, and any an earlier run sent that it found landed).
+  const landed = () => session.state().signatures.length;
+  const live = () => !session.spec.live?.partial && Boolean(session.spec.live);
+  try {
+    let state = await session.stateFor(key.address);
+    if (state.refused) {
+      out(`Nothing can be sent: ${state.refused}`);
+      // (a key that is not the project's: said plainly, so nobody makes a new key or cuts the file to get past it)
+      if (state.notOwner)
+        out(
+          `This key file’s address is ${key.address}: it is not the project’s key. If the project is yours, find the key it went live with: don’t make a new one, and don’t change ${state.file} to get past this.`,
+        );
+      return { ok: false, sent: 0, done: false, code: null };
+    }
+    if (!state.remaining) {
+      for (const line of state.unwritten ?? []) out(line);
+      if (!state.done) {
+        for (const w of state.warnings) out(w);
+        out(`Nothing can be sent for ${state.file} as it is.`);
+        return { ok: false, sent: 0, done: false, code: null };
+      }
+      out(
+        state.unwritten?.length
+          ? `Nothing to send for “${state.name}”: the file is as it was.`
+          : `Nothing to send: “${state.name}” is live on ${state.cluster} as ${state.file} says.`,
+      );
+      return { ok: true, sent: 0, done: true, code: null };
+    }
+
+    const balance = chain.account
+      ? await chain.account(key.address).then(
+          a => BigInt(a?.lamports ?? 0),
+          () => null,
+        )
+      : null;
+    const code = approvalCode(state, session.spec);
+    for (const line of approvalText(state, { keyFile: key.file, balance })) out(line);
+    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.`,
+      );
+      return { ok: false, sent: 0, done: false, code };
+    }
+    // A new setup the key can't pay for would stop part way: it is not started.
+    const needs = state.mode === 'new' && state.setupSol !== null ? solToLamports(state.setupSol) : null;
+    if (balance !== null && needs !== null && balance < needs) {
+      out(
+        `Nothing was sent: the key holds ${sol(balance)} SOL, less than the about ${state.setupSol} SOL going live takes. Send ${key.address} at least ${sol(needs - balance)} SOL more, then run this again.`,
+      );
+      return { ok: false, sent: 0, done: false, code };
+    }
+    if (yes === null && confirm) {
+      const said = await confirm(
+        `Send ${count(state.remaining, 'transaction')} from ${key.address}? Type yes to send: `,
+      );
+      if (!said) {
+        out('Nothing was sent.');
+        return { ok: true, sent: 0, done: false, code };
+      }
+    } else if (yes === null) {
+      out(
+        `Nothing was sent. This is what going on would send: show it to the person whose economy it is, and when they say yes, run the same command with --yes ${code}`,
+      );
+      return { ok: true, sent: 0, done: false, code };
+    } else if (yes !== true && String(yes) !== code) {
+      out(
+        `Nothing was sent: ${JSON.stringify(String(yes))} is not the code of what is above (the file, the chain or what is left to send has changed since that code was given, or it was mistyped). Read the above again; its code is ${code}.`,
+      );
+      return { ok: false, sent: 0, done: false, code };
+    }
+
+    // Only what was shown is sent. Each batch is held against the printout before the key signs it: every step it
+    // carries was on the printout, in the same words. After each batch, a step that was not on the printout, or a
+    // line about a token the chain did not say then, stops it for another read.
+    const shown = new Map(state.steps.map(s => [s.id, s.says]));
+    const readShown = state.read ?? null;
+    const changed = () => {
+      const sent = landed();
+      out(
+        `${sent ? `Stopped after ${count(sent, 'transaction')}` : 'Nothing was sent'}: what is left to send is not what was shown above. Run the command again to read what is left, and go on from there.`,
+      );
+      return { ok: false, sent, done: false, code };
+    };
+    for (let turn = 0; state.remaining && turn < 500; turn++) {
+      let batch;
+      try {
+        batch = await session.prepare(key.address, state.read ?? null);
+      } catch (e) {
+        if (e.status === 403)
+          e.message += ' With key files: run this command again with that address’s key file (--keypair).';
+        throw e;
+      }
+      if (!batch.steps?.length || batch.steps.flat().some(step => shown.get(step.id) !== step.says)) return changed();
+      for (const says of batch.says) out(`Sending: ${says}`);
+      await session.complete(
+        key.address,
+        batch.id,
+        batch.transactions.map(b64 => signWire(key, b64)),
+      );
+      state = await session.stateFor(key.address);
+      if (state.refused) throw new Error(state.refused);
+      if (state.steps.some(s => !shown.has(s.id)) || (state.remaining && (state.read ?? null) !== readShown))
+        return changed();
+    }
+    for (const line of state.unwritten ?? []) out(line);
+    const sent = landed();
+    out(
+      live()
+        ? `Live on ${state.cluster}: ${count(sent, 'transaction')} landed, and ${state.file} now holds the project’s addresses (project ${session.spec.live.project}).`
+        : `${count(sent, 'transaction')} landed, and ${state.file} is not recorded as live yet: run the command again.`,
+    );
+    return { ok: live(), sent, done: live(), code };
+  } catch (e) {
+    const sent = landed();
+    // A transaction that was sent and is not known to have landed is still looked for: it is not "nothing sent".
+    const unknown = session.spec.live?.pending?.length ?? 0;
+    const so = [
+      sent ? `Stopped after ${count(sent, 'transaction')} landed` : unknown ? 'Stopped' : 'Nothing was sent',
+      unknown
+        ? ` (${count(unknown, 'more was', 'more were')} sent and ${unknown === 1 ? 'is' : 'are'} not known to have landed yet)`
+        : '',
+    ].join('');
+    out(
+      `${so}: ${e.message}${sent || unknown ? ` What is known is recorded in ${path.basename(file)}: run the command again to go on from where it stopped; a transaction still looked for is found first, so nothing is sent twice.` : ''}`,
+    );
+    return { ok: false, sent, done: false, code: null };
+  } finally {
+    session.close();
+    key.drop();
+  }
+}

package/js/chain/lookup.js

@@ -166,6 +166,17 @@ export function compileFitting({ payer, blockhash, instructions, tables = [] })
   return tables.length && sizeOf(v0) <= MAX_TRANSACTION_BYTES ? compileMessage(v0) : null;
 }
 
+/**
+ * The message for a transaction that has two forms, `led` (the instructions with something put first for a wallet's
+ * sake: a compute budget) and `plain` (without it), keeping the kind of transaction `plain` alone would be: legacy
+ * when `plain` fits one (led when that fits too), else v0 with `tables` (led when that fits). null when neither fits.
+ */
+export function compileKeepingKind({ payer, blockhash, led, plain, tables = [] }) {
+  const legacy = instructions => compileFitting({ payer, blockhash, instructions });
+  const loaded = instructions => compileFitting({ payer, blockhash, instructions, tables });
+  return legacy(led) ?? legacy(plain) ?? loaded(led) ?? loaded(plain);
+}
+
 /**
  * The plan for sending `instructions` from `payer` as v0 with a table of their accounts made at `slot`, `first` the
  * addresses it holds first:

package/js/chain/programs.js

@@ -2,7 +2,7 @@
 //   { programId: base58, keys: [{ pubkey, isSigner, isWritable }], data: Uint8Array }
 // shared by browser apps and Node, which both serialize it with chain/tx.js.
 import { addressBytes } from './base58.js';
-import { concat, uintLE } from './bytes.js';
+import { concat, readUintLE, uintLE } from './bytes.js';
 import {
   ASSOCIATED_TOKEN_PROGRAM,
   associatedTokenAddress,
@@ -53,6 +53,54 @@ export const computeUnitPrice = microLamports => ({
   data: concat(Uint8Array.of(SET_COMPUTE_UNIT_PRICE), uintLE(microLamports, 8)),
 });
 
+/** Whether `ix` sets the transaction's compute unit limit. */
+export const isComputeUnitLimit = ix =>
+  ix.programId === COMPUTE_BUDGET_PROGRAM && ix.data[0] === SET_COMPUTE_UNIT_LIMIT;
+
+/** Whether `ix` sets the transaction's compute unit price (its priority fee). */
+export const isComputeUnitPrice = ix =>
+  ix.programId === COMPUTE_BUDGET_PROGRAM && ix.data[0] === SET_COMPUTE_UNIT_PRICE;
+
+/** The compute units a transaction has for each instruction when it sets no limit, and the most it may ask for. */
+const DEFAULT_UNITS_AN_INSTRUCTION = 200_000n;
+const MOST_UNITS = 1_400_000n;
+const MICRO_LAMPORTS = 1_000_000n;
+
+/**
+ * `instructions` led by the transaction's Compute Budget instructions: its unit limit, its unit price, then any other
+ * (a heap frame). A limit or a price it already carries is kept as it is; the one it lacks is added (`units`,
+ * `microLamports` a unit). The rest keep their order.
+ *
+ * A wallet that adds its own priority fee (Phantom does) adds it only to a transaction that sets neither, so one
+ * built this way comes back from the wallet with the message it was given.
+ */
+export function withComputeBudget(instructions, { units, microLamports }) {
+  const budget = instructions.filter(ix => ix.programId === COMPUTE_BUDGET_PROGRAM);
+  const limits = budget.filter(isComputeUnitLimit);
+  const prices = budget.filter(isComputeUnitPrice);
+  return [
+    ...(limits.length ? limits : [computeUnitLimit(units)]),
+    ...(prices.length ? prices : [computeUnitPrice(microLamports)]),
+    ...budget.filter(ix => !isComputeUnitLimit(ix) && !isComputeUnitPrice(ix)),
+    ...instructions.filter(ix => ix.programId !== COMPUTE_BUDGET_PROGRAM),
+  ];
+}
+
+/**
+ * The priority fee of a transaction of `instructions`, in lamports: its unit limit times its unit price (in
+ * micro-lamports a unit), rounded up to a whole lamport as the network does. 0n when it sets no price. With no limit
+ * set, the limit is taken at its most: 200,000 units for each other instruction, 1,400,000 at most.
+ */
+export function priorityFee(instructions) {
+  const price = instructions.find(isComputeUnitPrice);
+  if (!price) return 0n;
+  const limit = instructions.find(isComputeUnitLimit);
+  const others = BigInt(instructions.filter(ix => ix.programId !== COMPUTE_BUDGET_PROGRAM).length);
+  const byDefault = DEFAULT_UNITS_AN_INSTRUCTION * others;
+  const units = limit ? readUintLE(limit.data, 1, 4) : byDefault < MOST_UNITS ? byDefault : MOST_UNITS;
+  return (units * readUintLE(price.data, 1, 8) + MICRO_LAMPORTS - 1n) / MICRO_LAMPORTS;
+}
+
 /** Create `owner`'s token account for `mint` unless it already exists; `payer` pays the rent. */
 export function createAssociatedTokenAccountIdempotent(payer, owner, mint, tokenProgram = TOKEN_PROGRAM) {
   return {