@oracle-agent/oracle 0.1.0

package/src/data/http.mjs

@@ -0,0 +1,200 @@
+// Tiny HTTP helpers for the read-only data plane. No signing. No secrets logged.
+//
+// Optimizations that matter for a self-hoster hitting public rate limits:
+//   - bounded retry with Retry-After support on 429 / 502 / 503 / 504
+//   - single-flight dedupe so N concurrent identical GETs cost ONE upstream call
+//   - both are opt-out via opts.retries = 0 / opts.dedupe = false
+//
+// SECURITY: the dedupe key binds the FULL credential (hashed), not merely whether
+// one was present. Keying on presence alone lets two callers with different API
+// keys collapse into one upstream request, so the second caller receives data
+// fetched with the first caller's credential. Found in pre-public red team.
+
+import { createHash } from "node:crypto";
+
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+// Methods safe to replay when the transport failed and we cannot know whether
+// the server already applied the request.
+const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]);
+const DEFAULT_RETRIES = 2;
+const MAX_BACKOFF_MS = 4_000;
+
+// Headers that identify the CALLER. Two requests may only share a deduped
+// in-flight response when every one of these matches exactly.
+// Any header that distinguishes one caller's credentials from another's. If a
+// credential header is MISSING from this list, two different users' requests
+// hash identically and the in-flight dedupe collapses them into one — user B
+// receives a response fetched with user A's key. Enumerating providers here is
+// fragile, so the matcher below also treats anything key/token/secret-shaped as
+// identity-bearing.
+const IDENTITY_HEADERS = [
+  "authorization",
+  "x-api-key",
+  "x-tensor-api-key",
+  "0x-api-key",
+  "api-key",
+  "cookie",
+  "proxy-authorization",
+];
+
+const inflight = new Map();
+
+/**
+ * Derive a dedupe key that is safe to hold in memory: credential material is
+ * hashed, never stored raw, so the cache cannot become a secret-disclosure
+ * surface (heap dump, debugger, accidental log of the map).
+ */
+function dedupeKey(method, url, headers) {
+  const lower = {};
+  for (const [k, v] of Object.entries(headers || {})) lower[k.toLowerCase()] = v;
+
+  // Structural, not just the known list: ANY header whose name looks like it
+  // carries a credential participates in the fingerprint. A fixed enumeration
+  // silently fails the moment a provider uses a new header name — that is how
+  // `0x-api-key` was omitted, which collapsed two users' 0x requests into one
+  // and served user B a response fetched with user A's key.
+  const credentialShaped = Object.keys(lower).filter((h) =>
+    /(^|-)(api[-_]?key|key|token|secret|auth|authorization|session|cookie|signature|access)(-|$)/.test(h)
+  );
+  const names = [...new Set([...IDENTITY_HEADERS, ...credentialShaped])].sort();
+  const identity = names.map((h) => `${h}=${lower[h] ?? ""}`).join("\n");
+  const fingerprint = createHash("sha256").update(identity).digest("hex").slice(0, 32);
+  return `${method} ${url} ${fingerprint}`;
+}
+
+function backoffMs(attempt, retryAfterHeader) {
+  const retryAfter = Number(retryAfterHeader);
+  if (Number.isFinite(retryAfter) && retryAfter > 0) {
+    return Math.min(retryAfter * 1000, MAX_BACKOFF_MS);
+  }
+  const base = Math.min(250 * 2 ** attempt, MAX_BACKOFF_MS);
+  return base + Math.floor(Math.random() * 100);
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function once(url, { fetchImpl, method, headers, body, timeoutMs }) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(url, { method, headers, body, signal: ac.signal });
+    const text = await res.text();
+    let json = null;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = null;
+      }
+    }
+    if (!res.ok) {
+      const err = new Error(`HTTP ${res.status} ${method} ${url}`);
+      err.status = res.status;
+      err.retryAfter = res.headers?.get?.("retry-after") ?? null;
+      err.body = json ?? text.slice(0, 300);
+      throw err;
+    }
+    return json ?? text;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/**
+ * @param {string} url
+ * @param {{ method?: string, headers?: Record<string,string>, body?: any, timeoutMs?: number, fetchImpl?: typeof fetch, retries?: number, dedupe?: boolean }} [opts]
+ */
+export async function httpJson(url, opts = {}) {
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("fetch unavailable — pass opts.fetchImpl");
+  }
+  const timeoutMs = opts.timeoutMs ?? 12_000;
+  const method = (opts.method || "GET").toUpperCase();
+  const headers = { Accept: "application/json", ...(opts.headers || {}) };
+  let body = opts.body;
+  if (body != null && typeof body !== "string") {
+    headers["Content-Type"] = headers["Content-Type"] || "application/json";
+    body = JSON.stringify(body);
+  }
+  const retries = Number.isInteger(opts.retries) ? Math.max(opts.retries, 0) : DEFAULT_RETRIES;
+
+  const attempt = async () => {
+    let lastError;
+    for (let i = 0; i <= retries; i++) {
+      try {
+        return await once(url, { fetchImpl, method, headers, body, timeoutMs });
+      } catch (error) {
+        lastError = error;
+        const status = error?.status;
+        const abortLike = error?.name === "AbortError";
+        // A response with a status means the SERVER answered and refused to
+        // process the request, so replaying it is safe. A transport-level
+        // failure (no status) is ambiguous: the server may have already applied
+        // the request and only the response was lost. Never replay a
+        // non-idempotent method on an ambiguous failure.
+        // A retryable STATUS is not on its own a licence to replay: a 500 or
+        // 503 can be returned after the server already applied the request, so
+        // replaying a POST can place a second order or submit a second
+        // transaction. 429/408/425 mean "not processed", so those stay
+        // retryable for every method; genuine server errors only replay for
+        // idempotent methods.
+        const ALWAYS_SAFE_STATUS = new Set([408, 425, 429]);
+        const retryable =
+          status != null
+            ? ALWAYS_SAFE_STATUS.has(status) ||
+              (RETRYABLE_STATUS.has(status) && IDEMPOTENT_METHODS.has(method))
+            : !abortLike && IDEMPOTENT_METHODS.has(method);
+        if (i === retries || !retryable) throw error;
+        await sleep(backoffMs(i, error?.retryAfter));
+      }
+    }
+    throw lastError;
+  };
+
+  // Single-flight only for idempotent GETs with no body.
+  const dedupe = opts.dedupe !== false && method === "GET" && body == null;
+  if (!dedupe) return attempt();
+
+  const key = dedupeKey(method, url, headers);
+  const existing = inflight.get(key);
+  if (existing) return existing;
+  const p = attempt().finally(() => inflight.delete(key));
+  inflight.set(key, p);
+  return p;
+}
+
+export async function timed(fn) {
+  const t0 = Date.now();
+  try {
+    const data = await fn();
+    return { ok: true, ms: Date.now() - t0, data };
+  } catch (e) {
+    return {
+      ok: false,
+      ms: Date.now() - t0,
+      error: String(e.message || e),
+      status: e.status ?? null,
+    };
+  }
+}
+
+/**
+ * Run async tasks with a hard concurrency ceiling. Public health sweeps fan out
+ * across ~30 providers; unbounded Promise.all trips public rate limits.
+ */
+export async function mapLimit(items, limit, fn) {
+  const list = Array.from(items);
+  const cap = Math.max(1, Math.min(Number(limit) || 1, list.length || 1));
+  const out = new Array(list.length);
+  let cursor = 0;
+  await Promise.all(
+    Array.from({ length: cap }, async () => {
+      while (cursor < list.length) {
+        const index = cursor++;
+        out[index] = await fn(list[index], index);
+      }
+    })
+  );
+  return out;
+}

