@oracle-agent/oracle 0.10.0 → 0.12.0

package/src/router/risk-classifier.mjs

@@ -1,119 +0,0 @@
-// 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

@@ -1,329 +0,0 @@
-// 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 { uniV3QuoteExactIn, UNI_V3_CHAINS } from "../data/providers/uniswap-v3.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" },
-      };
-    },
-  });
-
-  // On-chain Uniswap V3 QuoterV2. UNLIKE every other source in this list, this is
-  // not a third-party API — it is an eth_call against the chain itself.
-  //
-  // Why it exists here: aggregators only index chains they chose to support. On
-  // Robinhood Chain (4663) LI.FI/ParaSwap/CoW all return nothing, so the candidate
-  // list came back empty and the router reported "no usable route" — which reads
-  // like a permission wall but is really zero coverage. A chain with a live V3
-  // deployment can always be priced directly, with no API key and no indexer.
-  //
-  // Kept LAST so it acts as a floor: when aggregators do cover a chain they usually
-  // win on route quality, and best-execution still compares net output. This only
-  // decides the trade when it is the sole source that answered.
-  //
-  // Read-only. quoteExactInputSingle is a view call; this cannot sign or broadcast.
-  if (UNI_V3_CHAINS[Number(chainId)]) {
-    c.push({
-      source: "uniswap-v3",
-      run: async () => {
-        const q = await uniV3QuoteExactIn(
-          { chainId, tokenIn, tokenOut, amountIn },
-          opts,
-        );
-        // Gas is deliberately null, not 0: the quoter returns a gasEstimate in UNITS,
-        // and without a gas price that is not a USD cost. Reporting 0 would make this
-        // source look free and beat correctly-priced aggregators. See CoW above for
-        // the one case where 0 is a measured fact rather than a missing number.
-        return {
-          amountOut: q?.amountOut,
-          minOut: q?.minOut ?? q?.amountOutMinimum ?? null,
-          gasUsd: null,
-          meta: { onchain: true, fee: q?.fee, gasUnits: q?.gasEstimate, quoter: q?.quoter },
-        };
-      },
-    });
-  }
-
-  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;
-}