nansen-cli 1.40.1 → 1.41.1

package/src/trading.js

@@ -9,19 +9,25 @@ import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import { base58Encode, exportWallet, getWalletConfig, showWallet, listWallets } from './wallet.js';
-import { base58Decode } from './transfer.js';
+import { base58Decode, encodeCompactU16 } from './transfer.js';
+import { buildMessageV0, fetchRecentBlockhash } from './x402-svm.js';
 import { keccak256, signSecp256k1, rlpEncode } from './crypto.js';
 import { getWalletConnectAddress, sendTransactionViaWalletConnect, sendSolanaTransactionViaWalletConnect, sendApprovalViaWalletConnect } from './walletconnect-trading.js';
 import { retrievePassword } from './keychain.js';
-import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance, encodeApproveCalldata, assertValidApprovalSpender, assertQuoteMatchesRequest, assertSwapCalldataNotBareTransfer, assertSwapOutcome, approvalAmountForSwap, needsAllowanceRevoke, OVERSIZED_ALLOWANCE_MULTIPLIER } from './trade-validation.js';
+import { validateQuoteInput, validateBalance, resolvePercentAmount, validateGasBalance, encodeApproveCalldata, assertValidApprovalSpender, assertQuoteMatchesRequest, assertSwapCalldataNotBareTransfer, assertSwapOutcome, assertSolanaInstructionsSafe, assertSolanaSwapOutcome, approvalAmountForSwap, needsAllowanceRevoke, OVERSIZED_ALLOWANCE_MULTIPLIER } from './trade-validation.js';
+import { readCompactU16 } from './solana-tx.js';
+export { readCompactU16 };
 import { CHAIN_RPCS } from './rpc-urls.js';
 import { simulateAssetChanges, SwapSimulationError, hasSimulationRpc } from './swap-simulation.js';
+import { simulateSolanaAssetChanges, SolanaSimulationError, hasSolanaSimulationRpc } from './solana-simulation.js';
 import { packageVersion, CommandError, telemetryHeaders, loadConfig } from './api.js';
 
 // ============= Constants =============
 
 const TRADING_API_URL = process.env.NANSEN_TRADING_API_URL || 'https://trading-api.nansen.ai';
 const CLIENT_USER_AGENT = `nansen-cli/${packageVersion}`;
