@anywalletkit/protocol-swap2-lifi 0.8.0 → 0.8.2

package/dist/protocol.cjs

@@ -137,6 +137,12 @@ function associatedTokenAccount(owner, mint, tokenProgram = solanaKey(SOLANA_TOK
   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 },
@@ -356,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 = {
@@ -408,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 = {
@@ -467,13 +473,13 @@ 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;
 }
@@ -505,36 +511,36 @@ var hexOf = (b) => `0x${Array.from(b, (x) => x.toString(16).padStart(2, "0")).jo
 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 `Mayan's nonEVMReceiver is ${keyOf(declared)}, not the recipient ${t.e.receiver}`;
+  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 `the Mayan call ${selector} is an entry point whose Solana recipient cannot be checked here`;
+  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 `the Mayan call ${selector} carries payload type ${p.word(word(o.payloadType[0]))}, not a plain delivery`;
+  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 `the Mayan order pays ${keyOf(dest)} on Solana, not the recipient ${t.e.receiver}`;
+  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 `the Mayan order goes to ${o.cctp ? "CCTP domain" : "Wormhole chain"} ${chain}, not Solana`;
-  if (o.tokenOut === void 0) return t.e.toToken === SOLANA_USDC ? null : `a Mayan CCTP transfer delivers USDC, not ${t.e.toToken}`;
+  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 : `the Mayan order delivers ${keyOf(token)}, not ${t.e.toToken}`;
+  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 `Polymer CCTP's nonEVMReceiver is ${keyOf(declared)}, not the recipient ${t.e.receiver}`;
-  if (t.e.toToken !== SOLANA_USDC) return `Polymer CCTP delivers USDC, not ${t.e.toToken}`;
+  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 : `the Polymer CCTP transfer mints to ${keyOf(mintTo)}, not the recipient's USDC account ${keyOf(account)}`;
+  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 `Chainflip pays a ${dst.length}-byte address on Solana, not the recipient ${t.e.receiver}`;
-  if (dst.raw(0, 32) !== t.ownerHex) return `Chainflip pays ${keyOf(dst.raw(0, 32))} on Solana, not the recipient ${t.e.receiver}`;
+  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 : `Chainflip delivers its asset ${asset}, not ${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,
@@ -545,16 +551,16 @@ var INTENTS_TO_SOLANA = "a LI.FI Intents order to Solana names its own oracles,
 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 NON_EVM_UNREAD;
-  if (!same(receiver, NON_EVM_ADDRESS)) return `BridgeData pays ${receiver}, not LI.FI's non-EVM placeholder ${NON_EVM_ADDRESS}, on a Solana route`;
-  if (DEPOSIT_FACETS.has(bridge.facet)) return `${bridge.facet} pays a deposit address whose off-chain order names the Solana recipient \u2014 the transaction does not bind it`;
-  if (bridge.facet === INTENTS_FACET) return INTENTS_TO_SOLANA;
+  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 NON_EVM_UNREAD;
+  if (!read) return note(NON_EVM_UNREAD, "recipient_unverifiable");
   const owner = solanaKey(e.receiver);
-  if (!owner) return `the recipient ${e.receiver} is not a Solana address`;
+  if (!owner) return note(`the recipient ${e.receiver} is not a Solana address`, "recipient_mismatch");
   const mint = solanaKey(e.toToken);
-  if (!mint) return `the destination token ${e.toToken} is not a Solana mint`;
+  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) {
@@ -562,61 +568,61 @@ function diamondCallMismatch(data, e) {
   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.facet === INTENTS_FACET && e.evmDestination) return INTENTS_UNPINNED;
+    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.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 `pays ${receiver}, not ${e.receiver}`;
-    if (hasSourceSwaps !== bridge.sourceSwaps) return `unknown Diamond call ${selector}`;
+    } 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");
   }
 }
 
@@ -665,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());
@@ -673,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 = [];
@@ -688,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 = {
@@ -874,6 +881,92 @@ function routeOptions(body, excluded, allowed) {
   }
   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));
@@ -914,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;
@@ -1007,7 +1102,10 @@ 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();
@@ -1016,7 +1114,7 @@ function lifiProvider(config = {}) {
           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");
+            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;
@@ -1025,7 +1123,7 @@ function lifiProvider(config = {}) {
         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",
@@ -1035,28 +1133,39 @@ 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;
@@ -1064,13 +1173,13 @@ function lifiProvider(config = {}) {
           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);
           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");
+          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,
@@ -1082,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);
@@ -1096,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) {
@@ -1122,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",
@@ -1147,7 +1260,7 @@ 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;
@@ -1155,10 +1268,10 @@ function lifiProvider(config = {}) {
     async buildDeposit(quote) {
       const placeholder = quote.providerData?.placeholder;
       if (placeholder !== void 0) {
-        throw new Error(`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`);
+        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 ?? ""] ?? "" : "",
@@ -1207,23 +1320,23 @@ 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 `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`;
+    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 : "");
@@ -1236,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),
@@ -1259,25 +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 `a LI.FI quote pays no deposit address, but this one names ${String(quote.depositAddress).slice(0, 64)}`;
+  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 `the price-only quote declares a native fee of ${String(fee).slice(0, 40)}, not a base-unit integer`;
+  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 `the quote spends ${quote.sourceAmount}, not the ${params.amountIn} input`;
+    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 `the quoted minimum ${minOut} is below the caller's floor ${params.minAmountOut}`;
+    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 "the quote's amounts are not integers";
+    return note("the quote's amounts are not integers", "upstream_unavailable");
   }
-  return quote.intentId.replace(/~[0-9a-f]{32}$/, "") === route ? null : "the intent id does not name this route";
+  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