@oracle-agent/oracle 0.14.1 → 0.16.0

package/src/data/providers/wallet-watch.mjs

@@ -1,264 +0,0 @@
-// followWallet.mjs — read-only ERC20 transfer history for an EVM address.
-// Node >=18 ESM. No dependencies. No keys, no signing.
-//
-// Strategy: eth_getLogs with the wallet pinned into the indexed topic slots
-// (topic1=from, topic2=to). That keeps result sets tiny, so free-tier
-// "too many results" caps never trigger. Endpoints are chosen for real
-// archive depth; publicnode-style nodes are excluded (~128 block history).
-
-export const TRANSFER_TOPIC =
-  "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
-
-// Verified working archive endpoints (keyless). Ordered by preference.
-export const DEFAULT_ENDPOINTS = {
-  1: [
-    "https://mainnet.gateway.tenderly.co",
-    "https://eth.drpc.org",
-    "https://rpc.flashbots.net",
-  ],
-  8453: [
-    "https://base.gateway.tenderly.co",
-    "https://mainnet.base.org",
-    "https://base.drpc.org",
-  ],
-  42161: [
-    "https://arbitrum.gateway.tenderly.co",
-    "https://arb1.arbitrum.io/rpc",
-    "https://arbitrum.drpc.org",
-  ],
-};
-
-// Max blocks per eth_getLogs call. Sized to the tightest verified free cap
-// (drpc/base.org enforce 10_000; Tenderly allows far more but 10k is safe
-// everywhere and keeps failover between providers transparent).
-export const DEFAULT_CHUNK = 10_000;
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-const toHex = (n) => "0x" + BigInt(n).toString(16);
-const topicAddr = (a) => "0x" + "0".repeat(24) + a.slice(2).toLowerCase();
-const addrFromTopic = (t) => "0x" + t.slice(26).toLowerCase();
-
-// Errors that mean "same request might work later" -> retry.
-const TRANSIENT = /timeout|timed out|too many requests|rate.?limit|429|502|503|504|internal error|temporarily|aborted|fetch failed|ECONNRESET|socket hang up/i;
-// Errors that mean "this range is too big" -> split, don't retry.
-const TOO_BIG = /too many|exceeds|limited to|not supported on free plan|response too large|range must not exceed|narrow your filter/i;
-
-class RpcError extends Error {
-  constructor(msg, { transient = false, tooBig = false, http = 0 } = {}) {
-    super(msg);
-    this.transient = transient;
-    this.tooBig = tooBig;
-    this.http = http;
-  }
-}
-
-async function rpcCall(url, method, params, timeoutMs) {
-  const ctl = new AbortController();
-  const timer = setTimeout(() => ctl.abort(), timeoutMs);
-  let res, text;
-  try {
-    res = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
-      signal: ctl.signal,
-    });
-    text = await res.text();
-  } catch (e) {
-    throw new RpcError(`${method} network: ${e.message}`, { transient: true });
-  } finally {
-    clearTimeout(timer);
-  }
-
-  let json;
-  try {
-    json = JSON.parse(text);
-  } catch {
-    // HTML error pages from CDNs (521/504) land here.
-    throw new RpcError(`${method} non-JSON http=${res.status}: ${text.slice(0, 80)}`, {
-      transient: res.status >= 500 || res.status === 429,
-      http: res.status,
-    });
-  }
-
-  if (json.error) {
-    const m = json.error.message || "rpc error";
-    throw new RpcError(`${method} rpc: ${m}`, {
-      transient: TRANSIENT.test(m),
-      tooBig: TOO_BIG.test(m),
-      http: res.status,
-    });
-  }
-  if (res.status !== 200) {
-    throw new RpcError(`${method} http=${res.status}: ${text.slice(0, 80)}`, {
-      transient: res.status >= 500 || res.status === 429,
-      http: res.status,
-    });
-  }
-  return json.result;
-}
-
-// Try each endpoint; retry transient failures with exponential backoff + jitter.
-async function withFailover(urls, method, params, { retries, timeoutMs, onWarn }) {
-  let last;
-  for (const url of urls) {
-    for (let attempt = 0; attempt <= retries; attempt++) {
-      try {
-        return { result: await rpcCall(url, method, params, timeoutMs), url };
-      } catch (e) {
-        last = e;
-        if (e.tooBig) throw e;               // caller must split the range
-        if (!e.transient) break;             // permanent for this endpoint -> next endpoint
-        if (attempt === retries) break;
-        const backoff = Math.min(2000 * 2 ** attempt, 8000) + Math.random() * 250;
-        onWarn?.(`retry ${url} (${e.message.slice(0, 70)}) in ${Math.round(backoff)}ms`);
-        await sleep(backoff);
-      }
-    }
-    onWarn?.(`endpoint exhausted: ${url} -> ${last?.message.slice(0, 70)}`);
-  }
-  throw last ?? new RpcError("no endpoints available");
-}
-
-// Fetch one window, halving recursively if the provider says it's too big.
-async function fetchWindow(urls, filter, from, to, cfg, out) {
-  let params = [{ ...filter, fromBlock: toHex(from), toBlock: toHex(to) }];
-  try {
-    const { result } = await withFailover(urls, "eth_getLogs", params, cfg);
-    if (Array.isArray(result)) out.push(...result);
-    return;
-  } catch (e) {
-    if (!e.tooBig || to <= from) throw e;
-    cfg.onWarn?.(`splitting ${from}-${to} (${e.message.slice(0, 60)})`);
-  }
-  const mid = from + Math.floor((to - from) / 2);
-  await fetchWindow(urls, filter, from, mid, cfg, out);
-  await fetchWindow(urls, filter, mid + 1, to, cfg, out);
-}
-
-/**
- * Read recent ERC20 transfers involving `address`.
- *
- * @param {string} address              0x-prefixed wallet address
- * @param {object} [opts]
- * @param {number[]} [opts.chains]      chain ids, default [1, 8453, 42161]
- * @param {number}  [opts.lookback]     blocks back from head, default 100000
- * @param {number}  [opts.fromBlock]    explicit start (overrides lookback)
- * @param {number}  [opts.toBlock]      explicit end, default head
- * @param {number}  [opts.chunkSize]    blocks per request, default 10000
- * @param {string[]}[opts.tokens]       restrict to these token contracts
- * @param {"in"|"out"|"both"} [opts.direction] default "both"
- * @param {number}  [opts.retries]      retries per endpoint, default 3
- * @param {number}  [opts.timeoutMs]    per-request timeout, default 20000
- * @param {number}  [opts.concurrency]  parallel chunks per chain, default 4
- * @param {object}  [opts.endpoints]    { chainId: [urls] } override
- * @param {(s:string)=>void} [opts.onWarn]
- * @returns {Promise<{events:Array,errors:Array,ranges:object}>}
- */
-export async function followWallet(address, opts = {}) {
-  if (!/^0x[0-9a-fA-F]{40}$/.test(address || "")) {
-    throw new Error(`invalid address: ${address}`);
-  }
-  const {
-    chains = [1, 8453, 42161],
-    lookback = 100_000,
-    fromBlock,
-    toBlock,
-    chunkSize = DEFAULT_CHUNK,
-    tokens,
-    direction = "both",
-    retries = 3,
-    timeoutMs = 20_000,
-    concurrency = 4,
-    endpoints = DEFAULT_ENDPOINTS,
-    onWarn,
-  } = opts;
-
-  const cfg = { retries, timeoutMs, onWarn };
-  const wallet = topicAddr(address);
-  const events = [];
-  const errors = [];
-  const ranges = {};
-  const seen = new Set(); // dedupe key: chainId|txHash|logIndex
-
-  await Promise.all(
-    chains.map(async (chainId) => {
-      const urls = endpoints[chainId];
-      if (!urls?.length) {
-        errors.push({ chainId, stage: "config", error: "no endpoints configured" });
-        return;
-      }
-      try {
-        // 1. Resolve the block range.
-        let head = toBlock;
-        if (head == null) {
-          const { result } = await withFailover(urls, "eth_blockNumber", [], cfg);
-          head = parseInt(result, 16);
-        }
-        const start = Math.max(0, fromBlock != null ? fromBlock : head - lookback + 1);
-        const end = Math.max(start, head);
-        ranges[chainId] = { fromBlock: start, toBlock: end, blocks: end - start + 1 };
-
-        // 2. Build chunk list.
-        const chunks = [];
-        for (let b = start; b <= end; b += chunkSize) {
-          chunks.push([b, Math.min(b + chunkSize - 1, end)]);
-        }
-
-        // 3. Topic filters — wallet pinned in indexed slots so results stay small.
-        const filters = [];
-        const base = tokens?.length ? { address: tokens } : {};
-        if (direction === "in" || direction === "both") {
-          filters.push({ ...base, topics: [TRANSFER_TOPIC, null, wallet] });
-        }
-        if (direction === "out" || direction === "both") {
-          filters.push({ ...base, topics: [TRANSFER_TOPIC, wallet, null] });
-        }
-
-        // 4. Run chunks with bounded concurrency.
-        const jobs = [];
-        for (const f of filters) for (const c of chunks) jobs.push([f, c]);
-
-        const raw = [];
-        let cursor = 0;
-        const workers = Array.from({ length: Math.min(concurrency, jobs.length) }, async () => {
-          while (cursor < jobs.length) {
-            const [filter, [lo, hi]] = jobs[cursor++];
-            try {
-              await fetchWindow(urls, filter, lo, hi, cfg, raw);
-            } catch (e) {
-              errors.push({ chainId, stage: "getLogs", range: [lo, hi], error: e.message });
-            }
-          }
-        });
-        await Promise.all(workers);
-
-        // 5. Normalize + dedupe.
-        for (const log of raw) {
-          if (!log?.topics || log.topics.length < 3) continue;      // skip ERC721 (4 topics) / malformed
-          const logIndex = parseInt(log.logIndex, 16);
-          const key = `${chainId}|${log.transactionHash}|${logIndex}`;
-          if (seen.has(key)) continue;
-          seen.add(key);
-          events.push({
-            chainId,
-            token: log.address.toLowerCase(),
-            from: addrFromTopic(log.topics[1]),
-            to: addrFromTopic(log.topics[2]),
-            value: BigInt(log.data === "0x" ? "0x0" : log.data).toString(),
-            blockNumber: parseInt(log.blockNumber, 16),
-            txHash: log.transactionHash,
-            logIndex,
-          });
-        }
-      } catch (e) {
-        errors.push({ chainId, stage: "range", error: e.message });
-      }
-    })
-  );
-
-  events.sort((a, b) => b.blockNumber - a.blockNumber || b.logIndex - a.logIndex);
-  return { events, errors, ranges };
-}
-
-export default followWallet;

