nansen-cli 1.41.0 → 1.41.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.41.1
+
+### Patch Changes
+
+- [#527](https://github.com/nansen-ai/nansen-cli/pull/527) [`02efb6d`](https://github.com/nansen-ai/nansen-cli/commit/02efb6d1f40453c03135eb68cf493486a5b6133a) Thanks [@kome12](https://github.com/kome12)! - Cross-chain (bridge) swaps now run swap-outcome verification instead of skipping it entirely. The output-arrival check is still skipped (the output settles on the destination chain), but the input-outflow cap and no-sibling-drain checks now run on the source-chain leg, closing a gap where a compromised quote's bridge instructions could move more than the declared input. Bridges also now enforce an intent-relative lower bound on the source-chain input outflow (an exactIn bridge must spend ~the requested input, so a large fee-only or partial no-op no longer verifies) and still validate the quote's output-amount integrity, and the native-SOL bridge log no longer contradicts itself about whether the output check ran. Note the lower bound relaxes by a native-SOL fee/rent allowance (~0.013 SOL), so on a small native-SOL leg at or below that allowance the floor effectively collapses to a bare "outflow > 0" — the tightest bound possible for a native leg whose fees are indistinguishable from the transfer. `--swap-mode` is now validated against `exactIn`/`exactOut` at the CLI, and both the swap-outcome verifier and the pre-signing request-intent completeness checks fail closed on an unrecognized mode in a persisted quote so a garbage value cannot bypass the exactIn input floor — even when outcome verification is skipped or degraded.
+
+  Because bridges now go through the simulation, a bridge quote that **reverts in simulation** returns `proceed: false` and is dropped (the signing loop falls through to the next quote); only a simulation that cannot run at all (`NO_SIM_RPC` / `SIM_RPC_ERROR` / `NOT_SIM_CAPABLE`) degrades to proceed-without-verification, matching same-chain swaps. This is a new, fail-closed outcome for bridges specifically.
+
+- [#513](https://github.com/nansen-ai/nansen-cli/pull/513) [`55eb953`](https://github.com/nansen-ai/nansen-cli/commit/55eb953cc15fe21aa441d1700e05ef053c643a58) Thanks [@kome12](https://github.com/kome12)! - Fix `trade execute` crashing on Solana-source bridge quotes from the Relay aggregator, which return raw uncompiled instructions instead of a ready-to-sign transaction. These are now compiled client-side before signing.
+
 ## 1.41.0
 
 ### Minor Changes

package/package.json

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

package/src/schema.json

@@ -1570,6 +1570,7 @@
             "swap-mode": {
               "type": "string",
               "default": "exactIn",
+              "enum": ["exactIn", "exactOut"],
               "description": "\"exactIn\" (default) to spend exactly --amount of the sell token, or \"exactOut\" to receive exactly --amount of the buy token. Not supported together with --amount-unit percent."
             },
             "slippage": {

package/src/trade-validation.js

@@ -912,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
@@ -929,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`.
  *
@@ -944,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 } = {}) {
@@ -983,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
@@ -1005,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.');
@@ -1058,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 ---
@@ -1117,7 +1181,7 @@ 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 —
@@ -1170,6 +1234,8 @@ const NATIVE_FEE_RENT_SLACK_LAMPORTS = MAX_PRIORITY_FEE_LAMPORTS + NATIVE_SIBLIN
  *      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
@@ -1186,10 +1252,12 @@ const NATIVE_FEE_RENT_SLACK_LAMPORTS = MAX_PRIORITY_FEE_LAMPORTS + NATIVE_SIBLIN
  * @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}} 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) — the caller should surface this.
+ * @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 } = {}) {
@@ -1227,6 +1295,9 @@ export function assertSolanaSwapOutcome(request, quote, sim, { slippage, sibling
 
   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.');
@@ -1252,11 +1323,55 @@ export function assertSolanaSwapOutcome(request, quote, sim, { slippage, sibling
   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 ---
-  const swapMode = request.swapMode ?? 'exactIn';
-  const outputIsNative = outputAsset === SOL_SENTINEL;
-  const outputDelta = deltas[outputAsset] || 0n;
+  // 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.');
@@ -1290,26 +1405,30 @@ export function assertSolanaSwapOutcome(request, quote, sim, { slippage, sibling
     const bps = BigInt(Math.min(10000, Math.round(slip * 10000)));
     minOut = (quoted * (10000n - bps)) / 10000n;
   }
-  // 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}).`);
+  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 ---
@@ -1326,7 +1445,9 @@ export function assertSolanaSwapOutcome(request, quote, sim, { slippage, sibling
   // 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.
-  return { verified: true, inputAssertionSkipped: inputIsNative };
+  // 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 };
 }
 
 /**

package/src/trading.js

@@ -9,7 +9,8 @@ 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';
@@ -25,6 +26,8 @@ import { packageVersion, CommandError, telemetryHeaders, loadConfig } from './ap
 
 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' },
@@ -509,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.
  *
@@ -853,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
@@ -874,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
@@ -901,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) {
@@ -925,9 +1035,10 @@ export async function verifySwapOutcome({ chain, from, quote, quoteData, apiKey
  */
 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 };
+  // 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 };
@@ -940,7 +1051,14 @@ export async function verifySolanaSwapOutcome({ chain, walletAddress, txBase64,
     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.');
+      // 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 };
@@ -1148,6 +1266,14 @@ 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.`);
+  }
 }
 
 /**
@@ -1170,6 +1296,12 @@ export function assertCompleteSolanaRequestIntent(request) {
   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.`);
+  }
 }
 
 /**
@@ -1718,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)) {
@@ -2311,10 +2449,6 @@ 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');
-              }
               const solWalletId = quoteData.privyWalletIds?.solana;
               if (!solWalletId) throw new Error('No Solana Privy wallet ID in quote');
               const walletResult = await privyClient.getWallet(solWalletId);
@@ -2328,6 +2462,11 @@ EXAMPLES:
                 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);
@@ -2626,15 +2765,13 @@ EXAMPLES:
               // 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;
-              if (typeof txBase64 === 'object' && txBase64.data) {
-                txBase64 = base58Decode(txBase64.data).toString('base64');
-              }
+              // 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 for this sub-path so the intent-binding check
-              // below can confirm the quote was built for this exact wallet.
+              // 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);
@@ -2651,6 +2788,8 @@ EXAMPLES:
                 }
               }
 
+              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);

package/src/x402-svm.js

@@ -32,9 +32,13 @@ export function deriveATA(ownerBase58, mintBase58, tokenProgramBase58 = TOKEN_PR
 
 /**
  * Build a Solana MessageV0 from accounts and instructions.
- * Simplified builder for x402 payment transactions.
+ * feePayer is always placed at account index 0, forced signer+writable,
+ * regardless of whether an instruction references it directly.
+ * Returns numRequiredSignatures alongside the bytes since it's read back out
+ * of the header to size the signature-placeholder slots of the wrapping
+ * unsigned transaction (see callers).
  */
-function buildMessageV0({ feePayer, instructions, recentBlockhash, accounts: _accounts }) {
+export function buildMessageV0({ feePayer, instructions, recentBlockhash, accounts: _accounts }) {
   // All unique accounts in order: feePayer first, then signers, then rest
   const accountMap = new Map();
   const feePayerKey = feePayer;
@@ -129,10 +133,10 @@ function buildMessageV0({ feePayer, instructions, recentBlockhash, accounts: _ac
     parts.push(ix.data);
   }
 
-  // Address table lookups (empty for our use case)
+  // Address table lookups (empty — all accounts referenced statically above)
   parts.push(encodeCompactU16(0));
 
-  return Buffer.concat(parts);
+  return { messageBytes: Buffer.concat(parts), numRequiredSignatures };
 }
 
 // ============= Ed25519 Signing =============
@@ -231,7 +235,7 @@ export function buildUnsignedSvmTransaction(
     },
   ];
 
-  const messageBytes = buildMessageV0({
+  const { messageBytes } = buildMessageV0({
     feePayer: feePayerStr,
     instructions,
     recentBlockhash,