@oracle-agent/oracle 0.14.1 → 0.15.0

package/src/router/index.mjs

@@ -1,250 +0,0 @@
-// Public entry point: find the best swap or bridge route.
-//
-// Returns a ranked comparison, not just a winner. Showing the runners-up and the
-// spread is what lets a caller sanity-check the result instead of trusting it -- and
-// a one-source "best route" is not a comparison at all, so that case is labelled
-// rather than presented as if it beat something.
-
-import {
-  gatherRoutes, rankRoutes, QUALITY, measurePriceImpact, applyImpactCeiling,
-} from "./best-execution.mjs";
-import { swapCandidates, bridgeCandidates, nativeUsd } from "./route-sources.mjs";
-import { llamaPrices } from "../data/providers/defillama.mjs";
-
-/** DefiLlama key for an ERC-20 on a given chain. */
-const LLAMA_CHAIN = {
-  1: "ethereum",
-  10: "optimism",
-  56: "bsc",
-  137: "polygon",
-  8453: "base",
-  42161: "arbitrum",
-  43114: "avax",
-};
-
-async function destPrice(chainId, token, opts) {
-  const chain = LLAMA_CHAIN[Number(chainId)];
-  if (!chain) return { priceUsd: null, decimals: null };
-  const key = `${chain}:${token}`;
-  try {
-    const res = await llamaPrices([key], opts);
-    const hit = res?.coins?.[key];
-    const p = Number(hit?.price);
-    const d = Number(hit?.decimals);
-    return {
-      priceUsd: Number.isFinite(p) ? p : null,
-      decimals: Number.isFinite(d) ? d : null,
-    };
-  } catch {
-    return { priceUsd: null, decimals: null };
-  }
-}
-
-/**
- * Best same-chain swap route.
- *
- * @param {object} p
- * @param {number} p.chainId
- * @param {string} p.tokenIn
- * @param {string} p.tokenOut
- * @param {string|bigint} p.amountIn  raw units of tokenIn
- * @param {string} [p.taker]          address used for quoting only
- * @param {number} [p.decimalsIn]     enables ParaSwap
- * @param {number} [p.decimalsOut]    enables ParaSwap + net ranking
- */
-export async function bestSwapRoute(p, opts = {}) {
-  const { chainId, tokenIn, tokenOut, amountIn } = p;
-  if (chainId == null || !tokenIn || !tokenOut || amountIn == null) {
-    throw new Error("bestSwapRoute requires chainId, tokenIn, tokenOut, amountIn");
-  }
-
-  // Prices and quotes run CONCURRENTLY, not one after the other.
-  //
-  // The obvious shape -- await the prices, then fan out the quotes -- adds the price
-  // latency to every single comparison. Measured on Base: ~890ms of DefiLlama in
-  // front of ~3.3s of quotes, for 4.7s total when the true floor is 3.3s.
-  //
-  // Neither price is needed to ASK for a quote:
-  //   * destPrice is only used at RANK time, after every quote has returned
-  //   * nativePriceUsd is only used by the 0x adapter to convert its native-wei gas
-  //     figure, so it is passed as a PROMISE and awaited inside that one adapter
-  //
-  // So the whole price fetch hides behind the slowest quote instead of preceding it.
-  const nativePricePromise = nativeUsd(chainId, opts);
-  const destPromise = destPrice(chainId, tokenOut, opts);
-
-  const candidates = swapCandidates({
-    ...p,
-    nativePriceUsd: nativePricePromise,
-    decimalsOut: p.decimalsOut,
-    destDecimalsPromise: destPromise,
-    opts,
-  });
-
-  const [routes, dest] = await Promise.all([
-    gatherRoutes(candidates, { timeoutMs: opts.timeoutMs ?? 12_000 }),
-    destPromise,
-  ]);
-
-  // Swallow an unused rejection so a failed price lookup cannot surface as an
-  // unhandled rejection when no adapter happened to await it.
-  nativePricePromise.catch(() => {});
-
-  const ranked = rankRoutes(routes, {
-    destPriceUsd: dest.priceUsd,
-    destDecimals: p.decimalsOut ?? dest.decimals,
-  });
-
-  // Liquidity check. Ranking alone will happily crown a quote taken against a
-  // drained pool, because a thin venue returns a well-formed number rather than
-  // an error. Re-quote the winner at 1/1000th size and compare per-unit price:
-  // real slippage decays smoothly, a dead pool falls off a cliff.
-  //
-  // Opt out with `maxImpactPct: null` for callers that genuinely want the raw
-  // ranking (analytics, spread display) rather than an executable route.
-  const maxImpactPct = opts.maxImpactPct === undefined ? 25 : opts.maxImpactPct;
-  if (maxImpactPct != null && ranked.best) {
-    const winner = ranked.best.source;
-    const probe = async (amt) => {
-      const sub = swapCandidates({
-        ...p,
-        amountIn: amt.toString(),
-        nativePriceUsd: nativePricePromise,
-        decimalsOut: p.decimalsOut,
-        destDecimalsPromise: destPromise,
-        opts,
-      }).filter((c) => c.source === winner);
-      if (!sub.length) return null;
-      const got = await gatherRoutes(sub, { timeoutMs: opts.timeoutMs ?? 12_000 });
-      return got?.[0]?.amountOut ?? null;
-    };
-
-    const impact = await measurePriceImpact(probe, amountIn);
-    if (impact) {
-      const guarded = applyImpactCeiling(ranked, { [winner]: impact }, { maxImpactPct });
-      return {
-        kind: "swap",
-        chainId,
-        tokenIn,
-        tokenOut,
-        amountIn: String(amountIn),
-        ...guarded,
-        // Provenance travels with the guarded result too. Omitting it here made
-        // the CLI print "sources: undefined/undefined answered" and a bare
-        // "undefined" note on exactly the swaps that DID get impact-measured.
-        sourcesTried: candidates.length,
-        sourcesAnswered: routes.filter((r) => r.quality !== QUALITY.FAILED).length,
-        note: describe(guarded, candidates.length),
-        priceImpact: { [winner]: Number(impact.impactPct.toFixed(2)) },
-      };
-    }
-  }
-
-  return {
-    kind: "swap",
-    chainId,
-    tokenIn,
-    tokenOut,
-    amountIn: String(amountIn),
-    ...ranked,
-    sourcesTried: candidates.length,
-    sourcesAnswered: routes.filter((r) => r.quality !== QUALITY.FAILED).length,
-    note: describe(ranked, candidates.length),
-  };
-}
-
-/**
- * Best cross-chain bridge route.
- *
- * Duration is reported, never folded into the score. A route that saves $2 and takes
- * 30 minutes is not strictly better than one costing $2 more that lands in 20
- * seconds -- that trade-off belongs to the caller, and burying it in a single number
- * would hide the only thing distinguishing two similar quotes.
- */
-export async function bestBridgeRoute(p, opts = {}) {
-  const { fromChainId, toChainId, tokenIn, tokenOut, amountIn } = p;
-  if (fromChainId == null || toChainId == null || !tokenIn || !tokenOut || amountIn == null) {
-    throw new Error(
-      "bestBridgeRoute requires fromChainId, toChainId, tokenIn, tokenOut, amountIn",
-    );
-  }
-  if (Number(fromChainId) === Number(toChainId)) {
-    throw new Error("bestBridgeRoute is for cross-chain; use bestSwapRoute for same-chain");
-  }
-
-  // Same concurrency rule as swaps: the destination price is only needed at RANK
-  // time, so fetching it before the quotes would add its latency to every bridge
-  // comparison for no reason.
-  const destPromise = destPrice(toChainId, tokenOut, opts);
-  const candidates = bridgeCandidates({ ...p, opts });
-  const [routes, dest] = await Promise.all([
-    gatherRoutes(candidates, { timeoutMs: opts.timeoutMs ?? 15_000 }),
-    destPromise,
-  ]);
-  const ranked = rankRoutes(routes, {
-    destPriceUsd: dest.priceUsd,
-    destDecimals: p.decimalsOut ?? dest.decimals,
-  });
-
-  const durations = ranked.routes
-    .map((r) => ({ source: r.source, seconds: r.meta?.durationSeconds ?? null }))
-    .filter((d) => d.seconds != null);
-
-  return {
-    kind: "bridge",
-    fromChainId,
-    toChainId,
-    tokenIn,
-    tokenOut,
-    amountIn: String(amountIn),
-    ...ranked,
-    durations,
-    sourcesTried: candidates.length,
-    sourcesAnswered: routes.filter((r) => r.quality !== QUALITY.FAILED).length,
-    note: describe(ranked, candidates.length),
-  };
-}
-
-function describe(ranked, tried) {
-  if (!ranked.best) return "no source returned a usable route";
-  const answered = ranked.routes.length;
-  if (answered === 1) {
-    return (
-      `only 1 of ${tried} sources answered, so this is the ONLY route, not a proven ` +
-      "best one. Treat it as unbenchmarked."
-    );
-  }
-  if (ranked.improvementBps != null) {
-    const bps = ranked.improvementBps;
-    const pct = bps / 100;
-    // Below 0.01bps the winner is a coin flip against quote noise, so claiming
-    // an edge in ANY unit is a false precision claim. Say they are tied.
-    if (bps < 0.01) {
-      return (
-        `best of ${answered} routes, ranked on ${ranked.rankedOn}: ` +
-        `effectively tied with the runner-up (${ranked.spreadBasis}), ` +
-        "inside quote noise. Re-quote before you size up."
-      );
-    }
-    // A sub-bp edge is still an edge and on size it is real money, so report it
-    // in bps rather than letting the percentage round it away to 0.00%.
-    const margin = pct >= 0.01 ? `${pct.toFixed(2)}%` : `${bps.toFixed(2)}bps`;
-    return (
-      `best of ${answered} routes, ranked on ${ranked.rankedOn}: ` +
-      `${margin} better than the runner-up ` +
-      `(${ranked.spreadBasis})`
-    );
-  }
-  // No spread claim when the top two are not measured the same way. Saying "X% better"
-  // off a mismatched pair is worse than saying nothing.
-  return (
-    `best of ${answered} routes, ranked on ${ranked.rankedOn}. No spread quoted: the ` +
-    "top routes report cost differently, so the margin is not comparable."
-  );
-}
-
-export { QUALITY };
-
-// Exported for tests: the note text is a user-facing claim about execution
-// quality, so it needs deterministic coverage independent of live quotes.
-export { describe as formatComparisonNote };

