nansen-cli 1.40.0 → 1.41.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.41.0
+
+### Minor Changes
+
+- [#512](https://github.com/nansen-ai/nansen-cli/pull/512) [`ba42a9c`](https://github.com/nansen-ai/nansen-cli/commit/ba42a9c51d75b0cf909c1f14a8e509d7a4ca77ad) Thanks [@kome12](https://github.com/kome12)! - Validate Solana swap quotes against the original request before signing (local, Privy, and WalletConnect wallets). The CLI now checks that a quote's chain, token pair, amounts, and target wallet match what was requested at quote time and refuses to sign when they don't, bringing Solana in line with the existing EVM checks. `--swap-mode exactOut` now also requires `--max-input` on Solana (previously EVM-only), so the maximum spend is bounded by a value you supply rather than one taken from the quote itself.
+
+- [#514](https://github.com/nansen-ai/nansen-cli/pull/514) [`1bc7337`](https://github.com/nansen-ai/nansen-cli/commit/1bc73378db87fed5c362e04b52ae8da8c69fbff7) Thanks [@kome12](https://github.com/kome12)! - `trade execute` and `trade limit-order` on Solana now statically check the aggregator's compiled instructions before signing, and reject a transaction that grants a token delegate, changes a token account's authority, closes an account with its rent redirected to a stranger, or sets an excessive compute-budget priority fee — closing a class of drain vector a balance-delta simulation alone can't see.
+
+- [#522](https://github.com/nansen-ai/nansen-cli/pull/522) [`820bf05`](https://github.com/nansen-ai/nansen-cli/commit/820bf058de615a818fa099c8bf527a94339c8f9e) Thanks [@kome12](https://github.com/kome12)! - Verify a Solana swap's simulated on-chain outcome before signing (local, Privy, and WalletConnect wallets), mirroring the existing EVM balance-delta check. The CLI simulates the aggregator's transaction and confirms the wallet's balance changes match the quote — input spent within your max, expected output received, no other asset drained — refusing to sign on a mismatch or an in-simulation revert. Covered by the existing `--no-verify-outcome` flag; degrades with a warning (and still signs) when no simulation-capable RPC is available, so an RPC outage never blocks a trade. New env var: `NANSEN_SOLANA_SIM_RPC`.
+
+### Patch Changes
+
+- [#519](https://github.com/nansen-ai/nansen-cli/pull/519) [`55ab7db`](https://github.com/nansen-ai/nansen-cli/commit/55ab7dbdc46ff7181b303d421146691b6eb7c9a7) Thanks [@kome12](https://github.com/kome12)! - trade execute: confirm EVM transactions against the hash derived locally from
+  the signed bytes instead of trusting the broadcaster's reported hash, and fail
+  closed if they disagree. Once a transaction has been broadcast, every uncertain
+  outcome now aborts the whole execute instead of silently trying the next quote
+  (which could broadcast a second transaction): a hash mismatch, a signed
+  transaction we cannot re-derive a hash for, and a receipt-confirmation timeout
+  (distinguished from a genuine on-chain revert) are all fatal across the swap,
+  approval, and revoke paths. Broadcaster hashes are also compared
+  prefix-insensitively, so a bare (0x-less) hash is no longer a false mismatch.
+
+- [#521](https://github.com/nansen-ai/nansen-cli/pull/521) [`977e326`](https://github.com/nansen-ai/nansen-cli/commit/977e3269246cc1c25d03e837c9ce4ac03c5d70b9) Thanks [@aikido-autofix](https://github.com/apps/aikido-autofix)! - Fix potential path traversal in safeQuotesPath by rejecting absolute relative paths (Windows cross-drive escape).
+
+- [#497](https://github.com/nansen-ai/nansen-cli/pull/497) [`223a9d5`](https://github.com/nansen-ai/nansen-cli/commit/223a9d501c0e624f3986a547ace3adf621c00896) Thanks [@crazywriter1](https://github.com/crazywriter1)! - Reject `--oid` values above 2^53-1 on `perp cancel`: large Hyperliquid uint64 order IDs would be silently rounded by JS Number, potentially cancelling the wrong order.
+
+## 1.40.1
+
+### Patch Changes
+
+- [#516](https://github.com/nansen-ai/nansen-cli/pull/516) [`48722ef`](https://github.com/nansen-ai/nansen-cli/commit/48722ef0c7e6c0a7ce8c4c026245afb6e6f47e79) Thanks [@kome12](https://github.com/kome12)! - Fix cross-chain bridges into native SOL being refused at execute time. The quote/intent binding compared the wrapped-SOL mint (how `--to SOL` resolves) against the System Program address that aggregators use as the native-SOL sentinel and rejected them as different tokens. Both spellings are now treated as the same asset.
+
 ## 1.40.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nansen-cli",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "description": "AI-agent CLI for Nansen API analytics, DEX swaps, and cross-chain trading",
   "main": "src/index.js",
   "type": "module",

package/src/limit-order.js

@@ -11,6 +11,7 @@ import path from 'path';
 import { base58Encode, exportWallet, getWalletConfig, showWallet } from './wallet.js';
 import { signEd25519, base58Decode, parseAmount, getTokenInfo } from './transfer.js';
 import { signSolanaTransaction, resolveTokenAddress } from './trading.js';
+import { assertSolanaInstructionsSafe } from './trade-validation.js';
 import { validateTokenAddress, telemetryHeaders, packageVersion } from './api.js';
 import { getWalletConnectAddress, sendSolanaTransactionViaWalletConnect, signSolanaMessageViaWalletConnect } from './walletconnect-trading.js';
 import { retrievePassword } from './keychain.js';
@@ -673,6 +674,17 @@ EXAMPLES:
         });
 
         // 5. Sign deposit transaction
+        // Same pre-signing drain gate the swap path uses. The legitimate deposit
+        // moves the input token into the already-registered vault (step 3) with an
+        // SPL Transfer/TransferChecked — which this gate does not classify — plus,
+        // when selling native SOL, a temp-WSOL CloseAccount whose rent returns to
+        // the wallet (permitted). Neither trips the delegate/authority/
+        // close-to-stranger checks, so this does not reject a well-formed deposit;
+        // it only fires if the crafted tx additionally grants a delegate, reassigns
+        // authority, or closes to a stranger. Verified live: a real SOL→USDC create
+        // round-trip clears this gate (the API-crafted deposit is a SOL-wrap
+        // transfer into the vault plus a temp-WSOL close-to-self).
+        assertSolanaInstructionsSafe(deposit.transaction, { walletAddress: pubkey });
         log('  Signing deposit transaction...');
         const signedDepositTx = await signTransaction(deposit.transaction, walletType, walletInfo);
 
@@ -807,6 +819,14 @@ EXAMPLES:
         const cancelResult = await cancelOrderRequest(token, orderId);
 
         // 3. Sign the withdrawal transaction
+        // Withdrawal moves the deposited token back out of the vault; that transfer
+        // is authorized by the vault program's PDA, not our wallet, so it isn't a
+        // wallet-authorized drain even if it were classified. Any temp-WSOL close
+        // returns rent to the wallet. This gate is defense-in-depth against a
+        // crafted withdrawal that instead grants a delegate, reassigns authority, or
+        // closes to a stranger. Verified live alongside the deposit path via a real
+        // cancel round-trip.
+        assertSolanaInstructionsSafe(cancelResult.transaction, { walletAddress: pubkey });
         log('  Signing withdrawal transaction...');
         const signedTx = await signTransaction(cancelResult.transaction, walletType, walletInfo);
 

package/src/perp.js

@@ -466,6 +466,12 @@ function parsePositiveInt(raw, name) {
   if (!Number.isInteger(n) || n <= 0) {
     throw invalid(`Invalid --${name} "${raw}". Must be a positive integer.`);
   }
+  // Hyperliquid order IDs are uint64. JS Number loses precision above 2^53-1,
+  // so parseInt would silently round a large oid and cancel the wrong order.
+  // Refuse here for the same reason the response path withholds unsafe oids.
+  if (!Number.isSafeInteger(n)) {
+    throw invalid(`Invalid --${name} "${raw}". Value exceeds safe integer precision (2^53-1); copy the exact order ID from "nansen perp positions".`);
+  }
   return n;
 }
 

package/src/rpc-urls.js

@@ -12,6 +12,7 @@
  *   NANSEN_XLAYER_RPC     Custom X Layer RPC
  *   NANSEN_SOLANA_RPC     Custom Solana RPC
  *   NANSEN_BASE_SIM_RPC   Custom Base simulation RPC (see SIMULATION_RPCS below)
+ *   NANSEN_SOLANA_SIM_RPC Custom Solana simulation RPC (see SIMULATION_RPCS below)
  *
  * Simulation RPCs (SIMULATION_RPCS) are a SEPARATE registry from the cheap
  * defaults above. Swap-outcome verification (src/swap-simulation.js) needs an
@@ -76,8 +77,16 @@ const DEFAULT_BASE_SIM_RPC = 'https://api.nansen.ai/api/v1/trade/simulate-swap';
 // Intentionally a mutable export: unit tests override an entry in-place (e.g.
 // `SIMULATION_RPCS.base = ...`) to point at a mock or to null out the endpoint,
 // restoring it in afterEach. Runtime code only ever reads it.
+//
+// Solana's `simulateTransaction` (with `accounts` + `replaceRecentBlockhash`) is
+// a standard public-RPC method, unlike the EVM entry above — no trace RPC or
+// Nansen-hosted proxy is needed, so this defaults to the same public endpoint as
+// CHAIN_RPCS.solana. It is called anonymously (see isNansenHostedUrl); a public
+// node may throttle simulation-with-accounts, in which case the check degrades
+// (warns and proceeds) rather than blocking a trade.
 export const SIMULATION_RPCS = {
   base: process.env.NANSEN_BASE_SIM_RPC || DEFAULT_BASE_SIM_RPC,
+  solana: process.env.NANSEN_SOLANA_SIM_RPC || CHAIN_RPCS.solana,
 };
 
 // Nansen hosts the API key may be forwarded to. Kept to an explicit allowlist

package/src/schema.json

@@ -1586,7 +1586,7 @@
             },
             "max-input": {
               "type": "string",
-              "description": "exactOut only: hard ceiling on the sell-token spend, in base units. Required for EVM (Base) exactOut and optional on Solana (which has no ERC-20 approval to scope). Measured against the slippage-buffered approval (input + slippage), not the bare quote input, so it matches the amount that can actually leave the wallet. Persisted with the quote and enforced before any approval or signing — a quote whose buffered approval exceeds it is refused."
+              "description": "exactOut only: hard ceiling on the sell-token spend, in base units. Required on every chain for --swap-mode exactOut. Measured against the slippage-buffered spend (input + slippage), not the bare quote input, so it matches the amount that can actually leave the wallet. Persisted with the quote and enforced before signing — a quote whose buffered spend exceeds it is refused."
             }
           },
           "prerequisites": [
@@ -1624,7 +1624,7 @@
             },
             "no-verify-outcome": {
               "type": "boolean",
-              "description": "Skip EVM swap-outcome verification. That check simulates the swap and confirms the wallet's balance changes match the quote (input spent within your max, expected output received, no other token moved) before broadcasting; it needs a simulation-capable endpoint (NANSEN_BASE_SIM_RPC) and degrades with a warning when none is available. No effect on Solana."
+              "description": "Skip swap-outcome verification. That check simulates the swap and confirms the wallet's balance changes match the quote (input spent within your max, expected output received, no other asset moved) before broadcasting; it needs a simulation-capable endpoint (NANSEN_BASE_SIM_RPC on EVM, NANSEN_SOLANA_SIM_RPC on Solana) and degrades with a warning when none is available."
             },
             "no-revoke-excessive-allowance": {
               "type": "boolean",

package/src/solana-simulation.js

@@ -0,0 +1,345 @@
+/**
+ * Solana swap-outcome simulation: run a swap transaction through
+ * `simulateTransaction` and report the resulting balance changes to the
+ * signer's wallet.
+ *
+ * This is the Solana sibling of swap-simulation.js. Solana signs the
+ * aggregator's serialized transaction verbatim, so this is the only check that
+ * confirms the wallet actually comes out the way the quote promised — the
+ * static checks in trade-validation.js inspect the instructions themselves,
+ * not their effect. All delta math runs here, client-side, from the raw
+ * `accounts` snapshot the RPC returns, so the verification stays independent
+ * of the service that built the quote.
+ *
+ * Unlike the EVM simulation endpoint, `simulateTransaction` (with `accounts` +
+ * `replaceRecentBlockhash`) is a standard public-RPC method — no trace RPC, no
+ * Nansen-hosted proxy. It is always called anonymously (see SIMULATION_RPCS.solana
+ * in rpc-urls.js); the Nansen API key is never attached here.
+ */
+
+import { SIMULATION_RPCS } from './rpc-urls.js';
+import { parseTransactionMessage } from './solana-tx.js';
+import { base58Encode } from './wallet.js';
+
+// Mirrors NATIVE_SOL_SYSTEM_MINT in trading.js / SOLANA_NATIVE_SOL_ALIASES in
+// trade-validation.js (duplicated, not imported, to avoid a circular import —
+// both of those modules will import from this one).
+const WSOL_MINT = 'So11111111111111111111111111111111111111112';
+export const SOL_SENTINEL = '11111111111111111111111111111111';
+
+function isSolanaNativeMint(mint) {
+  return mint === WSOL_MINT || mint === SOL_SENTINEL;
+}
+
+// getMultipleAccounts caps at 100 keys per call; batch defensively even though
+// a real swap's writable-account set is well under this.
+const MAX_ACCOUNTS_PER_CALL = 100;
+
+/**
+ * A simulation error the caller can distinguish from a genuine outcome mismatch.
+ * `code` is one of:
+ *   NO_SIM_RPC             - no simulation endpoint configured for the chain
+ *   SIM_RPC_ERROR           - transport/parse failure talking to the endpoint,
+ *                             OR a 200 OK sim that omitted the `accounts`
+ *                             result we asked for (an RPC capability gap, not
+ *                             a corrupt result — see the throw site below)
+ *   SIM_REVERTED            - the transaction itself reverted in simulation
+ *   SIM_RESULT_UNPARSEABLE  - the sim ran AND returned the accounts we asked
+ *                             for, but a tracked balance or lookup table
+ *                             couldn't be resolved/parsed
+ * NO_SIM_RPC and SIM_RPC_ERROR are degrade conditions (warn, proceed per
+ * policy); the caller decides. SIM_REVERTED and SIM_RESULT_UNPARSEABLE are
+ * outcome/parse problems and must not be silently ignored — fail closed.
+ */
+export class SolanaSimulationError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'SolanaSimulationError';
+    this.code = code;
+  }
+}
+
+/** Whether a sim-capable endpoint is configured for this chain. */
+export function hasSolanaSimulationRpc(chain) {
+  return chain === 'solana' && Boolean(SIMULATION_RPCS.solana);
+}
+
+async function rpcCall(rpcUrl, method, params, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw new SolanaSimulationError(
+        'SIM_RPC_ERROR',
+        `Simulation RPC returned non-JSON (HTTP ${res.status}) for ${method}: ${text.slice(0, 120)}`,
+      );
+    }
+    const ok = res.ok ?? (res.status >= 200 && res.status < 300);
+    if (!ok) {
+      const detail = body?.error?.message || text.slice(0, 120);
+      throw new SolanaSimulationError('SIM_RPC_ERROR', `Simulation RPC HTTP ${res.status} for ${method}: ${detail}`);
+    }
+    if (body.error) {
+      throw new SolanaSimulationError('SIM_RPC_ERROR', `${method} error: ${body.error.message || JSON.stringify(body.error)}`);
+    }
+    return body.result;
+  } catch (e) {
+    if (e instanceof SolanaSimulationError) throw e;
+    if (e.name === 'AbortError') {
+      throw new SolanaSimulationError('SIM_RPC_ERROR', `Simulation RPC timed out after ${timeoutMs}ms (${method})`);
+    }
+    throw new SolanaSimulationError('SIM_RPC_ERROR', `Simulation RPC request failed (${method}): ${e.message}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function getMultipleAccountsChunked(rpcUrl, pubkeys, encoding, timeoutMs) {
+  if (!pubkeys.length) return [];
+  const out = [];
+  for (let i = 0; i < pubkeys.length; i += MAX_ACCOUNTS_PER_CALL) {
+    const chunk = pubkeys.slice(i, i + MAX_ACCOUNTS_PER_CALL);
+    const result = await rpcCall(rpcUrl, 'getMultipleAccounts', [chunk, { encoding, commitment: 'confirmed' }], timeoutMs);
+    if (!Array.isArray(result?.value)) {
+      throw new SolanaSimulationError(
+        'SIM_RPC_ERROR',
+        `getMultipleAccounts returned no account array (value: ${JSON.stringify(result?.value)}); RPC may be rate-limiting or malfunctioning.`,
+      );
+    }
+    // The RPC spec guarantees value.length === chunk.length (null entries for
+    // missing accounts), and every downstream read indexes into this array
+    // positionally against writableKeys. A short array would silently shift
+    // every later account's pre-state by one slot rather than fail loudly —
+    // treat a non-conforming length the same as a malformed response.
+    if (result.value.length !== chunk.length) {
+      throw new SolanaSimulationError(
+        'SIM_RPC_ERROR',
+        `getMultipleAccounts returned ${result.value.length} accounts for a ${chunk.length}-key request; RPC may be rate-limiting or malfunctioning.`,
+      );
+    }
+    out.push(...result.value);
+  }
+  return out;
+}
+
+/**
+ * A static account index is writable unless it's a readonly signer or one of
+ * the trailing readonly non-signers. Mirrors the header layout parsed by
+ * parseTransactionMessage (solana-tx.js).
+ */
+function isStaticWritable(parsed, index) {
+  const { numRequiredSignatures, numReadonlySignedAccounts, numReadonlyUnsignedAccounts } = parsed.header;
+  const numStatic = parsed.staticAccountKeys.length;
+  if (index < numRequiredSignatures) {
+    return index < numRequiredSignatures - numReadonlySignedAccounts;
+  }
+  return index < numStatic - numReadonlyUnsignedAccounts;
+}
+
+/**
+ * Resolve only the WRITABLE accounts a v0 transaction references through
+ * address-lookup-tables. A readonly ALT account can never change balance, so
+ * it's irrelevant to the drain-surface check below — resolving only the
+ * writable indexes saves decoding entries this check will never use.
+ */
+async function resolveAltWritableAccounts(rpcUrl, parsed, timeoutMs) {
+  if (!parsed.addressTableLookups.length) return [];
+  const tableAddresses = parsed.addressTableLookups.map((l) => l.lookupTableAddress);
+  const tableInfos = await getMultipleAccountsChunked(rpcUrl, tableAddresses, 'base64', timeoutMs);
+
+  const resolved = [];
+  parsed.addressTableLookups.forEach((lookup, i) => {
+    const info = tableInfos[i];
+    if (!info) {
+      throw new SolanaSimulationError(
+        'SIM_RESULT_UNPARSEABLE',
+        `Address lookup table ${lookup.lookupTableAddress} not found; cannot resolve its accounts.`,
+      );
+    }
+    // LookupTableMeta: typeIndex u32, deactivationSlot u64, lastExtendedSlot u64,
+    // lastExtendedSlotStartIndex u8, authority Option<Pubkey>, padding — 32-byte
+    // pubkeys begin at byte offset 56.
+    const raw = Array.isArray(info.data) ? info.data[0] : info.data;
+    const buf = Buffer.from(raw, 'base64');
+    for (const idx of lookup.writableIndexes) {
+      const offset = 56 + idx * 32;
+      if (offset + 32 > buf.length) {
+        throw new SolanaSimulationError(
+          'SIM_RESULT_UNPARSEABLE',
+          `Address lookup table ${lookup.lookupTableAddress} has no entry at index ${idx}.`,
+        );
+      }
+      resolved.push(base58Encode(buf.subarray(offset, offset + 32)));
+    }
+  });
+  return resolved;
+}
+
+/** Lamports (native) or SPL token base-unit balance from a jsonParsed account. */
+function extractBalance(kind, info) {
+  if (!info) return 0n;
+  try {
+    if (kind === 'native') return BigInt(info.lamports ?? 0);
+    const amt = info.data?.parsed?.info?.tokenAmount?.amount;
+    return amt != null ? BigInt(amt) : 0n;
+  } catch {
+    throw new SolanaSimulationError('SIM_RESULT_UNPARSEABLE', `Could not parse a simulated ${kind} balance.`);
+  }
+}
+
+/**
+ * Simulate a Solana swap transaction and return the normalised asset changes
+ * it causes to `walletAddress`'s wallet.
+ *
+ * @param {string} chain - chain key (only 'solana' is wired today)
+ * @param {string} txBase64 - the serialized transaction to simulate, unsigned
+ * @param {{ walletAddress: string, timeoutMs?: number }} opts
+ * @returns {Promise<{ deltas: Record<string, bigint>, method: string }>}
+ *   deltas is keyed by mint address, with native SOL (and any WSOL leg of the
+ *   same swap) folded under SOL_SENTINEL.
+ * @throws {SolanaSimulationError} on any degrade condition, an in-sim revert,
+ *   or an unparseable result.
+ */
+export async function simulateSolanaAssetChanges(chain, txBase64, { walletAddress, timeoutMs = 20000 } = {}) {
+  const rpcUrl = SIMULATION_RPCS[chain];
+  if (!rpcUrl) {
+    throw new SolanaSimulationError('NO_SIM_RPC', `No simulation RPC configured for chain '${chain}'.`);
+  }
+  if (!walletAddress) {
+    throw new SolanaSimulationError('SIM_RPC_ERROR', 'simulateSolanaAssetChanges requires a `walletAddress`.');
+  }
+
+  const parsed = parseTransactionMessage(txBase64);
+
+  // Deduplicated: the same pubkey could in principle appear more than once
+  // across the static keys and ALT-resolved writable indexes (or across two
+  // different lookup tables). Without dedup, tracking + summing its delta
+  // twice would double (or further inflate) a real balance change, letting
+  // assertSolanaSwapOutcome's minimum-output check pass on an inflated delta
+  // that doesn't reflect what the wallet actually received.
+  const writableKeys = [];
+  const seenWritableKeys = new Set();
+  const pushWritable = (key) => {
+    if (seenWritableKeys.has(key)) return;
+    seenWritableKeys.add(key);
+    writableKeys.push(key);
+  };
+  for (let i = 0; i < parsed.staticAccountKeys.length; i++) {
+    if (isStaticWritable(parsed, i)) pushWritable(parsed.staticAccountKeys[i]);
+  }
+  for (const key of await resolveAltWritableAccounts(rpcUrl, parsed, timeoutMs)) {
+    pushWritable(key);
+  }
+
+  const preAccountInfos = await getMultipleAccountsChunked(rpcUrl, writableKeys, 'jsonParsed', timeoutMs);
+
+  // Track the wallet's own accounts among the writable set — that's the
+  // complete drain surface assertSolanaSwapOutcome needs (input/output/sibling).
+  // Accounts that don't exist pre-swap are tracked as *candidates*: a first-ever
+  // purchase of the output token has the tx create its ATA, so it has no
+  // pre-state to read ownership from. We snapshot it post-simulation anyway and
+  // classify it from the created account's owner (below); a zero pre-balance
+  // makes its whole post-balance the delta. Skipping these would report a 0n
+  // output delta and false-block every first-time buy.
+  const tracked = []; // { pubkey, preInfo, classified, kind?, mint? }
+  let sawWalletAccount = false;
+  writableKeys.forEach((pubkey, i) => {
+    const info = preAccountInfos[i];
+    if (!info) {
+      tracked.push({ pubkey, preInfo: null, classified: false });
+      return;
+    }
+    if (pubkey === walletAddress) {
+      tracked.push({ pubkey, preInfo: info, classified: true, kind: 'native' });
+      sawWalletAccount = true;
+      return;
+    }
+    const parsedInfo = info.data?.parsed;
+    if (parsedInfo?.type === 'account' && parsedInfo.info?.owner === walletAddress) {
+      tracked.push({ pubkey, preInfo: info, classified: true, kind: 'token', mint: parsedInfo.info.mint });
+      sawWalletAccount = true;
+    }
+  });
+
+  // The wallet's native account is the fee payer, so it always pre-exists and is
+  // writable; not seeing it means we couldn't locate the signer's own accounts
+  // and can't meaningfully verify the outcome. (Unclassified candidates alone
+  // don't count — they may all belong to other parties.)
+  if (!sawWalletAccount) {
+    throw new SolanaSimulationError(
+      'SIM_RESULT_UNPARSEABLE',
+      'Could not resolve the signer wallet as a writable account in this transaction; cannot verify the outcome.',
+    );
+  }
+
+  const simResult = await rpcCall(
+    rpcUrl,
+    'simulateTransaction',
+    [
+      txBase64,
+      {
+        sigVerify: false,
+        replaceRecentBlockhash: true,
+        commitment: 'confirmed',
+        encoding: 'base64',
+        accounts: { addresses: tracked.map((t) => t.pubkey), encoding: 'jsonParsed' },
+      },
+    ],
+    timeoutMs,
+  );
+
+  if (simResult?.value?.err != null) {
+    throw new SolanaSimulationError('SIM_REVERTED', `Swap reverts in simulation: ${JSON.stringify(simResult.value.err)}`);
+  }
+  const postAccountInfos = simResult?.value?.accounts;
+  if (!Array.isArray(postAccountInfos) || postAccountInfos.length !== tracked.length) {
+    // A 200 OK with `err: null` but no (or short) `accounts` array means the
+    // node accepted the request without honoring the `accounts` param — the
+    // same "public node doesn't fully support this" gap rpc-urls.js documents
+    // as a degrade condition, not a corrupt result. SIM_RPC_ERROR here (rather
+    // than SIM_RESULT_UNPARSEABLE) keeps this in verifySolanaSwapOutcome's
+    // degrade allow-list so a capability gap on the default public RPC warns
+    // and proceeds instead of blocking every trade.
+    throw new SolanaSimulationError('SIM_RPC_ERROR', 'Simulation did not return balance data for the tracked accounts (RPC may not support the `accounts` parameter).');
+  }
+
+  const deltas = {};
+  tracked.forEach((t, i) => {
+    const postInfo = postAccountInfos[i];
+    let { kind, mint } = t;
+    if (!t.classified) {
+      // Newly-created account: classify from its post-simulation state and
+      // count it only if the tx created it as one of the wallet's own accounts
+      // (e.g. the output-token ATA). Anything else is another party's account.
+      if (!postInfo) return;
+      const parsedInfo = postInfo.data?.parsed;
+      if (parsedInfo?.type === 'account' && parsedInfo.info?.owner === walletAddress) {
+        kind = 'token';
+        mint = parsedInfo.info.mint;
+      } else {
+        return;
+      }
+    }
+    const pre = extractBalance(kind, t.preInfo); // null preInfo (new account) → 0n
+    const post = extractBalance(kind, postInfo);
+    const delta = post - pre;
+    if (delta === 0n) return;
+    const key = kind === 'native' ? SOL_SENTINEL : (isSolanaNativeMint(mint) ? SOL_SENTINEL : mint);
+    deltas[key] = (deltas[key] || 0n) + delta;
+  });
+  for (const k of Object.keys(deltas)) {
+    if (deltas[k] === 0n) delete deltas[k];
+  }
+
+  return { deltas, method: 'simulateTransaction' };
+}

package/src/solana-tx.js

@@ -0,0 +1,153 @@
+/**
+ * Nansen CLI - Solana Transaction Deserialization
+ * Parses a serialized (legacy or v0) Solana VersionedTransaction so its
+ * instructions can be statically inspected before signing.
+ */
+
+import { base58Encode } from './wallet.js';
+
+export function readCompactU16(buf, offset) {
+  let value = 0;
+  let shift = 0;
+  let size = 0;
+  for (let i = 0; i < 3; i++) {
+    if (offset + i >= buf.length) {
+      throw new Error('Malformed Solana transaction: compact-u16 length runs past end of buffer');
+    }
+    const byte = buf[offset + i];
+    value |= (byte & 0x7f) << shift;
+    size++;
+    if ((byte & 0x80) === 0) break;
+    shift += 7;
+  }
+  return { value, size };
+}
+
+/**
+ * Parse a base64-encoded Solana transaction (wire format:
+ * [compact-u16 sigCount][sigCount * 64-byte signatures][message]) into its
+ * header, static account keys, instructions, and (v0 only) address-table
+ * lookups. `data` on instructions is returned undecoded (raw Buffer).
+ */
+export function parseTransactionMessage(base64) {
+  const bytes = Buffer.from(base64, 'base64');
+  // Fail closed on any read past the end of the buffer: a truncated or crafted
+  // transaction must throw here rather than silently misparse into a wrong
+  // (possibly drain-hiding) instruction list before signing.
+  const requireBytes = (off, need) => {
+    if (off + need > bytes.length) {
+      throw new Error('Malformed Solana transaction: read past end of buffer');
+    }
+  };
+  const { value: numSignatures, size: sigCountSize } = readCompactU16(bytes, 0);
+  let offset = sigCountSize + numSignatures * 64;
+
+  requireBytes(offset, 1);
+  const first = bytes[offset];
+  const isVersioned = (first & 0x80) !== 0;
+  if (isVersioned) {
+    // The low 7 bits are the version number. Only v0 exists today, and the rest
+    // of this parser assumes the v0 message layout (static keys, instructions,
+    // then address-table lookups). A future/unknown version could lay out its
+    // bytes differently, so as a pre-signing safety gate we fail closed rather
+    // than skip the prefix and misparse an unsupported format into a
+    // wrong-and-possibly-drain-hiding instruction list.
+    const version = first & 0x7f;
+    if (version !== 0) {
+      throw new Error(`Unsupported Solana transaction version ${version}. Refusing to sign.`);
+    }
+    offset += 1; // skip the version-prefix byte; header follows
+  }
+
+  requireBytes(offset, 3);
+  const numRequiredSignatures = bytes[offset];
+  const numReadonlySignedAccounts = bytes[offset + 1];
+  const numReadonlyUnsignedAccounts = bytes[offset + 2];
+  offset += 3;
+
+  const { value: numAccountKeys, size: keysCountSize } = readCompactU16(bytes, offset);
+  offset += keysCountSize;
+  const staticAccountKeys = [];
+  for (let i = 0; i < numAccountKeys; i++) {
+    requireBytes(offset, 32);
+    staticAccountKeys.push(base58Encode(bytes.subarray(offset, offset + 32)));
+    offset += 32;
+  }
+
+  requireBytes(offset, 32);
+  const recentBlockhash = base58Encode(bytes.subarray(offset, offset + 32));
+  offset += 32;
+
+  const { value: numInstructions, size: ixCountSize } = readCompactU16(bytes, offset);
+  offset += ixCountSize;
+  const instructions = [];
+  for (let i = 0; i < numInstructions; i++) {
+    requireBytes(offset, 1);
+    const programIdIndex = bytes[offset];
+    offset += 1;
+    const { value: numAccounts, size: accCountSize } = readCompactU16(bytes, offset);
+    offset += accCountSize;
+    requireBytes(offset, numAccounts);
+    const accountIndexes = [];
+    for (let j = 0; j < numAccounts; j++) {
+      accountIndexes.push(bytes[offset]);
+      offset += 1;
+    }
+    const { value: dataLen, size: dataLenSize } = readCompactU16(bytes, offset);
+    offset += dataLenSize;
+    requireBytes(offset, dataLen);
+    const data = bytes.subarray(offset, offset + dataLen);
+    offset += dataLen;
+    instructions.push({ programIdIndex, accountIndexes, data });
+  }
+
+  const addressTableLookups = [];
+  if (isVersioned) {
+    const { value: numLookups, size: lookupCountSize } = readCompactU16(bytes, offset);
+    offset += lookupCountSize;
+    for (let i = 0; i < numLookups; i++) {
+      requireBytes(offset, 32);
+      const lookupTableAddress = base58Encode(bytes.subarray(offset, offset + 32));
+      offset += 32;
+      const { value: numWritable, size: writableCountSize } = readCompactU16(bytes, offset);
+      offset += writableCountSize;
+      requireBytes(offset, numWritable);
+      const writableIndexes = [];
+      for (let j = 0; j < numWritable; j++) {
+        writableIndexes.push(bytes[offset]);
+        offset += 1;
+      }
+      const { value: numReadonly, size: readonlyCountSize } = readCompactU16(bytes, offset);
+      offset += readonlyCountSize;
+      requireBytes(offset, numReadonly);
+      const readonlyIndexes = [];
+      for (let j = 0; j < numReadonly; j++) {
+        readonlyIndexes.push(bytes[offset]);
+        offset += 1;
+      }
+      addressTableLookups.push({ lookupTableAddress, writableIndexes, readonlyIndexes });
+    }
+  }
+
+  return {
+    isVersioned,
+    header: { numRequiredSignatures, numReadonlySignedAccounts, numReadonlyUnsignedAccounts },
+    staticAccountKeys,
+    recentBlockhash,
+    instructions,
+    addressTableLookups,
+  };
+}
+
+/**
+ * Resolve an account index to its base58 pubkey, or null if it's only
+ * resolvable via an address-lookup-table entry (requires an RPC fetch this
+ * module intentionally doesn't make). Lookup-table entries can never be
+ * signers — Solana's message format requires every signer to be a static
+ * account key — so a null result here only ever means "not a signer, and
+ * this specific pubkey can't be verified without a network call."
+ */
+export function resolveStaticAccount(parsed, index) {
+  if (index < parsed.staticAccountKeys.length) return parsed.staticAccountKeys[index];
+  return null;
+}