package/src/data/providers/wormhole.mjs

@@ -1,28 +0,0 @@
-// Wormhole — Portal bridge + cross-chain messaging.
-// https://docs.wormhole.com — public REST APIs.
-// Never signs, never broadcasts.
-
-import { httpJson } from "../http.mjs";
-
-export const WORMHOLE_API = "https://api.portalbridge.com/v1";
-
-export async function wormholeQuote({ fromChain, toChain, token, amount } = {}) {
-  if (!fromChain || !toChain || !token || !amount) {
-    return { error: "wormhole quote requires fromChain, toChain, token, amount" };
-  }
-  try {
-    const params = new URLSearchParams({ fromChain: String(fromChain), toChain: String(toChain), token, amount: String(amount) });
-    const data = await httpJson(`${WORMHOLE_API}/quote?${params}`);
-    return { amountOut: data?.amountOut, fee: data?.fee, estimatedTime: data?.estimatedTime };
-  } catch (e) {
-    return { error: String(e.message || e).slice(0, 200) };
-  }
-}
-
-export async function wormholeHealth() {
-  try {
-    return { ok: true, note: "Portal bridge by Wormhole — 30+ chains" };
-  } catch (e) {
-    return { ok: false, error: String(e.message || e).slice(0, 160) };
-  }
-}