package/src/router/integrator-fee.mjs

@@ -1,135 +0,0 @@
-/**
- * Integrator fee policy.
- *
- * One place decides whether a route carries a fee, so the answer cannot drift
- * between providers. Three rules, in order:
- *
- *   1. OFF unless explicitly configured. No silent default skim.
- *   2. Locals Only holders pay ZERO Oracle integrator fees. Ownership changes
- *      only this rate and never changes product access.
- *   3. Whatever is charged must be disclosable. `describeFee()` returns the
- *      exact bps and recipient so the caller can render it BEFORE the user
- *      signs. Oracle's pitch is "decoded before you sign" — an undisclosed fee
- *      would cost more credibility than the basis points are worth.
- *
- * Note on the status quo this replaces: LI.FI already applies its own 25 bps
- * to every route Oracle sends and keeps all of it, because Oracle never
- * identified itself as an integrator. Verified live 2026-08-06 — an
- * unregistered quote returns feeCosts [{ name: "LIFI Fixed Fee", percentage:
- * "0.0025" }]. So this is not a new cost to the user on that path; it is
- * Oracle claiming a share of a fee that is already being charged.
- */
-
-const MAX_BPS = 100; // 1%. A hard ceiling so a typo cannot ship a 50% fee.
-
-/**
- * 10 bps. Deliberately at the low end: LI.FI's own default is 25 bps and
- * Matcha runs 15, so this stays invisible to anyone comparison-shopping.
- *
- * The fee's job is not revenue maximisation — Locals Only holders pay zero, so
- * a small non-holder fee makes the NFT obviously worth holding. A large one
- * would just teach people to route around Oracle.
- */
-export const DEFAULT_FEE_BPS = 10;
-
-/**
- * Per-action pricing. A same-chain swap is the most price-shopped action in
- * crypto — every aggregator quotes it and users compare to the basis point —
- * so it stays cheapest. The others are not comparison-shopped the same way and
- * deliver more work per transaction.
- *
- *   swap    10 bps  below LI.FI 25 and Matcha 15
- *   bridge  15 bps  multi-chain routing, longer settlement, more failure modes
- *   perps    5 bps  venues already charge taker fees; stacking is punitive
- *   nft      0      marketplace fees are already heavy
- *
- * A holder pays zero on every one of these.
- */
-export const FEE_TIERS = Object.freeze({
-  swap: 10,
-  bridge: 15,
-  perps: 5,
-  nft: 0,
-});
-
-export function tierBps(action) {
-  const key = String(action || "swap").toLowerCase();
-  return Object.prototype.hasOwnProperty.call(FEE_TIERS, key) ? FEE_TIERS[key] : DEFAULT_FEE_BPS;
-}
-
-export const FEE_ENV = "ORACLE_INTEGRATOR_FEE_BPS";
-export const FEE_RECIPIENT_ENV = "ORACLE_INTEGRATOR_FEE_RECIPIENT";
-export const INTEGRATOR_ENV = "ORACLE_INTEGRATOR_ID";
-
-export const DEFAULT_INTEGRATOR_ID = "oracle";
-
-function parseBps(raw, { fallback = 0 } = {}) {
-  // Absent means "use the house default". An explicitly EMPTY string means the
-  // operator set it to nothing on purpose, which is an instruction to charge
-  // nothing — not an invitation to fall back.
-  if (raw === undefined || raw === null) return fallback;
-  if (String(raw).trim() === "") return 0;
-  const n = Number(raw);
-  if (!Number.isFinite(n) || n <= 0) return 0;
-  return Math.min(Math.floor(n), MAX_BPS);
-}
-
-/**
- * Resolve the fee that applies to one route.
- *
- * `isHolder` is passed in rather than looked up here: this module must stay
- * synchronous and side-effect free so it can be called from inside quote
- * builders without turning them into async chain-readers.
- */
-export function resolveFee({ env = process.env, isHolder = false, action = "swap" } = {}) {
-  const recipient = String(env[FEE_RECIPIENT_ENV] || "").trim();
-  // Setting a recipient is the opt-in. Once that exists, bps defaults to 10
-  // rather than forcing every deployment to restate the house number.
-  const bps = parseBps(env[FEE_ENV], { fallback: recipient ? tierBps(action) : 0 });
-  const integrator = String(env[INTEGRATOR_ENV] || DEFAULT_INTEGRATOR_ID).trim();
-
-  // Holder check comes first. A zero-bps tier (nft) would otherwise return
-  // "not-configured" for a holder, which is a true zero with a misleading
-  // reason — the UI would say "No Oracle fee" instead of crediting the NFT.
-  if (isHolder) {
-    return { bps: 0, recipient, integrator, action, applies: false, reason: "locals-only-holder" };
-  }
-
-  if (!bps) {
-    return { bps: 0, recipient: "", integrator, action, applies: false, reason: "not-configured" };
-  }
-  if (!/^0x[a-fA-F0-9]{40}$/.test(recipient)) {
-    // Fail closed. A fee with nowhere to go is a fee that silently vanishes
-    // into the aggregator, which is the exact situation this module exists to
-    // end.
-    return { bps: 0, recipient: "", integrator, action, applies: false, reason: "no-recipient" };
-  }
-  return { bps, recipient, integrator, action, applies: true, reason: "configured" };
-}
-
-/** Human-readable disclosure. Render this next to the quote, before signing. */
-export function describeFee(fee) {
-  if (!fee?.applies) {
-    if (fee?.reason === "locals-only-holder") return "No Oracle fee (Locals Only holder).";
-    return "No Oracle fee.";
-  }
-  return `Oracle routing fee ${fee.bps} bps (${(fee.bps / 100).toFixed(2)}%) to ${fee.recipient}.`;
-}
-
-/** LI.FI wants a decimal fraction plus a registered integrator id. */
-export function lifiFeeParams(fee) {
-  if (!fee?.applies) return {};
-  return { integrator: fee.integrator, fee: String(fee.bps / 10_000) };
-}
-
-/** ParaSwap wants integer bps and a partner string. */
-export function paraswapFeeParams(fee) {
-  if (!fee?.applies) return {};
-  return {
-    partner: fee.integrator,
-    partnerFeeBps: String(fee.bps),
-    partnerAddress: fee.recipient,
-  };
-}
-
-export const FEE_MAX_BPS = MAX_BPS;

