@anywalletkit/protocol-swap2-curve 0.1.2 → 0.1.4

package/dist/index.cjs

@@ -222,6 +222,18 @@ function decodeExchange(family, data) {
 // src/routes.ts
 var import_viem2 = require("viem");
 var import_swap2_assets = require("@anywalletkit/swap2-assets");
+
+// src/reasons.ts
+var import_errors = require("@anywalletkit/protocol-swap2-core/errors");
+var notes = (0, import_errors.refusalNotes)(256);
+function noted(text, info) {
+  return info === void 0 ? text : notes.note(text, info);
+}
+function tagged(error, info) {
+  return info === void 0 ? error : (0, import_errors.withReason)(error, info);
+}
+
+// src/routes.ts
 var MAX_QUOTE_CANDIDATES = 30;
 var MAX_EXPLORED = 2e4;
 var lc = (a) => a.toLowerCase();
@@ -372,7 +384,7 @@ function routePools(args) {
 }
 function checkRoute(chainId, deployment, table, args, tokenIn, tokenOut) {
   const cols = deployment.family === "ng5" ? 5 : 4;
-  if (args.route.length !== 11 || args.params.length !== 5 || args.params.some((r) => r.length !== cols)) return `the route is not address[11] with uint256[${cols}][5]`;
+  if (args.route.length !== 11 || args.params.length !== 5 || args.params.some((r) => r.length !== cols)) return noted(`the route is not address[11] with uint256[${cols}][5]`, "policy_refused");
   const index = poolIndex(chainId, deployment, table);
   const zero = lc(ZERO_ADDRESS);
   const eth = lc(deployment.eth);
@@ -380,14 +392,14 @@ function checkRoute(chainId, deployment, table, args, tokenIn, tokenOut) {
   const v = erc4626Of(deployment);
   let steps = 0;
   while (steps < 5 && lc(args.route[2 * steps + 1]) !== zero) steps++;
-  if (steps === 0) return "the route has no step";
-  if (steps > MAX_ROUTE_STEPS) return `the route has ${steps} steps, more than ${MAX_ROUTE_STEPS}`;
-  for (let k = 2 * steps + 1; k < 11; k++) if (lc(args.route[k]) !== zero) return "the route names addresses after its end";
-  for (let k = steps; k < 5; k++) if (args.params[k].some((x) => x !== 0n)) return "the swap params carry rows after the route's end";
-  if (lc(args.route[0]) !== lc(tokenIn)) return `the route starts at ${args.route[0]}, not the source token`;
-  if (lc(args.route[2 * steps]) !== lc(tokenOut)) return `the route ends at ${args.route[2 * steps]}, not the destination token`;
+  if (steps === 0) return noted("the route has no step", "policy_refused");
+  if (steps > MAX_ROUTE_STEPS) return noted(`the route has ${steps} steps, more than ${MAX_ROUTE_STEPS}`, "policy_refused");
+  for (let k = 2 * steps + 1; k < 11; k++) if (lc(args.route[k]) !== zero) return noted("the route names addresses after its end", "policy_refused");
+  for (let k = steps; k < 5; k++) if (args.params[k].some((x) => x !== 0n)) return noted("the swap params carry rows after the route's end", "policy_refused");
+  if (lc(args.route[0]) !== lc(tokenIn)) return noted(`the route starts at ${args.route[0]}, not the source token`, "policy_refused");
+  if (lc(args.route[2 * steps]) !== lc(tokenOut)) return noted(`the route ends at ${args.route[2 * steps]}, not the destination token`, "price_check_failed");
   for (let k = 1; k < steps; k++) {
-    if (!intermediateAllowed(chainId, deployment, args.route[2 * k])) return `step ${k} hands the swap through ${args.route[2 * k]}, a token the catalog does not list on this chain`;
+    if (!intermediateAllowed(chainId, deployment, args.route[2 * k])) return noted(`step ${k} hands the swap through ${args.route[2 * k]}, a token the catalog does not list on this chain`, "policy_refused");
   }
   const pools = /* @__PURE__ */ new Set();
   let wraps = 0;
@@ -398,51 +410,52 @@ function checkRoute(chainId, deployment, table, args, tokenIn, tokenOut) {
     const b = lc(args.route[2 * k + 2]);
     const row = args.params[k];
     const type = row[2];
-    if (a === b) return `step ${k + 1} trades a token for itself`;
+    if (a === b) return noted(`step ${k + 1} trades a token for itself`, "policy_refused");
     if (type === 1n || type === 2n) {
-      if (CURVE_DENIED_POOLS[chainId]?.has(swap)) return `step ${k + 1} crosses ${args.route[2 * k + 1]}, a pool this module refuses (fake coin, drained in 2023, or over a dead venue)`;
+      if (CURVE_DENIED_POOLS[chainId]?.has(swap)) return noted(`step ${k + 1} crosses ${args.route[2 * k + 1]}, a pool this module refuses (fake coin, drained in 2023, or over a dead venue)`, "vault_mismatch");
       const pool = index.get(swap);
-      if (!pool) return `step ${k + 1} crosses ${args.route[2 * k + 1]}, which is not in the pool allowlist`;
-      if (pools.has(swap)) return `the route crosses ${args.route[2 * k + 1]} twice`;
+      if (!pool) return noted(`step ${k + 1} crosses ${args.route[2 * k + 1]}, which is not in the pool allowlist`, "vault_mismatch");
+      if (pools.has(swap)) return noted(`the route crosses ${args.route[2 * k + 1]} twice`, "policy_refused");
       pools.add(swap);
-      if (!pool.swapTypes.includes(type === 1n ? 1 : 2)) return `step ${k + 1} uses swap_type ${type}, which pool ${pool.name} does not allow`;
-      if (row[3] !== BigInt(pool.poolType)) return `step ${k + 1} names pool_type ${row[3]}, not pool ${pool.name}'s ${pool.poolType}`;
-      if (type === 2n && deployment.family === "lite4" && pool.poolType !== 10) return `step ${k + 1}: exchange_underlying is for stable-ng metapools on this router`;
-      if (type === 2n && !underlyingAllowed(pool, index)) return `step ${k + 1}: exchange_underlying on pool ${pool.name} needs its base pool in the allowlist`;
+      if (!pool.swapTypes.includes(type === 1n ? 1 : 2)) return noted(`step ${k + 1} uses swap_type ${type}, which pool ${pool.name} does not allow`, "policy_refused");
+      if (row[3] !== BigInt(pool.poolType)) return noted(`step ${k + 1} names pool_type ${row[3]}, not pool ${pool.name}'s ${pool.poolType}`, "policy_refused");
+      if (type === 2n && deployment.family === "lite4" && pool.poolType !== 10) return noted(`step ${k + 1}: exchange_underlying is for stable-ng metapools on this router`, "policy_refused");
+      if (type === 2n && !underlyingAllowed(pool, index)) return noted(`step ${k + 1}: exchange_underlying on pool ${pool.name} needs its base pool in the allowlist`, "policy_refused");
       const list = type === 1n ? pool.coins : pool.underlying;
-      if (!list) return `step ${k + 1}: pool ${pool.name} lists no underlying coins`;
+      if (!list) return noted(`step ${k + 1}: pool ${pool.name} lists no underlying coins`, "policy_refused");
       const i = row[0], j = row[1];
-      if (i >= BigInt(list.length) || j >= BigInt(list.length) || i === j) return `step ${k + 1}: coin indexes ${i}/${j} are not two coins of pool ${pool.name}`;
-      if (lc(list[Number(i.toString())]) !== a || lc(list[Number(j.toString())]) !== b) return `step ${k + 1}: pool ${pool.name}'s coins ${i}/${j} are not the hop's tokens`;
-      if (deployment.family === "ng5" && row[4] !== BigInt(list.length)) return `step ${k + 1} names ${row[4]} coins, not pool ${pool.name}'s ${list.length}`;
-      if (deployment.family === "lite4" && (a === eth || b === eth)) return `step ${k + 1}: this router does not pass the native coin to pools`;
-      if (STABLE_POOL_TYPES.has(pool.poolType) && (i > 127n || j > 127n)) return `step ${k + 1}: coin index out of range`;
+      if (i >= BigInt(list.length) || j >= BigInt(list.length) || i === j) return noted(`step ${k + 1}: coin indexes ${i}/${j} are not two coins of pool ${pool.name}`, "policy_refused");
+      if (lc(list[Number(i.toString())]) !== a || lc(list[Number(j.toString())]) !== b) return noted(`step ${k + 1}: pool ${pool.name}'s coins ${i}/${j} are not the hop's tokens`, "policy_refused");
+      if (deployment.family === "ng5" && row[4] !== BigInt(list.length)) return noted(`step ${k + 1} names ${row[4]} coins, not pool ${pool.name}'s ${list.length}`, "policy_refused");
+      if (deployment.family === "lite4" && (a === eth || b === eth)) return noted(`step ${k + 1}: this router does not pass the native coin to pools`, "policy_refused");
+      if (STABLE_POOL_TYPES.has(pool.poolType) && (i > 127n || j > 127n)) return noted(`step ${k + 1}: coin index out of range`, "policy_refused");
     } else if (type === 8n) {
-      if (weth === zero) return "this chain's router has no wrapped native";
-      if (swap !== weth) return `step ${k + 1} wraps through ${args.route[2 * k + 1]}, not the pinned wrapped native`;
-      if (!(a === eth && b === weth || a === weth && b === eth)) return `step ${k + 1}: swap_type 8 is only native \u2194 the pinned wrapped native here`;
-      if (row.some((x, c) => c !== 2 && x !== 0n)) return `step ${k + 1}: a wrap carries no other swap params`;
-      if (++wraps > 1) return "the route wraps more than once";
+      if (weth === zero) return noted("this chain's router has no wrapped native", "policy_refused");
+      if (swap !== weth) return noted(`step ${k + 1} wraps through ${args.route[2 * k + 1]}, not the pinned wrapped native`, "vault_mismatch");
+      if (!(a === eth && b === weth || a === weth && b === eth)) return noted(`step ${k + 1}: swap_type 8 is only native \u2194 the pinned wrapped native here`, "policy_refused");
+      if (row.some((x, c) => c !== 2 && x !== 0n)) return noted(`step ${k + 1}: a wrap carries no other swap params`, "policy_refused");
+      if (++wraps > 1) return noted("the route wraps more than once", "policy_refused");
     } else if (type === 9n) {
-      if (!v) return `swap_type 9 (ERC-4626) is not available on ${deployment.label}'s router ${deployment.version}`;
-      if (swap !== lc(v.vault)) return `step ${k + 1}: ERC-4626 hop through ${args.route[2 * k + 1]}, not the pinned vault`;
+      if (!v) return noted(`swap_type 9 (ERC-4626) is not available on ${deployment.label}'s router ${deployment.version}`, "policy_refused");
+      if (swap !== lc(v.vault)) return noted(`step ${k + 1}: ERC-4626 hop through ${args.route[2 * k + 1]}, not the pinned vault`, "vault_mismatch");
       const deposit = row[0] === 0n && a === lc(v.asset) && b === lc(v.vault);
       const redeem = row[0] === 1n && a === lc(v.vault) && b === lc(v.asset);
-      if (!deposit && !redeem) return `step ${k + 1}: the ERC-4626 hop is not a deposit of the vault's asset or a redeem of its shares`;
-      if (row.some((x, c) => c > 0 && c !== 2 && x !== 0n)) return `step ${k + 1}: an ERC-4626 hop carries no other swap params`;
-      if (++vaults > 1) return "the route crosses the vault more than once";
+      if (!deposit && !redeem) return noted(`step ${k + 1}: the ERC-4626 hop is not a deposit of the vault's asset or a redeem of its shares`, "policy_refused");
+      if (row.some((x, c) => c > 0 && c !== 2 && x !== 0n)) return noted(`step ${k + 1}: an ERC-4626 hop carries no other swap params`, "policy_refused");
+      if (++vaults > 1) return noted("the route crosses the vault more than once", "policy_refused");
     } else {
-      return `step ${k + 1} uses swap_type ${type}, which this module never builds`;
+      return noted(`step ${k + 1} uses swap_type ${type}, which this module never builds`, "policy_refused");
     }
   }
-  if (pools.size > MAX_ROUTE_POOLS) return `the route crosses ${pools.size} pools, more than ${MAX_ROUTE_POOLS}`;
-  if (pools.size === 0 && vaults === 0) return "the route crosses no pool";
+  if (pools.size > MAX_ROUTE_POOLS) return noted(`the route crosses ${pools.size} pools, more than ${MAX_ROUTE_POOLS}`, "policy_refused");
+  if (pools.size === 0 && vaults === 0) return noted("the route crosses no pool", "policy_refused");
   return null;
 }
 
 // src/provider.ts
 var import_viem4 = require("viem");
 var import_util5 = require("@anywalletkit/protocol-swap2-core/util");
+var import_errors4 = require("@anywalletkit/protocol-swap2-core/errors");
 
 // src/activity.ts
 var import_activity = require("@anywalletkit/protocol-swap2-core/activity");
@@ -642,6 +655,7 @@ var CURVE_POOLS = Object.freeze({
 });
 
 // src/rpc.ts
+var import_errors2 = require("@anywalletkit/protocol-swap2-core/errors");
 var import_util2 = require("@anywalletkit/protocol-swap2-core/util");
 var RPC_BATCH_MAX = 10;
 var RPC_RATE_LIMIT_PAUSE_MS = 1e3;
@@ -667,18 +681,18 @@ function rpcClient(rpcUrls) {
       body: JSON.stringify(calls.map((c, id) => ({ jsonrpc: "2.0", id, ...c }))),
       signal: signal ?? (0, import_util2.timeoutSignal)(12e3)
     });
-    if (!res.ok) throw Object.assign(new Error(`HTTP ${res.status}`), { limited: res.status === 429 });
+    if (!res.ok) throw (0, import_errors2.withReason)(Object.assign(new Error(`HTTP ${res.status}`), { limited: res.status === 429 }), (0, import_errors2.httpRefusal)(res.status, res.headers?.get?.("retry-after")) ?? { reason: "upstream_unavailable", httpStatus: res.status });
     const body = await res.json();
-    if (!Array.isArray(body)) throw Object.assign(new Error(body.error?.message ?? "batch refused"), { limited: isRateLimit(body.error) });
+    if (!Array.isArray(body)) throw (0, import_errors2.withReason)(Object.assign(new Error(body.error?.message ?? "batch refused"), { limited: isRateLimit(body.error) }), isRateLimit(body.error) ? "rate_limited" : "upstream_unavailable");
     const out = calls.map(() => null);
     const answered = /* @__PURE__ */ new Set();
     for (const r of body) {
       if (typeof r.id !== "number" || r.id < 0 || r.id >= out.length) continue;
-      if (r.error !== void 0 && r.error !== null && !isExecutionError(r.error)) throw Object.assign(new Error(errorText(r.error)), { limited: isRateLimit(r.error) });
+      if (r.error !== void 0 && r.error !== null && !isExecutionError(r.error)) throw (0, import_errors2.withReason)(Object.assign(new Error(errorText(r.error)), { limited: isRateLimit(r.error) }), isRateLimit(r.error) ? "rate_limited" : "upstream_unavailable");
       answered.add(r.id);
       if (r.error === void 0 || r.error === null) out[r.id] = r.result ?? null;
     }
-    if (answered.size !== calls.length) throw new Error(`answered ${answered.size} of ${calls.length} calls`);
+    if (answered.size !== calls.length) throw (0, import_errors2.refusal)("upstream_unavailable", `answered ${answered.size} of ${calls.length} calls`);
     return out;
   }
   async function batch(chainId, calls, signal) {
@@ -696,7 +710,9 @@ function rpcClient(rpcUrls) {
         }
       }
     }
