@oracle-agent/oracle 0.11.0 → 0.13.0

package/bin/oracle-route.mjs

@@ -1,254 +0,0 @@
-#!/usr/bin/env node
-// oracle-route -- compare swap and bridge routes across every available source.
-//
-// Usage:
-//   oracle-route swap   <chain> <tokenIn> <tokenOut> [amountIn]
-//   oracle-route bridge <fromChain> <toChain> <token> [amountIn]
-//
-// <chain> is an id (8453) or key (base). --json for machine output.
-
-import { bestSwapRoute, bestBridgeRoute } from "../src/router/index.mjs";
-import { prepareBestRoute } from "../src/router/prepare-route.mjs";
-import { prepareBestBridgeRoute } from "../src/router/prepare-bridge.mjs";
-import { registerBuiltinScanners } from "../src/scanner/chains.config.mjs";
-import { getScanner, listScanners } from "../src/scanner/contract.mjs";
-
-registerBuiltinScanners();
-
-const [cmd, ...rest] = process.argv.slice(2);
-const JSON_OUT = rest.includes("--json");
-const args = rest.filter((a) => a !== "--json");
-const NATIVE = "0x0000000000000000000000000000000000000000";
-
-function chainId(ref) {
-  if (!ref) die("missing <chain>");
-  const n = Number(ref);
-  if (getScanner(n)) return n;
-  const s = listScanners().find((x) => x.key === String(ref).toLowerCase());
-  if (s) return s.chainId;
-  die(`unknown chain "${ref}". Known: ${listScanners().map((x) => x.key).join(", ")}`);
-}
-
-function die(msg) {
-  console.error(`error: ${msg}`);
-  process.exit(1);
-}
-
-function fmt(raw, decimals) {
-  const n = Number(raw) / 10 ** decimals;
-  return n.toLocaleString(undefined, { maximumFractionDigits: 6 });
-}
-
-function render(r, decimals) {
-  console.log(`sources: ${r.sourcesAnswered}/${r.sourcesTried} answered`);
-  console.log(`ranked on: ${r.rankedOn}\n`);
-
-  if (!r.routes.length) {
-    console.log("no source returned a usable route.");
-    for (const f of r.failed) console.log(`  ${f.source}: ${f.error}`);
-    return;
-  }
-
-  const w = Math.max(...r.routes.map((x) => x.source.length), 6);
-  console.log(`  ${"source".padEnd(w)}  ${"net out".padStart(14)}  ${"gross".padStart(14)}  cost`);
-  for (const [i, x] of r.routes.entries()) {
-    const mark = i === 0 ? "*" : " ";
-    const cost =
-      x.gasUsd == null
-        ? "gas unknown"
-        : x.gasUsd === 0
-          ? "gasless (solver)"
-          : `$${Number(x.gasUsd + (x.feeUsd ?? 0)).toFixed(2)}`;
-    const dur = x.meta?.durationSeconds != null ? `  ~${x.meta.durationSeconds}s` : "";
-    console.log(
-      `${mark} ${x.source.padEnd(w)}  ${fmt(x.netOut, decimals).padStart(14)}  ` +
-        `${fmt(x.grossOut, decimals).padStart(14)}  ${cost}${dur}`,
-    );
-  }
-
-  for (const f of r.failed) console.log(`  ${f.source.padEnd(w)}  FAILED: ${String(f.error).slice(0, 60)}`);
-
-  console.log(`\n${r.note}`);
-  for (const wn of r.warnings) console.log(`\nWARNING: ${wn}`);
-}
-
-try {
-  switch (cmd) {
-    case "swap": {
-      const cid = chainId(args[0]);
-      if (!args[1] || !args[2]) die("usage: oracle-route swap <chain> <tokenIn> <tokenOut> [amountIn]");
-      const amountIn = args[3] || (10n ** 18n).toString();
-      const scanner = getScanner(cid);
-
-      // Decimals matter twice: ParaSwap needs them to quote at all, and the ranker
-      // needs the destination's to convert gas into output units.
-      const [dIn, dOut] = await Promise.all([
-        scanner.resolveToken(args[1]).then((t) => t.decimals).catch(() => null),
-        scanner.resolveToken(args[2]).then((t) => t.decimals).catch(() => null),
-      ]);
-
-      const r = await bestSwapRoute({
-        chainId: cid,
-        tokenIn: args[1],
-        tokenOut: args[2],
-        amountIn,
-        taker: args[4] || "0x000000000000000000000000000000000000dEaD",
-        decimalsIn: dIn,
-        decimalsOut: dOut,
-      });
-      if (JSON_OUT) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
-      else render(r, dOut ?? 18);
-      break;
-    }
-
-    case "bridge": {
-      const from = chainId(args[0]);
-      const to = chainId(args[1]);
-      const token = args[2] || NATIVE;
-      const amountIn = args[3] || (10n ** 18n).toString();
-
-      const r = await bestBridgeRoute({
-        fromChainId: from,
-        toChainId: to,
-        tokenIn: token,
-        tokenOut: token,
-        amountIn,
-        taker: args[4] || "0x000000000000000000000000000000000000dEaD",
-        decimalsOut: 18,
-      });
-      if (JSON_OUT) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
-      else render(r, 18);
-      break;
-    }
-
-    case "prepare": {
-      const cid = chainId(args[0]);
-      if (!args[1] || !args[2] || !args[3]) {
-        die("usage: oracle-route prepare <chain> <tokenIn> <tokenOut> <taker> [amountIn] [--source=X]");
-      }
-      // Argument order puts taker BEFORE amount deliberately: preparing without a
-      // real taker is the one mistake that cannot be recovered from downstream.
-      const taker = args[3];
-      const amountIn = args[4] || (10n ** 18n).toString();
-      const srcArg = rest.find((a) => a.startsWith("--source="));
-      const scanner = getScanner(cid);
-
-      const [dIn, dOut] = await Promise.all([
-        scanner.resolveToken(args[1]).then((t) => t.decimals).catch(() => null),
-        scanner.resolveToken(args[2]).then((t) => t.decimals).catch(() => null),
-      ]);
-
-      const r = await prepareBestRoute({
-        chainId: cid,
-        tokenIn: args[1],
-        tokenOut: args[2],
-        amountIn,
-        taker,
-        decimalsIn: dIn,
-        decimalsOut: dOut,
-        source: srcArg ? srcArg.split("=")[1] : undefined,
-      });
-
-      if (JSON_OUT) {
-        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
-        break;
-      }
-
-      if (!r.ok) {
-        console.log(`could not prepare: ${r.reason}`);
-        if (r.failureKind) console.log(`kind: ${r.failureKind}`);
-        if (r.alternative) console.log(`try: --source=${r.alternative}`);
-        process.exit(1);
-      }
-
-      console.log(`source:      ${r.chosen.source}${r.chosen.wasWinner ? " (winner)" : " (override -- NOT the winner)"}`);
-      console.log(`artifact:    ${r.artifactKind}`);
-      console.log(`destination: ${r.destination}`);
-      if (r.minOut) console.log(`minOut:      ${r.minOut}`);
-      if (r.driftBps != null) console.log(`drift:       ${(r.driftBps / 100).toFixed(3)}% vs comparison`);
-      if (r.requiresApproval) {
-        console.log(`\napproval required first:`);
-        console.log(`  token   ${r.requiresApproval.token}`);
-        console.log(`  spender ${r.requiresApproval.spender}`);
-        if (r.requiresApproval.note) console.log(`  note    ${r.requiresApproval.note}`);
-      }
-      if (r.runnersUp?.length) {
-        console.log(`\nrunners-up: ${r.runnersUp.map((x) => x.source).join(", ")}`);
-      }
-      for (const w of r.warnings) console.log(`\nWARNING: ${w}`);
-      console.log(`\n${r.note}`);
-      break;
-    }
-
-    case "prepare-bridge": {
-      const from = chainId(args[0]);
-      const to = chainId(args[1]);
-      if (!args[2]) die("usage: oracle-route prepare-bridge <fromChain> <toChain> <taker> [token] [amountIn] [--source=X]");
-      const taker = args[2];
-      const token = args[3] || NATIVE;
-      const amountIn = args[4] || (10n ** 17n).toString();
-      const srcArg = rest.find((a) => a.startsWith("--source="));
-
-      const r = await prepareBestBridgeRoute({
-        fromChainId: from,
-        toChainId: to,
-        tokenIn: token,
-        tokenOut: token,
-        amountIn,
-        taker,
-        decimalsOut: 18,
-        source: srcArg ? srcArg.split("=")[1] : undefined,
-      });
-
-      if (JSON_OUT) {
-        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
-        break;
-      }
-      if (!r.ok) {
-        console.log(`could not prepare: ${r.reason}`);
-        if (r.failureKind) console.log(`kind: ${r.failureKind}`);
-        if (r.alternative) console.log(`try: --source=${r.alternative}`);
-        process.exit(1);
-      }
-
-      console.log(`source:      ${r.chosen.source}${r.chosen.wasWinner ? " (winner)" : " (override -- NOT the winner)"}`);
-      console.log(`artifact:    ${r.artifactKind}`);
-      console.log(`route:       chain ${r.fromChainId} -> chain ${r.toChainId}`);
-      console.log(`signs:       ${r.transactionCount} transaction(s) on chain ${r.fromChainId}`);
-      console.log(`destination: ${r.destination}`);
-      if (r.minOut) console.log(`minOut:      ${r.minOut}`);
-      if (r.durationSeconds != null) console.log(`eta:         ~${r.durationSeconds}s to credit`);
-      if (r.driftBps != null) console.log(`drift:       ${(r.driftBps / 100).toFixed(3)}% vs comparison`);
-      if (r.requiresApproval) {
-        console.log(`\napproval required first:`);
-        console.log(`  token   ${r.requiresApproval.token}`);
-        console.log(`  spender ${r.requiresApproval.spender}`);
-      }
-      r.transactions.forEach((t, i) => {
-        console.log(`\ntx ${i + 1}/${r.transactionCount}: chain ${t.chainId} -> ${t.to}`);
-      });
-      if (r.runnersUp?.length) console.log(`\nrunners-up: ${r.runnersUp.map((x) => x.source).join(", ")}`);
-      for (const w of r.warnings) console.log(`\nWARNING: ${w}`);
-      console.log(`\n${r.note}`);
-      break;
-    }
-
-    default:
-      console.log(
-        [
-          "oracle-route -- best-execution routing",
-          "",
-          "  oracle-route swap   <chain> <tokenIn> <tokenOut> [amountIn] [taker]",
-          "  oracle-route bridge <fromChain> <toChain> [token] [amountIn] [taker]",
-          "  oracle-route prepare <chain> <tokenIn> <tokenOut> <taker> [amountIn] [--source=X]",
-          "  oracle-route prepare-bridge <fromChain> <toChain> <taker> [token] [amt] [--source=X]",
-          "",
-          "  Ranks by NET output (gross minus gas and fees), not headline quote.",
-          "  A route quoting more but costing more gas can lose. --json for detail.",
-        ].join("\n"),
-      );
-      process.exit(cmd ? 1 : 0);
-  }
-} catch (err) {
-  die(String(err?.message || err));
-}

