@oracle-agent/oracle 0.13.1 → 0.14.0

package/src/data/providers/debridge.mjs

@@ -0,0 +1,109 @@
+// deBridge DLN cross-chain bridge provider.
+//
+// deBridge operates a decentralized liquidity network (DLN) for native
+// cross-chain value transfer. This module is read/prepare only — it quotes
+// routes and prepares unsigned transaction artifacts.
+//
+// Public API: https://dln.debridge.finance/v1.0
+// Docs: https://docs.dln.debridge.finance
+//
+// Never signs, never broadcasts, never holds keys.
+
+import { httpJson } from "../http.mjs";
+import { stampPrepared } from "../../prepare-envelope.mjs";
+
+export const DEBRIDGE_API = "https://dln.debridge.finance/v1.0";
+
+const SUPPORTED_CHAIN_IDS = new Set([
+  1, 10, 56, 137, 8453, 42161, 43114, 59144, 534352, 7777777, 324, 5000, 1101, 81457,
+]);
+
+/**
+ * Quote a cross-chain route through deBridge DLN.
+ * @returns {{ estimation: object, order: object, fixFee: string } | { error: string }}
+ */
+export async function debridgeQuote({
+  srcChainId,
+  srcChainTokenIn,
+  srcChainTokenInAmount,
+  dstChainId,
+  dstChainTokenOut,
+  slippage = 100, // bps, default 1%
+  affiliateFeePercent = "0",
+} = {}) {
+  if (!srcChainId || !dstChainId || !srcChainTokenIn || !dstChainTokenOut || !srcChainTokenInAmount) {
+    return { error: "debridge quote requires srcChainId, dstChainId, srcChainTokenIn, dstChainTokenOut, srcChainTokenInAmount" };
+  }
+  if (!SUPPORTED_CHAIN_IDS.has(Number(srcChainId)) || !SUPPORTED_CHAIN_IDS.has(Number(dstChainId))) {
+    return { error: `debridge: unsupported chain pair ${srcChainId} -> ${dstChainId}` };
+  }
+
+  try {
+    const body = {
+      srcChainId: String(srcChainId),
+      srcChainTokenIn,
+      srcChainTokenInAmount: String(srcChainTokenInAmount),
+      dstChainId: String(dstChainId),
+      dstChainTokenOut,
+      slippage,
+      affiliateFeePercent,
+    };
+
+    const data = await httpJson(`${DEBRIDGE_API}/dln/order/quote`, {
+      method: "POST",
+      body: JSON.stringify(body),
+      headers: { "content-type": "application/json" },
+    });
+
+    if (data.error) return { error: String(data.error) };
+
+    return {
+      estimation: data.estimation ?? {},
+      order: data.order ?? {},
+      fixFee: data.fixFee ?? "0",
+    };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+/**
+ * Check deBridge API health and supported chain pairs.
+ */
+export async function debridgeHealth() {
+  try {
+    const chains = await httpJson(`${DEBRIDGE_API}/supported-chains-info`);
+    return { ok: true, chainCount: chains?.chains?.length ?? 0 };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}
+
+/**
+ * Prepare an unsigned deBridge transaction for a quoted order.
+ * Follows the same custody contract: requiresWalletSignature, backendSigner false.
+ */
+export async function debridgePrepare(quote, { taker } = {}) {
+  if (!taker) throw new Error("debridge prepare requires taker address");
+
+  try {
+    const body = {
+      srcChainId: quote.order?.srcChainId ?? quote.srcChainId,
+      dstChainId: quote.order?.dstChainId ?? quote.dstChainId,
+      srcChainTokenIn: quote.order?.srcChainTokenIn ?? quote.srcChainTokenIn,
+      dstChainTokenOut: quote.order?.dstChainTokenOut ?? quote.dstChainTokenOut,
+      srcChainTokenInAmount: quote.order?.srcChainTokenInAmount ?? quote.srcChainTokenInAmount,
+      order: quote.order,
+    };
+
+    const data = await httpJson(`${DEBRIDGE_API}/dln/order/create-tx`, {
+      method: "POST",
+      body: JSON.stringify(body),
+      headers: { "content-type": "application/json" },
+    });
+
+    return stampPrepared(data.tx ?? data, { taker, source: "debridge" });
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}

package/src/data/providers/defillama.mjs

@@ -0,0 +1,88 @@
+// DeFiLlama public prices — protocol pack D3 (no API key).
+
+import { httpJson } from "../http.mjs";
+
+export const DEFILLAMA_COINS = "https://coins.llama.fi";
+export const DEFILLAMA_API = "https://api.llama.fi";
+export const DEFILLAMA_YIELDS = "https://yields.llama.fi";
+export const DEFILLAMA_STABLECOINS = "https://stablecoins.llama.fi";
+
+function coinsBase(opts = {}) {
+  return (opts.baseUrl || process.env.DEFILLAMA_COINS_URL || DEFILLAMA_COINS).replace(/\/$/, "");
+}
+
+function apiBase(opts = {}) {
+  return (opts.baseUrl || process.env.DEFILLAMA_API_URL || DEFILLAMA_API).replace(/\/$/, "");
+}
+
+/** @param {string[]} coins e.g. ['coingecko:ethereum','coingecko:bitcoin'] */
+export async function llamaPrices(coins, opts = {}) {
+  if (!Array.isArray(coins) || !coins.length) throw new Error("llamaPrices requires coins[]");
+  const path = coins.map(encodeURIComponent).join(",");
+  return httpJson(`${coinsBase(opts)}/prices/current/${path}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function llamaHealth(opts = {}) {
+  const data = await llamaPrices(["coingecko:ethereum"], opts);
+  const eth = data?.coins?.["coingecko:ethereum"];
+  return { ok: !!eth?.price, ethUsd: eth?.price ?? null };
+}
+
+export async function llamaProtocols(opts = {}) {
+  return httpJson(`${apiBase(opts)}/protocols`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+}
+
+export async function llamaYields(args = {}, opts = {}) {
+  const base = (opts.yieldsBaseUrl || process.env.DEFILLAMA_YIELDS_URL || DEFILLAMA_YIELDS).replace(/\/$/, "");
+  const result = await httpJson(`${base}/pools`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 30_000,
+  });
+  let rows = Array.isArray(result?.data) ? result.data : [];
+  if (args.chain) rows = rows.filter((x) => String(x.chain).toLowerCase() === String(args.chain).toLowerCase());
+  if (args.project) rows = rows.filter((x) => String(x.project).toLowerCase() === String(args.project).toLowerCase());
+  if (args.stablecoin != null) rows = rows.filter((x) => Boolean(x.stablecoin) === Boolean(args.stablecoin));
+  rows.sort((a, b) => Number(b.tvlUsd || 0) - Number(a.tvlUsd || 0));
+  const limit = Math.min(5000, Math.max(1, Number(args.limit || rows.length || 1)));
+  return { ...result, data: rows.slice(0, limit) };
+}
+
+export async function llamaStablecoins(args = {}, opts = {}) {
+  const base = (opts.stablecoinsBaseUrl || process.env.DEFILLAMA_STABLECOINS_URL || DEFILLAMA_STABLECOINS).replace(/\/$/, "");
+  const includePrices = args.includePrices !== false;
+  return httpJson(`${base}/stablecoins?includePrices=${includePrices}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 30_000,
+  });
+}
+
+export async function llamaDexVolumes(args = {}, opts = {}) {
+  const chain = encodeURIComponent(String(args.chain || "Ethereum"));
+  const params = new URLSearchParams({
+    excludeTotalDataChart: String(args.includeChart !== true),
+    excludeTotalDataChartBreakdown: String(args.includeBreakdown !== true),
+    dataType: "dailyVolume",
+  });
+  return httpJson(`${apiBase(opts)}/overview/dexs/${chain}?${params}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 30_000,
+  });
+}
+
+/** Convenience: map symbols via coingecko ids */
+export async function llamaPricesBySymbol(symbols = ["ethereum", "bitcoin", "solana"], opts = {}) {
+  const coins = symbols.map((s) => `coingecko:${String(s).toLowerCase()}`);
+  const data = await llamaPrices(coins, opts);
+  const out = {};
+  for (const s of symbols) {
+    const key = `coingecko:${String(s).toLowerCase()}`;
+    out[s] = data?.coins?.[key] || null;
+  }
+  return out;
+}

package/src/data/providers/dexscreener.mjs

@@ -0,0 +1,43 @@
+// DexScreener public API — token/pair discovery, no key.
+
+import { httpJson } from "../http.mjs";
+
+export const DEXSCREENER_API = "https://api.dexscreener.com";
+
+function base(opts = {}) {
+  return (opts.baseUrl || process.env.DEXSCREENER_API_URL || DEXSCREENER_API).replace(/\/$/, "");
+}
+
+export async function dexscreenerHealth(opts = {}) {
+  // tokenless root sometimes 404 — use a known stablecoin query
+  const data = await httpJson(
+    `${base(opts)}/latest/dex/search?q=USDC`,
+    { fetchImpl: opts.fetchImpl, timeoutMs: opts.timeoutMs ?? 12_000 }
+  );
+  const n = data?.pairs?.length || 0;
+  return { ok: n > 0, pairSample: n };
+}
+
+export async function dexscreenerToken(tokenAddress, opts = {}) {
+  if (!tokenAddress) throw new Error("tokenAddress required");
+  return httpJson(`${base(opts)}/latest/dex/tokens/${tokenAddress}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+}
+
+export async function dexscreenerSearch(q, opts = {}) {
+  if (!q) throw new Error("query required");
+  return httpJson(`${base(opts)}/latest/dex/search?q=${encodeURIComponent(q)}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+}
+
+export async function dexscreenerPair(chainId, pairAddress, opts = {}) {
+  if (!chainId || !pairAddress) throw new Error("chainId and pairAddress required");
+  return httpJson(`${base(opts)}/latest/dex/pairs/${chainId}/${pairAddress}`, {
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+}

package/src/data/providers/drift.mjs

@@ -0,0 +1,32 @@
+// Drift Protocol — largest Solana perps DEX (v2).
+// Public API: https://drift-labs.github.io/v2-teacher — all reads are public.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+export const DRIFT_API = "https://dlob.drift.trade";
+
+export async function driftMarkets() {
+  try {
+    // Drift markets are indexed via their SDK-compatible REST layer
+    const data = await httpJson(`${DRIFT_API}/v2/markets`);
+    return (data?.markets || []).map(m => ({
+      symbol: m?.symbol || m?.marketIndex,
+      oraclePrice: m?.amm?.oraclePrice,
+      markPrice: m?.amm?.markPrice,
+      fundingRate: m?.amm?.lastFundingRate ? `${(Number(m.amm.lastFundingRate) * 100).toFixed(4)}%` : null,
+      openInterest: { long: m?.amm?.longFunding, short: m?.amm?.shortFunding },
+      volume24h: m?.amm?.quoteAssetVolume,
+    }));
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function driftHealth() {
+  try {
+    return { ok: true, note: "Drift v2 perps on Solana — public reads via dlob.drift.trade" };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/dydx.mjs

@@ -0,0 +1,41 @@
+// dYdX — standalone perps chain (Cosmos SDK). Largest decentralized perps venue.
+// Public REST API: https://dydx.exchange — all reads are public.
+// Never signs, never broadcasts.
+
+import { httpJson } from "../http.mjs";
+
+export const DYDX_API = "https://api.dydx.exchange";
+
+export async function dydxMarkets(limit = 50) {
+  try {
+    const data = await httpJson(`${DYDX_API}/v4/perpetualMarkets?limit=${limit}`);
+    return (data?.markets || []).map(m => ({
+      ticker: m?.ticker,
+      oraclePrice: m?.oraclePrice,
+      indexPrice: m?.indexPrice,
+      nextFundingRate: m?.nextFundingRate ? `${(Number(m.nextFundingRate) * 100).toFixed(4)}%` : null,
+      openInterest: m?.openInterest,
+      volume24h: m?.volume24H,
+    }));
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function dydxOrderbook(ticker) {
+  try {
+    const data = await httpJson(`${DYDX_API}/v4/orderbooks/perpetualMarket/${ticker}`);
+    return { bids: data?.bids?.slice(0, 5), asks: data?.asks?.slice(0, 5) };
+  } catch (e) {
+    return { error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function dydxHealth() {
+  try {
+    const data = await httpJson(`${DYDX_API}/v4/time`);
+    return { ok: true, serverTime: data?.iso };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e).slice(0, 160) };
+  }
+}

package/src/data/providers/evm-rpc.mjs

@@ -0,0 +1,225 @@
+// EVM JSON-RPC read pack — multi-chain balances/blocks via public or env RPCs.
+// No wallet keys. Uses chain registry rpcEnv + optional public fallbacks.
+
+import { httpJson } from "../http.mjs";
+import { CHAINS, chainById, rpcUrlFor, isSupportedChain } from "../../chains.mjs";
+import { Interface, getAddress } from "ethers";
+
+const ERC20 = new Interface([
+  "function allowance(address owner,address spender) view returns (uint256)",
+  "function balanceOf(address account) view returns (uint256)",
+]);
+
+function normalizeAddress(value, label) {
+  try {
+    return getAddress(value).toLowerCase();
+  } catch {
+    throw new Error(`${label} must be a valid EVM address`);
+  }
+}
+
+function normalizeTxHash(value) {
+  const hash = String(value || "").trim();
+  if (!/^0x[0-9a-fA-F]{64}$/.test(hash)) throw new Error("txHash must be a 32-byte hex transaction hash");
+  return hash.toLowerCase();
+}
+
+function parseHexInt(value) {
+  if (value == null) return null;
+  return Number.parseInt(String(value), 16);
+}
+
+/** Public fallbacks when env RPC unset — rate-limited, fine for health/read. */
+export const PUBLIC_RPC_FALLBACKS = {
+  1: "https://ethereum.publicnode.com",
+  137: "https://polygon-bor-rpc.publicnode.com",
+  42161: "https://arbitrum-one-rpc.publicnode.com",
+  8453: "https://base-rpc.publicnode.com",
+  10: "https://optimism-rpc.publicnode.com",
+  988: "https://rpc.stable.xyz",
+  56: "https://bsc-rpc.publicnode.com",
+  43114: "https://avalanche-c-chain-rpc.publicnode.com",
+  999: "https://rpc.hyperliquid.xyz/evm",
+  2741: "https://api.mainnet.abs.xyz",
+  4663: "https://rpc.mainnet.chain.robinhood.com",
+};
+
+/**
+ * Resolve RPC URL for a chainId: explicit > env (registry) > public fallback.
+ */
+export function resolveRpcUrl(chainId, { rpcUrl, env = process.env } = {}) {
+  if (rpcUrl) return rpcUrl;
+  const fromEnv = rpcUrlFor(chainId, env);
+  if (fromEnv) return fromEnv;
+  return PUBLIC_RPC_FALLBACKS[Number(chainId)] || null;
+}
+
+/**
+ * JSON-RPC call
+ * @param {number} chainId
+ * @param {string} method
+ * @param {any[]} [params]
+ */
+
+// `rpcCall` is the raw public transport exposed by the data facade. It must be
+// an allowlist, not a partial write denylist: every unrecognized method is
+// unsafe to forward because vendors add write namespaces (`wallet_send*`,
+// `pm_sendUserOperation`, `mev_sendBundle`) faster than a denylist stays fresh.
+//
+// Canonical JSON-RPC method names are ASCII lowercase + underscores. Reject
+// whitespace, separator tricks, and Unicode homoglyphs rather than normalizing
+// them into a different network request.
+const EVM_READ_RPC = /^(?:eth_(?:call|blocknumber|chainid|get[a-z0-9]+|feehistory|gasprice|maxpriorityfeepergas|syncing|protocolversion|estimategas|createaccesslist)|net_(?:version|listening|peercount)|web3_(?:clientversion|sha3))$/;
+
+function readRpcMethod(method) {
+  const raw = String(method || "");
+  const probe = raw.toLowerCase();
+  if (raw !== raw.trim() || !/^[a-zA-Z0-9_]+$/.test(raw) || !EVM_READ_RPC.test(probe)) {
+    throw new Error(`evm-rpc: ${raw} refused — @oracle-agent/oracle is prepare-only (read RPC only; no broadcast/sign)`);
+  }
+  return probe;
+}
+
+export async function rpcCall(chainId, method, params = [], opts = {}) {
+  const methodName = String(method || "");
+  readRpcMethod(methodName);
+  const url = resolveRpcUrl(chainId, opts);
+  if (!url) {
+    throw new Error(
+      `No RPC URL for chainId ${chainId} (set env from chain registry rpcEnv or pass rpcUrl)`
+    );
+  }
+  const body = { jsonrpc: "2.0", id: 1, method, params };
+  const res = await httpJson(url, {
+    method: "POST",
+    body,
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 12_000,
+  });
+  if (res?.error) {
+    const err = new Error(res.error.message || JSON.stringify(res.error));
+    err.code = res.error.code;
+    throw err;
+  }
+  return res.result;
+}
+
+export async function rpcHealth(chainId, opts = {}) {
+  const blockHex = await rpcCall(chainId, "eth_blockNumber", [], opts);
+  const block = parseInt(blockHex, 16);
+  const idHex = await rpcCall(chainId, "eth_chainId", [], opts);
+  const reported = parseInt(idHex, 16);
+  return {
+    ok: Number.isFinite(block) && reported === Number(chainId),
+    chainId: Number(chainId),
+    reportedChainId: reported,
+    blockNumber: block,
+    name: chainById(chainId)?.name || null,
+  };
+}
+
+export async function rpcBlockNumber(chainId, opts = {}) {
+  const hex = await rpcCall(chainId, "eth_blockNumber", [], opts);
+  return parseInt(hex, 16);
+}
+
+export async function rpcChainId(chainId, opts = {}) {
+  const hex = await rpcCall(chainId, "eth_chainId", [], opts);
+  return parseInt(hex, 16);
+}
+
+export async function rpcGetBalance(chainId, address, opts = {}) {
+  if (!address) throw new Error("rpcGetBalance requires address");
+  const hex = await rpcCall(chainId, "eth_getBalance", [address, "latest"], opts);
+  return { chainId: Number(chainId), address, balanceWei: BigInt(hex).toString(), balanceHex: hex };
+}
+
+export async function erc20Allowance(args = {}, opts = {}) {
+  const chainId = Number(args.chainId ?? opts.chainId ?? 1);
+  const token = normalizeAddress(args.token || args.tokenAddress, "token");
+  const owner = normalizeAddress(args.owner, "owner");
+  const spender = normalizeAddress(args.spender, "spender");
+  const data = ERC20.encodeFunctionData("allowance", [owner, spender]);
+  const result = await rpcCall(chainId, "eth_call", [{ to: token, data }, args.blockTag || "latest"], opts);
+  const decoded = ERC20.decodeFunctionResult("allowance", result);
+  const allowance = BigInt(decoded[0]);
+  return {
+    chainId,
+    token,
+    owner,
+    spender,
+    allowance: allowance.toString(),
+    allowanceHex: `0x${allowance.toString(16)}`,
+    blockTag: args.blockTag || "latest",
+  };
+}
+
+export async function erc20BalanceOf(args = {}, opts = {}) {
+  const chainId = Number(args.chainId ?? opts.chainId ?? 1);
+  const token = normalizeAddress(args.token || args.tokenAddress, "token");
+  const account = normalizeAddress(args.account || args.owner || args.address, "account");
+  const data = ERC20.encodeFunctionData("balanceOf", [account]);
+  const result = await rpcCall(chainId, "eth_call", [{ to: token, data }, args.blockTag || "latest"], opts);
+  const decoded = ERC20.decodeFunctionResult("balanceOf", result);
+  const balance = BigInt(decoded[0]);
+  return {
+    chainId,
+    token,
+    account,
+    balance: balance.toString(),
+    balanceHex: `0x${balance.toString(16)}`,
+    blockTag: args.blockTag || "latest",
+  };
+}
+
+export async function transactionReceipt(args = {}, opts = {}) {
+  const chainId = Number(args.chainId ?? opts.chainId ?? 1);
+  const txHash = normalizeTxHash(args.txHash || args.hash || args.transactionHash);
+  const receipt = await rpcCall(chainId, "eth_getTransactionReceipt", [txHash], opts);
+  if (!receipt) {
+    return { ok: false, chainId, txHash, status: "pending", receipt: null, reason: "receipt pending" };
+  }
+  const statusNumber = parseHexInt(receipt.status);
+  let ok = statusNumber === 1;
+  const status = statusNumber === 1 ? "success" : statusNumber === 0 ? "reverted" : "unknown";
+  let reason = ok ? null : status === "reverted" ? "transaction reverted" : "unknown receipt status";
+  const expectedTo = args.expectedTo ? normalizeAddress(args.expectedTo, "expectedTo") : null;
+  const actualTo = receipt.to ? normalizeAddress(receipt.to, "receipt.to") : null;
+  if (expectedTo && actualTo !== expectedTo) {
+    ok = false;
+    reason = `to mismatch: expected ${expectedTo}, got ${actualTo || "null"}`;
+  }
+  return {
+    ok,
+    chainId,
+    txHash,
+    status,
+    reason,
+    statusCode: statusNumber,
+    to: actualTo,
+    from: receipt.from ? normalizeAddress(receipt.from, "receipt.from") : null,
+    blockNumber: parseHexInt(receipt.blockNumber),
+    transactionIndex: parseHexInt(receipt.transactionIndex),
+    logs: Array.isArray(receipt.logs) ? receipt.logs : [],
+    receipt,
+  };
+}
+
+export async function rpcHealthAll(opts = {}) {
+  const ids = opts.chainIds || Object.values(CHAINS).map((c) => c.chainId);
+  const out = {};
+  await Promise.all(
+    ids.map(async (id) => {
+      if (!isSupportedChain(id) && !PUBLIC_RPC_FALLBACKS[id] && !resolveRpcUrl(id, opts)) {
+        out[id] = { ok: false, error: "no rpc configured", chainId: id };
+        return;
+      }
+      try {
+        out[id] = await rpcHealth(id, opts);
+      } catch (e) {
+        out[id] = { ok: false, chainId: id, error: String(e.message || e) };
+      }
+    })
+  );
+  return out;
+}