@vtx-labs/solana-explain 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,3317 @@
+#!/usr/bin/env node
+import { parseArgs } from 'util';
+import { readFile } from 'fs/promises';
+import { pathToFileURL } from 'url';
+import process from 'process';
+import bs58 from 'bs58';
+
+// src/errors.ts
+var SolanaExplainError = class extends Error {
+  code;
+  cause;
+  /** Optional, CLI-friendly remediation hint. */
+  hint;
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    if (options.cause !== void 0) this.cause = options.cause;
+    if (options.hint !== void 0) this.hint = options.hint;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var RpcError = class extends SolanaExplainError {
+};
+var DecodeError = class extends SolanaExplainError {
+};
+var SimulationError = class extends SolanaExplainError {
+  /** Partial result when the simulation ran but reverted. */
+  result;
+  /** Tail of the node's program logs, for diagnostics. */
+  logs;
+  constructor(code, message, options = {}) {
+    super(code, message, options);
+    if (options.result !== void 0) this.result = options.result;
+    if (options.logs !== void 0) this.logs = options.logs;
+  }
+};
+var InputError = class extends SolanaExplainError {
+};
+function wrapError(err, fallbackCode, fallbackMessage) {
+  if (err instanceof SolanaExplainError) return err;
+  if (isAbortError(err)) {
+    return new RpcError("ABORTED", "The operation was aborted.", { cause: err });
+  }
+  const detail = err instanceof Error ? err.message : String(err);
+  return new SolanaExplainError(fallbackCode, `${fallbackMessage}: ${detail}`, { cause: err });
+}
+function isAbortError(err) {
+  return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+}
+function decodeBase58(input) {
+  try {
+    return bs58.decode(input);
+  } catch (err) {
+    throw new InputError("INVALID_ENCODING", "Input is not valid base58.", { cause: err });
+  }
+}
+function encodeBase58(bytes) {
+  return bs58.encode(bytes);
+}
+function tryDecodeBase58(input) {
+  try {
+    const out = bs58.decode(input);
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}
+var BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+function decodeBase64(input) {
+  const trimmed = input.trim();
+  if (!BASE64_RE.test(trimmed) || trimmed.length % 4 !== 0) {
+    throw new InputError("INVALID_ENCODING", "Input is not valid base64.");
+  }
+  try {
+    return new Uint8Array(Buffer.from(trimmed, "base64"));
+  } catch (err) {
+    throw new InputError("INVALID_ENCODING", "Input is not valid base64.", { cause: err });
+  }
+}
+function tryDecodeBase64(input) {
+  const trimmed = input.trim();
+  if (trimmed.length === 0 || trimmed.length % 4 !== 0 || !BASE64_RE.test(trimmed)) return null;
+  try {
+    const buf = Buffer.from(trimmed, "base64");
+    if (buf.length === 0) return null;
+    if (buf.toString("base64") !== trimmed) return null;
+    return new Uint8Array(buf);
+  } catch {
+    return null;
+  }
+}
+function encodeBase64(bytes) {
+  return Buffer.from(bytes).toString("base64");
+}
+function looksLikeBase64(input) {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) return false;
+  if (/[+/=]/.test(trimmed)) return true;
+  return BASE64_RE.test(trimmed);
+}
+function looksLikeBase58(input) {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) return false;
+  return /^[1-9A-HJ-NP-Za-km-z]+$/.test(trimmed);
+}
+function normalizeRpcUrl(url) {
+  let u = url.trim();
+  if (u.length === 0) {
+    throw new InputError("INVALID_INPUT", "RPC URL is empty.");
+  }
+  if (!/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(u)) {
+    u = `https://${u}`;
+  }
+  try {
+    const parsed = new URL(u);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new InputError(
+        "INVALID_INPUT",
+        `Unsupported RPC URL scheme "${parsed.protocol}". Use http(s).`
+      );
+    }
+    return parsed.toString();
+  } catch (err) {
+    if (err instanceof InputError) throw err;
+    throw new InputError("INVALID_INPUT", `Invalid RPC URL: ${url}`, { cause: err });
+  }
+}
+
+// src/rpc/http.ts
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new RpcError("ABORTED", "Aborted while backing off."));
+      return;
+    }
+    const t = setTimeout(resolve, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new RpcError("ABORTED", "Aborted while backing off."));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function combineSignals(timeoutMs, external) {
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  const onExternalAbort = () => controller.abort();
+  if (external) {
+    if (external.aborted) controller.abort();
+    else external.addEventListener("abort", onExternalAbort, { once: true });
+  }
+  return {
+    signal: controller.signal,
+    timedOut: () => timedOut,
+    cleanup: () => {
+      clearTimeout(timer);
+      external?.removeEventListener("abort", onExternalAbort);
+    }
+  };
+}
+function createHttpRpc(url, opts = {}) {
+  const endpoint = normalizeRpcUrl(url);
+  const defaultTimeout = opts.timeoutMs ?? 3e4;
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new RpcError(
+      "RPC_HTTP",
+      "global fetch is not available; use Node 18+ or pass a fetch implementation."
+    );
+  }
+  let idCounter = 1;
+  async function call(method, params, timeoutMs, externalSignal) {
+    const body = { jsonrpc: "2.0", id: idCounter++, method, params };
+    let attempt = 0;
+    for (; ; ) {
+      const { signal, timedOut, cleanup } = combineSignals(timeoutMs, externalSignal);
+      let res;
+      try {
+        res = await fetchImpl(endpoint, {
+          method: "POST",
+          headers: { "content-type": "application/json", ...opts.headers },
+          body: JSON.stringify(body),
+          signal
+        });
+      } catch (err) {
+        cleanup();
+        if (timedOut()) {
+          throw new RpcError("RPC_TIMEOUT", `RPC request "${method}" timed out after ${timeoutMs}ms.`, {
+            cause: err,
+            hint: "Increase --timeout or check your RPC URL."
+          });
+        }
+        if (isAbortError(err) || externalSignal?.aborted) {
+          throw new RpcError("ABORTED", `RPC request "${method}" was aborted.`, { cause: err });
+        }
+        throw new RpcError("RPC_HTTP", `Network error calling "${method}": ${describeErr(err)}`, {
+          cause: err,
+          hint: "Check connectivity and that the RPC URL is reachable."
+        });
+      }
+      cleanup();
+      if (RETRY_STATUSES.has(res.status) && attempt < 1) {
+        attempt++;
+        const backoff = 250 + Math.floor(Math.random() * 400);
+        await sleep(backoff, externalSignal);
+        continue;
+      }
+      const text = await res.text();
+      if (!res.ok) {
+        throw new RpcError(
+          "RPC_HTTP",
+          `RPC HTTP ${res.status} ${res.statusText} for "${method}". Body: ${snippet(text)}`,
+          res.status === 429 ? { hint: "Public endpoints are rate-limited; use a dedicated RPC." } : {}
+        );
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch (err) {
+        throw new RpcError(
+          "RPC_JSON",
+          `RPC returned non-JSON for "${method}". Body: ${snippet(text)}`,
+          { cause: err, hint: "Is the RPC URL correct? A captive portal/HTML page may be intercepting." }
+        );
+      }
+      if (parsed.error) {
+        const msg = `${parsed.error.message} (code ${parsed.error.code})`;
+        if (/version|transaction version/i.test(parsed.error.message)) {
+          throw new RpcError("UNSUPPORTED_TX_VERSION", `RPC: ${msg}`, {
+            hint: "Raise --max-tx-version (e.g. 0) to fetch versioned transactions."
+          });
+        }
+        throw new RpcError("RPC_JSON", `JSON-RPC error for "${method}": ${msg}`);
+      }
+      return parsed.result;
+    }
+  }
+  return {
+    async getTransaction(sig, o) {
+      const config = {
+        encoding: "base64",
+        commitment: o.commitment ?? "confirmed"
+      };
+      if (o.maxSupportedTransactionVersion !== void 0) {
+        config["maxSupportedTransactionVersion"] = o.maxSupportedTransactionVersion;
+      }
+      return call(
+        "getTransaction",
+        [sig, config],
+        defaultTimeout,
+        o.signal
+      );
+    },
+    async simulateTransaction(txBase64, o) {
+      const config = {
+        encoding: "base64",
+        commitment: o.commitment ?? "confirmed",
+        sigVerify: o.sigVerify ?? false,
+        replaceRecentBlockhash: o.replaceRecentBlockhash ?? true
+      };
+      if (o.innerInstructions) config["innerInstructions"] = true;
+      if (o.accounts) {
+        config["accounts"] = {
+          addresses: o.accounts.addresses,
+          encoding: o.accounts.encoding ?? "jsonParsed"
+        };
+      }
+      return call(
+        "simulateTransaction",
+        [txBase64, config],
+        defaultTimeout,
+        o.signal
+      );
+    },
+    async getMultipleAccounts(addresses, o) {
+      if (addresses.length === 0) return [];
+      const config = {
+        commitment: o.commitment ?? "confirmed",
+        encoding: o.encoding ?? "jsonParsed"
+      };
+      const result = await call(
+        "getMultipleAccounts",
+        [addresses, config],
+        defaultTimeout,
+        o.signal
+      );
+      return result.value;
+    },
+    async getLatestBlockhash(o) {
+      const result = await call("getLatestBlockhash", [{ commitment: o?.commitment ?? "confirmed" }], defaultTimeout, o?.signal);
+      return result.value;
+    }
+  };
+}
+function snippet(text, n = 120) {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  return oneLine.length > n ? `${oneLine.slice(0, n)}\u2026` : oneLine;
+}
+function describeErr(err) {
+  if (err instanceof Error) {
+    const code = err.cause?.code;
+    return code ? `${err.message} (${code})` : err.message;
+  }
+  return String(err);
+}
+
+// src/decode/known-programs.ts
+var SYSTEM_PROGRAM_ID = "11111111111111111111111111111111";
+var TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+var TOKEN_2022_PROGRAM_ID = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+var ASSOCIATED_TOKEN_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+var MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+var MEMO_V1_PROGRAM_ID = "Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo";
+var COMPUTE_BUDGET_PROGRAM_ID = "ComputeBudget111111111111111111111111111111";
+var KNOWN_PROGRAMS = Object.freeze({
+  // Core / decoded
+  [SYSTEM_PROGRAM_ID]: { name: "System", kind: "system" },
+  [TOKEN_PROGRAM_ID]: { name: "SPL Token", kind: "token" },
+  [TOKEN_2022_PROGRAM_ID]: { name: "Token-2022", kind: "token-2022" },
+  [ASSOCIATED_TOKEN_PROGRAM_ID]: { name: "Associated Token Account", kind: "ata" },
+  [MEMO_PROGRAM_ID]: { name: "Memo", kind: "memo" },
+  [MEMO_V1_PROGRAM_ID]: { name: "Memo (v1)", kind: "memo" },
+  [COMPUTE_BUDGET_PROGRAM_ID]: { name: "Compute Budget", kind: "compute-budget" },
+  // Native
+  Stake11111111111111111111111111111111111111: { name: "Stake", kind: "stake" },
+  Vote111111111111111111111111111111111111111: { name: "Vote", kind: "vote" },
+  BPFLoaderUpgradeab1e11111111111111111111111: { name: "BPF Upgradeable Loader", kind: "loader" },
+  BPFLoader2111111111111111111111111111111111: { name: "BPF Loader 2", kind: "loader" },
+  AddressLookupTab1e1111111111111111111111111: {
+    name: "Address Lookup Table",
+    kind: "other"
+  },
+  // Metaplex
+  metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s: {
+    name: "Metaplex Token Metadata",
+    kind: "nft"
+  },
+  BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY: {
+    name: "Metaplex Bubblegum",
+    kind: "nft"
+  },
+  cndy3Z4yxLzowg4ZTHTHJYjBmtkk3vd6yMJ4r8x7q3o: {
+    name: "Metaplex Candy Machine",
+    kind: "nft"
+  },
+  // Aggregators / DEX
+  JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4: { name: "Jupiter v6", kind: "aggregator" },
+  JUP4Fb2cqiRUcaTHdrPC8h2gNsA2ETXiPDD33WconZX: { name: "Jupiter v4", kind: "aggregator" },
+  "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8": { name: "Raydium AMM v4", kind: "amm" },
+  CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK: { name: "Raydium CLMM", kind: "amm" },
+  whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc: { name: "Orca Whirlpool", kind: "amm" },
+  "9W959DqEETiGZocYWCQPaJ6sBmUzgfxXfqGeTEdp3aQP": { name: "Orca v2", kind: "amm" },
+  PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY: { name: "Phoenix", kind: "amm" },
+  LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo: { name: "Meteora DLMM", kind: "amm" }
+});
+function knownProgram(programId) {
+  return KNOWN_PROGRAMS[programId];
+}
+
+// src/decode/reader.ts
+var Reader = class {
+  view;
+  bytes;
+  offset = 0;
+  constructor(bytes) {
+    this.bytes = bytes;
+    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  }
+  get remaining() {
+    return this.bytes.length - this.offset;
+  }
+  ensure(n, field) {
+    if (this.offset + n > this.bytes.length) {
+      throw new DecodeError(
+        "DECODE_FAILED",
+        `unexpected end while reading ${field} (need ${n} bytes at offset ${this.offset}, have ${this.remaining})`
+      );
+    }
+  }
+  u8(field = "u8") {
+    this.ensure(1, field);
+    const v = this.view.getUint8(this.offset);
+    this.offset += 1;
+    return v;
+  }
+  u16(field = "u16") {
+    this.ensure(2, field);
+    const v = this.view.getUint16(this.offset, true);
+    this.offset += 2;
+    return v;
+  }
+  u32(field = "u32") {
+    this.ensure(4, field);
+    const v = this.view.getUint32(this.offset, true);
+    this.offset += 4;
+    return v;
+  }
+  u64(field = "u64") {
+    this.ensure(8, field);
+    const v = this.view.getBigUint64(this.offset, true);
+    this.offset += 8;
+    return v;
+  }
+  i64(field = "i64") {
+    this.ensure(8, field);
+    const v = this.view.getBigInt64(this.offset, true);
+    this.offset += 8;
+    return v;
+  }
+  bytes_(n, field = "bytes") {
+    this.ensure(n, field);
+    const out = this.bytes.subarray(this.offset, this.offset + n);
+    this.offset += n;
+    return out;
+  }
+  /** Read a 32-byte pubkey and return base58. */
+  pubkey(field = "pubkey") {
+    return encodeBase58(this.bytes_(32, field));
+  }
+  /**
+   * Solana compact-u16 (a.k.a. ShortVec) length prefix. 1–3 bytes, 7 bits each.
+   */
+  compactU16(field = "compact-u16") {
+    let value = 0;
+    let shift = 0;
+    for (let i = 0; i < 3; i++) {
+      const byte = this.u8(`${field} length byte`);
+      value |= (byte & 127) << shift;
+      if ((byte & 128) === 0) return value >>> 0;
+      shift += 7;
+    }
+    return value >>> 0;
+  }
+  /** Remaining bytes (no copy). */
+  rest() {
+    const out = this.bytes.subarray(this.offset);
+    this.offset = this.bytes.length;
+    return out;
+  }
+};
+
+// src/decode/programs/system.ts
+function acc(ix, i) {
+  return ix.accounts[i]?.pubkey;
+}
+function decodeSystem(ix) {
+  if (ix.data.length < 4) {
+    return { decoded: false, program: "System", warning: "instruction data too short" };
+  }
+  const r = new Reader(ix.data);
+  const disc = r.u32("discriminator");
+  try {
+    switch (disc) {
+      case 0: {
+        const lamports = r.u64("lamports");
+        const space = r.u64("space");
+        const owner = r.pubkey("owner");
+        const newAccount = acc(ix, 1) ?? "";
+        return {
+          program: "System",
+          type: "createAccount",
+          decoded: true,
+          args: { lamports: lamports.toString(), space: space.toString(), owner },
+          accountNames: ["funding", "new"],
+          effects: [
+            {
+              kind: "account-created",
+              address: newAccount,
+              owner,
+              lamports,
+              space: Number(space),
+              as: "system"
+            }
+          ]
+        };
+      }
+      case 1: {
+        const owner = r.pubkey("owner");
+        return {
+          program: "System",
+          type: "assign",
+          decoded: true,
+          args: { owner },
+          accountNames: ["account"]
+        };
+      }
+      case 2: {
+        const lamports = r.u64("lamports");
+        const from = acc(ix, 0) ?? "";
+        const to = acc(ix, 1) ?? "";
+        return {
+          program: "System",
+          type: "transfer",
+          decoded: true,
+          args: { lamports: lamports.toString() },
+          accountNames: ["from", "to"],
+          effects: [{ kind: "sol-transfer", from, to, lamports }]
+        };
+      }
+      case 3: {
+        const base = r.pubkey("base");
+        const seedLen = Number(r.u64("seed length"));
+        const seed = new TextDecoder().decode(r.bytes_(seedLen, "seed"));
+        const lamports = r.u64("lamports");
+        const space = r.u64("space");
+        const owner = r.pubkey("owner");
+        const newAccount = acc(ix, 1) ?? "";
+        return {
+          program: "System",
+          type: "createAccountWithSeed",
+          decoded: true,
+          args: { base, seed, lamports: lamports.toString(), space: space.toString(), owner },
+          accountNames: ["funding", "new", "base"],
+          effects: [
+            {
+              kind: "account-created",
+              address: newAccount,
+              owner,
+              lamports,
+              space: Number(space),
+              as: "system"
+            }
+          ]
+        };
+      }
+      case 8: {
+        const space = r.u64("space");
+        return {
+          program: "System",
+          type: "allocate",
+          decoded: true,
+          args: { space: space.toString() },
+          accountNames: ["account"]
+        };
+      }
+      case 9: {
+        const base = r.pubkey("base");
+        const seedLen = Number(r.u64("seed length"));
+        const seed = new TextDecoder().decode(r.bytes_(seedLen, "seed"));
+        const space = r.u64("space");
+        const owner = r.pubkey("owner");
+        return {
+          program: "System",
+          type: "allocateWithSeed",
+          decoded: true,
+          args: { base, seed, space: space.toString(), owner },
+          accountNames: ["account", "base"]
+        };
+      }
+      case 10: {
+        const base = r.pubkey("base");
+        const seedLen = Number(r.u64("seed length"));
+        const seed = new TextDecoder().decode(r.bytes_(seedLen, "seed"));
+        const owner = r.pubkey("owner");
+        return {
+          program: "System",
+          type: "assignWithSeed",
+          decoded: true,
+          args: { base, seed, owner },
+          accountNames: ["account", "base"]
+        };
+      }
+      case 11: {
+        const lamports = r.u64("lamports");
+        const seedLen = Number(r.u64("seed length"));
+        const fromSeed = new TextDecoder().decode(r.bytes_(seedLen, "fromSeed"));
+        const fromOwner = r.pubkey("fromOwner");
+        const from = acc(ix, 0) ?? "";
+        const to = acc(ix, 2) ?? "";
+        return {
+          program: "System",
+          type: "transferWithSeed",
+          decoded: true,
+          args: { lamports: lamports.toString(), fromSeed, fromOwner },
+          accountNames: ["from", "base", "to"],
+          effects: [{ kind: "sol-transfer", from, to, lamports }]
+        };
+      }
+      default: {
+        const names = {
+          4: "advanceNonceAccount",
+          5: "withdrawNonceAccount",
+          6: "initializeNonceAccount",
+          7: "authorizeNonceAccount"
+        };
+        return {
+          program: "System",
+          type: names[disc] ?? `unknown(${disc})`,
+          decoded: disc in names
+        };
+      }
+    }
+  } catch (err) {
+    return {
+      program: "System",
+      decoded: false,
+      warning: err instanceof Error ? err.message : "system decode failed",
+      warningCode: "partial-decode"
+    };
+  }
+}
+var systemDecoder = {
+  programId: SYSTEM_PROGRAM_ID,
+  name: "System",
+  kind: "system",
+  decode: decodeSystem
+};
+
+// src/decode/programs/spl-token.ts
+var MAX_U64 = (1n << 64n) - 1n;
+function acc2(ix, i) {
+  return ix.accounts[i]?.pubkey;
+}
+function decodeTokenInstruction(ix, programName, variant) {
+  if (ix.data.length < 1) {
+    return { decoded: false, program: programName, warning: "empty instruction data" };
+  }
+  const r = new Reader(ix.data);
+  const tag = r.u8("tag");
+  try {
+    switch (tag) {
+      case 0: {
+        const decimals = r.u8("decimals");
+        return {
+          program: programName,
+          type: "initializeMint",
+          decoded: true,
+          args: { decimals },
+          accountNames: ["mint", "rent"]
+        };
+      }
+      case 20: {
+        const decimals = r.u8("decimals");
+        return {
+          program: programName,
+          type: "initializeMint2",
+          decoded: true,
+          args: { decimals },
+          accountNames: ["mint"]
+        };
+      }
+      case 1:
+      case 16:
+      case 18: {
+        const account = acc2(ix, 0) ?? "";
+        const mint = acc2(ix, 1) ?? "";
+        const owner = acc2(ix, 2);
+        const type = tag === 1 ? "initializeAccount" : tag === 16 ? "initializeAccount2" : "initializeAccount3";
+        return {
+          program: programName,
+          type,
+          decoded: true,
+          accountNames: ["account", "mint", "owner"],
+          effects: [
+            {
+              kind: "account-created",
+              address: account,
+              owner: owner ?? mint,
+              as: "token-account"
+            }
+          ]
+        };
+      }
+      case 3: {
+        const amount = r.u64("amount");
+        const from = acc2(ix, 0) ?? "";
+        const to = acc2(ix, 1) ?? "";
+        return {
+          program: programName,
+          type: "transfer",
+          decoded: true,
+          args: { amount: amount.toString() },
+          accountNames: ["source", "destination", "authority"],
+          // No decimals/mint in unchecked transfer — correlate fills from diff.
+          effects: [{ kind: "token-transfer", from, to, amount, tokenProgram: variant }],
+          warning: "unchecked transfer carries no mint/decimals",
+          warningCode: "ambiguous-amount"
+        };
+      }
+      case 12: {
+        const amount = r.u64("amount");
+        const decimals = r.u8("decimals");
+        const source = acc2(ix, 0) ?? "";
+        const mint = acc2(ix, 1) ?? "";
+        const dest = acc2(ix, 2) ?? "";
+        return {
+          program: programName,
+          type: "transferChecked",
+          decoded: true,
+          args: { amount: amount.toString(), decimals },
+          accountNames: ["source", "mint", "destination", "authority"],
+          effects: [
+            { kind: "token-transfer", from: source, to: dest, mint, amount, decimals, tokenProgram: variant }
+          ]
+        };
+      }
+      case 4: {
+        const amount = r.u64("amount");
+        const delegate = acc2(ix, 1) ?? "";
+        const owner = acc2(ix, 2) ?? "";
+        return {
+          program: programName,
+          type: "approve",
+          decoded: true,
+          args: { amount: amount.toString() },
+          accountNames: ["source", "delegate", "owner"],
+          effects: [
+            {
+              kind: "approval",
+              owner,
+              delegate,
+              mint: "",
+              amount: amount === MAX_U64 ? "unlimited" : amount
+            }
+          ]
+        };
+      }
+      case 13: {
+        const amount = r.u64("amount");
+        const decimals = r.u8("decimals");
+        const mint = acc2(ix, 1) ?? "";
+        const delegate = acc2(ix, 2) ?? "";
+        const owner = acc2(ix, 3) ?? "";
+        return {
+          program: programName,
+          type: "approveChecked",
+          decoded: true,
+          args: { amount: amount.toString(), decimals },
+          accountNames: ["source", "mint", "delegate", "owner"],
+          effects: [
+            {
+              kind: "approval",
+              owner,
+              delegate,
+              mint,
+              amount: amount === MAX_U64 ? "unlimited" : amount
+            }
+          ]
+        };
+      }
+      case 5: {
+        const owner = acc2(ix, 1) ?? "";
+        return {
+          program: programName,
+          type: "revoke",
+          decoded: true,
+          accountNames: ["source", "owner"],
+          effects: [{ kind: "approval", owner, delegate: "", mint: "", amount: 0n, revoke: true }]
+        };
+      }
+      case 6: {
+        return {
+          program: programName,
+          type: "setAuthority",
+          decoded: true,
+          accountNames: ["account", "currentAuthority"]
+        };
+      }
+      case 7: {
+        const amount = r.u64("amount");
+        const mint = acc2(ix, 0) ?? "";
+        const to = acc2(ix, 1) ?? "";
+        return {
+          program: programName,
+          type: "mintTo",
+          decoded: true,
+          args: { amount: amount.toString() },
+          accountNames: ["mint", "destination", "authority"],
+          effects: [{ kind: "mint", mint, to, amount }]
+        };
+      }
+      case 14: {
+        const amount = r.u64("amount");
+        const decimals = r.u8("decimals");
+        const mint = acc2(ix, 0) ?? "";
+        const to = acc2(ix, 1) ?? "";
+        return {
+          program: programName,
+          type: "mintToChecked",
+          decoded: true,
+          args: { amount: amount.toString(), decimals },
+          accountNames: ["mint", "destination", "authority"],
+          effects: [{ kind: "mint", mint, to, amount, decimals }]
+        };
+      }
+      case 8: {
+        const amount = r.u64("amount");
+        const from = acc2(ix, 0) ?? "";
+        const mint = acc2(ix, 1) ?? "";
+        return {
+          program: programName,
+          type: "burn",
+          decoded: true,
+          args: { amount: amount.toString() },
+          accountNames: ["account", "mint", "authority"],
+          effects: [{ kind: "burn", mint, from, amount }]
+        };
+      }
+      case 15: {
+        const amount = r.u64("amount");
+        const decimals = r.u8("decimals");
+        const from = acc2(ix, 0) ?? "";
+        const mint = acc2(ix, 1) ?? "";
+        return {
+          program: programName,
+          type: "burnChecked",
+          decoded: true,
+          args: { amount: amount.toString(), decimals },
+          accountNames: ["account", "mint", "authority"],
+          effects: [{ kind: "burn", mint, from, amount, decimals }]
+        };
+      }
+      case 9: {
+        const account = acc2(ix, 0) ?? "";
+        const destination = acc2(ix, 1) ?? "";
+        return {
+          program: programName,
+          type: "closeAccount",
+          decoded: true,
+          accountNames: ["account", "destination", "owner"],
+          effects: [{ kind: "close-account", account, destination }]
+        };
+      }
+      case 10:
+        return {
+          program: programName,
+          type: "freezeAccount",
+          decoded: true,
+          accountNames: ["account", "mint", "authority"]
+        };
+      case 11:
+        return {
+          program: programName,
+          type: "thawAccount",
+          decoded: true,
+          accountNames: ["account", "mint", "authority"]
+        };
+      case 17: {
+        const account = acc2(ix, 0) ?? "";
+        return {
+          program: programName,
+          type: "syncNative",
+          decoded: true,
+          accountNames: ["account"],
+          effects: [{ kind: "sync-native", account }]
+        };
+      }
+      default:
+        return {
+          program: programName,
+          type: `unknown(${tag})`,
+          decoded: false,
+          warning: `unrecognized ${programName} instruction tag ${tag}`,
+          warningCode: "partial-decode"
+        };
+    }
+  } catch (err) {
+    return {
+      program: programName,
+      decoded: false,
+      warning: err instanceof Error ? err.message : "token decode failed",
+      warningCode: "partial-decode"
+    };
+  }
+}
+
+// src/decode/programs/token-2022.ts
+var EXTENSION_TAGS = {
+  21: "getAccountDataSize",
+  22: "initializeMintCloseAuthority",
+  23: "transferFeeExtension",
+  24: "confidentialTransferExtension",
+  25: "defaultAccountStateExtension",
+  26: "reallocate",
+  27: "memoTransferExtension",
+  28: "createNativeMint",
+  29: "initializeNonTransferableMint",
+  30: "interestBearingMintExtension",
+  31: "cpiGuardExtension",
+  32: "initializePermanentDelegate",
+  33: "transferHookExtension",
+  34: "confidentialTransferFeeExtension",
+  35: "withdrawExcessLamports",
+  36: "metadataPointerExtension",
+  37: "groupPointerExtension",
+  38: "groupMemberPointerExtension"
+};
+function decodeToken2022(ix) {
+  if (ix.data.length < 1) {
+    return { decoded: false, program: "Token-2022", warning: "empty instruction data" };
+  }
+  const tag = ix.data[0];
+  if (tag >= 21) {
+    const name = EXTENSION_TAGS[tag] ?? `extension(${tag})`;
+    return {
+      program: "Token-2022",
+      type: name,
+      decoded: false,
+      warning: `Token-2022 extension instruction "${name}" not byte-decoded; effect visible in balance diff`,
+      warningCode: "token-2022-extension-unparsed"
+    };
+  }
+  return decodeTokenInstruction(ix, "Token-2022", "token-2022");
+}
+var token2022Decoder = {
+  programId: TOKEN_2022_PROGRAM_ID,
+  name: "Token-2022",
+  kind: "token-2022",
+  decode: decodeToken2022
+};
+var splTokenDecoder = {
+  programId: TOKEN_PROGRAM_ID,
+  name: "SPL Token",
+  kind: "token",
+  decode: (ix) => decodeTokenInstruction(ix, "SPL Token", "spl-token")
+};
+
+// src/decode/programs/ata.ts
+function acc3(ix, i) {
+  return ix.accounts[i]?.pubkey;
+}
+function decodeAta(ix) {
+  const tag = ix.data.length === 0 ? 0 : ix.data[0];
+  const type = tag === 0 ? "create" : tag === 1 ? "createIdempotent" : tag === 2 ? "recoverNested" : void 0;
+  if (type === void 0) {
+    return {
+      program: "Associated Token Account",
+      decoded: false,
+      warning: `unrecognized ATA instruction tag ${tag}`,
+      warningCode: "partial-decode"
+    };
+  }
+  if (type === "recoverNested") {
+    return {
+      program: "Associated Token Account",
+      type,
+      decoded: true,
+      accountNames: ["nestedAta", "nestedMint", "destinationAta", "ownerAta", "ownerMint", "wallet"]
+    };
+  }
+  const ata = acc3(ix, 1) ?? "";
+  const owner = acc3(ix, 2) ?? "";
+  const tokenProgram = acc3(ix, 5);
+  return {
+    program: "Associated Token Account",
+    type,
+    decoded: true,
+    accountNames: ["payer", "ata", "owner", "mint", "systemProgram", "tokenProgram"],
+    effects: [
+      {
+        kind: "account-created",
+        address: ata,
+        owner: owner || (tokenProgram ?? ""),
+        as: "ata"
+      }
+    ]
+  };
+}
+var ataDecoder = {
+  programId: ASSOCIATED_TOKEN_PROGRAM_ID,
+  name: "Associated Token Account",
+  kind: "ata",
+  decode: decodeAta
+};
+
+// src/decode/programs/memo.ts
+var MAX_DISPLAY = 256;
+function decodeMemoData(ix, name) {
+  const text = new TextDecoder("utf-8", { fatal: false }).decode(ix.data);
+  const display = text.length > MAX_DISPLAY ? `${text.slice(0, MAX_DISPLAY)}\u2026` : text;
+  const truncated = text.length > MAX_DISPLAY;
+  return {
+    program: name,
+    type: "memo",
+    decoded: true,
+    args: { text: display, ...truncated ? { truncated: true } : {} },
+    effects: [{ kind: "memo", text: display }],
+    ...truncated ? { warning: "memo truncated for display; full bytes available via --raw", warningCode: "partial-decode" } : {}
+  };
+}
+var memoDecoder = {
+  programId: MEMO_PROGRAM_ID,
+  name: "Memo",
+  kind: "memo",
+  decode: (ix) => decodeMemoData(ix, "Memo")
+};
+var memoV1Decoder = {
+  programId: MEMO_V1_PROGRAM_ID,
+  name: "Memo (v1)",
+  kind: "memo",
+  decode: (ix) => decodeMemoData(ix, "Memo (v1)")
+};
+
+// src/decode/programs/compute-budget.ts
+function decodeComputeBudget(ix) {
+  if (ix.data.length < 1) {
+    return { decoded: false, program: "Compute Budget", warning: "empty instruction data" };
+  }
+  const r = new Reader(ix.data);
+  const tag = r.u8("tag");
+  try {
+    switch (tag) {
+      case 1: {
+        const bytes = r.u32("heap bytes");
+        return {
+          program: "Compute Budget",
+          type: "requestHeapFrame",
+          decoded: true,
+          args: { bytes }
+        };
+      }
+      case 2: {
+        const units = r.u32("unit limit");
+        return {
+          program: "Compute Budget",
+          type: "setComputeUnitLimit",
+          decoded: true,
+          args: { units },
+          effects: [{ kind: "compute-budget", unitLimit: units }]
+        };
+      }
+      case 3: {
+        const price = r.u64("micro-lamports");
+        return {
+          program: "Compute Budget",
+          type: "setComputeUnitPrice",
+          decoded: true,
+          args: { microLamports: price.toString() },
+          effects: [{ kind: "compute-budget", unitPriceMicroLamports: price }]
+        };
+      }
+      case 4: {
+        const bytes = r.u32("data size limit");
+        return {
+          program: "Compute Budget",
+          type: "setLoadedAccountsDataSizeLimit",
+          decoded: true,
+          args: { bytes }
+        };
+      }
+      case 0:
+        return {
+          program: "Compute Budget",
+          type: "requestUnits",
+          decoded: true
+        };
+      default:
+        return {
+          program: "Compute Budget",
+          type: `unknown(${tag})`,
+          decoded: false,
+          warningCode: "partial-decode"
+        };
+    }
+  } catch (err) {
+    return {
+      program: "Compute Budget",
+      decoded: false,
+      warning: err instanceof Error ? err.message : "compute-budget decode failed",
+      warningCode: "partial-decode"
+    };
+  }
+}
+var computeBudgetDecoder = {
+  programId: COMPUTE_BUDGET_PROGRAM_ID,
+  name: "Compute Budget",
+  kind: "compute-budget",
+  decode: decodeComputeBudget
+};
+
+// src/decode/programs/recognize.ts
+var ALREADY_DECODED = /* @__PURE__ */ new Set([
+  "11111111111111111111111111111111",
+  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+  "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
+  "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+  "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr",
+  "Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo",
+  "ComputeBudget111111111111111111111111111111"
+]);
+function buildRecognizers() {
+  const decoders = [];
+  for (const [programId, info] of Object.entries(KNOWN_PROGRAMS)) {
+    if (ALREADY_DECODED.has(programId)) continue;
+    decoders.push({
+      programId,
+      name: info.name,
+      kind: info.kind,
+      decode: () => ({
+        program: info.name,
+        decoded: false,
+        // Honest signal: we know *who* but not the exact ix semantics.
+        warning: `${info.name} recognized by program id; semantics inferred from balance diff (no IDL)`
+      })
+    });
+  }
+  return decoders;
+}
+
+// src/decode/registry.ts
+var Registry = class _Registry {
+  map;
+  constructor(decoders) {
+    this.map = /* @__PURE__ */ new Map();
+    for (const d of decoders) this.map.set(d.programId, d);
+  }
+  get(programId) {
+    return this.map.get(programId);
+  }
+  has(programId) {
+    return this.map.has(programId);
+  }
+  list() {
+    return [...this.map.values()];
+  }
+  merge(decoders) {
+    const merged = new Map(this.map);
+    for (const d of decoders) merged.set(d.programId, d);
+    return new _Registry([...merged.values()]);
+  }
+};
+var BUNDLED_DECODERS = [
+  systemDecoder,
+  splTokenDecoder,
+  token2022Decoder,
+  ataDecoder,
+  memoDecoder,
+  memoV1Decoder,
+  computeBudgetDecoder
+];
+function createRegistry(decoders) {
+  const base = [...BUNDLED_DECODERS, ...buildRecognizers()];
+  const reg = new Registry(base);
+  return reg;
+}
+var defaultRegistry = createRegistry();
+function decodeInstruction(ix, registry = defaultRegistry, precomputed) {
+  const decoder = registry.get(ix.programId);
+  const known = knownProgram(ix.programId);
+  const baseAccounts = ix.accounts.map((a) => ({
+    pubkey: a.pubkey,
+    isSigner: a.isSigner,
+    isWritable: a.isWritable
+  }));
+  if (!decoder) {
+    return {
+      index: ix.index,
+      programId: ix.programId,
+      ...known ? { program: known.name } : {},
+      decoded: false,
+      accounts: baseAccounts,
+      warning: known ? `${known.name} recognized by program id (no byte decoder)` : "unknown program (no decoder)"
+    };
+  }
+  let out;
+  try {
+    out = precomputed ?? decoder.decode(ix);
+  } catch (err) {
+    return {
+      index: ix.index,
+      programId: ix.programId,
+      program: decoder.name,
+      decoded: false,
+      accounts: baseAccounts,
+      warning: `decoder error: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const accounts = baseAccounts.map((a, i) => {
+    const name = out.accountNames?.[i];
+    return name !== void 0 ? { ...a, name } : a;
+  });
+  return {
+    index: ix.index,
+    programId: ix.programId,
+    ...out.program !== void 0 ? { program: out.program } : {},
+    ...out.type !== void 0 ? { type: out.type } : {},
+    decoded: out.decoded,
+    accounts,
+    ...out.args !== void 0 ? { args: out.args } : {},
+    ...out.warning !== void 0 ? { warning: out.warning } : {}
+  };
+}
+function decodeInstructionRaw(ix, registry = defaultRegistry) {
+  const decoder = registry.get(ix.programId);
+  if (!decoder) return { decoded: decodeInstruction(ix, registry), effects: [] };
+  let out;
+  try {
+    out = decoder.decode(ix);
+  } catch {
+    return { decoded: decodeInstruction(ix, registry), effects: [] };
+  }
+  const decoded = decodeInstruction(ix, registry, out);
+  return {
+    decoded,
+    effects: out.effects ?? [],
+    ...out.warningCode !== void 0 ? { warningCode: out.warningCode } : {}
+  };
+}
+
+// src/decode/message.ts
+var VERSION_PREFIX_MASK = 128;
+function stripSignatures(bytes) {
+  if (bytes.length === 0) {
+    throw new DecodeError("DECODE_FAILED", "empty transaction buffer");
+  }
+  const reader = new Reader(bytes);
+  let sigCount;
+  try {
+    sigCount = reader.compactU16("signature count");
+  } catch {
+    return bytes;
+  }
+  if (sigCount > 0 && sigCount <= 64) {
+    const afterSigs = reader.offset + sigCount * 64;
+    if (afterSigs < bytes.length) {
+      const next = bytes[afterSigs];
+      if (next !== void 0) {
+        const looksVersioned = (next & VERSION_PREFIX_MASK) !== 0;
+        const looksLegacyHeader = next > 0 && next <= 32;
+        if (looksVersioned || looksLegacyHeader) {
+          return bytes.subarray(afterSigs);
+        }
+      }
+    }
+  }
+  return bytes;
+}
+function parseMessage(messageBytes) {
+  const r = new Reader(messageBytes);
+  const firstByte = r.u8("version/header byte");
+  let version;
+  let numRequiredSignatures;
+  if ((firstByte & VERSION_PREFIX_MASK) !== 0) {
+    version = firstByte & 127;
+    if (version !== 0) {
+      throw new DecodeError(
+        "DECODE_FAILED",
+        `unsupported transaction message version v${version} (only legacy and v0 are supported)`
+      );
+    }
+    numRequiredSignatures = r.u8("numRequiredSignatures");
+  } else {
+    version = "legacy";
+    numRequiredSignatures = firstByte;
+  }
+  const numReadonlySignedAccounts = r.u8("numReadonlySignedAccounts");
+  const numReadonlyUnsignedAccounts = r.u8("numReadonlyUnsignedAccounts");
+  const keyCount = r.compactU16("account key count");
+  if (keyCount > 256) {
+    throw new DecodeError("DECODE_FAILED", `implausible account key count: ${keyCount}`);
+  }
+  const staticAccountKeys = [];
+  for (let i = 0; i < keyCount; i++) {
+    staticAccountKeys.push(r.pubkey(`account key #${i}`));
+  }
+  const recentBlockhash = r.pubkey("recentBlockhash");
+  const ixCount = r.compactU16("instruction count");
+  if (ixCount > 1024) {
+    throw new DecodeError("DECODE_FAILED", `implausible instruction count: ${ixCount}`);
+  }
+  const compiled = [];
+  for (let i = 0; i < ixCount; i++) {
+    const programIdIndex = r.u8(`instruction #${i} programIdIndex`);
+    const accCount = r.compactU16(`instruction #${i} account count`);
+    const accountIndexes = [];
+    for (let j = 0; j < accCount; j++) {
+      accountIndexes.push(r.u8(`instruction #${i} account index #${j}`));
+    }
+    const dataLen = r.compactU16(`instruction #${i} data length`);
+    const data = r.bytes_(dataLen, `instruction #${i} data`).slice();
+    compiled.push({ programIdIndex, accountIndexes, data });
+  }
+  const addressTableLookups = [];
+  let hasUnresolvedLut = false;
+  if (version === 0) {
+    const lutCount = r.compactU16("address table lookup count");
+    for (let i = 0; i < lutCount; i++) {
+      const accountKey = r.pubkey(`LUT #${i} account key`);
+      const writableCount = r.compactU16(`LUT #${i} writable count`);
+      const writableIndexes = [];
+      for (let j = 0; j < writableCount; j++) {
+        writableIndexes.push(r.u8(`LUT #${i} writable index #${j}`));
+      }
+      const readonlyCount = r.compactU16(`LUT #${i} readonly count`);
+      const readonlyIndexes = [];
+      for (let j = 0; j < readonlyCount; j++) {
+        readonlyIndexes.push(r.u8(`LUT #${i} readonly index #${j}`));
+      }
+      addressTableLookups.push({ accountKey, writableIndexes, readonlyIndexes });
+      if (writableIndexes.length + readonlyIndexes.length > 0) hasUnresolvedLut = true;
+    }
+  }
+  return {
+    version,
+    staticAccountKeys,
+    header: {
+      numRequiredSignatures,
+      numReadonlySignedAccounts,
+      numReadonlyUnsignedAccounts
+    },
+    recentBlockhash,
+    compiled,
+    addressTableLookups,
+    hasUnresolvedLut
+  };
+}
+function buildAccountList(msg, loaded) {
+  const loadedWritable = loaded?.writable ?? [];
+  const loadedReadonly = loaded?.readonly ?? [];
+  const accountKeys = [...msg.staticAccountKeys, ...loadedWritable, ...loadedReadonly];
+  const { numRequiredSignatures, numReadonlySignedAccounts, numReadonlyUnsignedAccounts } = msg.header;
+  const staticCount = msg.staticAccountKeys.length;
+  const isSigner = [];
+  const isWritable = [];
+  for (let i = 0; i < accountKeys.length; i++) {
+    if (i < staticCount) {
+      const signer = i < numRequiredSignatures;
+      let writable;
+      if (signer) {
+        writable = i < numRequiredSignatures - numReadonlySignedAccounts;
+      } else {
+        const unsignedIndex = i - numRequiredSignatures;
+        const unsignedWritableCount = staticCount - numRequiredSignatures - numReadonlyUnsignedAccounts;
+        writable = unsignedIndex < unsignedWritableCount;
+      }
+      isSigner.push(signer);
+      isWritable.push(writable);
+    } else {
+      const loadedIndex = i - staticCount;
+      isSigner.push(false);
+      isWritable.push(loadedIndex < loadedWritable.length);
+    }
+  }
+  return { accountKeys, isSigner, isWritable };
+}
+function toInstructionViews(msg, resolved) {
+  const { accountKeys, isSigner, isWritable } = resolved;
+  return msg.compiled.map((ix, index) => {
+    const programId = accountKeys[ix.programIdIndex];
+    if (programId === void 0) {
+      throw new DecodeError(
+        "DECODE_FAILED",
+        `instruction #${index} programIdIndex ${ix.programIdIndex} out of range (have ${accountKeys.length} keys)`
+      );
+    }
+    const accounts = ix.accountIndexes.map((ai) => {
+      const pubkey = accountKeys[ai];
+      if (pubkey === void 0) {
+        throw new DecodeError(
+          "DECODE_FAILED",
+          `instruction #${index} references account index ${ai} out of range (have ${accountKeys.length} keys)`
+        );
+      }
+      return {
+        pubkey,
+        isSigner: isSigner[ai] ?? false,
+        isWritable: isWritable[ai] ?? false
+      };
+    });
+    return { index, programId, accounts, data: ix.data };
+  });
+}
+
+// src/input/detect.ts
+function detectInput(input) {
+  if (Array.isArray(input)) {
+    return { kind: "instruction-set", instructions: validateInstructions(input) };
+  }
+  if (input instanceof Uint8Array) {
+    if (input.length === 0) {
+      throw new InputError("EMPTY_INPUT", "Empty byte input.", {
+        hint: "Pass a signature, a serialized transaction, or pipe data via --stdin."
+      });
+    }
+    assertWireMessage(input, "raw bytes");
+    return { kind: "tx-bytes", bytes: input, encoding: "base64", ambiguous: false };
+  }
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw new InputError("EMPTY_INPUT", "Input is empty or whitespace only.", {
+      hint: "Pass a signature, a serialized transaction, or pipe data via --stdin."
+    });
+  }
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (err) {
+      throw new InputError("INVALID_INPUT", "Input looks like JSON but failed to parse.", {
+        cause: err
+      });
+    }
+    const arr = Array.isArray(parsed) ? parsed : null;
+    if (!arr) {
+      throw new InputError(
+        "INVALID_INPUT",
+        "JSON instruction input must be an array of instructions."
+      );
+    }
+    return { kind: "instruction-set", instructions: validateInstructions(arr) };
+  }
+  if (looksLikeBase58(trimmed) && trimmed.length >= 64 && trimmed.length <= 88) {
+    const decoded = tryDecodeBase58(trimmed);
+    if (decoded && decoded.length === 64) {
+      return { kind: "signature", signature: trimmed };
+    }
+    if (decoded && decoded.length !== 64) ;
+  }
+  const asB64 = tryDecodeBase64(trimmed);
+  const asB58 = tryDecodeBase58(trimmed);
+  const b64Ok = asB64 ? isWireMessage(asB64) : false;
+  const b58Ok = asB58 ? isWireMessage(asB58) : false;
+  if (b64Ok && b58Ok) {
+    return { kind: "tx-bytes", bytes: asB64, encoding: "base64", ambiguous: true };
+  }
+  if (b64Ok) {
+    return { kind: "tx-bytes", bytes: asB64, encoding: "base64", ambiguous: false };
+  }
+  if (b58Ok) {
+    return { kind: "tx-bytes", bytes: asB58, encoding: "base58", ambiguous: false };
+  }
+  if (looksLikeBase58(trimmed)) {
+    const decoded = tryDecodeBase58(trimmed);
+    if (decoded) {
+      throw new InputError(
+        "INVALID_SIGNATURE",
+        `Input decoded as ${decoded.length} bytes; a signature must be exactly 64 bytes, and it is not a valid transaction.`,
+        { hint: "Provide a 64-byte base58 signature or a base64/base58 serialized transaction." }
+      );
+    }
+  }
+  throw new InputError(
+    "INVALID_INPUT",
+    "Could not classify input as a signature, transaction, or instruction set.",
+    { hint: "Provide a base58 signature, a base64/base58 transaction, or a JSON instruction array." }
+  );
+}
+function detectTxBytes(input, encoding = "auto") {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw new InputError("EMPTY_INPUT", "Empty transaction input.");
+  }
+  if (encoding === "base64") {
+    const bytes = tryDecodeBase64(trimmed);
+    if (!bytes) throw new InputError("INVALID_ENCODING", "Input is not valid base64.");
+    assertWireMessage(bytes, "base64 transaction");
+    return { bytes, encoding: "base64", ambiguous: false };
+  }
+  if (encoding === "base58") {
+    const bytes = tryDecodeBase58(trimmed);
+    if (!bytes) throw new InputError("INVALID_ENCODING", "Input is not valid base58.");
+    assertWireMessage(bytes, "base58 transaction");
+    return { bytes, encoding: "base58", ambiguous: false };
+  }
+  const asB64 = tryDecodeBase64(trimmed);
+  const asB58 = tryDecodeBase58(trimmed);
+  const b64Ok = asB64 ? isWireMessage(asB64) : false;
+  const b58Ok = asB58 ? isWireMessage(asB58) : false;
+  if (b64Ok) return { bytes: asB64, encoding: "base64", ambiguous: b58Ok };
+  if (b58Ok) return { bytes: asB58, encoding: "base58", ambiguous: false };
+  throw new InputError("DECODE_FAILED", "Input did not parse as a serialized transaction.");
+}
+function isWireMessage(bytes) {
+  try {
+    const stripped = stripSignatures(bytes);
+    const msg = parseMessage(stripped);
+    return msg.staticAccountKeys.length > 0 && msg.compiled.length >= 0;
+  } catch {
+    return false;
+  }
+}
+function assertWireMessage(bytes, label) {
+  if (!isWireMessage(bytes)) {
+    throw new InputError(
+      "DECODE_FAILED",
+      `${label} did not parse as a Solana wire transaction message.`,
+      { hint: "Ensure the input is a serialized (not deserialized) transaction." }
+    );
+  }
+}
+function validateInstructions(arr) {
+  if (arr.length === 0) {
+    throw new InputError("EMPTY_INPUT", "Instruction set is empty.");
+  }
+  return arr.map((raw, i) => {
+    if (typeof raw !== "object" || raw === null) {
+      throw new InputError("INVALID_INPUT", `Instruction #${i} is not an object.`);
+    }
+    const o = raw;
+    if (typeof o["programId"] !== "string") {
+      throw new InputError("INVALID_INPUT", `Instruction #${i} is missing a string "programId".`);
+    }
+    const accountsRaw = o["accounts"];
+    if (!Array.isArray(accountsRaw)) {
+      throw new InputError("INVALID_INPUT", `Instruction #${i} "accounts" must be an array.`);
+    }
+    const accounts = accountsRaw.map((a, j) => {
+      if (typeof a !== "object" || a === null) {
+        throw new InputError("INVALID_INPUT", `Instruction #${i} account #${j} is not an object.`);
+      }
+      const ao = a;
+      if (typeof ao["pubkey"] !== "string") {
+        throw new InputError(
+          "INVALID_INPUT",
+          `Instruction #${i} account #${j} is missing a string "pubkey".`
+        );
+      }
+      return {
+        pubkey: ao["pubkey"],
+        isSigner: Boolean(ao["isSigner"]),
+        isWritable: Boolean(ao["isWritable"])
+      };
+    });
+    const data = o["data"];
+    if (typeof data !== "string" && !Array.isArray(data) && !(data instanceof Uint8Array)) {
+      throw new InputError(
+        "INVALID_INPUT",
+        `Instruction #${i} "data" must be a base64/base58 string, byte array, or Uint8Array.`
+      );
+    }
+    return {
+      programId: o["programId"],
+      accounts,
+      data
+    };
+  });
+}
+
+// src/explain/token-meta.ts
+var KNOWN_MINTS = Object.freeze({
+  EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: { symbol: "USDC", decimals: 6 },
+  Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB: { symbol: "USDT", decimals: 6 },
+  So11111111111111111111111111111111111111112: { symbol: "wSOL", decimals: 9 },
+  mSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So: { symbol: "mSOL", decimals: 9 },
+  "7dHbWXmci3dT8UFYWYZweBLXgycu7Y3iL6trKn1Y7ARj": {
+    symbol: "stSOL",
+    decimals: 9
+  },
+  "4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R": {
+    symbol: "RAY",
+    decimals: 6
+  },
+  JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN: { symbol: "JUP", decimals: 6 },
+  DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263: { symbol: "BONK", decimals: 5 }
+});
+var WSOL_MINT = "So11111111111111111111111111111111111111112";
+function resolveSymbol(mint) {
+  return KNOWN_MINTS[mint]?.symbol;
+}
+function isWsol(mint) {
+  return mint === WSOL_MINT;
+}
+
+// src/acquire/normalize.ts
+function tokenProgramKey(programId) {
+  if (programId === TOKEN_PROGRAM_ID) return "spl-token";
+  if (programId === TOKEN_2022_PROGRAM_ID) return "token-2022";
+  return programId ?? "spl-token";
+}
+function tokenBalancesFromMeta(entries, accountKeys) {
+  if (!entries) return [];
+  const out = [];
+  for (const e of entries) {
+    const account = accountKeys[e.accountIndex];
+    if (account === void 0) continue;
+    const amount = BigInt(e.uiTokenAmount.amount);
+    const symbol = resolveSymbol(e.mint);
+    out.push({
+      account,
+      mint: e.mint,
+      ...e.owner !== void 0 ? { owner: e.owner } : {},
+      amount,
+      decimals: e.uiTokenAmount.decimals,
+      tokenProgram: tokenProgramKey(e.programId),
+      ...symbol !== void 0 ? { symbol } : {}
+    });
+  }
+  return out;
+}
+function tokenBalanceFromAccount(address, account) {
+  if (!account) return null;
+  const data = account.data;
+  if (typeof data !== "object" || data === null || !("parsed" in data) || !("program" in data)) {
+    return null;
+  }
+  const program = data.program;
+  const parsed = data.parsed;
+  if (program !== "spl-token" && program !== "spl-token-2022" || typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  const info = parsed.info;
+  const type = parsed.type;
+  if (type !== "account" || typeof info !== "object" || info === null) return null;
+  const i = info;
+  if (typeof i.mint !== "string" || !i.tokenAmount) return null;
+  const amountStr = i.tokenAmount.amount;
+  const decimals = i.tokenAmount.decimals;
+  if (typeof amountStr !== "string" || typeof decimals !== "number") return null;
+  const symbol = resolveSymbol(i.mint);
+  return {
+    account: address,
+    mint: i.mint,
+    ...typeof i.owner === "string" ? { owner: i.owner } : {},
+    amount: BigInt(amountStr),
+    decimals,
+    tokenProgram: program === "spl-token-2022" ? "token-2022" : "spl-token",
+    ...symbol !== void 0 ? { symbol } : {}
+  };
+}
+function innerFromMeta(groups, accountKeys, decodeData, isSigner, isWritable) {
+  if (!groups) return [];
+  return groups.map((g) => ({
+    index: g.index,
+    instructions: g.instructions.map((ix, i) => {
+      const programId = accountKeys[ix.programIdIndex] ?? "";
+      return {
+        index: i,
+        programId,
+        accounts: ix.accounts.map((ai) => ({
+          pubkey: accountKeys[ai] ?? "",
+          isSigner: isSigner[ai] ?? false,
+          isWritable: isWritable[ai] ?? false
+        })),
+        data: decodeData(ix.data)
+      };
+    })
+  }));
+}
+
+// src/acquire/tx-error.ts
+function humanizeTxError(err, instructions) {
+  return { raw: err, human: describe(err, instructions) };
+}
+function describe(err, instructions) {
+  if (err === null || err === void 0) return "unknown error";
+  if (typeof err === "string") return prettifyVariant(err);
+  if (typeof err === "object") {
+    const entries = Object.entries(err);
+    if (entries.length === 0) return "unknown error";
+    const [key, value] = entries[0];
+    if (key === "InstructionError" && Array.isArray(value)) {
+      const [idx, detail] = value;
+      const ix = instructions?.[idx];
+      const progInfo = ix ? knownProgram(ix.programId) : void 0;
+      const where = `instruction #${idx}${progInfo ? ` (${progInfo.name})` : ix ? ` (${ix.programId})` : ""}`;
+      if (typeof detail === "string") {
+        return `${where} failed: ${prettifyVariant(detail)}`;
+      }
+      if (detail && typeof detail === "object") {
+        const dEntries = Object.entries(detail);
+        if (dEntries.length > 0) {
+          const [dKey, dVal] = dEntries[0];
+          if (dKey === "Custom") {
+            return `${where} failed with custom program error ${String(dVal)}`;
+          }
+          return `${where} failed: ${dKey}${dVal !== null ? ` (${JSON.stringify(dVal)})` : ""}`;
+        }
+      }
+      return `${where} failed`;
+    }
+    if (key === "InsufficientFundsForRent") {
+      const acc4 = value && typeof value === "object" && "account_index" in value ? ` (account #${String(value.account_index)})` : "";
+      return `insufficient funds for rent${acc4}`;
+    }
+    if (value === null || typeof value === "object" && Object.keys(value).length === 0) {
+      return prettifyVariant(key);
+    }
+    return `${prettifyVariant(key)}: ${safeJson(value)}`;
+  }
+  return String(err);
+}
+function prettifyVariant(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase();
+}
+function safeJson(v) {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+// src/acquire/from-signature.ts
+async function acquireFromSignature(args) {
+  const { rpc, signature, commitment, maxSupportedTransactionVersion, signal, includeRaw } = args;
+  const resp = await rpc.getTransaction(signature, {
+    commitment,
+    maxSupportedTransactionVersion,
+    ...signal ? { signal } : {}
+  });
+  if (resp === null) {
+    throw new RpcError(
+      "TX_NOT_FOUND",
+      `Transaction ${signature} not found at commitment "${commitment}".`,
+      {
+        hint: "Try --commitment finalized, verify the signature, or check you are on the right cluster."
+      }
+    );
+  }
+  return normalizeSignatureResponse(resp, signature, includeRaw ?? false);
+}
+function normalizeSignatureResponse(resp, signature, includeRaw) {
+  const warnings = [];
+  const meta = resp.meta;
+  const messageBytes = decodeMessageBytes(resp.transaction.message);
+  const parsed = parseMessage(messageBytes);
+  const loaded = meta?.loadedAddresses ? { writable: meta.loadedAddresses.writable, readonly: meta.loadedAddresses.readonly } : void 0;
+  if (parsed.version === 0 && parsed.hasUnresolvedLut && !loaded) {
+    warnings.push({
+      code: "lut-unresolved",
+      message: "versioned tx uses address lookup tables not resolved by the node response"
+    });
+  }
+  const resolved = buildAccountList(parsed, loaded);
+  const accountKeys = resolved.accountKeys;
+  const instructions = toInstructionViews(parsed, resolved);
+  const feePayer = accountKeys[0] ?? "";
+  const preLamports = (meta?.preBalances ?? []).map((n) => BigInt(n));
+  const postLamports = (meta?.postBalances ?? []).map((n) => BigInt(n));
+  const preTokens = tokenBalancesFromMeta(meta?.preTokenBalances, accountKeys);
+  const postTokens = tokenBalancesFromMeta(meta?.postTokenBalances, accountKeys);
+  const inner = meta?.innerInstructions ? innerFromMeta(
+    meta.innerInstructions,
+    accountKeys,
+    decodeBase58,
+    resolved.isSigner,
+    resolved.isWritable
+  ) : [];
+  if (!meta?.innerInstructions) {
+    warnings.push({
+      code: "inner-instructions-missing",
+      message: "node did not return inner instructions (CPI tree unavailable)"
+    });
+  }
+  const err = meta?.err ?? null;
+  const success = err === null || err === void 0;
+  const error = success ? void 0 : humanizeTxError(err, instructions);
+  const result = {
+    source: "signature",
+    signature,
+    feePayer,
+    success,
+    ...error ? { error } : {},
+    slot: resp.slot,
+    blockTime: resp.blockTime,
+    feeLamports: BigInt(meta?.fee ?? 0),
+    ...meta?.computeUnitsConsumed !== void 0 ? { computeUnits: meta.computeUnitsConsumed } : {},
+    pre: { accountKeys, lamports: preLamports, tokenBalances: preTokens },
+    post: { accountKeys, lamports: postLamports, tokenBalances: postTokens },
+    instructions,
+    innerInstructions: inner,
+    warnings,
+    ...includeRaw ? { raw: resp } : {}
+  };
+  return result;
+}
+function decodeMessageBytes(message) {
+  if (Array.isArray(message) && typeof message[0] === "string") {
+    const enc = message[1];
+    if (enc === "base64") return decodeBase64(message[0]);
+    if (enc === "base58") return decodeBase58(message[0]);
+    return decodeBase64(message[0]);
+  }
+  if (typeof message === "string") {
+    return decodeBase64(message);
+  }
+  throw new RpcError(
+    "RPC_JSON",
+    "Unexpected transaction.message shape; expected base64-encoded message."
+  );
+}
+
+// src/acquire/from-simulation.ts
+function accountLamports(acc4) {
+  return acc4 ? BigInt(acc4.lamports) : 0n;
+}
+async function acquireFromSimulation(args) {
+  const { rpc, txBytes, commitment, replaceRecentBlockhash, sigVerify, signal, includeRaw } = args;
+  const stripped = stripSignatures(txBytes);
+  const parsed = parseMessage(stripped);
+  const resolved = buildAccountList(parsed);
+  const accountKeys = resolved.accountKeys;
+  const instructions = toInstructionViews(parsed, resolved);
+  const feePayer = accountKeys[0] ?? "";
+  const warnings = [];
+  if (parsed.version === 0 && parsed.hasUnresolvedLut) {
+    warnings.push({
+      code: "lut-unresolved",
+      message: "versioned tx references address lookup tables; simulate path diffs only resolved writable keys"
+    });
+  }
+  const writable = accountKeys.filter((_, i) => resolved.isWritable[i]);
+  const uniqueWritable = [...new Set(writable)];
+  const preAccounts = await rpc.getMultipleAccounts(uniqueWritable, {
+    commitment,
+    encoding: "jsonParsed",
+    ...signal ? { signal } : {}
+  });
+  const txBase64 = encodeBase64(txBytes);
+  const sim = await rpc.simulateTransaction(txBase64, {
+    commitment,
+    sigVerify,
+    replaceRecentBlockhash,
+    innerInstructions: true,
+    accounts: { addresses: uniqueWritable, encoding: "jsonParsed" },
+    ...signal ? { signal } : {}
+  });
+  const value = sim.value;
+  const postAccounts = value.accounts ?? [];
+  const preLamportsByAddr = /* @__PURE__ */ new Map();
+  const postLamportsByAddr = /* @__PURE__ */ new Map();
+  const preTokens = [];
+  const postTokens = [];
+  uniqueWritable.forEach((addr, i) => {
+    const preAcc = preAccounts[i] ?? null;
+    const postAcc = postAccounts[i] ?? null;
+    preLamportsByAddr.set(addr, accountLamports(preAcc));
+    postLamportsByAddr.set(addr, postAcc ? accountLamports(postAcc) : accountLamports(preAcc));
+    const preTb = tokenBalanceFromAccount(addr, preAcc);
+    if (preTb) preTokens.push(preTb);
+    const postTb = tokenBalanceFromAccount(addr, postAcc);
+    if (postTb) postTokens.push(postTb);
+  });
+  const preLamports = accountKeys.map((k) => preLamportsByAddr.get(k) ?? 0n);
+  const postLamports = accountKeys.map((k) => postLamportsByAddr.get(k) ?? preLamportsByAddr.get(k) ?? 0n);
+  const inner = value.innerInstructions ? innerFromMeta(
+    value.innerInstructions,
+    accountKeys,
+    decodeBase58,
+    resolved.isSigner,
+    resolved.isWritable
+  ) : [];
+  const err = value.err ?? null;
+  const success = err === null || err === void 0;
+  const error = success ? void 0 : humanizeTxError(err, instructions);
+  if (!success) {
+    warnings.push({
+      code: "simulation-failed",
+      message: "simulation returned a runtime error; balance diff reflects the pre-state"
+    });
+  }
+  const result = {
+    source: "simulation",
+    feePayer,
+    success,
+    ...error ? { error } : {},
+    slot: sim.context.slot,
+    blockTime: null,
+    // Simulation does not surface a fee; fee impact is visible via lamport diff.
+    feeLamports: 0n,
+    ...value.unitsConsumed !== void 0 ? { computeUnits: value.unitsConsumed } : {},
+    pre: { accountKeys, lamports: preLamports, tokenBalances: preTokens },
+    post: { accountKeys, lamports: postLamports, tokenBalances: postTokens },
+    instructions,
+    innerInstructions: inner,
+    warnings,
+    ...includeRaw ? { raw: sim } : {}
+  };
+  return result;
+}
+function normalizeData(data) {
+  if (data instanceof Uint8Array) return data;
+  if (Array.isArray(data)) return Uint8Array.from(data);
+  if (looksLikeBase64(data) && /[+/=]/.test(data)) {
+    return decodeBase64(data);
+  }
+  try {
+    return decodeBase58(data);
+  } catch {
+    return decodeBase64(data);
+  }
+}
+function writeCompactU16(out, value) {
+  let v = value;
+  for (; ; ) {
+    let byte = v & 127;
+    v >>= 7;
+    if (v === 0) {
+      out.push(byte);
+      return;
+    }
+    byte |= 128;
+    out.push(byte);
+  }
+}
+function buildLegacyMessage(instructions, feePayer, recentBlockhash) {
+  if (instructions.length === 0) {
+    throw new InputError("EMPTY_INPUT", "No instructions to assemble.");
+  }
+  const metaByKey = /* @__PURE__ */ new Map();
+  const upsert = (m) => {
+    const cur = metaByKey.get(m.pubkey);
+    if (cur) {
+      cur.isSigner = cur.isSigner || m.isSigner;
+      cur.isWritable = cur.isWritable || m.isWritable;
+    } else {
+      metaByKey.set(m.pubkey, { ...m });
+    }
+  };
+  upsert({ pubkey: feePayer, isSigner: true, isWritable: true });
+  for (const ix of instructions) {
+    for (const a of ix.accounts) upsert({ ...a });
+    upsert({ pubkey: ix.programId, isSigner: false, isWritable: false });
+  }
+  const all = [...metaByKey.values()];
+  all.sort((a, b) => {
+    if (a.pubkey === feePayer) return -1;
+    if (b.pubkey === feePayer) return 1;
+    const rank = (m) => m.isSigner ? m.isWritable ? 0 : 1 : m.isWritable ? 2 : 3;
+    const r = rank(a) - rank(b);
+    if (r !== 0) return r;
+    return a.pubkey.localeCompare(b.pubkey);
+  });
+  const numRequiredSignatures = all.filter((m) => m.isSigner).length;
+  const numReadonlySignedAccounts = all.filter((m) => m.isSigner && !m.isWritable).length;
+  const numReadonlyUnsignedAccounts = all.filter((m) => !m.isSigner && !m.isWritable).length;
+  const keyIndex = /* @__PURE__ */ new Map();
+  all.forEach((m, i) => keyIndex.set(m.pubkey, i));
+  const out = [];
+  out.push(numRequiredSignatures, numReadonlySignedAccounts, numReadonlyUnsignedAccounts);
+  writeCompactU16(out, all.length);
+  for (const m of all) {
+    const bytes = decodePubkey(m.pubkey);
+    out.push(...bytes);
+  }
+  out.push(...decodePubkey(recentBlockhash));
+  writeCompactU16(out, instructions.length);
+  for (const ix of instructions) {
+    const programIdIndex = keyIndex.get(ix.programId);
+    if (programIdIndex === void 0) {
+      throw new InputError("INVALID_INPUT", `programId ${ix.programId} not in account list`);
+    }
+    out.push(programIdIndex);
+    writeCompactU16(out, ix.accounts.length);
+    for (const a of ix.accounts) {
+      const idx = keyIndex.get(a.pubkey);
+      if (idx === void 0) {
+        throw new InputError("INVALID_INPUT", `account ${a.pubkey} not in account list`);
+      }
+      out.push(idx);
+    }
+    const data = normalizeData(ix.data);
+    writeCompactU16(out, data.length);
+    out.push(...data);
+  }
+  const message = Uint8Array.from(out);
+  const tx = [];
+  writeCompactU16(tx, numRequiredSignatures);
+  for (let i = 0; i < numRequiredSignatures; i++) {
+    for (let j = 0; j < 64; j++) tx.push(0);
+  }
+  tx.push(...message);
+  return Uint8Array.from(tx);
+}
+function decodePubkey(pubkey) {
+  let bytes;
+  try {
+    bytes = bs58.decode(pubkey);
+  } catch (err) {
+    throw new InputError("INVALID_INPUT", `Invalid base58 pubkey: ${pubkey}`, { cause: err });
+  }
+  if (bytes.length !== 32) {
+    throw new InputError(
+      "INVALID_INPUT",
+      `Pubkey ${pubkey} decoded to ${bytes.length} bytes (expected 32).`
+    );
+  }
+  return bytes;
+}
+
+// src/render/format.ts
+function groupThousands(intStr) {
+  const neg = intStr.startsWith("-");
+  const digits = neg ? intStr.slice(1) : intStr;
+  const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return neg ? `-${grouped}` : grouped;
+}
+function formatUnits(amount, decimals) {
+  const neg = amount < 0n;
+  const abs = neg ? -amount : amount;
+  if (decimals <= 0) {
+    return (neg ? "-" : "") + groupThousands(abs.toString());
+  }
+  const base = 10n ** BigInt(decimals);
+  const whole = abs / base;
+  const frac = abs % base;
+  let fracStr = frac.toString().padStart(decimals, "0").replace(/0+$/, "");
+  const wholeStr = groupThousands(whole.toString());
+  const sign = neg ? "-" : "";
+  return fracStr.length > 0 ? `${sign}${wholeStr}.${fracStr}` : `${sign}${wholeStr}`;
+}
+function lamportsToSol(lamports) {
+  return formatUnits(lamports, 9);
+}
+function signedUi(delta, decimals, symbol) {
+  const sign = delta > 0n ? "+" : "";
+  const body = formatUnits(delta, decimals);
+  const unit = symbol ? ` ${symbol}` : "";
+  return `${sign}${body}${unit}`;
+}
+function shortAddr(addr, head = 4, tail = 4) {
+  if (addr.length <= head + tail + 1) return addr;
+  return `${addr.slice(0, head)}\u2026${addr.slice(-tail)}`;
+}
+function formatBlockTime(blockTime) {
+  if (blockTime === null || blockTime === void 0) return void 0;
+  const d = new Date(blockTime * 1e3);
+  if (Number.isNaN(d.getTime())) return void 0;
+  const pad = (n) => n.toString().padStart(2, "0");
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())} UTC`;
+}
+function formatCount(n) {
+  return groupThousands(Math.trunc(n).toString());
+}
+
+// src/explain/diff.ts
+function tokenKey(e) {
+  return `${e.account}::${e.mint}`;
+}
+function diffBalances(pre, post) {
+  const deltas = [];
+  const preLamportsByAddr = /* @__PURE__ */ new Map();
+  for (let i = 0; i < pre.accountKeys.length; i++) {
+    const key = pre.accountKeys[i];
+    const lam = pre.lamports[i];
+    if (key !== void 0 && lam !== void 0) preLamportsByAddr.set(key, lam);
+  }
+  const seenAddrs = /* @__PURE__ */ new Set();
+  for (let i = 0; i < post.accountKeys.length; i++) {
+    const account = post.accountKeys[i];
+    const postLam = post.lamports[i];
+    if (account === void 0 || postLam === void 0) continue;
+    seenAddrs.add(account);
+    const preLam = preLamportsByAddr.get(account) ?? 0n;
+    const delta = postLam - preLam;
+    if (delta !== 0n) {
+      deltas.push({
+        account,
+        asset: { kind: "SOL" },
+        pre: preLam,
+        post: postLam,
+        delta,
+        uiDelta: signedUi(delta, 9, "SOL")
+      });
+    }
+  }
+  for (const [account, preLam] of preLamportsByAddr) {
+    if (seenAddrs.has(account)) continue;
+    const delta = 0n - preLam;
+    if (delta !== 0n) {
+      deltas.push({
+        account,
+        asset: { kind: "SOL" },
+        pre: preLam,
+        post: 0n,
+        delta,
+        uiDelta: signedUi(delta, 9, "SOL")
+      });
+    }
+  }
+  const preTok = /* @__PURE__ */ new Map();
+  for (const e of pre.tokenBalances) preTok.set(tokenKey(e), e);
+  const postTok = /* @__PURE__ */ new Map();
+  for (const e of post.tokenBalances) postTok.set(tokenKey(e), e);
+  const allKeys = /* @__PURE__ */ new Set([...preTok.keys(), ...postTok.keys()]);
+  for (const key of allKeys) {
+    const p = preTok.get(key);
+    const q = postTok.get(key);
+    const meta = q ?? p;
+    if (!meta) continue;
+    const preAmt = p?.amount ?? 0n;
+    const postAmt = q?.amount ?? 0n;
+    const delta = postAmt - preAmt;
+    if (delta === 0n) continue;
+    const decimals = meta.decimals;
+    deltas.push({
+      account: meta.account,
+      asset: {
+        kind: "token",
+        mint: meta.mint,
+        decimals,
+        ...meta.symbol !== void 0 ? { symbol: meta.symbol } : {},
+        tokenProgram: meta.tokenProgram
+      },
+      pre: preAmt,
+      post: postAmt,
+      delta,
+      uiDelta: signedUi(delta, decimals, meta.symbol),
+      ...meta.owner !== void 0 ? { owner: meta.owner } : {}
+    });
+  }
+  deltas.sort((a, b) => {
+    if (a.asset.kind !== b.asset.kind) return a.asset.kind === "SOL" ? -1 : 1;
+    const am = a.delta < 0n ? -a.delta : a.delta;
+    const bm = b.delta < 0n ? -b.delta : b.delta;
+    return am > bm ? -1 : am < bm ? 1 : 0;
+  });
+  return deltas;
+}
+function netSolByAccount(deltas) {
+  const m = /* @__PURE__ */ new Map();
+  for (const d of deltas) {
+    if (d.asset.kind === "SOL") m.set(d.account, (m.get(d.account) ?? 0n) + d.delta);
+  }
+  return m;
+}
+function netTokenByOwnerMint(deltas) {
+  const m = /* @__PURE__ */ new Map();
+  for (const d of deltas) {
+    if (d.asset.kind !== "token") continue;
+    const owner = d.owner ?? d.account;
+    const key = `${owner}::${d.asset.mint}`;
+    const cur = m.get(key);
+    if (cur) {
+      cur.delta += d.delta;
+    } else {
+      m.set(key, {
+        owner,
+        mint: d.asset.mint,
+        decimals: d.asset.decimals,
+        ...d.asset.symbol !== void 0 ? { symbol: d.asset.symbol } : {},
+        delta: d.delta
+      });
+    }
+  }
+  return m;
+}
+
+// src/explain/correlate.ts
+function mintDecimals(tokenBalances) {
+  const m = /* @__PURE__ */ new Map();
+  for (const tb of tokenBalances) {
+    if (!m.has(tb.mint)) m.set(tb.mint, tb.decimals);
+  }
+  return m;
+}
+function tokenAccountMeta(tokenBalances) {
+  const m = /* @__PURE__ */ new Map();
+  for (const tb of tokenBalances) {
+    m.set(tb.account, {
+      mint: tb.mint,
+      ...tb.owner !== void 0 ? { owner: tb.owner } : {},
+      decimals: tb.decimals,
+      tokenProgram: tb.tokenProgram
+    });
+  }
+  return m;
+}
+function uiAmount(amount, decimals) {
+  return formatUnits(amount, decimals);
+}
+function correlate(input) {
+  const { instructions, innerInstructions, deltas, tokenBalances, registry } = input;
+  const decoded = [];
+  const actions = [];
+  const accountsCreated = [];
+  const approvals = [];
+  const warnings = [];
+  const invocationCounts = /* @__PURE__ */ new Map();
+  const decByMint = mintDecimals(tokenBalances);
+  const taMeta = tokenAccountMeta(tokenBalances);
+  const innerByIndex = /* @__PURE__ */ new Map();
+  for (const grp of innerInstructions ?? []) innerByIndex.set(grp.index, grp.instructions);
+  const seenSyncNative = /* @__PURE__ */ new Set();
+  const handleEffect = (eff) => {
+    switch (eff.kind) {
+      case "sol-transfer": {
+        actions.push({
+          kind: "sol-transfer",
+          from: eff.from,
+          to: eff.to,
+          lamports: eff.lamports,
+          sol: lamportsToSol(eff.lamports)
+        });
+        break;
+      }
+      case "token-transfer": {
+        const srcMeta = taMeta.get(eff.from);
+        const dstMeta = taMeta.get(eff.to);
+        const mint = eff.mint || srcMeta?.mint || dstMeta?.mint || "";
+        const decimals = eff.decimals ?? srcMeta?.decimals ?? dstMeta?.decimals ?? decByMint.get(mint);
+        const symbol = mint ? resolveSymbol(mint) : void 0;
+        if (decimals === void 0) {
+          warnings.push({
+            code: "ambiguous-amount",
+            message: `token transfer of ${eff.amount} raw units lacks decimals; shown in base units`
+          });
+        }
+        const dec = decimals ?? 0;
+        const action = {
+          kind: "token-transfer",
+          from: eff.from,
+          to: eff.to,
+          mint,
+          amount: eff.amount,
+          uiAmount: uiAmount(eff.amount, dec),
+          decimals: dec,
+          tokenProgram: eff.tokenProgram,
+          ...symbol !== void 0 ? { symbol } : {}
+        };
+        actions.push(action);
+        break;
+      }
+      case "mint": {
+        const decimals = eff.decimals ?? decByMint.get(eff.mint) ?? 0;
+        actions.push({
+          kind: "mint",
+          mint: eff.mint,
+          to: eff.to,
+          amount: eff.amount,
+          uiAmount: uiAmount(eff.amount, decimals)
+        });
+        break;
+      }
+      case "burn": {
+        const decimals = eff.decimals ?? decByMint.get(eff.mint) ?? 0;
+        actions.push({
+          kind: "burn",
+          mint: eff.mint,
+          from: eff.from,
+          amount: eff.amount,
+          uiAmount: uiAmount(eff.amount, decimals)
+        });
+        break;
+      }
+      case "approval": {
+        const mint = eff.mint || taMeta.get(eff.owner)?.mint || "";
+        const ap = {
+          owner: eff.owner,
+          delegate: eff.delegate,
+          mint,
+          amount: eff.amount,
+          ...eff.revoke !== void 0 ? { revoke: eff.revoke } : {}
+        };
+        approvals.push(ap);
+        actions.push({ kind: "approval", ...ap });
+        break;
+      }
+      case "close-account": {
+        const d = deltas.find((x) => x.account === eff.account && x.asset.kind === "SOL");
+        const reclaimed = d ? -d.delta : 0n;
+        actions.push({
+          kind: "close-account",
+          account: eff.account,
+          destination: eff.destination,
+          reclaimedLamports: reclaimed > 0n ? reclaimed : 0n
+        });
+        break;
+      }
+      case "account-created": {
+        const meta = taMeta.get(eff.address);
+        const ac = {
+          address: eff.address,
+          owner: eff.owner,
+          lamports: eff.lamports ?? 0n,
+          ...eff.space !== void 0 ? { space: eff.space } : {},
+          ...eff.as !== void 0 ? { as: eff.as } : meta ? { as: "token-account" } : {}
+        };
+        accountsCreated.push(ac);
+        actions.push({ kind: "account-created", ...ac });
+        break;
+      }
+      case "memo": {
+        actions.push({ kind: "memo", text: eff.text });
+        break;
+      }
+      case "compute-budget": {
+        actions.push({
+          kind: "compute-budget",
+          ...eff.unitLimit !== void 0 ? { unitLimit: eff.unitLimit } : {},
+          ...eff.unitPriceMicroLamports !== void 0 ? { unitPriceMicroLamports: eff.unitPriceMicroLamports } : {}
+        });
+        break;
+      }
+      case "sync-native": {
+        seenSyncNative.add(eff.account);
+        break;
+      }
+    }
+  };
+  const decodeInner = (views) => views.map((view) => {
+    invocationCounts.set(view.programId, (invocationCounts.get(view.programId) ?? 0) + 1);
+    const { decoded: dec, effects, warningCode } = decodeInstructionRaw(view, registry);
+    if (!dec.decoded) {
+      const known = knownProgram(view.programId);
+      warnings.push({
+        code: known ? "partial-decode" : "unknown-program",
+        message: dec.warning ?? (known ? `${known.name} not byte-decoded` : "unknown program"),
+        instructionIndex: view.index
+      });
+    } else if (warningCode) {
+      warnings.push({
+        code: warningCode,
+        message: dec.warning ?? "partial decode",
+        instructionIndex: view.index
+      });
+    }
+    for (const eff of effects) handleEffect(eff);
+    return dec;
+  });
+  for (const view of instructions) {
+    invocationCounts.set(view.programId, (invocationCounts.get(view.programId) ?? 0) + 1);
+    const { decoded: dec, effects, warningCode } = decodeInstructionRaw(view, registry);
+    if (!dec.decoded) {
+      const known = knownProgram(view.programId);
+      warnings.push({
+        code: known ? "partial-decode" : "unknown-program",
+        message: dec.warning ?? (known ? `${known.name} not byte-decoded` : "unknown program"),
+        instructionIndex: view.index
+      });
+      actions.push({
+        kind: "program-call",
+        programId: view.programId,
+        ...known ? { program: known.name } : {},
+        ...known ? { note: "effect inferred from balance diff (no IDL)" } : { note: "unknown program; see balance changes" }
+      });
+    } else if (warningCode) {
+      warnings.push({
+        code: warningCode,
+        message: dec.warning ?? "partial decode",
+        instructionIndex: view.index
+      });
+    }
+    for (const eff of effects) handleEffect(eff);
+    const inner = innerByIndex.get(view.index);
+    if (inner && inner.length > 0) {
+      dec.inner = decodeInner(inner);
+    }
+    decoded.push(dec);
+  }
+  if (seenSyncNative.size > 0) {
+    for (const action of actions) {
+      if (action.kind === "token-transfer" && isWsol(action.mint)) {
+        if (!action.symbol) action.symbol = "wSOL";
+      }
+    }
+  }
+  const createdAddrs = new Set(accountsCreated.map((a) => a.address));
+  for (const action of actions) {
+    if (action.kind === "close-account" && createdAddrs.has(action.account)) {
+      warnings.push({
+        code: "partial-decode",
+        message: `account ${action.account} was created and closed within this transaction (temporary ATA)`
+      });
+    }
+  }
+  for (const action of actions) {
+    if ((action.kind === "sol-transfer" || action.kind === "token-transfer") && action.from === action.to) {
+      warnings.push({
+        code: "ambiguous-amount",
+        message: "no net token movement (self-transfer)"
+      });
+    }
+  }
+  const programsInvoked = [...invocationCounts.entries()].map(
+    ([programId, count]) => {
+      const known = knownProgram(programId);
+      return { programId, ...known ? { name: known.name } : {}, count };
+    }
+  );
+  return { decoded, actions, accountsCreated, approvals, programsInvoked, warnings };
+}
+
+// src/explain/summarize.ts
+function aggregatorName(programs) {
+  const agg = programs.find((p) => p.name && isAggregator(p.name));
+  if (agg?.name) return agg.name;
+  const amm = programs.find((p) => p.name && isAmm(p.name));
+  return amm?.name;
+}
+function isAggregator(name) {
+  return /jupiter/i.test(name);
+}
+function isAmm(name) {
+  return /raydium|orca|whirlpool|phoenix|meteora/i.test(name);
+}
+function summarize(input) {
+  const { actions, deltas, programsInvoked, feePayer, feeLamports, success, error, focusAccount } = input;
+  const focus = focusAccount ?? feePayer;
+  const feeSol = lamportsToSol(feeLamports);
+  const feeSuffix = feeLamports > 0n ? `, paid ${feeSol} SOL fee` : "";
+  if (!success) {
+    const why = error?.human ? `: ${error.human}` : "";
+    return `Transaction FAILED${why}. ${feeLamports > 0n ? `Fee of ${feeSol} SOL was still charged.` : ""}`.trim();
+  }
+  const solByAcc = netSolByAccount(deltas);
+  const tokByOwner = netTokenByOwnerMint(deltas);
+  const meaningfulDeltas = deltas.filter((d) => {
+    if (d.asset.kind === "token") return true;
+    if (d.account !== feePayer) return true;
+    return d.delta !== -feeLamports;
+  });
+  const hasDex = programsInvoked.some((p) => p.name && (isAggregator(p.name) || isAmm(p.name)));
+  if (hasDex) {
+    const dexName = aggregatorName(programsInvoked) ?? "a DEX";
+    const focusGains = [];
+    const focusLosses = [];
+    const solDelta = solByAcc.get(focus);
+    if (solDelta !== void 0 && solDelta !== 0n) {
+      const label = `${formatUnits(absBig(solDelta), 9)} SOL`;
+      (solDelta > 0n ? focusGains : focusLosses).push(label);
+    }
+    for (const t of tokByOwner.values()) {
+      if (t.owner !== focus || t.delta === 0n) continue;
+      const label = `${formatUnits(absBig(t.delta), t.decimals)} ${t.symbol ?? shortAddr(t.mint)}`;
+      (t.delta > 0n ? focusGains : focusLosses).push(label);
+    }
+    if (focusLosses.length > 0 && focusGains.length > 0) {
+      return `Swapped ${focusLosses.join(" + ")} for ${focusGains.join(" + ")} via ${dexName}${feeSuffix}.`;
+    }
+    if (focusGains.length > 0 || focusLosses.length > 0) {
+      const moved = [...focusGains, ...focusLosses].join(", ");
+      return `Routed ${moved} via ${dexName}${feeSuffix}.`;
+    }
+  }
+  const tokenTransfers = actions.filter((a) => a.kind === "token-transfer");
+  const solTransfers = actions.filter((a) => a.kind === "sol-transfer");
+  if (tokenTransfers.length > 0) {
+    const biggest = tokenTransfers.slice().sort((a, b) => a.amount > b.amount ? -1 : 1)[0];
+    const sym = biggest.symbol ?? shortAddr(biggest.mint);
+    const dirNote = biggest.from === biggest.to ? " (self-transfer, no net movement)" : "";
+    const count = tokenTransfers.length > 1 ? ` (+${tokenTransfers.length - 1} more transfer${tokenTransfers.length - 1 > 1 ? "s" : ""})` : "";
+    return `Transferred ${biggest.uiAmount} ${sym} from ${shortAddr(biggest.from)} to ${shortAddr(biggest.to)}${dirNote}${count}${feeSuffix}.`;
+  }
+  if (solTransfers.length > 0) {
+    const total = solTransfers.reduce((acc4, a) => acc4 + a.lamports, 0n);
+    if (solTransfers.length === 1) {
+      const a = solTransfers[0];
+      return `Sent ${a.sol} SOL from ${shortAddr(a.from)} to ${shortAddr(a.to)}${feeSuffix}.`;
+    }
+    return `Made ${solTransfers.length} SOL transfers totaling ${lamportsToSol(total)} SOL${feeSuffix}.`;
+  }
+  const mints = actions.filter((a) => a.kind === "mint");
+  const burns = actions.filter((a) => a.kind === "burn");
+  if (mints.length > 0) {
+    const m = mints[0];
+    return `Minted ${m.uiAmount} of ${shortAddr(m.mint)} to ${shortAddr(m.to)}${feeSuffix}.`;
+  }
+  if (burns.length > 0) {
+    const b = burns[0];
+    return `Burned ${b.uiAmount} of ${shortAddr(b.mint)}${feeSuffix}.`;
+  }
+  const approvals = actions.filter((a) => a.kind === "approval");
+  if (approvals.length > 0) {
+    const ap = approvals[0];
+    if (ap.revoke) {
+      return `Revoked token delegate approval${feeSuffix}.`;
+    }
+    const amt = ap.amount === "unlimited" ? "unlimited" : ap.amount.toString();
+    return `Approved delegate ${shortAddr(ap.delegate)} to spend ${amt} tokens${feeSuffix}.`;
+  }
+  const created = actions.filter((a) => a.kind === "account-created");
+  if (created.length > 0) {
+    const what = created.some((c) => c.kind === "account-created" && c.as === "ata") ? "associated token account" : "account";
+    const plural = created.length > 1 ? `${created.length} accounts` : `an ${what}`;
+    return `Created ${plural}${feeSuffix}.`;
+  }
+  const memos = actions.filter((a) => a.kind === "memo");
+  const cb = actions.filter((a) => a.kind === "compute-budget");
+  if (memos.length > 0 && meaningfulDeltas.length === 0) {
+    const text = memos[0].kind === "memo" ? memos[0].text : "";
+    const memoNote = `attached memo "${text}"`;
+    return cb.length > 0 ? `Set compute budget; ${memoNote}${feeSuffix}.` : `${capitalize(memoNote)}${feeSuffix}.`;
+  }
+  if (cb.length > 0 && meaningfulDeltas.length === 0 && actions.every((a) => a.kind === "compute-budget")) {
+    return `Set compute budget only; no balance changes${feeSuffix}.`;
+  }
+  const calls = actions.filter((a) => a.kind === "program-call");
+  if (calls.length > 0) {
+    const named = calls.find((c) => c.kind === "program-call" && c.program);
+    const name = named && named.kind === "program-call" && named.program ? named.program : shortAddr(calls[0].kind === "program-call" ? calls[0].programId : "");
+    if (deltas.length > 0) {
+      return `Interacted with ${name}; see balance changes for the net effect${feeSuffix}.`;
+    }
+    return `Called ${name} (no net balance change)${feeSuffix}.`;
+  }
+  if (meaningfulDeltas.length > 0) {
+    return `Transaction changed ${meaningfulDeltas.length} balance${meaningfulDeltas.length > 1 ? "s" : ""}${feeSuffix}.`;
+  }
+  return `Transaction succeeded with no net balance change${feeSuffix}.`;
+}
+function absBig(n) {
+  return n < 0n ? -n : n;
+}
+function capitalize(s) {
+  return s.length === 0 ? s : s[0].toUpperCase() + s.slice(1);
+}
+
+// src/explain.ts
+function resolveRpc(rpc, timeoutMs) {
+  if (typeof rpc === "string") {
+    return createHttpRpc(rpc, { timeoutMs });
+  }
+  return rpc;
+}
+function resolveRegistry(opts) {
+  if (opts.registry) {
+    return defaultRegistry.merge(opts.registry.list());
+  }
+  return defaultRegistry;
+}
+function clampTimeout(timeoutMs) {
+  const def = 3e4;
+  if (timeoutMs === void 0) return { value: def };
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return { value: def, warning: `invalid timeout ${timeoutMs}; using ${def}ms` };
+  }
+  const min = 1e3;
+  const max = 6e5;
+  if (timeoutMs < min) return { value: min, warning: `timeout clamped up to ${min}ms` };
+  if (timeoutMs > max) return { value: max, warning: `timeout clamped down to ${max}ms` };
+  return { value: timeoutMs };
+}
+function buildExplanation(input) {
+  const deltas = diffBalances(input.pre, input.post);
+  for (const d of deltas) {
+    if (d.asset.kind === "token" && d.asset.symbol === void 0) {
+      const sym = resolveSymbol(d.asset.mint);
+      if (sym) d.asset.symbol = sym;
+    }
+  }
+  const allTokenBalances = [...input.pre.tokenBalances, ...input.post.tokenBalances];
+  const correlation = correlate({
+    instructions: input.instructions,
+    ...input.innerInstructions ? { innerInstructions: input.innerInstructions } : {},
+    deltas,
+    tokenBalances: allTokenBalances,
+    registry: input.registry
+  });
+  const summary = summarize({
+    actions: correlation.actions,
+    deltas,
+    programsInvoked: correlation.programsInvoked,
+    feePayer: input.feePayer,
+    feeLamports: input.feeLamports,
+    success: input.success,
+    ...input.error ? { error: input.error } : {},
+    ...input.focusAccount ? { focusAccount: input.focusAccount } : {}
+  });
+  const warnings = [...input.warnings ?? [], ...correlation.warnings];
+  const result = {
+    source: input.source,
+    ...input.signature ? { signature: input.signature } : {},
+    success: input.success,
+    ...input.error ? { error: input.error } : {},
+    ...input.slot !== void 0 ? { slot: input.slot } : {},
+    ...input.blockTime !== void 0 ? { blockTime: input.blockTime } : {},
+    feeLamports: input.feeLamports,
+    ...input.computeUnits !== void 0 ? { computeUnits: input.computeUnits } : {},
+    feePayer: input.feePayer,
+    summary,
+    actions: correlation.actions,
+    balanceChanges: deltas,
+    instructions: correlation.decoded,
+    accountsCreated: correlation.accountsCreated,
+    approvals: correlation.approvals,
+    programsInvoked: correlation.programsInvoked,
+    warnings,
+    ...input.includeRaw && input.raw !== void 0 ? { raw: input.raw } : {}
+  };
+  return result;
+}
+function normalizedToResult(norm, registry, opts, extraWarnings) {
+  const input = {
+    source: norm.source,
+    ...norm.signature ? { signature: norm.signature } : {},
+    feePayer: norm.feePayer,
+    success: norm.success,
+    ...norm.error ? { error: norm.error } : {},
+    ...norm.slot !== void 0 ? { slot: norm.slot } : {},
+    blockTime: norm.blockTime ?? null,
+    feeLamports: norm.feeLamports,
+    ...norm.computeUnits !== void 0 ? { computeUnits: norm.computeUnits } : {},
+    pre: norm.pre,
+    post: norm.post,
+    instructions: norm.instructions,
+    ...norm.innerInstructions ? { innerInstructions: norm.innerInstructions } : {},
+    registry,
+    ...opts.focusAccount ? { focusAccount: opts.focusAccount } : {},
+    warnings: [...norm.warnings, ...extraWarnings],
+    ...opts.includeRaw && norm.raw !== void 0 ? { raw: norm.raw } : {},
+    ...opts.includeRaw ? { includeRaw: true } : {}
+  };
+  const result = buildExplanation(input);
+  if (norm.source === "signature" && opts.commitment) {
+    result.commitment = opts.commitment;
+  }
+  return result;
+}
+async function explainSignature(signature, options) {
+  try {
+    const { value: timeoutMs, warning } = clampTimeout(options.timeoutMs);
+    const rpc = resolveRpc(options.rpc, timeoutMs);
+    const registry = resolveRegistry(options);
+    const commitment = options.commitment ?? "confirmed";
+    const norm = await acquireFromSignature({
+      rpc,
+      signature,
+      commitment,
+      maxSupportedTransactionVersion: options.maxSupportedTransactionVersion ?? 0,
+      ...options.signal ? { signal: options.signal } : {},
+      ...options.includeRaw ? { includeRaw: true } : {}
+    });
+    const extra = warning ? [{ code: "version-skew", message: warning }] : [];
+    return normalizedToResult(norm, registry, options, extra);
+  } catch (err) {
+    throw asExplainError(err, "failed to explain signature");
+  }
+}
+async function explainTransaction(tx, options) {
+  try {
+    const { value: timeoutMs, warning } = clampTimeout(options.timeoutMs);
+    const rpc = resolveRpc(options.rpc, timeoutMs);
+    const registry = resolveRegistry(options);
+    const commitment = options.commitment ?? "confirmed";
+    let bytes;
+    let ambiguous = false;
+    if (tx instanceof Uint8Array) {
+      const det = detectInput(tx);
+      if (det.kind !== "tx-bytes") {
+        throw new InputError("INVALID_INPUT", "Provided bytes are not a serialized transaction.");
+      }
+      bytes = det.bytes;
+    } else {
+      const det = detectTxBytes(tx, options.encoding ?? "auto");
+      bytes = det.bytes;
+      ambiguous = det.ambiguous;
+    }
+    const norm = await acquireFromSimulation({
+      rpc,
+      txBytes: bytes,
+      commitment,
+      replaceRecentBlockhash: options.replaceRecentBlockhash ?? true,
+      sigVerify: options.sigVerify ?? false,
+      ...options.signal ? { signal: options.signal } : {},
+      ...options.includeRaw ? { includeRaw: true } : {}
+    });
+    const extra = [];
+    if (ambiguous) {
+      extra.push({
+        code: "version-skew",
+        message: "input was decodable as both base64 and base58; interpreted as base64"
+      });
+    }
+    if (warning) extra.push({ code: "version-skew", message: warning });
+    return normalizedToResult(norm, registry, options, extra);
+  } catch (err) {
+    throw asExplainError(err, "failed to explain transaction");
+  }
+}
+async function explainInstructions(instructions, options) {
+  try {
+    if (!options.feePayer || options.feePayer.trim().length === 0) {
+      throw new InputError(
+        "INVALID_INPUT",
+        "feePayer is required to assemble a simulatable message from instructions.",
+        { hint: "Pass options.feePayer with the payer pubkey." }
+      );
+    }
+    if (!Array.isArray(instructions) || instructions.length === 0) {
+      throw new InputError("EMPTY_INPUT", "No instructions provided.");
+    }
+    const { value: timeoutMs, warning } = clampTimeout(options.timeoutMs);
+    const rpc = resolveRpc(options.rpc, timeoutMs);
+    const registry = resolveRegistry(options);
+    const commitment = options.commitment ?? "confirmed";
+    let blockhash;
+    try {
+      const bh = await rpc.getLatestBlockhash({
+        commitment,
+        ...options.signal ? { signal: options.signal } : {}
+      });
+      blockhash = bh.blockhash;
+    } catch {
+      blockhash = "11111111111111111111111111111111";
+    }
+    const txBytes = buildLegacyMessage(instructions, options.feePayer, blockhash);
+    const norm = await acquireFromSimulation({
+      rpc,
+      txBytes,
+      commitment,
+      replaceRecentBlockhash: true,
+      sigVerify: false,
+      ...options.signal ? { signal: options.signal } : {},
+      ...options.includeRaw ? { includeRaw: true } : {}
+    });
+    const extra = warning ? [{ code: "version-skew", message: warning }] : [];
+    return normalizedToResult(norm, registry, options, extra);
+  } catch (err) {
+    throw asExplainError(err, "failed to explain instructions");
+  }
+}
+function asExplainError(err, context) {
+  if (err instanceof SolanaExplainError) return err;
+  return wrapError(err, "INVALID_INPUT", context);
+}
+
+// src/render/ansi.ts
+var ESC = `${String.fromCharCode(27)}[`;
+var RESET = `${ESC}0m`;
+var CODES = {
+  bold: `${ESC}1m`,
+  dim: `${ESC}2m`,
+  red: `${ESC}31m`,
+  green: `${ESC}32m`,
+  yellow: `${ESC}33m`,
+  blue: `${ESC}34m`,
+  magenta: `${ESC}35m`,
+  cyan: `${ESC}36m`,
+  gray: `${ESC}90m`,
+  // VTX brand blue (#3182ce) via 256-color approximation.
+  brand: `${ESC}38;5;33m`
+};
+function wrap(enabled, code, s) {
+  return enabled ? `${code}${s}${RESET}` : s;
+}
+function createStyler(enabled) {
+  return {
+    enabled,
+    bold: (s) => wrap(enabled, CODES.bold, s),
+    dim: (s) => wrap(enabled, CODES.dim, s),
+    red: (s) => wrap(enabled, CODES.red, s),
+    green: (s) => wrap(enabled, CODES.green, s),
+    yellow: (s) => wrap(enabled, CODES.yellow, s),
+    blue: (s) => wrap(enabled, CODES.blue, s),
+    magenta: (s) => wrap(enabled, CODES.magenta, s),
+    cyan: (s) => wrap(enabled, CODES.cyan, s),
+    gray: (s) => wrap(enabled, CODES.gray, s),
+    brand: (s) => wrap(enabled, CODES.brand, s)
+  };
+}
+function shouldUseColor(opts) {
+  if (opts.explicit !== void 0) return opts.explicit;
+  const env = opts.env ?? {};
+  if (env["NO_COLOR"] !== void 0 && env["NO_COLOR"] !== "") return false;
+  if (env["FORCE_COLOR"] !== void 0 && env["FORCE_COLOR"] !== "0" && env["FORCE_COLOR"] !== "") {
+    return true;
+  }
+  return Boolean(opts.isTTY);
+}
+var ANSI_RE = new RegExp(`${String.fromCharCode(27)}[[0-9;]*m`, "g");
+function stripAnsi(s) {
+  return s.replace(ANSI_RE, "");
+}
+
+// src/render/index.ts
+var INDENT = "  ";
+function renderText(result, opts = {}) {
+  const s = createStyler(opts.color ?? false);
+  const lines = [];
+  if (opts.quiet) {
+    return result.summary;
+  }
+  const commitmentNote = result.source === "simulation" ? "simulation" : result.commitment ?? "confirmed";
+  const when = formatBlockTime(result.blockTime);
+  const headParts = [
+    `Solana transaction`,
+    commitmentNote,
+    result.slot !== void 0 ? `slot ${formatCount(result.slot)}` : void 0,
+    when
+  ].filter(Boolean);
+  lines.push("");
+  lines.push(`${INDENT}${s.brand(headParts.join(" \xB7 "))}`);
+  const status = result.success ? s.green("\u2713 Success") : s.red("\u2717 Failed");
+  if (result.signature) {
+    lines.push(`${INDENT}${s.dim("Signature")}  ${shortAddr(result.signature, 6, 6)}   ${status}`);
+  } else {
+    lines.push(`${INDENT}${s.dim("Source")}     ${result.source}   ${status}`);
+  }
+  lines.push("");
+  lines.push(`${INDENT}${s.bold("Summary")}    ${result.summary}`);
+  if (!result.success && result.error) {
+    lines.push(`${INDENT}${s.red("Error")}      ${result.error.human}`);
+  }
+  if (result.balanceChanges.length > 0) {
+    lines.push("");
+    lines.push(`${INDENT}${s.bold("Balance changes")}`);
+    for (const d of groupBalances(result.balanceChanges, result.feePayer)) {
+      const label = d.label;
+      const focusTag = d.account === result.feePayer ? s.dim(" (fee payer)") : "";
+      const colored = colorDelta(d.text, s);
+      lines.push(`${INDENT}${INDENT}${padRight(label, 22)}${colored}${focusTag}`);
+    }
+  }
+  if (result.actions.length > 0) {
+    lines.push("");
+    lines.push(`${INDENT}${s.bold("Actions")}`);
+    result.actions.forEach((a, i) => {
+      lines.push(`${INDENT}${INDENT}${i + 1}. ${describeAction(a)}`);
+    });
+  }
+  if (opts.verbose && result.instructions.length > 0) {
+    lines.push("");
+    lines.push(`${INDENT}${s.bold("Instructions")}`);
+    for (const ix of result.instructions) {
+      renderInstruction(ix, lines, s, 2);
+    }
+  }
+  if (result.programsInvoked.length > 0) {
+    const names = result.programsInvoked.map((p) => p.name ?? shortAddr(p.programId)).filter((v, idx, arr) => arr.indexOf(v) === idx);
+    lines.push("");
+    lines.push(`${INDENT}${s.bold("Programs")}   ${names.join(" \xB7 ")}`);
+  }
+  const feeStr = `${lamportsToSol(result.feeLamports)} SOL`;
+  const computeStr = result.computeUnits !== void 0 ? `${formatCount(result.computeUnits)} units` : "n/a";
+  lines.push(`${INDENT}${s.bold("Fee")}        ${feeStr}${" ".repeat(8)}${s.bold("Compute")}   ${computeStr}`);
+  if (result.warnings.length > 0) {
+    lines.push("");
+    lines.push(`${INDENT}${s.yellow(`\u26A0 ${result.warnings.length} warning${result.warnings.length > 1 ? "s" : ""}`)}`);
+    for (const w of result.warnings) {
+      const at = w.instructionIndex !== void 0 ? ` [ix #${w.instructionIndex}]` : "";
+      lines.push(`${INDENT}${INDENT}${s.dim("\xB7")} ${w.message}${s.dim(at)}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderInstruction(ix, lines, s, depth) {
+  const pad = INDENT.repeat(depth);
+  const name = ix.program ?? shortAddr(ix.programId);
+  const type = ix.type ? `.${ix.type}` : "";
+  const mark = ix.decoded ? "" : s.dim(" (not decoded)");
+  lines.push(`${pad}${s.cyan(`#${ix.index}`)} ${name}${type}${mark}`);
+  if (ix.args && Object.keys(ix.args).length > 0) {
+    const argStr = Object.entries(ix.args).map(([k, v]) => `${k}=${String(v)}`).join(", ");
+    lines.push(`${pad}${INDENT}${s.dim(argStr)}`);
+  }
+  if (ix.inner) {
+    for (const inner of ix.inner) renderInstruction(inner, lines, s, depth + 1);
+  }
+}
+function groupBalances(deltas, feePayer) {
+  const byAccount = /* @__PURE__ */ new Map();
+  for (const d of deltas) {
+    const list = byAccount.get(d.account) ?? [];
+    list.push(d);
+    byAccount.set(d.account, list);
+  }
+  const out = [];
+  for (const [account, list] of byAccount) {
+    const text = list.map((d) => d.uiDelta).join("   ");
+    const isFee = account === feePayer;
+    out.push({ account, label: shortAddr(account, 4, 4) + (isFee ? "" : ""), text });
+  }
+  return out;
+}
+function colorDelta(text, s) {
+  return text.split("   ").map(
+    (part) => part.trim().startsWith("-") ? s.red(part) : part.trim().startsWith("+") ? s.green(part) : part
+  ).join("   ");
+}
+function padRight(str, width) {
+  const visible = stripAnsi(str);
+  return visible.length >= width ? str : str + " ".repeat(width - visible.length);
+}
+function describeAction(a) {
+  switch (a.kind) {
+    case "sol-transfer":
+      return `Transfer ${a.sol} SOL  ${shortAddr(a.from)} \u2192 ${shortAddr(a.to)}`;
+    case "token-transfer": {
+      const sym = a.symbol ?? shortAddr(a.mint);
+      const self = a.from === a.to ? "  (self-transfer)" : "";
+      return `Transfer ${a.uiAmount} ${sym}  ${shortAddr(a.from)} \u2192 ${shortAddr(a.to)}${self}`;
+    }
+    case "mint":
+      return `Mint ${a.uiAmount} of ${shortAddr(a.mint)} \u2192 ${shortAddr(a.to)}`;
+    case "burn":
+      return `Burn ${a.uiAmount} of ${shortAddr(a.mint)} from ${shortAddr(a.from)}`;
+    case "account-created": {
+      const as = a.as ? ` (${a.as})` : "";
+      return `Create account ${shortAddr(a.address)}${as} owned by ${shortAddr(a.owner)}`;
+    }
+    case "approval":
+      if (a.revoke) return `Revoke delegate on ${shortAddr(a.owner)}`;
+      return `Approve ${a.amount === "unlimited" ? "unlimited" : a.amount.toString()} to delegate ${shortAddr(a.delegate)}`;
+    case "close-account":
+      return `Close account ${shortAddr(a.account)} \u2192 reclaim ${lamportsToSol(a.reclaimedLamports)} SOL to ${shortAddr(a.destination)}`;
+    case "memo":
+      return `Memo: "${a.text}"`;
+    case "compute-budget": {
+      const parts = [];
+      if (a.unitLimit !== void 0) parts.push(`unit limit ${groupThousands(a.unitLimit.toString())}`);
+      if (a.unitPriceMicroLamports !== void 0)
+        parts.push(`price ${a.unitPriceMicroLamports.toString()} \xB5-lamports`);
+      return `Set compute budget: ${parts.join(", ") || "(no-op)"}`;
+    }
+    case "program-call": {
+      const name = a.program ?? shortAddr(a.programId);
+      const note = a.note ? `  \u2014 ${a.note}` : "";
+      return `Call ${name}${a.instruction ? `.${a.instruction}` : ""}${note}`;
+    }
+  }
+}
+function renderMarkdown(result) {
+  const lines = [];
+  lines.push(`### Solana transaction \u2014 ${result.success ? "\u2705 Success" : "\u274C Failed"}`);
+  lines.push("");
+  if (result.signature) lines.push(`**Signature:** \`${result.signature}\`  `);
+  if (result.slot !== void 0) lines.push(`**Slot:** ${formatCount(result.slot)}  `);
+  const when = formatBlockTime(result.blockTime);
+  if (when) lines.push(`**Time:** ${when}  `);
+  lines.push(`**Fee:** ${lamportsToSol(result.feeLamports)} SOL  `);
+  if (result.computeUnits !== void 0)
+    lines.push(`**Compute:** ${formatCount(result.computeUnits)} units  `);
+  lines.push("");
+  lines.push(`> ${result.summary}`);
+  lines.push("");
+  if (!result.success && result.error) {
+    lines.push(`**Error:** ${result.error.human}`);
+    lines.push("");
+  }
+  if (result.balanceChanges.length > 0) {
+    lines.push("#### Balance changes");
+    lines.push("");
+    lines.push("| Account | Asset | Change |");
+    lines.push("| --- | --- | --- |");
+    for (const d of result.balanceChanges) {
+      const asset = d.asset.kind === "SOL" ? "SOL" : `${d.asset.symbol ?? shortAddr(d.asset.mint)}`;
+      lines.push(`| \`${shortAddr(d.account, 6, 6)}\` | ${asset} | ${d.uiDelta} |`);
+    }
+    lines.push("");
+  }
+  if (result.actions.length > 0) {
+    lines.push("#### Actions");
+    lines.push("");
+    result.actions.forEach((a, i) => lines.push(`${i + 1}. ${describeAction(a)}`));
+    lines.push("");
+  }
+  if (result.programsInvoked.length > 0) {
+    lines.push("#### Programs");
+    lines.push("");
+    for (const p of result.programsInvoked) {
+      lines.push(`- ${p.name ?? `\`${p.programId}\``} \xD7${p.count}`);
+    }
+    lines.push("");
+  }
+  if (result.warnings.length > 0) {
+    lines.push("#### Warnings");
+    lines.push("");
+    for (const w of result.warnings) lines.push(`- \u26A0\uFE0F ${w.message} \`(${w.code})\``);
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+function renderJson(result, opts) {
+  const replacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
+  return JSON.stringify(result, replacer, 2 );
+}
+
+// src/cli/help.ts
+function helpText(color) {
+  const s = createStyler(color);
+  const b = s.brand;
+  const d = s.dim;
+  const bold = s.bold;
+  return `
+${b("  \u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557  \u2588\u2588\u2557  \u2588\u2588\u2557      \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557")}
+${b("  \u2588\u2588\u2551   \u2588\u2588\u2551\u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D\u255A\u2588\u2588\u2557\u2588\u2588\u2554\u255D  \u2588\u2588\u2551     \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D")}
+${b("  \u2588\u2588\u2551   \u2588\u2588\u2551   \u2588\u2588\u2551    \u255A\u2588\u2588\u2588\u2554\u255D   \u2588\u2588\u2551     \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557")}
+${b("  \u255A\u2588\u2588\u2557 \u2588\u2588\u2554\u255D   \u2588\u2588\u2551    \u2588\u2588\u2554\u2588\u2588\u2557   \u2588\u2588\u2551     \u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2551")}
+${b("   \u255A\u2588\u2588\u2588\u2588\u2554\u255D    \u2588\u2588\u2551   \u2588\u2588\u2554\u255D \u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551")}
+${b("    \u255A\u2550\u2550\u2550\u255D     \u255A\u2550\u255D   \u255A\u2550\u255D  \u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D\u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D")}
+  ${bold("solana-explain")}  ${d("\xB7 plain-English Solana tx reports \xB7 vtxlabs.dev")}
+
+${bold("USAGE")}
+  solana-explain <input> [options]
+  solana-explain --stdin [options]
+  solana-explain --file <path> [options]
+
+  <input> is auto-detected: a base58 signature, a base64/base58 serialized
+  transaction, or '-' / --stdin for piped data. JSON instruction sets are
+  accepted only via --stdin or --file (a JSON array of instructions).
+
+${bold("OPTIONS")}
+  -r, --rpc <url>          RPC endpoint URL. Falls back to $SOLANA_RPC_URL, then
+                           $RPC_URL. Required if neither is set.
+  -c, --commitment <c>     processed | confirmed | finalized   ${d("(default: confirmed)")}
+      --cluster <name>     Preset for -r: mainnet | devnet | testnet | localnet
+      --simulate           Force the simulate path even for a signature input
+      --focus <pubkey>     Phrase balance deltas from this account's perspective
+  -j, --json               Emit machine-readable JSON (the ExplainResult)
+      --markdown           Emit Markdown (great for issues / PRs / docs)
+      --raw                Include the raw RPC payload under result.raw (with -j)
+      --no-color           Disable ANSI color (auto-off when !isTTY or $NO_COLOR)
+      --max-tx-version <n> Max supported tx version for getTransaction ${d("(default: 0)")}
+      --timeout <ms>       Per-run network timeout ${d("(default: 30000)")}
+      --stdin              Read input from stdin
+      --file <path>        Read input from a file
+      --fee-payer <pubkey> Fee payer for JSON instruction-set input
+  -q, --quiet              Only the summary line + nonzero exit on failure
+  -v, --verbose            Show every instruction incl. inner/CPI tree + raw args
+      --version            Print version and exit
+  -h, --help               Show this help and exit
+
+${bold("EXAMPLES")}
+  ${d("# Explain a confirmed transaction by signature")}
+  solana-explain 5Nq...d8 --rpc https://api.mainnet-beta.solana.com
+
+  ${d("# Simulate & explain a base64 transaction piped from another tool")}
+  cat unsigned.b64 | solana-explain --stdin --simulate -r $SOLANA_RPC_URL
+
+  ${d("# Explain an instruction set from a file as machine-readable JSON")}
+  solana-explain --file ixs.json --fee-payer 7Bf...a21 --cluster devnet -j
+
+${bold("EXIT CODES")}
+  0 success   2 tx failed   3 not found   4 bad input   5 RPC error
+  6 sim rejected   1 internal error   130 aborted (Ctrl-C)
+`;
+}
+
+// src/cli/index.ts
+var VERSION = "0.1.0";
+var CLUSTER_URLS = {
+  mainnet: "https://api.mainnet-beta.solana.com",
+  "mainnet-beta": "https://api.mainnet-beta.solana.com",
+  devnet: "https://api.devnet.solana.com",
+  testnet: "https://api.testnet.solana.com",
+  localnet: "http://127.0.0.1:8899",
+  localhost: "http://127.0.0.1:8899"
+};
+function exitCodeFor(err) {
+  switch (err.code) {
+    case "TX_NOT_FOUND":
+      return 3;
+    case "INVALID_INPUT":
+    case "INVALID_SIGNATURE":
+    case "INVALID_ENCODING":
+    case "EMPTY_INPUT":
+    case "DECODE_FAILED":
+    case "UNSUPPORTED_TX_VERSION":
+      return 4;
+    case "RPC_HTTP":
+    case "RPC_JSON":
+    case "RPC_TIMEOUT":
+      return 5;
+    case "SIMULATION_REJECTED":
+      return 6;
+    case "ABORTED":
+      return 130;
+    default:
+      return 1;
+  }
+}
+async function readStdin() {
+  const chunks = [];
+  return new Promise((resolve, reject) => {
+    process.stdin.on("data", (c) => chunks.push(c));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    process.stdin.on("error", reject);
+  });
+}
+function parse(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      rpc: { type: "string", short: "r" },
+      commitment: { type: "string", short: "c" },
+      cluster: { type: "string" },
+      simulate: { type: "boolean" },
+      focus: { type: "string" },
+      json: { type: "boolean", short: "j" },
+      markdown: { type: "boolean" },
+      raw: { type: "boolean" },
+      color: { type: "boolean", default: true },
+      // --no-color sets false
+      "max-tx-version": { type: "string" },
+      timeout: { type: "string" },
+      stdin: { type: "boolean" },
+      file: { type: "string" },
+      "fee-payer": { type: "string" },
+      quiet: { type: "boolean", short: "q" },
+      verbose: { type: "boolean", short: "v" },
+      version: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  return { values, positionals };
+}
+async function resolveInputString(values, positionals, stderr) {
+  const file = values["file"];
+  const wantsStdin = Boolean(values["stdin"]) || positionals[0] === "-";
+  if (file) {
+    try {
+      return await readFile(file, "utf8");
+    } catch (err) {
+      throw new InputError(
+        "INVALID_INPUT",
+        `Cannot read file "${file}": ${err instanceof Error ? err.message : String(err)}`,
+        { hint: "Check the path and permissions." }
+      );
+    }
+  }
+  if (wantsStdin) {
+    if (process.stdin.isTTY) {
+      stderr.write("waiting for piped input\u2026 (Ctrl-D to end; or pass <input> directly)\n");
+    }
+    const data = await readStdin();
+    if (data.trim().length === 0) {
+      throw new InputError("EMPTY_INPUT", "Nothing was piped to stdin.", {
+        hint: "Pipe a signature/transaction, or pass <input> as an argument."
+      });
+    }
+    return data;
+  }
+  const positional = positionals[0];
+  if (positional === void 0 || positional.trim().length === 0) {
+    throw new InputError("EMPTY_INPUT", "No input provided.", {
+      hint: "Pass a signature/transaction, use --stdin, or --file <path>."
+    });
+  }
+  return positional;
+}
+function resolveRpcUrl(values, env) {
+  const cluster = values["cluster"];
+  const explicit = values["rpc"];
+  if (explicit) return explicit;
+  if (cluster) {
+    const url = CLUSTER_URLS[cluster.toLowerCase()];
+    if (!url) {
+      throw new InputError(
+        "INVALID_INPUT",
+        `Unknown cluster "${cluster}". Use mainnet | devnet | testnet | localnet.`
+      );
+    }
+    return url;
+  }
+  const fromEnv = env["SOLANA_RPC_URL"] ?? env["RPC_URL"];
+  if (fromEnv) return fromEnv;
+  throw new InputError("INVALID_INPUT", "No RPC URL.", {
+    hint: "Pass --rpc <url>, --cluster <name>, or set SOLANA_RPC_URL."
+  });
+}
+async function run(argv, io) {
+  let values;
+  let positionals;
+  try {
+    const parsed = parse(argv);
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (err) {
+    const colorEarly = shouldUseColor({ isTTY: io.stderr.isTTY, env: io.env });
+    const s2 = createStyler(colorEarly);
+    io.stderr.write(`${s2.red("Error")} ${err instanceof Error ? err.message : String(err)}
+`);
+    io.stderr.write(`Run ${s2.bold("solana-explain --help")} for usage.
+`);
+    return 4;
+  }
+  const machineOutput = Boolean(values["json"] || values["markdown"]);
+  const colorEnabled = !machineOutput && shouldUseColor({
+    ...values["color"] === false ? { explicit: false } : {},
+    isTTY: io.stdout.isTTY,
+    env: io.env
+  });
+  const s = createStyler(colorEnabled);
+  const debug = Boolean(io.env["DEBUG"]) || Boolean(values["verbose"]);
+  if (values["help"]) {
+    io.stdout.write(helpText(colorEnabled));
+    return 0;
+  }
+  if (values["version"]) {
+    io.stdout.write(`${VERSION}
+`);
+    return 0;
+  }
+  try {
+    const inputStr = await resolveInputString(values, positionals, io.stderr);
+    const rpcUrl = resolveRpcUrl(values, io.env);
+    const commitment = values["commitment"] ?? "confirmed";
+    if (!["processed", "confirmed", "finalized"].includes(commitment)) {
+      throw new InputError("INVALID_INPUT", `Invalid commitment "${commitment}".`);
+    }
+    const timeoutMs = values["timeout"] ? Number(values["timeout"]) : void 0;
+    const maxTxVersion = values["max-tx-version"] ? Number(values["max-tx-version"]) : 0;
+    const baseOpts = {
+      rpc: rpcUrl,
+      commitment,
+      ...values["focus"] ? { focusAccount: values["focus"] } : {},
+      ...timeoutMs !== void 0 ? { timeoutMs } : {},
+      ...io.signal ? { signal: io.signal } : {},
+      ...values["raw"] ? { includeRaw: true } : {}
+    };
+    let result;
+    const detected = detectInput(inputStr);
+    if (values["simulate"] && detected.kind === "signature") {
+      throw new InputError(
+        "INVALID_INPUT",
+        "--simulate requires a serialized transaction, not a signature.",
+        { hint: "Pipe a base64/base58 transaction with --simulate." }
+      );
+    }
+    if (detected.kind === "signature") {
+      result = await explainSignature(detected.signature, {
+        ...baseOpts,
+        maxSupportedTransactionVersion: maxTxVersion
+      });
+    } else if (detected.kind === "tx-bytes") {
+      result = await explainTransaction(detected.bytes, {
+        ...baseOpts,
+        encoding: detected.encoding
+      });
+    } else {
+      const feePayer = values["fee-payer"] ?? "";
+      if (!feePayer) {
+        throw new InputError(
+          "INVALID_INPUT",
+          "Instruction-set input requires --fee-payer <pubkey>.",
+          { hint: "Add --fee-payer with the payer pubkey." }
+        );
+      }
+      result = await explainInstructions(detected.instructions, {
+        ...baseOpts,
+        feePayer
+      });
+    }
+    if (values["json"]) {
+      io.stdout.write(renderJson(result, { pretty: true }) + "\n");
+    } else if (values["markdown"]) {
+      io.stdout.write(renderMarkdown(result));
+    } else if (values["quiet"]) {
+      io.stdout.write(result.summary + "\n");
+      for (const w of result.warnings) io.stderr.write(`${s.yellow("\u26A0")} ${w.message}
+`);
+    } else {
+      io.stdout.write(renderText(result, { color: colorEnabled, verbose: Boolean(values["verbose"]) }) + "\n");
+    }
+    return result.success ? 0 : 2;
+  } catch (err) {
+    return handleError(err, s, io.stderr, debug);
+  }
+}
+function handleError(err, s, stderr, debug) {
+  if (err instanceof SimulationError) {
+    stderr.write(`${s.red("Error")} ${err.message}
+`);
+    if (err.logs && err.logs.length > 0) {
+      stderr.write(`${s.dim("Logs (tail):")}
+`);
+      for (const l of err.logs) stderr.write(`${s.dim("  " + l)}
+`);
+    }
+    if (err.hint) stderr.write(`${s.dim("Hint:")} ${err.hint}
+`);
+    if (debug && err.cause) stderr.write(`${String(err.cause)}
+`);
+    return exitCodeFor(err);
+  }
+  if (err instanceof SolanaExplainError) {
+    stderr.write(`${s.red("Error")} ${err.message}
+`);
+    if (err.hint) stderr.write(`${s.dim("Hint:")} ${err.hint}
+`);
+    if (debug && err.cause) {
+      stderr.write(`${s.dim("Cause:")} ${err.cause instanceof Error ? err.cause.stack ?? err.cause.message : String(err.cause)}
+`);
+    }
+    return exitCodeFor(err);
+  }
+  stderr.write(`${s.red("Internal error")} ${err instanceof Error ? err.message : String(err)}
+`);
+  stderr.write(
+    `${s.dim("This is likely a bug. Please report it: https://github.com/VTX-Labs/solana-explain/issues")}
+`
+  );
+  if (debug && err instanceof Error && err.stack) stderr.write(`${err.stack}
+`);
+  return 1;
+}
+async function main() {
+  const controller = new AbortController();
+  const onSigint = () => controller.abort();
+  process.on("SIGINT", onSigint);
+  let exitCode;
+  try {
+    exitCode = await run(process.argv.slice(2), {
+      stdout: process.stdout,
+      stderr: process.stderr,
+      env: process.env,
+      signal: controller.signal
+    });
+  } catch (err) {
+    process.stderr.write(`Internal error: ${err instanceof Error ? err.message : String(err)}
+`);
+    exitCode = 1;
+  } finally {
+    process.off("SIGINT", onSigint);
+  }
+  if (controller.signal.aborted) {
+    process.exitCode = 130;
+  } else {
+    process.exitCode = exitCode;
+  }
+}
+var isMain = (() => {
+  try {
+    const invoked = process.argv[1];
+    if (!invoked) return false;
+    return import.meta.url === pathToFileURL(invoked).href;
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  void main();
+}
+
+export { run };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map