package/bin/oracle-scan.mjs

@@ -1,192 +0,0 @@
-#!/usr/bin/env node
-// oracle-scan -- exercise the chain-scanner framework from the shell.
-//
-// Useful for two things: checking a chain is actually reachable with your RPC
-// config, and researching a token without wiring up an agent first.
-//
-// Usage:
-//   oracle-scan chains                      coverage matrix for every chain
-//   oracle-scan head <chain>                current block
-//   oracle-scan token <chain> <address>     on-chain ERC-20 identity
-//   oracle-scan pools <chain> <address>     tradeable pools by liquidity
-//   oracle-scan risk  <chain> <address>     structural risk checks
-//
-// <chain> is a chain id (8453) or key (base).
-
-import { registerBuiltinScanners } from "../src/scanner/chains.config.mjs";
-import { getScanner, listScanners, scannerCoverage } from "../src/scanner/contract.mjs";
-
-registerBuiltinScanners();
-
-const [cmd, ...rest] = process.argv.slice(2);
-const JSON_OUT = rest.includes("--json");
-const args = rest.filter((a) => a !== "--json");
-
-function resolve(ref) {
-  if (!ref) die("missing <chain>");
-  const byId = getScanner(Number(ref));
-  if (byId) return byId;
-  const byKey = listScanners().find((s) => s.key === String(ref).toLowerCase());
-  if (byKey) return byKey;
-  die(
-    `unknown chain "${ref}". Known: ${listScanners().map((s) => `${s.key}(${s.chainId})`).join(", ")}`,
-  );
-}
-
-function die(msg) {
-  console.error(`error: ${msg}`);
-  process.exit(1);
-}
-
-function out(obj) {
-  process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
-}
-
-// A missing RPC is the most common reason a scan fails. Say so precisely instead of
-// surfacing a generic fetch error.
-function rpcHint(scanner, err) {
-  const msg = String(err?.message || err);
-  if (/rpc|fetch|ECONN|timeout|provider/i.test(msg)) {
-    return (
-      `${msg}\n\nThis chain reads its RPC from: ${scanner.rpcEnv.join(" or ")}\n` +
-      `Set one, e.g.:  export ${scanner.rpcEnv[0]}=https://...`
-    );
-  }
-  return msg;
-}
-
-try {
-  switch (cmd) {
-    case "chains": {
-      const cov = scannerCoverage();
-      if (JSON_OUT) {
-        out(cov);
-        break;
-      }
-      console.log(`${cov.chainCount} chains registered\n`);
-      const rows = Object.entries(cov.chains).map(([id, c]) => ({
-        chain: `${c.key} (${id})`,
-        caps: c.supported.length,
-        routing: c.failClosed ? "fail-closed (no verified venue)" : `${c.venueCount} venue(s)`,
-      }));
-      const w = Math.max(...rows.map((r) => r.chain.length));
-      for (const r of rows) {
-        console.log(`  ${r.chain.padEnd(w)}  ${String(r.caps).padStart(2)} caps   ${r.routing}`);
-      }
-      console.log(
-        "\nEvery chain is read/research capable. Routing value requires a verified\n" +
-          "venue -- see CONTRIBUTING.md for the verification rule.",
-      );
-      break;
-    }
-
-    case "head": {
-      const s = resolve(args[0]);
-      out(await s.blockNumber());
-      break;
-    }
-
-    case "token": {
-      const s = resolve(args[0]);
-      if (!args[1]) die("usage: oracle-scan token <chain> <address>");
-      out(await s.resolveToken(args[1]));
-      break;
-    }
-
-    case "pools": {
-      const s = resolve(args[0]);
-      if (!args[1]) die("usage: oracle-scan pools <chain> <address>");
-      const r = await s.resolvePools(args[1]);
-      if (JSON_OUT) {
-        out(r);
-        break;
-      }
-      console.log(`evidence: ${r.evidence}`);
-      if (r.reason) console.log(`reason:   ${r.reason}`);
-      for (const p of r.pools.slice(0, 10)) {
-        const liq = p.liquidityUsd == null ? "?" : `$${Math.round(p.liquidityUsd).toLocaleString()}`;
-        console.log(`  ${p.dex.padEnd(12)} ${liq.padStart(14)}  ${p.pair}`);
-      }
-      if (!r.pools.length) console.log("  (no pools with liquidity found)");
-      break;
-    }
-
-    case "risk": {
-      const s = resolve(args[0]);
-      if (!args[1]) die("usage: oracle-scan risk <chain> <address>");
-      const r = await s.scoreRisk(args[1]);
-      if (JSON_OUT) {
-        out(r);
-        break;
-      }
-      console.log(`verdict: ${r.verdict}\n`);
-      for (const c of r.checks) {
-        console.log(`  ${c.result.padEnd(8)} ${c.check.padEnd(16)} ${c.detail ?? ""}`);
-      }
-      console.log(`\n${r.note}`);
-      break;
-    }
-
-    case "quote": {
-      const s = resolve(args[0]);
-      if (!args[1] || !args[2]) die("usage: oracle-scan quote <chain> <tokenIn> <tokenOut> [amountIn]");
-      if (!s.supports("quote")) {
-        die(
-          `${s.key} has no verified router, so quoting stays fail-closed.\n` +
-            "Add a venue with recorded provenance -- see docs/adding-a-chain.md.",
-        );
-      }
-      const amountIn = args[3] || (10n ** 18n).toString();
-      out(await s.quote({ tokenIn: args[1], tokenOut: args[2], amountIn }));
-      break;
-    }
-
-    case "sell": {
-      // The single most valuable check on a low-cap venue: can you get OUT?
-      const s = resolve(args[0]);
-      if (!args[1]) die("usage: oracle-scan sell <chain> <token> [amountIn]");
-      if (!s.supports("sellSimulation")) {
-        die(
-          `${s.key} has no verified router, so sell simulation is unavailable.\n` +
-            "Without it, treat every token on this chain as unproven for exit.",
-        );
-      }
-      const amountIn = args[2] || (10n ** 16n).toString();
-      const r = await s.sellSimulation({ token: args[1], amountIn });
-      if (JSON_OUT) {
-        out(r);
-        break;
-      }
-      console.log(`verdict:   ${r.verdict}`);
-      console.log(`reason:    ${r.reason ?? ""}`);
-      if (r.retentionBps != null) {
-        console.log(`retention: ${(r.retentionBps / 100).toFixed(2)}%`);
-      }
-      if (r.leg) console.log(`failed at: ${r.leg} leg`);
-      if (r.note) console.log(`\n${r.note}`);
-      break;
-    }
-
-    default:
-      console.log(
-        [
-          "oracle-scan -- chain scanner CLI",
-          "",
-          "  oracle-scan chains                              coverage matrix",
-          "  oracle-scan head  <chain>                       current block",
-          "  oracle-scan token <chain> <address>             ERC-20 identity",
-          "  oracle-scan pools <chain> <address>             pools by liquidity",
-          "  oracle-scan risk  <chain> <address>             structural risk checks",
-          "  oracle-scan quote <chain> <tIn> <tOut> [amt]    live exact-input quote",
-          "  oracle-scan sell  <chain> <token> [amt]         round-trip: can you exit?",
-          "",
-          "  <chain> is an id (8453) or key (base).  --json for machine output.",
-          "  quote/sell need a chain with a verified router (see: oracle-scan chains).",
-        ].join("\n"),
-      );
-      process.exit(cmd ? 1 : 0);
-  }
-} catch (err) {
-  const s = args[0] ? (getScanner(Number(args[0])) || listScanners().find((x) => x.key === args[0])) : null;
-  die(s ? rpcHint(s, err) : String(err?.message || err));
-}

