@oracle-agent/oracle 0.14.1 → 0.15.0

package/src/rfq/sources.mjs

@@ -1,181 +0,0 @@
-import { lifiQuote } from "../data/providers/lifi.mjs";
-import { paraswapPrice } from "../data/providers/paraswap.mjs";
-import { zeroxQuote } from "../data/providers/zerox.mjs";
-import { cowQuote } from "../data/providers/cowswap.mjs";
-import { uniV3QuoteExactIn, UNI_V3_CHAINS } from "../data/providers/uniswap-v3.mjs";
-import { normalizeFirmQuote } from "./intent.mjs";
-
-function allowed(intent, source) {
-  return Array.isArray(intent?.allowedSources) && intent.allowedSources.includes(source);
-}
-
-function envValue(env, key) {
-  return String(env?.[key] ?? "").trim();
-}
-
-function candidate(source, run) {
-  return Object.freeze({ source, run });
-}
-
-export function sourceCandidates(intent, opts = {}) {
-  if (!intent || intent.kind !== "rfq-intent") throw new Error("rfq: intent required");
-  const env = opts.env ?? process.env;
-  const providers = opts.providers ?? {};
-  const uniChains = opts.supportedUniV3Chains ?? UNI_V3_CHAINS;
-  const sameChain = Number(intent.fromChainId) === Number(intent.toChainId);
-  const out = [];
-  if (allowed(intent, "lifi")) {
-    out.push(candidate("lifi", async () => {
-      const fn = providers.lifiQuote ?? lifiQuote;
-      const q = await fn({
-        fromChain: intent.fromChainId,
-        toChain: intent.toChainId,
-        fromToken: intent.sellToken,
-        toToken: intent.buyToken,
-        fromAmount: intent.sellAmount,
-        fromAddress: intent.receiver,
-      }, opts);
-      const est = q?.estimate ?? q?.[0]?.estimate ?? q;
-      return {
-        quoteId: q?.id ?? q?.routeId ?? null,
-        amountOut: est?.toAmount ?? q?.toAmount,
-        minBuyAmount: est?.toAmountMin ?? q?.toAmountMin ?? est?.toAmount ?? q?.toAmount,
-        expiryMs: Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000),
-        artifact: { type: "lifi-route", calldataHash: q?.transactionRequest?.data ? await hashMaybe(opts, q.transactionRequest.data) : undefined, route: q },
-        metadata: { tool: q?.tool ?? q?.toolDetails?.name ?? null },
-      };
-    }));
-  }
-  if (!sameChain) return out;
-  if (allowed(intent, "paraswap")) {
-    out.push(candidate("paraswap", async () => {
-      const fn = providers.paraswapPrice ?? paraswapPrice;
-      const q = await fn({
-        chainId: intent.fromChainId,
-        srcToken: intent.sellToken,
-        destToken: intent.buyToken,
-        amount: intent.sellAmount,
-        srcDecimals: opts.decimalsIn,
-        destDecimals: opts.decimalsOut,
-      }, opts);
-      const pr = q?.priceRoute ?? q;
-      return {
-        quoteId: pr?.id ?? null,
-        amountOut: pr?.destAmount,
-        minBuyAmount: q?.amountOutMinimum ?? pr?.destAmount,
-        expiryMs: Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000),
-        artifact: { type: "paraswap-price-route", route: pr },
-        metadata: { contractAddress: pr?.contractAddress ?? null },
-      };
-    }));
-  }
-  if (allowed(intent, "0x") && (envValue(env, "ZEROX_API_KEY") || envValue(env, "0X_API_KEY") || providers.zeroxQuote)) {
-    out.push(candidate("0x", async () => {
-      const fn = providers.zeroxQuote ?? zeroxQuote;
-      const q = await fn({ chainId: intent.fromChainId, sellToken: intent.sellToken, buyToken: intent.buyToken, sellAmount: intent.sellAmount, taker: intent.receiver }, opts);
-      return {
-        quoteId: q?.id ?? null,
-        amountOut: q?.buyAmount ?? q?.grossBuyAmount,
-        minBuyAmount: q?.minBuyAmount ?? q?.buyAmount,
-        expiryMs: Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000),
-        artifact: { type: "0x-transaction", to: q?.transaction?.to, data: q?.transaction?.data, value: q?.transaction?.value ?? "0" },
-        metadata: { route: q?.route ?? null },
-      };
-    }));
-  }
-  if (allowed(intent, "cow")) {
-    out.push(candidate("cow", async () => {
-      const fn = providers.cowQuote ?? cowQuote;
-      const q = await fn({ chainId: intent.fromChainId, sellToken: intent.sellToken, buyToken: intent.buyToken, sellAmountBeforeFee: intent.sellAmount, from: intent.receiver, signingScheme: "eip712" }, opts);
-      const quote = q?.quote ?? q;
-      return {
-        quoteId: q?.id ?? null,
-        amountOut: quote?.buyAmount,
-        minBuyAmount: quote?.buyAmount,
-        expiryMs: Math.min(Number(quote?.validTo ?? 0) * 1000 || Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000), intent.deadlineMs),
-        artifact: { type: "cow-order", order: quote },
-        metadata: { solver: true },
-      };
-    }));
-  }
-  if (allowed(intent, "uniswap-v3") && uniChains[Number(intent.fromChainId)]) {
-    out.push(candidate("uniswap-v3", async () => {
-      const fn = providers.uniV3QuoteExactIn ?? uniV3QuoteExactIn;
-      const q = await fn({ chainId: intent.fromChainId, tokenIn: intent.sellToken, tokenOut: intent.buyToken, amountIn: intent.sellAmount }, opts);
-      return {
-        quoteId: q?.id ?? null,
-        amountOut: q?.amountOut,
-        minBuyAmount: q?.minOut ?? q?.amountOutMinimum ?? q?.amountOut,
-        expiryMs: Date.now() + Number(opts.defaultQuoteTtlMs ?? 20_000),
-        artifact: { type: "uniswap-v3-quote", quoter: q?.quoter, fee: q?.fee },
-        metadata: { onchain: true },
-      };
-    }));
-  }
-  return out;
-}
-
-async function hashMaybe(opts, value) {
-  const crypto = await import("node:crypto");
-  return `0x${crypto.createHash("sha256").update(String(value)).digest("hex")}`;
-}
-
-async function runWithTimeout(c, timeoutMs) {
-  return Promise.race([
-    Promise.resolve().then(c.run),
-    new Promise((_, reject) => setTimeout(() => reject(new Error(`${c.source}: timeout`)), timeoutMs)),
-  ]);
-}
-
-export async function executeRfqCandidates(intent, candidates, opts = {}) {
-  const timeoutMs = Number(opts.timeoutMs ?? 12_000);
-  const settled = await Promise.allSettled(candidates.map((c) => runWithTimeout(c, timeoutMs)));
-  const quotes = [];
-  const failed = [];
-  for (let i = 0; i < settled.length; i++) {
-    const c = candidates[i];
-    const r = settled[i];
-    if (r.status === "rejected") {
-      failed.push({ source: c.source, error: String(r.reason?.message || r.reason) });
-      continue;
-    }
-    try {
-      quotes.push(normalizeFirmQuote(intent, { ...r.value, source: c.source }, opts));
-    } catch (e) {
-      failed.push({ source: c.source, error: String(e?.message || e) });
-    }
-  }
-  return { quotes, failed };
-}
-
-export function rankRfqQuotes(quotes = [], opts = {}) {
-  const nowMs = Number(opts.nowMs ?? Date.now());
-  const usable = quotes.filter((q) => Number(q.expiryMs ?? 0) > nowMs);
-  usable.sort((a, b) => {
-    const floor = BigInt(b.minBuyAmount ?? 0) - BigInt(a.minBuyAmount ?? 0);
-    if (floor !== 0n) return floor > 0n ? 1 : -1;
-    const gross = BigInt(b.amountOut ?? 0) - BigInt(a.amountOut ?? 0);
-    return gross > 0n ? 1 : gross < 0n ? -1 : 0;
-  });
-  const ranked = usable.map((q) => ({ ...q, scoreBasis: "minBuyAmount" }));
-  const warnings = [];
-  if (!ranked.length) warnings.push("no RFQ source returned a usable firm quote");
-  if (quotes.length !== ranked.length) warnings.push("expired RFQ quotes were excluded from ranking");
-  return { best: ranked[0] ?? null, quotes: ranked, failed: [], warnings };
-}
-
-export async function requestRfqQuotes(intent, opts = {}) {
-  const candidates = sourceCandidates(intent, opts);
-  const { quotes, failed } = await executeRfqCandidates(intent, candidates, opts);
-  const ranked = rankRfqQuotes(quotes, opts);
-  return {
-    kind: "rfq-result",
-    intent,
-    best: ranked.best,
-    quotes: ranked.quotes,
-    failed,
-    warnings: [...ranked.warnings],
-    sourcesTried: candidates.length,
-    sourcesAnswered: quotes.length,
-  };
-}