package/src/data/providers/yearn.mjs

@@ -1,31 +0,0 @@
-// Yearn Finance — yield aggregator across strategies.
-// https://docs.yearn.fi — public API.
-// Never signs, never broadcasts.
-
-import { httpJson } from "../http.mjs";
-
-const YEARN_API = "https://api.yearn.fi/v1";
-
-export async function yearnVaults() {
-  try {
-    const data = await httpJson(`${YEARN_API}/vaults/all`);
-    return (data || []).map(v => ({
-      name: v?.name,
-      symbol: v?.symbol,
-      apy: v?.apy?.net_apy ? `${(Number(v.apy.net_apy) * 100).toFixed(2)}%` : null,
-      tvl: v?.tvl?.tvl_deposited,
-      chain: v?.chainId,
-      type: v?.type || "v2",
-    }));
-  } catch (e) {
-    return { error: String(e.message || e).slice(0, 200) };
-  }
-}
-
-export async function yearnHealth() {
-  try {
-    return { ok: true, note: "Yearn — yield aggregator across Ethereum, Arbitrum, Optimism, Fantom" };
-  } catch (e) {
-    return { ok: false, error: String(e.message || e).slice(0, 160) };
-  }
-}

package/src/data/providers/zerox.mjs

@@ -1,167 +0,0 @@
-// 0x Swap API v2 — price/quote. Requires ZEROX_API_KEY (or 0X_API_KEY).
-
-import { httpJson } from "../http.mjs";
-import { attachAutoSlippage, bindAutoSlippageGuardToCall, resolveAutoSlippage } from "../../auto-slippage.mjs";
-import { resolveProviderEndpoint, credentialedHeaders } from "../provider-endpoint.mjs";
-import { stampPrepared } from "../../prepare-envelope.mjs";
-
-export const ZEROX_API = "https://api.0x.org";
-
-function endpoint(opts = {}) {
-  return resolveProviderEndpoint({
-    provider: "zerox",
-    defaultUrl: ZEROX_API,
-    hosts: ["api.0x.org"],
-    url: opts.baseUrl || process.env.ZEROX_API_URL,
-  });
-}
-
-function base(opts = {}) {
-  return endpoint(opts).baseUrl;
-}
-
-function apiKey(opts = {}) {
-  return (
-    opts.apiKey ||
-    process.env.ZEROX_API_KEY ||
-    process.env.OX_API_KEY ||
-    process.env["0X_API_KEY"] ||
-    ""
-  );
-}
-
-function headers(opts = {}) {
-  return credentialedHeaders(
-    { "0x-version": "v2", accept: "application/json" },
-    { "0x-api-key": apiKey(opts) },
-    endpoint(opts).trusted
-  );
-}
-
-export async function zeroxHealth(opts = {}) {
-  if (!apiKey(opts)) {
-    return { ok: false, configured: false, error: "ZEROX_API_KEY not set" };
-  }
-  try {
-    const q = await zeroxPrice(
-      {
-        chainId: 8453,
-        sellToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
-        buyToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
-        sellAmount: "1000000000000000",
-      },
-      opts
-    );
-    return { ok: true, configured: true, buyAmount: q.buyAmount || q.grossBuyAmount };
-  } catch (e) {
-    return { ok: false, configured: true, error: String(e.message || e).slice(0, 160) };
-  }
-}
-
-/** Indicative price (no firm quote). */
-export async function zeroxPrice(q = {}, opts = {}) {
-  if (!apiKey(opts)) throw new Error("ZEROX_API_KEY required for 0x");
-  const {
-    chainId = 8453,
-    sellToken,
-    buyToken,
-    sellAmount,
-    taker,
-  } = q;
-  if (!sellToken || !buyToken || !sellAmount) {
-    throw new Error("zeroxPrice requires sellToken, buyToken, sellAmount");
-  }
-  const params = new URLSearchParams({
-    chainId: String(chainId),
-    sellToken,
-    buyToken,
-    sellAmount: String(sellAmount),
-  });
-  if (taker) params.set("taker", taker);
-  return httpJson(`${base(opts)}/swap/allowance-holder/price?${params}`, {
-    headers: headers(opts),
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 15_000,
-  });
-}
-
-/** Firm quote (may include transaction). */
-export async function zeroxQuote(q = {}, opts = {}) {
-  if (!apiKey(opts)) throw new Error("ZEROX_API_KEY required for 0x");
-  const {
-    chainId = 8453,
-    sellToken,
-    buyToken,
-    sellAmount,
-    taker,
-  } = q;
-  if (!sellToken || !buyToken || !sellAmount) {
-    throw new Error("zeroxQuote requires sellToken, buyToken, sellAmount");
-  }
-  const selected = resolveAutoSlippage({
-    liquidityUsd: q.liquidityUsd,
-    priceChange5m: q.priceChange5m,
-    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
-  });
-  if (!selected.executable) {
-    throw new Error(`0x: route requires ${selected.requiredBps} bps above cap ${selected.capBps}`);
-  }
-  const params = new URLSearchParams({
-    chainId: String(chainId),
-    sellToken,
-    buyToken,
-    sellAmount: String(sellAmount),
-    slippageBps: String(selected.selectedBps),
-  });
-  if (taker) params.set("taker", taker);
-  const result = await httpJson(`${base(opts)}/swap/allowance-holder/quote?${params}`, {
-    headers: headers(opts),
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs ?? 15_000,
-  });
-  const amountOut = result?.buyAmount || result?.grossBuyAmount;
-  if (!amountOut) return { ...result, autoSlippagePolicy: selected };
-  return attachAutoSlippage(result, {
-    chainId,
-    venue: result?.transaction?.to || result?.to || "0x",
-    amountOut,
-    liquidityUsd: q.liquidityUsd,
-    priceChange5m: q.priceChange5m,
-    requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
-  });
-}
-
-export async function zeroxPrepare(q = {}, opts = {}) {
-  if (!q.taker) throw new Error("0x: taker required for executable prepare");
-  const quote = await zeroxQuote(q, opts);
-  const tx = quote?.transaction;
-  if (!tx?.to || !tx?.data) throw new Error("0x: firm quote returned no transaction");
-  const chainId = Number(q.chainId ?? 8453);
-  const spender = quote?.issues?.allowance?.spender || quote?.allowanceTarget;
-  return stampPrepared({
-    provider: "zerox",
-    calldataReady: true,
-    // NOT executable authority. The bytes are assembled but nothing is signed:
-    // the user's wallet is still the only thing that can authorize this. The
-    // previous `executionReady: true` read as "cleared to execute" and trained
-    // agents to treat a quote as permission.
-    requiresUserSignature: true,
-    signingReady: false,
-    broadcastReady: false,
-    chainId,
-    quote,
-    autoSlippage: quote.autoSlippage,
-    requiresApproval: quote?.issues?.allowance?.actual != null && BigInt(quote.issues.allowance.actual) < BigInt(q.sellAmount)
-      ? { token: q.sellToken, spender, amount: String(q.sellAmount) }
-      : null,
-    transaction: {
-      chainId,
-      from: q.taker,
-      to: tx.to,
-      data: tx.data,
-      value: tx.value ?? "0x0",
-      ...(tx.gas != null ? { gasLimit: tx.gas } : {}),
-      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: tx.to, data: tx.data }),
-    },
-  }, { provider: "zerox", kind: "zerox-tx" });
-}

