@oracle-agent/oracle 0.1.0

package/src/router/risk-classifier.mjs

@@ -0,0 +1,119 @@
+// Oracle Router risk classifier.
+//
+// Pure, dependency-free, deterministic. No I/O, no network, no chain reads,
+// no imports. The router uses this to LABEL a proposed action's risk tier for
+// advisory purposes only -- the label is context for a human or for Oracle
+// Control, never an authorization decision. Oracle Control independently
+// validates and gates every real action; nothing here grants or implies
+// permission to sign, broadcast, or spend.
+
+export const RISK_TIERS = Object.freeze(["low", "medium", "high", "critical"]);
+
+// Kinds the router treats as pure read/advisory work (no custody exposure).
+export const READ_ONLY_KINDS = Object.freeze(["read", "quote", "explain", "simulate"]);
+
+// Kinds that describe a draft custody-adjacent action. These are still just
+// labels on a proposal -- classifying something as "swap" does not create a
+// swap, sign anything, or move funds.
+export const CUSTODY_ADJACENT_KINDS = Object.freeze([
+  "approval",
+  "transfer",
+  "swap",
+  "order",
+  "bridge",
+]);
+
+function normalizeKind(kind) {
+  const k = String(kind || "").trim().toLowerCase();
+  return k || "unknown";
+}
+
+// Coarse USD notional bands. Unknown/invalid notional is NOT treated as "low"
+// -- callers must not be able to escape risk scoring by omitting a number.
+function notionalBand(notionalUsd) {
+  if (notionalUsd == null) return null;
+  const n = Number(notionalUsd);
+  if (!Number.isFinite(n) || n < 0) return null;
+  if (n > 100_000) return 3;
+  if (n > 10_000) return 2;
+  if (n > 1_000) return 1;
+  return 0;
+}
+
+function tierFromScore(score) {
+  if (score >= 7) return "critical";
+  if (score >= 4) return "high";
+  if (score >= 2) return "medium";
+  return "low";
+}
+
+/**
+ * Classify the risk tier of a proposed action. Pure function: same input
+ * always produces the same output, and calling it has zero side effects.
+ *
+ * @param {object} [input]
+ * @param {string} [input.kind]               "read" | "quote" | "explain" | "simulate" |
+ *                                             "approval" | "transfer" | "swap" | "order" |
+ *                                             "bridge" | any other string (treated conservatively)
+ * @param {number} [input.notionalUsd]         approximate USD notional, if known
+ * @param {boolean} [input.destinationKnown]   true if destination is a reviewed/allowlisted venue
+ * @param {boolean} [input.unlimitedApproval]  true if the action requests an unbounded/MaxUint256-style approval
+ * @param {boolean} [input.crossChain]         true if the action spans chains (bridge-like)
+ * @returns {{ tier: "low"|"medium"|"high"|"critical", score: number, reasons: readonly string[] }}
+ */
+export function classifyRisk(input = {}) {
+  const kind = normalizeKind(input?.kind);
+  const reasons = [];
+  let score = 0;
+
+  const isReadOnly = READ_ONLY_KINDS.includes(kind);
+  const isCustodyAdjacent = CUSTODY_ADJACENT_KINDS.includes(kind);
+
+  if (isReadOnly) {
+    reasons.push(`kind "${kind}" is read/advisory-only`);
+  } else if (isCustodyAdjacent) {
+    score += 2;
+    reasons.push(`kind "${kind}" is custody-adjacent (+2)`);
+  } else {
+    score += 3;
+    reasons.push(`kind "${kind}" is unrecognized; treated conservatively (+3)`);
+  }
+
+  const band = notionalBand(input?.notionalUsd);
+  if (band != null && band > 0) {
+    score += band;
+    reasons.push(`notional band ${band} (+${band})`);
+  } else if (band == null && !isReadOnly) {
+    score += 1;
+    reasons.push("notional unknown for a non-read action (+1)");
+  }
+
+  if (input?.unlimitedApproval) {
+    score += 3;
+    reasons.push("unlimited/unbounded approval requested (+3)");
+  }
+
+  if (input?.destinationKnown === false) {
+    score += 2;
+    reasons.push("destination not a reviewed/allowlisted venue (+2)");
+  }
+
+  if (input?.crossChain) {
+    score += 1;
+    reasons.push("cross-chain action (+1)");
+  }
+
+  return Object.freeze({
+    tier: tierFromScore(score),
+    score,
+    reasons: Object.freeze(reasons),
+  });
+}
+
+export function isReadOnlyKind(kind) {
+  return READ_ONLY_KINDS.includes(normalizeKind(kind));
+}
+
+export function isCustodyAdjacentKind(kind) {
+  return CUSTODY_ADJACENT_KINDS.includes(normalizeKind(kind));
+}