+// Solana's max transaction wire size (IPv6 MTU minus headers).
+const SOLANA_MAX_TX_SIZE = 1232;
 
 const CHAIN_MAP = {
   solana:   { index: '501', type: 'solana', chainId: 501,  name: 'Solana',   explorer: 'https://solscan.io/tx/', lifiChainId: '1151111081099710' },
@@ -109,7 +115,8 @@ export function getQuotesDir() {
 export function safeQuotesPath(filename) {
   const base = path.resolve(getQuotesDir());
   const target = path.resolve(base, filename);
-  if (path.relative(base, target).startsWith('..')) return null;
+  const relative = path.relative(base, target);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return null;
   return target;
 }
 
@@ -505,6 +512,107 @@ export function signSolanaTransaction(transactionBase64, privateKeyHex) {
   return signedTx.toString('base64');
 }
 
+// Any valid base58 32-byte value works here — recentBlockhash is fixed-size
+// regardless of its actual value, so this is exact for a size-only preflight
+// and lets the signer/signature-count checks below run before the real
+// blockhash fetch (no wasted RPC round trip on a request we're going to reject).
+const SIZE_CHECK_BLOCKHASH = '11111111111111111111111111111111';
+
+function decodeInstructionData(hex) {
+  if (hex == null || hex === '') return Buffer.alloc(0); // some instructions legitimately carry no data
+  const body = hex.startsWith('0x') ? hex.slice(2) : hex;
+  // Buffer.from(str, 'hex') silently drops a trailing odd nibble and stops at
+  // the first non-hex character, so it would decode malformed data into a
+  // plausible-but-wrong instruction that then gets signed. Reject instead.
+  if (body.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(body)) {
+    throw new Error(`Cannot compile Solana transaction: instruction data is not valid hex ("${hex}")`);
+  }
+  return Buffer.from(body, 'hex');
+}
+
+/**
+ * Compile a raw, uncompiled Solana transaction — {instructions, addressLookupTableAddresses}
+ * — into a signable base64 VersionedTransaction. Some aggregators (Relay's Solana-source
+ * bridge quotes) return this shape instead of a ready-to-sign serialized transaction.
+ *
+ * Every account is kept static; the address-lookup-table hint is a size optimization,
+ * not a correctness requirement, so skipping it is valid as long as the compiled
+ * transaction still fits Solana's packet limit. Full lookup-table compilation is
+ * unimplemented — throws instead of silently building an oversized/invalid transaction.
+ *
+ * getExpectedSigner is an async thunk resolving to the address of the wallet that is
+ * about to sign. The transaction only ever gets a single signature written into slot 0
+ * (see signSolanaTransaction / the WalletConnect injection path), so the instructions'
+ * own declared signer must both be unambiguous (exactly one signer) and match that
+ * wallet — otherwise the transaction would silently sign the wrong account or leave a
+ * required signature slot empty, failing on-chain with an opaque error.
+ */
+export async function compileRawSolanaTransaction(transaction, rpcUrl, getExpectedSigner) {
+  const instructions = transaction.instructions.map(ix => {
+    if (!Array.isArray(ix.keys)) {
+      throw new Error('Cannot compile Solana transaction: instruction is missing its "keys" accounts list');
+    }
+    return { programId: ix.programId, accounts: ix.keys, data: decodeInstructionData(ix.data) };
+  });
+
+  const feePayer = instructions.flatMap(ix => ix.accounts).find(a => a.isSigner)?.pubkey;
+  if (!feePayer) {
+    throw new Error('Cannot compile Solana transaction: no signer account found in instructions');
+  }
+
+  const expectedSigner = await getExpectedSigner();
+  if (!expectedSigner) {
+    throw new Error('Cannot compile Solana transaction: wallet address unavailable to verify the signer');
+  }
+  if (feePayer !== expectedSigner) {
+    throw new Error(
+      `Solana transaction signer (${feePayer}) doesn't match the wallet executing this trade ` +
+      `(${expectedSigner}). Refusing to sign — get a new quote.`
+    );
+  }
+
+  const preflight = buildMessageV0({ feePayer, instructions, recentBlockhash: SIZE_CHECK_BLOCKHASH });
+  if (preflight.numRequiredSignatures !== 1) {
+    throw new Error(
+      `Cannot compile Solana transaction: requires ${preflight.numRequiredSignatures} signatures, ` +
+      `but only the wallet's own signature can be provided.`
+    );
+  }
+  const unsignedSize = 1 + 64 + preflight.messageBytes.length; // compact-u16(1) + 1 signature slot
+  if (unsignedSize > SOLANA_MAX_TX_SIZE) {
+    throw new Error(
+      `Solana transaction too large to compile without address-lookup-table support ` +
+      `(${unsignedSize} bytes > ${SOLANA_MAX_TX_SIZE} limit). This route needs its ` +
+      `address lookup tables resolved, which isn't supported yet.`
+    );
+  }
+
+  const recentBlockhash = await fetchRecentBlockhash(rpcUrl);
+  const { messageBytes } = buildMessageV0({ feePayer, instructions, recentBlockhash });
+  const unsignedTx = Buffer.concat([encodeCompactU16(1), Buffer.alloc(64), messageBytes]);
+  return unsignedTx.toString('base64');
+}
+
+/**
+ * Normalize a Solana quote's `transaction` field to a base64-encoded, ready-to-sign
+ * VersionedTransaction. Three shapes seen across aggregators: Jupiter (already base64),
+ * OKX ({data: base58}), and Relay bridge quotes (raw uncompiled
+ * {instructions, addressLookupTableAddresses} — compiled client-side).
+ *
+ * getExpectedSigner (only consulted for the Relay shape) is an async thunk resolving to
+ * the signing wallet's address — see compileRawSolanaTransaction.
+ */
+export async function normalizeSolanaTransaction(transaction, rpcUrl, getExpectedSigner) {
+  if (typeof transaction === 'string') return transaction; // Jupiter: already base64
+  // Dispatch most-specific shape first. Only Relay carries `instructions` and
+  // only OKX carries `data`; checking `instructions` ahead of the bare
+  // `data` truthiness test keeps a future Relay shape that also had a `data`
+  // field from being mis-routed into the OKX base58 decode.
+  if (Array.isArray(transaction.instructions)) return compileRawSolanaTransaction(transaction, rpcUrl, getExpectedSigner);
+  if (transaction.data) return base58Decode(transaction.data).toString('base64'); // OKX: base58 serialized tx
+  throw new Error('Unrecognized Solana transaction format in quote');
+}
+
 /**
  * Sign an EVM transaction from quote data.
  *
@@ -565,6 +673,30 @@ export function signEvmTransaction(txData, privateKeyHex, chain, nonce) {
   return signLegacyTransaction({ ...common, gasPrice: toHex(txData.gasPrice) }, privateKeyHex);
 }
 
+/**
+ * Canonical EVM transaction hash: keccak256 over the raw signed tx bytes.
+ *
+ * Works for legacy (RLP) and typed (0x02-prefixed EIP-1559) transactions alike,
+ * because the tx hash is defined over exactly the bytes that get broadcast.
+ *
+ * NB: this is NOT the signing hash. signEvmTransaction/signLegacyTransaction hash
+ * the *unsigned* payload to produce the message that gets signed; this hashes the
+ * fully *signed* transaction to produce its on-chain identifier.
+ *
+ * @param {string} signedTxHex - 0x-prefixed (or bare) hex of the signed transaction
+ * @returns {string} 0x-prefixed transaction hash
+ */
+export function evmTxHash(signedTxHex) {
+  if (typeof signedTxHex !== 'string') {
+    throw new Error('evmTxHash: signed transaction must be a hex string');
+  }
+  const hex = signedTxHex.startsWith('0x') ? signedTxHex.slice(2) : signedTxHex;
+  if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) {
+    throw new Error('evmTxHash: signed transaction is not valid hex');
+  }
+  return '0x' + keccak256(Buffer.from(hex, 'hex')).toString('hex');
+}
+
 // How many queued-but-unmined transactions we are willing to sign past.
 //
 // `pending` counts mempool-queued transactions as well as mined ones, and that is
@@ -658,7 +790,108 @@ export async function waitForReceipt(chain, txHash, timeoutMs = 180000, pollMs =
     // Receipt not yet available — wait and retry
     await new Promise(r => setTimeout(r, pollMs));
   }
-  throw new Error(`Transaction receipt not found after ${timeoutMs}ms. Tx: ${txHash}`);
+  // A timeout is NOT a confirmed revert: the tx may still be pending under our
+  // nonce. Tag it so callers can distinguish "reverted" (safe to try the next
+  // quote) from "unconfirmed" (retrying may broadcast a second tx that races
+  // the first for the same nonce). See the swap-path receipt catch.
+  const timeoutErr = new Error(`Transaction receipt not found after ${timeoutMs}ms. Tx: ${txHash}`);
+  timeoutErr.code = 'RECEIPT_TIMEOUT';
+  throw timeoutErr;
+}
+
+/**
+ * Post-broadcast failures that must abort the whole `execute` rather than fall
+ * through to the next quote. Once a transaction is broadcast we hold no evidence
+ * about what landed on-chain, so "try the next quote" would sign and broadcast a
+ * second transaction — the one thing we must not do. Covers every path (swap,
+ * approval, revoke; Privy/WalletConnect/local-key). Each code is thrown with a
+ * rationale at its throw site:
+ *   - TXHASH_MISMATCH  — broadcaster reported a tx we did not sign
+ *   - INVALID_SIGNED_TX — we cannot even derive a hash for what we broadcast
+ *   - RECEIPT_TIMEOUT  — receipt never landed; the tx may still be pending, so
+ *                        retrying would race a second tx against the same nonce
+ *                        (a confirmed on-chain revert is NOT this — it may retry)
+ *
+ * @param {Error} err
+ * @returns {boolean}
+ */
+function isFatalBroadcastError(err) {
+  return err?.code === 'TXHASH_MISMATCH'
+    || err?.code === 'INVALID_SIGNED_TX'
+    || err?.code === 'RECEIPT_TIMEOUT';
+}
+
+/**
+ * Assert the broadcaster reported the transaction we actually signed, and return
+ * our locally-derived hash.
+ *
+ * Fails closed (TXHASH_MISMATCH) when the broadcaster's returned hash differs
+ * from keccak256 of our signed bytes: a mismatch means its receipt would confirm
+ * a transaction we never signed, so nothing has been verified. When the
+ * broadcaster returns no hash we cannot compare, so the returned local hash is
+ * what callers must poll for a receipt — a substituted transaction then times
+ * out rather than falsely confirming.
+ *
+ * @param {string} signedTxHex - the raw signed tx we sent to /execute
+ * @param {string} broadcasterTxHash - the txHash /execute returned (may be empty)
+ * @param {string} [label] - describes the tx for the error, e.g. "allowance-revoke"
+ * @returns {string} our locally-derived transaction hash
+ */
+function assertTxHashMatch(signedTxHex, broadcasterTxHash, label = '') {
+  const what = label ? `the ${label} transaction this CLI signed` : 'the transaction this CLI signed';
+  // A derivation failure here happens AFTER the tx was broadcast, so it must be
+  // fatal (INVALID_SIGNED_TX), never swallowed into "try the next quote": we
+  // hold no hash for the transaction we just sent.
+  let localHash;
+  try {
+    localHash = evmTxHash(signedTxHex);
+  } catch (hashErr) {
+    throw new CommandError(
+      `Aborting: cannot derive a local hash for ${what}: ${hashErr.message}. `
+      + `The transaction may already have been broadcast, so nothing further will run — `
+      + `check your wallet before retrying.`,
+      'INVALID_SIGNED_TX',
+    );
+  }
+  // Normalize both sides through the same bare-hex form before comparing.
+  // evmTxHash always emits 0x-prefixed, but a broadcaster may report bare hex;
+  // comparing 0x-prefixed against bare would be a false mismatch on the prefix
+  // alone — and TXHASH_MISMATCH is fatal, so that would wrongly abort.
+  if (broadcasterTxHash) {
+    const norm = h => h.toLowerCase().replace(/^0x/, '');
+    if (norm(localHash) !== norm(broadcasterTxHash)) {
+      throw new CommandError(
+        `Aborting: the broadcaster reported transaction ${broadcasterTxHash}, but ${what} `
+        + `hashes to ${localHash}. These must match — a mismatch means the receipt would confirm `
+        + `a transaction you did not sign, so nothing has been verified and no further steps will `
+        + `run. Check both hashes on a block explorer to see what was actually broadcast before retrying.`,
+        'TXHASH_MISMATCH',
+      );
+    }
+  }
+  return localHash;
+}
+
+/**
+ * Confirm a broadcast EVM transaction against the hash we derived locally from
+ * the signed bytes — not the hash the broadcaster reported. See
+ * {@link assertTxHashMatch} for the two guarantees (fail closed on mismatch;
+ * poll our own hash so a silent substitution times out rather than confirms).
+ *
+ * @param {string} chain
+ * @param {string} signedTxHex - the raw signed tx we sent to /execute
+ * @param {string} broadcasterTxHash - the txHash /execute returned
+ * @param {string} [label] - describes the tx for a mismatch error, e.g.
+ *   "allowance-revoke" — the least useful moment to lose context is a revoke
+ *   mismatch with the allowance sitting at 0, so callers should pass it
+ * @returns {Promise<{receipt: object, hash: string}>} the receipt and the
+ *   locally-derived hash it was confirmed against (log THIS, not the
+ *   broadcaster's hash — it is the transaction we actually verified landed)
+ */
+export async function confirmEvmBroadcast(chain, signedTxHex, broadcasterTxHash, label = '') {
+  const hash = assertTxHashMatch(signedTxHex, broadcasterTxHash, label);
+  const receipt = await waitForReceipt(chain, hash);
+  return { receipt, hash };
 }
 
 /**
@@ -724,10 +957,12 @@ function toRpcHexValue(value) {
  * guards: the cheap eth_call sim answers "will it revert", this answers "does the
  * outcome match intent" (see assertSwapOutcome in trade-validation.js).
  *
- * EVM-only, and on its own gate independent of --no-simulate/gasless. Skipped
- * for cross-chain bridges (the output lands on the destination chain, so a
- * source-chain simulation can't observe it). When no simulation-capable endpoint
- * is configured it DEGRADES — logs a warning, then proceeds — so a simulation
+ * EVM-only, and on its own gate independent of --no-simulate/gasless. Runs for
+ * cross-chain bridges too — assertSwapOutcome skips only the output-arrival
+ * assertion internally, since the output lands on the destination chain and a
+ * source-chain simulation can't observe it; the input-outflow and no-sibling-
+ * drain assertions still bound the source-chain leg. When no simulation-capable
+ * endpoint is configured it DEGRADES — logs a warning, then proceeds — so a simulation
  * outage never blocks trading. --no-verify-outcome skips it entirely.
  *
  * Returns { proceed, reason }. proceed=false means this quote failed
@@ -745,11 +980,12 @@ function toRpcHexValue(value) {
  */
 export async function verifySwapOutcome({ chain, from, quote, quoteData, apiKey = null, log = () => {} }) {
   if (CHAIN_MAP[chain?.toLowerCase()]?.type !== 'evm') return { proceed: true }; // EVM-only
-  // Cross-chain: the output token settles on the destination chain, so it can
-  // never appear in a source-chain simulation and the output-received assertion
-  // would always fail. The source-chain leg only spends/locks the input here;
-  // skip outcome verification for bridges (mirrors the bridge branch below).
-  if (quoteData?.toChain && quoteData.toChain !== quoteData.chain) return { proceed: true };
+  // Cross-chain (bridge): the output token settles on the destination chain,
+  // so the source-chain simulation still runs but assertSwapOutcome skips
+  // only the output-arrival assertion internally (isBridge, derived from
+  // quoteData.request). The input-outflow cap and no-sibling-drain checks
+  // still bound the source-chain leg.
+
   // No request intent recorded (a pre-intent quote): assertSwapOutcome has
   // nothing to compare the simulated deltas against and would raise a misleading
   // SWAP_OUTCOME_MISMATCH. Degrade cleanly — the static guards still ran, and a
@@ -772,7 +1008,10 @@ export async function verifySwapOutcome({ chain, from, quote, quoteData, apiKey
       { to: tx.to, data: tx.data, value: toRpcHexValue(tx.value) },
       { from, apiKey },
     );
-    assertSwapOutcome(quoteData.request, quote, sim, { slippage: quoteData.slippage, expectedSpenders });
+    const outcome = assertSwapOutcome(quoteData.request, quote, sim, { slippage: quoteData.slippage, expectedSpenders });
+    if (outcome.outputAssertionSkipped) {
+      log('  ℹ Bridge: input-outflow and sibling checks ran; output arrives on the destination chain and is not simulated here.');
+    }
     log(`  ✓ Swap outcome verified (via ${sim.method}).`);
     return { proceed: true };
   } catch (e) {
@@ -787,6 +1026,51 @@ export async function verifySwapOutcome({ chain, from, quote, quoteData, apiKey
   }
 }
 
+/**
+ * The Solana sibling of verifySwapOutcome: simulates the swap transaction via
+ * simulateTransaction and checks the resulting balance deltas against the
+ * persisted request intent, degrading (warn + proceed) on any RPC/sim outage
+ * so an outage never blocks a trade — only a real outcome mismatch or an
+ * in-simulation revert blocks (falls through to the next quote).
+ */
+export async function verifySolanaSwapOutcome({ chain, walletAddress, txBase64, quote, quoteData, log = () => {} }) {
+  if (chain !== 'solana') return { proceed: true };
+  // Cross-chain (bridge): the output settles on the destination chain, so
+  // the source-chain simulation still runs but assertSolanaSwapOutcome skips
+  // only the output-arrival assertion internally (mirrors the EVM path above).
+
+  if (!quoteData?.request) {
+    log('  ⚠ Swap-outcome verification skipped (no request intent — re-quote to enable it).');
+    return { proceed: true };
+  }
+  if (!hasSolanaSimulationRpc(chain)) {
+    log(`  ⚠ Swap-outcome verification unavailable (no simulation endpoint for ${chain}); proceeding without it.`);
+    return { proceed: true };
+  }
+  try {
+    const sim = await simulateSolanaAssetChanges(chain, txBase64, { walletAddress });
+    const outcome = assertSolanaSwapOutcome(quoteData.request, quote, sim, { slippage: quoteData.slippage });
+    if (outcome.inputAssertionSkipped) {
+      // On a native-SOL bridge the output assertion did NOT run (it settles on
+      // the destination chain), so don't claim "output ... checks still ran" —
+      // that would contradict the bridge line logged just below.
+      const alsoRan = outcome.outputAssertionSkipped ? 'sibling checks still ran' : 'output and sibling checks still ran';
+      log(`  ℹ Native-SOL input spend is bounded with fee/rent slack, not exactly delta-verified; ${alsoRan}.`);
+    }
+    if (outcome.outputAssertionSkipped) {
+      log('  ℹ Bridge: input-outflow and sibling checks ran; output arrives on the destination chain and is not simulated here.');
+    }
+    log(`  ✓ Swap outcome verified (via ${sim.method}).`);
+    return { proceed: true };
+  } catch (e) {
+    if (e instanceof SolanaSimulationError && ['NO_SIM_RPC', 'SIM_RPC_ERROR'].includes(e.code)) {
+      log(`  ⚠ Swap-outcome verification could not run (${e.message}); proceeding without it.`);
+      return { proceed: true };
+    }
+    return { proceed: false, reason: e.message };
+  }
+}
+
 /**
  * Estimate gas for an EVM transaction. Returns the gas estimate or null on failure.
  * Used to fix under-gassed quotes from aggregators.
@@ -982,6 +1266,42 @@ export function assertCompleteEvmRequestIntent(request) {
   if (missing.length) {
     throw new Error(`Quote request intent is incomplete (${missing.join(', ')} missing). Re-quote before executing an EVM swap. Refusing to sign.`);
   }
+  // swapMode must be a recognized mode, not merely present. This runs
+  // unconditionally before signing — unlike the swap-outcome verifier, which is
+  // skipped by --no-verify-outcome or when the sim RPC degrades — so a corrupted
+  // or edited quote record with a garbage swapMode fails closed regardless of
+  // the outcome-verification path.
+  if (request.swapMode !== 'exactIn' && request.swapMode !== 'exactOut') {
+    throw new Error(`Quote request intent has an unrecognized swap mode ("${request.swapMode}"); expected exactIn or exactOut. Re-quote before executing an EVM swap. Refusing to sign.`);
+  }
+}
+
+/**
+ * The Solana sibling of assertCompleteEvmRequestIntent. Solana signs the
+ * aggregator's serialized VersionedTransaction verbatim — there is no
+ * approval/calldata split to independently validate — so assertQuoteMatchesRequest
+ * is the only guard between a compromised quote and a signed drain. That check's
+ * per-field `if (request.x)` comparisons silently skip a missing field, so this
+ * closes the gap by failing closed on any incomplete request intent up front.
+ */
+export function assertCompleteSolanaRequestIntent(request) {
+  if (!request) {
+    throw new Error('Quote is missing request intent. Re-quote with this CLI version before executing a Solana swap. Refusing to sign.');
+  }
+
+  const missing = [];
+  for (const field of ['chain', 'walletAddress', 'fromToken', 'toToken', 'swapMode', 'amount', 'maxInputAmount']) {
+    if (request[field] == null || request[field] === '') missing.push(field);
+  }
+  if (missing.length) {
+    throw new Error(`Quote request intent is incomplete (${missing.join(', ')} missing). Re-quote before executing a Solana swap. Refusing to sign.`);
+  }
+  // swapMode must be a recognized mode, not merely present — see the EVM sibling.
+  // Runs unconditionally before signing, so a garbage swapMode fails closed even
+  // when the swap-outcome verifier is skipped or degraded.
+  if (request.swapMode !== 'exactIn' && request.swapMode !== 'exactOut') {
+    throw new Error(`Quote request intent has an unrecognized swap mode ("${request.swapMode}"); expected exactIn or exactOut. Re-quote before executing a Solana swap. Refusing to sign.`);
+  }
 }
 
 /**
@@ -1257,23 +1577,6 @@ function rlpNormalize(val) {
   return toBuffer(val);
 }
 
-// ============= Compact-u16 (Solana) =============
-
-/**
- * Read a compact-u16 from a buffer (Solana transaction format).
- */
-export function readCompactU16(buf, offset) {
-  let value = 0;
-  let size = 0;
-  for (let i = 0; i < 3; i++) {
-    const byte = buf[offset + i];
-    value |= (byte & 0x7f) << (7 * i);
-    size++;
-    if ((byte & 0x80) === 0) break;
-  }
-  return { value, size };
-}
-
 // ============= Chain Utilities =============
 
 /**
@@ -1547,6 +1850,12 @@ export function buildTradingCommands(deps = {}) {
       const autoSlippage = flags['auto-slippage'];
       const maxAutoSlippage = options['max-auto-slippage'];
       const swapMode = options['swap-mode'] || 'exactIn';
+      if (swapMode !== 'exactIn' && swapMode !== 'exactOut') {
+        throw new CommandError(
+          `Invalid --swap-mode: "${swapMode}". Use one of: exactIn, exactOut.`,
+          'INVALID_INPUT',
+        );
+      }
       const amountUnit = options['amount-unit'];
       const aggregatorFilter = options.aggregator;
       if (aggregatorFilter && !['lifi', 'relay', 'jupiter', 'okx'].includes(aggregatorFilter)) {
@@ -1593,9 +1902,9 @@ OPTIONS:
   --swap-mode <mode>        exactIn (default) or exactOut
   --max-input <baseUnits>   exactOut only: hard ceiling on the sell-token spend
                             (base units), measured against the slippage-buffered
-                            approval (input + slippage), not the bare quote input.
-                            Required for EVM (Base) exactOut and enforced before
-                            signing; optional on Solana (no ERC-20 approval to scope).
+                            spend (input + slippage), not the bare quote input.
+                            Required for exactOut on every chain and enforced
+                            before signing.
   --aggregator <name>       Force a specific aggregator (lifi, relay, jupiter, okx).
                             Filters the quote list client-side; errors if none match.
 
@@ -1630,12 +1939,9 @@ CROSS-CHAIN NOTES (when using --to-chain):
         throw new CommandError('Error: --amount-unit percent is not supported with --swap-mode exactOut. Percentage is relative to your sell-token balance.', 'INVALID_INPUT');
       }
 
-      // The exactOut spend-ceiling requirements below only guard the EVM signing
-      // path: the ERC-20 approval scoping, request-intent binding, and
-      // assertInputWithinMax checks are wired into the EVM execute paths only.
-      // Solana signs the API transaction verbatim (no approval to scope), so
-      // requiring --max-input there would break existing Solana exactOut users
-      // without buying any of that path a security guarantee. Gate on EVM source.
+      // isEvmSource gates the ERC-20-approval-specific check just below (auto-slippage
+      // sizing an approval has no Solana equivalent). The --max-input requirement
+      // itself is NOT gated on it — see the check after maxInputOverride is parsed.
       const isEvmSource = CHAIN_MAP[chain?.toLowerCase()]?.type === 'evm';
 
       // exactOut scopes the ERC-20 approval to a slippage-buffered max input. With
@@ -1669,7 +1975,10 @@ CROSS-CHAIN NOTES (when using --to-chain):
           throw new CommandError(`Error: invalid --max-input "${maxInputRaw}": must be an integer in base units of the sell token.`, 'INVALID_INPUT');
         }
       }
-      if (isEvmSource && swapMode === 'exactOut' && maxInputOverride == null) {
+      // Required on every chain: an exactOut cap derived from the API's own quote
+      // response would just check that quote against itself and could never reject
+      // anything (there is no independent signal to catch an inflated input).
+      if (swapMode === 'exactOut' && maxInputOverride == null) {
         throw new CommandError('Error: --swap-mode exactOut requires --max-input (base units of the sell token) so the input is independently capped before signing.', 'INVALID_INPUT');
       }
 
@@ -1922,6 +2231,9 @@ CROSS-CHAIN NOTES (when using --to-chain):
         }
 
         const signerType = isWalletConnect ? 'walletconnect' : walletProvider;
+        // exactOut has no request.amount input bound (amount is the OUTPUT), so
+        // maxInputAmount is the only spend ceiling assertInputWithinMax can enforce.
+        // Required explicitly via --max-input on every chain (checked above).
         const maxInputAmount = swapMode === 'exactOut' ? maxInputOverride : String(resolvedAmount);
         const quoteId = saveQuote(response, chain, signerType, privyWalletIds, isCrossChain ? toChainRaw : null, {
           swapMode,
@@ -1994,7 +2306,7 @@ OPTIONS:
   --quote <id>              Quote ID from 'nansen quote'
   --wallet <name>           Wallet name (default: default wallet)
   --no-simulate             Skip pre-broadcast simulation (the eth_call revert check)
-  --no-verify-outcome       Skip EVM swap-outcome verification (balance-delta check)
+  --no-verify-outcome       Skip swap-outcome verification (balance-delta check)
   --no-revoke-excessive-allowance
                             Skip auto-revoking an oversized/legacy allowance before re-approving
   --gasless                 Relay-only: have Relay's solver pay gas (no WalletConnect)
@@ -2137,13 +2449,50 @@ EXAMPLES:
 
             if (chainType === 'solana' && isPrivy) {
               // Solana via Privy: sign the serialized transaction
-              let txBase64 = currentQuote.transaction;
-              if (typeof txBase64 === 'object' && txBase64.data) {
-                txBase64 = base58Decode(txBase64.data).toString('base64');
-              }
-              log('  Signing Solana transaction via Privy...');
               const solWalletId = quoteData.privyWalletIds?.solana;
               if (!solWalletId) throw new Error('No Solana Privy wallet ID in quote');
+              const walletResult = await privyClient.getWallet(solWalletId);
+              const walletAddress = walletResult.address;
+              // Fail closed if the signer address doesn't resolve: without it the
+              // wallet-binding comparison below would silently skip, leaving the
+              // quote unbound to the wallet that will sign it. This is resolved
+              // independently of the persisted request so assertQuoteMatchesRequest
+              // is a real check, not a comparison of the request against itself.
+              if (!walletAddress) {
+                throw new Error('Could not resolve the Solana Privy wallet address; cannot confirm the quote was built for this wallet. Refusing to sign.');
+              }
+
+              // Solana: transaction is a base64 string (Jupiter), an object with a
+              // base58-encoded `data` field (OKX), or raw uncompiled instructions
+              // (Relay bridge quotes). Normalize to base64.
+              const txBase64 = await normalizeSolanaTransaction(currentQuote.transaction, CHAIN_RPCS.solana, async () => walletAddress);
+
+              // Validate the persisted request/quote metadata (token pair, amounts,
+              // signer) before signing the aggregator's serialized transaction.
+              assertCompleteSolanaRequestIntent(quoteData.request);
+              assertQuoteMatchesRequest(quoteData.request, currentQuote, { chain, walletAddress, slippage: quoteData.slippage });
+
+              // Then statically inspect the serialized transaction's own
+              // instructions ahead of signing — catches a delegate grant, authority
+              // change, close-to-stranger, or excessive fee that the metadata check
+              // alone wouldn't see. The residual sibling-transfer gap is closed by
+              // verifySolanaSwapOutcome below (degrades gracefully when no sim RPC
+              // is available, so this static check remains a guard when sim is off).
+              assertSolanaInstructionsSafe(txBase64, { walletAddress });
+
+              // Verify the swap's simulated on-chain outcome matches intent.
+              // Degrades with a warning if no simulation endpoint is available.
+              if (!noVerifyOutcome) {
+                const outcome = await verifySolanaSwapOutcome({ chain, walletAddress, txBase64, quote: currentQuote, quoteData, log });
+                if (!outcome.proceed) {
+                  log(`  ❌ ${quoteName} failed swap-outcome verification: ${outcome.reason}`);
+                  if (qi + 1 < endIndex) log('  Trying next quote...');
+                  lastQuoteError = `${quoteName} outcome verification failed: ${outcome.reason}`;
+                  continue;
+                }
+              }
+
+              log('  Signing Solana transaction via Privy...');
               const signResult = await privyClient.signSolanaTransaction(solWalletId, txBase64);
               signedTransaction = signResult.data?.signed_transaction || signResult.signed_transaction;
               requestId = currentQuote.metadata?.requestId;
@@ -2254,9 +2603,10 @@ EXAMPLES:
                     }
                     log(`  Waiting for allowance revoke confirmation...`);
                     try {
-                      const receipt = await waitForReceipt(chain, revokeResult.txHash);
-                      log(`  ✓ Allowance revoked in block ${parseInt(receipt.blockNumber, 16)}: ${revokeResult.txHash}`);
+                      const { receipt, hash: revokeHash } = await confirmEvmBroadcast(chain, signedRevoke, revokeResult.txHash, 'allowance-revoke');
+                      log(`  ✓ Allowance revoked in block ${parseInt(receipt.blockNumber, 16)}: ${revokeHash}`);
                     } catch (receiptErr) {
+                      if (isFatalBroadcastError(receiptErr)) throw receiptErr;
                       log(`  ❌ Allowance revoke may not have confirmed for ${quoteName}: ${receiptErr.message}.${allowanceRevokeRecoveryHint(revokeResult.txHash)}`);
                       if (qi + 1 < endIndex) log(`  Trying next quote...`);
                       lastQuoteError = `${quoteName} allowance revoke unconfirmed`;
@@ -2312,9 +2662,10 @@ EXAMPLES:
                   }
                   log(`  Waiting for approval confirmation...`);
                   try {
-                    const receipt = await waitForReceipt(chain, approvalResult.txHash);
-                    log(`  ✓ Approval confirmed in block ${parseInt(receipt.blockNumber, 16)}: ${approvalResult.txHash}`);
+                    const { receipt, hash: approvalHash } = await confirmEvmBroadcast(chain, signedApproval, approvalResult.txHash, 'allowance-approval');
+                    log(`  ✓ Approval confirmed in block ${parseInt(receipt.blockNumber, 16)}: ${approvalHash}`);
                   } catch (receiptErr) {
+                    if (isFatalBroadcastError(receiptErr)) throw receiptErr;
                     log(`  ❌ Approval may not have confirmed${shouldRevoke ? ' after revoking the prior allowance (now 0)' : ''}: ${receiptErr.message}`);
                     if (qi + 1 < endIndex) log(`  Trying next quote...`);
                     lastQuoteError = `${quoteName} approval unconfirmed`;
@@ -2408,17 +2759,60 @@ EXAMPLES:
               signedTransaction = signResult.data?.signed_transaction || signResult.signed_transaction;
 
             } else if (chainType === 'solana') {
-              // NB: validateSwapTarget (the EVM `to`/`data` guard) intentionally does
-              // not apply here — Solana quotes are a pre-built serialized
-              // VersionedTransaction with no `to`/`data`/approval split to validate,
-              // and this path (including the WalletConnect sub-branch below) signs it
-              // as supplied. Deeper Solana inspection (e.g. checking instruction
-              // program IDs) is tracked as a follow-up, not an oversight.
-              // Solana: transaction is either a base64 string (Jupiter) or an object
-              // with a base58-encoded `data` field (OKX). Normalize to base64.
-              let txBase64 = currentQuote.transaction;
-              if (typeof txBase64 === 'object' && txBase64.data) {
-                txBase64 = base58Decode(txBase64.data).toString('base64');
+              // NB: validateSwapTarget (the EVM `to`/`data` guard) does not apply
+              // here — Solana quotes are a pre-built serialized VersionedTransaction
+              // with no `to`/`data`/approval split to validate. assertQuoteMatchesRequest
+              // below binds the metadata (token pair, amounts, signer), and
+              // assertSolanaInstructionsSafe statically inspects the tx's own
+              // instructions before signing.
+              // Solana: transaction is a base64 string (Jupiter), an object with a
+              // base58-encoded `data` field (OKX), or raw uncompiled instructions
+              // (Relay bridge quotes). Normalize to base64.
+
+              // Resolve the signer first — both the Relay-shape compiler (which needs
+              // an expected signer for its fee-payer check) and the intent-binding
+              // check below use this exact same address.
+              let solanaWalletAddress;
+              if (isWalletConnect) {
+                solanaWalletAddress = await getWalletConnectAddress(chainType);
+                if (!solanaWalletAddress) {
+                  throw new CommandError('WalletConnect session lost during execute. Reconnect with `walletconnect connect` and retry.', 'NO_WALLET');
+                }
+              } else {
+                solanaWalletAddress = exported.solana.address;
+                // Fail closed if the signer address doesn't resolve: without it the
+                // wallet-binding comparison below would silently skip, leaving the
+                // quote unbound to the wallet that will sign it.
+                if (!solanaWalletAddress) {
+                  throw new Error("Could not resolve the local wallet's Solana address; cannot confirm the quote was built for this wallet. Refusing to sign.");
+                }
+              }
+
+              const txBase64 = await normalizeSolanaTransaction(currentQuote.transaction, CHAIN_RPCS.solana, async () => solanaWalletAddress);
+
+              // Validate the persisted request/quote metadata (token pair, amounts,
+              // signer) before signing the opaque Solana transaction.
+              assertCompleteSolanaRequestIntent(quoteData.request);
+              assertQuoteMatchesRequest(quoteData.request, currentQuote, { chain, walletAddress: solanaWalletAddress, slippage: quoteData.slippage });
+
+              // Then statically inspect the serialized transaction's own
+              // instructions ahead of signing — catches a delegate grant, authority
+              // change, close-to-stranger, or excessive fee that the metadata check
+              // alone wouldn't see. The residual sibling-transfer gap is closed by
+              // verifySolanaSwapOutcome below (degrades gracefully when no sim RPC
+              // is available, so this static check remains a guard when sim is off).
+              assertSolanaInstructionsSafe(txBase64, { walletAddress: solanaWalletAddress });
+
+              // Verify the swap's simulated on-chain outcome matches intent.
+              // Degrades with a warning if no simulation endpoint is available.
+              if (!noVerifyOutcome) {
+                const outcome = await verifySolanaSwapOutcome({ chain, walletAddress: solanaWalletAddress, txBase64, quote: currentQuote, quoteData, log });
+                if (!outcome.proceed) {
+                  log(`  ❌ ${quoteName} failed swap-outcome verification: ${outcome.reason}`);
+                  if (qi + 1 < endIndex) log('  Trying next quote...');
+                  lastQuoteError = `${quoteName} outcome verification failed: ${outcome.reason}`;
+                  continue;
+                }
               }
 
               if (isWalletConnect) {
@@ -2567,12 +2961,13 @@ EXAMPLES:
                         if (broadcastResult.status !== 'Success') {
                           throw new Error(broadcastResult.error || 'broadcast failed');
                         }
-                        revokeTxHash = broadcastResult.txHash;
+                        revokeTxHash = assertTxHashMatch(revokeResult.signedTransaction, broadcastResult.txHash, 'allowance-revoke');
                       }
                       if (!revokeTxHash) {
                         throw new Error('Allowance revoke returned no transaction hash and no signed transaction; cannot confirm allowance was cleared');
                       }
                     } catch (revokeErr) {
+                      if (isFatalBroadcastError(revokeErr)) throw revokeErr;
                       log(`  ❌ Allowance revoke failed for ${quoteName}: ${revokeErr.message}.${allowanceRevokeRecoveryHint(revokeTxHash)}`);
                       if (qi + 1 < endIndex) log(`  Trying next quote...`);
                       lastQuoteError = `${quoteName} allowance revoke failed`;
@@ -2583,6 +2978,7 @@ EXAMPLES:
                       const receipt = await waitForReceipt(chain, revokeTxHash);
                       log(`  ✓ Allowance revoked in block ${parseInt(receipt.blockNumber, 16)}: ${revokeTxHash}`);
                     } catch (receiptErr) {
+                      if (isFatalBroadcastError(receiptErr)) throw receiptErr;
                       log(`  ❌ Allowance revoke may not have confirmed for ${quoteName}: ${receiptErr.message}.${allowanceRevokeRecoveryHint(revokeTxHash)}`);
                       if (qi + 1 < endIndex) log(`  Trying next quote...`);
                       lastQuoteError = `${quoteName} allowance revoke unconfirmed`;
@@ -2621,7 +3017,7 @@ EXAMPLES:
                       if (broadcastResult.status !== 'Success') {
                         throw new Error(broadcastResult.error || 'broadcast failed');
                       }
-                      approvalTxHash = broadcastResult.txHash;
+                      approvalTxHash = assertTxHashMatch(approvalResult.signedTransaction, broadcastResult.txHash, 'allowance-approval');
                     }
                     if (!approvalTxHash) {
                       // Fail closed: the wallet returned neither a hash nor a
@@ -2632,6 +3028,7 @@ EXAMPLES:
                       throw new Error('returned no transaction hash and no signed transaction; cannot confirm approval landed');
                     }
                   } catch (approvalErr) {
+                    if (isFatalBroadcastError(approvalErr)) throw approvalErr;
                     const revokedMsg = shouldRevoke
                       ? ' after revoking the prior allowance (now 0)'
                       : '';
@@ -2645,6 +3042,7 @@ EXAMPLES:
                     const receipt = await waitForReceipt(chain, approvalTxHash);
                     log(`  ✓ Approval confirmed in block ${parseInt(receipt.blockNumber, 16)}: ${approvalTxHash}`);
                   } catch (receiptErr) {
+                    if (isFatalBroadcastError(receiptErr)) throw receiptErr;
                     const revokedMsg = shouldRevoke
                       ? ' after revoking the prior allowance (now 0)'
                       : '';
@@ -2730,6 +3128,14 @@ EXAMPLES:
                 try {
                   await waitForReceipt(chain, wcResult.txHash);
                 } catch (receiptErr) {
+                  // A timeout here is uncertain post-broadcast state, not a
+                  // confirmed revert — fail closed rather than retry (which would
+                  // broadcast a second swap). Applies even though this path has no
+                  // locally-derived hash to bind to.
+                  if (receiptErr.code === 'RECEIPT_TIMEOUT') {
+                    throw new CommandError(`\n  ⚠ Transaction was broadcast but NOT confirmed within the wait window.\n    Tx Hash:   ${wcResult.txHash}\n    Explorer:  ${chainConfig.explorer}${wcResult.txHash}\n    ${receiptErr.message}\n\n  The transaction may still be pending — do NOT assume it failed. Check the\n  explorer before retrying; retrying may broadcast a second swap.`, 'RECEIPT_TIMEOUT');
+                  }
+                  if (isFatalBroadcastError(receiptErr)) throw receiptErr;
                   log(`\n  ⚠ Transaction was broadcast but REVERTED on-chain!`);
                   log(`    Tx Hash:   ${wcResult.txHash}`);
                   log(`    Explorer:  ${chainConfig.explorer}${wcResult.txHash}`);
@@ -2892,9 +3298,10 @@ EXAMPLES:
 
                     log(`  Waiting for allowance revoke confirmation...`);
                     try {
-                      const receipt = await waitForReceipt(chain, revokeResult.txHash);
-                      log(`  ✓ Allowance revoked in block ${parseInt(receipt.blockNumber, 16)}: ${revokeResult.txHash}`);
+                      const { receipt, hash: revokeHash } = await confirmEvmBroadcast(chain, revokeTxHex, revokeResult.txHash, 'allowance-revoke');
+                      log(`  ✓ Allowance revoked in block ${parseInt(receipt.blockNumber, 16)}: ${revokeHash}`);
                     } catch (receiptErr) {
+                      if (isFatalBroadcastError(receiptErr)) throw receiptErr;
                       log(`  ❌ Allowance revoke may not have confirmed for ${quoteName}: ${receiptErr.message}.${allowanceRevokeRecoveryHint(revokeResult.txHash)}`);
                       if (qi + 1 < endIndex) log(`  Trying next quote...`);
                       lastQuoteError = `${quoteName} allowance revoke unconfirmed`;
@@ -2943,9 +3350,10 @@ EXAMPLES:
 
                   log(`  Waiting for approval confirmation...`);
                   try {
-                    const receipt = await waitForReceipt(chain, approvalResult.txHash);
-                    log(`  ✓ Approval confirmed in block ${parseInt(receipt.blockNumber, 16)}: ${approvalResult.txHash}`);
+                    const { receipt, hash: approvalHash } = await confirmEvmBroadcast(chain, approvalTxHex, approvalResult.txHash, 'allowance-approval');
+                    log(`  ✓ Approval confirmed in block ${parseInt(receipt.blockNumber, 16)}: ${approvalHash}`);
                   } catch (receiptErr) {
+                    if (isFatalBroadcastError(receiptErr)) throw receiptErr;
                     log(`  ❌ Approval may not have confirmed${shouldRevoke ? ' after revoking the prior allowance (now 0)' : ''}: ${receiptErr.message}`);
                     if (qi + 1 < endIndex) log(`  Trying next quote...`);
                     lastQuoteError = `${quoteName} approval unconfirmed`;
@@ -3065,17 +3473,51 @@ EXAMPLES:
             const result = await executeTransaction(execParams);
 
             if (result.status === 'Success') {
-              const txId = result.signature || result.txHash;
-              const explorerUrl = chainConfig.explorer + txId;
+              let txId = result.signature || result.txHash;
+              let explorerUrl = chainConfig.explorer + txId;
 
               // For EVM: verify the tx actually succeeded on-chain
-              if (chainType === 'evm' && result.txHash) {
+              if (chainType === 'evm') {
                 log('  Verifying on-chain status...');
+                // Non-gasless: derive our local hash up front, OUTSIDE the receipt-poll
+                // try below. A hex-validation failure here means no poll ever ran, so it
+                // must surface as itself — not as the "REVERTED on-chain" diagnostic that
+                // catch is reserved for. (Gasless has no local hash to bind to: the Relay
+                // solver wraps and broadcasts its own tx, so result.txHash legitimately is
+                // not the hash of the bytes we signed.)
+                if (!gasless) {
+                  try {
+                    txId = evmTxHash(signedTransaction);
+                  } catch (hashErr) {
+                    throw new CommandError(`Cannot derive local tx hash for ${quoteName}: ${hashErr.message}`, 'INVALID_SIGNED_TX');
+                  }
+                  explorerUrl = chainConfig.explorer + txId;
+                }
                 try {
-                  await waitForReceipt(chain, result.txHash);
+                  if (gasless) {
+                    // If the solver reported no hash there is nothing to poll — skip
+                    // rather than block on eth_getTransactionReceipt(undefined).
+                    if (result.txHash) await waitForReceipt(chain, result.txHash);
+                  } else {
+                    const { hash } = await confirmEvmBroadcast(chain, signedTransaction, result.txHash);
+                    txId = hash;
+                    explorerUrl = chainConfig.explorer + txId;
+                  }
                 } catch (receiptErr) {
+                  // A receipt TIMEOUT is not a confirmed revert: the tx was
+                  // broadcast and may still be pending under our nonce. Retrying
+                  // the next quote would sign and broadcast a SECOND swap racing
+                  // the first for that nonce — the duplicate-broadcast this PR
+                  // exists to prevent. (It's also exactly how guarantee #2's
+                  // silent-substitution case surfaces: a 180s timeout polling our
+                  // own hash.) Fail closed with a clearer banner than the generic
+                  // rethrow, then let isFatalBroadcastError handle the rest.
+                  if (receiptErr.code === 'RECEIPT_TIMEOUT') {
+                    throw new CommandError(`\n  ⚠ Transaction was broadcast but NOT confirmed within the wait window.\n    Tx Hash:   ${txId || result.txHash}\n    Explorer:  ${explorerUrl}\n    ${receiptErr.message}\n\n  The transaction may still be pending — do NOT assume it failed. Check the\n  explorer before retrying; retrying may broadcast a second swap against the\n  same nonce.`, 'RECEIPT_TIMEOUT');
+                  }
+                  if (isFatalBroadcastError(receiptErr)) throw receiptErr;
                   log(`\n  ⚠ Transaction was broadcast but REVERTED on-chain!`);
-                  log(`    Tx Hash:   ${result.txHash}`);
+                  log(`    Tx Hash:   ${txId || result.txHash}`);
                   log(`    Explorer:  ${explorerUrl}`);
                   log(`    Error:     ${receiptErr.message}`);
                   if (qi + 1 < endIndex) {
@@ -3083,7 +3525,7 @@ EXAMPLES:
                     lastQuoteError = `${quoteName} reverted on-chain`;
                     continue;
                   }
-                  throw new CommandError(`\n  ⚠ Transaction was broadcast but REVERTED on-chain!\n    Tx Hash:   ${result.txHash}\n    Explorer:  ${explorerUrl}\n    Error:     ${receiptErr.message}\n\n  The trading API reported success, but the contract execution failed.\n  This can happen due to: stale quotes, insufficient gas, or liquidity changes.`, 'TX_REVERTED');
+                  throw new CommandError(`\n  ⚠ Transaction was broadcast but REVERTED on-chain!\n    Tx Hash:   ${txId || result.txHash}\n    Explorer:  ${explorerUrl}\n    Error:     ${receiptErr.message}\n\n  The trading API reported success, but the contract execution failed.\n  This can happen due to: stale quotes, insufficient gas, or liquidity changes.`, 'TX_REVERTED');
                 }
               }
 
@@ -3141,6 +3583,11 @@ EXAMPLES:
             }
 
           } catch (quoteErr) {
+            // Post-broadcast failures abort the whole execute — never retry the
+            // next quote once a transaction is already out and its outcome is
+            // unknown (mismatch, underivable local hash, or an unconfirmed
+            // receipt timeout). See isFatalBroadcastError.
+            if (isFatalBroadcastError(quoteErr)) throw quoteErr;
             const msg = quoteErr.message || '';
             log(`  ❌ Quote ${quoteName} failed: ${msg}`);
             if (msg.includes('AccountNotFound') && chainType === 'solana') {