package/src/route-attestation.mjs

@@ -1,132 +0,0 @@
-import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-import { isAddress } from "ethers";
-import { assertAutoSlippageGuard } from "./auto-slippage.mjs";
-import { resolveAttestationSecret } from "./attestation-secret.mjs";
-import { assertFreshWindow } from "./fresh-window.mjs";
-
-const DEFAULT_ROUTE_ATTESTATION_TTL_MS = 20_000;
-
-function canonicalJson(value) {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-  if (value && typeof value === "object") {
-    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
-  }
-  return JSON.stringify(value);
-}
-
-function normalAddress(value, label) {
-  const text = String(value || "").trim();
-  if (!isAddress(text)) throw new Error(`${label} must be an address`);
-  return text.toLowerCase();
-}
-
-function normalData(value) {
-  const data = String(value || "0x").toLowerCase();
-  if (!/^0x(?:[0-9a-f]{2})*$/.test(data)) throw new Error("route attestation calldata must be hex bytes");
-  return data;
-}
-
-function hashText(value) {
-  return `0x${createHash("sha256").update(String(value)).digest("hex")}`;
-}
-
-function hmac(secret, payload) {
-  return `0x${createHmac("sha256", String(secret)).update(payload).digest("hex")}`;
-}
-
-function sameSignature(a, b) {
-  const left = Buffer.from(String(a || "").replace(/^0x/, ""), "hex");
-  const right = Buffer.from(String(b || "").replace(/^0x/, ""), "hex");
-  return left.length === right.length && left.length > 0 && timingSafeEqual(left, right);
-}
-
-function routeSecret(secret) {
-  return resolveAttestationSecret(
-    secret,
-    "ORACLE_ROUTE_ATTESTATION_SECRET",
-    "MAD_ROUTE_ATTESTATION_SECRET",
-  );
-}
-
-function unsigned(attestation) {
-  const { signature: _signature, ...payload } = attestation;
-  return payload;
-}
-
-export function routeCalldataHash(data) {
-  return hashText(normalData(data));
-}
-
-export function routeSlippageHash(slippageGuard) {
-  if (!slippageGuard) throw new Error("route attestation requires slippage guard");
-  return hashText(canonicalJson(slippageGuard));
-}
-
-export function createRouteAttestation({
-  provider,
-  chainId,
-  sender,
-  to,
-  destination,
-  data,
-  value = "0",
-  slippageGuard,
-  nowMs = Date.now(),
-  ttlMs = DEFAULT_ROUTE_ATTESTATION_TTL_MS,
-  secret,
-} = {}) {
-  const target = normalAddress(destination || to, "route destination");
-  const attestation = {
-    mode: "route-attestation",
-    version: 1,
-    provider: String(provider || "").trim(),
-    chainId: Number(chainId),
-    sender: sender ? normalAddress(sender, "route sender") : null,
-    destination: target,
-    calldataHash: routeCalldataHash(data),
-    value: String(value ?? "0"),
-    slippageHash: routeSlippageHash(slippageGuard),
-    issuedAtMs: Number(nowMs),
-    expiresAtMs: Number(nowMs) + Number(ttlMs),
-  };
-  if (!attestation.provider) throw new Error("route attestation provider required");
-  if (!Number.isFinite(attestation.chainId)) throw new Error("route attestation chainId required");
-  const payload = canonicalJson(attestation);
-  return { ...attestation, signature: hmac(routeSecret(secret), payload) };
-}
-
-export function assertRouteAttestation(attestation, tx = {}, { chainId, nowMs = Date.now(), secret } = {}) {
-  // Time is a security parameter: an unusable clock must fail CLOSED,
-  // otherwise NaN/null/-Infinity silently makes this attestation eternal.
-  assertFreshWindow(attestation || {}, nowMs, "route attestation");
-  if (!attestation || attestation.mode !== "route-attestation") throw new Error("route attestation required");
-  if (Number(attestation.expiresAtMs) <= Number(nowMs)) throw new Error("route attestation expired");
-  if (Number(attestation.chainId) !== Number(chainId ?? tx.chainId)) throw new Error("route attestation chain mismatch");
-  const to = normalAddress(tx.to, "route tx.to");
-  if (normalAddress(attestation.destination, "route destination") !== to) throw new Error("route attestation destination mismatch");
-  if (tx.from && attestation.sender && normalAddress(attestation.sender, "route sender") !== normalAddress(tx.from, "route tx.from")) {
-    throw new Error("route attestation sender mismatch");
-  }
-  if (String(attestation.value) !== String(tx.value ?? "0")) throw new Error("route attestation value mismatch");
-  if (attestation.calldataHash !== routeCalldataHash(tx.data || "0x")) throw new Error("route attestation calldata mismatch");
-  if (attestation.slippageHash !== routeSlippageHash(tx.slippageGuard ?? tx.madSlippage)) {
-    throw new Error("route attestation slippage mismatch");
-  }
-  const expected = hmac(routeSecret(secret), canonicalJson(unsigned(attestation)));
-  if (!sameSignature(attestation.signature, expected)) throw new Error("route attestation signature mismatch");
-  // Third call site. exec-policy and protocol-execution both demand an
-  // authenticated, calldata-bound guard; this path asked for neither, so a
-  // dynamic route destination got a weaker slippage check than a static one.
-  // The attestation's own calldataHash/slippageHash made it non-exploitable,
-  // but a guard boundary that differs by which door you came through is the
-  // shape every one of these findings has had. Same bar on all three.
-  assertAutoSlippageGuard(tx.slippageGuard ?? tx.madSlippage, {
-    chainId: Number(chainId ?? tx.chainId),
-    venue: to,
-    nowMs,
-    secret,
-    tx: { ...tx, chainId: Number(chainId ?? tx.chainId), to, data: tx.data },
-    requireSigned: true,
-  });
-  return true;
-}