package/bin/oracle-upgrade.mjs

@@ -1,42 +0,0 @@
-#!/usr/bin/env node
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { upgradeProfiles } from "../src/profile-upgrade.mjs";
-
-const argv = process.argv.slice(2);
-const value = (flag) => {
-  const index = argv.indexOf(flag);
-  if (index < 0) return null;
-  if (!argv[index + 1] || argv[index + 1].startsWith("--")) throw new Error(`${flag} requires a value`);
-  return argv[index + 1];
-};
-
-try {
-  const known = new Set(["--apply", "--json", "--only", "--hermes-home", "--package-root", "--control-command"]);
-  for (let i = 0; i < argv.length; i += 1) {
-    if (!known.has(argv[i])) throw new Error(`unknown option: ${argv[i]}`);
-    if (["--only", "--hermes-home", "--package-root", "--control-command"].includes(argv[i])) i += 1;
-  }
-  const packageRoot = path.resolve(value("--package-root") || path.join(path.dirname(fileURLToPath(import.meta.url)), ".."));
-  const hermesHome = path.resolve(value("--hermes-home") || process.env.HERMES_HOME || path.join(os.homedir(), ".hermes"));
-  const control = value("--control-command");
-  const result = upgradeProfiles({
-    hermesHome,
-    packageRoot,
-    only: value("--only"),
-    apply: argv.includes("--apply"),
-    controlCommand: control ? control.trim().split(/\s+/) : null,
-  });
-  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-  else {
-    console.log(`oracle-upgrade ${result.applied ? "applied" : "dry run"}: ${result.profiles.length} profile(s)`);
-    for (const key of ["created", "updated", "unchanged", "backups"]) console.log(`${key}: ${result[key].length}`);
-    if (!result.applied) console.log("Re-run with --apply to make these changes.");
-  }
-} catch (error) {
-  const failure = { ok: false, error: error.message };
-  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify(failure, null, 2)}\n`);
-  else console.error(`oracle-upgrade: ${error.message}`);
-  process.exitCode = 1;
-}