@anywalletkit/protocol-swap2-thorchain 0.3.5 → 0.4.1

package/dist/protocol.cjs

@@ -67,8 +67,212 @@ 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",
+  asgardVaults: "/thorchain/vaults/asgard",
+  mimir: "/thorchain/mimir"
+});
+var DEFAULT_CONFIRM_MAX_LAG_BLOCKS = 50;
+var DEFAULT_CONFIRM_TIMEOUT_MS = 2500;
+var MIN_CONFIRM_TIMEOUT_MS = 100;
+var MAX_CONFIRM_TIMEOUT_MS = 8e3;
+function confirmOptions(o) {
+  const maxLagBlocks = o.confirmMaxLagBlocks ?? DEFAULT_CONFIRM_MAX_LAG_BLOCKS;
+  if (!Number.isInteger(maxLagBlocks) || maxLagBlocks < 0 || maxLagBlocks > 1e5) {
+    throw new Error("thorchain: confirmMaxLagBlocks must be an integer between 0 and 100000");
+  }
+  const timeoutMs = o.confirmTimeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < MIN_CONFIRM_TIMEOUT_MS || timeoutMs > MAX_CONFIRM_TIMEOUT_MS) {
+    throw new Error(`thorchain: confirmTimeoutMs must be an integer between ${MIN_CONFIRM_TIMEOUT_MS} and ${MAX_CONFIRM_TIMEOUT_MS}`);
+  }
+  return { maxLagBlocks, timeoutMs };
+}
+var HostUnavailable = class extends Error {
+  /**
+   * `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;
+}
+function sameTarget(a, b) {
+  if (typeof a !== "string" || typeof b !== "string" || !a || !b) return false;
+  return a.startsWith("0x") || b.startsWith("0x") ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+function nodeDeadline(ms, outer) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), Math.max(0, ms));
+  const onAbort = () => ctrl.abort();
+  if (outer) {
+    if (outer.aborted) ctrl.abort();
+    else outer.addEventListener("abort", onAbort);
+  }
+  return {
+    signal: ctrl.signal,
+    clear() {
+      clearTimeout(timer);
+      outer?.removeEventListener("abort", onAbort);
+      if (!ctrl.signal.aborted) ctrl.abort();
+    }
+  };
+}
+function sameRequestUrl(actual, expected) {
+  if (actual === void 0 || actual === null || actual === "") return true;
+  if (typeof actual !== "string") return false;
+  try {
+    const a = new URL(actual);
+    const e = new URL(expected);
+    return a.origin === e.origin && a.pathname === e.pathname && a.search === "" && a.hash === "";
+  } catch {
+    return false;
+  }
+}
+async function nodeRead(host, path, clientId, signal, outer) {
+  const url = `${host}${path}`;
+  let res;
+  try {
+    res = await fetch(url, { method: "GET", headers: { accept: "application/json", "x-client-id": clientId }, redirect: "error", signal });
+  } catch (error) {
+    if (outer?.aborted) throw error;
+    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}`, statusRefusal(res.status, res.headers?.get?.("retry-after")));
+  try {
+    return await res.json();
+  } catch (error) {
+    if (outer?.aborted) throw error;
+    throw new HostUnavailable(host, `${path} is not JSON`);
+  }
+}
+function int64(v) {
+  if (typeof v === "number") return Number.isSafeInteger(v) ? v : null;
+  if (typeof v === "string" && /^-?\d{1,15}$/.test(v)) return Number(v);
+  return null;
+}
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var INBOUND_STRINGS = ["address", "router", "dust_threshold"];
+var INBOUND_FLAGS = ["halted", "global_trading_paused", "chain_trading_paused"];
+function inboundAddresses(body) {
+  if (!Array.isArray(body)) return null;
+  const out = [];
+  for (const e of body) {
+    if (!isObject(e) || typeof e.chain !== "string") return null;
+    const entry = { chain: e.chain };
+    for (const k of INBOUND_STRINGS) {
+      const v = e[k];
+      if (v === void 0) continue;
+      if (typeof v !== "string") return null;
+      entry[k] = v;
+    }
+    for (const k of INBOUND_FLAGS) {
+      const v = e[k];
+      if (v === void 0) continue;
+      if (typeof v !== "boolean") return null;
+      entry[k] = v;
+    }
+    out.push(entry);
+  }
+  return out;
+}
+function lastblockHeight(body) {
+  if (!Array.isArray(body) || body.length === 0) return null;
+  let height = -1;
+  for (const entry of body) {
+    if (!isObject(entry)) return null;
+    const h = int64(entry.thorchain);
+    if (h === null || h < 0) return null;
+    if (h > height) height = h;
+  }
+  return height;
+}
+function asgardVaults(body) {
+  if (!Array.isArray(body)) return null;
+  const out = [];
+  for (const v of body) {
+    if (!isObject(v)) return null;
+    if (typeof v.status !== "string" || typeof v.pub_key !== "string" || !/^thorpub1[0-9a-z]{20,}$/.test(v.pub_key)) return null;
+    if (v.type !== void 0 && v.type !== "AsgardVault") return null;
+    if (!Array.isArray(v.addresses)) return null;
+    const addresses = [];
+    for (const a of v.addresses) {
+      if (!isObject(a) || typeof a.chain !== "string" || typeof a.address !== "string") return null;
+      addresses.push({ chain: a.chain, address: a.address });
+    }
+    out.push({ pubKey: v.pub_key, status: v.status, addresses });
+  }
+  return out;
+}
+function mimirFlags(body) {
+  if (!isObject(body) || Object.keys(body).length === 0) return null;
+  const keys = Object.keys(body).map((k) => [k.toUpperCase(), body[k]]);
+  if (keys.some(([, value]) => typeof value !== "number" && typeof value !== "string")) return null;
+  return (pubKey) => {
+    const pub = pubKey.toUpperCase();
+    const compromisedKey = `COMPROMISEDVAULT-${pub}`;
+    const insolventPrefix = `SOLVENCYHALTVAULT-${pub}-`;
+    let flag = null;
+    for (const [key, value] of keys) {
+      const kind = key === compromisedKey ? "compromised" : key.startsWith(insolventPrefix) ? "insolvent" : null;
+      if (!kind) continue;
+      const n = int64(value);
+      if (n === null) return "malformed";
+      if (n > 0 && flag !== "compromised") flag = kind;
+    }
+    return flag;
+  };
+}
+async function nodeHead(host, read) {
+  const [lastblock, inbound] = await Promise.all([read(THORNODE_CONFIRM_PATHS.lastblock), read(THORNODE_CONFIRM_PATHS.inboundAddresses)]);
+  const height = lastblockHeight(lastblock);
+  if (height === null) throw new HostUnavailable(host, "lastblock is not a THORNode lastblock list");
+  return { height, inbound };
+}
+async function vaultVerdict(host, read, inbound, claim) {
+  if (!Array.isArray(inbound)) throw new HostUnavailable(host, "inbound_addresses is not a list");
+  const entries = inboundAddresses(inbound);
+  if (!entries) throw new HostUnavailable(host, "inbound_addresses is not a THORNode inbound address list");
+  const entry = entries.find((e) => e.chain === claim.chain);
+  if (paused(entry)) return { ok: false, why: "halted", chain: claim.chain };
+  if (claim.destChain !== void 0 && paused(entries.find((e) => e.chain === claim.destChain))) {
+    return { ok: false, why: "halted", chain: claim.destChain };
+  }
+  if (!sameTarget(entry?.address, claim.vault)) {
+    const [asgardBody, mimirBody] = await Promise.all([read(THORNODE_CONFIRM_PATHS.asgardVaults), read(THORNODE_CONFIRM_PATHS.mimir)]);
+    const vaults = asgardVaults(asgardBody);
+    if (!vaults) throw new HostUnavailable(host, "vaults/asgard is not a THORNode vault list");
+    const flags = mimirFlags(mimirBody);
+    if (!flags) throw new HostUnavailable(host, "mimir is not a THORNode mimir map");
+    const holders = vaults.filter((v) => v.addresses.some((a) => a.chain === claim.chain && sameTarget(a.address, claim.vault)));
+    const active = holders.find((v) => v.status === "ActiveVault");
+    if (!active) {
+      if (!holders.length) return { ok: false, why: "another-vault" };
+      return { ok: false, why: "not-active", status: /^[A-Za-z]{1,32}$/.test(holders[0].status) ? holders[0].status : "an unknown status" };
+    }
+    const flag = flags(active.pubKey);
+    if (flag === "malformed") throw new HostUnavailable(host, "mimir holds a non-integer vault flag");
+    if (flag) return { ok: false, why: "flagged", flag };
+  }
+  if (claim.router !== void 0 && !sameTarget(entry?.router, claim.router)) return { ok: false, why: "another-router" };
+  return { ok: true };
+}
+
+// src/provider.ts
 var HOSTS = [
   "https://gateway.liquify.com/chain/thorchain_api",
   "https://thorchain.ibs.team/api"
@@ -84,6 +288,9 @@ var NATIVE = "0x0000000000000000000000000000000000000000";
 var TOLERANCE_BPS = "300";
 var MAX_TOLERANCE_BPS = 500n;
 var QUOTE_VALIDITY_MS = 5 * 6e4;
+var NODE_READ_TIMEOUT_MS = 8e3;
+var CONFIRM_BUDGET_MS = 8e3;
+var LAGGING = /* @__PURE__ */ Symbol("lagging");
 var THOR_CHAIN = {
   "eip155:1": "ETH",
   "eip155:8453": "BASE",
@@ -164,25 +371,20 @@ function destAsset(destChain, destToken) {
   const asset = thorAsset(destChain, a.symbol);
   return asset ? { asset, decimals: a.decimals } : void 0;
 }
-var HostUnavailable = class extends Error {
-  constructor(host, reason) {
-    super(`thorchain: ${host} unavailable (${reason})`);
-  }
-};
 async function hostGet(host, path, clientId, signal) {
   let res;
   try {
     res = await fetch(`${host}${path}`, {
       headers: { accept: "application/json", "x-client-id": clientId },
       cache: "no-store",
-      signal: signal ?? (0, import_util2.timeoutSignal)(8e3)
+      signal: signal ?? (0, import_util2.timeoutSignal)(NODE_READ_TIMEOUT_MS)
     });
   } catch (error) {
     if (signal?.aborted) throw error;
     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 };
@@ -207,35 +409,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;
 }
-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}`);
-  return res.body;
+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 paused(entry) {
-  return !entry || entry.halted === true || entry.global_trading_paused === true || entry.chain_trading_paused === true;
+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" };
 }
-function sameTarget(a, b) {
-  if (!a || !b) return false;
-  return a.startsWith("0x") || b.startsWith("0x") ? a.toLowerCase() === b.toLowerCase() : a === b;
+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}`, 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 };
 }