package/src/router/best-execution.mjs

@@ -1,326 +0,0 @@
-// Best-execution router.
-//
-// The naive version of this picks the biggest amountOut and calls it a day. That is
-// wrong often enough to matter, for three reasons:
-//
-//   1. GAS IS PART OF THE PRICE. A route that returns 0.2% more but costs $14 more
-//      in gas is worse on a $500 swap and better on a $50k one. The crossover point
-//      depends on trade size, so a fixed preference for "best quote" is wrong on one
-//      side of it. We convert gas to the destination asset and subtract.
-//
-//   2. QUOTES ARE NOT COMMITMENTS. Aggregators return an expected output that moves
-//      with the block. What protects you is minOut, so a route with a tight quote and
-//      a hard guarantee can beat a fatter quote with a loose one.
-//
-//   3. SOURCES DISAGREE ABOUT WHAT THEY MEAN. Some return amounts net of fees, some
-//      gross; some price gas in native, some in USD, some not at all. Comparing raw
-//      fields across them is comparing different things wearing the same name.
-//
-// So: normalize every source to one shape, mark what is MEASURED vs MISSING, and rank
-// on net output. Where a cost is unknown we say so rather than treating it as zero --
-// silently scoring an unknown as free is how the worst route wins a comparison.
-
-import { EVIDENCE } from "../scanner/contract.mjs";
-
-/** How a route's numbers were obtained. Drives both ranking and disclosure. */
-export const QUALITY = Object.freeze({
-  // Output and gas both measured. Directly comparable.
-  FULL: "FULL",
-  // Output measured, gas unknown. Comparable only with the caveat stated.
-  NO_GAS: "NO_GAS",
-  // Source errored or returned nothing usable.
-  FAILED: "FAILED",
-});
-
-/** Chain -> the coingecko-ish key DefiLlama uses for the native asset. */
-const NATIVE_PRICE_KEY = {
-  1: "coingecko:ethereum",
-  10: "coingecko:ethereum",
-  56: "coingecko:binancecoin",
-  137: "coingecko:matic-network",
-  8453: "coingecko:ethereum",
-  42161: "coingecko:ethereum",
-  43114: "coingecko:avalanche-2",
-  999: "coingecko:ethereum",
-};
-
-const bn = (v) => {
-  try {
-    if (v == null || v === "") return null;
-    return BigInt(String(v).split(".")[0]);
-  } catch {
-    return null;
-  }
-};
-
-/**
- * Normalize one source's response into the shape the ranker consumes.
- *
- * Every field is explicit about whether it was measured. `gasUsd: null` means "we do
- * not know", never "free".
- */
-export function normalizeRoute(raw) {
-  const {
-    source,
-    amountOut,
-    minOut = null,
-    gasUsd = null,
-    feeUsd = null,
-    estimatedGas = null,
-    error = null,
-    executionReady = false,
-    meta = {},
-  } = raw || {};
-
-  if (error || amountOut == null) {
-    return {
-      source,
-      quality: QUALITY.FAILED,
-      amountOut: null,
-      error: error || "no amountOut returned",
-    };
-  }
-
-  const out = bn(amountOut);
-  if (out == null || out <= 0n) {
-    return { source, quality: QUALITY.FAILED, amountOut: null, error: "non-positive amountOut" };
-  }
-
-  return {
-    source,
-    quality: gasUsd == null ? QUALITY.NO_GAS : QUALITY.FULL,
-    amountOut: out.toString(),
-    minOut: bn(minOut)?.toString() ?? null,
-    gasUsd,
-    feeUsd,
-    estimatedGas: estimatedGas == null ? null : String(estimatedGas),
-    executionReady,
-    meta,
-  };
-}
-
-/**
- * Measure how badly a route's price decays with size.
- *
- * WHY THIS EXISTS: a quote against a drained pool is indistinguishable, in shape,
- * from a quote against a deep one -- same fields, no error, just a smaller number.
- * Verified on Robinhood 2026-08-02: a dead Uniswap V3 SQUEEZE pool holding 7.03
- * USDG happily quoted a 205,374-token sell, and every layer downstream treated
- * that as truth. `minOut` does NOT protect against this: it guards the price
- * MOVING between quote and fill, so against a garbage quote it faithfully locks
- * in the garbage.
- *
- * The probe: quote a small slice of the same trade, compare per-unit prices. Real
- * slippage decays smoothly with size; a drained pool falls off a cliff.
- *
- * `probeFn(amountIn) -> amountOut | null`. Returns null when the comparison could
- * not be made, which callers MUST treat as unproven rather than as a pass.
- */
-export async function measurePriceImpact(probeFn, amountIn, { divisor = 1000n } = {}) {
-  const full = bn(amountIn);
-  if (full == null || full <= 0n) return null;
-
-  const probeAmt = full / divisor > 0n ? full / divisor : 1n;
-  if (probeAmt >= full) return null; // too small to compare against itself
-
-  let smallOut;
-  let fullOut;
-  try {
-    [smallOut, fullOut] = await Promise.all([probeFn(probeAmt), probeFn(full)]);
-  } catch {
-    return null;
-  }
-
-  const s = bn(smallOut);
-  const f = bn(fullOut);
-  if (s == null || f == null || s <= 0n) return null;
-
-  // Scale to compare per-unit prices without floating point until the last step.
-  const smallPx = Number(s) / Number(probeAmt);
-  const fullPx = Number(f) / Number(full);
-  if (!Number.isFinite(smallPx) || !Number.isFinite(fullPx) || smallPx <= 0) return null;
-
-  return {
-    impactPct: (1 - fullPx / smallPx) * 100,
-    probeAmountIn: probeAmt.toString(),
-    probeAmountOut: s.toString(),
-    fullAmountOut: f.toString(),
-  };
-}
-
-/**
- * Reject routes whose price impact exceeds a ceiling.
- *
- * Applied AFTER ranking so the rejection is visible: a caller can see that the
- * nominal winner was dropped and why, rather than silently receiving second place.
- * A route with no impact measurement is NOT dropped here -- absence of evidence is
- * surfaced through `unmeasured` so the caller decides, but it is never presented
- * as a passing measurement.
- */
-export function applyImpactCeiling(ranked, impacts, { maxImpactPct = 25 } = {}) {
-  const rejected = [];
-  const unmeasured = [];
-
-  const kept = (ranked.routes ?? []).filter((r) => {
-    const m = impacts?.[r.source];
-    if (!m) {
-      unmeasured.push(r.source);
-      return true;
-    }
-    if (m.impactPct > maxImpactPct) {
-      rejected.push({
-        source: r.source,
-        impactPct: Number(m.impactPct.toFixed(2)),
-        reason:
-          `price impact ${m.impactPct.toFixed(1)}% exceeds ${maxImpactPct}% ceiling -- ` +
-          "the venue cannot absorb this size near the quoted price",
-      });
-      return false;
-    }
-    return true;
-  });
-
-  const warnings = [...(ranked.warnings ?? [])];
-  if (rejected.length) {
-    warnings.push(
-      `dropped ${rejected.length} route(s) on price impact: ` +
-        rejected.map((r) => `${r.source} (${r.impactPct}%)`).join(", "),
-    );
-  }
-  if (unmeasured.length) {
-    warnings.push(
-      `price impact NOT measured for: ${unmeasured.join(", ")}. These are unproven ` +
-        "against thin liquidity, not proven safe.",
-    );
-  }
-
-  return {
-    ...ranked,
-    routes: kept,
-    best: kept[0] ?? null,
-    impactRejected: rejected,
-    impactUnmeasured: unmeasured,
-    warnings,
-  };
-}
-
-/**
- * Rank normalized routes by NET output.
- *
- * net = amountOut - (gasUsd + feeUsd converted into the destination asset)
- *
- * Requires the destination asset's USD price and decimals to do the conversion. When
- * those are unavailable we fall back to gross ranking and SAY SO in the result, so a
- * caller is never left believing gas was accounted for when it was not.
- */
-export function rankRoutes(routes, { destPriceUsd = null, destDecimals = null } = {}) {
-  const usable = routes.filter((r) => r.quality !== QUALITY.FAILED);
-  const failed = routes.filter((r) => r.quality === QUALITY.FAILED);
-
-  const canNet =
-    destPriceUsd != null && destPriceUsd > 0 && destDecimals != null && destDecimals >= 0;
-
-  const scored = usable.map((r) => {
-    const gross = BigInt(r.amountOut);
-    let costInDest = 0n;
-    let costAccounted = false;
-
-    if (canNet) {
-      const totalCostUsd = (r.gasUsd ?? 0) + (r.feeUsd ?? 0);
-      if (totalCostUsd > 0) {
-        // usd -> destination units
-        const units = (totalCostUsd / destPriceUsd) * 10 ** destDecimals;
-        if (Number.isFinite(units) && units >= 0) {
-          costInDest = BigInt(Math.floor(units));
-          costAccounted = true;
-        }
-      } else if (r.gasUsd === 0) {
-        costAccounted = true; // genuinely gasless (e.g. an intent filled by a solver)
-      }
-    }
-
-    const net = gross > costInDest ? gross - costInDest : 0n;
-    return {
-      ...r,
-      grossOut: gross.toString(),
-      netOut: net.toString(),
-      costInDest: costInDest.toString(),
-      costAccounted,
-    };
-  });
-
-  // Sort by net desc. A route whose gas we could not measure sorts on gross, which
-  // flatters it -- hence the explicit warning below rather than a silent ordering.
-  scored.sort((a, b) => (BigInt(b.netOut) > BigInt(a.netOut) ? 1 : -1));
-
-  const unaccounted = scored.filter((r) => !r.costAccounted).map((r) => r.source);
-  const warnings = [];
-  if (!canNet) {
-    warnings.push(
-      "destination price/decimals unavailable: ranked on GROSS output. Gas is not " +
-        "included, so a cheap-looking route may cost more to execute.",
-    );
-  } else if (unaccounted.length) {
-    warnings.push(
-      `gas not reported by: ${unaccounted.join(", ")}. These are ranked on gross ` +
-        "output and may be overstated relative to gas-measured routes.",
-    );
-  }
-
-  // Spread between the winner and the runner-up -- but ONLY when that comparison is
-  // apples to apples.
-  //
-  // Subtle trap worth naming: computing this from the two best COST-ACCOUNTED routes
-  // while the actual winner has unknown gas produces a number that reads as "the
-  // winner beats second place by X" when it is really "third beats fourth by X".
-  // When the top route's cost is unmeasured, the honest answer is null.
-  let improvementBps = null;
-  let spreadBasis = null;
-  if (scored.length >= 2 && scored[0].costAccounted && scored[1].costAccounted) {
-    const best = BigInt(scored[0].netOut);
-    const next = BigInt(scored[1].netOut);
-    if (next > 0n) {
-      improvementBps = Number(((best - next) * 10_000n) / next);
-      spreadBasis = `${scored[0].source} vs ${scored[1].source}`;
-    }
-  }
-
-  return {
-    best: scored[0] ?? null,
-    routes: scored,
-    failed,
-    improvementBps,
-    spreadBasis,
-    rankedOn: canNet ? "net-of-cost" : "gross",
-    warnings,
-  };
-}
-
-/**
- * Run every candidate source concurrently, tolerating individual failures.
- *
- * One aggregator being down, rate-limited, or missing an API key must never sink the
- * comparison -- that would make the router less reliable than calling a single venue
- * directly, which defeats the purpose.
- */
-export async function gatherRoutes(candidates, { timeoutMs = 12_000 } = {}) {
-  const withTimeout = (p, source) =>
-    Promise.race([
-      p,
-      new Promise((_, rej) => setTimeout(() => rej(new Error(`${source}: timeout`)), timeoutMs)),
-    ]);
-
-  const settled = await Promise.allSettled(
-    candidates.map((c) => withTimeout(Promise.resolve().then(c.run), c.source)),
-  );
-
-  return settled.map((s, i) => {
-    const source = candidates[i].source;
-    if (s.status === "rejected") {
-      return normalizeRoute({ source, error: String(s.reason?.message || s.reason) });
-    }
-    return normalizeRoute({ source, ...s.value });
-  });
-}
-
-export { NATIVE_PRICE_KEY };