package/src/router/route-sources.mjs

@@ -0,0 +1,292 @@
+// Source adapters for the best-execution router.
+//
+// Each aggregator returns a different shape and means slightly different things by
+// the same words. This module is where those differences are made explicit instead
+// of being papered over by a shared field name.
+//
+// Notable disagreements handled here:
+//   * LI.FI reports gas AND fee costs already denominated in USD
+//   * 0x returns totalNetworkFee in native wei -- needs a native price to compare
+//   * 1inch quote returns only dstAmount + gas units, no cost
+//   * CoW is an intent: the solver pays gas, so gasUsd is genuinely 0, not unknown
+//   * Odos/ParaSwap report USD-valued gas estimates directly
+//
+// Sources needing an API key are skipped when the key is absent rather than throwing.
+// A missing optional key is a config state, not an error, and must not sink the
+// comparison.
+
+import { lifiQuote } from "../data/providers/lifi.mjs";
+import { paraswapPrice } from "../data/providers/paraswap.mjs";
+import { zeroxQuote } from "../data/providers/zerox.mjs";
+import { oneinchQuote } from "../data/providers/oneinch.mjs";
+import { cowQuote } from "../data/providers/cowswap.mjs";
+import { llamaPrices } from "../data/providers/defillama.mjs";
+import { NATIVE_PRICE_KEY } from "./best-execution.mjs";
+
+const num = (v) => {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+/** Sum a LI.FI-style cost array that carries amountUSD entries. */
+function sumUsd(list) {
+  if (!Array.isArray(list)) return null;
+  let total = 0;
+  let sawAny = false;
+  for (const c of list) {
+    const v = num(c?.amountUSD);
+    if (v != null) {
+      total += v;
+      sawAny = true;
+    }
+  }
+  return sawAny ? total : null;
+}
+
+/** Fetch the native asset's USD price, for sources that price gas in wei. */
+export async function nativeUsd(chainId, opts = {}) {
+  const key = NATIVE_PRICE_KEY[Number(chainId)];
+  if (!key) return null;
+  try {
+    const res = await llamaPrices([key], opts);
+    return num(res?.coins?.[key]?.price);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the candidate list for a same-chain swap.
+ *
+ * @returns {Array<{source: string, run: () => Promise<object>}>}
+ */
+export function swapCandidates({
+  chainId,
+  tokenIn,
+  tokenOut,
+  amountIn,
+  taker,
+  decimalsIn,
+  decimalsOut,
+  nativePriceUsd = null,
+  destDecimalsPromise = null,
+  opts = {},
+}) {
+  const c = [];
+
+  c.push({
+    source: "lifi",
+    run: async () => {
+      const q = await lifiQuote(
+        { fromChain: chainId, toChain: chainId, fromToken: tokenIn, toToken: tokenOut, fromAmount: amountIn },
+        opts,
+      );
+      const est = q?.estimate ?? q?.[0]?.estimate;
+      return {
+        amountOut: est?.toAmount,
+        minOut: est?.toAmountMin,
+        gasUsd: sumUsd(est?.gasCosts),
+        feeUsd: sumUsd(est?.feeCosts),
+        meta: { tool: q?.tool ?? q?.toolDetails?.name },
+      };
+    },
+  });
+
+  // Odos is deliberately NOT in this list: its public SOR API was sunset on
+  // 2026-07-30 and returns HTTP 410. Querying it would spend a timeout on every
+  // single swap comparison to learn a fact we already know. src/data/providers/odos.mjs
+  // is kept for callers that still reference it, and re-adding it here is a one-line
+  // change if Odos ships a replacement endpoint.
+
+  // ParaSwap needs decimals for BOTH sides to quote at all.
+  //
+  // decimalsOut may arrive from the caller or from the destination price lookup,
+  // which now resolves in parallel rather than before this list is built. So the
+  // gate is decimalsIn (caller-only), and decimalsOut is resolved inside run().
+  //
+  // Subtle regression this avoids: gating on a value that is no longer awaited here
+  // would silently DROP ParaSwap for every caller who did not pass decimalsOut --
+  // quietly shrinking the comparison from three sources to two while still reporting
+  // a "best" route.
+  if (decimalsIn != null) {
+    c.push({
+      source: "paraswap",
+      run: async () => {
+        const dOut = decimalsOut ?? (await Promise.resolve(destDecimalsPromise))?.decimals;
+        if (dOut == null) {
+          throw new Error("paraswap needs destination decimals; none supplied or resolvable");
+        }
+        const q = await paraswapPrice(
+          { chainId, srcToken: tokenIn, destToken: tokenOut, amount: amountIn, srcDecimals: decimalsIn, destDecimals: dOut },
+          opts,
+        );
+        const pr = q?.priceRoute;
+        return {
+          amountOut: pr?.destAmount,
+          gasUsd: num(pr?.gasCostUSD),
+          meta: { bestRoute: pr?.bestRoute?.[0]?.swaps?.[0]?.swapExchanges?.[0]?.exchange },
+        };
+      },
+    });
+  }
+
+  // 0x and 1inch need keys. Skip silently when absent -- see module header.
+  if (process.env.ZEROX_API_KEY) {
+    c.push({
+      source: "0x",
+      run: async () => {
+        const q = await zeroxQuote({ chainId, sellToken: tokenIn, buyToken: tokenOut, sellAmount: amountIn, taker }, opts);
+        // totalNetworkFee is native wei; convert only if we have a price.
+        // nativePriceUsd may be a PROMISE: prices are fetched in parallel with the
+        // quotes rather than before them. Awaiting here means only the one adapter
+        // that actually needs it pays for it, and only after its own HTTP call.
+        let gasUsd = null;
+        const feeWei = q?.totalNetworkFee;
+        const nativePrice = await Promise.resolve(nativePriceUsd);
+        if (feeWei != null && nativePrice) {
+          gasUsd = (Number(feeWei) / 1e18) * nativePrice;
+        }
+        return { amountOut: q?.buyAmount, minOut: q?.minBuyAmount, gasUsd, meta: { source: q?.route?.fills?.[0]?.source } };
+      },
+    });
+  }
+
+  if (process.env.ONEINCH_API_KEY) {
+    c.push({
+      source: "1inch",
+      run: async () => {
+        const q = await oneinchQuote({ chainId, src: tokenIn, dst: tokenOut, amount: amountIn }, opts);
+        let gasUsd = null;
+        if (q?.gas != null && nativePriceUsd) {
+          // 1inch returns gas UNITS; without a gas price this stays unknown rather
+          // than being guessed. Reporting a made-up cost is worse than reporting none.
+          gasUsd = null;
+        }
+        return { amountOut: q?.dstAmount, gasUsd, meta: { gasUnits: q?.gas } };
+      },
+    });
+  }
+
+  // CoW is an intent, not a transaction: a solver executes and eats the gas, so the
+  // user pays 0 gas. That is a MEASURED zero, not an unknown, and it is exactly the
+  // case naive "biggest number wins" ranking gets wrong -- CoW often quotes slightly
+  // lower gross while winning decisively on net.
+  c.push({
+    source: "cow",
+    run: async () => {
+      const q = await cowQuote(
+        { chainId, sellToken: tokenIn, buyToken: tokenOut, sellAmountBeforeFee: String(amountIn), from: taker },
+        opts,
+      );
+      const quote = q?.quote ?? q;
+      const feeAmount = quote?.feeAmount;
+      return {
+        amountOut: quote?.buyAmount,
+        gasUsd: 0,
+        meta: { intent: true, feeAmountInSellToken: feeAmount, settlement: "solver-executed" },
+      };
+    },
+  });
+
+  return c;
+}
+
+/**
+ * Build the candidate list for a cross-chain bridge.
+ *
+ * Bridging has a cost structure swaps do not: a relayer fee, a destination-gas
+ * component, and a time-to-finality that is itself a cost. A route that saves $2 and
+ * takes 30 minutes is not obviously better than one that costs $2 more and lands in
+ * 20 seconds, so duration is surfaced rather than collapsed into the score.
+ */
+export function bridgeCandidates({
+  fromChainId,
+  toChainId,
+  tokenIn,
+  tokenOut,
+  amountIn,
+  taker,
+  opts = {},
+}) {
+  const c = [];
+
+  c.push({
+    source: "lifi",
+    run: async () => {
+      const q = await lifiQuote(
+        { fromChain: fromChainId, toChain: toChainId, fromToken: tokenIn, toToken: tokenOut, fromAmount: amountIn },
+        opts,
+      );
+      const est = q?.estimate ?? q?.[0]?.estimate;
+      return {
+        amountOut: est?.toAmount,
+        minOut: est?.toAmountMin,
+        gasUsd: sumUsd(est?.gasCosts),
+        feeUsd: sumUsd(est?.feeCosts),
+        meta: {
+          tool: q?.tool ?? q?.toolDetails?.name,
+          durationSeconds: num(est?.executionDuration),
+        },
+      };
+    },
+  });
+
+  c.push({
+    source: "relay",
+    run: async () => {
+      const { relayQuote } = await import("../data/providers/bridges.mjs");
+      const q = await relayQuote(
+        {
+          user: taker,
+          originChainId: fromChainId,
+          destinationChainId: toChainId,
+          originCurrency: tokenIn,
+          destinationCurrency: tokenOut,
+          amount: String(amountIn),
+        },
+        opts,
+      );
+      const d = q?.details;
+      return {
+        amountOut: d?.currencyOut?.amount,
+        minOut: d?.currencyOut?.minimumAmount,
+        gasUsd: num(d?.totalImpact?.usd) != null ? Math.abs(num(d.totalImpact.usd)) : null,
+        meta: { durationSeconds: num(d?.timeEstimate), rate: d?.rate },
+      };
+    },
+  });
+
+  c.push({
+    source: "across",
+    run: async () => {
+      const { acrossSuggestedFees } = await import("../data/providers/bridges.mjs");
+      const q = await acrossSuggestedFees(
+        { token: tokenIn, destinationToken: tokenOut, originChainId: fromChainId, destinationChainId: toChainId, amount: String(amountIn) },
+        opts,
+      );
+      // Across returns fees, not an output amount: derive output as input - fees so it
+      // is comparable with sources that quote an output directly.
+      const totalFee = q?.totalRelayFee?.total;
+      let amountOut = null;
+      if (totalFee != null) {
+        try {
+          const outWei = BigInt(String(amountIn)) - BigInt(String(totalFee));
+          if (outWei > 0n) amountOut = outWei.toString();
+        } catch {
+          /* leave null -- a failed derivation must not become a fabricated number */
+        }
+      }
+      return {
+        amountOut,
+        gasUsd: null,
+        meta: {
+          derivedFromFees: true,
+          durationSeconds: num(q?.estimatedFillTimeSec),
+          limits: q?.limits ? { min: q.limits.minDeposit, max: q.limits.maxDeposit } : undefined,
+        },
+      };
+    },
+  });
+
+  return c;
+}