@anywalletkit/protocol-swap2-thorchain 0.4.0 → 0.4.1

package/dist/protocol.js

@@ -1,7 +1,7 @@
 import {
   ThorchainSwap2Protocol
-} from "./chunk-LP5BU2JS.js";
-import "./chunk-AYP7O2NT.js";
+} from "./chunk-YKA6IYKX.js";
+import "./chunk-EIAXGWNG.js";
 import "./chunk-DIQDMNP7.js";
 import "./chunk-X6XXFQ2M.js";
 export {

package/dist/provider.cjs

@@ -69,10 +69,12 @@ function describeThorchainActivity(tx, ctx) {
 // src/provider.ts
 var import_viem = require("viem");
 var import_util2 = require("@anywalletkit/protocol-swap2-core/util");
+var import_errors2 = require("@anywalletkit/protocol-swap2-core/errors");
 var import_swap2_assets = require("@anywalletkit/swap2-assets");
 var import_core = require("@anywalletkit/core");
 
 // src/confirm.ts
+var import_errors = require("@anywalletkit/protocol-swap2-core/errors");
 var THORNODE_CONFIRM_PATHS = Object.freeze({
   lastblock: "/thorchain/lastblock",
   inboundAddresses: "/thorchain/inbound_addresses",
@@ -95,10 +97,18 @@ function confirmOptions(o) {
   return { maxLagBlocks, timeoutMs };
 }
 var HostUnavailable = class extends Error {
-  constructor(host, reason) {
+  /**
+   * `info` classifies the failure (`refusalOf` reads it back): what the HTTP status says (429 `rate_limited`, 401 / 403
+   * `key_rejected`), else `upstream_unavailable` — unreachable, timed out, a 5xx, redirected or another shape.
+   */
+  constructor(host, reason, info) {
     super(`thorchain: ${host} unavailable (${reason})`);
+    (0, import_errors.withReason)(this, info ?? "upstream_unavailable");
   }
 };
+function statusRefusal(status, retryAfter) {
+  return (0, import_errors.httpRefusal)(status, retryAfter) ?? { reason: "upstream_unavailable", httpStatus: status };
+}
 function paused(entry) {
   return !entry || entry.halted === true || entry.global_trading_paused === true || entry.chain_trading_paused === true;
 }
@@ -144,7 +154,7 @@ async function nodeRead(host, path, clientId, signal, outer) {
     throw new HostUnavailable(host, error instanceof Error ? error.message : "fetch failed");
   }
   if (res.redirected === true || !sameRequestUrl(res.url, url)) throw new HostUnavailable(host, `${path} redirected`);
-  if (!res.ok) throw new HostUnavailable(host, `${path} HTTP ${res.status}`);
+  if (!res.ok) throw new HostUnavailable(host, `${path} HTTP ${res.status}`, statusRefusal(res.status, res.headers?.get?.("retry-after")));
   try {
     return await res.json();
   } catch (error) {
@@ -376,7 +386,7 @@ async function hostGet(host, path, clientId, signal) {
     throw new HostUnavailable(host, error instanceof Error ? error.message : "fetch failed");
   }
   if (res.status >= 500 || res.status === 429 || res.status === 403) {
-    throw new HostUnavailable(host, `HTTP ${res.status}`);
+    throw new HostUnavailable(host, `HTTP ${res.status}`, statusRefusal(res.status, res.headers?.get?.("retry-after")));
   }
   const body = await res.json().catch(() => null);
   return { ok: res.ok, status: res.status, body };
@@ -401,30 +411,53 @@ function belowThorMinimums(amount1e8, inbound, quote) {
   if (min !== void 0 && (!/^\d+$/.test(String(min)) || amount1e8 < BigInt(min))) return "amount below THORChain recommended minimum";
   return null;
 }
+function nodesFailed(failures) {
+  const known = failures.filter((f) => f !== void 0);
+  if (!known.length || known.length !== failures.length) return { reason: "upstream_unavailable" };
+  const combined = (0, import_errors2.combinedRefusal)(known.map((f) => ({ message: "", ...f })));
+  return combined.reason === "no_route" ? { reason: "upstream_unavailable" } : combined;
+}
+function quoteRejection(text, status, bodyless) {
+  if (/emit asset 0 less than price limit/.test(text)) return { reason: "amount_too_small" };
+  if (/emit asset \d+ less than price limit/.test(text)) return { reason: "price_check_failed" };
+  if (/halt|paused/i.test(text)) return { reason: "chain_halted" };
+  if (/dust|too small|not enough [a-z ]*(?:to pay|for) (?:the )?fee/i.test(text)) return { reason: "amount_too_small" };
+  if (/insufficient liquidity|not enough liquidity/i.test(text)) return { reason: "insufficient_liquidity" };
+  if (/pool [^ ]* ?(?:does not exist|doesn't exist|not exist|not found|not available|is not available)|no pool/i.test(text)) return { reason: "unsupported_pair" };
+  if (/rate limit|too many requests/i.test(text)) return { reason: "rate_limited" };
+  if (/api key|unauthori[sz]ed/i.test(text)) return { reason: "key_rejected" };
+  const byStatus = status >= 400 ? (0, import_errors2.httpRefusal)(status) : void 0;
+  if (byStatus) return byStatus;
+  return bodyless ? { reason: "upstream_unavailable", httpStatus: status } : { reason: "no_route" };
+}
 async function inboundAddressesOn(host, clientId) {
   const res = await hostGet(host, "/thorchain/inbound_addresses", clientId);
-  if (!res.ok || !Array.isArray(res.body)) throw new HostUnavailable(host, `inbound_addresses HTTP ${res.status}`);
+  if (!res.ok || !Array.isArray(res.body)) throw new HostUnavailable(host, `inbound_addresses HTTP ${res.status}`, res.ok ? void 0 : statusRefusal(res.status));
   const entries = inboundAddresses(res.body);
   if (!entries) throw new HostUnavailable(host, "inbound_addresses is not a THORNode inbound address list");
   return entries;
 }
-function verifiedMemo(memo, expectedAsset, expectedDestination, expectedRefund, expectedAffiliate, expectedAffiliateBps) {
-  if (memo.includes("|")) return null;
+function verifiedMemo(memo, expectedAsset, expectedDestination, expectedRefund, expectedAffiliate, expectedAffiliateBps, why) {
+  const refused = (reason) => {
+    why?.(reason);
+    return null;
+  };
+  if (memo.includes("|")) return refused("recipient_unverifiable");
   const parts = memo.split(":");
-  if (parts.length !== 4 && parts.length !== 6) return null;
+  if (parts.length !== 4 && parts.length !== 6) return refused("policy_refused");
   const [op, asset, destination, limit, affiliate, bps] = parts;
-  if (op !== "=" || !asset || !/^[A-Za-z0-9._~\-]+$/.test(asset)) return null;
+  if (op !== "=" || !asset || !/^[A-Za-z0-9._~\-]+$/.test(asset)) return refused("policy_refused");
   const expectedTarget = expectedRefund ? `${expectedDestination}/${expectedRefund}` : expectedDestination;
-  if (!sameTarget(destination, expectedTarget)) return null;
+  if (!sameTarget(destination, expectedTarget)) return refused("recipient_mismatch");
   if (parts.length === 6) {
-    if (!expectedAffiliate || affiliate !== expectedAffiliate || bps !== expectedAffiliateBps) return null;
+    if (!expectedAffiliate || affiliate !== expectedAffiliate || bps !== expectedAffiliateBps) return refused("policy_refused");
   } else if (expectedAffiliate || expectedAffiliateBps) {
-    return null;
+    return refused("policy_refused");
   }
   const stream = (limit ?? "").split("/");
-  if (stream.length !== 1 || stream.some((v) => !/^\d+$/.test(v))) return null;
+  if (stream.length !== 1 || stream.some((v) => !/^\d+$/.test(v))) return refused("price_check_failed");
   const floor = BigInt(stream[0] ?? "0");
-  if (floor <= 0n) return null;
+  if (floor <= 0n) return refused("price_check_failed");
   const canonical = `=:${expectedAsset}:${expectedTarget}:${stream.join("/")}${expectedAffiliate ? `:${expectedAffiliate}:${expectedAffiliateBps}` : ""}`;
   return { limit: floor, canonical };
 }
@@ -437,7 +470,7 @@ function thorchainPins(opts = {}) {
   for (const n of nodes) if (!/^https:\/\//i.test(n)) throw new Error("thorchain: thorchainPins nodeUrl must use https");
   const clientId = opts.clientId?.trim() || DEFAULT_CLIENT_ID;
   const { maxLagBlocks, timeoutMs } = confirmOptions(opts);
-  const askNode = async (host, claim) => {
+  const askNode = async (host, claim, failures) => {
     const node = nodeDeadline(timeoutMs);
     const read = (path) => nodeRead(host, path, clientId, node.signal);
     try {
@@ -445,59 +478,71 @@ function thorchainPins(opts = {}) {
       try {
         return { height: head.height, verdict: await vaultVerdict(host, read, head.inbound, claim) };
       } catch (error) {
-        if (error instanceof HostUnavailable) return { height: head.height, verdict: null };
+        if (error instanceof HostUnavailable) {
+          failures.push((0, import_errors2.refusalOf)(error));
+          return { height: head.height, verdict: null };
+        }
         throw error;
       }
     } catch (error) {
-      if (error instanceof HostUnavailable) return null;
+      if (error instanceof HostUnavailable) {
+        failures.push((0, import_errors2.refusalOf)(error));
+        return null;
+      }
       throw error;
     } finally {
       node.clear();
     }
   };
   const routersFor = (chain) => [...THORCHAIN_ROUTERS[chain] ?? [], ...opts.trustedRouters?.[chain] ?? []];
+  const { note, reasonOf } = (0, import_errors2.refusalNotes)();
   return Object.freeze({
     callTargets: routersFor,
     spenders: routersFor,
+    reasonOf,
     // A Tron source is a send to the inbound vault; verifyBuild confirms that vault with two THORNodes (scan 2026-10-28 F9).
     depositAddressRoutes: true,
     async verifyBuild(quote, tx, params) {
-      if (!params) return "the request this quote answered is unknown";
+      if (!params) return note("the request this quote answered is unknown", "policy_refused");
       const src = (0, import_swap2_assets.ccAsset)(params.sourceChain, params.sourceToken);
       const dst = destAsset(params.destChain, params.destToken);
-      if (!src || !dst) return "unknown source or destination asset";
+      if (!src || !dst) return note("unknown source or destination asset", "unsupported_pair");
       const chainId = CHAIN_ID[params.sourceChain];
       let vault, memo, router;
       if (chainId) {
-        if (!tx.data) return "no router calldata";
+        if (!tx.data) return note("no router calldata", "policy_refused");
         let args;
         try {
           const d = (0, import_viem.decodeFunctionData)({ abi: ROUTER_ABI, data: tx.data });
-          if (d.functionName !== "depositWithExpiry") return `${d.functionName} is not depositWithExpiry`;
+          if (d.functionName !== "depositWithExpiry") return note(`${d.functionName} is not depositWithExpiry`, "policy_refused");
           args = d.args;
         } catch {
-          return "the router calldata does not decode";
+          return note("the router calldata does not decode", "policy_refused");
         }
-        if (!args || args.length !== 5) return "the router calldata does not decode";
+        if (!args || args.length !== 5) return note("the router calldata does not decode", "policy_refused");
         router = tx.to;
-        if (!routersFor(params.sourceChain).some((r) => sameTarget(r, router))) return `router ${tx.to} is not pinned`;
+        if (!routersFor(params.sourceChain).some((r) => sameTarget(r, router))) return note(`router ${tx.to} is not pinned`, "vault_mismatch");
         vault = String(args[0]);
         const asset = String(args[1]);
-        if (!sameTarget(asset, src.contract ?? NATIVE)) return `the router call moves ${asset}, not the source asset`;
-        if (BigInt(args[2]) !== BigInt(quote.sourceAmount)) return `the router call moves ${String(args[2])}, not the ${quote.sourceAmount} input`;
+        if (!sameTarget(asset, src.contract ?? NATIVE)) return note(`the router call moves ${asset}, not the source asset`, "policy_refused");
+        if (BigInt(args[2]) !== BigInt(quote.sourceAmount)) return note(`the router call moves ${String(args[2])}, not the ${quote.sourceAmount} input`, "policy_refused");
         memo = String(args[3]);
       } else {
-        if (!tx.memo || tx.value !== quote.sourceAmount) return "the deposit is not a send of the input with a memo";
+        if (!tx.memo || tx.value !== quote.sourceAmount) return note("the deposit is not a send of the input with a memo", "policy_refused");
         vault = tx.to;
         memo = tx.memo;
       }
-      const checked = verifiedMemo(memo, dst.asset, params.destAddress, params.refundAddress ?? "", opts.affiliate ?? "", opts.affiliateBps ?? "");
-      if (!checked) return `the memo does not pay ${params.destAddress} in ${dst.asset} with this app's refund and affiliate`;
-      if (memo !== checked.canonical) return `the memo is not the canonical ${checked.canonical}`;
-      if (checked.limit * 10n ** BigInt(dst.decimals) / 100000000n < BigInt(quote.minDestAmount)) return `the memo's limit ${checked.limit} is below the quoted minimum`;
+      let memoRefusal = "recipient_mismatch";
+      const checked = verifiedMemo(memo, dst.asset, params.destAddress, params.refundAddress ?? "", opts.affiliate ?? "", opts.affiliateBps ?? "", (why) => {
+        memoRefusal = why;
+      });
+      if (!checked) return note(`the memo does not pay ${params.destAddress} in ${dst.asset} with this app's refund and affiliate`, memoRefusal);
+      if (memo !== checked.canonical) return note(`the memo is not the canonical ${checked.canonical}`, "policy_refused");
+      if (checked.limit * 10n ** BigInt(dst.decimals) / 100000000n < BigInt(quote.minDestAmount)) return note(`the memo's limit ${checked.limit} is below the quoted minimum`, "price_check_failed");
       const sourceChain = THOR_CHAIN[params.sourceChain] ?? params.sourceChain;
       const claim = { chain: sourceChain, destChain: THOR_CHAIN[params.destChain] ?? params.destChain, vault, ...router !== void 0 ? { router } : {} };
-      const views = await Promise.all(nodes.map((host) => askNode(host, claim)));
+      const failures = [];
+      const views = await Promise.all(nodes.map((host) => askNode(host, claim, failures)));
       const top = views.reduce((max, v) => v && v.height > max ? v.height : max, -1);
       let agreeing = 0;
       let lagging = false;
@@ -511,20 +556,20 @@ function thorchainPins(opts = {}) {
         if (!v.ok) {
           switch (v.why) {
             case "halted":
-              return `${v.chain} is halted / paused`;
+              return note(`${v.chain} is halted / paused`, "chain_halted");
             case "another-vault":
-              return `a THORNode reports another inbound vault than ${vault}`;
+              return note(`a THORNode reports another inbound vault than ${vault}`, "vault_mismatch");
             case "not-active":
-              return `a THORNode lists the inbound vault as ${v.status}, not ActiveVault`;
+              return note(`a THORNode lists the inbound vault as ${v.status}, not ActiveVault`, "vault_mismatch");
             case "flagged":
-              return `a THORNode's mimir flags the inbound vault as ${v.flag}`;
+              return note(`a THORNode's mimir flags the inbound vault as ${v.flag}`, "vault_mismatch");
             case "another-router":
-              return "a THORNode reports another router";
+              return note("a THORNode reports another router", "vault_mismatch");
           }
         }
         if (++agreeing >= 2) return null;
       }
-      return lagging ? `two THORNodes within ${maxLagBlocks} blocks of the highest THORChain height they report could not confirm the inbound vault (behind or unreachable)` : "two THORNodes could not confirm the inbound vault";
+      return lagging ? note(`two THORNodes within ${maxLagBlocks} blocks of the highest THORChain height they report could not confirm the inbound vault (behind or unreachable)`, "stale_node") : note("two THORNodes could not confirm the inbound vault", nodesFailed(failures));
     }
   });
 }
@@ -605,15 +650,15 @@ function thorchainProvider(config = {}) {
   const confirmText = (v) => {
     switch (v.why) {
       case "halted":
-        return `${v.chain} is halted / paused on the confirming node`;
+        return { text: `${v.chain} is halted / paused on the confirming node`, info: { reason: "chain_halted" } };
       case "another-vault":
-        return "a second node reports another inbound vault \u2014 refused until they agree";
+        return { text: "a second node reports another inbound vault \u2014 refused until they agree", info: { reason: "vault_mismatch" } };
       case "not-active":
-        return `a second node lists the inbound vault as ${v.status}, not ActiveVault \u2014 refused`;
+        return { text: `a second node lists the inbound vault as ${v.status}, not ActiveVault \u2014 refused`, info: { reason: "vault_mismatch" } };
       case "flagged":
-        return `a second node's mimir flags the inbound vault as ${v.flag} \u2014 refused`;
+        return { text: `a second node's mimir flags the inbound vault as ${v.flag} \u2014 refused`, info: { reason: "vault_mismatch" } };
       case "another-router":
-        return "a second node reports another router \u2014 refused until they agree";
+        return { text: "a second node reports another router \u2014 refused until they agree", info: { reason: "vault_mismatch" } };
     }
   };
   const confirmOn = async (host, signal, outer, quoteHeight, claim) => {
@@ -632,10 +677,14 @@ function thorchainProvider(config = {}) {
     };
     let lagging = false;
     let asked = 0;
+    const failures = [];
     for (const host of confirmHosts) {
       if (host === quoteHost) continue;
       const budget = Math.min(confirmTimeoutMs, deadlineAt - Date.now());
-      if (budget < MIN_CONFIRM_TIMEOUT_MS) break;
+      if (budget < MIN_CONFIRM_TIMEOUT_MS) {
+        failures.push({ reason: "upstream_unavailable" });
+        break;
+      }
       asked++;
       const node = nodeDeadline(budget, outer);
       try {
@@ -647,19 +696,22 @@ function thorchainProvider(config = {}) {
         return verdict;
       } catch (error) {
         if (outer?.aborted) throw error;
-        if (error instanceof HostUnavailable) continue;
+        if (error instanceof HostUnavailable) {
+          failures.push((0, import_errors2.refusalOf)(error));
+          continue;
+        }
         throw error;
       } finally {
         node.clear();
       }
     }
     if (lagging) {
-      return `no confirming node is within ${confirmMaxLagBlocks} blocks of the quoting node's THORChain height (behind or unreachable) \u2014 refused until one catches up`;
+      return { text: `no confirming node is within ${confirmMaxLagBlocks} blocks of the quoting node's THORChain height (behind or unreachable) \u2014 refused until one catches up`, info: { reason: "stale_node" } };
     }
     if (asked === 0) {
-      return `the ${CONFIRM_BUDGET_MS / 1e3} s confirmation budget ran out before a second node could be asked to confirm the inbound vault \u2014 retry`;
+      return { text: `the ${CONFIRM_BUDGET_MS / 1e3} s confirmation budget ran out before a second node could be asked to confirm the inbound vault \u2014 retry`, info: { reason: "upstream_unavailable" } };
     }
-    return "no second node answered to confirm the inbound vault (configure confirmNodeUrl)";
+    return { text: "no second node answered to confirm the inbound vault (configure confirmNodeUrl)", info: nodesFailed(failures) };
   };
   const configuredAffiliate = config.affiliate ?? "";
   const configuredAffiliateBps = config.affiliateBps ?? "";
@@ -705,24 +757,27 @@ function thorchainProvider(config = {}) {
       const fromAsset = thorAsset(params.sourceChain, params.sourceToken);
       const dst = destAsset(params.destChain, params.destToken);
       if (!src || !fromAsset || !dst || fromAsset === dst.asset) {
-        params.onRefusal?.(`thorchain: no pool for ${params.sourceToken} on ${params.sourceChain} \u2192 ${params.destToken} on ${params.destChain}`);
+        params.onRefusal?.(`thorchain: no pool for ${params.sourceToken} on ${params.sourceChain} \u2192 ${params.destToken} on ${params.destChain}`, { reason: "unsupported_pair" });
         return null;
       }
       const amountIn = BigInt(params.amountIn);
       const amount1e8 = amountIn * 100000000n / 10n ** BigInt(src.decimals);
       if (amount1e8 <= 0n) return null;
       if (amount1e8 * 10n ** BigInt(src.decimals) !== amountIn * 100000000n) {
-        params.onRefusal?.(`thorchain: amount has more precision than THORChain's 8 decimals \u2014 round it to 8 decimals`);
+        params.onRefusal?.(`thorchain: amount has more precision than THORChain's 8 decimals \u2014 round it to 8 decimals`, { reason: "policy_refused" });
         return null;
       }
       const requestedTolerance = params.slippageBps ?? Number(TOLERANCE_BPS);
       if (!Number.isInteger(requestedTolerance) || requestedTolerance < 0 || requestedTolerance > (0, import_core.bigintToNumber)(MAX_TOLERANCE_BPS)) {
-        params.onRefusal?.(`thorchain: slippage ${String(params.slippageBps)} bps is outside 0\u2013${MAX_TOLERANCE_BPS} bps`);
+        params.onRefusal?.(`thorchain: slippage ${String(params.slippageBps)} bps is outside 0\u2013${MAX_TOLERANCE_BPS} bps`, { reason: "policy_refused" });
         return null;
       }
       const explicitSlippage = params.slippageBps !== void 0;
       const liquidityBps = explicitSlippage ? dst.decimals > 8 ? requestedTolerance - 1 : requestedTolerance : 0;
       const limitMode = liquidityBps > 0 ? "liquidity_tolerance_bps" : "tolerance_bps";
+      let quoteStatus = 0;
+      let quoteBodyless = false;
+      let quoteBodyAborted = false;
       const quoteOn = async (host, bps, limitMode2 = "tolerance_bps") => {
         const qs = new URLSearchParams({
           from_asset: fromAsset,
@@ -743,6 +798,9 @@ function thorchainProvider(config = {}) {
         }
         if (params.refundAddress) qs.set("refund_address", params.refundAddress);
         const res = await hostGet(host, `/thorchain/quote/swap?${qs.toString()}`, clientId, signal);
+        quoteStatus = res.status;
+        quoteBodyless = res.body === null && !res.ok;
+        quoteBodyAborted = res.body === null && signal?.aborted === true;
         if (Array.isArray(res.body)) return null;
         return res.body ?? (res.ok ? null : { error: `HTTP ${res.status}` });
       };
@@ -753,13 +811,14 @@ function thorchainProvider(config = {}) {
       let quoteHeight = 0;
       let confirmDeadlineAt = 0;
       let heightUnavailable = false;
+      const hostFailures = [];
       for (const host of hosts) {
         try {
           if (limitMode === "liquidity_tolerance_bps") {
             q = await quoteOn(host, String(liquidityBps), "liquidity_tolerance_bps");
             const feeBps = Number(q?.fees?.total_bps);
             if (Number.isFinite(feeBps) && feeBps > (0, import_core.bigintToNumber)(MAX_TOLERANCE_BPS)) {
-              params.onRefusal?.(`thorchain: THORChain fees ${(feeBps / 100).toFixed(2)}% \u2014 too expensive at this amount (cap ${(0, import_core.bigintToNumber)(MAX_TOLERANCE_BPS) / 100}%)`);
+              params.onRefusal?.(`thorchain: THORChain fees ${(feeBps / 100).toFixed(2)}% \u2014 too expensive at this amount (cap ${(0, import_core.bigintToNumber)(MAX_TOLERANCE_BPS) / 100}%)`, { reason: "policy_refused" });
               return null;
             }
           } else {
@@ -776,25 +835,28 @@ function thorchainProvider(config = {}) {
             }
           }
           if (q?.error || q?.message) {
-            params.onRefusal?.(`thorchain: ${String(q.error ?? q.message).slice(0, 200)}`);
+            params.onRefusal?.(`thorchain: ${String(q.error ?? q.message).slice(0, 200)}`, quoteBodyAborted ? (0, import_errors2.httpRefusal)(quoteStatus) : quoteRejection(String(q.error ?? q.message), quoteStatus, quoteBodyless));
             return null;
           }
           if (!q || !q.expected_amount_out || !q.inbound_address || !q.memo || !q.expiry) {
-            params.onRefusal?.(`thorchain: incomplete quote from ${host} (expected_amount_out / inbound_address / memo / expiry missing)`);
+            params.onRefusal?.(`thorchain: incomplete quote from ${host} (expected_amount_out / inbound_address / memo / expiry missing)`, quoteBodyAborted ? void 0 : { reason: "upstream_unavailable", ...quoteStatus >= 300 ? { httpStatus: quoteStatus } : {} });
             return null;
           }
           if (chainId ? !q.router : !!q.router) {
-            params.onRefusal?.(chainId ? "thorchain: quote has no router for an EVM source" : "thorchain: quote names a router for a deposit source \u2014 execution model changed");
+            params.onRefusal?.(chainId ? "thorchain: quote has no router for an EVM source" : "thorchain: quote names a router for a deposit source \u2014 execution model changed", { reason: chainId ? "upstream_unavailable" : "policy_refused" });
             return null;
           }
-          checkedMemo = verifiedMemo(q.memo, dst.asset, params.destAddress, params.refundAddress ?? "", configuredAffiliate, configuredAffiliateBps);
+          let memoRefusal = "recipient_mismatch";
+          checkedMemo = verifiedMemo(q.memo, dst.asset, params.destAddress, params.refundAddress ?? "", configuredAffiliate, configuredAffiliateBps, (why) => {
+            memoRefusal = why;
+          });
           if (!checkedMemo) {
-            params.onRefusal?.(`thorchain: memo failed verification (${String(q.memo).slice(0, 80)})`);
+            params.onRefusal?.(`thorchain: memo failed verification (${String(q.memo).slice(0, 80)})`, { reason: memoRefusal });
             return null;
           }
           const floor1e8 = params.minAmountOut !== void 0 ? toThorUnitsCeil(BigInt(params.minAmountOut), dst.decimals) : void 0;
           if (floor1e8 !== void 0 && checkedMemo.limit < floor1e8) {
-            params.onRefusal?.(`thorchain: floor breach (limit=${checkedMemo.limit} < floor=${floor1e8}, 1e8 units)`);
+            params.onRefusal?.(`thorchain: floor breach (limit=${checkedMemo.limit} < floor=${floor1e8}, 1e8 units)`, { reason: "price_check_failed" });
             return null;
           }
           const deadlineAt = Date.now() + CONFIRM_BUDGET_MS;
@@ -810,6 +872,7 @@ function thorchainProvider(config = {}) {
           break;
         } catch (error) {
           if (error instanceof HostUnavailable) {
+            hostFailures.push((0, import_errors2.refusalOf)(error));
             q = null;
             checkedMemo = null;
             inbounds = null;
@@ -820,7 +883,8 @@ function thorchainProvider(config = {}) {
       }
       if (!q?.expected_amount_out || !q.inbound_address || !q.expiry || !checkedMemo || !inbounds) {
         params.onRefusal?.(
-          inbounds ? "thorchain: no quote from any node" : heightUnavailable ? "thorchain: THORChain height (/thorchain/lastblock) unavailable from every node that answered the inbound addresses" : "thorchain: inbound addresses unavailable from every node"
+          inbounds ? "thorchain: no quote from any node" : heightUnavailable ? "thorchain: THORChain height (/thorchain/lastblock) unavailable from every node that answered the inbound addresses" : "thorchain: inbound addresses unavailable from every node",
+          inbounds ? { reason: "no_route" } : nodesFailed(hostFailures)
         );
         return null;
       }
@@ -828,19 +892,19 @@ function thorchainProvider(config = {}) {
       const srcInbound = inbounds.find((entry) => entry.chain === THOR_CHAIN[params.sourceChain]);
       const dstInbound = inbounds.find((entry) => entry.chain === THOR_CHAIN[params.destChain]);
       if (paused(srcInbound) || paused(dstInbound)) {
-        params.onRefusal?.(`thorchain: ${paused(srcInbound) ? THOR_CHAIN[params.sourceChain] : THOR_CHAIN[params.destChain]} chain is halted / paused on THORChain`);
+        params.onRefusal?.(`thorchain: ${paused(srcInbound) ? THOR_CHAIN[params.sourceChain] : THOR_CHAIN[params.destChain]} chain is halted / paused on THORChain`, { reason: "chain_halted" });
         return null;
       }
       if (!sameTarget(srcInbound?.address, q.inbound_address)) {
-        params.onRefusal?.("thorchain: quote inbound address differs from the node's current inbound (vault rotated) \u2014 retry");
+        params.onRefusal?.("thorchain: quote inbound address differs from the node's current inbound (vault rotated) \u2014 retry", { reason: "vault_mismatch" });
         return null;
       }
       if (chainId && !sameTarget(srcInbound?.router, q.router)) {
-        params.onRefusal?.("thorchain: quote router differs from the node's current router \u2014 retry");
+        params.onRefusal?.("thorchain: quote router differs from the node's current router \u2014 retry", { reason: "vault_mismatch" });
         return null;
       }
       if (chainId && !pinnedRouter(params.sourceChain, q.router)) {
-        params.onRefusal?.(`thorchain: router ${String(q.router)} is not a THORChain router this module trusts on ${params.sourceChain} (THORCHAIN_ROUTERS / trustedRouters)`);
+        params.onRefusal?.(`thorchain: router ${String(q.router)} is not a THORChain router this module trusts on ${params.sourceChain} (THORCHAIN_ROUTERS / trustedRouters)`, { reason: "vault_mismatch" });
         return null;
       }
       const unconfirmed = await confirmedElsewhere(
@@ -854,36 +918,36 @@ function thorchainProvider(config = {}) {
         signal
       );
       if (unconfirmed) {
-        params.onRefusal?.(`thorchain: ${unconfirmed}`);
+        params.onRefusal?.(`thorchain: ${unconfirmed.text}`, unconfirmed.info);
         return null;
       }
       const tooSmall = belowThorMinimums(amount1e8, srcInbound, q);
       if (tooSmall) {
-        params.onRefusal?.(`thorchain: ${tooSmall}`);
+        params.onRefusal?.(`thorchain: ${tooSmall}`, { reason: "amount_too_small" });
         return null;
       }
       const outUnits = BigInt(q.expected_amount_out) * 10n ** BigInt(dst.decimals) / 100000000n;
       if (outUnits <= 0n) {
-        params.onRefusal?.("thorchain: expected output rounds to zero");
+        params.onRefusal?.("thorchain: expected output rounds to zero", { reason: "amount_too_small" });
         return null;
       }
       const memoMinUnits = limit1e8 * 10n ** BigInt(dst.decimals) / 100000000n;
       const minUnits = memoMinUnits;
       if (minUnits <= 0n || minUnits > outUnits) {
-        params.onRefusal?.(`thorchain: memo limit ${limit1e8} inconsistent with expected output ${q.expected_amount_out}`);
+        params.onRefusal?.(`thorchain: memo limit ${limit1e8} inconsistent with expected output ${q.expected_amount_out}`, { reason: "price_check_failed" });
         return null;
       }
       if (params.slippageBps !== void 0) {
         const slippageFloor = outUnits * BigInt(1e4 - params.slippageBps) / 10000n;
         if (minUnits < slippageFloor) {
-          params.onRefusal?.(`thorchain: memo limit ${limit1e8} is below expected ${q.expected_amount_out} minus ${params.slippageBps} bps slippage (1e8 units)`);
+          params.onRefusal?.(`thorchain: memo limit ${limit1e8} is below expected ${q.expected_amount_out} minus ${params.slippageBps} bps slippage (1e8 units)`, { reason: "price_check_failed" });
           return null;
         }
       }
       const nowSeconds = Math.floor(Date.now() / 1e3);
       const executionExpiry = Math.min(q.expiry, nowSeconds + 15 * 60);
       if (!Number.isInteger(executionExpiry) || executionExpiry <= nowSeconds + 30) {
-        params.onRefusal?.(`thorchain: quote expires in ${Number.isInteger(executionExpiry) ? executionExpiry - nowSeconds : "?"} s \u2014 too soon to execute`);
+        params.onRefusal?.(`thorchain: quote expires in ${Number.isInteger(executionExpiry) ? executionExpiry - nowSeconds : "?"} s \u2014 too soon to execute`, { reason: "quote_expired" });
         return null;
       }
       const assetAddr = src.contract ? src.contract : NATIVE;
@@ -939,7 +1003,7 @@ function thorchainProvider(config = {}) {
       if (!quote.txRequest) {
         const sourceChain = quote.providerData?.sourceChain ?? "";
         if (!isDepositSource(sourceChain) || !quote.depositAddress || !quote.depositMemo) {
-          throw new Error("thorchain: deposit-address execution is only supported for an opted-in Tron source");
+          throw (0, import_errors2.refusal)("unsupported_pair", "thorchain: deposit-address execution is only supported for an opted-in Tron source");
         }
         return { chain: sourceChain, to: quote.depositAddress, value: quote.sourceAmount, memo: quote.depositMemo };
       }
@@ -956,26 +1020,28 @@ function thorchainProvider(config = {}) {
     async preflightDeposit(quote, tx) {
       const data = quote.providerData;
       if (!data?.sourceChain || !data.destChain || !data.inboundAddress || !data.assetAddress || !data.expiry || !data.memo) {
-        throw new Error("thorchain: quote is missing execution-bound metadata");
+        throw (0, import_errors2.refusal)("policy_refused", "thorchain: quote is missing execution-bound metadata");
       }
       const evmSource = CHAIN_ID[data.sourceChain] !== void 0;
-      if (evmSource && !data.router) throw new Error("thorchain: quote is missing execution-bound metadata");
-      if (!evmSource && !isDepositSource(data.sourceChain)) throw new Error("thorchain: source chain has no executor");
+      if (evmSource && !data.router) throw (0, import_errors2.refusal)("policy_refused", "thorchain: quote is missing execution-bound metadata");
+      if (!evmSource && !isDepositSource(data.sourceChain)) throw (0, import_errors2.refusal)("unsupported_pair", "thorchain: source chain has no executor");
       if (!/^\d+$/.test(data.expiry) || BigInt(data.expiry) <= BigInt(Math.floor(Date.now() / 1e3))) {
-        throw new Error("thorchain: quote expired before broadcast");
+        throw (0, import_errors2.refusal)("quote_expired", "thorchain: quote expired before broadcast");
       }
-      if (evmSource && !pinnedRouter(data.sourceChain, data.router)) throw new Error("thorchain: the quote's router is not one this module trusts");
+      if (evmSource && !pinnedRouter(data.sourceChain, data.router)) throw (0, import_errors2.refusal)("vault_mismatch", "thorchain: the quote's router is not one this module trusts");
       let inbounds = null;
       let snapshotHost = "";
       let snapshotHeight = 0;
       let confirmDeadlineAt = 0;
       let heightUnavailable = false;
+      const hostFailures = [];
       for (const host of hosts) {
         const deadlineAt = Date.now() + CONFIRM_BUDGET_MS;
         try {
           const snapshot = await nodeSnapshot(host);
           if ("heightError" in snapshot) {
             heightUnavailable = true;
+            hostFailures.push((0, import_errors2.refusalOf)(snapshot.heightError));
             continue;
           }
           inbounds = snapshot.inbounds;
@@ -986,12 +1052,13 @@ function thorchainProvider(config = {}) {
         } catch (error) {
           inbounds = null;
           if (!(error instanceof HostUnavailable)) throw error;
+          hostFailures.push((0, import_errors2.refusalOf)(error));
         }
       }
       if (!inbounds) {
-        throw new Error(
+        throw (0, import_errors2.withReason)(new Error(
           heightUnavailable ? "thorchain: cannot read THORChain height (/thorchain/lastblock) before broadcast from any node that answered the inbound addresses" : "thorchain: cannot refresh inbound addresses before broadcast"
-        );
+        ), nodesFailed(hostFailures));
       }
       const confirm = async () => {
         const unconfirmed = await confirmedElsewhere(
@@ -1003,44 +1070,46 @@ function thorchainProvider(config = {}) {
           evmSource ? data.router : void 0,
           confirmDeadlineAt
         );
-        if (unconfirmed) throw new Error(`thorchain: ${unconfirmed}`);
+        if (unconfirmed) throw (0, import_errors2.withReason)(new Error(`thorchain: ${unconfirmed.text}`), unconfirmed.info);
       };
       const src = inbounds.find((entry) => entry.chain === THOR_CHAIN[data.sourceChain]);
       const dst = inbounds.find((entry) => entry.chain === THOR_CHAIN[data.destChain]);
-      if (paused(src) || paused(dst)) throw new Error("thorchain: source or destination chain trading is paused");
-      if (!sameTarget(src?.address, data.inboundAddress)) throw new Error("thorchain: inbound vault rotated after quote");
+      if (paused(src) || paused(dst)) throw (0, import_errors2.refusal)("chain_halted", "thorchain: source or destination chain trading is paused");
+      if (!sameTarget(src?.address, data.inboundAddress)) throw (0, import_errors2.refusal)("vault_mismatch", "thorchain: inbound vault rotated after quote");
       if (!evmSource) {
         if (tx.data !== void 0 || tx.approvalAddress !== void 0 || tx.bodyBoc !== void 0 || tx.typedData !== void 0 || tx.serializedTx !== void 0 || tx.stateInitBoc !== void 0) {
-          throw new Error("thorchain: deposit-address execution must be a plain send with memo");
+          throw (0, import_errors2.refusal)("policy_refused", "thorchain: deposit-address execution must be a plain send with memo");
         }
         if (!sameTarget(tx.to, data.inboundAddress) || tx.memo !== data.memo || tx.value !== quote.sourceAmount || tx.chain && tx.chain !== data.sourceChain) {
-          throw new Error("thorchain: deposit does not match the validated quote");
+          throw (0, import_errors2.refusal)(!sameTarget(tx.to, data.inboundAddress) ? "vault_mismatch" : "policy_refused", "thorchain: deposit does not match the validated quote");
         }
         const srcAsset = (0, import_swap2_assets.ccAssetByToken)(data.sourceChain, sameTarget(data.assetAddress, NATIVE) ? "" : data.assetAddress);
-        if (!srcAsset) throw new Error("thorchain: unknown source asset");
+        if (!srcAsset) throw (0, import_errors2.refusal)("unsupported_pair", "thorchain: unknown source asset");
         const amount1e8 = BigInt(quote.sourceAmount) * 100000000n / 10n ** BigInt(srcAsset.decimals);
         const tooSmall = belowThorMinimums(amount1e8, src, null);
-        if (tooSmall) throw new Error(`thorchain: ${tooSmall}`);
+        if (tooSmall) throw (0, import_errors2.refusal)("amount_too_small", `thorchain: ${tooSmall}`);
         await confirm();
         return;
       }
       if (!sameTarget(src?.router, data.router) || !sameTarget(tx.to, data.router)) {
-        throw new Error("thorchain: router rotated after quote");
+        throw (0, import_errors2.refusal)("vault_mismatch", "thorchain: router rotated after quote");
       }
-      if (!tx.data) throw new Error("thorchain: missing depositWithExpiry calldata");
+      if (!tx.data) throw (0, import_errors2.refusal)("policy_refused", "thorchain: missing depositWithExpiry calldata");
       let decoded;
       try {
         decoded = (0, import_viem.decodeFunctionData)({ abi: ROUTER_ABI, data: tx.data });
       } catch {
-        throw new Error("thorchain: malformed depositWithExpiry calldata");
+        throw (0, import_errors2.refusal)("policy_refused", "thorchain: malformed depositWithExpiry calldata");
       }
       const args = decoded.args;
       if (decoded.functionName !== "depositWithExpiry" || !args || args.length !== 5 || !sameTarget(String(args[0]), data.inboundAddress) || !sameTarget(String(args[1]), data.assetAddress) || BigInt(args[2]) !== BigInt(quote.sourceAmount) || String(args[3]) !== data.memo || BigInt(args[4]) !== BigInt(data.expiry) || tx.chainId !== CHAIN_ID[data.sourceChain]) {
-        throw new Error("thorchain: calldata does not match the validated quote");
+        const vaultChanged = decoded.functionName === "depositWithExpiry" && !!args && args.length === 5 && !sameTarget(String(args[0]), data.inboundAddress);
+        throw (0, import_errors2.refusal)(vaultChanged ? "vault_mismatch" : "policy_refused", "thorchain: calldata does not match the validated quote");
       }
       const tokenSource = !sameTarget(data.assetAddress, NATIVE);
       if (tx.value !== (tokenSource ? "0" : quote.sourceAmount) || (tokenSource ? !sameTarget(tx.approvalAddress, data.router) : tx.approvalAddress !== void 0)) {
-        throw new Error("thorchain: value/approval does not match the validated source asset");
+        const spenderChanged = tokenSource && tx.approvalAddress !== void 0 && !sameTarget(tx.approvalAddress, data.router);
+        throw (0, import_errors2.refusal)(spenderChanged ? "vault_mismatch" : "policy_refused", "thorchain: value/approval does not match the validated source asset");
       }
       await confirm();
     },