package/src/data/provider-endpoint.mjs

@@ -0,0 +1,94 @@
+// Provider endpoint pinning.
+//
+// Every keyed provider had the same shape: `baseUrl` came from caller-supplied
+// opts, and headers() attached the operator's API key unconditionally. One
+// hostile opts object — from a prompt-injected model, a malicious skill, or a
+// config someone pasted — ships the credential to an arbitrary host. That is
+// credential exfiltration and SSRF wearing a configuration costume.
+//
+// The rule here: a credential is attached ONLY when the resolved host is one
+// the provider is pinned to. Overriding the URL is still allowed (local mocks,
+// self-hosted proxies, testing) but doing so DROPS the key rather than
+// forwarding it somewhere new.
+
+const OVERRIDE_ENV = "ORACLE_ALLOW_CUSTOM_PROVIDER_URL";
+
+/**
+ * @param {object} spec
+ * @param {string} spec.provider   provider id, for error messages
+ * @param {string} spec.defaultUrl the pinned default endpoint
+ * @param {string[]} spec.hosts    hostnames allowed to receive the credential
+ * @param {string} [spec.url]      caller/env supplied override
+ * @param {boolean} [spec.strict]  throw instead of dropping the key
+ */
+export function resolveProviderEndpoint({ provider, defaultUrl, hosts = [], url, strict = false }) {
+  // An empty/blank override means "not configured", not "call the empty
+  // string". Treat it as absent so callers can pass `opts.baseUrl` straight
+  // through without pre-checking it.
+  const override = String(url ?? "").trim();
+  const raw = (override || String(defaultUrl)).replace(/\/$/, "");
+  if (raw === String(defaultUrl).replace(/\/$/, "")) {
+    return { baseUrl: raw, trusted: true, host: hostOf(defaultUrl) };
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`${provider}: baseUrl must be an absolute http(s) URL`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`${provider}: baseUrl must be an absolute http(s) URL`);
+  }
+  const host = parsed.host;
+  if (!host) {
+    throw new Error(`${provider}: baseUrl must be an absolute http(s) URL`);
+  }
+
+  const allowed = new Set([hostOf(defaultUrl), ...hosts]);
+  if (allowed.has(host)) {
+    // A protocol downgrade to plaintext would put the pinned credential on the
+    // wire in cleartext, so an allowlisted HOST over http:// is still not a
+    // trusted destination for a secret. Loopback is exempt: there is no wire.
+    const loopback = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i.test(host);
+    if (parsed.protocol === "http:" && !loopback) {
+      return { baseUrl: raw, trusted: false, host, reason: "plaintext http downgrade" };
+    }
+    return { baseUrl: raw, trusted: true, host };
+  }
+
+  if (String(process.env[OVERRIDE_ENV] || "") === "1") {
+    // Explicit operator opt-in. Still untrusted: the caller asked for a
+    // different host, so the key does not travel there.
+    return { baseUrl: raw, trusted: false, host };
+  }
+
+  if (strict) {
+    throw new Error(
+      `${provider}: refusing to call non-allowlisted host ${host} (set ${OVERRIDE_ENV}=1 to permit it)`
+    );
+  }
+  return { baseUrl: raw, trusted: false, host };
+}
+
+function hostOf(url) {
+  const u = new URL(String(url));
+  if (u.protocol !== "http:" && u.protocol !== "https:") throw new Error("unsupported protocol");
+  return u.host;
+}
+
+/**
+ * Attach credential headers only to a trusted endpoint.
+ *
+ * @param {object} baseHeaders  headers safe for any host (accept, user-agent)
+ * @param {object} credentials  header name -> secret value
+ * @param {boolean} trusted     from resolveProviderEndpoint
+ */
+export function credentialedHeaders(baseHeaders, credentials, trusted) {
+  const h = { ...baseHeaders };
+  if (!trusted) return h;
+  for (const [name, value] of Object.entries(credentials || {})) {
+    if (value) h[name] = value;
+  }
+  return h;
+}