-    throw new Error(`curve: no RPC answered on chain ${chainId} (${lastErr instanceof Error ? lastErr.message : String(lastErr)})`);
+    const error = new Error(`curve: no RPC answered on chain ${chainId} (${lastErr instanceof Error ? lastErr.message : String(lastErr)})`);
+    if (lastErr === void 0 || signal?.aborted) throw error;
+    throw (0, import_errors2.withReason)(error, (0, import_errors2.refusalOf)(lastErr) ?? "upstream_unavailable");
   }
   return async function rpc(chainId, calls, signal) {
     if (calls.length <= RPC_BATCH_MAX) return batch(chainId, calls, signal);
@@ -756,6 +772,7 @@ function curveIntentChain(intentId) {
 var import_viem3 = require("viem");
 var import_util4 = require("@anywalletkit/protocol-swap2-core/util");
 var import_validate = require("@anywalletkit/protocol-swap2-core/validate");
+var import_errors3 = require("@anywalletkit/protocol-swap2-core/errors");
 var lc2 = (a) => a.toLowerCase();
 var isAddress = (a) => /^0x[0-9a-fA-F]{40}$/.test(a);
 var own = (o, k) => Object.prototype.hasOwnProperty.call(o, k) ? o[k] : void 0;
@@ -765,19 +782,19 @@ function curveQuoteCheck(tables = {}) {
   return function verify(params, quote) {
     const chainId = chainIdOf(params.sourceChain);
     const d2 = deploymentOf(deployments, chainId);
-    if (!d2 || params.destChain !== params.sourceChain) return "not a same-chain swap on a pinned Curve router";
+    if (!d2 || params.destChain !== params.sourceChain) return noted("not a same-chain swap on a pinned Curve router", "unsupported_pair");
     const tx = quote.txRequest;
-    if (!tx?.data || !tx.to || tx.serializedTx !== void 0) return "the quote carries no router call";
-    if (!isAddress(tx.to) || lc2(tx.to) !== lc2(d2.router)) return `the call targets ${tx.to}, not the Curve router`;
-    if (tx.chainId !== void 0 && tx.chainId !== chainId) return `the call is for chain ${tx.chainId}`;
-    if (curveIntentChain(quote.intentId) !== chainId) return `the quote names ${String(quote.intentId).slice(0, 40)}, not a curve:${chainId} swap`;
+    if (!tx?.data || !tx.to || tx.serializedTx !== void 0) return noted("the quote carries no router call", "policy_refused");
+    if (!isAddress(tx.to) || lc2(tx.to) !== lc2(d2.router)) return noted(`the call targets ${tx.to}, not the Curve router`, "vault_mismatch");
+    if (tx.chainId !== void 0 && tx.chainId !== chainId) return noted(`the call is for chain ${tx.chainId}`, "policy_refused");
+    if (curveIntentChain(quote.intentId) !== chainId) return noted(`the quote names ${String(quote.intentId).slice(0, 40)}, not a curve:${chainId} swap`, "policy_refused");
     const src = (0, import_util4.sourceAssetOf)(params);
-    if (!src) return `unknown source token ${params.sourceToken}`;
+    if (!src) return noted(`unknown source token ${params.sourceToken}`, "unsupported_pair");
     const nativeIn = !src.contract;
     const nativeOut = /^0x0+$/.test(params.destToken);
-    if (!nativeOut && !isAddress(params.destToken)) return "destination token must be an EVM address";
-    if (!isAddress(params.destAddress)) return "recipient must be an EVM address";
-    if (!nativeIn && lc2(src.contract) === lc2(d2.eth) || !nativeOut && lc2(params.destToken) === lc2(d2.eth)) return "the router's native sentinel is not a token";
+    if (!nativeOut && !isAddress(params.destToken)) return noted("destination token must be an EVM address", "unsupported_pair");
+    if (!isAddress(params.destAddress)) return noted("recipient must be an EVM address", "recipient_mismatch");
+    if (!nativeIn && lc2(src.contract) === lc2(d2.eth) || !nativeOut && lc2(params.destToken) === lc2(d2.eth)) return noted("the router's native sentinel is not a token", "unsupported_pair");
     const tokenIn = nativeIn ? d2.eth : src.contract;
     const tokenOut = nativeOut ? d2.eth : params.destToken;
     let amountIn, minOut, value;
@@ -786,20 +803,20 @@ function curveQuoteCheck(tables = {}) {
       minOut = BigInt(quote.minDestAmount);
       value = BigInt(tx.value ?? "0");
     } catch {
-      return "the request does not name amounts";
+      return noted("the request does not name amounts", "policy_refused");
     }
     if (nativeIn ? value !== amountIn || tx.approvalAddress !== void 0 : value !== 0n || !tx.approvalAddress || !isAddress(tx.approvalAddress) || lc2(tx.approvalAddress) !== lc2(d2.router)) {
-      return nativeIn ? "a native input is paid as exactly the input in value, with no approval" : "a token input attaches no value and approves exactly the Curve router";
+      return noted(nativeIn ? "a native input is paid as exactly the input in value, with no approval" : "a token input attaches no value and approves exactly the Curve router", "policy_refused");
     }
     const call = decodeExchange(d2.family, tx.data);
-    if (!call) return "the router call is not exchange(route, params, amount, min, receiver)";
-    if (call.selector !== EXCHANGE_SELECTOR[d2.family]) return `selector ${call.selector} is not the explicit-receiver exchange ${EXCHANGE_SELECTOR[d2.family]}`;
-    if (!call.receiver || lc2(call.receiver) !== lc2(params.destAddress)) return `the swap pays ${call.receiver ?? "the sender"}, not the recipient`;
-    if (call.pools && call.pools.some((p) => lc2(p) !== lc2(ZERO_ADDRESS))) return "the call names zap pools this module never uses";
-    if (call.amount !== amountIn) return `the swap sells ${call.amount}, not the ${amountIn} input`;
-    if (call.minDy <= 0n) return "the swap has no minimum (min_dy 0)";
-    if (call.minDy !== minOut) return `the swap's minimum ${call.minDy} is not the quote's ${minOut}`;
-    if (quote.providerData?.minOut !== void 0 && quote.providerData.minOut !== minOut.toString()) return "the quote's facts disagree on the minimum";
+    if (!call) return noted("the router call is not exchange(route, params, amount, min, receiver)", "policy_refused");
+    if (call.selector !== EXCHANGE_SELECTOR[d2.family]) return noted(`selector ${call.selector} is not the explicit-receiver exchange ${EXCHANGE_SELECTOR[d2.family]}`, "policy_refused");
+    if (!call.receiver || lc2(call.receiver) !== lc2(params.destAddress)) return noted(`the swap pays ${call.receiver ?? "the sender"}, not the recipient`, "recipient_mismatch");
+    if (call.pools && call.pools.some((p) => lc2(p) !== lc2(ZERO_ADDRESS))) return noted("the call names zap pools this module never uses", "policy_refused");
+    if (call.amount !== amountIn) return noted(`the swap sells ${call.amount}, not the ${amountIn} input`, "policy_refused");
+    if (call.minDy <= 0n) return noted("the swap has no minimum (min_dy 0)", "price_check_failed");
+    if (call.minDy !== minOut) return noted(`the swap's minimum ${call.minDy} is not the quote's ${minOut}`, "price_check_failed");
+    if (quote.providerData?.minOut !== void 0 && quote.providerData.minOut !== minOut.toString()) return noted("the quote's facts disagree on the minimum", "price_check_failed");
     return checkRoute(chainId, d2, own(pools, chainId), call, tokenIn, tokenOut);
   };
 }
@@ -807,7 +824,9 @@ var curveVerifyQuote = curveQuoteCheck();
 var curvePins = Object.freeze({
   callTargets: (chain) => routerFor(CURVE_DEPLOYMENTS, chain),
   spenders: (chain) => routerFor(CURVE_DEPLOYMENTS, chain),
-  verifyQuote: curveVerifyQuote
+  verifyQuote: curveVerifyQuote,
+  // The reason of each text verifyQuote returned (remoteProvider puts it on its refusal).
+  reasonOf: notes.reasonOf
 });
 function routerFor(deployments, chain) {
   const d2 = deploymentOf(deployments, chainIdOf(chain));
@@ -824,21 +843,21 @@ function curveOnChain(opts) {
     if (!p) {
       const d2 = deploymentOf(deployments, chainId);
       p = (async () => {
-        if (!d2) throw new Error(`curve: no pinned router on chain ${chainId}`);
+        if (!d2) throw (0, import_errors3.refusal)("unsupported_pair", `curve: no pinned router on chain ${chainId}`);
         const [code, version, listed] = await rpc(chainId, [
           { method: "eth_getCode", params: [d2.router, "latest"] },
           ethCall(d2.router, (0, import_viem3.encodeFunctionData)({ abi: VERSION_ABI, functionName: "version" })),
           ethCall(d2.addressProvider, (0, import_viem3.encodeFunctionData)({ abi: ADDRESS_PROVIDER_ABI, functionName: "get_address", args: [2n] }))
         ]);
         if (typeof code !== "string" || code.length <= 2 || lc2((0, import_viem3.keccak256)(code)) !== lc2(d2.codeHash)) {
-          throw new Error(`curve: the router on chain ${chainId} is not the pinned code (code hash mismatch) \u2014 refusing`);
+          throw (0, import_errors3.refusal)("vault_mismatch", `curve: the router on chain ${chainId} is not the pinned code (code hash mismatch) \u2014 refusing`);
         }
         let v = "";
         try {
           v = typeof version === "string" ? (0, import_viem3.decodeFunctionResult)({ abi: VERSION_ABI, functionName: "version", data: version }) : "";
         } catch {
         }
-        if (v !== d2.version) throw new Error(`curve: the router on chain ${chainId} reports version ${v || "none"}, not ${d2.version} \u2014 refusing`);
+        if (v !== d2.version) throw (0, import_errors3.refusal)("vault_mismatch", `curve: the router on chain ${chainId} reports version ${v || "none"}, not ${d2.version} \u2014 refusing`);
         const ap = wordAddress(listed);
         if (ap && ap !== lc2(d2.addressProviderRouter) && ap !== lc2(d2.router)) {
           warn(`curve: the AddressProvider on ${d2.label} lists router ${ap} (id 2); this module keeps the pinned ${d2.router}`);
@@ -856,17 +875,17 @@ function curveOnChain(opts) {
   async function inspectSealed(quote, tx, probe) {
     const chainId = curveIntentChain(quote.intentId);
     const d2 = chainId === null ? void 0 : deploymentOf(deployments, chainId);
-    if (chainId === null || !d2) return "the quote is not a Curve swap on a pinned chain";
+    if (chainId === null || !d2) return noted("the quote is not a Curve swap on a pinned chain", "policy_refused");
     const quoted = quote.txRequest;
-    if (!quoted?.data || !quoted.to || !tx.data) return "the quote or the transaction carries no router call";
-    if (tx.data.length !== quoted.data.length || lc2(tx.data) !== lc2(quoted.data)) return "the transaction is not the quoted router call";
-    if (!isAddress(tx.to) || lc2(tx.to) !== lc2(d2.router) || lc2(quoted.to) !== lc2(d2.router)) return `the transaction calls ${tx.to}, not the Curve router`;
-    if ((tx.value ?? "0") !== (quoted.value ?? "0")) return "the transaction's value is not the quote's";
-    if (tx.chainId !== void 0 && tx.chainId !== chainId || quoted.chainId !== void 0 && quoted.chainId !== chainId) return `the transaction is not for chain ${chainId}`;
-    if ((tx.approvalAddress ?? "").toLowerCase() !== (quoted.approvalAddress ?? "").toLowerCase()) return "the transaction's approval is not the quote's";
+    if (!quoted?.data || !quoted.to || !tx.data) return noted("the quote or the transaction carries no router call", "policy_refused");
+    if (tx.data.length !== quoted.data.length || lc2(tx.data) !== lc2(quoted.data)) return noted("the transaction is not the quoted router call", "policy_refused");
+    if (!isAddress(tx.to) || lc2(tx.to) !== lc2(d2.router) || lc2(quoted.to) !== lc2(d2.router)) return noted(`the transaction calls ${tx.to}, not the Curve router`, "vault_mismatch");
+    if ((tx.value ?? "0") !== (quoted.value ?? "0")) return noted("the transaction's value is not the quote's", "policy_refused");
+    if (tx.chainId !== void 0 && tx.chainId !== chainId || quoted.chainId !== void 0 && quoted.chainId !== chainId) return noted(`the transaction is not for chain ${chainId}`, "policy_refused");
+    if ((tx.approvalAddress ?? "").toLowerCase() !== (quoted.approvalAddress ?? "").toLowerCase()) return noted("the transaction's approval is not the quote's", "vault_mismatch");
     const call = decodeExchange(d2.family, quoted.data);
-    if (!call || call.selector !== EXCHANGE_SELECTOR[d2.family]) return "the quoted call is not the explicit-receiver exchange";
-    if (call.minDy <= 0n) return "the swap has no minimum (min_dy 0)";
+    if (!call || call.selector !== EXCHANGE_SELECTOR[d2.family]) return noted("the quoted call is not the explicit-receiver exchange", "policy_refused");
+    if (call.minDy <= 0n) return noted("the swap has no minimum (min_dy 0)", "price_check_failed");
     const last = lastToken(call);
     const reason = checkRoute(chainId, d2, own(pools, chainId), call, call.route[0], last);
     if (reason) return reason;
@@ -882,8 +901,8 @@ function curveOnChain(opts) {
     const poolReason = await poolsReason(chainId, hops, res.slice(1, 1 + reads.length));
     if (poolReason) return poolReason;
     const out = wordUint(res[0]);
-    if (out === null) return "the router no longer quotes this route";
-    if (out < call.minDy) return `price moved \u2014 the pools now pay ${out}, under your minimum ${call.minDy}`;
+    if (out === null) return noted("the router no longer quotes this route", "simulation_failed");
+    if (out < call.minDy) return noted(`price moved \u2014 the pools now pay ${out}, under your minimum ${call.minDy}`, "price_check_failed");
     return { out, probeOut: probe && probeIn > 0n ? wordUint(res[probeAt]) : null, amount: call.amount, minDy: call.minDy };
   }
   function poolCalls(list) {
@@ -897,19 +916,19 @@ function curveOnChain(opts) {
     const retry = [];
     for (const pool of list) {
       const code = res[at++];
-      if (typeof code !== "string") return `could not read pool ${pool.name} (${pool.address}) over RPC`;
-      if (code.length <= 2 || lc2((0, import_viem3.keccak256)(code)) !== lc2(pool.codeHash)) return `pool ${pool.name} (${pool.address}) is not the pinned code`;
+      if (typeof code !== "string") return noted(`could not read pool ${pool.name} (${pool.address}) over RPC`, "upstream_unavailable");
+      if (code.length <= 2 || lc2((0, import_viem3.keccak256)(code)) !== lc2(pool.codeHash)) return noted(`pool ${pool.name} (${pool.address}) is not the pinned code`, "vault_mismatch");
       for (let k = 0; k < pool.coins.length; k++) {
         const coin = wordAddress(res[at++]);
         if (coin === null) retry.push({ pool, k });
-        else if (coin !== lc2(pool.coins[k])) return `pool ${pool.name} now reports coin ${k} = ${coin}, not the pinned ${pool.coins[k]}`;
+        else if (coin !== lc2(pool.coins[k])) return noted(`pool ${pool.name} now reports coin ${k} = ${coin}, not the pinned ${pool.coins[k]}`, "vault_mismatch");
       }
     }
     if (retry.length) {
       const again = await rpc(chainId, retry.map(({ pool, k }) => ethCall(pool.address, `${COINS_INT}${k.toString(16).padStart(64, "0")}`)));
       for (const [n, { pool, k }] of retry.entries()) {
         const coin = wordAddress(again[n]);
-        if (coin !== lc2(pool.coins[k])) return `pool ${pool.name} does not report its pinned coin ${k}`;
+        if (coin !== lc2(pool.coins[k])) return noted(`pool ${pool.name} does not report its pinned coin ${k}`, "vault_mismatch");
       }
     }
     return null;
@@ -935,8 +954,10 @@ function curveRemotePins(opts) {
     callTargets: (c) => routerFor(deployments, c),
     spenders: (c) => routerFor(deployments, c),
     verifyQuote,
+    // The reason of each text verifyQuote / verifyBuild returned (remoteProvider puts it on its refusal).
+    reasonOf: notes.reasonOf,
     async verifyBuild(quote, tx, params) {
-      if (!params) return "the request this quote answered is unknown";
+      if (!params) return noted("the request this quote answered is unknown", "policy_refused");
       const reason = verifyQuote(params, quote);
       if (reason) return reason;
       try {
@@ -948,15 +969,15 @@ function curveRemotePins(opts) {
         try {
           dest = BigInt(quote.destAmount);
         } catch {
-          return "the quote names no output";
+          return noted("the quote names no output", "upstream_unavailable");
         }
         const bps = params.slippageBps ?? fixedSlippage ?? Math.min(9999, curveAutoSlippageBps(params, curveImpactBps(amount, out, probeOut)) + CURVE_AUTO_SLIPPAGE_DRIFT_BPS);
-        if ((0, import_validate.slippageFloor)(dest, bps) > out) return `the quote promises ${dest}, more than ${bps} bps above the ${out} the pools pay now`;
+        if ((0, import_validate.slippageFloor)(dest, bps) > out) return noted(`the quote promises ${dest}, more than ${bps} bps above the ${out} the pools pay now`, "price_check_failed");
         const fresh = dest < out ? dest : out;
-        if (minDy < (0, import_validate.slippageFloor)(fresh, bps)) return `the swap's minimum ${minDy} is more than ${bps} bps under the ${fresh} the pools pay now`;
+        if (minDy < (0, import_validate.slippageFloor)(fresh, bps)) return noted(`the swap's minimum ${minDy} is more than ${bps} bps under the ${fresh} the pools pay now`, "price_check_failed");
         return null;
       } catch (e) {
-        return e instanceof Error ? e.message.replace(/^curve: /, "") : String(e);
+        return noted(e instanceof Error ? e.message.replace(/^curve: /, "") : String(e), (0, import_errors3.refusalOf)(e));
       }
     }
   });
@@ -994,46 +1015,47 @@ function curveProvider(config) {
       return from.chain === to.chain && chainIdOf2(from.chain) !== null;
     },
     async getQuote(params, signal) {
-      const refuse = (why) => {
-        params.onRefusal?.(`curve: ${why}`);
+      const refuse = (why, info) => {
+        if (info === void 0) params.onRefusal?.(`curve: ${why}`);
+        else params.onRefusal?.(`curve: ${why}`, typeof info === "string" ? { reason: info } : info);
         return null;
       };
-      if (params.flex) return refuse("amount-flexible deposits are not supported");
-      if (params.sourceChain !== params.destChain) return refuse("same-chain swaps only");
+      if (params.flex) return refuse("amount-flexible deposits are not supported", "unsupported_pair");
+      if (params.sourceChain !== params.destChain) return refuse("same-chain swaps only", "unsupported_pair");
       const chainId = chainIdOf2(params.sourceChain);
-      if (chainId === null) return refuse(`no Curve router, pool allowlist or RPC for ${params.sourceChain}`);
+      if (chainId === null) return refuse(`no Curve router, pool allowlist or RPC for ${params.sourceChain}`, "unsupported_pair");
       const d2 = deploymentOf(deployments, chainId);
       const src = (0, import_util5.sourceAssetOf)(params);
-      if (!src) return refuse(`unknown source token ${params.sourceToken}`);
+      if (!src) return refuse(`unknown source token ${params.sourceToken}`, "unsupported_pair");
       const nativeIn = !src.contract;
       const nativeOut = /^0x0+$/.test(params.destToken);
-      if (!nativeOut && !/^0x[0-9a-fA-F]{40}$/.test(params.destToken)) return refuse("destination token must be an EVM address");
-      if (!/^0x[0-9a-fA-F]{40}$/.test(params.destAddress)) return refuse("recipient must be an EVM address");
+      if (!nativeOut && !/^0x[0-9a-fA-F]{40}$/.test(params.destToken)) return refuse("destination token must be an EVM address", "unsupported_pair");
+      if (!/^0x[0-9a-fA-F]{40}$/.test(params.destAddress)) return refuse("recipient must be an EVM address", "recipient_mismatch");
       let amountIn;
       try {
         amountIn = BigInt(params.amountIn);
       } catch {
         return refuse("amount is not an integer");
       }
-      if (amountIn <= 0n) return refuse("amount must be positive");
+      if (amountIn <= 0n) return refuse("amount must be positive", "amount_too_small");
       if (params.slippageBps !== void 0 && (!Number.isInteger(params.slippageBps) || params.slippageBps < 0 || params.slippageBps >= 1e4)) return refuse("slippage must be 0..9999 bps");
-      if (!nativeIn && src.contract.toLowerCase() === d2.eth.toLowerCase()) return refuse("the native coin is named by the catalog, not by the router's 0xEeee sentinel");
-      if (!nativeOut && params.destToken.toLowerCase() === d2.eth.toLowerCase()) return refuse("name a native output with the zero address, not the router's 0xEeee sentinel");
+      if (!nativeIn && src.contract.toLowerCase() === d2.eth.toLowerCase()) return refuse("the native coin is named by the catalog, not by the router's 0xEeee sentinel", "unsupported_pair");
+      if (!nativeOut && params.destToken.toLowerCase() === d2.eth.toLowerCase()) return refuse("name a native output with the zero address, not the router's 0xEeee sentinel", "unsupported_pair");
       const tokenIn = (0, import_viem4.getAddress)(nativeIn ? d2.eth : src.contract);
       const tokenOut = (0, import_viem4.getAddress)(nativeOut ? d2.eth : params.destToken);
-      if (tokenIn === tokenOut) return refuse("same token in and out");
+      if (tokenIn === tokenOut) return refuse("same token in and out", "unsupported_pair");
       const wrapPair = [(0, import_viem4.getAddress)(d2.eth), (0, import_viem4.getAddress)(d2.weth)];
-      if (wrapPair.includes(tokenIn) && wrapPair.includes(tokenOut)) return refuse("that is a wrap/unwrap, not a swap");
+      if (wrapPair.includes(tokenIn) && wrapPair.includes(tokenOut)) return refuse("that is a wrap/unwrap, not a swap", "unsupported_pair");
       try {
         await chain.verifyDeployment(chainId);
         const { routes, truncated } = findRoutes(chainId, d2, tableOf(chainId), tokenIn, tokenOut);
-        if (!routes.length) return refuse("no allowlisted Curve pool route for this pair");
+        if (!routes.length) return refuse("no allowlisted Curve pool route for this pair", "no_route");
         const outs = await price(chainId, d2, routes, amountIn, signal);
         let best = null;
         outs.forEach((out2, i) => {
           if (out2 !== null && out2 > 0n && (!best || out2 > best.out)) best = { route: routes[i], out: out2 };
         });
-        if (!best) return refuse("no allowlisted Curve pool quotes this pair and amount");
+        if (!best) return refuse("no allowlisted Curve pool quotes this pair and amount", "no_route");
         const { route, out } = best;
         let priceImpactBps;
         const probeIn = amountIn / 1000n;
@@ -1046,9 +1068,9 @@ function curveProvider(config) {
         }
         const bps = params.slippageBps ?? fixedSlippage ?? curveAutoSlippageBps(params, priceImpactBps);
         const minOut = out * BigInt(1e4 - bps) / 10000n;
-        if (minOut <= 0n) return refuse("the minimum rounds to zero for this amount");
+        if (minOut <= 0n) return refuse("the minimum rounds to zero for this amount", "amount_too_small");
         if (params.minAmountOut !== void 0 && minOut < BigInt(params.minAmountOut)) {
-          return refuse(`floor breach (min=${minOut} < floor=${params.minAmountOut})`);
+          return refuse(`floor breach (min=${minOut} < floor=${params.minAmountOut})`, "price_check_failed");
         }
         const args = routeArgs(d2.family, route);
         const recipient = (0, import_viem4.getAddress)(params.destAddress);
@@ -1090,10 +1112,10 @@ function curveProvider(config) {
           }
         };
         const why = selfCheck(params, quote);
-        if (why) return refuse(`built a call its own check refuses (${why})`);
+        if (why) return refuse(`built a call its own check refuses (${why})`, notes.reasonOf(why) ?? "policy_refused");
         return quote;
       } catch (e) {
-        return refuse(e instanceof Error ? e.message.replace(/^curve: /, "") : String(e));
+        return refuse(e instanceof Error ? e.message.replace(/^curve: /, "") : String(e), (0, import_errors4.refusalOf)(e));
       }
     },
     /**
@@ -1103,11 +1125,11 @@ function curveProvider(config) {
      */
     async preflightDeposit(quote, tx) {
       const reason = await chain.checkSealed(quote, tx);
-      if (reason) throw new Error(`curve: ${reason}. Nothing was sent; refresh the quote.`);
+      if (reason) throw tagged(new Error(`curve: ${reason}. Nothing was sent; refresh the quote.`), notes.reasonOf(reason));
     },
     async buildDeposit(quote) {
       const tx = quote.txRequest;
-      if (!tx?.to || !tx.data) throw new Error("swap2: Curve quote has no transaction request");
+      if (!tx?.to || !tx.data) throw (0, import_errors4.refusal)("policy_refused", "swap2: Curve quote has no transaction request");
       return {
         chain: "",
         to: tx.to,