nansen-cli 1.40.1 → 1.41.1

package/src/trade-validation.js

@@ -6,9 +6,33 @@
 
 import { validateAddress } from './api.js';
 import { CHAIN_RPCS } from './rpc-urls.js';
+import { parseTransactionMessage, resolveStaticAccount } from './solana-tx.js';
+import { SOL_SENTINEL } from './solana-simulation.js';
 
 const SUPPORTED_CHAINS = ['solana', 'base'];
 
+// SPL Token / Token-2022 instruction discriminators (first data byte) that can
+// move control of a user's token account without moving its balance — the
+// class of drain vector a balance-delta simulation can't see (see
+// assertSolanaInstructionsSafe).
+const SPL_TOKEN_PROGRAMS = new Set([
+  'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
+  'TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb',
+]);
+const SPL_APPROVE = 4;
+const SPL_SET_AUTHORITY = 6;
+const SPL_CLOSE_ACCOUNT = 9;
+const SPL_APPROVE_CHECKED = 13;
+
+const COMPUTE_BUDGET_PROGRAM = 'ComputeBudget111111111111111111111111111111';
+const COMPUTE_BUDGET_SET_UNIT_LIMIT = 2;
+const COMPUTE_BUDGET_SET_UNIT_PRICE = 3;
+const SOLANA_MAX_COMPUTE_UNITS = 1_400_000; // Solana's per-transaction compute-unit ceiling — the
+                                             // worst-case bound used when a price is set with no
+                                             // explicit limit instruction.
+const MAX_PRIORITY_FEE_LAMPORTS = 10_000_000n; // 0.01 SOL sanity ceiling on the priority fee a
+                                                // single trade can be made to pay.
+
 /**
  * Validate quote inputs before any network call.
  * Throws on validation failure with an actionable error message.
@@ -578,7 +602,8 @@ export function needsAllowanceRevoke(existingAllowance, approveAmt) {
 
 /**
  * Compare two token addresses for equality (case-insensitive on EVM, exact on
- * Solana). Missing values never match.
+ * Solana except for the native-SOL sentinel aliasing above). Missing values
+ * never match.
  */
 function tokensEqual(a, b, chain) {
   if (!a || !b) return false;
@@ -742,13 +767,15 @@ export function assertQuoteMatchesRequest(request, quote, { chain, walletAddress
  * exactOut gap where the API chooses the input and nothing capped it.
  *
  * The amount compared against the cap is the maximum that can actually leave the
- * wallet — for exactOut that is the slippage-buffered approval, NOT the raw quote
- * input. The approval encoder (encodeApproveCalldata) scopes the ERC-20 approval
- * to that same buffered amount and caps it at maxInputAmount, so validating the
- * raw input here would let a quote pass this check and then be refused at signing
- * (a 1,000,000 input at 3% slippage needs a 1,030,000 approval, which a 1,000,000
- * cap rejects). Comparing the same amount approvalAmountForSwap produces keeps
- * this check and the encoder in lockstep.
+ * wallet — for exactOut that is the slippage-buffered spend, NOT the raw quote
+ * input. On EVM the approval encoder (encodeApproveCalldata) scopes the ERC-20
+ * approval to that same buffered amount and caps it at maxInputAmount, so
+ * validating the raw input here would let a quote pass this check and then be
+ * refused at signing (a 1,000,000 input at 3% slippage needs a 1,030,000
+ * approval, which a 1,000,000 cap rejects). On Solana there is no approval step,
+ * but the swap can still consume up to that buffered amount, so the same ceiling
+ * applies. Comparing the amount approvalAmountForSwap produces keeps this check
+ * consistent with what the execute path can actually spend.
  *
  * Behaviour:
  *   - exactOut with no persisted `maxInputAmount` → throws (fail closed). The
@@ -759,8 +786,9 @@ export function assertQuoteMatchesRequest(request, quote, { chain, walletAddress
  *     more than the user approved leave the wallet.
  *   - exactIn with no cap → no-op (request.amount already binds the input).
  *
- * Applies to native and ERC-20 swaps alike; the caller runs it before any
- * approval, transaction signing, or WalletConnect call.
+ * Applies to native, ERC-20, and Solana swaps alike (Solana has no approval step,
+ * so the "buffered spend" ceiling is just the spend itself); the caller runs it
+ * before any approval, transaction signing, or WalletConnect call.
  *
  * @param {object} request - Persisted intent (quoteData.request)
  * @param {object} quote - The quote being executed
@@ -816,10 +844,18 @@ export function assertInputWithinMax(request, quote, slippage) {
     );
   }
   if (spend > cap) {
+    // Normalize case: request.chain is persisted verbatim from the user's
+    // --chain input (e.g. `--chain Solana`), so an exact === would mislabel a
+    // Solana swap with the EVM-worded (approval/native-value) message.
+    const isSolana = String(request.chain).toLowerCase() === 'solana';
     throw new Error(
       swapMode === 'exactOut'
-        ? `Quote needs an approval of ${spend} base units (input ${input} + slippage buffer) to guarantee the exact output, which exceeds your maximum input (${cap}). Raise --max-input or lower the requested output. Refusing to sign.`
-        : `Quote input amount (${input}) exceeds your maximum input (${cap}). A larger input would enlarge the approval and native value beyond what you approved. Refusing to sign.`,
+        ? isSolana
+          ? `Quote needs ${spend} base units (input ${input} + slippage buffer) to guarantee the exact output, which exceeds your maximum input (${cap}). Raise --max-input or lower the requested output. Refusing to sign.`
+          : `Quote needs an approval of ${spend} base units (input ${input} + slippage buffer) to guarantee the exact output, which exceeds your maximum input (${cap}). Raise --max-input or lower the requested output. Refusing to sign.`
+        : isSolana
+          ? `Quote input amount (${input}) exceeds your maximum input (${cap}). Refusing to sign.`
+          : `Quote input amount (${input}) exceeds your maximum input (${cap}). A larger input would enlarge the approval and native value beyond what you approved. Refusing to sign.`,
     );
   }
 }
@@ -876,6 +912,18 @@ export function assertSwapCalldataNotBareTransfer(data) {
 
 // ============= Swap-outcome verification (balance-delta simulation) =============
 
+/**
+ * A cross-chain bridge's output settles on the destination chain, invisible to
+ * a source-chain simulation, so the output-arrival assertion is meaningless
+ * for one and both assert...SwapOutcome functions skip it via this check.
+ * Derived from the immutable persisted request intent (not the loose
+ * quote/quoteData) so it can't drift between calls or across chains.
+ */
+function isBridgeRequest(request) {
+  return request.toChain != null
+    && String(request.toChain).toLowerCase() !== String(request.chain).toLowerCase();
+}
+
 /**
  * Assert that a SIMULATED swap's asset changes match the user's intent, failing
  * closed on any mismatch. This is a defence-in-depth outcome check that
@@ -893,6 +941,8 @@ export function assertSwapCalldataNotBareTransfer(data) {
  *      log) is never counted.
  *   2. the output token arrives by AT LEAST minOut — exactOut: >= the requested
  *      output; exactIn: the quoted output reduced by the slippage in effect.
+ *      SKIPPED for a cross-chain bridge: the output settles on the destination
+ *      chain and can never appear in a source-chain simulation.
  *   3. NO token other than the input leaves the wallet.
  *   4. the wallet grants no Approval to a spender outside `expectedSpenders`.
  *
@@ -908,6 +958,9 @@ export function assertSwapCalldataNotBareTransfer(data) {
  *   router); anything else fails assertion 4. Compared case-insensitively.
  * @param {bigint} [ctx.siblingDustThreshold=0n] - non-input outflow tolerated
  *   before assertion 3 fires (for fee-on-transfer / rounding). Strict 0 default.
+ * @returns {{verified: true, outputAssertionSkipped: boolean}} outputAssertionSkipped
+ *   is true for a cross-chain bridge, meaning assertion 2 did not run — the
+ *   caller should surface this.
  * @throws {Error} with `code = 'SWAP_OUTCOME_MISMATCH'` on any failed assertion.
  */
 export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpenders, siblingDustThreshold = 0n } = {}) {
@@ -947,6 +1000,9 @@ export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpend
     throw fail(`quote input and output tokens are the same (${inputToken}); refusing to verify.`);
   }
 
+  // Bridges skip only assertion 2 (output arrival) below — see isBridgeRequest.
+  const isBridge = isBridgeRequest(request);
+
   // --- Assertion 1: input outflow within the spend ceiling ---
   // This bounds the outflow by maxInputAmount (the slippage-buffered ceiling),
   // NOT the exact expected input: for exactOut the aggregator may legitimately
@@ -969,9 +1025,50 @@ export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpend
     throw fail(`the input token (${inputToken}) left the wallet by ${outflow}, exceeding your maximum input (${cap}).`);
   }
 
-  // --- Assertion 2: output arrives at or above the minimum acceptable ---
+  // Fail closed on an unrecognized swap mode. `?? 'exactIn'` only defaults a
+  // missing mode; a persisted request with a garbage value (an edited/older
+  // quote record) must not silently fall into the exactOut branch below, which
+  // would drop the intent-relative input floor. The CLI validates --swap-mode
+  // against this same enum, so a well-formed quote never reaches here invalid.
   const swapMode = request.swapMode ?? 'exactIn';
-  const outputDelta = deltas[outputToken] || 0n;
+  if (swapMode !== 'exactIn' && swapMode !== 'exactOut') {
+    throw fail(`unrecognized swap mode "${swapMode}"; expected exactIn or exactOut.`);
+  }
+
+  // A bridge drops assertion 2 (its output settles on the destination chain),
+  // and for a normal swap that positive-output check is what implicitly proves
+  // the input was actually consumed. Restore that with an intent-relative LOWER
+  // bound on the source-chain outflow: a bare `outflow > 0` is too weak — a
+  // fee-only or 1-unit no-op would still verify a bridge that never funded its
+  // input. For exactIn the outflow must be ~the requested input (assertion 1
+  // already caps it above); for exactOut the input is variable up to the cap, so
+  // only a positive-outflow floor is meaningful. EVM native input delta is the
+  // transferred value with gas excluded, so the outflow is exact — no fee slack.
+  if (isBridge) {
+    if (swapMode === 'exactIn') {
+      if (request.amount == null) throw fail('bridge exactIn request is missing the requested input amount.');
+      let requested;
+      try {
+        requested = BigInt(request.amount);
+      } catch {
+        throw fail(`requested input amount (${request.amount}) is not an integer.`);
+      }
+      if (requested <= 0n) throw fail(`bridge exactIn request has a non-positive input amount (${requested}).`);
+      if (outflow < requested) {
+        throw fail(`the bridge moved only ${outflow} of the input token (${inputToken}) out of the wallet, below the requested input (${requested}); a bridge must spend its full input on the source chain.`);
+      }
+    } else if (outflow <= 0n) {
+      throw fail(`the bridge moved no input token (${inputToken}) out of the wallet; a bridge must spend its input on the source chain.`);
+    }
+  }
+
+  // --- Assertion 2: output arrives at or above the minimum acceptable ---
+  // The minimum-output computation below — and its quote-integrity checks (the
+  // output amount must be present, an integer, and positive) — runs for EVERY
+  // swap, bridges included: a bridge quote with a missing or zero output is
+  // still malformed. Only the final delta comparison is bridge-skipped, because
+  // the output settles on the destination chain and can never appear in this
+  // source-chain simulation.
   let minOut;
   if (swapMode === 'exactOut') {
     if (request.amount == null) throw fail('exactOut request is missing the requested output amount.');
@@ -1022,8 +1119,11 @@ export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpend
     const bps = BigInt(Math.min(10000, Math.round(slip * 10000)));
     minOut = (quoted * (10000n - bps)) / 10000n;
   }
-  if (outputDelta < minOut) {
-    throw fail(`the output token (${outputToken}) increased by only ${outputDelta}, below the minimum acceptable output (${minOut}).`);
+  if (!isBridge) {
+    const outputDelta = deltas[outputToken] || 0n;
+    if (outputDelta < minOut) {
+      throw fail(`the output token (${outputToken}) increased by only ${outputDelta}, below the minimum acceptable output (${minOut}).`);
+    }
   }
 
   // --- Assertion 3: no token other than the input leaves the wallet ---
@@ -1081,5 +1181,426 @@ export function assertSwapOutcome(request, quote, sim, { slippage, expectedSpend
     }
   }
 
-  return { verified: true };
+  return { verified: true, outputAssertionSkipped: isBridge };
+}
+
+// Native-SOL dust tolerated on a non-input sibling in assertSolanaSwapOutcome —
+// covers the base tx fee plus one transient ATA's rent (e.g. a WSOL account
+// opened and closed within the swap). SPL-token siblings get no such tolerance
+// (dust threshold 0n); only native SOL legitimately moves as a byproduct of fees
+// and rent rather than the swap itself.
+const NATIVE_SIBLING_DUST_LAMPORTS = 3_000_000n; // ~0.003 SOL
+
+// Full native-SOL fee/rent noise budget: the dust above PLUS the priority fee
+// a transaction may legitimately pay, up to the ceiling assertSolanaInstructionsSafe
+// enforces. NATIVE_SIBLING_DUST_LAMPORTS alone only covers the base fee + rent —
+// a real, legal priority fee (anywhere up to MAX_PRIORITY_FEE_LAMPORTS) also
+// leaves the wallet as native SOL regardless of whether SOL is the input,
+// output, or an uninvolved sibling of the swap, so all three assertions below
+// need the same combined slack or a legitimate high-priority-fee trade false-blocks.
+const NATIVE_FEE_RENT_SLACK_LAMPORTS = MAX_PRIORITY_FEE_LAMPORTS + NATIVE_SIBLING_DUST_LAMPORTS;
+
+/**
+ * The Solana sibling of assertSwapOutcome. Solana signs the aggregator's
+ * serialized transaction verbatim and has no approval/calldata split to
+ * validate, so this verifies the balance-delta simulation result (see
+ * solana-simulation.js) against the persisted request intent directly.
+ *
+ * REQUIRES assertSolanaInstructionsSafe to have already run, RPC-free, on the
+ * same transaction (both current signing paths in trading.js call it first):
+ * an unexpected authority grant is rejected there (no assertion 4 sibling
+ * needed here), and assertion 1's native-input slack below is only a safe
+ * bound because that check has already enforced the priority-fee ceiling —
+ * skip it on any future signing path and native-input drains widen from a
+ * fixed slack to an unbounded priority fee.
+ *
+ * Three assertions:
+ *   1. the input token leaves the wallet by no more than maxInputAmount.
+ *      Native-SOL input can't be bound at the exact cap the way an SPL input
+ *      can: its lamport delta also carries the base fee, priority fee, and net
+ *      ATA rent (opened minus reclaimed), which is too noisy for a tight
+ *      bound. It is still bounded, not skipped — the cap is relaxed by a
+ *      fee/rent slack (the priority-fee ceiling assertSolanaInstructionsSafe
+ *      enforces, plus one transient ATA's rent) so a real outflow beyond any
+ *      realistic transaction cost is still caught. Without this, a
+ *      transaction with an extra unaccounted native-SOL outflow (e.g. a plain
+ *      System-Program transfer, which assertSolanaInstructionsSafe does not
+ *      classify) would sail through as long as the declared output arrived —
+ *      neither assertQuoteMatchesRequest (checks the quote's declared
+ *      metadata, not the transaction's real effects) nor assertion 3 (which
+ *      exempts the input asset, assuming assertion 1 already bounded it)
+ *      would catch it.
+ *   2. the output token arrives by at least the minimum acceptable amount.
+ *      Native-SOL output relaxes this floor by NATIVE_FEE_RENT_SLACK_LAMPORTS
+ *      because its lamport delta also nets out the base fee, priority fee, and
+ *      ATA rent (same noise as native input); SPL output keeps the exact floor.
+ *      SKIPPED for a cross-chain bridge: the output settles on the destination
+ *      chain and can never appear in a source-chain simulation.
+ *   3. no OTHER tracked asset leaves the wallet. SPL-token siblings get zero
+ *      tolerance; native SOL, when it's a sibling (not the input), tolerates
+ *      NATIVE_FEE_RENT_SLACK_LAMPORTS of fee/rent dust. All three assertions
+ *      share this one slack value — splitting it (e.g. a smaller tolerance for
+ *      assertion 2/3 than assertion 1) would false-block a legitimate trade
+ *      paying close to the priority-fee ceiling on whichever assertion has the
+ *      smaller number, since the same fee leaves the wallet as native SOL
+ *      regardless of SOL's role in that particular swap.
+ *
+ * @param {object} request - persisted intent (quoteData.request); required
+ * @param {object} quote - the quote being executed
+ * @param {{deltas: Record<string, bigint|string|number>}} sim - the normalised
+ *   result from simulateSolanaAssetChanges()
+ * @param {object} [ctx]
+ * @param {number} [ctx.slippage] - slippage fraction in effect; defaults to 3%
+ * @param {bigint} [ctx.siblingDustThreshold] - overrides NATIVE_FEE_RENT_SLACK_LAMPORTS
+ * @returns {{verified: true, inputAssertionSkipped: boolean, outputAssertionSkipped: boolean}}
+ *   inputAssertionSkipped is true when the input was native SOL, meaning
+ *   assertion 1 ran with the fee/rent slack applied instead of an exact bound
+ *   (see assertion 1's rationale above). outputAssertionSkipped is true for a
+ *   cross-chain bridge, meaning assertion 2 did not run. The caller should
+ *   surface both.
+ * @throws {Error} with `code = 'SWAP_OUTCOME_MISMATCH'` on any failed assertion.
+ */
+export function assertSolanaSwapOutcome(request, quote, sim, { slippage, siblingDustThreshold } = {}) {
+  const fail = (detail) => {
+    const e = new Error(`Swap outcome mismatch (SWAP_OUTCOME_MISMATCH): ${detail} Refusing to sign.`);
+    e.code = 'SWAP_OUTCOME_MISMATCH';
+    return e;
+  };
+
+  if (!request) throw fail('no request intent to verify the outcome against.');
+  if (!sim || typeof sim !== 'object' || sim.deltas == null) {
+    throw fail('simulation returned no asset changes to verify.');
+  }
+
+  const deltas = {};
+  for (const [k, v] of Object.entries(sim.deltas)) {
+    let amt;
+    try {
+      amt = typeof v === 'bigint' ? v : BigInt(v);
+    } catch {
+      throw fail(`simulated delta for ${k} (${v}) is not an integer.`);
+    }
+    deltas[k] = amt;
+  }
+
+  const foldNative = (mint) => (mint && SOLANA_NATIVE_SOL_ALIASES.has(mint) ? SOL_SENTINEL : mint);
+  const inputAsset = quote?.inputMint ? foldNative(quote.inputMint) : null;
+  const outputAsset = quote?.outputMint ? foldNative(quote.outputMint) : null;
+  if (!inputAsset || !outputAsset) {
+    throw fail('quote is missing the input or output token address.');
+  }
+  if (inputAsset === outputAsset) {
+    throw fail(`quote input and output tokens are the same (${inputAsset}); refusing to verify.`);
+  }
+
+  const inputIsNative = inputAsset === SOL_SENTINEL;
+
+  // Bridges skip only assertion 2 (output arrival) below — see isBridgeRequest.
+  const isBridge = isBridgeRequest(request);
+
+  // --- Assertion 1: input outflow within the spend ceiling ---
+  if (request.maxInputAmount == null) {
+    throw fail('request has no maximum input to bound the outflow against.');
+  }
+  let cap;
+  try {
+    cap = BigInt(request.maxInputAmount);
+  } catch {
+    throw fail(`maximum input (${request.maxInputAmount}) is not an integer.`);
+  }
+  // Native-SOL input's lamport delta also carries the base fee, priority fee,
+  // and net ATA rent (opened minus reclaimed), so it can't be bound at the
+  // exact cap the way an SPL input can — but it must still be BOUNDED, not
+  // skipped: without this, a transaction with an extra unaccounted native-SOL
+  // outflow (e.g. a plain System-Program transfer, which assertSolanaInstructionsSafe
+  // does not classify) sails through as long as the declared output still
+  // arrives. The slack allows the worst realistic fee/rent noise — the same
+  // priority-fee ceiling assertSolanaInstructionsSafe enforces, plus one
+  // transient ATA's rent — without opening the cap back up to an unbounded drain.
+  const effectiveCap = inputIsNative ? cap + NATIVE_FEE_RENT_SLACK_LAMPORTS : cap;
+  const inputDelta = deltas[inputAsset] || 0n;
+  const outflow = inputDelta < 0n ? -inputDelta : 0n;
+  if (outflow > effectiveCap) {
+    throw fail(`the input token (${inputAsset}) left the wallet by ${outflow}, exceeding your maximum input (${cap}${inputIsNative ? ` plus fee/rent slack` : ''}).`);
+  }
+  // Fail closed on an unrecognized swap mode (mirrors assertSwapOutcome). A
+  // persisted request with a garbage value must not fall into the exactOut
+  // branch below and drop the intent-relative input floor.
+  const swapMode = request.swapMode ?? 'exactIn';
+  if (swapMode !== 'exactIn' && swapMode !== 'exactOut') {
+    throw fail(`unrecognized swap mode "${swapMode}"; expected exactIn or exactOut.`);
+  }
+
+  // A bridge drops assertion 2 (its output settles on the destination chain),
+  // and for a normal swap that positive-output check is what implicitly proves
+  // the input was actually consumed. Restore that with an intent-relative LOWER
+  // bound on the source-chain outflow: a bare `outflow > 0` is too weak — a
+  // native-SOL leg always burns a fee, so a fee-only no-op (and any partial SPL
+  // outflow) would otherwise verify a bridge that never funded its input. For
+  // exactIn the outflow must be ~the requested input (assertion 1 caps it
+  // above); for exactOut the input is variable up to the cap, so only a
+  // positive-outflow floor is meaningful. Native-SOL input carries fee/rent
+  // noise (bridged amount + base/priority fee − reclaimed ATA rent), so relax
+  // the floor by the same slack assertion 1 adds to the ceiling; SPL is exact.
+  if (isBridge) {
+    if (swapMode === 'exactIn') {
+      if (request.amount == null) throw fail('bridge exactIn request is missing the requested input amount.');
+      let requested;
+      try {
+        requested = BigInt(request.amount);
+      } catch {
+        throw fail(`requested input amount (${request.amount}) is not an integer.`);
+      }
+      if (requested <= 0n) throw fail(`bridge exactIn request has a non-positive input amount (${requested}).`);
+      const floorSlack = inputIsNative ? NATIVE_FEE_RENT_SLACK_LAMPORTS : 0n;
+      // Clamp the floor to a positive minimum: for a native bridge smaller than
+      // the fee/rent slack a real leg is indistinguishable from a fee-only no-op,
+      // so the tightest we can still require is a non-zero outflow.
+      const minOutflow = requested > floorSlack ? requested - floorSlack : 1n;
+      if (outflow < minOutflow) {
+        throw fail(`the bridge moved only ${outflow} of the input token (${inputAsset}) out of the wallet, below the requested input (${requested}${inputIsNative ? ` minus fee/rent slack` : ''}); a bridge must spend its full input on the source chain.`);
+      }
+    } else if (outflow <= 0n) {
+      throw fail(`the bridge moved no input token (${inputAsset}) out of the wallet; a bridge must spend its input on the source chain.`);
+    }
+  }
+
+  // --- Assertion 2: output arrives at or above the minimum acceptable ---
+  // The minimum-output computation below — and its quote-integrity checks (the
+  // output amount must be present, an integer, and positive) — runs for EVERY
+  // swap, bridges included: a bridge quote with a missing or zero output is
+  // still malformed. Only the final delta comparison is bridge-skipped, because
+  // the output settles on the destination chain and can never appear in this
+  // source-chain simulation.
+  let minOut;
+  if (swapMode === 'exactOut') {
+    if (request.amount == null) throw fail('exactOut request is missing the requested output amount.');
+    try {
+      minOut = BigInt(request.amount);
+    } catch {
+      throw fail(`requested output amount (${request.amount}) is not an integer.`);
+    }
+    if (minOut <= 0n) {
+      throw fail(`exactOut request has a non-positive output amount (${minOut}); cannot compute a minimum acceptable output.`);
+    }
+  } else {
+    const quotedRaw = quote?.outAmount ?? quote?.outputAmount;
+    if (quotedRaw == null) {
+      throw fail('quote is missing the quoted output amount; cannot compute the minimum acceptable output.');
+    }
+    let quoted;
+    try {
+      quoted = BigInt(quotedRaw);
+    } catch {
+      throw fail(`quoted output amount (${quotedRaw}) is not an integer.`);
+    }
+    if (quoted <= 0n) {
+      throw fail(`quote has a non-positive output amount (${quoted}); cannot compute a minimum acceptable output.`);
+    }
+    // Floor of quoted × (1 − slippage), capped at 50% independent of what the
+    // user set (mirrors assertSwapOutcome's rationale: a defence-in-depth
+    // floor, not the user's execution tolerance).
+    const rawSlip = Number.isFinite(slippage) && slippage >= 0 ? slippage : 0.03;
+    const slip = Math.min(rawSlip, 0.5);
+    const bps = BigInt(Math.min(10000, Math.round(slip * 10000)));
+    minOut = (quoted * (10000n - bps)) / 10000n;
+  }
+  if (!isBridge) {
+    const outputIsNative = outputAsset === SOL_SENTINEL;
+    const outputDelta = deltas[outputAsset] || 0n;
+    // Native-SOL output carries the same fee/rent noise as native input: the
+    // lamport delta is (SOL received − base/priority fee − net ATA rent), so a
+    // legitimate trade can land a few million lamports under the quoted amount at
+    // tight slippage or on a congested-network priority fee. Relax the floor by
+    // the same combined fee/rent slack used for native siblings (assertion 3) and
+    // native input (assertion 1) so fee noise never false-blocks; the slippage
+    // floor still bounds any real shortfall. SPL output has no such noise and
+    // keeps the exact floor.
+    const outputFloorSlack = outputIsNative
+      ? (siblingDustThreshold != null ? siblingDustThreshold : NATIVE_FEE_RENT_SLACK_LAMPORTS)
+      : 0n;
+    // minOut can be smaller than the dust tolerance for a dust-quoted swap; clamp
+    // the floor at 0 so the subtraction never goes negative and silently admits
+    // any non-negative outputDelta (including zero). The explicit outputDelta <= 0n
+    // check below then restores the invariant assertSwapOutcome (the EVM sibling)
+    // gets for free because its minOut can never collapse to <= 0: a swap must
+    // deliver SOME positive output, even when the dust-adjusted floor is 0.
+    const adjustedFloor = minOut > outputFloorSlack ? minOut - outputFloorSlack : 0n;
+    if (outputDelta <= 0n || outputDelta < adjustedFloor) {
+      throw fail(`the output token (${outputAsset}) increased by only ${outputDelta}, below the minimum acceptable output (${minOut}).`);
+    }
+  }
+
+  // --- Assertion 3: no other tracked asset leaves the wallet ---
+  const nativeDust = siblingDustThreshold != null ? siblingDustThreshold : NATIVE_FEE_RENT_SLACK_LAMPORTS;
+  for (const [token, delta] of Object.entries(deltas)) {
+    if (token === inputAsset) continue; // bounded by assertion 1 (with fee/rent slack, for native input)
+    if (delta >= 0n) continue;
+    const dust = token === SOL_SENTINEL ? nativeDust : 0n;
+    if (-delta > dust) {
+      throw fail(`a token other than the one you are selling (${token}) left the wallet (delta ${delta}); a swap must not move any token except the input.`);
+    }
+  }
+
+  // inputAssertionSkipped tells the caller assertion 1 ran with the fee/rent
+  // slack applied (native-SOL input, per the JSDoc above), so it can surface
+  // that instead of implying the input spend was tightly delta-verified.
+  // outputAssertionSkipped tells the caller assertion 2 did not run at all
+  // (cross-chain bridge, per the JSDoc above).
+  return { verified: true, inputAssertionSkipped: inputIsNative, outputAssertionSkipped: isBridge };
+}
+
+/**
+ * Statically inspect a Solana transaction's instructions for drain vectors a
+ * balance-delta simulation can't see — granting a token delegate, changing a
+ * token account's authority, or closing an account to a stranger — and for an
+ * excessive compute-budget priority fee. Runs before signing, on the raw
+ * instructions rather than trusting the aggregator's intent.
+ *
+ * Scope: this inspects only the recognized top-level instructions of the
+ * message — the SPL Token and ComputeBudget programs. It does not, and by
+ * design cannot, see instructions a program issues via CPI at runtime, nor
+ * does it classify calls to programs it doesn't recognize. It is one layer
+ * (paired with the intent-binding metadata check), not a complete
+ * authorization audit of the transaction.
+ *
+ * IMPORTANT — this static check does NOT classify SPL Transfer/TransferChecked:
+ * a legitimate swap or vault deposit moves the input token (and WSOL) with
+ * exactly those instructions, so they can't be blanket-rejected, and there is
+ * nothing here to bound their destination or amount. On its own this leaves a
+ * residual gap: a transaction that also transfers an unrelated ("sibling")
+ * token the wallet holds, authorized by the wallet, would pass this check.
+ * That gap is now closed, for swap execution, by outcome simulation —
+ * assertSolanaSwapOutcome, run via verifySolanaSwapOutcome immediately after
+ * this check on all Solana swap-execute signing paths (trading.js), simulates
+ * the transaction and rejects any balance delta on a token other than the
+ * declared input/output. That simulation degrades gracefully (warns and
+ * proceeds) when no simulation RPC endpoint is configured, so this static
+ * check plus the metadata binding remain the ONLY transaction-level guards
+ * whenever a sim RPC is unavailable. Limit-order vault deposit/cancel
+ * (limit-order.js) call only this static check, not verifySolanaSwapOutcome —
+ * they have no swap quote (no declared input/output pair) to bind an outcome
+ * check against, so the sibling-transfer gap described above is still open
+ * there; tracked as a follow-up, not covered here.
+ *
+ * Within that scope, the SPL Token program requires the *authority* of
+ * Approve/ApproveChecked/SetAuthority/CloseAccount to sign the transaction,
+ * so checking "does our wallet authorize this instruction" catches the drain
+ * without an RPC-based account-ownership lookup. For a single-owner authority
+ * the wallet sits in the authority position itself; for a multisig authority
+ * the authority account is the multisig and our wallet appears among the
+ * signer accounts that follow it — so we treat the wallet signing *anywhere
+ * from the authority position onward* as authorizing the instruction.
+ * Address-lookup-table-resolved accounts can never be signers, so those
+ * positions are always statically resolvable; only CloseAccount's destination
+ * can legitimately be ALT-resolved, and an unresolvable destination is treated
+ * the same as a stranger (fail closed). The instruction's own program ID must
+ * also be statically resolvable — an ALT-resolved program ID can't be checked
+ * against SPL_TOKEN_PROGRAMS/COMPUTE_BUDGET_PROGRAM, so it's rejected outright
+ * rather than silently skipped.
+ *
+ * Throws on any of those patterns. Returns the parsed transaction otherwise.
+ */
+export function assertSolanaInstructionsSafe(txBase64, { walletAddress } = {}) {
+  // Fail closed on a missing wallet address: every authority check below
+  // compares resolved accounts against `walletAddress`, so a null/undefined
+  // address would make each comparison silently false and disable the drain
+  // protection rather than over-reject. Refuse to run the check without knowing
+  // whose signature we're guarding.
+  if (!walletAddress) {
+    throw new Error('Cannot verify Solana instruction safety without the signing wallet address. Refusing to sign.');
+  }
+  const parsed = parseTransactionMessage(txBase64);
+  const accountAt = (ix, position) => resolveStaticAccount(parsed, ix.accountIndexes[position]);
+
+  // Does our wallet authorize this SPL instruction? For a single-owner
+  // authority the wallet is at `authorityPos`; for a multisig authority the
+  // authority account is the multisig and our wallet is one of the signer
+  // accounts that follow it. Scanning from `authorityPos` to the end covers
+  // both. Returns true on an unresolvable authority (null): the authority must
+  // be a signer, so it can never legitimately be ALT-resolved — a null means an
+  // out-of-bounds or ALT index there, i.e. a crafted/malformed transaction, and
+  // we fail closed rather than let a silent misparse pass.
+  const walletAuthorizes = (ix, authorityPos) => {
+    if (accountAt(ix, authorityPos) === null) return true;
+    for (let i = authorityPos; i < ix.accountIndexes.length; i++) {
+      if (accountAt(ix, i) === walletAddress) return true;
+    }
+    return false;
+  };
+
+  let computeUnitLimit = null;
+  let computeUnitPriceMicroLamports = null;
+
+  for (const ix of parsed.instructions) {
+    const programId = resolveStaticAccount(parsed, ix.programIdIndex);
+    // A program ID that's only ALT-resolvable can't be checked against
+    // SPL_TOKEN_PROGRAMS/COMPUTE_BUDGET_PROGRAM without an RPC call this
+    // static check intentionally doesn't make — and skipping it here would
+    // let an Approve/SetAuthority/CloseAccount instruction bypass the drain
+    // protection above just by routing the program ID through an ALT entry.
+    // Real swap/vault transactions reference these well-known programs as
+    // static keys, so fail closed rather than silently skip classification.
+    if (!programId) {
+      throw new Error(
+        'Solana transaction invokes a program only resolvable via an address-lookup-table entry, which cannot be safety-classified. Refusing to sign.',
+      );
+    }
+
+    if (SPL_TOKEN_PROGRAMS.has(programId)) {
+      // No discriminator byte — not a valid SPL Token instruction (the runtime
+      // would reject it too). Skip explicitly so the fail-closed intent doesn't
+      // rest on `undefined` never equalling a discriminant constant.
+      if (ix.data.length === 0) continue;
+      const discriminator = ix.data[0];
+      if (discriminator === SPL_APPROVE || discriminator === SPL_APPROVE_CHECKED) {
+        if (walletAuthorizes(ix, discriminator === SPL_APPROVE_CHECKED ? 3 : 2)) {
+          throw new Error(
+            'Solana transaction grants a token delegate (Approve) authorized by your wallet. Refusing to sign.',
+          );
+        }
+      } else if (discriminator === SPL_SET_AUTHORITY) {
+        if (walletAuthorizes(ix, 1)) {
+          throw new Error(
+            "Solana transaction changes a token account's authority (SetAuthority) using your wallet's signature. Refusing to sign.",
+          );
+        }
+      } else if (discriminator === SPL_CLOSE_ACCOUNT) {
+        const authority = accountAt(ix, 2);
+        const destination = accountAt(ix, 1);
+        // Fail closed on an unresolvable authority regardless of destination;
+        // otherwise reject only when our wallet authorizes the close and the
+        // rent goes anywhere but back to us.
+        if (authority === null || (walletAuthorizes(ix, 2) && destination !== walletAddress)) {
+          throw new Error(
+            `Solana transaction closes a token account and sends the reclaimed rent to ` +
+            `${destination || 'an address only resolvable via an address lookup table'} instead of your wallet. Refusing to sign.`,
+          );
+        }
+      }
+    } else if (programId === COMPUTE_BUDGET_PROGRAM) {
+      if (ix.data.length === 0) continue; // no discriminator — not a valid ComputeBudget instruction
+      const discriminator = ix.data[0];
+      if (discriminator === COMPUTE_BUDGET_SET_UNIT_LIMIT && ix.data.length >= 5) {
+        computeUnitLimit = ix.data.readUInt32LE(1);
+      } else if (discriminator === COMPUTE_BUDGET_SET_UNIT_PRICE) {
+        if (ix.data.length < 9) {
+          throw new Error('Solana transaction has a malformed compute-budget price instruction. Refusing to sign.');
+        }
+        computeUnitPriceMicroLamports = ix.data.readBigUInt64LE(1);
+      }
+    }
+  }
+
+  if (computeUnitPriceMicroLamports != null) {
+    const units = BigInt(computeUnitLimit ?? SOLANA_MAX_COMPUTE_UNITS);
+    const feeLamports = (computeUnitPriceMicroLamports * units) / 1_000_000n;
+    if (feeLamports > MAX_PRIORITY_FEE_LAMPORTS) {
+      throw new Error(
+        `Solana transaction sets an excessive priority fee (~${feeLamports} lamports, cap ${MAX_PRIORITY_FEE_LAMPORTS}). Refusing to sign.`,
+      );
+    }
+  }
+
+  return parsed;
 }