package/src/data/public-api-scan.mjs

@@ -1,61 +0,0 @@
-import { dataCatalog, dataHealth } from "./desk-data.mjs";
-
-export const COVERED_CHAINS = Object.freeze({
-  1: "Ethereum",
-  10: "Optimism",
-  56: "BNB Chain",
-  137: "Polygon",
-  988: "Stable",
-  999: "HyperEVM",
-  2741: "Abstract",
-  4663: "Robinhood Chain",
-  8453: "Base",
-  42161: "Arbitrum",
-  43114: "Avalanche",
-});
-
-function providerStatus(record) {
-  if (!record) return "not-probed";
-  if (!record.ok) return "down";
-  if (record.detail?.configured === false) return "key-missing";
-  if (record.detail?.ok === false) return "degraded";
-  return "healthy";
-}
-
-export function buildPublicApiCoverage(catalog, health) {
-  const globals = catalog.filter((p) => !p.chainIds.length).map((p) => p.id);
-  const providers = Object.fromEntries(catalog.map((p) => [p.id, {
-    venue: p.venue,
-    auth: p.auth,
-    chainIds: p.chainIds,
-    ops: p.ops,
-    description: p.description,
-    status: providerStatus(health?.providers?.[p.id]),
-    probe: health?.providers?.[p.id] || null,
-  }]));
-  const chains = {};
-  for (const [chainId, name] of Object.entries(COVERED_CHAINS)) {
-    const id = Number(chainId);
-    const explicit = catalog.filter((p) => p.chainIds.includes(id)).map((p) => p.id);
-    chains[chainId] = {
-      name,
-      providers: [...new Set([...globals, ...explicit])],
-      explicitProviders: explicit,
-      failClosed: explicit.length === 0,
-    };
-  }
-  return {
-    generatedAt: health?.when || new Date().toISOString(),
-    coveredChainCount: Object.keys(COVERED_CHAINS).length,
-    providerCount: catalog.length,
-    globals,
-    chains,
-    providers,
-  };
-}
-
-export async function scanPublicApis({ providers, timeoutMs = 12_000 } = {}) {
-  const catalog = dataCatalog();
-  const health = await dataHealth({ providers, timeoutMs });
-  return buildPublicApiCoverage(catalog, health);
-}

