@xgamesfun/solana 0.0.0-stage → 0.24.0

package/js/chain/rpc.js

@@ -0,0 +1,219 @@
+// The Solana JSON-RPC calls this kit makes, over fetch, for browser apps and Node alike. Public RPCs rate-limit
+// (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';
+
+// 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>} */ ({}));
+
+const TIMEOUT_MS = 20_000;
+const RETRIES = 4;
+// A rate limit is waited out longer than a failed connection: about a minute in all, with jitter so pages and
+// servers sharing an IP don't retry in step.
+const RATE_LIMIT_RETRIES = 7;
+const CONFIRM_POLL_MS = 1200;
+const CONFIRM_TIMEOUT_MS = 90_000;
+const ACCOUNTS_PER_CALL = 100;
+/** The HTTP statuses of a gateway that failed for a moment (bad gateway, unavailable, timed out): retried. */
+const PASSING = [502, 503, 504];
+/** The JSON-RPC errors of a node behind the cluster: retried. */
+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) {
+    super(message);
+    this.name = 'RpcError';
+    this.code = code;
+    this.logs = logs;
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** The first block of each public Solana cluster: it names the cluster whatever URL reaches it. */
+export const GENESIS = Object.freeze({
+  devnet: 'EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG',
+  mainnet: '5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d',
+  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.';
+
+/** 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}`);
+  return url;
+}
+
+/**
+ * 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.
+ */
+export async function checkCluster(rpc) {
+  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}`);
+  return genesis;
+}
+const decodeAccount = (raw) =>
+  raw ? { owner: raw.owner, lamports: raw.lamports, data: fromBase64(raw.data[0]), executable: raw.executable } : null;
+
+/** The program's own words for a failed run (`AnchorError … Error Message: …`), else the last error log line. A program
+ * built without its errors' text logs the error's name as its message: then the name alone (the client's IDL has
+ * the sentence: `loot.lootError`). */
+export function programError(err, logs) {
+  const anchor = logs?.find((line) => line.includes('AnchorError'));
+  const said = anchor ? /Error Message: (.+?)\.?$/.exec(anchor)?.[1] : undefined;
+  const code = anchor ? /Error Code: (\w+)/.exec(anchor)?.[1] : undefined;
+  const last = logs?.filter((l) => /error|failed|insufficient/i.test(l)).at(-1);
+  if (said) return code && code !== said ? `${said} (${code})` : said;
+  return last ?? (typeof err === 'string' ? err : JSON.stringify(err));
+}
+
+/** 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 = []) {
+    for (let attempt = 0; ; attempt++) {
+      let response;
+      try {
+        response = await fetchImpl(url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ jsonrpc: '2.0', id: ++id, method, params }),
+          signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+      } catch (error) {
+        if (attempt < RETRIES) {
+          await sleepImpl(500 * 2 ** attempt);
+          continue;
+        }
+        throw new RpcError(`RPC ${method} did not answer: ${error.message}`);
+      }
+      if (response.status === 429 && attempt < RATE_LIMIT_RETRIES) {
+        const after = Number(response.headers?.get?.('retry-after'));
+        await sleepImpl(after > 0 ? after * 1000 : Math.min(1000 * 2 ** attempt, 15_000) * (0.75 + Math.random() / 2));
+        continue;
+      }
+      // Sending the same signed transaction again is safe: it has one signature, so it lands once at most.
+      if (PASSING.includes(response.status) && attempt < RETRIES) {
+        await sleepImpl(500 * 2 ** attempt);
+        continue;
+      }
+      const body = await response.json().catch(() => null);
+      if (!response.ok || !body || body.error) {
+        const message = body?.error?.message ?? `RPC ${method} failed (HTTP ${response.status})`;
+        if (body?.error?.code === 429 && attempt < RETRIES) {
+          await sleepImpl(1000 * 2 ** attempt);
+          continue;
+        }
+        // A node of a load-balanced RPC a moment behind: "No confirmed state available yet" (-32005), "Minimum context
+        // slot has not been reached" (-32016). Asked again, another (or the same, caught up) answers.
+        if (BEHIND.includes(body?.error?.code) && 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 });
+      }
+      return body.result;
+    }
+  }
+
+  async function accounts(addresses, commitment = 'confirmed', { minContextSlot } = NO_OPTIONS) {
+    const out = [];
+    for (let i = 0; i < addresses.length; i += ACCOUNTS_PER_CALL) {
+      const batch = addresses.slice(i, i + ACCOUNTS_PER_CALL);
+      const r = await call('getMultipleAccounts', [batch, { encoding: 'base64', commitment, ...(minContextSlot != null ? { minContextSlot: Number(minContextSlot) } : {}) }]);
+      out.push(...r.value.map(decodeAccount));
+    }
+    return out;
+  }
+
+  async function signatureStatus(signature) {
+    const r = await call('getSignatureStatuses', [[signature], { searchTransactionHistory: false }]);
+    return r.value[0];
+  }
+
+  return {
+    url,
+    call,
+    /** Accounts as of `commitment`; `minContextSlot`: from a node that has seen at least that slot (one's own landed send). */
+    accounts,
+    async account(address, commitment = 'confirmed', options = {}) {
+      return (await accounts([address], commitment, options))[0];
+    },
+    async latestBlockhash() {
+      const r = await call('getLatestBlockhash', [{ commitment: 'confirmed' }]);
+      return { blockhash: r.value.blockhash, lastValidBlockHeight: r.value.lastValidBlockHeight };
+    },
+    async blockHeight() {
+      return call('getBlockHeight', [{ commitment: 'confirmed' }]);
+    },
+    async balance(address) {
+      return BigInt((await call('getBalance', [address, { commitment: 'confirmed' }])).value);
+    },
+    /**
+     * A token account's balance in base units, or 0n when there is no account there. Any other refusal throws: an
+     * address that is not a token account (a wallet's, passed by mistake: "Invalid param: not a Token account") is
+     * not an empty one.
+     */
+    async tokenBalance(tokenAccount) {
+      try {
+        return BigInt((await call('getTokenAccountBalance', [tokenAccount, { commitment: 'confirmed' }])).value.amount);
+      } catch (error) {
+        if (/could not find account|account not found/i.test(error.message)) return 0n;
+        throw error;
+      }
+    },
+    async programAccounts(program, filters) {
+      const r = await call('getProgramAccounts', [program, { encoding: 'base64', commitment: 'confirmed', filters }]);
+      return r.map((x) => ({ pubkey: x.pubkey, account: decodeAccount(x.account) }));
+    },
+    /**
+     * Dry-run a wire transaction (empty signature slots are fine). Throws with the program's reason when it fails.
+     * `accounts`: addresses whose state after the run to return (base64-decoded, or null).
+     */
+    async simulate(wire, { accounts: watch = [], replaceBlockhash = false } = {}) {
+      const r = await call('simulateTransaction', [
+        toBase64(wire),
+        {
+          encoding: 'base64',
+          sigVerify: false,
+          replaceRecentBlockhash: replaceBlockhash,
+          commitment: 'confirmed',
+          ...(watch.length ? { accounts: { encoding: 'base64', addresses: watch } } : {}),
+        },
+      ]);
+      const value = r.value;
+      if (value.err) throw new RpcError(`The network refused this in a dry run: ${programError(value.err, value.logs)}`, { logs: value.logs });
+      return { unitsConsumed: value.unitsConsumed ?? null, logs: value.logs ?? [], accounts: (value.accounts ?? []).map(decodeAccount) };
+    },
+    async send(wire) {
+      return call('sendTransaction', [toBase64(wire), { encoding: 'base64', preflightCommitment: 'confirmed', maxRetries: 3 }]);
+    },
+    signatureStatus,
+    /** Wait until a sent transaction is confirmed; throws with the program's reason when it failed. */
+    async confirm(signature, { timeoutMs = CONFIRM_TIMEOUT_MS, lastValidBlockHeight = null } = {}) {
+      const deadline = Date.now() + timeoutMs;
+      for (let poll = 0; Date.now() < deadline; poll++) {
+        const status = await signatureStatus(signature);
+        if (status?.err) {
+          const tx = await call('getTransaction', [signature, { commitment: 'confirmed', maxSupportedTransactionVersion: 0 }]).catch(() => null);
+          throw new RpcError(`Transaction ${signature} failed: ${programError(status.err, tx?.meta?.logMessages)}`, { logs: tx?.meta?.logMessages });
+        }
+        if (status?.confirmationStatus === 'confirmed' || status?.confirmationStatus === 'finalized') return signature;
+        if (lastValidBlockHeight !== null && poll % 5 === 4) {
+          const height = await call('getBlockHeight', [{ commitment: 'confirmed' }]).catch(() => 0);
+          if (height > lastValidBlockHeight) throw new RpcError(`Transaction ${signature} expired before it landed. Try again.`);
+        }
+        await sleepImpl(CONFIRM_POLL_MS);
+      }
+      throw new RpcError(`Transaction ${signature} was not confirmed in time; check it in the explorer.`);
+    },
+  };
+}

package/js/chain/sha256.js

@@ -0,0 +1,68 @@
+// SHA-256 (FIPS 180-4), synchronous. Program addresses are derived in browser apps and Node alike, and WebCrypto's
+// digest is asynchronous and missing outside secure contexts, so this carries its own.
+
+const K = Uint32Array.from([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5, 0xd807aa98,
+  0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+  0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8,
+  0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819,
+  0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+  0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+  0xc67178f2,
+]);
+const INITIAL = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
+const BLOCK_BYTES = 64;
+
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+
+/** The message padded to whole 64-byte blocks, with its bit length at the end. */
+function padded(message) {
+  const length = Math.ceil((message.length + 9) / BLOCK_BYTES) * BLOCK_BYTES;
+  const out = new Uint8Array(length);
+  out.set(message);
+  out[message.length] = 0x80;
+  const view = new DataView(out.buffer);
+  const bits = message.length * 8;
+  view.setUint32(length - 8, Math.floor(bits / 2 ** 32));
+  view.setUint32(length - 4, bits >>> 0);
+  return out;
+}
+
+function compress(state, view, offset, w) {
+  for (let i = 0; i < 16; i++) w[i] = view.getUint32(offset + i * 4);
+  for (let i = 16; i < 64; i++) {
+    const a = w[i - 15];
+    const b = w[i - 2];
+    const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+    const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+    w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+  }
+  let [a, b, c, d, e, f, g, h] = state;
+  for (let i = 0; i < 64; i++) {
+    const t1 = (h + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i]) >>> 0;
+    const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) >>> 0;
+    h = g;
+    g = f;
+    f = e;
+    e = (d + t1) >>> 0;
+    d = c;
+    c = b;
+    b = a;
+    a = (t1 + t2) >>> 0;
+  }
+  const next = [a, b, c, d, e, f, g, h];
+  for (let i = 0; i < 8; i++) state[i] = (state[i] + next[i]) >>> 0;
+}
+
+export function sha256(message) {
+  const data = padded(message);
+  const view = new DataView(data.buffer);
+  const state = [...INITIAL];
+  const w = new Uint32Array(64);
+  for (let offset = 0; offset < data.length; offset += BLOCK_BYTES) compress(state, view, offset, w);
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  state.forEach((word, i) => outView.setUint32(i * 4, word));
+  return out;
+}

package/js/chain/token.js

@@ -0,0 +1,85 @@
+// The System and SPL Token instructions a project's setup needs (a new mint, its first tokens, handing its authority to
+// the project), as plain data. Classic Token and Token-2022 share these layouts.
+import { addressBytes } from './base58.js';
+import { concat, uintLE, utf8 } from './bytes.js';
+import { SYSTEM_PROGRAM, TOKEN_PROGRAM } from './pda.js';
+import { meta } from './programs.js';
+
+/** A classic mint's size. */
+export const MINT_BYTES = 82;
+/** A classic token account's size. */
+export const TOKEN_ACCOUNT_BYTES = 165;
+
+/** System `CreateAccount`: `from` pays `lamports` for `space` bytes at `address` (which signs), owned by `owner`. */
+export function createAccountIx({ from, address, lamports, space, owner }) {
+  return {
+    programId: SYSTEM_PROGRAM,
+    keys: [meta(from, true, true), meta(address, true, true)],
+    data: concat(uintLE(0, 4), uintLE(lamports, 8), uintLE(space, 8), addressBytes(owner)),
+  };
+}
+
+/**
+ * System `CreateAccountWithSeed`: `from` pays `lamports` for `space` bytes at `addressWithSeed(from, seed, owner)`, owned
+ * by `owner`. `from` is the base too, so it alone signs.
+ */
+export function createAccountWithSeedIx({ from, address, seed, lamports, space, owner }) {
+  const text = utf8(seed);
+  return {
+    programId: SYSTEM_PROGRAM,
+    keys: [meta(from, true, true), meta(address, false, true)],
+    data: concat(uintLE(3, 4), addressBytes(from), uintLE(text.length, 8), text, uintLE(lamports, 8), uintLE(space, 8), addressBytes(owner)),
+  };
+}
+
+/**
+ * System `AllocateWithSeed`: the account at `addressWithSeed(base, seed, owner)`, which holds only lamports (System's, no
+ * data), gets `space` bytes and becomes `owner`'s. `base` alone signs. Unlike `CreateAccountWithSeed` it takes an address
+ * someone already sent lamports to; whoever pays tops it up to the rent first (a System transfer).
+ */
+export function allocateWithSeedIx({ base, address, seed, space, owner }) {
+  const text = utf8(seed);
+  return {
+    programId: SYSTEM_PROGRAM,
+    keys: [meta(address, false, true), meta(base, true, false)],
+    data: concat(uintLE(9, 4), addressBytes(base), uintLE(text.length, 8), text, uintLE(space, 8), addressBytes(owner)),
+  };
+}
+
+/** Token `InitializeAccount3`: `account` (made empty first) becomes a token account of `mint` that `owner` holds. */
+export const initializeAccount3Ix = ({ account, mint, owner, tokenProgram = TOKEN_PROGRAM }) => ({
+  programId: tokenProgram,
+  keys: [meta(account, false, true), meta(mint, false, false)],
+  data: concat(Uint8Array.of(18), addressBytes(owner)),
+});
+
+/** Token `InitializeMint2`. */
+export function initializeMint2Ix({ mint, decimals, authority, freezeAuthority = null, tokenProgram = TOKEN_PROGRAM }) {
+  const freeze = freezeAuthority ? concat(Uint8Array.of(1), addressBytes(freezeAuthority)) : Uint8Array.of(0);
+  return {
+    programId: tokenProgram,
+    keys: [meta(mint, false, true)],
+    data: concat(Uint8Array.of(20, decimals), addressBytes(authority), freeze),
+  };
+}
+
+/** Token `MintTo`: `authority` (the mint authority, which signs) mints `amount` into the token account `to`. */
+export const mintToIx = ({ mint, to, authority, amount, tokenProgram = TOKEN_PROGRAM }) => ({
+  programId: tokenProgram,
+  keys: [meta(mint, false, true), meta(to, false, true), meta(authority, true, false)],
+  data: concat(Uint8Array.of(7), uintLE(amount, 8)),
+});
+
+/** Token `TransferChecked`. */
+export const transferCheckedIx = ({ from, mint, to, owner, amount, decimals, tokenProgram = TOKEN_PROGRAM }) => ({
+  programId: tokenProgram,
+  keys: [meta(from, false, true), meta(mint, false, false), meta(to, false, true), meta(owner, true, false)],
+  data: concat(Uint8Array.of(12), uintLE(amount, 8), Uint8Array.of(decimals)),
+});
+
+/** Token `SetAuthority` of a mint's minting (`kind` 0) or freezing (1) to `newAuthority` (null: none). */
+export const setAuthorityIx = ({ account, current, kind = 0, newAuthority, tokenProgram = TOKEN_PROGRAM }) => ({
+  programId: tokenProgram,
+  keys: [meta(account, false, true), meta(current, true, false)],
+  data: concat(Uint8Array.of(6, kind), newAuthority ? concat(Uint8Array.of(1), addressBytes(newAuthority)) : Uint8Array.of(0)),
+});

package/js/chain/token2022.js

@@ -0,0 +1,247 @@
+// What a Token-2022 transfer needs beyond the transfer itself, read from the mint. The loot program moves every token
+// with TransferChecked and hands each Token-2022 transfer the instruction's remaining accounts,
+// so the caller passes:
+//   - the Memo program, which the program calls first when the receiving account requires a memo. It is always passed
+//     for a Token-2022 mint: any receiver can turn memos on between the moment a transaction is built and the moment
+//     it lands, and one account more costs nothing;
+//   - for a mint with a transfer hook: the hook program, its list of extra accounts ("extra-account-metas", mint) and
+//     every account that list names, resolved here as spl-transfer-hook-interface does. Token-2022 takes the ones its
+//     hook names by address and ignores the rest. The hook never gets a signature: every account is passed unsigned.
+// Classic SPL mints need none of it.
+import { addressBytes, encodeBase58, NO_ADDRESS } from './base58.js';
+import { concat, readUintLE, uintLE, utf8 } from './bytes.js';
+import { pdaOf, TOKEN_PROGRAM, TOKEN_2022_PROGRAM } from './pda.js';
+import { meta } from './programs.js';
+import { MINT_BYTES, TOKEN_ACCOUNT_BYTES } from './token.js';
+
+export const MEMO_PROGRAM = 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr';
+/** The hook interface's Execute instruction: its discriminator, then the amount (u64). */
+export const EXECUTE_DISCRIMINATOR = Uint8Array.of(105, 37, 101, 197, 75, 251, 102, 26);
+
+const ACCOUNT_TYPE_MINT = 1;
+const EXTENSION = { DefaultAccountState: 6, MemoTransfer: 8, PermanentDelegate: 12, TransferHook: 14, PausableConfig: 26 };
+const META_BYTES = 35;
+
+function checkedSlice(data, at, length, what) {
+  if (!Number.isInteger(at) || !Number.isInteger(length) || at < 0 || length < 0 || at + length > data.length) throw new RangeError(`${what} runs past the data`);
+  return data.subarray(at, at + length);
+}
+
+/** The value of extension `type` in a Token-2022 mint or account, or null. */
+export function extension(data, type) {
+  let at = TOKEN_ACCOUNT_BYTES + 1;
+  while (at + 4 <= data.length) {
+    const kind = Number(readUintLE(data, at, 2));
+    const length = Number(readUintLE(data, at + 2, 2));
+    if (at + 4 + length > data.length) throw new RangeError('extension runs past the data');
+    if (kind === type) return checkedSlice(data, at + 4, length, 'extension');
+    if (kind === 0) return null;
+    at += 4 + length;
+  }
+  return null;
+}
+
+/** The transfer hook program a Token-2022 mint names, or null. */
+export function hookProgramOf(mintData) {
+  if (mintData.length <= TOKEN_ACCOUNT_BYTES || mintData[TOKEN_ACCOUNT_BYTES] !== ACCOUNT_TYPE_MINT) return null;
+  const value = extension(mintData, EXTENSION.TransferHook);
+  if (!value || value.length < 64) return null;
+  const program = encodeBase58(value.subarray(32, 64));
+  return program === NO_ADDRESS ? null : program;
+}
+
+/**
+ * Whether a mint's new accounts start frozen, or can be made to (as the program judges it): a Token-2022
+ * mint carrying `DefaultAccountState` set to frozen, or set to anything while it has a freeze authority, which can switch
+ * it to frozen whenever it likes. An auction, a contest, a lottery, an offer and a sealed schedule refuse such a mint:
+ * each reads the setting once, as it opens, and a refund or payout opened into a frozen account would never land.
+ */
+export function mayStartFrozen({ owner, data }) {
+  if (owner !== TOKEN_2022_PROGRAM || data.length <= TOKEN_ACCOUNT_BYTES || data[TOKEN_ACCOUNT_BYTES] !== ACCOUNT_TYPE_MINT) return false;
+  const state = extension(data, EXTENSION.DefaultAccountState);
+  if (!state) return false;
+  const freezer = data.length >= 50 && readUintLE(data, 46, 4) !== 0n;
+  return state[0] === 2 || freezer;
+}
+
+/**
+ * Who can stop a mint's tokens moving, read from its account (`owner`, its token program; `data`): its freeze authority
+ * (it can freeze any account of the mint), a Token-2022 pause (`PausableConfig`: its authority stops every transfer), a
+ * transfer hook (its program runs on every transfer and can refuse one), a permanent delegate (it can move anyone's
+ * tokens of the mint away). Each is [{ power, holder }], `holder` the address that has it. Empty for a plain mint.
+ */
+export function mintPowers({ owner, data }) {
+  const out = [];
+  if (owner !== TOKEN_PROGRAM && owner !== TOKEN_2022_PROGRAM) return out;
+  const option = (at) => (data.length >= at + 36 && readUintLE(data, at, 4) === 1n ? encodeBase58(data.subarray(at + 4, at + 36)) : null);
+  const freezer = option(46);
+  if (freezer) out.push({ power: 'freeze', holder: freezer });
+  if (owner !== TOKEN_2022_PROGRAM || data.length <= TOKEN_ACCOUNT_BYTES || data[TOKEN_ACCOUNT_BYTES] !== ACCOUNT_TYPE_MINT) return out;
+  const address = (value, at) => {
+    const a = value && value.length >= at + 32 ? encodeBase58(value.subarray(at, at + 32)) : null;
+    return a === NO_ADDRESS ? null : a;
+  };
+  const pause = extension(data, EXTENSION.PausableConfig);
+  if (pause) out.push({ power: 'pause', holder: address(pause, 0), paused: pause.length > 32 && pause[32] !== 0 });
+  const hook = hookProgramOf(data);
+  if (hook) out.push({ power: 'hook', holder: hook, authority: address(extension(data, EXTENSION.TransferHook), 0) });
+  const delegate = address(extension(data, EXTENSION.PermanentDelegate), 0);
+  if (delegate) out.push({ power: 'delegate', holder: delegate });
+  return out;
+}
+
+/** Whether a token account requires a memo on every transfer into it. */
+export function requiresMemo(accountData) {
+  const value = accountData.length > TOKEN_ACCOUNT_BYTES ? extension(accountData, EXTENSION.MemoTransfer) : null;
+  return Boolean(value?.length && value[0] !== 0);
+}
+
+/** The hook's list of extra accounts for this mint. */
+export const validationAddress = (mint, hookProgram) => pdaOf([utf8('extra-account-metas'), addressBytes(mint)], hookProgram);
+
+/** The ExtraAccountMeta entries of an "extra-account-metas" account: [{ discriminator, config, isSigner, isWritable }]. */
+export function readExtraMetas(data) {
+  let at = 0;
+  while (at + 12 <= data.length) {
+    const length = Number(readUintLE(data, at + 8, 4));
+    if (at + 12 + length > data.length) throw new RangeError('extra account entry runs past the data');
+    const isExecute = EXECUTE_DISCRIMINATOR.every((b, i) => data[at + i] === b);
+    if (isExecute) {
+      if (length < 4) throw new RangeError('extra account list is missing its count');
+      const count = Number(readUintLE(data, at + 12, 4));
+      if (4 + count * META_BYTES > length) throw new RangeError('extra account list runs past its entry');
+      return Array.from({ length: count }, (_, i) => {
+        const o = at + 16 + i * META_BYTES;
+        if (o + META_BYTES > at + 12 + length) throw new RangeError('extra account list runs past its entry');
+        return { discriminator: data[o], config: data.subarray(o + 1, o + 33), isSigner: data[o + 33] !== 0, isWritable: data[o + 34] !== 0 };
+      });
+    }
+    at += 12 + length;
+  }
+  throw new Error('The hook’s account list has no entry for transfers.');
+}
+
+/** The seeds a PDA entry packs into its 32 bytes: [{ literal } | { ixData: [index, length] } | { key: index } | { data: [account, at, length] }]. */
+function unpackSeeds(config) {
+  const seeds = [];
+  for (let at = 0; at < config.length && config[at] !== 0; ) {
+    const kind = config[at];
+    if (kind === 1) {
+      seeds.push({ literal: checkedSlice(config, at + 2, config[at + 1], 'literal seed') });
+      at += 2 + config[at + 1];
+    } else if (kind === 2) {
+      checkedSlice(config, at, 3, 'instruction seed');
+      seeds.push({ ixData: [config[at + 1], config[at + 2]] });
+      at += 3;
+    } else if (kind === 3) {
+      checkedSlice(config, at, 2, 'account key seed');
+      seeds.push({ key: config[at + 1] });
+      at += 2;
+    } else if (kind === 4) {
+      checkedSlice(config, at, 4, 'account data seed');
+      seeds.push({ data: [config[at + 1], config[at + 2], config[at + 3]] });
+      at += 4;
+    } else throw new Error(`The hook asks for an account by a seed this kit does not know (${kind}).`);
+  }
+  return seeds;
+}
+
+/**
+ * The extra accounts the hook names for one transfer: { source, destination, authority, amount } (amount a bigint).
+ * `read(address)` returns an account's data (or null), for seeds taken from account data.
+ */
+async function resolveFor(mint, hookProgram, validation, metas, transfer, read) {
+  const keys = [transfer.source, mint, transfer.destination, transfer.authority, validation];
+  const ixData = concat(EXECUTE_DISCRIMINATOR, uintLE(transfer.amount ?? 0n, 8));
+  const out = [];
+  for (const m of metas) {
+    if (m.isSigner) throw new Error('This transfer hook requires an additional signature.');
+    let address;
+    if (m.discriminator === 0) address = encodeBase58(m.config);
+    else if (m.discriminator === 1 || m.discriminator >= 128) {
+      const program = m.discriminator === 1 ? hookProgram : keys[m.discriminator - 128];
+      const seeds = [];
+      for (const s of unpackSeeds(m.config)) {
+        if (s.literal) seeds.push(s.literal);
+        else if (s.ixData) seeds.push(checkedSlice(ixData, s.ixData[0], s.ixData[1], 'instruction seed'));
+        else if (s.key !== undefined) seeds.push(addressBytes(keys[s.key]));
+        else {
+          const data = await read(keys[s.data[0]]);
+          if (!data) throw new Error(`The hook needs data from ${keys[s.data[0]]}, which does not exist yet.`);
+          seeds.push(checkedSlice(data, s.data[1], s.data[2], 'account data seed'));
+        }
+      }
+      if (!program) throw new Error('The hook names a program by an account it does not have.');
+      address = pdaOf(seeds, program);
+    } else throw new Error(`The hook asks for an account in a way this kit does not resolve (${m.discriminator}).`);
+    if (!address) throw new Error('The hook asks for an account this transfer does not have.');
+    keys.push(address);
+    out.push(meta(address, false, m.isWritable));
+  }
+  return out;
+}
+
+/** Whether the hook's list depends on which transfer it is (an account, the amount or account data). */
+const perTransfer = (metas) =>
+  metas.some((m) => m.discriminator >= 128 || (m.discriminator === 1 && unpackSeeds(m.config).some((s) => !s.literal && !(s.key === 1 || s.key === 4))));
+
+/**
+ * The accounts to append after an instruction's own remaining accounts so every transfer of `mint` it makes can run:
+ * [] for a classic mint; the Memo program, and for a hooked mint the hook's accounts, for a Token-2022 one.
+ * `transfers`: the transfers the instruction makes ({ source, destination, authority, amount }), needed only when the
+ * hook's list depends on them; the accounts of all of them are passed. `rpc` reads the mint and the hook's list.
+ */
+export async function transferExtras(rpc, mint, transfers = []) {
+  const [mintAccount] = await rpc.accounts([mint]);
+  if (!mintAccount) throw new Error(`There is no token ${mint} on this network.`);
+  if (mintAccount.owner === TOKEN_PROGRAM) return [];
+  if (mintAccount.owner !== TOKEN_2022_PROGRAM) throw new Error('The mint is not owned by a supported token program.');
+  const extras = [meta(MEMO_PROGRAM, false, false)];
+  const hookProgram = hookProgramOf(mintAccount.data);
+  if (!hookProgram) return extras;
+  const validation = validationAddress(mint, hookProgram);
+  const [list] = await rpc.accounts([validation]);
+  extras.push(meta(hookProgram, false, false), meta(validation, false, false));
+  if (!list) throw new Error('The transfer hook account list is missing.');
+  if (list.owner !== hookProgram) throw new Error('The transfer hook account list has the wrong owner.');
+  const metas = readExtraMetas(list.data);
+  const read = async (address) => (await rpc.accounts([address]))[0]?.data ?? null;
+  const cases = perTransfer(metas) ? transfers : [{ source: NO_ADDRESS, destination: NO_ADDRESS, authority: NO_ADDRESS, amount: 0n }];
+  if (!cases.length) throw new Error('This token’s transfer hook needs to know each transfer; pass them.');
+  for (const transfer of cases) for (const m of await resolveFor(mint, hookProgram, validation, metas, transfer, read)) extras.push(m);
+  // One entry per address; writable if any transfer needs it writable.
+  const merged = new Map();
+  for (const m of extras) merged.set(m.pubkey, merged.has(m.pubkey) ? { ...m, isWritable: m.isWritable || merged.get(m.pubkey).isWritable } : m);
+  return [...merged.values()];
+}
+
+/** Length of a newly created associated account, including Token-2022's immutable owner. */
+export function associatedAccountSize(mintAccount) {
+  if (mintAccount?.owner === TOKEN_PROGRAM) return TOKEN_ACCOUNT_BYTES;
+  if (mintAccount?.owner !== TOKEN_2022_PROGRAM) throw new Error('The mint is not owned by a supported token program.');
+  const data = mintAccount.data;
+  if (data.length !== MINT_BYTES && (data.length < TOKEN_ACCOUNT_BYTES + 1 || data[TOKEN_ACCOUNT_BYTES] !== ACCOUNT_TYPE_MINT)) throw new Error('Invalid Token-2022 mint layout.');
+  const required = new Map([[7, 0]]); // ImmutableOwner, set by the associated token program.
+  for (let at = TOKEN_ACCOUNT_BYTES + 1; at + 4 <= data.length;) {
+    const kind = Number(readUintLE(data, at, 2));
+    const length = Number(readUintLE(data, at + 2, 2));
+    if (kind === 0) break;
+    if (at + 4 + length > data.length || kind > 27) throw new Error('Unsupported or truncated mint extension.');
+    if (kind === 1) required.set(2, 8); // TransferFeeAmount
+    if (kind === 9) required.set(13, 0); // NonTransferableAccount
+    if (kind === 14) required.set(15, 1); // TransferHookAccount
+    if (kind === 26) required.set(27, 0); // PausableAccount
+    at += 4 + length;
+  }
+  const size = TOKEN_ACCOUNT_BYTES + 1 + [...required.values()].reduce((n, length) => n + 4 + length, 0);
+  return size === 355 ? size + 2 : size;
+}
+
+/** Shared browser/keeper resolution for all transfers of one mint, preserving role accounts before extras. */
+export async function resolveTransfers(rpc, mint, transfers = []) {
+  const [account] = await rpc.accounts([mint]);
+  if (!account) throw new Error(`There is no token ${mint} on this network.`);
+  const accountSize = associatedAccountSize(account);
+  const cached = { accounts: async (keys) => keys.length === 1 && keys[0] === mint ? [account] : rpc.accounts(keys) };
+  return { tokenProgram: account.owner, accountSize, extraAccounts: await transferExtras(cached, mint, transfers) };
+}