package/src/data/providers/aerodrome.mjs

@@ -0,0 +1,244 @@
+// Aerodrome Slipstream (Base) — QuoterV2 + SwapRouter exact-input.
+// Official deployments: aerodrome-finance/slipstream README (Base).
+// Quoter/router use tickSpacing (not Uniswap fee tiers). No API key.
+// Read/quote/prepare only — never signs or broadcasts.
+
+import { Interface, getAddress, isAddress } from "ethers";
+import { rpcCall } from "./evm-rpc.mjs";
+import { attachAutoSlippage, bindAutoSlippageGuardToCall } from "../../auto-slippage.mjs";
+
+/** @type {Record<number, { name: string, quoter: string, router: string, factory: string, weth: string, usdc: string }>} */
+export const AERODROME_CHAINS = {
+  8453: {
+    name: "base",
+    // Verified 2026-07-24: slipstream README initial deployment + eth_getCode + live quote.
+    quoter: "0x254cF9E1E6e233aa1AC962CB9B05b2cfeAaE15b0",
+    router: "0xBE6D8f0d05cC4be24d5167a3eF062215bE6D18a5",
+    factory: "0x5e7BB104d84c7CB9B682AaC2F3d509f5F406809A",
+    weth: "0x4200000000000000000000000000000000000006",
+    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  },
+};
+
+// Common Slipstream tick spacings on Base.
+export const AERODROME_TICK_SPACINGS = [1, 50, 100, 200, 2000];
+
+const QUOTER_IFACE = new Interface([
+  "function quoteExactInputSingle((address tokenIn, address tokenOut, uint256 amountIn, int24 tickSpacing, uint160 sqrtPriceLimitX96) params) returns (uint256 amountOut, uint160 sqrtPriceX96After, uint32 initializedTicksCrossed, uint256 gasEstimate)",
+]);
+
+const ROUTER_IFACE = new Interface([
+  "function exactInputSingle((address tokenIn, address tokenOut, int24 tickSpacing, address recipient, uint256 deadline, uint256 amountIn, uint256 amountOutMinimum, uint160 sqrtPriceLimitX96) params) payable returns (uint256 amountOut)",
+]);
+
+const NATIVE = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+const ZERO = "0x0000000000000000000000000000000000000000";
+
+function chainMeta(chainId) {
+  const id = Number(chainId);
+  const m = AERODROME_CHAINS[id];
+  if (!m) {
+    throw new Error(
+      `aerodrome: unsupported chainId ${chainId} (supported: ${Object.keys(AERODROME_CHAINS).join(", ")})`
+    );
+  }
+  return { chainId: id, ...m };
+}
+
+function normalizeToken(addr, chainId) {
+  const meta = AERODROME_CHAINS[Number(chainId)];
+  if (!addr || addr === NATIVE || addr === ZERO || /^eth$/i.test(String(addr))) {
+    return getAddress(meta.weth);
+  }
+  const s = String(addr);
+  if (/^weth$/i.test(s)) return getAddress(meta.weth);
+  if (/^usdc$/i.test(s)) return getAddress(meta.usdc);
+  if (!isAddress(s)) throw new Error(`invalid token address: ${addr}`);
+  return getAddress(s);
+}
+
+/**
+ * Quote exact-input single hop via Aerodrome Slipstream QuoterV2.
+ * @param {object} q
+ * @param {number} [q.chainId=8453]
+ * @param {string} [q.tokenIn] default WETH
+ * @param {string} [q.tokenOut] default USDC
+ * @param {string|number|bigint} q.amountIn raw base units
+ * @param {number} [q.tickSpacing] if omitted, tries common spacings for best-out
+ */
+export async function aerodromeQuoteExactIn(q = {}, opts = {}) {
+  const { chainId, quoter, router } = chainMeta(q.chainId ?? 8453);
+  const tokenIn = normalizeToken(q.tokenIn || "WETH", chainId);
+  const tokenOut = normalizeToken(q.tokenOut || AERODROME_CHAINS[chainId].usdc, chainId);
+  const amountIn = BigInt(q.amountIn ?? 0);
+  if (amountIn <= 0n) throw new Error("amountIn required (raw base units)");
+
+  const spacings =
+    q.tickSpacing != null
+      ? [Number(q.tickSpacing)]
+      : q.tryTickSpacings === false
+        ? [100]
+        : [...AERODROME_TICK_SPACINGS];
+
+  const results = [];
+  let best = null;
+
+  for (const tickSpacing of spacings) {
+    const data = QUOTER_IFACE.encodeFunctionData("quoteExactInputSingle", [
+      {
+        tokenIn,
+        tokenOut,
+        amountIn,
+        tickSpacing,
+        sqrtPriceLimitX96: 0n,
+      },
+    ]);
+    try {
+      const raw = await rpcCall(chainId, "eth_call", [{ to: quoter, data }, "latest"], opts);
+      if (!raw || raw === "0x") {
+        results.push({ tickSpacing, ok: false, error: "empty result" });
+        continue;
+      }
+      const decoded = QUOTER_IFACE.decodeFunctionResult("quoteExactInputSingle", raw);
+      const row = {
+        tickSpacing,
+        ok: true,
+        amountOut: decoded[0].toString(),
+        sqrtPriceX96After: decoded[1].toString(),
+        initializedTicksCrossed: Number(decoded[2]),
+        gasEstimate: decoded[3].toString(),
+      };
+      results.push(row);
+      if (!best || BigInt(row.amountOut) > BigInt(best.amountOut)) best = row;
+    } catch (e) {
+      results.push({ tickSpacing, ok: false, error: String(e.message || e).slice(0, 160) });
+    }
+  }
+
+  if (!best) {
+    const err = results.map((r) => `${r.tickSpacing}:${r.error || "fail"}`).join("; ");
+    throw new Error(`aerodrome quote failed chain=${chainId}: ${err}`);
+  }
+
+  return attachAutoSlippage(
+    {
+      venue: "aerodrome",
+      chainId,
+      chain: AERODROME_CHAINS[chainId].name,
+      quoter,
+      router,
+      tokenIn,
+      tokenOut,
+      amountIn: amountIn.toString(),
+      tickSpacing: best.tickSpacing,
+      amountOut: best.amountOut,
+      gasEstimate: best.gasEstimate,
+      sqrtPriceX96After: best.sqrtPriceX96After,
+      initializedTicksCrossed: best.initializedTicksCrossed,
+      triedTickSpacings: results,
+      best: true,
+    },
+    {
+      chainId,
+      venue: router,
+      amountOut: best.amountOut,
+      liquidityUsd: q.liquidityUsd,
+      priceChange5m: q.priceChange5m,
+      requestedCapBps: q.maxSlippageBps ?? q.slippageBps,
+    }
+  );
+}
+
+export async function aerodromePrepareExactIn(q = {}, opts = {}) {
+  const chainId = Number(q.chainId ?? 8453);
+  const meta = chainMeta(chainId);
+  const recipient = getAddress(q.recipient || q.from || q.userAddress);
+  const inputRaw = String(q.tokenIn || "WETH");
+  const nativeInput =
+    !q.tokenIn || inputRaw === NATIVE || inputRaw === ZERO || /^eth$/i.test(inputRaw);
+  const quote = await aerodromeQuoteExactIn(q, opts);
+  const deadlineWindow = Math.min(600, Math.max(30, Number(q.deadlineSeconds ?? 300)));
+  const nowSeconds = Number(opts.nowSeconds ?? Math.floor(Date.now() / 1000));
+  const deadline = nowSeconds + deadlineWindow;
+  const data = ROUTER_IFACE.encodeFunctionData("exactInputSingle", [
+    {
+      tokenIn: quote.tokenIn,
+      tokenOut: quote.tokenOut,
+      tickSpacing: quote.tickSpacing,
+      recipient,
+      deadline,
+      amountIn: BigInt(quote.amountIn),
+      amountOutMinimum: BigInt(quote.amountOutMinimum),
+      sqrtPriceLimitX96: 0n,
+    },
+  ]);
+  return {
+    provider: "aerodrome",
+    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,
+    deadline,
+    quote,
+    autoSlippage: quote.autoSlippage,
+    requiresApproval: nativeInput
+      ? null
+      : {
+          token: quote.tokenIn,
+          spender: meta.router,
+          amount: quote.amountIn,
+        },
+    transaction: {
+      chainId,
+      from: recipient,
+      to: meta.router,
+      data,
+      value: nativeInput ? quote.amountIn : "0",
+      slippageGuard: bindAutoSlippageGuardToCall(quote.autoSlippage, { chainId, venue: meta.router, data }),
+    },
+  };
+}
+
+export async function aerodromeHealth(opts = {}) {
+  const chainId = Number(opts.chainId ?? 8453);
+  try {
+    const q = await aerodromeQuoteExactIn(
+      {
+        chainId,
+        tokenIn: "WETH",
+        tokenOut: "USDC",
+        amountIn: "1000000000000000",
+      },
+      opts
+    );
+    const usdc = Number(q.amountOut) / 1e6;
+    return {
+      ok: true,
+      chainId,
+      tickSpacing: q.tickSpacing,
+      amountOutUsdc: usdc,
+      midPxHint: usdc / 0.001,
+      router: AERODROME_CHAINS[chainId]?.router,
+      quoter: AERODROME_CHAINS[chainId]?.quoter,
+    };
+  } catch (e) {
+    return { ok: false, chainId, error: String(e.message || e).slice(0, 200) };
+  }
+}
+
+export async function aerodromeChains() {
+  return Object.entries(AERODROME_CHAINS).map(([id, m]) => ({
+    chainId: Number(id),
+    name: m.name,
+    quoter: m.quoter,
+    router: m.router,
+    factory: m.factory,
+    weth: m.weth,
+    usdc: m.usdc,
+  }));
+}