@anywalletkit/protocol-swap2-relay 0.1.1 → 0.1.2

package/dist/protocol.cjs

@@ -87,6 +87,7 @@ var relay = {
 
 // src/provider.ts
 var import_util2 = require("@anywalletkit/protocol-swap2-core/util");
+var import_errors3 = require("@anywalletkit/protocol-swap2-core/errors");
 
 // src/activity.ts
 var import_activity = require("@anywalletkit/protocol-swap2-core/activity");
@@ -100,13 +101,15 @@ function describeRelayActivity(tx, ctx) {
 
 // src/order.ts
 var import_secp256k1 = require("@noble/curves/secp256k1.js");
+var import_errors = require("@anywalletkit/protocol-swap2-core/errors");
 var import_viem = require("viem");
 var RelayRefusal = class extends Error {
   code;
-  constructor(code, detail) {
+  constructor(code, detail, reason) {
     super(`relay: ${detail} [${code}]`);
     this.name = "RelayRefusal";
     this.code = code;
+    if (reason !== void 0) (0, import_errors.withReason)(this, reason);
   }
 };
 var RELAY_ORDER_TYPES = {
@@ -163,7 +166,7 @@ var MAX_BYTES_HEX = 2 + 2 * 1024;
 var MAX_TEXT = 64;
 var U256_MAX = (1n << 256n) - 1n;
 var bad = (what) => {
-  throw new RelayRefusal("order-malformed", `the order's ${what}`);
+  throw new RelayRefusal("order-malformed", `the order's ${what}`, "upstream_unavailable");
 };
 function rec(v, what) {
   if (v === null || typeof v !== "object" || Array.isArray(v)) bad(`${what} is not an object`);
@@ -282,6 +285,7 @@ function relayOrderSigner(id, signature) {
 
 // src/verify.ts
 var import_viem2 = require("viem");
+var import_errors2 = require("@anywalletkit/protocol-swap2-core/errors");
 var import_util = require("@anywalletkit/protocol-swap2-core/util");
 
 // src/cleared.ts
@@ -291,10 +295,10 @@ var clearedOrders = /* @__PURE__ */ new Map();
 function relayClearOrder(id, stage, nowMs = Date.now()) {
   const key = `${stage}:${id.toLowerCase()}`;
   const until = clearedOrders.get(key);
-  if (until !== void 0 && until > nowMs) throw new RelayRefusal("order-reused", `order ${id} was already cleared for a deposit \u2014 quote again`);
+  if (until !== void 0 && until > nowMs) throw new RelayRefusal("order-reused", `order ${id} was already cleared for a deposit \u2014 quote again`, "policy_refused");
   if (clearedOrders.size >= CLEARED_MAX) {
     for (const [k, t] of clearedOrders) if (t <= nowMs) clearedOrders.delete(k);
-    if (clearedOrders.size >= CLEARED_MAX) throw new RelayRefusal("order-reused", "too many deposits cleared in the last minutes \u2014 try again later");
+    if (clearedOrders.size >= CLEARED_MAX) throw new RelayRefusal("order-reused", "too many deposits cleared in the last minutes \u2014 try again later", "policy_refused");
   }
   clearedOrders.set(key, nowMs + CLEARED_TTL_MS);
 }
@@ -336,24 +340,24 @@ function buildRelayDeposit(source, depositor, token, amount, id) {
   };
 }
 function checkRequest(r) {
-  const invalid = (what) => {
-    throw new RelayRefusal("request-invalid", what);
+  const invalid = (what, reason) => {
+    throw new RelayRefusal("request-invalid", what, reason);
   };
   if (r === null || typeof r !== "object") invalid("no request to check the order against");
   const source = relayChain(r.sourceChain);
   const dest = relayChain(r.destChain);
-  if (!source) throw new RelayRefusal("chain-unsupported", `source chain ${String(r.sourceChain)} is not a pinned Relay chain`);
-  if (!dest) throw new RelayRefusal("chain-unsupported", `destination chain ${String(r.destChain)} is not a pinned Relay chain`);
-  if (source === dest) throw new RelayRefusal("chain-unsupported", "source and destination are the same chain");
+  if (!source) throw new RelayRefusal("chain-unsupported", `source chain ${String(r.sourceChain)} is not a pinned Relay chain`, "unsupported_pair");
+  if (!dest) throw new RelayRefusal("chain-unsupported", `destination chain ${String(r.destChain)} is not a pinned Relay chain`, "unsupported_pair");
+  if (source === dest) throw new RelayRefusal("chain-unsupported", "source and destination are the same chain", "unsupported_pair");
   for (const [what, v] of [["input token", r.sourceToken], ["output token", r.destToken], ["depositor", r.depositor], ["recipient", r.recipient]]) {
     if (typeof v !== "string" || !ADDRESS.test(v)) invalid(`the ${what} is not an address`);
   }
-  if (/^0x0{40}$/.test(r.depositor)) invalid("the depositor is the zero address");
-  if (/^0x0{40}$/.test(r.recipient)) invalid("the recipient is the zero address");
+  if (/^0x0{40}$/.test(r.depositor)) invalid("the depositor is the zero address", "recipient_mismatch");
+  if (/^0x0{40}$/.test(r.recipient)) invalid("the recipient is the zero address", "recipient_mismatch");
   if (typeof r.amount !== "bigint" || r.amount <= 0n || r.amount > U256_MAX2) invalid("the amount is not a positive integer");
   if (r.minAmountOut !== void 0 && (typeof r.minAmountOut !== "bigint" || r.minAmountOut < 0n)) invalid("the output floor is not an unsigned integer");
   if (r.slippageBps !== void 0 && (!Number.isInteger(r.slippageBps) || r.slippageBps < 0 || r.slippageBps > RELAY_MAX_SLIPPAGE_BPS)) {
-    invalid(`slippage must be a whole number of basis points up to ${RELAY_MAX_SLIPPAGE_BPS}`);
+    invalid(`slippage must be a whole number of basis points up to ${RELAY_MAX_SLIPPAGE_BPS}`, "policy_refused");
   }
   const nowMs = r.nowMs ?? Date.now();
   if (!Number.isFinite(nowMs) || nowMs <= 0) invalid("the clock is not a time");
@@ -363,143 +367,143 @@ var isAddr = (bytes2, addr) => bytes2.length === 42 && bytes2 === lower(addr);
 function checkDeadline(code, what, deadline, nowS) {
   const left = deadline - nowS;
   if (left > RELAY_ORDER_LIFETIME_S + RELAY_CLOCK_SKEW_S) {
-    throw new RelayRefusal(code, `${what} is ${left} s away, past the ${RELAY_ORDER_LIFETIME_S} s an order lives`);
+    throw new RelayRefusal(code, `${what} is ${left} s away, past the ${RELAY_ORDER_LIFETIME_S} s an order lives`, "policy_refused");
   }
   if (left < RELAY_ORDER_LIFETIME_S - RELAY_MAX_ORDER_AGE_S) {
-    throw new RelayRefusal(code, `${what} is ${left} s away: the order is older than ${RELAY_MAX_ORDER_AGE_S} s or already past it`);
+    throw new RelayRefusal(code, `${what} is ${left} s away: the order is older than ${RELAY_MAX_ORDER_AGE_S} s or already past it`, "quote_expired");
   }
 }
 function wordAddress(word) {
   return /^0{24}/.test(word) ? `0x${word.slice(24)}` : null;
 }
 function checkDepositTarget(tx, source) {
-  if (tx === null || typeof tx !== "object") throw new RelayRefusal("tx-calldata", "there is no deposit transaction");
+  if (tx === null || typeof tx !== "object") throw new RelayRefusal("tx-calldata", "there is no deposit transaction", "policy_refused");
   if (tx.chainId !== source.chainId) {
-    throw new RelayRefusal("tx-chain", `the deposit is for chain ${String(tx.chainId)}, not ${source.chainId}`);
+    throw new RelayRefusal("tx-chain", `the deposit is for chain ${String(tx.chainId)}, not ${source.chainId}`, "vault_mismatch");
   }
   if (typeof tx.to !== "string" || !ADDRESS.test(tx.to) || lower(tx.to) !== source.depository) {
-    throw new RelayRefusal("tx-target", `the deposit calls ${String(tx.to)}, not the ${source.name} depository ${source.depository} \u2014 routes that first swap on the source chain go through a router and are not signed by this module`);
+    throw new RelayRefusal("tx-target", `the deposit calls ${String(tx.to)}, not the ${source.name} depository ${source.depository} \u2014 routes that first swap on the source chain go through a router and are not signed by this module`, "vault_mismatch");
   }
 }
 function checkDepositTx(tx, source, request, order, id) {
   checkDepositTarget(tx, source);
   if (typeof tx.data !== "string" || !/^0x(?:[0-9a-fA-F]{2})*$/.test(tx.data) || tx.data.length < 10) {
-    throw new RelayRefusal("tx-calldata", "the deposit has no calldata");
+    throw new RelayRefusal("tx-calldata", "the deposit has no calldata", "policy_refused");
   }
   const data = lower(tx.data);
   const selector = data.slice(0, 10);
   const input = order.inputs[0].payment;
   const native = isNative(input.currency);
   if (selector === RELAY_DEPOSIT_ERC20_ALLOWANCE) {
-    throw new RelayRefusal("tx-selector", "the deposit uses depositErc20 without an amount, which takes the whole allowance");
+    throw new RelayRefusal("tx-selector", "the deposit uses depositErc20 without an amount, which takes the whole allowance", "policy_refused");
   }
   if (selector !== RELAY_DEPOSIT_NATIVE && selector !== RELAY_DEPOSIT_ERC20) {
-    throw new RelayRefusal("tx-selector", `the deposit calls ${selector}, not a known deposit function`);
+    throw new RelayRefusal("tx-selector", `the deposit calls ${selector}, not a known deposit function`, "policy_refused");
   }
   if (selector === RELAY_DEPOSIT_NATIVE !== native) {
-    throw new RelayRefusal("tx-selector", `the deposit calls ${native ? "depositErc20" : "depositNative"} for an order whose input is ${native ? "the native coin" : "a token"}`);
+    throw new RelayRefusal("tx-selector", `the deposit calls ${native ? "depositErc20" : "depositNative"} for an order whose input is ${native ? "the native coin" : "a token"}`, "policy_refused");
   }
   const words = native ? 2 : 4;
   if (data.length !== 10 + 64 * words) {
-    throw new RelayRefusal("tx-calldata", `the deposit calldata is ${(data.length - 2) / 2} bytes, not ${4 + 32 * words}`);
+    throw new RelayRefusal("tx-calldata", `the deposit calldata is ${(data.length - 2) / 2} bytes, not ${4 + 32 * words}`, "policy_refused");
   }
   const word = (i) => data.slice(10 + 64 * i, 74 + 64 * i);
   const depositor = wordAddress(word(0));
-  if (depositor === null) throw new RelayRefusal("tx-calldata", "the depositor argument is not a padded address");
+  if (depositor === null) throw new RelayRefusal("tx-calldata", "the depositor argument is not a padded address", "policy_refused");
   if (depositor !== lower(request.depositor)) {
-    throw new RelayRefusal("tx-depositor", `the deposit is credited to ${depositor}, not to the sender ${lower(request.depositor)}`);
+    throw new RelayRefusal("tx-depositor", `the deposit is credited to ${depositor}, not to the sender ${lower(request.depositor)}`, "recipient_mismatch");
   }
   if (!native) {
     const token = wordAddress(word(1));
-    if (token === null) throw new RelayRefusal("tx-calldata", "the token argument is not a padded address");
-    if (token !== input.currency) throw new RelayRefusal("tx-token", `the deposit moves ${token}, the order's input is ${input.currency}`);
+    if (token === null) throw new RelayRefusal("tx-calldata", "the token argument is not a padded address", "policy_refused");
+    if (token !== input.currency) throw new RelayRefusal("tx-token", `the deposit moves ${token}, the order's input is ${input.currency}`, "policy_refused");
     const amount = BigInt(`0x${word(2)}`);
-    if (amount !== input.amount) throw new RelayRefusal("tx-amount", `the deposit moves ${amount}, the order's input is ${input.amount}`);
+    if (amount !== input.amount) throw new RelayRefusal("tx-amount", `the deposit moves ${amount}, the order's input is ${input.amount}`, "policy_refused");
   }
   const txId = `0x${word(native ? 1 : 3)}`;
-  if (txId !== id) throw new RelayRefusal("tx-id", `the deposit names order ${txId}, the order received hashes to ${id}`);
+  if (txId !== id) throw new RelayRefusal("tx-id", `the deposit names order ${txId}, the order received hashes to ${id}`, "recipient_unverifiable");
   const value = typeof tx.value === "string" && /^(?:0|[1-9]\d{0,77})$/.test(tx.value) ? BigInt(tx.value) : null;
   const wantValue = native ? input.amount : 0n;
   if (value === null || value !== wantValue) {
-    throw new RelayRefusal("tx-value", `the deposit sends ${String(tx.value)} wei, it must send ${wantValue}`);
+    throw new RelayRefusal("tx-value", `the deposit sends ${String(tx.value)} wei, it must send ${wantValue}`, "policy_refused");
   }
 }
 function verifyRelayOrder(request, protocol, deposit) {
   const { source, dest, nowS } = checkRequest(request);
   if (deposit !== void 0) checkDepositTarget(deposit, source);
   if (protocol === null || typeof protocol !== "object") {
-    throw new RelayRefusal("protocol-data-missing", "the quote carries no order (protocol.v2) \u2014 nothing to check the deposit against");
+    throw new RelayRefusal("protocol-data-missing", "the quote carries no order (protocol.v2) \u2014 nothing to check the deposit against", "upstream_unavailable");
   }
   if (protocol.orderData === void 0 || protocol.orderData === null) {
-    throw new RelayRefusal("protocol-data-missing", "the quote carries no order data \u2014 nothing to check the deposit against");
+    throw new RelayRefusal("protocol-data-missing", "the quote carries no order data \u2014 nothing to check the deposit against", "upstream_unavailable");
   }
   if (protocol.hubType !== "onchain") {
-    throw new RelayRefusal("hub-type", `the order settles through a "${String(protocol.hubType)}" hub, only "onchain" is read`);
+    throw new RelayRefusal("hub-type", `the order settles through a "${String(protocol.hubType)}" hub, only "onchain" is read`, "unsupported_pair");
   }
   const order = parseRelayOrder(protocol.orderData);
-  if (order.version !== RELAY_ORDER_VERSION) throw new RelayRefusal("order-version", `order version "${order.version}" is not ${RELAY_ORDER_VERSION}`);
-  if (order.inputs.length !== 1) throw new RelayRefusal("order-inputs", `the order has ${order.inputs.length} inputs, exactly one is signed for`);
-  if (order.output.payments.length !== 1) throw new RelayRefusal("order-payments", `the order pays ${order.output.payments.length} outputs, exactly one is accepted`);
-  if (order.output.calls.length !== 0) throw new RelayRefusal("order-calls", "the order runs calls on the destination \u2014 only plain payments are accepted");
-  if (order.fees.length !== 0) throw new RelayRefusal("order-fees", "the order carries order-level fees, which this module does not show and does not accept");
+  if (order.version !== RELAY_ORDER_VERSION) throw new RelayRefusal("order-version", `order version "${order.version}" is not ${RELAY_ORDER_VERSION}`, "upstream_unavailable");
+  if (order.inputs.length !== 1) throw new RelayRefusal("order-inputs", `the order has ${order.inputs.length} inputs, exactly one is signed for`, "policy_refused");
+  if (order.output.payments.length !== 1) throw new RelayRefusal("order-payments", `the order pays ${order.output.payments.length} outputs, exactly one is accepted`, "policy_refused");
+  if (order.output.calls.length !== 0) throw new RelayRefusal("order-calls", "the order runs calls on the destination \u2014 only plain payments are accepted", "policy_refused");
+  if (order.fees.length !== 0) throw new RelayRefusal("order-fees", "the order carries order-level fees, which this module does not show and does not accept", "policy_refused");
   const input = order.inputs[0];
   const pay = order.output.payments[0];
-  if (input.payment.weight === 0n) throw new RelayRefusal("input-weight", "the order's input has zero weight");
+  if (input.payment.weight === 0n) throw new RelayRefusal("input-weight", "the order's input has zero weight", "policy_refused");
   if (!RELAY_SOLVERS.some((s) => s.address === order.solver && s.chainId === order.solverChainId)) {
-    throw new RelayRefusal("solver-not-pinned", `solver ${order.solver} on "${order.solverChainId}" is not a pinned Relay solver`);
+    throw new RelayRefusal("solver-not-pinned", `solver ${order.solver} on "${order.solverChainId}" is not a pinned Relay solver`, "recipient_unverifiable");
   }
-  if (order.output.chainId !== dest.slug) throw new RelayRefusal("output-chain", `the order pays on "${order.output.chainId}", the request is for ${dest.name} ("${dest.slug}")`);
-  if (!isAddr(pay.recipient, request.recipient)) throw new RelayRefusal("output-recipient", `the order pays ${pay.recipient}, not the recipient ${lower(request.recipient)}`);
-  if (!isAddr(pay.currency, request.destToken)) throw new RelayRefusal("output-currency", `the order pays in ${pay.currency}, the request is for ${lower(request.destToken)}`);
-  if (pay.minimumAmount <= 0n) throw new RelayRefusal("output-minimum", "the order's minimum output is zero");
+  if (order.output.chainId !== dest.slug) throw new RelayRefusal("output-chain", `the order pays on "${order.output.chainId}", the request is for ${dest.name} ("${dest.slug}")`, "recipient_mismatch");
+  if (!isAddr(pay.recipient, request.recipient)) throw new RelayRefusal("output-recipient", `the order pays ${pay.recipient}, not the recipient ${lower(request.recipient)}`, "recipient_mismatch");
+  if (!isAddr(pay.currency, request.destToken)) throw new RelayRefusal("output-currency", `the order pays in ${pay.currency}, the request is for ${lower(request.destToken)}`, "price_check_failed");
+  if (pay.minimumAmount <= 0n) throw new RelayRefusal("output-minimum", "the order's minimum output is zero", "price_check_failed");
   if (request.minAmountOut !== void 0 && pay.minimumAmount < request.minAmountOut) {
-    throw new RelayRefusal("output-minimum", `the order's minimum output ${pay.minimumAmount} is under the caller's floor ${request.minAmountOut}`);
+    throw new RelayRefusal("output-minimum", `the order's minimum output ${pay.minimumAmount} is under the caller's floor ${request.minAmountOut}`, "price_check_failed");
   }
-  if (pay.expectedAmount < pay.minimumAmount) throw new RelayRefusal("output-expected", `the order expects ${pay.expectedAmount}, less than its own minimum ${pay.minimumAmount}`);
+  if (pay.expectedAmount < pay.minimumAmount) throw new RelayRefusal("output-expected", `the order expects ${pay.expectedAmount}, less than its own minimum ${pay.minimumAmount}`, "price_check_failed");
   const slippage = BigInt(request.slippageBps ?? RELAY_DEFAULT_SLIPPAGE_BPS);
   const floor = pay.expectedAmount * (10000n - slippage) / 10000n;
   if (pay.minimumAmount < floor) {
-    throw new RelayRefusal("output-minimum", `the order's minimum output ${pay.minimumAmount} is more than ${slippage} bps under its expected ${pay.expectedAmount}`);
+    throw new RelayRefusal("output-minimum", `the order's minimum output ${pay.minimumAmount} is more than ${slippage} bps under its expected ${pay.expectedAmount}`, "price_check_failed");
   }
   checkDeadline("output-deadline", "the output deadline", order.output.deadline, nowS);
-  if (input.payment.chainId !== source.slug) throw new RelayRefusal("input-chain", `the order is funded on "${input.payment.chainId}", the request sends on ${source.name} ("${source.slug}")`);
-  if (!isAddr(input.payment.currency, request.sourceToken)) throw new RelayRefusal("input-currency", `the order is funded in ${input.payment.currency}, the request sends ${lower(request.sourceToken)}`);
-  if (input.payment.amount !== request.amount) throw new RelayRefusal("input-amount", `the order is funded with ${input.payment.amount}, the request sends ${request.amount}`);
+  if (input.payment.chainId !== source.slug) throw new RelayRefusal("input-chain", `the order is funded on "${input.payment.chainId}", the request sends on ${source.name} ("${source.slug}")`, "policy_refused");
+  if (!isAddr(input.payment.currency, request.sourceToken)) throw new RelayRefusal("input-currency", `the order is funded in ${input.payment.currency}, the request sends ${lower(request.sourceToken)}`, "policy_refused");
+  if (input.payment.amount !== request.amount) throw new RelayRefusal("input-amount", `the order is funded with ${input.payment.amount}, the request sends ${request.amount}`, "policy_refused");
   let originRefund = false;
   for (const refund of input.refunds) {
     if (refund.chainId === source.slug) {
-      if (!isAddr(refund.recipient, request.depositor)) throw new RelayRefusal("refund-recipient", `a source-chain refund goes to ${refund.recipient}, not the sender ${lower(request.depositor)}`);
-      if (refund.currency !== input.payment.currency) throw new RelayRefusal("refund-currency", `a source-chain refund is in ${refund.currency}, not the token sent`);
+      if (!isAddr(refund.recipient, request.depositor)) throw new RelayRefusal("refund-recipient", `a source-chain refund goes to ${refund.recipient}, not the sender ${lower(request.depositor)}`, "recipient_mismatch");
+      if (refund.currency !== input.payment.currency) throw new RelayRefusal("refund-currency", `a source-chain refund is in ${refund.currency}, not the token sent`, "policy_refused");
       originRefund = true;
     } else if (refund.chainId === dest.slug) {
       if (!isAddr(refund.recipient, request.recipient) && !isAddr(refund.recipient, request.depositor)) {
-        throw new RelayRefusal("refund-recipient", `a destination-chain refund goes to ${refund.recipient}, neither the recipient nor the sender`);
+        throw new RelayRefusal("refund-recipient", `a destination-chain refund goes to ${refund.recipient}, neither the recipient nor the sender`, "recipient_mismatch");
       }
-      if (refund.currency.length !== 42) throw new RelayRefusal("refund-currency", "a destination-chain refund names no token");
+      if (refund.currency.length !== 42) throw new RelayRefusal("refund-currency", "a destination-chain refund names no token", "policy_refused");
     } else {
-      throw new RelayRefusal("refund-chain", `a refund is payable on "${refund.chainId}", neither the source nor the destination chain`);
+      throw new RelayRefusal("refund-chain", `a refund is payable on "${refund.chainId}", neither the source nor the destination chain`, "recipient_mismatch");
     }
     checkDeadline("refund-deadline", "a refund deadline", refund.deadline, nowS);
   }
-  if (!originRefund) throw new RelayRefusal("refund-missing", "the order has no refund to the sender on the source chain");
+  if (!originRefund) throw new RelayRefusal("refund-missing", "the order has no refund to the sender on the source chain", "policy_refused");
   const id = relayOrderId(order);
   if (typeof protocol.orderId !== "string" || lower(protocol.orderId) !== id) {
-    throw new RelayRefusal("order-id-mismatch", `the quote names order ${String(protocol.orderId)}, the order data hashes to ${id}`);
+    throw new RelayRefusal("order-id-mismatch", `the quote names order ${String(protocol.orderId)}, the order data hashes to ${id}`, "recipient_unverifiable");
   }
   const signer = relayOrderSigner(id, protocol.orderSignature);
   if (signer === null || signer !== order.solver) {
-    throw new RelayRefusal("signature-invalid", signer === null ? "the order signature is not a valid signature" : `the order is signed by ${signer}, not by its solver ${order.solver}`);
+    throw new RelayRefusal("signature-invalid", signer === null ? "the order signature is not a valid signature" : `the order is signed by ${signer}, not by its solver ${order.solver}`, "recipient_unverifiable");
   }
   const pd = protocol.paymentDetails;
-  if (pd === null || typeof pd !== "object") throw new RelayRefusal("payment-details", "the quote has no payment details");
+  if (pd === null || typeof pd !== "object") throw new RelayRefusal("payment-details", "the quote has no payment details", "upstream_unavailable");
   if (pd.chainId !== source.slug || typeof pd.depository !== "string" || lower(pd.depository) !== source.depository || typeof pd.currency !== "string" || lower(pd.currency) !== input.payment.currency || typeof pd.amount !== "string" || pd.amount !== input.payment.amount.toString(10)) {
-    throw new RelayRefusal("payment-details", "the quote's payment details do not describe the order's input on the pinned depository");
+    throw new RelayRefusal("payment-details", "the quote's payment details do not describe the order's input on the pinned depository", "vault_mismatch");
   }
   const built = buildRelayDeposit(source, request.depositor, input.payment.currency, input.payment.amount, id);
   if (deposit !== void 0) {
     checkDepositTx(deposit, source, request, order, id);
     if (lower(deposit.data) !== built.data || lower(deposit.to) !== built.to || deposit.value !== built.value) {
-      throw new RelayRefusal("tx-calldata", "the deposit is not the call this module builds for the order");
+      throw new RelayRefusal("tx-calldata", "the deposit is not the call this module builds for the order", "policy_refused");
     }
   }
   return { order, id, deposit: built, expectedAmount: pay.expectedAmount, minimumAmount: pay.minimumAmount, source, dest };
@@ -509,22 +513,22 @@ function relayRefusalReason(err) {
   throw err;
 }
 function relayRequestOf(params, opts = {}) {
-  const invalid = (what) => {
-    throw new RelayRefusal("request-invalid", what);
+  const invalid = (what, reason) => {
+    throw new RelayRefusal("request-invalid", what, reason);
   };
-  if (params.flex) invalid("the amount is sealed into the order (no flexible deposits)");
-  if (!relayChain(params.sourceChain)) throw new RelayRefusal("chain-unsupported", `source chain ${params.sourceChain} is not a pinned Relay chain`);
-  if (!relayChain(params.destChain)) throw new RelayRefusal("chain-unsupported", `destination chain ${params.destChain} is not a pinned Relay chain`);
-  if (params.sourceChain === params.destChain) throw new RelayRefusal("chain-unsupported", "same-chain swaps are not served through the depository");
+  if (params.flex) invalid("the amount is sealed into the order (no flexible deposits)", "unsupported_pair");
+  if (!relayChain(params.sourceChain)) throw new RelayRefusal("chain-unsupported", `source chain ${params.sourceChain} is not a pinned Relay chain`, "unsupported_pair");
+  if (!relayChain(params.destChain)) throw new RelayRefusal("chain-unsupported", `destination chain ${params.destChain} is not a pinned Relay chain`, "unsupported_pair");
+  if (params.sourceChain === params.destChain) throw new RelayRefusal("chain-unsupported", "same-chain swaps are not served through the depository", "unsupported_pair");
   let sourceToken;
   if (typeof params.sourceToken === "string" && ADDRESS.test(params.sourceToken)) sourceToken = params.sourceToken;
   else {
     const asset = (0, import_util.sourceAssetOf)(params);
-    if (!asset) invalid(`source token ${String(params.sourceToken)} is not known on ${params.sourceChain}`);
+    if (!asset) invalid(`source token ${String(params.sourceToken)} is not known on ${params.sourceChain}`, "unsupported_pair");
     sourceToken = asset.contract ?? RELAY_NATIVE;
-    if (!ADDRESS.test(sourceToken)) invalid(`source token ${String(params.sourceToken)} has no EVM contract`);
+    if (!ADDRESS.test(sourceToken)) invalid(`source token ${String(params.sourceToken)} has no EVM contract`, "unsupported_pair");
   }
-  if (typeof params.destToken !== "string" || !ADDRESS.test(params.destToken)) invalid("the destination token must be an EVM address (zero for the native coin)");
+  if (typeof params.destToken !== "string" || !ADDRESS.test(params.destToken)) invalid("the destination token must be an EVM address (zero for the native coin)", "unsupported_pair");
   if (typeof params.amountIn !== "string" || !/^[1-9]\d{0,77}$/.test(params.amountIn)) invalid("amount must be a positive base-unit integer");
   if (params.minAmountOut !== void 0 && !/^(?:0|[1-9]\d{0,77})$/.test(params.minAmountOut)) invalid("the output floor must be a base-unit integer");
   const recipient = params.destAddress || opts.placeholder || "";
@@ -560,57 +564,63 @@ function relayProtocolOf(quote) {
   return { orderId: pd.orderId, hubType: pd.hubType, orderData, orderSignature: pd.orderSignature, paymentDetails };
 }
 function checkRelayQuote(request, quote, tx) {
-  if (quote === null || typeof quote !== "object" || quote.provider !== "relay") throw new RelayRefusal("quote-shape", "not a Relay quote");
+  if (quote === null || typeof quote !== "object" || quote.provider !== "relay") throw new RelayRefusal("quote-shape", "not a Relay quote", "policy_refused");
   const t = tx ?? quote.txRequest;
-  if (!t) throw new RelayRefusal("quote-shape", "the quote has no transaction");
-  if (quote.depositAddress) throw new RelayRefusal("quote-shape", "a Relay quote pays the depository through its calldata, never a deposit address");
+  if (!t) throw new RelayRefusal("quote-shape", "the quote has no transaction", "policy_refused");
+  if (quote.depositAddress) throw new RelayRefusal("quote-shape", "a Relay quote pays the depository through its calldata, never a deposit address", "vault_mismatch");
   if (quote.txRequest?.serializedTx !== void 0 || quote.txRequest?.nativeFee !== void 0) {
-    throw new RelayRefusal("quote-shape", "a Relay deposit carries no extra native fee and no serialized transaction");
+    throw new RelayRefusal("quote-shape", "a Relay deposit carries no extra native fee and no serialized transaction", "policy_refused");
   }
   const v = verifyRelayOrder(request, relayProtocolOf(quote), t);
   const approval = t.approvalAddress;
   if (v.deposit.approvalAddress === void 0 ? approval !== void 0 && approval !== "" : typeof approval !== "string" || lower(approval) !== v.deposit.approvalAddress) {
-    throw new RelayRefusal("quote-approval", `the quote approves ${String(approval)}, the order needs ${v.deposit.approvalAddress ?? "no approval"}`);
+    throw new RelayRefusal("quote-approval", `the quote approves ${String(approval)}, the order needs ${v.deposit.approvalAddress ?? "no approval"}`, "vault_mismatch");
   }
   if (quote.sourceAmount !== request.amount.toString(10) || quote.minDestAmount !== v.minimumAmount.toString(10) || quote.destAmount !== v.expectedAmount.toString(10)) {
-    throw new RelayRefusal("quote-amounts", "the amounts the quote shows are not the order's");
+    throw new RelayRefusal("quote-amounts", "the amounts the quote shows are not the order's", "price_check_failed");
   }
   const gas = t.gasLimit;
   if (gas !== void 0) {
     const floor = v.deposit.approvalAddress === void 0 ? RELAY_GAS_FLOOR_NATIVE : RELAY_GAS_FLOOR_ERC20;
     if (typeof gas !== "string" || !/^[1-9]\d{0,10}$/.test(gas) || BigInt(gas) < floor || BigInt(gas) > RELAY_GAS_CAP) {
-      throw new RelayRefusal("quote-gas", `the gas limit ${String(gas).slice(0, 40)} is outside ${floor}\u2013${RELAY_GAS_CAP}`);
+      throw new RelayRefusal("quote-gas", `the gas limit ${String(gas).slice(0, 40)} is outside ${floor}\u2013${RELAY_GAS_CAP}`, "policy_refused");
     }
   }
   const now = request.nowMs ?? Date.now();
   if (typeof quote.validUntilMs !== "number" || !Number.isFinite(quote.validUntilMs) || quote.validUntilMs > now + RELAY_MAX_QUOTE_LIFE_MS) {
-    throw new RelayRefusal("quote-expiry", "the quote claims to live longer than a Relay quote may");
+    throw new RelayRefusal("quote-expiry", "the quote claims to live longer than a Relay quote may", "policy_refused");
   }
   if (typeof quote.intentId !== "string" || quote.intentId !== `relay:${String(quote.providerData?.requestId)}` || !/^relay:0x[0-9a-f]{64}$/.test(quote.intentId)) {
-    throw new RelayRefusal("quote-shape", "the quote's id is not its Relay request id");
+    throw new RelayRefusal("quote-shape", "the quote's id is not its Relay request id", "policy_refused");
   }
   return v;
 }
+var pinNotes = (0, import_errors2.refusalNotes)();
+function notedReason(err) {
+  const text2 = relayRefusalReason(err);
+  const info = (0, import_errors2.refusalOf)(err);
+  return info ? pinNotes.note(text2, info) : text2;
+}
 function relayVerifyQuote(params, quote) {
   try {
     checkRelayQuote(relayRequestOf(params), quote);
     return null;
   } catch (err) {
-    return relayRefusalReason(err);
+    return notedReason(err);
   }
 }
 function relayVerifyBuild(quote, tx, params) {
   try {
-    if (!params) throw new RelayRefusal("request-invalid", "the request this quote answered is not known on this side \u2014 quote again");
-    if (tx.chain !== params.sourceChain) throw new RelayRefusal("tx-chain", `the build is for ${tx.chain}, not ${params.sourceChain}`);
+    if (!params) throw new RelayRefusal("request-invalid", "the request this quote answered is not known on this side \u2014 quote again", "policy_refused");
+    if (tx.chain !== params.sourceChain) throw new RelayRefusal("tx-chain", `the build is for ${tx.chain}, not ${params.sourceChain}`, "vault_mismatch");
     if (tx.serializedTx !== void 0 || tx.memo !== void 0 || tx.typedData !== void 0 || tx.bodyBoc !== void 0) {
-      throw new RelayRefusal("quote-shape", "a Relay deposit is one EVM call");
+      throw new RelayRefusal("quote-shape", "a Relay deposit is one EVM call", "policy_refused");
     }
     const v = checkRelayQuote(relayRequestOf(params), quote, tx);
     relayClearOrder(v.id, "build");
     return null;
   } catch (err) {
-    return relayRefusalReason(err);
+    return notedReason(err);
   }
 }
 var relayPins = Object.freeze({
@@ -623,7 +633,8 @@ var relayPins = Object.freeze({
     return c2 ? [c2.depository] : [];
   },
   verifyQuote: relayVerifyQuote,
-  verifyBuild: relayVerifyBuild
+  verifyBuild: relayVerifyBuild,
+  reasonOf: pinNotes.reasonOf
 });
 
 // src/provider.ts
@@ -647,28 +658,69 @@ var RELAY_STATUS_MAP = Object.freeze({
   refunded: "refunded",
   failure: "refund-pending"
 });
+var RELAY_ERROR_REASONS = Object.freeze(Object.assign(/* @__PURE__ */ Object.create(null), {
+  AMOUNT_TOO_LOW: "amount_too_small",
+  AMOUNT_TOO_HIGH: "amount_too_large",
+  INSUFFICIENT_LIQUIDITY: "insufficient_liquidity",
+  NO_QUOTES: "no_route",
+  NO_SWAP_ROUTES_FOUND: "no_route",
+  NO_INTERNAL_SWAP_ROUTES_FOUND: "no_route",
+  // Relay's own failures: a third-party pricing failure, and the transient codes it says to retry with backoff.
+  SWAP_QUOTE_FAILED: "upstream_unavailable",
+  REQUEST_TIMED_OUT: "upstream_unavailable",
+  RPC_HTTP_ERROR: "upstream_unavailable",
+  PRICE_FETCH_FAILED: "upstream_unavailable",
+  SERVICE_UNAVAILABLE: "upstream_unavailable",
+  // The recipient resolves to a token contract, which cannot receive.
+  INVALID_RECIPIENT: "recipient_mismatch",
+  UNSUPPORTED_CHAIN: "unsupported_pair",
+  UNSUPPORTED_CURRENCY: "unsupported_pair",
+  UNSUPPORTED_ROUTE: "unsupported_pair",
+  UNSUPPORTED_EXECUTION_TYPE: "unsupported_pair",
+  INVALID_INPUT_CURRENCY: "unsupported_pair",
+  INVALID_OUTPUT_CURRENCY: "unsupported_pair",
+  CHAIN_DISABLED: "chain_halted",
+  ROUTE_TEMPORARILY_RESTRICTED: "chain_halted",
+  SWAP_IMPACT_TOO_HIGH: "price_check_failed",
+  UNAUTHORIZED: "key_rejected",
+  UNAUTHORIZED_QUOTE: "key_rejected",
+  FORBIDDEN: "key_rejected"
+}));
+function quoteHttpRefusal(res, parsed, aborted) {
+  const code = parsed?.errorCode;
+  const byCode = typeof code === "string" && Object.prototype.hasOwnProperty.call(RELAY_ERROR_REASONS, code) ? RELAY_ERROR_REASONS[code] : void 0;
+  const byStatus = (0, import_errors3.httpRefusal)(res.status, res.headers?.get?.("retry-after"));
+  if (byStatus?.reason === "rate_limited") return byStatus;
+  if (byCode) {
+    if (byStatus?.reason === byCode) return byStatus;
+    return byCode === "upstream_unavailable" || byCode === "key_rejected" ? { reason: byCode, httpStatus: res.status } : { reason: byCode };
+  }
+  if (byStatus) return byStatus;
+  if (parsed !== null && typeof parsed === "object") return { reason: "no_route" };
+  return aborted ? void 0 : { reason: "upstream_unavailable", httpStatus: res.status };
+}
 function clip(text2, max = 240) {
   const t = (0, import_util2.redactUrls)(text2).replace(/\s+/g, " ").trim();
   return t.length > max ? `${t.slice(0, max)}\u2026` : t;
 }
 function depositStep(body) {
   const steps = body.steps;
-  if (!Array.isArray(steps) || steps.length === 0 || steps.length > 8) throw new RelayRefusal("quote-steps", "the quote has no steps");
+  if (!Array.isArray(steps) || steps.length === 0 || steps.length > 8) throw new RelayRefusal("quote-steps", "the quote has no steps", "upstream_unavailable");
   let found = null;
   for (const s of steps) {
-    if (s === null || typeof s !== "object") throw new RelayRefusal("quote-steps", "the quote has a malformed step");
+    if (s === null || typeof s !== "object") throw new RelayRefusal("quote-steps", "the quote has a malformed step", "upstream_unavailable");
     if (s.id === "approve") continue;
-    if (s.id !== "deposit") throw new RelayRefusal("quote-steps", `the quote needs a "${clip(String(s.id), 40)}" step, only a single deposit is signed`);
-    if (found) throw new RelayRefusal("quote-steps", "the quote has more than one deposit step");
+    if (s.id !== "deposit") throw new RelayRefusal("quote-steps", `the quote needs a "${clip(String(s.id), 40)}" step, only a single deposit is signed`, "unsupported_pair");
+    if (found) throw new RelayRefusal("quote-steps", "the quote has more than one deposit step", "unsupported_pair");
     found = s;
   }
-  if (!found) throw new RelayRefusal("quote-steps", "the quote has no deposit step");
+  if (!found) throw new RelayRefusal("quote-steps", "the quote has no deposit step", "upstream_unavailable");
   const items = found.items;
-  if (!Array.isArray(items) || items.length !== 1) throw new RelayRefusal("quote-steps", "the deposit step is not a single transaction");
+  if (!Array.isArray(items) || items.length !== 1) throw new RelayRefusal("quote-steps", "the deposit step is not a single transaction", "unsupported_pair");
   const data = items[0]?.data;
-  if (data === null || typeof data !== "object") throw new RelayRefusal("quote-steps", "the deposit step has no transaction");
+  if (data === null || typeof data !== "object") throw new RelayRefusal("quote-steps", "the deposit step has no transaction", "upstream_unavailable");
   const requestId = typeof found.requestId === "string" ? found.requestId.toLowerCase() : "";
-  if (!REQUEST_ID.test(requestId)) throw new RelayRefusal("quote-steps", "the quote has no request id to track the deposit by");
+  if (!REQUEST_ID.test(requestId)) throw new RelayRefusal("quote-steps", "the quote has no request id to track the deposit by", "upstream_unavailable");
   return { requestId, tx: data };
 }
 function relayProvider(config = {}) {
@@ -704,12 +756,12 @@ function relayProvider(config = {}) {
       .../^\d{1,5}$/.test(pd.slippageBps ?? "") ? { slippageBps: Number(pd.slippageBps) } : {}
     };
     if (sealed.depositor.toLowerCase() === EVM_PLACEHOLDER.toLowerCase() || sealed.recipient.toLowerCase() === EVM_PLACEHOLDER.toLowerCase()) {
-      throw new RelayRefusal("request-invalid", "a quote priced without the real addresses is never built or signed \u2014 quote again with them");
+      throw new RelayRefusal("request-invalid", "a quote priced without the real addresses is never built or signed \u2014 quote again with them", "policy_refused");
     }
     const mine = issued.get(quote.intentId);
     if (!mine) return sealed;
     const same = mine.sourceChain === sealed.sourceChain && mine.destChain === sealed.destChain && mine.amount === sealed.amount && mine.sourceToken.toLowerCase() === sealed.sourceToken.toLowerCase() && mine.destToken.toLowerCase() === sealed.destToken.toLowerCase() && mine.depositor.toLowerCase() === sealed.depositor.toLowerCase() && mine.recipient.toLowerCase() === sealed.recipient.toLowerCase();
-    if (!same) throw new RelayRefusal("request-invalid", "the quote no longer says what was asked when it was issued \u2014 quote again");
+    if (!same) throw new RelayRefusal("request-invalid", "the quote no longer says what was asked when it was issued \u2014 quote again", "policy_refused");
     return mine;
   }
   async function readJson(res) {
@@ -725,8 +777,8 @@ function relayProvider(config = {}) {
     supportsChainPair: (from, to) => relay.supports(from, to),
     supportsRoute: (from, to) => relay.supports(from.chain, to.chain),
     async getQuote(params, signal) {
-      const refuse = (reason) => {
-        params.onRefusal?.(reason);
+      const refuse = (reason, info) => {
+        params.onRefusal?.(reason, info);
         return null;
       };
       const dry = params.dry !== false;
@@ -735,7 +787,7 @@ function relayProvider(config = {}) {
       try {
         request = relayRequestOf(params, dry ? { placeholder: EVM_PLACEHOLDER } : {});
       } catch (err) {
-        if (err instanceof RelayRefusal) return refuse(err.message);
+        if (err instanceof RelayRefusal) return refuse(err.message, (0, import_errors3.refusalOf)(err));
         throw err;
       }
       const src = relayChain(request.sourceChain);
@@ -770,20 +822,21 @@ function relayProvider(config = {}) {
         if (!res.ok) {
           const e = parsed ?? {};
           const why = typeof e.message === "string" ? clip(e.message) : `HTTP ${res.status}`;
-          return refuse(`relay: no quote \u2014 ${typeof e.errorCode === "string" ? `${clip(e.errorCode, 60)}: ` : ""}${why}`);
+          return refuse(`relay: no quote \u2014 ${typeof e.errorCode === "string" ? `${clip(e.errorCode, 60)}: ` : ""}${why}`, quoteHttpRefusal(res, parsed, signal?.aborted === true));
         }
-        if (parsed === null || typeof parsed !== "object") return refuse("relay: the quote response is not JSON");
+        if (parsed === null || typeof parsed !== "object") return refuse("relay: the quote response is not JSON", signal?.aborted ? void 0 : { reason: "upstream_unavailable" });
         body = parsed;
       } catch (err) {
-        return refuse(`relay: quote request failed \u2014 ${clip(err instanceof Error ? err.message : String(err))}`);
+        const info = (0, import_errors3.refusalOf)(err) ?? (signal?.aborted ? void 0 : { reason: "upstream_unavailable" });
+        return refuse(`relay: quote request failed \u2014 ${clip(err instanceof Error ? err.message : String(err))}`, info);
       }
       try {
         const step = depositStep(body);
         const proto = body.protocol?.v2 ?? null;
         const v = verifyRelayOrder(request, proto, step.tx);
         const extra = (x) => x !== void 0 && x !== null && x !== "0" && x !== 0;
-        if (extra(body.fees?.app?.amount)) throw new RelayRefusal("app-fee", "the quote charges an app fee this module did not ask for");
-        if (extra(body.details?.currencyGasTopup?.amount)) throw new RelayRefusal("gas-topup", "the quote converts part of the output into a gas top-up this module did not ask for");
+        if (extra(body.fees?.app?.amount)) throw new RelayRefusal("app-fee", "the quote charges an app fee this module did not ask for", "policy_refused");
+        if (extra(body.details?.currencyGasTopup?.amount)) throw new RelayRefusal("gas-topup", "the quote converts part of the output into a gas top-up this module did not ask for", "policy_refused");
         const native = v.deposit.approvalAddress === void 0;
         const floor = native ? RELAY_GAS_FLOOR_NATIVE : RELAY_GAS_FLOOR_ERC20;
         const apiGas = typeof step.tx.gas === "string" && /^[1-9]\d{0,9}$/.test(step.tx.gas) ? BigInt(step.tx.gas) * 2n : 0n;
@@ -838,15 +891,15 @@ function relayProvider(config = {}) {
           }
         };
       } catch (err) {
-        if (err instanceof RelayRefusal) return refuse(err.message);
-        return refuse(`relay: unreadable quote \u2014 ${clip(err instanceof Error ? err.message : String(err))}`);
+        if (err instanceof RelayRefusal) return refuse(err.message, (0, import_errors3.refusalOf)(err));
+        return refuse(`relay: unreadable quote \u2014 ${clip(err instanceof Error ? err.message : String(err))}`, (0, import_errors3.refusalOf)(err) ?? { reason: "upstream_unavailable" });
       }
     },
     /** The quote's own transaction — after the order it carries has been verified once more. */
     async buildDeposit(quote) {
       const tx = quote.txRequest;
-      if (!tx || !quote.intentId.startsWith(INTENT_PREFIX)) throw new Error("swap2: Relay quote has no transaction request");
-      if (quote.providerData?.placeholder === "1") throw new RelayRefusal("request-invalid", "a quote priced without the real addresses is never built \u2014 quote again with them");
+      if (!tx || !quote.intentId.startsWith(INTENT_PREFIX)) throw (0, import_errors3.refusal)("policy_refused", "swap2: Relay quote has no transaction request");
+      if (quote.providerData?.placeholder === "1") throw new RelayRefusal("request-invalid", "a quote priced without the real addresses is never built \u2014 quote again with them", "policy_refused");
       const request = requestOf(quote);
       const v = checkRelayQuote(request, quote);
       return {
@@ -864,15 +917,15 @@ function relayProvider(config = {}) {
      * and the exact transaction about to be signed — and each order is cleared for one deposit only.
      */
     async preflightDeposit(quote, tx) {
-      if (quote.providerData?.placeholder === "1") throw new RelayRefusal("request-invalid", "a quote priced without the real addresses is never signed");
+      if (quote.providerData?.placeholder === "1") throw new RelayRefusal("request-invalid", "a quote priced without the real addresses is never signed", "policy_refused");
       const request = requestOf(quote);
-      if (tx.chain !== request.sourceChain) throw new RelayRefusal("tx-chain", `the deposit is for ${tx.chain}, not ${request.sourceChain}`);
+      if (tx.chain !== request.sourceChain) throw new RelayRefusal("tx-chain", `the deposit is for ${tx.chain}, not ${request.sourceChain}`, "vault_mismatch");
       if (tx.serializedTx !== void 0 || tx.memo !== void 0 || tx.typedData !== void 0 || tx.bodyBoc !== void 0) {
-        throw new RelayRefusal("quote-shape", "a Relay deposit is one EVM call");
+        throw new RelayRefusal("quote-shape", "a Relay deposit is one EVM call", "policy_refused");
       }
       const v = checkRelayQuote(request, quote, tx);
       const store = config.clearedStore;
-      if (store && await store.has(v.id)) throw new RelayRefusal("order-reused", `order ${v.id} was already cleared for a deposit \u2014 quote again`);
+      if (store && await store.has(v.id)) throw new RelayRefusal("order-reused", `order ${v.id} was already cleared for a deposit \u2014 quote again`, "policy_refused");
       relayClearOrder(v.id, "sign");
       if (store) await store.add(v.id, v.order.output.deadline * 1e3);
     },