package/src/data/quote-placeholder.mjs

@@ -1,31 +0,0 @@
-// Placeholder addresses for quote-only provider calls.
-//
-// Several aggregator APIs (LI.FI, CoW, bridge quoters) require a `from`/`user`
-// address to price a route, even when nothing will be signed. Hardcoding a real
-// operator wallet as that default is a privacy and correctness bug: public users
-// would silently quote against someone else's account, and balance-aware routers
-// can return routes tailored to that stranger's holdings.
-//
-// So: callers SHOULD pass their own address. When they don't, we fall back to a
-// well-known burn/zero-ish placeholder that holds nothing and signs nothing.
-//
-// vitalik.eth is deliberately NOT used here either -- a placeholder must be
-// obviously inert, not a real person's account.
-
-/**
- * ERC-191 "dead" address. Universally recognizable as a placeholder, holds no
- * meaningful balance, and cannot sign. Safe default for price-only queries.
- */
-export const QUOTE_PLACEHOLDER_ADDRESS =
-  "0x000000000000000000000000000000000000dEaD";
-
-/**
- * Resolve the address to use for a quote-only request.
- *
- * @param {string} [preferred] caller-supplied address (their own wallet)
- * @returns {string} the caller's address when usable, else the inert placeholder
- */
-export function quoteAddress(preferred) {
-  const v = String(preferred || "").trim();
-  return /^0x[0-9a-fA-F]{40}$/.test(v) ? v : QUOTE_PLACEHOLDER_ADDRESS;
-}