@@ -279,23 +499,109 @@ function thorchainProvider(config = {}) {
     routers.set(chain, set);
   }
   const pinnedRouter = (chain, router) => !!router && routers.get(chain)?.has(router.toLowerCase()) === true;
-  const confirmedElsewhere = async (quoteHost, chain, vault, router) => {
+  const { maxLagBlocks: confirmMaxLagBlocks, timeoutMs: confirmTimeoutMs } = confirmOptions(config);
+  const nodeSnapshot = (host, outer) => new Promise((resolve, reject) => {
+    let inbounds;
+    let height;
+    let heightError;
+    let done = false;
+    const tip = nodeDeadline(NODE_READ_TIMEOUT_MS, outer);
+    const settle = () => {
+      if (done || inbounds === void 0 || height === void 0 && heightError === void 0) return;
+      done = true;
+      resolve(heightError ? { inbounds, heightError } : { inbounds, height });
+    };
+    const fail = (error) => {
+      if (done) return;
+      done = true;
+      tip.clear();
+      reject(error);
+    };
+    inboundAddressesOn(host, clientId).then((v) => {
+      inbounds = v;
+      settle();
+    }, fail);
+    nodeRead(host, THORNODE_CONFIRM_PATHS.lastblock, clientId, tip.signal, outer).then(
+      (body) => {
+        tip.clear();
+        const h = lastblockHeight(body);
+        if (h === null) heightError = new HostUnavailable(host, "lastblock is not a THORNode lastblock list");
+        else height = h;
+        settle();
+      },
+      (error) => {
+        tip.clear();
+        if (!(error instanceof HostUnavailable)) return fail(error);
+        heightError = error;
+        settle();
+      }
+    );
+  });
+  const confirmText = (v) => {
+    switch (v.why) {
+      case "halted":
+        return { text: `${v.chain} is halted / paused on the confirming node`, info: { reason: "chain_halted" } };
+      case "another-vault":
+        return { text: "a second node reports another inbound vault \u2014 refused until they agree", info: { reason: "vault_mismatch" } };
+      case "not-active":
+        return { text: `a second node lists the inbound vault as ${v.status}, not ActiveVault \u2014 refused`, info: { reason: "vault_mismatch" } };
+      case "flagged":
+        return { text: `a second node's mimir flags the inbound vault as ${v.flag} \u2014 refused`, info: { reason: "vault_mismatch" } };
+      case "another-router":
+        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) => {
+    const read = (path) => nodeRead(host, path, clientId, signal, outer);
+    const head = await nodeHead(host, read);
+    if (quoteHeight - head.height > confirmMaxLagBlocks) return LAGGING;
+    const verdict = await vaultVerdict(host, read, head.inbound, claim);
+    return verdict.ok ? null : confirmText(verdict);
+  };
+  const confirmedElsewhere = async (quoteHost, quoteHeight, chain, destChain, vault, router, deadlineAt, outer) => {
+    const claim = {
+      chain: THOR_CHAIN[chain] ?? chain,
+      ...destChain !== void 0 ? { destChain: THOR_CHAIN[destChain] ?? destChain } : {},
+      vault,
+      ...router !== void 0 ? { router } : {}
+    };
+    let lagging = false;
+    let asked = 0;
+    const failures = [];
     for (const host of confirmHosts) {
       if (host === quoteHost) continue;
-      let entries;
+      const budget = Math.min(confirmTimeoutMs, deadlineAt - Date.now());
+      if (budget < MIN_CONFIRM_TIMEOUT_MS) {
+        failures.push({ reason: "upstream_unavailable" });
+        break;
+      }
+      asked++;
+      const node = nodeDeadline(budget, outer);
       try {
-        entries = await inboundAddressesOn(host, clientId);
+        const verdict = await confirmOn(host, node.signal, outer, quoteHeight, claim);
+        if (verdict === LAGGING) {
+          lagging = true;
+          continue;
+        }
+        return verdict;
       } catch (error) {
-        if (error instanceof HostUnavailable) continue;
+        if (outer?.aborted) throw error;
+        if (error instanceof HostUnavailable) {
+          failures.push((0, import_errors2.refusalOf)(error));
+          continue;
+        }
         throw error;
+      } finally {
+        node.clear();
       }
-      const entry = entries.find((e) => e.chain === THOR_CHAIN[chain]);
-      if (paused(entry)) return `${THOR_CHAIN[chain]} is halted / paused on the confirming node`;
-      if (!sameTarget(entry?.address, vault)) return "a second node reports another inbound vault \u2014 refused until they agree";
-      if (router !== void 0 && !sameTarget(entry?.router, router)) return "a second node reports another router \u2014 refused until they agree";
-      return null;
     }
-    return "no second node answered to confirm the inbound vault (configure confirmNodeUrl)";
+    if (lagging) {
+      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 { 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 { text: "no second node answered to confirm the inbound vault (configure confirmNodeUrl)", info: nodesFailed(failures) };
   };
   const configuredAffiliate = config.affiliate ?? "";
   const configuredAffiliateBps = config.affiliateBps ?? "";
@@ -341,24 +647,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,
@@ -379,6 +688,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}` });
       };
@@ -386,13 +698,17 @@ function thorchainProvider(config = {}) {
       let checkedMemo = null;
       let inbounds = null;
       let quoteHost = "";
+      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 {
@@ -409,32 +725,44 @@ 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;
           }
-          inbounds = await inboundAddressesOn(host, clientId);
+          const deadlineAt = Date.now() + CONFIRM_BUDGET_MS;
+          const snapshot = await nodeSnapshot(host, signal);
+          if ("heightError" in snapshot) {
+            heightUnavailable = true;
+            throw snapshot.heightError;
+          }
+          inbounds = snapshot.inbounds;
+          quoteHeight = snapshot.height;
           quoteHost = host;
+          confirmDeadlineAt = deadlineAt;
           break;
         } catch (error) {
           if (error instanceof HostUnavailable) {
+            hostFailures.push((0, import_errors2.refusalOf)(error));
             q = null;
             checkedMemo = null;
             inbounds = null;
@@ -444,60 +772,72 @@ function thorchainProvider(config = {}) {
         }
       }
       if (!q?.expected_amount_out || !q.inbound_address || !q.expiry || !checkedMemo || !inbounds) {
-        params.onRefusal?.(!inbounds ? "thorchain: inbound addresses unavailable from every node" : "thorchain: no quote from any node");
+        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 ? { reason: "no_route" } : nodesFailed(hostFailures)
+        );
         return null;
       }
       const limit1e8 = checkedMemo.limit;
       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(quoteHost, params.sourceChain, q.inbound_address, chainId ? q.router : void 0);
+      const unconfirmed = await confirmedElsewhere(
+        quoteHost,
+        quoteHeight,
+        params.sourceChain,
+        params.destChain,
+        q.inbound_address,
+        chainId ? q.router : void 0,
+        confirmDeadlineAt,
+        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;
@@ -553,7 +893,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 };
       }
@@ -570,67 +910,96 @@ 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 {
-          inbounds = await inboundAddressesOn(host, clientId);
+          const snapshot = await nodeSnapshot(host);
+          if ("heightError" in snapshot) {
+            heightUnavailable = true;
+            hostFailures.push((0, import_errors2.refusalOf)(snapshot.heightError));
+            continue;
+          }
+          inbounds = snapshot.inbounds;
+          snapshotHeight = snapshot.height;
           snapshotHost = host;
+          confirmDeadlineAt = deadlineAt;
           break;
         } catch (error) {
+          inbounds = null;
           if (!(error instanceof HostUnavailable)) throw error;
+          hostFailures.push((0, import_errors2.refusalOf)(error));
         }
       }
-      if (!inbounds) throw new Error("thorchain: cannot refresh inbound addresses before broadcast");
+      if (!inbounds) {
+        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(snapshotHost, data.sourceChain, data.inboundAddress, evmSource ? data.router : void 0);
-        if (unconfirmed) throw new Error(`thorchain: ${unconfirmed}`);
+        const unconfirmed = await confirmedElsewhere(
+          snapshotHost,
+          snapshotHeight,
+          data.sourceChain,
+          data.destChain,
+          data.inboundAddress,
+          evmSource ? data.router : void 0,
+          confirmDeadlineAt
+        );
+        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();
     },