@oracle-agent/oracle 0.14.1 → 0.16.0

package/src/desk/swap-prepare.mjs

@@ -1,194 +0,0 @@
-// Swap PREPARE for the desk plane.
-//
-// The app called POST /swap/prepare and nothing implemented it, so the UI
-// presented a working prepare surface that could never return a quote. This is
-// the missing handler.
-//
-// It is a THIN ADAPTER over the same prepareBestRoute() the CLI drives via
-// `oracle route prepare` -- not a second implementation. The app speaks
-// symbols and human decimal amounts ("0.5 USDC"); the router speaks addresses
-// and raw integer units. Everything here is that translation plus the custody
-// invariants, and the actual routing/comparison/preparation is the shared path.
-//
-// Custody: returns an UNSIGNED transaction. Never signs, never broadcasts,
-// never touches key material. The wallet is the only thing that can authorize.
-
-import { prepareBestRoute } from "../router/prepare-route.mjs";
-import { getScanner, listScanners } from "../scanner/contract.mjs";
-import { registerBuiltinScanners } from "../scanner/chains.config.mjs";
-import { UNI_V3_CHAINS } from "../data/providers/uniswap-v3.mjs";
-
-const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
-const MAX_SYMBOL_LEN = 24;
-
-let scannersReady = false;
-function ensureScanners() {
-  if (scannersReady) return;
-  registerBuiltinScanners();
-  scannersReady = true;
-}
-
-export class SwapPrepareError extends Error {
-  constructor(status, message) {
-    super(message);
-    this.status = status;
-  }
-}
-
-/** Accept a numeric chain id or a scanner key ("base", "ethereum"). */
-export function resolveChainId(ref) {
-  ensureScanners();
-  if (ref == null || ref === "") throw new SwapPrepareError(400, "chainId is required");
-  const n = Number(ref);
-  if (Number.isFinite(n) && getScanner(n)) return n;
-  const s = listScanners().find((x) => x.key === String(ref).toLowerCase());
-  if (s) return s.chainId;
-  throw new SwapPrepareError(400, `unknown chain "${ref}"`);
-}
-
-function cleanSymbol(value, label) {
-  if (typeof value !== "string") throw new SwapPrepareError(400, `${label} is required`);
-  const t = value.trim();
-  if (t === "" || t.length > MAX_SYMBOL_LEN) throw new SwapPrepareError(400, `${label} is invalid`);
-  // Symbols and 0x addresses both ride this field; the scanner resolves either.
-  if (!/^[A-Za-z0-9._-]+$/.test(t) && !ADDRESS_RE.test(t)) {
-    throw new SwapPrepareError(400, `${label} is invalid`);
-  }
-  return t;
-}
-
-/**
- * Human decimal amount -> raw integer units, without floating point.
- *
- * Number(0.1) * 1e18 is 100000000000000001... and a wrong amountIn silently
- * prepares a transaction for the wrong size, so this is done on strings.
- */
-export function toRawUnits(amount, decimals) {
-  const text = String(amount).trim();
-  if (!/^\d+(\.\d+)?$/.test(text)) throw new SwapPrepareError(400, "sellAmount must be a positive decimal number");
-  if (Number(text) <= 0) throw new SwapPrepareError(400, "sellAmount must be greater than zero");
-  const d = Number.isFinite(Number(decimals)) ? Number(decimals) : 18;
-  const [whole, frac = ""] = text.split(".");
-  if (frac.length > d) {
-    throw new SwapPrepareError(400, `sellAmount has more precision than the token's ${d} decimals`);
-  }
-  const padded = frac.padEnd(d, "0");
-  const raw = (BigInt(whole) * 10n ** BigInt(d) + BigInt(padded || "0")).toString();
-  if (raw === "0") throw new SwapPrepareError(400, "sellAmount rounds to zero at this token's precision");
-  return raw;
-}
-
-/**
- * Symbol or address -> { address, decimals }.
- *
- * scanner.resolveToken() deliberately refuses symbols ("symbol lookup is a
- * market-data concern") and only reads on-chain metadata for a 20-byte
- * address. So a bare symbol is mapped through the per-chain token constants
- * the V3 provider already maintains, and anything that is already an address
- * goes straight to the scanner for its REAL on-chain decimals.
- */
-async function resolveAsset(chainId, ref) {
-  ensureScanners();
-  if (ADDRESS_RE.test(ref)) {
-    const scanner = getScanner(chainId);
-    const meta = await scanner.resolveToken(ref).catch(() => null);
-    const decimals = Number(meta?.decimals);
-    return { address: ref, decimals: Number.isFinite(decimals) ? decimals : null };
-  }
-  const cfg = UNI_V3_CHAINS[chainId];
-  if (!cfg) return null;
-  const key = ref.toLowerCase();
-  // USDC is 6 decimals nearly everywhere and WETH is 18; both are confirmed
-  // against the chain below rather than trusted from this table.
-  const address = key === "usdc" ? cfg.usdc : key === "weth" || key === "eth" ? cfg.weth : null;
-  if (!address) return null;
-  const scanner = getScanner(chainId);
-  const meta = await scanner.resolveToken(address).catch(() => null);
-  const decimals = Number(meta?.decimals);
-  return { address, decimals: Number.isFinite(decimals) ? decimals : null };
-}
-
-/**
- * @param {object} body  { chainId, sellSymbol, buySymbol, sellAmount, taker, source? }
- * @returns unsigned prepare artifact in the shape the app's parser reads
- */
-export async function prepareSwapForDesk(body = {}, opts = {}) {
-  const chainId = resolveChainId(body.chainId ?? body.chain);
-  const sellSymbol = cleanSymbol(body.sellSymbol ?? body.sellToken, "sellSymbol");
-  const buySymbol = cleanSymbol(body.buySymbol ?? body.buyToken, "buySymbol");
-  if (sellSymbol.toLowerCase() === buySymbol.toLowerCase()) {
-    throw new SwapPrepareError(400, "sell and buy assets must differ");
-  }
-
-  // prepareBestRoute refuses placeholder/burn takers itself; surface that as a
-  // 400 rather than letting it throw as an unhandled 500.
-  const taker = typeof body.taker === "string" ? body.taker.trim() : "";
-  if (!ADDRESS_RE.test(taker)) {
-    throw new SwapPrepareError(400, "taker must be the wallet address that will sign");
-  }
-
-  const [inTok, outTok] = await Promise.all([
-    resolveAsset(chainId, sellSymbol),
-    resolveAsset(chainId, buySymbol),
-  ]);
-  if (!inTok) throw new SwapPrepareError(400, `could not resolve sell asset "${sellSymbol}" on chain ${chainId}`);
-  if (!outTok) throw new SwapPrepareError(400, `could not resolve buy asset "${buySymbol}" on chain ${chainId}`);
-
-  const amountIn = toRawUnits(body.sellAmount, inTok.decimals);
-
-  const r = await prepareBestRoute(
-    {
-      chainId,
-      tokenIn: inTok.address || sellSymbol,
-      tokenOut: outTok.address || buySymbol,
-      amountIn,
-      taker,
-      decimalsIn: inTok.decimals ?? null,
-      decimalsOut: outTok.decimals ?? null,
-      source: typeof body.source === "string" && body.source.trim() !== "" ? body.source.trim() : undefined,
-    },
-    opts,
-  );
-
-  if (!r.ok) {
-    // A liquidity/impact rejection is a real answer, not a server fault.
-    return {
-      ok: false,
-      reason: r.reason,
-      priceImpactBlocked: Boolean(r.priceImpactBlocked),
-      requiresWalletSignature: true,
-      backendSigner: false,
-    };
-  }
-
-  const dOut = outTok.decimals ?? 18;
-  const buyAmountRaw = r.minOut ?? r.chosen?.netOut ?? r.chosen?.grossOut ?? null;
-
-  return {
-    ok: true,
-    requiresWalletSignature: true,
-    backendSigner: false,
-    quote: {
-      sellSymbol,
-      buySymbol,
-      sellAmount: String(body.sellAmount),
-      // Raw units stay authoritative; the formatted value is for display only.
-      // Emitting only the formatted string is what broke portfolio pricing.
-      buyAmount: buyAmountRaw == null ? null : String(buyAmountRaw),
-      buyAmountFormatted:
-        buyAmountRaw == null ? null : (Number(buyAmountRaw) / 10 ** dOut).toString(),
-      routeLabel: r.chosen?.source ?? null,
-      priceImpactPct: Number.isFinite(Number(r.chosen?.priceImpactPct))
-        ? Number(r.chosen.priceImpactPct)
-        : null,
-      // Absent is unknown, not zero. Inventing a slippage cap prints a
-      // protection level the route never quoted.
-      slippageBps: Number.isFinite(Number(r.slippageBps)) ? Number(r.slippageBps) : null,
-      intentHash: r.intentHash ?? null,
-      minOut: r.minOut ?? null,
-      requiresApproval: r.requiresApproval ?? null,
-      warnings: Array.isArray(r.warnings) ? r.warnings : [],
-    },
-    transaction: r.transaction ?? null,
-  };
-}