package/src/router/prepare-bridge.mjs

@@ -1,293 +0,0 @@
-// Prepare a cross-chain bridge route.
-//
-// Bridging differs from swapping in ways that matter for a signable artifact:
-//
-//   1. IT IS OFTEN MULTIPLE TRANSACTIONS. Relay can return an approval and a deposit
-//      as separate items. A caller handed a bare "transaction" would sign the first
-//      and believe they were done, leaving funds approved but not bridged. So the
-//      artifact is always a LIST, and its length is stated.
-//
-//   2. THE DESTINATION CHAIN IS PART OF THE TRUST DECISION. Every transaction here
-//      executes on the ORIGIN chain, but the value lands elsewhere. Signing an
-//      origin-chain tx that credits the wrong destination is unrecoverable, so
-//      toChainId is echoed alongside the destination address.
-//
-//   3. TIME IS A REAL COST. A bridge that saves $2 and takes 30 minutes is not
-//      obviously better than one costing $2 more that lands in 20 seconds. Duration
-//      is surfaced, never folded into a score.
-//
-//   4. FINALITY IS NOT ATOMIC. The origin transaction succeeding does NOT mean funds
-//      arrived. That gap is where users panic, so it is stated explicitly rather than
-//      left implied.
-//
-// Custody is unchanged: artifacts only. This module cannot sign or broadcast.
-
-import { bestBridgeRoute } from "./index.mjs";
-import { stampPrepared } from "../prepare-envelope.mjs";
-
-const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
-
-/**
- * Placeholder addresses: fine for quoting, never for preparing.
- * Same reasoning as the swap path -- some venues catch this and some do not.
- */
-const NON_TAKER_ADDRESSES = new Set(
-  [
-    "0x0000000000000000000000000000000000000000",
-    "0x000000000000000000000000000000000000dead",
-    "0x0000000000000000000000000000000000000001",
-    "0x00000000000000000000000000000000000a1ce5",
-  ].map((a) => a.toLowerCase()),
-);
-
-const DEFAULT_DRIFT_TOLERANCE_BPS = 100;
-
-const PREPARERS = {
-  relay: async ({ fromChainId, toChainId, tokenIn, tokenOut, amountIn, taker }, opts) => {
-    const { relayPrepare } = await import("../data/providers/bridges.mjs");
-    const p = await relayPrepare(
-      {
-        user: taker,
-        originChainId: fromChainId,
-        destinationChainId: toChainId,
-        originCurrency: tokenIn,
-        destinationCurrency: tokenOut,
-        amount: String(amountIn),
-      },
-      opts,
-    );
-    return {
-      transactions: p.transactions || [],
-      amountOut: p.quote?.details?.currencyOut?.amount ?? null,
-      minOut: p.quote?.details?.currencyOut?.minimumAmount ?? null,
-      durationSeconds: p.quote?.details?.timeEstimate ?? null,
-    };
-  },
-
-  lifi: async ({ fromChainId, toChainId, tokenIn, tokenOut, amountIn, taker, isHolder }, opts) => {
-    const { lifiPrepare } = await import("../data/providers/lifi.mjs");
-    const p = await lifiPrepare(
-      {
-        fromChain: fromChainId,
-        toChain: toChainId,
-        fromToken: tokenIn,
-        toToken: tokenOut,
-        fromAmount: amountIn,
-        fromAddress: taker,
-        // A bridge is not a same-chain swap: more routing, longer settlement,
-        // more failure modes. Priced on its own tier.
-        isHolder,
-        feeAction: "bridge",
-      },
-      opts,
-    );
-    // LI.FI returns a single transactionRequest. Normalized into a list so callers
-    // handle one shape regardless of source -- a single-item list is honest, a bare
-    // object next to Relay's list is a trap.
-    return {
-      transactions: p.transaction ? [p.transaction] : [],
-      requiresApproval: p.requiresApproval ?? null,
-      amountOut: p.quote?.estimate?.toAmount ?? null,
-      minOut: p.quote?.estimate?.toAmountMin ?? null,
-      durationSeconds: p.quote?.estimate?.executionDuration ?? null,
-    };
-  },
-};
-
-export function supportedBridgePreparers() {
-  return Object.keys(PREPARERS);
-}
-
-/**
- * Compare bridge routes, then prepare the winner.
- *
- * @param {object} p same shape as bestBridgeRoute, plus:
- * @param {string} p.taker the real wallet that will sign
- * @param {string} [p.source] force a specific source
- * @param {number} [p.driftToleranceBps]
- */
-export async function prepareBestBridgeRoute(p, opts = {}) {
-  const { taker, fromChainId, toChainId } = p;
-
-  if (!taker) {
-    throw new Error(
-      "prepareBestBridgeRoute requires taker: bridge transactions are built FOR an " +
-        "address, and the quote-only placeholder must never end up in one",
-    );
-  }
-  if (!ADDRESS_RE.test(taker)) {
-    throw new Error(`taker must be a valid 20-byte address, got "${taker}"`);
-  }
-  if (NON_TAKER_ADDRESSES.has(taker.toLowerCase())) {
-    throw new Error(
-      `taker "${taker}" is a placeholder/burn address. Bridging to it would send ` +
-        "funds to an address nobody controls, on a chain where you cannot undo it.",
-    );
-  }
-
-  const comparison = await bestBridgeRoute(p, opts);
-  if (!comparison.best) {
-    return { ok: false, reason: "no source returned a usable bridge route", comparison };
-  }
-
-  const chosenSource = p.source || comparison.best.source;
-  const chosen = comparison.routes.find((r) => r.source === chosenSource);
-  if (!chosen) {
-    return { ok: false, reason: `source "${chosenSource}" returned no usable route`, comparison };
-  }
-
-  const prepare = PREPARERS[chosenSource];
-  if (!prepare) {
-    const alt = comparison.routes.find((r) => PREPARERS[r.source] && r.source !== chosenSource);
-    return {
-      ok: false,
-      reason:
-        `${chosenSource} won the comparison but has no bridge prepare path in this ` +
-        `build. ` +
-        (alt
-          ? `Next preparable route is ${alt.source}; pass source:"${alt.source}".`
-          : "No route in this comparison can be prepared."),
-      // Machine-readable siblings of the message above. A caller should not have to
-      // regex prose to find the fallback -- and the CLI/agent path reads these.
-      failureKind: "no-prepare-path",
-      ...(alt ? { alternative: alt.source } : {}),
-      winner: chosenSource,
-      comparison,
-    };
-  }
-
-  let prepared;
-  try {
-    prepared = await prepare(p, opts);
-  } catch (err) {
-    const detail =
-      typeof err?.body === "string" ? err.body : err?.body ? JSON.stringify(err.body) : "";
-    const msg = [String(err?.message || err), detail].filter(Boolean).join(" :: ");
-
-    const allowanceIssue = /allowance/i.test(msg);
-    const balanceIssue = !allowanceIssue && /not enough|insufficient|balance/i.test(msg);
-    const alt = comparison.routes.find((r) => PREPARERS[r.source] && r.source !== chosenSource);
-
-    return {
-      ok: false,
-      reason: allowanceIssue
-        ? `${chosenSource} will not build calldata until the token approval exists ` +
-          `on-chain. Approve first, then prepare again. Underlying: ${msg}`
-        : balanceIssue
-          ? `${chosenSource} refused to build: ${msg}. Quoting works for any address; ` +
-            `preparing needs the real funded wallet on chain ${fromChainId}.`
-          : `${chosenSource} bridge prepare failed: ${msg}`,
-      failureKind: allowanceIssue
-        ? "approval-required-first"
-        : balanceIssue
-          ? "taker-not-funded"
-          : "provider-error",
-      ...(alt ? { alternative: alt.source } : {}),
-      comparison,
-    };
-  }
-
-  const txs = prepared.transactions || [];
-  if (!txs.length) {
-    return {
-      ok: false,
-      reason: `${chosenSource} returned no executable transaction for this route`,
-      failureKind: "provider-error",
-      comparison,
-    };
-  }
-
-  // Every transaction must execute on the ORIGIN chain. A wrong chainId here means a
-  // wallet could be prompted on the wrong network, and the user would be signing
-  // something they cannot reason about.
-  const wrongChain = txs.filter(
-    (t) => t.chainId != null && Number(t.chainId) !== Number(fromChainId),
-  );
-  if (wrongChain.length) {
-    return {
-      ok: false,
-      reason:
-        `${chosenSource} returned a transaction for chain ${wrongChain[0].chainId} but ` +
-        `the origin chain is ${fromChainId}. Refusing to hand over a mismatched ` +
-        `artifact.`,
-      failureKind: "chain-mismatch",
-      comparison,
-    };
-  }
-
-  // Drift against the comparison. Same reasoning as swaps: the comparison is stale.
-  const tolerance = p.driftToleranceBps ?? DEFAULT_DRIFT_TOLERANCE_BPS;
-  let driftBps = null;
-  let driftWarning = null;
-  if (prepared.amountOut != null && chosen.grossOut != null) {
-    try {
-      const then = BigInt(chosen.grossOut);
-      const now = BigInt(prepared.amountOut);
-      if (then > 0n) {
-        driftBps = Number(((now - then) * 10_000n) / then);
-        if (driftBps < -tolerance) {
-          driftWarning =
-            `route moved ${(driftBps / 100).toFixed(2)}% against you since the ` +
-            `comparison (tolerance ${(tolerance / 100).toFixed(2)}%). Re-compare ` +
-            `before signing.`;
-        }
-      }
-    } catch {
-      /* no fabricated drift */
-    }
-  }
-
-  const warnings = [
-    ...(driftWarning ? [driftWarning] : []),
-    ...(comparison.warnings || []),
-    // The single most common bridging surprise.
-    `Bridging is NOT atomic: the origin transaction succeeding does not mean funds ` +
-      `arrived on chain ${toChainId}. Expect ~${
-        prepared.durationSeconds != null ? `${prepared.durationSeconds}s` : "minutes"
-      } before the destination credits, and do not re-send if it is pending.`,
-  ];
-
-  if (txs.length > 1) {
-    warnings.push(
-      `This route needs ${txs.length} transactions signed IN ORDER. Signing only the ` +
-        `first leaves funds approved but not bridged.`,
-    );
-  }
-
-  return stampPrepared({
-    ok: true,
-    chosen: {
-      source: chosenSource,
-      wasWinner: chosenSource === comparison.best.source,
-      netOut: chosen.netOut,
-      grossOut: chosen.grossOut,
-      gasUsd: chosen.gasUsd,
-    },
-    artifactKind: "unsigned-transaction-sequence",
-    fromChainId: Number(fromChainId),
-    toChainId: Number(toChainId),
-    transactionCount: txs.length,
-    transactions: txs,
-    requiresApproval: prepared.requiresApproval ?? null,
-    minOut: prepared.minOut ?? null,
-    durationSeconds: prepared.durationSeconds ?? null,
-    // Where value goes on the origin chain. The first destination is the bridge entry.
-    destination: txs[0]?.to ?? null,
-    unsigned: true,
-    signedBy: "user-wallet",
-    driftBps,
-    warnings,
-    runnersUp: comparison.routes
-      .filter((r) => r.source !== chosenSource)
-      .map((r) => ({ source: r.source, netOut: r.netOut, gasUsd: r.gasUsd })),
-    comparison: {
-      rankedOn: comparison.rankedOn,
-      sourcesAnswered: comparison.sourcesAnswered,
-      sourcesTried: comparison.sourcesTried,
-      improvementBps: comparison.improvementBps,
-    },
-    note:
-      `UNSIGNED. ${txs.length} transaction(s) on chain ${fromChainId}, crediting ` +
-      `chain ${toChainId}. Verify every destination address before signing.`,
-  }, { provider: "router", kind: "best-bridge" });
-}