@anywalletkit/protocol-swap2-lifi 0.7.0 → 0.8.1

package/dist/protocol.cjs

@@ -73,6 +73,76 @@ function describeLifiActivity(tx, ctx, isDiamond) {
   });
 }
 
+// src/solana-address.ts
+var import_ed25519 = require("@noble/curves/ed25519.js");
+var import_sha2 = require("@noble/hashes/sha2.js");
+var ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var BASE58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+var SOLANA_TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+var ASSOCIATED_TOKEN_PROGRAM = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+var PDA_MARKER = Uint8Array.from("ProgramDerivedAddress", (c) => c.charCodeAt(0));
+function base58(bytes) {
+  let n = 0n;
+  for (const b of bytes) n = n << 8n | BigInt(b);
+  let out = "";
+  while (n > 0n) {
+    out = ALPHABET[Number(n % 58n)] + out;
+    n /= 58n;
+  }
+  for (const b of bytes) {
+    if (b !== 0) break;
+    out = `1${out}`;
+  }
+  return out;
+}
+function solanaKey(address) {
+  if (!BASE58.test(address)) return null;
+  let n = 0n;
+  for (const ch of address) n = n * 58n + BigInt(ALPHABET.indexOf(ch));
+  let zeros = 0;
+  while (address[zeros] === "1") zeros++;
+  const body = [];
+  while (n > 0n) {
+    body.unshift(Number(n & 0xffn));
+    n >>= 8n;
+  }
+  if (zeros + body.length !== 32) return null;
+  const out = new Uint8Array(32);
+  out.set(body, zeros);
+  return out;
+}
+var onCurve = (bytes) => {
+  try {
+    import_ed25519.ed25519.Point.fromBytes(bytes);
+    return true;
+  } catch {
+    return false;
+  }
+};
+function programAddress(seeds, program) {
+  for (let bump = 255; bump >= 0; bump--) {
+    const parts = [...seeds, Uint8Array.of(bump), program, PDA_MARKER];
+    const buf = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+      buf.set(p, at);
+      at += p.length;
+    }
+    const hash = (0, import_sha2.sha256)(buf);
+    if (!onCurve(hash)) return hash;
+  }
+  throw new Error("no program address for these seeds");
+}
+function associatedTokenAccount(owner, mint, tokenProgram = solanaKey(SOLANA_TOKEN_PROGRAM)) {
+  return programAddress([owner, tokenProgram, mint], solanaKey(ASSOCIATED_TOKEN_PROGRAM));
+}
+
+// src/refusals.ts
+var import_errors = require("@anywalletkit/protocol-swap2-core/errors");
+var notes = (0, import_errors.refusalNotes)();
+var note = notes.note;
+var reasonOf = notes.reasonOf;
+
 // src/calldata.ts
 var GENERIC_SWAPS = {
   "0x4630a0d8": { single: false },
@@ -292,18 +362,18 @@ function swapsAt(r, base, head) {
 function checkSteps(steps, e, finalAsset) {
   const first = steps[0];
   const last = steps[steps.length - 1];
-  if (!same(first.sendingAssetId, e.fromToken)) return `spends ${first.sendingAssetId}, not ${e.fromToken}`;
-  if (first.fromAmount === 0n || first.fromAmount > e.amountIn) return `swaps ${first.fromAmount}, not the ${e.amountIn} spent`;
+  if (!same(first.sendingAssetId, e.fromToken)) return note(`spends ${first.sendingAssetId}, not ${e.fromToken}`, "policy_refused");
+  if (first.fromAmount === 0n || first.fromAmount > e.amountIn) return note(`swaps ${first.fromAmount}, not the ${e.amountIn} spent`, "policy_refused");
   let deposited = 0n;
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
-    if (i > 0 && !same(step.sendingAssetId, steps[i - 1].receivingAssetId)) return `step ${i} spends ${step.sendingAssetId}, which step ${i - 1} does not deliver`;
+    if (i > 0 && !same(step.sendingAssetId, steps[i - 1].receivingAssetId)) return note(`step ${i} spends ${step.sendingAssetId}, which step ${i - 1} does not deliver`, "policy_refused");
     if (!step.requiresDeposit) continue;
-    if (!same(step.sendingAssetId, e.fromToken)) return `step ${i} pulls ${step.sendingAssetId} from the wallet, not the input ${e.fromToken}`;
+    if (!same(step.sendingAssetId, e.fromToken)) return note(`step ${i} pulls ${step.sendingAssetId} from the wallet, not the input ${e.fromToken}`, "policy_refused");
     deposited += step.fromAmount;
   }
-  if (deposited > e.amountIn) return `the steps pull ${deposited} from the wallet, more than the ${e.amountIn} spent`;
-  if (!same(last.receivingAssetId, finalAsset)) return `delivers ${last.receivingAssetId}, not ${finalAsset}`;
+  if (deposited > e.amountIn) return note(`the steps pull ${deposited} from the wallet, more than the ${e.amountIn} spent`, "policy_refused");
+  if (!same(last.receivingAssetId, finalAsset)) return note(`delivers ${last.receivingAssetId}, not ${finalAsset}`, "policy_refused");
   return null;
 }
 var MAYAN_REFUND_AT = {
@@ -344,32 +414,32 @@ function acrossSwapRefunds(r, at) {
 }
 var ERC20_TRANSFER = "0xa9059cbb";
 function ecoDelivery(r, at, e) {
-  if (kindOf(e.toToken) === "native") return "an Eco route to the native token cannot be checked here";
+  if (kindOf(e.toToken) === "native") return note("an Eco route to the native token cannot be checked here", "recipient_unverifiable");
   const destination = r.word(at + 32 * 3);
-  if (destination !== e.destChainId) return `the Eco intent executes on chain ${destination}, not the destination ${e.destChainId} \u2014 a route whose delivery cannot be checked here`;
+  if (destination !== e.destChainId) return note(`the Eco intent executes on chain ${destination}, not the destination ${e.destChainId} \u2014 a route whose delivery cannot be checked here`, "recipient_unverifiable");
   const route = r.bytes(at, at + 32 * 4);
   const tuple = route.small(0);
   const calls = tuple + route.small(tuple + 32 * 5);
   const n = route.small(calls);
-  if (n === 0) return "the Eco route makes no calls on the destination chain";
-  if (n > 16) return `the Eco route makes ${n} calls on the destination chain, more than the 16 read here`;
+  if (n === 0) return note("the Eco route makes no calls on the destination chain", "recipient_unverifiable");
+  if (n > 16) return note(`the Eco route makes ${n} calls on the destination chain, more than the 16 read here`, "recipient_unverifiable");
   const last = calls + 32 + route.small(calls + 32 + 32 * (n - 1));
   const target = route.address(last);
   const data = route.bytes(last, last + 32);
-  if (route.word(last + 64) !== 0n || data.length !== 68 || data.raw(0, 4) !== ERC20_TRANSFER) return "the Eco route does not end in a token transfer";
+  if (route.word(last + 64) !== 0n || data.length !== 68 || data.raw(0, 4) !== ERC20_TRANSFER) return note("the Eco route does not end in a token transfer", "recipient_unverifiable");
   const to = data.address(4);
   const amount = data.word(36);
-  if (!same(target, e.toToken)) return `the Eco route delivers ${target}, not ${e.toToken}`;
-  if (!same(to, e.receiver)) return `the Eco route pays ${to}, not ${e.receiver}`;
-  if (amount < e.minOut) return `the Eco route delivers ${amount}, below the ${e.minOut} shown`;
+  if (!same(target, e.toToken)) return note(`the Eco route delivers ${target}, not ${e.toToken}`, "policy_refused");
+  if (!same(to, e.receiver)) return note(`the Eco route pays ${to}, not ${e.receiver}`, "recipient_mismatch");
+  if (amount < e.minOut) return note(`the Eco route delivers ${amount}, below the ${e.minOut} shown`, "price_check_failed");
   return null;
 }
 function m0Delivery(r, at, e) {
-  if (kindOf(e.toToken) === "native") return "an M0 order cannot deliver the native token";
+  if (kindOf(e.toToken) === "native") return note("an M0 order cannot deliver the native token", "unsupported_pair");
   const tokenOut = r.address(at + 32 * 3);
   const amountOut = r.word(at + 32 * 5);
-  if (!same(tokenOut, e.toToken)) return `the M0 order asks for ${tokenOut}, not ${e.toToken}`;
-  if (amountOut < e.minOut) return `the M0 order asks for ${amountOut}, below the ${e.minOut} shown`;
+  if (!same(tokenOut, e.toToken)) return note(`the M0 order asks for ${tokenOut}, not ${e.toToken}`, "policy_refused");
+  if (amountOut < e.minOut) return note(`the M0 order asks for ${amountOut}, below the ${e.minOut} shown`, "price_check_failed");
   return null;
 }
 var FACET_DATA = {
@@ -383,8 +453,9 @@ var FACET_DATA = {
   Frax: { inline: 5, refunds: [["refundRecipient", 3]], zeroRefused: true },
   Glacis: { inline: 4, refunds: [["refundAddress", 1]], zeroRefused: true },
   LayerSwap: { refunds: [["refundRecipient", 2]], zeroRefused: true },
+  // The escrow order's user. Not reached while LI.FI Intents is refused on every EVM-source route (INTENTS_UNPINNED); kept for when
+  // its oracles and settler are pinned.
   LiFiIntentEscrowV2: { refunds: [["depositAndRefundAddress", 2]], zeroRefused: true },
-  // the escrow order's user
   M0: { inline: 7, refunds: [["refundRecipient", 1], ["orderOwner", 2]], zeroRefused: true, delivery: m0Delivery },
   // orderOwner gets a cancelled order back
   Mayan: { refunds: [["refundRecipient", 7]], nested: mayanRefunds, zeroRefused: true },
@@ -402,79 +473,161 @@ function facetDataAt(r, bridge, spec) {
 }
 function refundMismatch(r, bridge, e) {
   const spec = FACET_DATA[bridge.facet];
-  if (!spec) return NO_REFUND_FIELDS.has(bridge.facet) ? null : `no known refund layout for ${bridge.facet}`;
+  if (!spec) return NO_REFUND_FIELDS.has(bridge.facet) ? null : note(`no known refund layout for ${bridge.facet}`, "recipient_unverifiable");
   const at = facetDataAt(r, bridge, spec);
   const paid = (spec.refunds ?? []).map(([field, word]) => [`${bridge.facet} ${field}`, r.address(at + 32 * word), spec.zeroRefused === true]);
   paid.push(...spec.nested?.(r, at) ?? []);
   for (const [what, to, zeroRefused] of paid) {
     if (zeroRefused && /^0x0{40}$/.test(to)) continue;
-    if (!same(to, e.sender) && !same(to, e.receiver)) return `${what} pays ${to}, neither the sender ${e.sender} nor the recipient`;
+    if (!same(to, e.sender) && !same(to, e.receiver)) return note(`${what} pays ${to}, neither the sender ${e.sender} nor the recipient`, "recipient_mismatch");
   }
   return null;
 }
+var NON_EVM_UNREAD = "the recipient on a non-EVM destination sits in bridge-specific data and cannot be checked here";
+var LIFI_SOLANA_CHAIN_ID = 1151111081099710n;
+var NON_EVM_ADDRESS = "0x11f111f111f111f111f111f111f111f111f111f1";
+var SOLANA_USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+var WORMHOLE_SOLANA = 1n;
+var CCTP_DOMAIN_SOLANA = 5n;
+var CHAINFLIP_SOLANA_ASSETS = {
+  "11111111111111111111111111111111": 9n,
+  [SOLANA_USDC]: 10n,
+  Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB: 16n
+};
+var DEPOSIT_FACETS = /* @__PURE__ */ new Set(["NEARIntents", "LayerSwap", "Unit"]);
+var MAYAN_SOLANA = {
+  // Swift v2 createOrderWithToken(tokenIn, amountIn, (payloadType, trader, destAddr, destChainId, referrerAddr, tokenOut, minAmountOut, …), customPayload)
+  "0xa3a30834": { destAddr: 4, chain: 5, cctp: false, payloadType: [2, 1n], tokenOut: 7 },
+  // MCTP createOrder((tokenIn, amountIn, gasDrop, destAddr, destChain, tokenOut, minAmountOut, deadline, redeemFee, referrerAddr, referrerBps))
+  "0x1c59b7fc": { destAddr: 3, chain: 4, cctp: false, tokenOut: 5 },
+  // MCTP bridgeWithFee(tokenIn, amountIn, redeemFee, gasDrop, destAddr, destDomain, payloadType, customPayload): delivers USDC
+  "0x2072197f": { destAddr: 4, chain: 5, cctp: true, payloadType: [6, 1n] },
+  // Fast MCTP bridge(tokenIn, amountIn, redeemFee, circleMaxFee, gasDrop, destAddr, destDomain, referrerAddress, referrerBps, payloadType, minFinalityThreshold, customPayload): delivers USDC
+  "0xf58b6de8": { destAddr: 5, chain: 6, cctp: true, payloadType: [9, 1n] },
+  // Fast MCTP createOrder(tokenIn, amountIn, circleMaxFee, destDomain, minFinalityThreshold, (payloadType 3, destAddr, tokenOut, amountOutMin, …))
+  "0x2337e236": { destAddr: 6, chain: 3, cctp: true, payloadType: [5, 3n], tokenOut: 7 }
+};
+var hexOf = (b) => `0x${Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("")}`;
+var keyOf = (word) => base58(Uint8Array.from(word.slice(2).match(/../g) ?? [], (h) => Number.parseInt(h, 16)));
+function mayanToSolana(r, at, t) {
+  const declared = r.raw(at, 32);
+  if (declared !== t.ownerHex) return note(`Mayan's nonEVMReceiver is ${keyOf(declared)}, not the recipient ${t.e.receiver}`, "recipient_mismatch");
+  const p = r.bytes(at, at + 32 * 2);
+  const selector = p.raw(0, 4);
+  const o = MAYAN_SOLANA[selector];
+  if (!o) return note(`the Mayan call ${selector} is an entry point whose Solana recipient cannot be checked here`, "recipient_unverifiable");
+  const word = (i) => 4 + 32 * i;
+  if (o.payloadType && p.word(word(o.payloadType[0])) !== o.payloadType[1]) return note(`the Mayan call ${selector} carries payload type ${p.word(word(o.payloadType[0]))}, not a plain delivery`, "recipient_unverifiable");
+  const dest = p.raw(word(o.destAddr), 32);
+  if (dest !== t.ownerHex) return note(`the Mayan order pays ${keyOf(dest)} on Solana, not the recipient ${t.e.receiver}`, "recipient_mismatch");
+  const chain = p.word(word(o.chain));
+  if (chain !== (o.cctp ? CCTP_DOMAIN_SOLANA : WORMHOLE_SOLANA)) return note(`the Mayan order goes to ${o.cctp ? "CCTP domain" : "Wormhole chain"} ${chain}, not Solana`, "policy_refused");
+  if (o.tokenOut === void 0) return t.e.toToken === SOLANA_USDC ? null : note(`a Mayan CCTP transfer delivers USDC, not ${t.e.toToken}`, "policy_refused");
+  const token = p.raw(word(o.tokenOut), 32);
+  return token === t.mintHex ? null : note(`the Mayan order delivers ${keyOf(token)}, not ${t.e.toToken}`, "policy_refused");
+}
+function polymerToSolana(r, at, t) {
+  const declared = r.raw(at + 32 * 2, 32);
+  if (declared !== t.ownerHex) return note(`Polymer CCTP's nonEVMReceiver is ${keyOf(declared)}, not the recipient ${t.e.receiver}`, "recipient_mismatch");
+  if (t.e.toToken !== SOLANA_USDC) return note(`Polymer CCTP delivers USDC, not ${t.e.toToken}`, "policy_refused");
+  const mintTo = r.raw(at + 32 * 3, 32);
+  const account = hexOf(associatedTokenAccount(t.owner, t.mint));
+  return mintTo === account ? null : note(`the Polymer CCTP transfer mints to ${keyOf(mintTo)}, not the recipient's USDC account ${keyOf(account)}`, "recipient_mismatch");
+}
+function chainflipToSolana(r, at, t) {
+  const dst = r.bytes(at, at);
+  if (dst.length !== 32) return note(`Chainflip pays a ${dst.length}-byte address on Solana, not the recipient ${t.e.receiver}`, "recipient_mismatch");
+  if (dst.raw(0, 32) !== t.ownerHex) return note(`Chainflip pays ${keyOf(dst.raw(0, 32))} on Solana, not the recipient ${t.e.receiver}`, "recipient_mismatch");
+  const asset = r.word(at + 32);
+  const want = CHAINFLIP_SOLANA_ASSETS[t.e.toToken];
+  return want !== void 0 && asset === want ? null : note(`Chainflip delivers its asset ${asset}, not ${t.e.toToken}`, "policy_refused");
+}
+var SOLANA_DELIVERY = {
+  Mayan: mayanToSolana,
+  PolymerCCTP: polymerToSolana,
+  Chainflip: chainflipToSolana
+};
+var INTENTS_TO_SOLANA = "a LI.FI Intents order to Solana names its own oracles, output settler and output amount, which cannot be checked here \u2014 its escrow could release the input without the delivery";
+var INTENTS_UNPINNED = "a LI.FI Intents order to an EVM chain names its own oracles, output settler and output amount, which cannot be checked here \u2014 its escrow could release the input without the delivery";
+var INTENTS_FACET = "LiFiIntentEscrowV2";
+function solanaRecipientMismatch(r, bridge, receiver, e) {
+  if (e.destChainId !== LIFI_SOLANA_CHAIN_ID) return note(NON_EVM_UNREAD, "recipient_unverifiable");
+  if (!same(receiver, NON_EVM_ADDRESS)) return note(`BridgeData pays ${receiver}, not LI.FI's non-EVM placeholder ${NON_EVM_ADDRESS}, on a Solana route`, "recipient_mismatch");
+  if (DEPOSIT_FACETS.has(bridge.facet)) return note(`${bridge.facet} pays a deposit address whose off-chain order names the Solana recipient \u2014 the transaction does not bind it`, "recipient_unverifiable");
+  if (bridge.facet === INTENTS_FACET) return note(INTENTS_TO_SOLANA, "recipient_unverifiable");
+  const read = SOLANA_DELIVERY[bridge.facet];
+  if (!read) return note(NON_EVM_UNREAD, "recipient_unverifiable");
+  const owner = solanaKey(e.receiver);
+  if (!owner) return note(`the recipient ${e.receiver} is not a Solana address`, "recipient_mismatch");
+  const mint = solanaKey(e.toToken);
+  if (!mint) return note(`the destination token ${e.toToken} is not a Solana mint`, "unsupported_pair");
+  return read(r, facetDataAt(r, bridge, FACET_DATA[bridge.facet]), { owner, ownerHex: hexOf(owner), mint, mintHex: hexOf(mint), e });
+}
 function diamondCallMismatch(data, e) {
   let r;
   try {
     r = new Reader(data);
   } catch {
-    return "the calldata is not hex";
+    return note("the calldata is not hex", "upstream_unavailable");
   }
-  if (r.length < 4 + 32 * 2) return "the calldata is too short";
+  if (r.length < 4 + 32 * 2) return note("the calldata is too short", "upstream_unavailable");
   const selector = data.slice(0, 10).toLowerCase();
   const generic = GENERIC_SWAPS[selector];
   try {
     if (generic) {
-      if (!e.sameChain) return "a same-chain swap call on a cross-chain route";
+      if (!e.sameChain) return note("a same-chain swap call on a cross-chain route", "policy_refused");
       const receiver2 = r.address(4 + 96);
       const minAmount2 = r.word(4 + 128);
       const steps = generic.single ? [swapAt(r, 4 + r.small(4 + 160))] : swapsAt(r, 4, 4 + 160);
-      if (!e.evmDestination || !same(receiver2, e.receiver)) return `pays ${receiver2}, not ${e.receiver}`;
-      if (minAmount2 < e.minOut) return `accepts ${minAmount2}, below the ${e.minOut} shown`;
-      if (generic.from && kindOf(e.fromToken) !== generic.from) return `${selector} swaps from ${generic.from === "native" ? "the native coin" : "a token"}, but the input is ${kindOf(e.fromToken) === "native" ? "the native coin" : "a token"}`;
+      if (!e.evmDestination || !same(receiver2, e.receiver)) return note(`pays ${receiver2}, not ${e.receiver}`, "recipient_mismatch");
+      if (minAmount2 < e.minOut) return note(`accepts ${minAmount2}, below the ${e.minOut} shown`, "price_check_failed");
+      if (generic.from && kindOf(e.fromToken) !== generic.from) return note(`${selector} swaps from ${generic.from === "native" ? "the native coin" : "a token"}, but the input is ${kindOf(e.fromToken) === "native" ? "the native coin" : "a token"}`, "policy_refused");
       if (generic.to && (kindOf(e.toToken) !== generic.to || kindOf(steps[steps.length - 1].receivingAssetId) !== generic.to)) {
-        return `${selector} delivers ${generic.to === "native" ? "the native coin" : "a token"}, but the output is ${kindOf(e.toToken) === "native" ? "the native coin" : "a token"} \u2014 its minimum would be counted in the wrong asset`;
+        return note(`${selector} delivers ${generic.to === "native" ? "the native coin" : "a token"}, but the output is ${kindOf(e.toToken) === "native" ? "the native coin" : "a token"} \u2014 its minimum would be counted in the wrong asset`, "policy_refused");
       }
       return checkSteps(steps, e, e.toToken);
     }
     const unbound = UNBOUND_BRIDGES[selector];
-    if (unbound) return `${unbound} delivers to a recipient the transaction does not bind (an off-chain order or unchecked facet data)`;
+    if (unbound) return note(`${unbound} delivers to a recipient the transaction does not bind (an off-chain order or unchecked facet data)`, "recipient_unverifiable");
     const bridge = BRIDGE_CALLS[selector];
-    if (!bridge) return `unknown Diamond call ${selector}`;
+    if (!bridge) return note(`unknown Diamond call ${selector}`, "policy_refused");
+    if (bridge.facet === INTENTS_FACET && e.evmDestination) return note(INTENTS_UNPINNED, "recipient_unverifiable");
     const head = r.small(4);
-    if (head < (bridge.sourceSwaps ? 96 : 64) || head % 32 !== 0 || head > 32 * 32) return `unknown Diamond call ${selector}`;
+    if (head < (bridge.sourceSwaps ? 96 : 64) || head % 32 !== 0 || head > 32 * 32) return note(`unknown Diamond call ${selector}`, "policy_refused");
     const at = 4 + head;
-    if (r.small(at + 32) !== 320) return `unknown Diamond call ${selector}`;
+    if (r.small(at + 32) !== 320) return note(`unknown Diamond call ${selector}`, "policy_refused");
     const sendingAssetId = r.address(at + 128);
     const receiver = r.address(at + 160);
     const minAmount = r.word(at + 192);
     const destinationChainId = r.word(at + 224);
     const hasSourceSwaps = r.bool(at + 256);
     const hasDestinationCall = r.bool(at + 288);
-    if (e.sameChain) return "a bridge call on a same-chain route";
-    if (destinationChainId !== e.destChainId) return `bridges to chain ${destinationChainId}, not ${e.destChainId}`;
-    if (hasDestinationCall) return "the route runs a call on the destination chain, whose recipient cannot be checked here";
-    if (!e.evmDestination) return "the recipient on a non-EVM destination sits in bridge-specific data and cannot be checked here";
-    if (!same(receiver, e.receiver)) return `pays ${receiver}, not ${e.receiver}`;
-    if (hasSourceSwaps !== bridge.sourceSwaps) return `unknown Diamond call ${selector}`;
+    if (e.sameChain) return note("a bridge call on a same-chain route", "policy_refused");
+    if (destinationChainId !== e.destChainId) return note(`bridges to chain ${destinationChainId}, not ${e.destChainId}`, "policy_refused");
+    if (hasDestinationCall) return note("the route runs a call on the destination chain, whose recipient cannot be checked here", "recipient_unverifiable");
+    if (!e.evmDestination) {
+      const why = solanaRecipientMismatch(r, bridge, receiver, e);
+      if (why) return why;
+    } else if (!same(receiver, e.receiver)) return note(`pays ${receiver}, not ${e.receiver}`, "recipient_mismatch");
+    if (hasSourceSwaps !== bridge.sourceSwaps) return note(`unknown Diamond call ${selector}`, "policy_refused");
     const refund = refundMismatch(r, bridge, e);
     if (refund) return refund;
     const spec = FACET_DATA[bridge.facet];
     const delivery = spec?.delivery?.(r, facetDataAt(r, bridge, spec), e);
     if (delivery) return delivery;
     if (hasSourceSwaps) {
-      if (minAmount === 0n) return "bridges nothing after the source swaps";
+      if (minAmount === 0n) return note("bridges nothing after the source swaps", "policy_refused");
       return checkSteps(swapsAt(r, 4, 4 + 32), e, sendingAssetId);
     }
-    if (minAmount > e.amountIn || minAmount * 10000n < e.amountIn * (10000n - BRIDGE_INPUT_FEE_MAX_BPS)) return `bridges ${minAmount}, not the ${e.amountIn} spent`;
-    return same(sendingAssetId, e.fromToken) ? null : `bridges ${sendingAssetId}, not ${e.fromToken}`;
+    if (minAmount > e.amountIn || minAmount * 10000n < e.amountIn * (10000n - BRIDGE_INPUT_FEE_MAX_BPS)) return note(`bridges ${minAmount}, not the ${e.amountIn} spent`, "policy_refused");
+    return same(sendingAssetId, e.fromToken) ? null : note(`bridges ${sendingAssetId}, not ${e.fromToken}`, "policy_refused");
   } catch (err) {
-    return `the Diamond calldata does not decode (${err instanceof Error ? err.message : String(err)})`;
+    return note(`the Diamond calldata does not decode (${err instanceof Error ? err.message : String(err)})`, "policy_refused");
   }
 }
 
 // src/solana.ts
 var import_util2 = require("@anywalletkit/protocol-swap2-core/util");
-var ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 var MAYAN_ENTRY_PROGRAMS = /* @__PURE__ */ new Set([
   "D8C8iW6zmoKg5TRr8nQ7h14TMWqQX8FiBdj2ju5MF3wa",
   // CPI_PROXY_PROGRAM_ID
@@ -489,20 +642,6 @@ var MAYAN_ENTRY_PROGRAMS = /* @__PURE__ */ new Set([
 ]);
 var SYSTEM_PROGRAM = "11111111111111111111111111111111";
 var LIFI_SOLANA_FEE_WALLET = "34FKjAdVcTax2DHqV2XnbXa9J3zmyKcFuFKWbcmgxjgm";
-function base58(bytes) {
-  let n = 0n;
-  for (const b of bytes) n = n << 8n | BigInt(b);
-  let out = "";
-  while (n > 0n) {
-    out = ALPHABET[Number(n % 58n)] + out;
-    n /= 58n;
-  }
-  for (const b of bytes) {
-    if (b !== 0) break;
-    out = `1${out}`;
-  }
-  return out;
-}
 var Cursor = class {
   constructor(b) {
     this.b = b;
@@ -532,7 +671,7 @@ var Cursor = class {
 };
 function solanaBridgeTxMismatch(base64, sender) {
   const bytes = (0, import_util2.base64Bytes)(base64);
-  if (!bytes) return "the Solana transaction is not base64";
+  if (!bytes) return note("the Solana transaction is not base64", "upstream_unavailable");
   const c = new Cursor(bytes);
   try {
     c.bytes(64 * c.short());
@@ -540,7 +679,7 @@ function solanaBridgeTxMismatch(base64, sender) {
     if ((first & 128) === 0) c.at--;
     c.bytes(3);
     const keys = Array.from({ length: c.short() }, () => base58(c.bytes(32)));
-    if (keys[0] !== sender) return `the Solana transaction is paid by ${keys[0] ?? "nobody"}, not the sender ${sender}`;
+    if (keys[0] !== sender) return note(`the Solana transaction is paid by ${keys[0] ?? "nobody"}, not the sender ${sender}`, "policy_refused");
     c.bytes(32);
     let mayan = false;
     const payees = [];
@@ -555,15 +694,16 @@ function solanaBridgeTxMismatch(base64, sender) {
         if (to !== void 0 && to !== sender && to !== LIFI_SOLANA_FEE_WALLET) payees.push(to);
       }
     }
-    return mayan && payees.length ? `the Solana transaction transfers SOL to ${payees[0]}, which is neither the sender nor LI.FI's fee wallet` : null;
+    return mayan && payees.length ? note(`the Solana transaction transfers SOL to ${payees[0]}, which is neither the sender nor LI.FI's fee wallet`, "recipient_mismatch") : null;
   } catch (err) {
-    return `the Solana transaction does not decode (${err instanceof Error ? err.message : String(err)})`;
+    return note(`the Solana transaction does not decode (${err instanceof Error ? err.message : String(err)})`, "policy_refused");
   }
 }
 
 // src/provider.ts
 var import_util3 = require("@anywalletkit/protocol-swap2-core/util");
 var import_validate = require("@anywalletkit/protocol-swap2-core/validate");
+var import_errors2 = require("@anywalletkit/protocol-swap2-core/errors");
 var import_core = require("@anywalletkit/core");
 var DEFAULT_LIFI_BASE = "https://li.quest/v1";
 var LIFI_CHAIN = {
@@ -604,7 +744,8 @@ var LIFI_CHAIN = {
   "eip155:2818": "2818",
   "eip155:14": "14",
   // 2026-11-10: Elysium (Kinetiq; li.quest/v1/chains id 99901, key "ely"). LI.FI's bridges there are Relay (refused
-  // below: UNBOUND_TOOLS) and LI.FI Intents; same-chain swaps go through GenericSwapFacetV3 (KyberSwap, Nordstern).
+  // below: UNBOUND_TOOLS) and LI.FI Intents (refused too: UNPINNED_TOOLS), so it has no cross-chain LI.FI route for now;
+  // same-chain swaps go through GenericSwapFacetV3 (KyberSwap, Nordstern).
   "eip155:99901": "99901",
   [LIFI_SOLANA_CAIP2]: "1151111081099710"
 };
@@ -614,12 +755,12 @@ var SOLANA_NATIVE = "11111111111111111111111111111111";
 var EVM_PLACEHOLDER = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045";
 var SOLANA_PLACEHOLDER = "HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk";
 var isSolana = (chain) => chain === LIFI_SOLANA_CAIP2;
-var BASE58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+var BASE582 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 var BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 var SAME_CHAIN_MAX_SECONDS = 90;
 var MAX_INPUT_FEE_BPS = 300;
 function sameChainAddress(chain, actual, expected) {
-  if (isSolana(chain)) return !!actual && BASE58.test(actual) && actual === expected;
+  if (isSolana(chain)) return !!actual && BASE582.test(actual) && actual === expected;
   return sameAddress(actual, expected);
 }
 function nativeFor(chain, token) {
@@ -708,7 +849,16 @@ function headers(key) {
 }
 var TOOL_KEY = /^[A-Za-z0-9_-]{1,64}$/;
 var UNBOUND_TOOLS = Object.freeze(["relaydepository", "garden", "squid", "symbiosis"]);
-function routeOptions(body, excluded) {
+var UNPINNED_TOOLS = Object.freeze(["lifiIntents"]);
+var REFUSED_EVM_TOOLS = Object.freeze([...UNBOUND_TOOLS, ...UNPINNED_TOOLS]);
+var SOLANA_DESTINATION_TOOLS = Object.freeze(["mayan", "mayanMCTP", "mayanFastMCTP", "polymer", "polymerStandard", "chainflip"]);
+var SMART_DEPOSITS_TOOL = /^smartdeposits?$/i;
+var dryRecipient = (params, fromAddress) => !isSolana(params.sourceChain) && isSolana(params.destChain) ? SOLANA_PLACEHOLDER : fromAddress;
+function placeholderIn(params) {
+  if (!params.refundAddress) return "sender";
+  return !params.destAddress && dryRecipient(params, params.refundAddress) !== params.refundAddress ? "recipient" : null;
+}
+function routeOptions(body, excluded, allowed) {
   const routes = body?.routes;
   if (!Array.isArray(routes)) return [];
   const out = [];
@@ -718,7 +868,7 @@ function routeOptions(body, excluded) {
     const cross = Array.isArray(step.includedSteps) ? step.includedSteps.find((i) => i?.type === "cross")?.tool : void 0;
     const tool = typeof cross === "string" ? cross : step.tool;
     const eta = step.estimate?.executionDuration;
-    if (typeof tool !== "string" || !TOOL_KEY.test(tool) || excluded.includes(tool) || typeof eta !== "number" || !Number.isFinite(eta) || eta < 0) continue;
+    if (typeof tool !== "string" || !TOOL_KEY.test(tool) || excluded.includes(tool) || allowed && !allowed.includes(tool) || typeof eta !== "number" || !Number.isFinite(eta) || eta < 0) continue;
     if (typeof r.toAmount !== "string" || typeof r.toAmountMin !== "string" || !/^\d{1,60}$/.test(r.toAmount) || !/^\d{1,60}$/.test(r.toAmountMin)) continue;
     out.push({
       tool,
@@ -731,6 +881,92 @@ function routeOptions(body, excluded) {
   }
   return out;
 }
+var LIFI_TOOL_REASONS = {
+  NO_POSSIBLE_ROUTE: "no_route",
+  INSUFFICIENT_LIQUIDITY: "insufficient_liquidity",
+  TOOL_TIMEOUT: "upstream_unavailable",
+  RPC_ERROR: "upstream_unavailable",
+  AMOUNT_TOO_LOW: "amount_too_small",
+  AMOUNT_TOO_HIGH: "amount_too_large",
+  FEES_HIGHER_THAN_AMOUNT: "amount_too_small",
+  FEES_HGHER_THAN_AMOUNT: "amount_too_small",
+  // an older spelling of the same code
+  DIFFERENT_RECIPIENT_NOT_SUPPORTED: "unsupported_pair",
+  CANNOT_GUARANTEE_MIN_AMOUNT: "price_check_failed"
+};
+var LIFI_ERROR_REASONS = {
+  1001: "no_route",
+  // FailedToBuildTransactionError: "None of the available routes could successfully generate a tx"
+  1002: "no_route",
+  // NoQuoteError: "No available quotes for the requested transfer"
+  1003: "no_route",
+  // NotFoundError
+  1005: "rate_limited",
+  // RateLimitError
+  1006: "upstream_unavailable",
+  // ServerError
+  1007: "price_check_failed",
+  // SlippageError
+  1008: "upstream_unavailable",
+  // ThirdPartyError
+  1009: "upstream_unavailable",
+  // TimeoutError
+  1010: "key_rejected",
+  // UnauthorizedError
+  1012: "upstream_unavailable"
+  // RpcFailure
+};
+var LIFI_MESSAGE_REASONS = [
+  [/no available quotes|unable to find a quote|none of the available routes|no route/i, "no_route"],
+  [/rate limit|too many requests/i, "rate_limited"],
+  [/api[ -]?key|unauthori[sz]ed/i, "key_rejected"],
+  [/insufficient liquidity|not enough liquidity/i, "insufficient_liquidity"],
+  [/amount (?:is )?too (?:low|small)|below the minimum/i, "amount_too_small"],
+  [/amount (?:is )?too (?:high|large)|above the maximum/i, "amount_too_large"],
+  [/not supported|unsupported|unknown token|invalid token/i, "unsupported_pair"],
+  [/halted|paused|maintenance/i, "chain_halted"]
+];
+function lifiToolCodes(errors) {
+  const out = /* @__PURE__ */ new Set();
+  const stack = [errors];
+  for (let visited = 0; stack.length > 0 && visited < 256; visited++) {
+    const node = stack.pop();
+    if (Array.isArray(node)) {
+      stack.push(...node.slice(0, 64));
+      continue;
+    }
+    if (!node || typeof node !== "object") continue;
+    const code = node.code;
+    if (typeof code === "string" && Object.prototype.hasOwnProperty.call(LIFI_TOOL_REASONS, code)) out.add(code);
+    for (const [key, value] of Object.entries(node).slice(0, 64)) if (key !== "action" && value && typeof value === "object") stack.push(value);
+  }
+  return [...out];
+}
+function lifiBodyReason(body, filteredOut) {
+  const b = body && typeof body === "object" ? body : {};
+  const tools = [...new Set(lifiToolCodes(b.errors).map((code) => LIFI_TOOL_REASONS[code]))];
+  if (tools.length === 1) return tools[0];
+  if (filteredOut.length > 0 && filteredOut.every((r) => /^ROUTE_SLIPPAGE_FLOOR_UNREACHABLE/.test(r))) return "price_check_failed";
+  const byCode = typeof b.code === "number" ? LIFI_ERROR_REASONS[b.code] : void 0;
+  if (byCode) return byCode;
+  const message = typeof b.message === "string" ? b.message : "";
+  return LIFI_MESSAGE_REASONS.find(([pattern]) => pattern.test(message))?.[1];
+}
+var LIFI_TRANSIENT_REASONS = /* @__PURE__ */ new Set(["rate_limited", "insufficient_liquidity", "chain_halted"]);
+function lifiHttpRefusal(status, retryAfter, body, filteredOut) {
+  const http = (0, import_errors2.httpRefusal)(status, retryAfter);
+  if (http && http.reason !== "upstream_unavailable") return http;
+  const info = (reason) => {
+    if (reason === "rate_limited") {
+      const wait = (0, import_errors2.parseRetryAfter)(retryAfter);
+      return { reason, httpStatus: status, ...wait !== void 0 ? { retryAfterMs: wait } : {} };
+    }
+    return reason === "upstream_unavailable" || reason === "key_rejected" ? { reason, httpStatus: status } : { reason };
+  };
+  const byBody = lifiBodyReason(body, filteredOut);
+  if (http) return byBody !== void 0 && LIFI_TRANSIENT_REASONS.has(byBody) ? info(byBody) : http;
+  return byBody !== void 0 ? info(byBody) : { reason: "no_route" };
+}
 function cleanChoice(choice) {
   if (!choice) return null;
   const allow = (choice.allowBridges ?? []).filter((t) => TOOL_KEY.test(t));
@@ -771,8 +1007,10 @@ function lifiProvider(config = {}) {
       return !!LIFI_CHAIN[from.chain] && !!LIFI_CHAIN[to.chain];
     },
     async getQuote(params, signal) {
-      const reject = (why) => {
-        params.onRefusal?.(`lifi: ${why}`);
+      const reject = (why, reason) => {
+        const info = typeof reason === "string" ? { reason } : reason;
+        if (info) params.onRefusal?.(`lifi: ${why}`, info);
+        else params.onRefusal?.(`lifi: ${why}`);
         return null;
       };
       if (params.flex) return null;
@@ -783,13 +1021,15 @@ function lifiProvider(config = {}) {
       if (!fromToken) return null;
       const solanaSource = isSolana(params.sourceChain);
       const crossChain = params.sourceChain !== params.destChain;
+      const evmToSolana = !solanaSource && isSolana(params.destChain);
       const noDestinationCall = crossChain && !solanaSource;
       let routeScope = config.routeWideSlippage === true && !solanaSource && !isSolana(params.destChain);
       const dry = params.dry !== false;
       const fromAddress = params.refundAddress || (dry ? solanaSource ? SOLANA_PLACEHOLDER : EVM_PLACEHOLDER : "");
-      const toAddress = params.destAddress || (dry ? fromAddress : "");
+      const toAddress = params.destAddress || (dry ? dryRecipient(params, fromAddress) : "");
       if (!fromAddress) return reject("a live quote needs the sender's address");
       if (!toAddress) return reject("a live quote needs a recipient");
+      const placeholder = dry ? placeholderIn(params) : null;
       const slippageBps = params.slippageBps ?? defaultSlippageBps;
       let sentSlippage = slippageBps / 1e4;
       let deadline;
@@ -810,7 +1050,7 @@ function lifiProvider(config = {}) {
               options: {
                 slippage: slippageBps / 1e4,
                 ...routeScope ? { slippageScope: "route" } : {},
-                ...solanaSource ? {} : { bridges: { deny: UNBOUND_TOOLS } },
+                ...solanaSource ? {} : { bridges: { ...evmToSolana ? { allow: SOLANA_DESTINATION_TOOLS } : {}, deny: REFUSED_EVM_TOOLS } },
                 ...noDestinationCall ? { allowDestinationCall: false } : {},
                 ...integrator().trim() ? { integrator: integrator().trim() } : {}
               }
@@ -818,7 +1058,7 @@ function lifiProvider(config = {}) {
             signal: signal ?? (0, import_util3.timeoutSignal)(8e3)
           });
           if (res.ok) {
-            const options = routeOptions(await res.json(), solanaSource ? [] : UNBOUND_TOOLS);
+            const options = routeOptions(await res.json(), solanaSource ? [] : REFUSED_EVM_TOOLS, evmToSolana ? SOLANA_DESTINATION_TOOLS : void 0);
             if (options.length) choice = cleanChoice(config.chooseRoute(options, params));
           }
         } catch {
@@ -840,8 +1080,10 @@ function lifiProvider(config = {}) {
         }
         if (routeScope) url.searchParams.set("slippageScope", "route");
         if (noDestinationCall) url.searchParams.set("allowDestinationCall", "false");
-        const unbound = crossChain && !solanaSource ? UNBOUND_TOOLS : [];
-        for (const t of (choice?.allowBridges ?? []).filter((b) => solanaSource || !UNBOUND_TOOLS.includes(b))) url.searchParams.append("allowBridges", t);
+        const unbound = crossChain && !solanaSource ? REFUSED_EVM_TOOLS : [];
+        const allow = (choice?.allowBridges ?? []).filter((b) => solanaSource || !REFUSED_EVM_TOOLS.includes(b));
+        const solanaAllow = evmToSolana ? allow.filter((b) => SOLANA_DESTINATION_TOOLS.includes(b)) : [];
+        for (const t of evmToSolana ? solanaAllow.length ? solanaAllow : SOLANA_DESTINATION_TOOLS : allow) url.searchParams.append("allowBridges", t);
         for (const t of /* @__PURE__ */ new Set([...choice?.denyBridges ?? [], ...unbound])) url.searchParams.append("denyBridges", t);
         if (choice?.order) url.searchParams.set("order", choice.order);
         deadline = signal ? void 0 : (0, import_util3.timeoutSignal)(12e3);
@@ -860,18 +1102,28 @@ function lifiProvider(config = {}) {
             continue;
           }
           const why = reasons.length === 1 ? ` (${reasons[0].slice(0, 200)})` : "";
-          params.onRefusal?.(`lifi: ${typeof body?.message === "string" ? body.message.slice(0, 200) : `HTTP ${res.status}`}${why}`);
+          params.onRefusal?.(
+            `lifi: ${typeof body?.message === "string" ? body.message.slice(0, 200) : `HTTP ${res.status}`}${why}`,
+            lifiHttpRefusal(res.status, res.headers?.get?.("retry-after"), body, reasons)
+          );
           return null;
         }
         const q = await res.json();
         const receivedAt = Date.now();
+        if (evmToSolana) {
+          const steps = q.includedSteps;
+          const tools = [q.tool, ...Array.isArray(steps) ? steps.map((i) => i?.tool) : []];
+          if (tools.some((t) => typeof t === "string" && SMART_DEPOSITS_TOOL.test(t))) {
+            return reject("LI.FI Smart Deposits pay a deposit address whose recipient the transaction does not bind \u2014 refused for a Solana destination", "recipient_unverifiable");
+          }
+        }
         const action = q.action;
         const est = q.estimate;
         const tr = q.transactionRequest;
         const expectedToToken = nativeFor(params.destChain, params.destToken);
         const expectedFromChain = Number(fromChain);
         const expectedToChain = Number(toChain);
-        if (q.type !== "lifi" || !q.id || !action || !est?.toAmount || !est.fromAmount || !tr) return reject("incomplete quote (no action, estimate or transaction)");
+        if (q.type !== "lifi" || !q.id || !action || !est?.toAmount || !est.fromAmount || !tr) return reject("incomplete quote (no action, estimate or transaction)", "upstream_unavailable");
         const mismatch = [
           action.fromChainId !== expectedFromChain && "source chain",
           action.toChainId !== expectedToChain && "destination chain",
@@ -881,41 +1133,53 @@ function lifiProvider(config = {}) {
           !sameChainAddress(params.sourceChain, action.fromAddress, fromAddress) && "sender",
           !sameChainAddress(params.destChain, action.toAddress, toAddress) && "recipient"
         ].filter(Boolean);
-        if (mismatch.length) return reject(`quote does not match the request (${mismatch.join(", ")})`);
+        if (mismatch.length) {
+          return reject(
+            `quote does not match the request (${mismatch.join(", ")})`,
+            // LI.FI refunds to the sender it was asked for (fromAddress): either address differing pays or refunds someone else.
+            mismatch.includes("recipient") || mismatch.includes("sender") ? "recipient_mismatch" : "policy_refused"
+          );
+        }
         const bridged = BigInt(est.fromAmount);
         const spent = BigInt(params.amountIn);
-        if (bridged > spent) return reject(`the estimate bridges ${est.fromAmount}, more than the ${params.amountIn} spent`);
+        if (bridged > spent) return reject(`the estimate bridges ${est.fromAmount}, more than the ${params.amountIn} spent`, "price_check_failed");
         if ((spent - bridged) * 10000n > spent * BigInt(MAX_INPUT_FEE_BPS)) {
-          return reject(`the route takes ${(0, import_core.bigintToNumber)((spent - bridged) * 10000n / spent) / 100}% of the input as a fee (over ${MAX_INPUT_FEE_BPS / 100}%)`);
+          return reject(`the route takes ${(0, import_core.bigintToNumber)((spent - bridged) * 10000n / spent) / 100}% of the input as a fee (over ${MAX_INPUT_FEE_BPS / 100}%)`, "policy_refused");
         }
         if (solanaSource) {
-          if (!tr.data || tr.data.length < 64 || tr.data.length % 4 !== 0 || !BASE64.test(tr.data)) return reject("the Solana transaction is not base64");
-          if (tr.to !== void 0 || tr.value !== void 0 || tr.gasLimit !== void 0) return reject("the Solana transaction carries EVM fields");
+          if (!tr.data || tr.data.length < 64 || tr.data.length % 4 !== 0 || !BASE64.test(tr.data)) return reject("the Solana transaction is not base64", "upstream_unavailable");
+          if (tr.to !== void 0 || tr.value !== void 0 || tr.gasLimit !== void 0) return reject("the Solana transaction carries EVM fields", "upstream_unavailable");
           if (fromChain !== toChain) {
             const why = solanaBridgeTxMismatch(tr.data, fromAddress);
-            if (why) return reject(why);
+            if (why) return reject(why, reasonOf(why));
           }
-        } else if (!isHexData(tr.data) || !normalizeAddress(tr.to) || !normalizeAddress(tr.from) || tr.chainId !== expectedFromChain || !tr.value || !tr.gasLimit || !trustedAddress(params.sourceChain, tr.to, trustedTransactionTargets) || !sameAddress(tr.from, fromAddress)) return reject("the transaction is malformed or targets an untrusted contract");
-        if (sentSlippage !== void 0 && (typeof action.slippage !== "number" || Math.abs(action.slippage - sentSlippage) > 1e-12)) return reject("the quote ignored the requested slippage");
+        } else if (!isHexData(tr.data) || !normalizeAddress(tr.to) || !normalizeAddress(tr.from) || tr.chainId !== expectedFromChain || !tr.value || !tr.gasLimit || !trustedAddress(params.sourceChain, tr.to, trustedTransactionTargets) || !sameAddress(tr.from, fromAddress)) {
+          return reject(
+            "the transaction is malformed or targets an untrusted contract",
+            !isHexData(tr.data) || !normalizeAddress(tr.to) || !normalizeAddress(tr.from) || !tr.value || !tr.gasLimit ? "upstream_unavailable" : !trustedAddress(params.sourceChain, tr.to, trustedTransactionTargets) ? "vault_mismatch" : "policy_refused"
+          );
+        }
+        if (sentSlippage !== void 0 && (typeof action.slippage !== "number" || Math.abs(action.slippage - sentSlippage) > 1e-12)) return reject("the quote ignored the requested slippage", "price_check_failed");
         const sourceIsToken = fromToken !== EVM_ZERO && fromToken !== SOLANA_NATIVE;
         if (solanaSource) {
         } else if (sourceIsToken) {
-          if (!trustedAddress(params.sourceChain, est.approvalAddress, trustedApprovalAddresses)) return reject("the approval target is not a trusted LI.FI contract");
+          if (!trustedAddress(params.sourceChain, est.approvalAddress, trustedApprovalAddresses)) return reject("the approval target is not a trusted LI.FI contract", "vault_mismatch");
         } else if (est.approvalAddress !== void 0) {
-          if (!trustedAddress(params.sourceChain, est.approvalAddress, trustedApprovalAddresses)) return reject("the approval target is not a trusted LI.FI contract");
+          if (!trustedAddress(params.sourceChain, est.approvalAddress, trustedApprovalAddresses)) return reject("the approval target is not a trusted LI.FI contract", "vault_mismatch");
         }
         let txRequest;
+        let nativeFee = 0n;
         if (solanaSource) {
           txRequest = { serializedTx: tr.data, value: sourceIsToken ? "0" : params.amountIn };
         } else {
           try {
-            if (BigInt(tr.value) < 0n || BigInt(tr.gasLimit) <= 0n) return reject("the transaction has a negative value or no gas limit");
+            if (BigInt(tr.value) < 0n || BigInt(tr.gasLimit) <= 0n) return reject("the transaction has a negative value or no gas limit", "upstream_unavailable");
           } catch {
-            return reject("the transaction value or gas limit is not a number");
+            return reject("the transaction value or gas limit is not a number", "upstream_unavailable");
           }
           const value = BigInt(tr.value);
-          const nativeFee = sourceIsToken ? value : value > BigInt(params.amountIn) ? value - BigInt(params.amountIn) : 0n;
-          if (!sourceIsToken && value < BigInt(params.amountIn)) return reject("the transaction sends less native coin than the input");
+          nativeFee = sourceIsToken ? value : value > BigInt(params.amountIn) ? value - BigInt(params.amountIn) : 0n;
+          if (!sourceIsToken && value < BigInt(params.amountIn)) return reject("the transaction sends less native coin than the input", "policy_refused");
           txRequest = {
             to: tr.to,
             data: tr.data,
@@ -927,7 +1191,7 @@ function lifiProvider(config = {}) {
           };
         }
         const feeUsd = (est.feeCosts ?? []).reduce((a, f) => a + Number(f.amountUSD ?? 0), 0);
-        if (!est.toAmountMin) return reject("the quote has no minimum output");
+        if (!est.toAmountMin) return reject("the quote has no minimum output", "upstream_unavailable");
         const minDestAmount = est.toAmountMin;
         if (sentSlippage !== void 0) {
           const dest = BigInt(est.toAmount);
@@ -941,18 +1205,22 @@ function lifiProvider(config = {}) {
               continue;
             }
             params.onRefusal?.(
-              `lifi: this route's minimum is ${(effective * 100).toFixed(2)}% under the quote (LI.FI applies slippage on every step) \u2014 more than the requested ${slippageBps / 100}%`
+              `lifi: this route's minimum is ${(effective * 100).toFixed(2)}% under the quote (LI.FI applies slippage on every step) \u2014 more than the requested ${slippageBps / 100}%`,
+              { reason: "price_check_failed" }
             );
             return null;
           }
         }
         if (params.minAmountOut !== void 0 && BigInt(minDestAmount) < BigInt(params.minAmountOut)) {
-          params.onRefusal?.(`lifi: floor breach (min=${minDestAmount} < floor=${params.minAmountOut})`);
+          params.onRefusal?.(`lifi: floor breach (min=${minDestAmount} < floor=${params.minAmountOut})`, { reason: "price_check_failed" });
           return null;
         }
         const duration = est.executionDuration ?? 0;
         if (fromChain === toChain && duration > SAME_CHAIN_MAX_SECONDS) {
-          params.onRefusal?.(`lifi: same-chain route settles asynchronously (${duration} s via ${q.tool ?? "unknown tool"}) \u2014 a same-chain swap must deliver in the same transaction`);
+          params.onRefusal?.(
+            `lifi: same-chain route settles asynchronously (${duration} s via ${q.tool ?? "unknown tool"}) \u2014 a same-chain swap must deliver in the same transaction`,
+            { reason: "unsupported_pair" }
+          );
           return null;
         }
         if (!solanaSource) {
@@ -967,7 +1235,7 @@ function lifiProvider(config = {}) {
             sameChain: fromChain === toChain,
             evmDestination: !isSolana(params.destChain)
           });
-          if (why) return reject(`the transaction does not match the quote: ${why}`);
+          if (why) return reject(`the transaction does not match the quote: ${why}`, reasonOf(why) ?? "policy_refused");
         }
         return {
           provider: "lifi",
@@ -975,7 +1243,10 @@ function lifiProvider(config = {}) {
           intentId: `lifi:${fromChain}:${toChain}`,
           depositAddress: "",
           depositMemo: null,
-          txRequest,
+          // Every check above ran on LI.FI's transaction; one built for a placeholder is not handed out (placeholderIn).
+          // Its bridge fee on top of the input still is, as `providerData.nativeFee`, so the router's value nets it out
+          // (usdValue reads it when there is no txRequest) instead of ranking the route on its gross output.
+          ...placeholder ? { providerData: { placeholder, ...nativeFee > 0n ? { nativeFee: nativeFee.toString() } : {} } } : { txRequest },
           // What the wallet spends (action.fromAmount, = the input); an input-side bridge fee is inside destAmount.
           sourceAmount: params.amountIn,
           destAmount: est.toAmount,
@@ -989,14 +1260,18 @@ function lifiProvider(config = {}) {
           validUntilMs: receivedAt + quoteTtlMs
         };
       } catch {
-        if (deadline?.aborted) params.onRefusal?.("lifi: no quote within 12 s");
+        if (deadline?.aborted) params.onRefusal?.("lifi: no quote within 12 s", { reason: "upstream_unavailable" });
         return null;
       }
       return null;
     },
     async buildDeposit(quote) {
+      const placeholder = quote.providerData?.placeholder;
+      if (placeholder !== void 0) {
+        throw (0, import_errors2.refusal)("policy_refused", `swap2: this LI.FI quote was priced for a placeholder ${String(placeholder).slice(0, 20)} (a dry quote without that address) and has no transaction to build \u2014 quote again with the sender and the recipient`);
+      }
       const tx = quote.txRequest;
-      if (!tx) throw new Error("swap2: LI.FI quote has no transaction request");
+      if (!tx) throw (0, import_errors2.refusal)("policy_refused", "swap2: LI.FI quote has no transaction request");
       const [, fromChain] = quote.intentId.split(":");
       return {
         chain: tx.serializedTx ? CAIP2_BY_LIFI_CHAIN[fromChain ?? ""] ?? "" : "",
@@ -1045,22 +1320,27 @@ function lifiProvider(config = {}) {
 function lifiVerifyQuote(params, quote) {
   const fromChain = LIFI_CHAIN[params.sourceChain];
   const toChain = LIFI_CHAIN[params.destChain];
-  if (!fromChain || !toChain) return "not a LI.FI chain pair";
+  if (!fromChain || !toChain) return note("not a LI.FI chain pair", "unsupported_pair");
+  const placeholder = params.dry !== false ? placeholderIn(params) : null;
+  if (placeholder) {
+    if (quote.txRequest !== void 0) return note(`a dry quote priced for a placeholder ${placeholder} carries a transaction \u2014 it would pay or refund that placeholder, not the wallet that signs it`, "recipient_mismatch");
+    return priceOnlyMismatch(params, quote, `lifi:${fromChain}:${toChain}`);
+  }
   const tx = quote.txRequest;
-  if (!tx) return "the quote carries no transaction";
+  if (!tx) return note("the quote carries no transaction", "policy_refused");
   if (isSolana(params.sourceChain)) {
-    if (!tx.serializedTx || tx.data !== void 0 || tx.to !== void 0) return "a Solana source carries a serialized transaction only";
+    if (!tx.serializedTx || tx.data !== void 0 || tx.to !== void 0) return note("a Solana source carries a serialized transaction only", "policy_refused");
     return fromChain === toChain ? null : solanaBridgeTxMismatch(tx.serializedTx, params.refundAddress || (params.dry !== false ? SOLANA_PLACEHOLDER : ""));
   }
-  if (!isHexData(tx.data) || !tx.to || tx.serializedTx !== void 0) return "the quote carries no Diamond call";
-  if (!sameAddress(tx.to, diamondFor(params.sourceChain))) return `the call targets ${tx.to}, not the LI.FI Diamond`;
-  if (tx.chainId !== void 0 && String(tx.chainId) !== fromChain) return `the call is for chain ${tx.chainId}, not ${fromChain}`;
+  if (!isHexData(tx.data) || !tx.to || tx.serializedTx !== void 0) return note("the quote carries no Diamond call", "policy_refused");
+  if (!sameAddress(tx.to, diamondFor(params.sourceChain))) return note(`the call targets ${tx.to}, not the LI.FI Diamond`, "vault_mismatch");
+  if (tx.chainId !== void 0 && String(tx.chainId) !== fromChain) return note(`the call is for chain ${tx.chainId}, not ${fromChain}`, "policy_refused");
   const fromToken = lifiToken(params);
-  if (!fromToken) return `unknown source token ${params.sourceToken}`;
+  if (!fromToken) return note(`unknown source token ${params.sourceToken}`, "unsupported_pair");
   const sourceIsToken = fromToken !== EVM_ZERO;
   const dry = params.dry !== false;
   const fromAddress = params.refundAddress || (dry ? EVM_PLACEHOLDER : "");
-  const toAddress = params.destAddress || (dry ? fromAddress : "");
+  const toAddress = params.destAddress || (dry ? dryRecipient(params, fromAddress) : "");
   if (!fromAddress || !toAddress) return "a live quote needs the sender and the recipient";
   let amountIn, minOut, value, nativeFee;
   try {
@@ -1069,18 +1349,18 @@ function lifiVerifyQuote(params, quote) {
     value = BigInt(tx.value ?? "0");
     nativeFee = BigInt(tx.nativeFee ?? "0");
   } catch {
-    return "the quote's amounts are not integers";
+    return note("the quote's amounts are not integers", "upstream_unavailable");
   }
-  if (BigInt(quote.sourceAmount) !== amountIn) return `the quote spends ${quote.sourceAmount}, not the ${amountIn} input`;
-  if (params.minAmountOut !== void 0 && minOut < BigInt(params.minAmountOut)) return `the quoted minimum ${minOut} is below the caller's floor ${params.minAmountOut}`;
+  if (BigInt(quote.sourceAmount) !== amountIn) return note(`the quote spends ${quote.sourceAmount}, not the ${amountIn} input`, "policy_refused");
+  if (params.minAmountOut !== void 0 && minOut < BigInt(params.minAmountOut)) return note(`the quoted minimum ${minOut} is below the caller's floor ${params.minAmountOut}`, "price_check_failed");
   if (sourceIsToken) {
-    if (value !== nativeFee) return "a token input attaches only its declared bridge fee";
-    if (!tx.approvalAddress || !sameAddress(tx.approvalAddress, diamondFor(params.sourceChain))) return "a token input approves the LI.FI Diamond";
+    if (value !== nativeFee) return note("a token input attaches only its declared bridge fee", "policy_refused");
+    if (!tx.approvalAddress || !sameAddress(tx.approvalAddress, diamondFor(params.sourceChain))) return note("a token input approves the LI.FI Diamond", "vault_mismatch");
   } else {
-    if (value < amountIn || value - amountIn !== nativeFee) return "a native input is paid as the input plus its declared bridge fee";
-    if (tx.approvalAddress !== void 0) return "a native input approves nothing";
+    if (value < amountIn || value - amountIn !== nativeFee) return note("a native input is paid as the input plus its declared bridge fee", "policy_refused");
+    if (tx.approvalAddress !== void 0) return note("a native input approves nothing", "vault_mismatch");
   }
-  if (quote.intentId.replace(/~[0-9a-f]{32}$/, "") !== `lifi:${fromChain}:${toChain}`) return "the intent id does not name this route";
+  if (quote.intentId.replace(/~[0-9a-f]{32}$/, "") !== `lifi:${fromChain}:${toChain}`) return note("the intent id does not name this route", "policy_refused");
   const why = diamondCallMismatch(tx.data, {
     fromToken,
     toToken: nativeFor(params.destChain, params.destToken),
@@ -1092,12 +1372,27 @@ function lifiVerifyQuote(params, quote) {
     sameChain: fromChain === toChain,
     evmDestination: !isSolana(params.destChain)
   });
-  return why ? `the transaction does not match the request: ${why}` : null;
+  return why ? note(`the transaction does not match the request: ${why}`, reasonOf(why) ?? "policy_refused") : null;
+}
+function priceOnlyMismatch(params, quote, route) {
+  if (quote.depositAddress !== "") return note(`a LI.FI quote pays no deposit address, but this one names ${String(quote.depositAddress).slice(0, 64)}`, "vault_mismatch");
+  const fee = quote.providerData?.nativeFee;
+  if (fee !== void 0 && !/^\d{1,80}$/.test(String(fee))) return note(`the price-only quote declares a native fee of ${String(fee).slice(0, 40)}, not a base-unit integer`, "upstream_unavailable");
+  try {
+    if (BigInt(quote.sourceAmount) !== BigInt(params.amountIn)) return note(`the quote spends ${quote.sourceAmount}, not the ${params.amountIn} input`, "policy_refused");
+    const minOut = BigInt(quote.minDestAmount);
+    if (params.minAmountOut !== void 0 && minOut < BigInt(params.minAmountOut)) return note(`the quoted minimum ${minOut} is below the caller's floor ${params.minAmountOut}`, "price_check_failed");
+  } catch {
+    return note("the quote's amounts are not integers", "upstream_unavailable");
+  }
+  return quote.intentId.replace(/~[0-9a-f]{32}$/, "") === route ? null : note("the intent id does not name this route", "policy_refused");
 }
 var lifiPins = Object.freeze({
   callTargets: (chain) => /^eip155:[0-9]+$/.test(chain) ? [diamondFor(chain)] : [],
   spenders: (chain) => /^eip155:[0-9]+$/.test(chain) ? [diamondFor(chain)] : [],
-  verifyQuote: lifiVerifyQuote
+  verifyQuote: lifiVerifyQuote,
+  /** The reason of a text {@link lifiVerifyQuote} returned (`remoteProvider` puts it on the stub's refusal). */
+  reasonOf: (text) => reasonOf(text)
 });
 
 // src/protocol.ts