nansen-cli 1.40.0 → 1.41.0

package/src/trading.js

@@ -13,9 +13,12 @@ import { base58Decode } from './transfer.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 =============
@@ -109,7 +112,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;
 }
 
@@ -565,6 +569,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 +686,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 };
 }
 
 /**
@@ -787,6 +916,43 @@ 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: the output settles on the destination chain and can never
+  // appear in a source-chain simulation (mirrors the EVM bridge skip above).
+  if (quoteData?.toChain && quoteData.toChain !== quoteData.chain) return { proceed: true };
+  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) {
+      log('  ℹ Native-SOL input spend is bounded with fee/rent slack, not exactly delta-verified; output and sibling checks still ran.');
+    }
+    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.
@@ -984,6 +1150,28 @@ export function assertCompleteEvmRequestIntent(request) {
   }
 }
 
+/**
+ * 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.`);
+  }
+}
+
 /**
  * Sanity-check the target of a swap transaction before signing it.
  *
@@ -1257,23 +1445,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 =============
 
 /**
@@ -1593,9 +1764,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 +1801,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 +1837,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 +2093,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 +2168,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)
@@ -2141,9 +2315,45 @@ EXAMPLES:
               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.');
+              }
+
+              // 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 +2464,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 +2523,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,12 +2620,12 @@ 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.
+              // 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 either a base64 string (Jupiter) or an object
               // with a base58-encoded `data` field (OKX). Normalize to base64.
               let txBase64 = currentQuote.transaction;
@@ -2421,6 +2633,49 @@ EXAMPLES:
                 txBase64 = base58Decode(txBase64.data).toString('base64');
               }
 
+              // Resolve the signer for this sub-path so the intent-binding check
+              // below can confirm the quote was built for this exact wallet.
+              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.");
+                }
+              }
+
+              // 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) {
                 // Solana via WalletConnect: convert base64 → base58 for WC protocol
                 log('  Signing Solana transaction via WalletConnect...');
@@ -2567,12 +2822,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 +2839,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 +2878,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 +2889,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 +2903,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 +2989,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 +3159,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 +3211,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 +3334,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 +3386,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 +3444,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') {