@oracle-agent/oracle 0.1.0

package/src/router/best-execution.mjs

@@ -0,0 +1,221 @@
+// 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,
+  };
+}
+
+/**
+ * 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 };

package/src/router/index.mjs

@@ -0,0 +1,185 @@
+// 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 } 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,
+  });
+
+  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) {
+    return (
+      `best of ${answered} routes, ranked on ${ranked.rankedOn}: ` +
+      `${(ranked.improvementBps / 100).toFixed(2)}% 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 };

package/src/router/prepare-bridge.mjs

@@ -0,0 +1,288 @@
+// 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";
+
+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 }, 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,
+      },
+      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 {
+    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.`,
+  };
+}