@oracle-agent/oracle 0.11.0 → 0.13.0

package/src/router/index.mjs

@@ -1,226 +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,
-        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) {
-    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

@@ -1,289 +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 }, 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 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" });
-}