package/src/equities/bridge.mjs

@@ -1,388 +0,0 @@
-// Bridge and reachability.
-//
-// The best price on a venue you cannot reach is not the best execution. This module annotates
-// a route with what it costs and how long it takes to move funds to the chain the venue lives on.
-//
-// Three rules hold everywhere in this file:
-//   1. Nothing here is live. Every emission is an ESTIMATE, never a quote.
-//   2. Unknown is not zero. An unlisted chain pair returns costAccounted false with a machine
-//      readable reason. An invented bridge cost would silently change which venue wins.
-//   3. A bridged leg is never atomic. Origin confirmation is not destination arrival, and that
-//      gap is where users double send. The nonAtomic flag cannot be dropped or set false.
-//
-// All bps values are fixed point from src/num.mjs. estMinutes is a plain nonnegative integer
-// count of wall clock minutes, which is a duration and not a monetary field.
-
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-
-import { parseDecimal } from './num.mjs';
-
-const ROUTES_PATH = fileURLToPath(new URL('../fixtures/bridge_routes.json', import.meta.url));
-
-export const BRIDGE_ESTIMATE_KIND = 'bridge-estimate';
-const ESTIMATE_LABEL = 'ESTIMATE';
-const MACHINE_REASON = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const ROUTE_KINDS = new Set(['identity', 'table', 'unknown', 'unevaluated']);
-const CONFIDENCES = new Set(['exact', 'estimate']);
-
-// Structural zero. The identity answer is derived from this constant, never from a table row,
-// so no fixture edit can turn "funds are already there" into a nonzero cost.
-const ZERO_BPS = Object.freeze(parseDecimal('0'));
-
-function fail(path, message) {
-  throw new TypeError(`${path} ${message}`);
-}
-
-function isRecord(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function isFixed(value) {
-  return (
-    isRecord(value) &&
-    typeof value.mantissa === 'bigint' &&
-    Number.isSafeInteger(value.scale) &&
-    value.scale >= 0
-  );
-}
-
-function requireChain(value, name) {
-  if (typeof value !== 'string' || value.length === 0) {
-    fail(`bridge.${name}`, 'must be a nonempty chain name');
-  }
-  return value;
-}
-
-function deepFreeze(value) {
-  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
-    Object.freeze(value);
-    for (const child of Object.values(value)) deepFreeze(child);
-  }
-  return value;
-}
-
-function routeError(message) {
-  throw new TypeError(`Fixture fixtures/bridge_routes.json: ${message}`);
-}
-
-function validateRouteTable(table, origin) {
-  if (!isRecord(table)) routeError(`${origin} root must be an object`);
-  if (!Array.isArray(table.routes) || table.routes.length === 0) {
-    routeError(`${origin} routes must be a nonempty array`);
-  }
-
-  const seen = new Set();
-  table.routes.forEach((route, index) => {
-    const at = `${origin} routes[${index}]`;
-    if (!isRecord(route)) routeError(`${at} must be an object`);
-    for (const key of ['from', 'to']) {
-      if (typeof route[key] !== 'string' || route[key].length === 0) {
-        routeError(`${at}.${key} must be a nonempty string`);
-      }
-    }
-    // Authored as a decimal string so it enters fixed point without ever being a float.
-    if (typeof route.estBps !== 'string' || !/^\d+(?:\.\d+)?$/.test(route.estBps)) {
-      routeError(`${at}.estBps must be a nonnegative decimal string`);
-    }
-    if (!Number.isSafeInteger(route.estMinutes) || route.estMinutes < 0) {
-      routeError(`${at}.estMinutes must be a nonnegative safe integer`);
-    }
-    if (typeof route.atomic !== 'boolean') {
-      routeError(`${at}.atomic must be a boolean`);
-    }
-    if (route.from !== route.to && route.atomic !== false) {
-      routeError(`${at}.atomic must be false because a bridged leg is not atomic`);
-    }
-    if (
-      Object.hasOwn(route, 'exercisedByLiveVenue') &&
-      typeof route.exercisedByLiveVenue !== 'boolean'
-    ) {
-      routeError(`${at}.exercisedByLiveVenue must be a boolean when present`);
-    }
-
-    const key = `${route.from}\u0000${route.to}`;
-    if (seen.has(key)) routeError(`${at} duplicates directed pair ${route.from} to ${route.to}`);
-    seen.add(key);
-  });
-
-  return table;
-}
-
-let cachedTable;
-
-export function loadBridgeRoutes({ path = ROUTES_PATH } = {}) {
-  if (path === ROUTES_PATH && cachedTable) return cachedTable;
-
-  let source;
-  try {
-    source = readFileSync(path, 'utf8');
-  } catch (error) {
-    if (error?.code === 'ENOENT') {
-      throw new Error(`Fixture fixtures/bridge_routes.json is missing at ${path}`);
-    }
-    throw new Error(`Fixture fixtures/bridge_routes.json could not be read: ${error.message}`);
-  }
-
-  let data;
-  try {
-    data = JSON.parse(source);
-  } catch (error) {
-    throw new SyntaxError(
-      `Fixture fixtures/bridge_routes.json contains invalid JSON: ${error.message}`,
-    );
-  }
-
-  const table = deepFreeze(validateRouteTable(data, 'root'));
-  if (path === ROUTES_PATH) cachedTable = table;
-  return table;
-}
-
-function resolveTable(table) {
-  if (table === undefined) return loadBridgeRoutes();
-  return deepFreeze(validateRouteTable(table, 'supplied'));
-}
-
-function chainsOf(table) {
-  const chains = new Set();
-  for (const route of table.routes) {
-    chains.add(route.from);
-    chains.add(route.to);
-  }
-  return chains;
-}
-
-/** Every chain the estimate table knows about, live or forward looking. */
-export function listBridgeChains({ table } = {}) {
-  return [...chainsOf(resolveTable(table))].sort();
-}
-
-function findRoute(table, from, to) {
-  // Directed lookup only. A table that authored one direction says nothing about the other,
-  // and withdrawal cost is genuinely not symmetric in the real world.
-  return table.routes.find((route) => route.from === from && route.to === to) ?? null;
-}
-
-function emit(estimate) {
-  return Object.freeze({
-    kind: BRIDGE_ESTIMATE_KIND,
-    label: ESTIMATE_LABEL,
-    isQuote: false,
-    live: false,
-    ...estimate,
-  });
-}
-
-/**
- * Estimate the cost and time of getting funds from one chain to another.
- * Returns a frozen estimate. It is never a quote and never a promise.
- */
-export function estimateBridge({ from, to, table } = {}) {
-  requireChain(from, 'from');
-  requireChain(to, 'to');
-
-  const routes = resolveTable(table);
-
-  if (from === to) {
-    // Funds are already there. This is the common case and it is exactly zero, not a small
-    // fudge factor. Read only for metadata, never for the cost itself.
-    const row = findRoute(routes, from, to);
-    const exercised = row?.exercisedByLiveVenue === true;
-    return emit({
-      from,
-      to,
-      route: 'identity',
-      bridged: false,
-      nonAtomic: false,
-      estBps: ZERO_BPS,
-      estMinutes: 0,
-      costAccounted: true,
-      confidence: 'exact',
-      exercisedByLiveVenue: exercised,
-      forwardLooking: !exercised,
-      reason: null,
-      evidence: { knownFrom: true, knownTo: true },
-      source: 'identity',
-    });
-  }
-
-  const row = findRoute(routes, from, to);
-  if (row) {
-    const exercised = row.exercisedByLiveVenue === true;
-    return emit({
-      from,
-      to,
-      route: 'table',
-      bridged: true,
-      // Origin confirmation is not destination arrival.
-      nonAtomic: true,
-      estBps: Object.freeze(parseDecimal(row.estBps)),
-      estMinutes: row.estMinutes,
-      costAccounted: true,
-      confidence: 'estimate',
-      exercisedByLiveVenue: exercised,
-      forwardLooking: !exercised,
-      reason: null,
-      evidence: { knownFrom: true, knownTo: true },
-      source: 'fixtures/bridge_routes.json',
-    });
-  }
-
-  // Unknown. Do not guess. A fabricated bridge estimate would silently reorder a ranking.
-  const known = chainsOf(routes);
-  const knownFrom = known.has(from);
-  const knownTo = known.has(to);
-  return emit({
-    from,
-    to,
-    route: 'unknown',
-    bridged: true,
-    nonAtomic: true,
-    estBps: null,
-    estMinutes: null,
-    costAccounted: false,
-    confidence: null,
-    exercisedByLiveVenue: false,
-    forwardLooking: false,
-    reason: knownFrom && knownTo ? 'unknown-chain-pair' : 'unknown-chain',
-    evidence: { knownFrom, knownTo },
-    source: null,
-  });
-}
-
-/**
- * Contract check for a bridge estimate. The nonAtomic flag is structurally impossible to omit
- * or to falsify on a bridged leg.
- */
-export function validateBridgeEstimate(estimate) {
-  if (!isRecord(estimate)) fail('bridgeEstimate', 'must be an object');
-
-  if (estimate.kind !== BRIDGE_ESTIMATE_KIND) {
-    fail('bridgeEstimate.kind', `must be ${BRIDGE_ESTIMATE_KIND}`);
-  }
-  if (estimate.label !== ESTIMATE_LABEL) {
-    fail('bridgeEstimate.label', `must be ${ESTIMATE_LABEL} because nothing here is a quote`);
-  }
-  if (estimate.isQuote !== false) fail('bridgeEstimate.isQuote', 'must be false');
-  if (estimate.live !== false) fail('bridgeEstimate.live', 'must be false');
-
-  requireChain(estimate.from, 'from');
-  requireChain(estimate.to, 'to');
-  if (!ROUTE_KINDS.has(estimate.route)) {
-    fail('bridgeEstimate.route', `must be one of ${[...ROUTE_KINDS].join(', ')}`);
-  }
-  if (typeof estimate.bridged !== 'boolean') fail('bridgeEstimate.bridged', 'must be a boolean');
-
-  if (!Object.hasOwn(estimate, 'nonAtomic')) {
-    fail('bridgeEstimate.nonAtomic', 'is required on every bridge estimate');
-  }
-  if (typeof estimate.nonAtomic !== 'boolean') {
-    fail('bridgeEstimate.nonAtomic', 'must be a boolean');
-  }
-  if (estimate.bridged && estimate.nonAtomic !== true) {
-    fail(
-      'bridgeEstimate.nonAtomic',
-      'must be true for a bridged leg because origin confirmation is not destination arrival',
-    );
-  }
-  if (!estimate.bridged && estimate.nonAtomic !== false) {
-    fail('bridgeEstimate.nonAtomic', 'must be false when nothing moves');
-  }
-
-  if (typeof estimate.costAccounted !== 'boolean') {
-    fail('bridgeEstimate.costAccounted', 'must be a boolean');
-  }
-
-  if (estimate.costAccounted) {
-    if (!isFixed(estimate.estBps)) {
-      fail('bridgeEstimate.estBps', 'must be a fixed point value when costAccounted is true');
-    }
-    if (!Number.isSafeInteger(estimate.estMinutes) || estimate.estMinutes < 0) {
-      fail('bridgeEstimate.estMinutes', 'must be a nonnegative safe integer');
-    }
-    if (!CONFIDENCES.has(estimate.confidence)) {
-      fail('bridgeEstimate.confidence', `must be one of ${[...CONFIDENCES].join(', ')}`);
-    }
-    if (estimate.reason !== null) {
-      fail('bridgeEstimate.reason', 'must be null when the cost is accounted');
-    }
-  } else {
-    // Unknown is not zero and it is certainly not a number.
-    if (estimate.estBps !== null) {
-      fail('bridgeEstimate.estBps', 'must be null when costAccounted is false');
-    }
-    if (estimate.estMinutes !== null) {
-      fail('bridgeEstimate.estMinutes', 'must be null when costAccounted is false');
-    }
-    if (typeof estimate.reason !== 'string' || !MACHINE_REASON.test(estimate.reason)) {
-      fail('bridgeEstimate.reason', 'must be a machine readable lower case code');
-    }
-    if (estimate.confidence !== null) {
-      fail('bridgeEstimate.confidence', 'must be null when costAccounted is false');
-    }
-  }
-
-  if (typeof estimate.exercisedByLiveVenue !== 'boolean') {
-    fail('bridgeEstimate.exercisedByLiveVenue', 'must be a boolean');
-  }
-  if (typeof estimate.forwardLooking !== 'boolean') {
-    fail('bridgeEstimate.forwardLooking', 'must be a boolean');
-  }
-  if (!isRecord(estimate.evidence)) fail('bridgeEstimate.evidence', 'must be an object');
-
-  return estimate;
-}
-
-/**
- * The bps a caller may fold into a net of cost ranking, or null when there is no honest number.
- * A null here means the ranking must not silently treat the leg as free.
- */
-export function netAdjustmentBps(estimate) {
-  validateBridgeEstimate(estimate);
-  return estimate.costAccounted ? estimate.estBps : null;
-}
-
-function unevaluated(reason) {
-  return emit({
-    from: 'unknown',
-    to: 'unknown',
-    route: 'unevaluated',
-    bridged: true,
-    nonAtomic: true,
-    estBps: null,
-    estMinutes: null,
-    costAccounted: false,
-    confidence: null,
-    exercisedByLiveVenue: false,
-    forwardLooking: false,
-    reason,
-    evidence: { knownFrom: false, knownTo: false },
-    source: null,
-    evaluated: false,
-  });
-}
-
-/**
- * Annotate routes with reachability from a given chain. Purely additive: the annotation is
- * evidence beside the route, and it never rewrites the route's own costAccounted claim.
- * Callers fold reachability into ranking only when the user supplies a from chain.
- */
-export function annotateReachability(routes, { fromChain = null, table } = {}) {
-  if (!Array.isArray(routes)) fail('bridge.routes', 'must be an array');
-
-  if (fromChain === null || fromChain === undefined) {
-    const blank = unevaluated('no-from-chain');
-    return routes.map((route) => ({ ...route, reachability: blank }));
-  }
-
-  requireChain(fromChain, 'fromChain');
-
-  return routes.map((route) => {
-    const destination = route?.chain;
-    if (typeof destination !== 'string' || destination.length === 0) {
-      return { ...route, reachability: unevaluated('no-destination-chain') };
-    }
-    const estimate = estimateBridge({ from: fromChain, to: destination, table });
-    return { ...route, reachability: Object.freeze({ ...estimate, evaluated: true }) };
-  });
-}