@oracle-agent/oracle 0.13.1 → 0.14.0

package/src/data/http.mjs

@@ -0,0 +1,253 @@
+// 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 REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 3;
+
+function credentialHeaderName(name) {
+  const h = String(name || "").toLowerCase();
+  return IDENTITY_HEADERS.includes(h) || /(^|-)(api[-_]?key|key|token|secret|auth|authorization|session|cookie|signature|access)(-|$)/.test(h);
+}
+
+function stripCredentialHeaders(headers) {
+  const safe = {};
+  for (const [name, value] of Object.entries(headers || {})) {
+    if (!credentialHeaderName(name)) safe[name] = value;
+  }
+  return safe;
+}
+
+function redirectedUrl(location, currentUrl) {
+  if (!location) throw new Error(`HTTP redirect from ${currentUrl} missing Location`);
+  const next = new URL(String(location), String(currentUrl));
+  if (next.protocol !== "http:" && next.protocol !== "https:") {
+    throw new Error(`HTTP redirect from ${currentUrl} used unsupported protocol ${next.protocol}`);
+  }
+  return next.toString();
+}
+
+function sameOrigin(a, b) {
+  return new URL(String(a)).origin === new URL(String(b)).origin;
+}
+
+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 {
+    let currentUrl = String(url);
+    let currentHeaders = { ...(headers || {}) };
+    for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects += 1) {
+      const res = await fetchImpl(currentUrl, {
+        method,
+        headers: currentHeaders,
+        body,
+        signal: ac.signal,
+        redirect: "manual",
+      });
+      const text = await res.text();
+      let json = null;
+      if (text) {
+        try {
+          json = JSON.parse(text);
+        } catch {
+          json = null;
+        }
+      }
+      if (REDIRECT_STATUS.has(res.status)) {
+        if (method !== "GET" && method !== "HEAD") {
+          const err = new Error(`HTTP ${res.status} ${method} ${currentUrl} redirected non-idempotent request`);
+          err.status = res.status;
+          err.body = json ?? text.slice(0, 300);
+          throw err;
+        }
+        if (redirects === MAX_REDIRECTS) throw new Error(`HTTP redirect loop for ${url}`);
+        const nextUrl = redirectedUrl(res.headers?.get?.("location"), currentUrl);
+        if (!sameOrigin(nextUrl, currentUrl)) currentHeaders = stripCredentialHeaders(currentHeaders);
+        currentUrl = nextUrl;
+        continue;
+      }
+      if (!res.ok) {
+        const err = new Error(`HTTP ${res.status} ${method} ${currentUrl}`);
+        err.status = res.status;
+        err.retryAfter = res.headers?.get?.("retry-after") ?? null;
+        err.body = json ?? text.slice(0, 300);
+        throw err;
+      }
+      return json ?? text;
+    }
+    throw new Error(`HTTP redirect loop for ${url}`);
+  } 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/names.mjs

@@ -0,0 +1,188 @@
+// Cross-chain name resolution. Read-only by construction: every lookup goes
+// through rpcCall(), whose allowlist refuses anything that is not a read
+// method, so this module cannot sign or broadcast even by mistake.
+//
+// No API keys. HL Names publishes a REST API that requires one, but the
+// contract answers primaryName(address) for free, and the MetaMask snap is
+// only a proxy for that same paid endpoint. Reading the chain is cheaper and
+// has one less party to trust. Ported from the resolution chain already proven
+// in DEMI's polymarket bot (src/hooks/useResolveName.js).
+//
+// Verified live 2026-08-05 against 0x4d47b6757afd42c3dbd9691b71b43d74afa4b6b2:
+//   .hl    -> demi.hl        .hype -> demi.hype
+//   .eth   -> demigodzx.eth  .base -> (no record, call OK)
+
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { rpcCall } from "./providers/evm-rpc.mjs";
+
+const HYPEREVM = 999;
+const MAINNET = 1;
+const BASE = 8453;
+
+const HLNAMES = "0x1d9d87eBc14e71490bB87f1C39F65BDB979f3cb7";
+const DOTHYPE_RESOLVER = "0x4d5e4ed4D5e4A160Fa136853597cDc2eBBe66494";
+const ENS_REGISTRY = "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e";
+const BASE_L2_RESOLVER = "0xC6d566A56A1aFf6508b41f6c90ff131615583BCD";
+
+// Base reverse records live under a chain-specific reverse namespace, not
+// .addr.reverse: 0x80002105 is the ENSIP-11 coinType for Base.
+const BASE_REVERSE_SUFFIX = ".80002105.reverse";
+
+export const ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+
+const enc = new TextEncoder();
+const hex = (bytes) => "0x" + Buffer.from(bytes).toString("hex");
+const selector = (sig) => hex(keccak_256(enc.encode(sig))).slice(0, 10);
+const padAddress = (addr) => addr.toLowerCase().replace(/^0x/, "").padStart(64, "0");
+
+export function namehash(name) {
+  let node = new Uint8Array(32);
+  if (name) {
+    for (const label of String(name).split(".").reverse()) {
+      const labelHash = keccak_256(enc.encode(label));
+      const joined = new Uint8Array(64);
+      joined.set(node, 0);
+      joined.set(labelHash, 32);
+      node = keccak_256(joined);
+    }
+  }
+  return hex(node);
+}
+
+// ABI-decode a single dynamic string. Returns "" for empty/zero results so a
+// name that simply is not registered reads the same as a contract that
+// returned nothing, which is what every caller wants.
+export function decodeAbiString(raw) {
+  if (!raw || raw === "0x" || /^0x0*$/.test(raw)) return "";
+  try {
+    const body = raw.slice(2);
+    const offset = parseInt(body.slice(0, 64), 16) * 2;
+    const length = parseInt(body.slice(offset, offset + 64), 16);
+    if (!Number.isFinite(length) || length <= 0) return "";
+    const chars = body.slice(offset + 64, offset + 64 + length * 2);
+    return Buffer.from(chars, "hex").toString("utf8");
+  } catch {
+    return "";
+  }
+}
+
+export function encodeAbiString(value) {
+  const bytes = enc.encode(String(value));
+  const len = bytes.length.toString(16).padStart(64, "0");
+  const padded = Buffer.from(bytes).toString("hex").padEnd(Math.ceil(bytes.length / 32) * 64, "0");
+  return "0000000000000000000000000000000000000000000000000000000000000020" + len + padded;
+}
+
+async function ethCall(chainId, to, data) {
+  try {
+    return await rpcCall(chainId, "eth_call", [{ to, data }, "latest"]);
+  } catch {
+    // A dead RPC must not take down the whole chain of lookups: a missing
+    // .hl answer should still let .eth resolve.
+    return null;
+  }
+}
+
+async function reverseHl(address) {
+  const raw = await ethCall(HYPEREVM, HLNAMES, selector("primaryName(address)") + padAddress(address));
+  const name = decodeAbiString(raw);
+  if (!name) return null;
+  return name.endsWith(".hl") ? name : `${name}.hl`;
+}
+
+async function reverseHype(address) {
+  const raw = await ethCall(HYPEREVM, DOTHYPE_RESOLVER, selector("getName(address)") + padAddress(address));
+  const name = decodeAbiString(raw);
+  if (!name) return null;
+  return name.endsWith(".hype") ? name : `${name}.hype`;
+}
+
+async function reverseVia(chainId, node, resolverAddress) {
+  const raw = await ethCall(chainId, resolverAddress, selector("name(bytes32)") + node.slice(2));
+  return decodeAbiString(raw) || null;
+}
+
+async function reverseEns(address) {
+  const node = namehash(`${address.slice(2).toLowerCase()}.addr.reverse`);
+  const resolverRaw = await ethCall(MAINNET, ENS_REGISTRY, selector("resolver(bytes32)") + node.slice(2));
+  if (!resolverRaw) return null;
+  const resolver = "0x" + resolverRaw.slice(-40);
+  if (/^0x0+$/.test(resolver)) return null;
+  return reverseVia(MAINNET, node, resolver);
+}
+
+async function reverseBasename(address) {
+  const node = namehash(address.slice(2).toLowerCase() + BASE_REVERSE_SUFFIX);
+  return reverseVia(BASE, node, BASE_L2_RESOLVER);
+}
+
+// Priority mirrors the polymarket bot: Hyperliquid-native names first because
+// this is DEMI's primary venue, then ENS, then Base.
+const REVERSE_ORDER = [
+  { source: "hl", fn: reverseHl },
+  { source: "hype", fn: reverseHype },
+  { source: "ens", fn: reverseEns },
+  { source: "basename", fn: reverseBasename },
+];
+
+/** address -> { name, source } | null */
+export async function lookupName(address) {
+  if (!ADDRESS_RE.test(String(address || "").trim())) return null;
+  const addr = String(address).trim();
+  for (const { source, fn } of REVERSE_ORDER) {
+    const name = await fn(addr);
+    if (name) return { name, source, address: addr };
+  }
+  return null;
+}
+
+// HLNames is an ERC721 whose tokenId IS the namehash, so forward resolution
+// is ownerOf(namehash(name)) rather than a resolve()-style helper. Probed the
+// whole plausible surface (resolve/resolveName/getAddress/addr/lookup, string
+// and bytes32 forms) and every one returned empty; ownerOf(namehash("demi.hl"))
+// returned DEMI's address, while ownerOf(labelhash("demi")) returned zero,
+// which pins both the function AND the tokenId derivation.
+async function forwardHl(name) {
+  const node = namehash(name);
+  const raw = await ethCall(HYPEREVM, HLNAMES, selector("ownerOf(uint256)") + node.slice(2));
+  if (!raw || raw.length < 66) return null;
+  const addr = "0x" + raw.slice(-40);
+  return /^0x0+$/.test(addr) ? null : addr;
+}
+
+async function forwardEnsLike(chainId, name, registry) {
+  const node = namehash(name);
+  const resolverRaw = await ethCall(chainId, registry, selector("resolver(bytes32)") + node.slice(2));
+  if (!resolverRaw) return null;
+  const resolver = "0x" + resolverRaw.slice(-40);
+  if (/^0x0+$/.test(resolver)) return null;
+  const addrRaw = await ethCall(chainId, resolver, selector("addr(bytes32)") + node.slice(2));
+  if (!addrRaw) return null;
+  const addr = "0x" + addrRaw.slice(-40);
+  return /^0x0+$/.test(addr) ? null : addr;
+}
+
+/** name -> { address, source } | null */
+export async function resolveName(name) {
+  const clean = String(name || "").trim().toLowerCase();
+  if (!clean || !clean.includes(".")) return null;
+
+  if (clean.endsWith(".hl")) {
+    const address = await forwardHl(clean);
+    return address ? { address, source: "hl", name: clean } : null;
+  }
+  if (clean.endsWith(".eth")) {
+    const address = await forwardEnsLike(MAINNET, clean, ENS_REGISTRY);
+    return address ? { address, source: clean.endsWith(".base.eth") ? "basename" : "ens", name: clean } : null;
+  }
+  return null;
+}
+
+/** Accepts either a raw address or a name and always yields an address. */
+export async function toAddress(input) {
+  const value = String(input || "").trim();
+  if (ADDRESS_RE.test(value)) return { address: value, source: "address", name: null };
+  return resolveName(value);
+}
+
+export const NAME_SOURCES = REVERSE_ORDER.map((r) => r.source);

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/aave-v3.mjs

@@ -0,0 +1,139 @@
+// Aave V3 public GraphQL API (api.v3.aave.com/graphql) — keyless reads.
+//
+// Read-only: markets, per-market reserves, supported chains. No key, no
+// signing, no broadcast. The Aave app API also exposes tx-building queries
+// (supply/borrow/withdraw); this module deliberately never touches them.
+//
+// Schema notes verified against the live endpoint (2026-08-06):
+//   - `markets(request: MarketsRequest!)` where MarketsRequest = { chainIds, user }
+//   - `market(request: MarketRequest!)`   where MarketRequest  = { address, chainId, user }
+//   - `chains(filter: ChainsFilter!)`     ChainsFilter = MAINNET_ONLY | TESTNET_ONLY | ALL
+//   - totalMarketSize / totalAvailableLiquidity are BigDecimal SCALARS (no subfields)
+//   - PercentValue  = { raw decimals value formatted }
+//   - DecimalValue  = { raw decimals value }
+//   - TokenAmount   = { amount: DecimalValue, usd: BigDecimal, usdPerToken: BigDecimal }
+// Selecting subfields on a BigDecimal (or `amount` on a DecimalValue) is a
+// hard GraphQL error, so the queries below are pinned to the real shapes.
+
+import { httpJson } from "../http.mjs";
+
+export const AAVE_V3_API = "https://api.v3.aave.com/graphql";
+
+/** Aave V3 mainnet deployments, verified live via chains(filter: MAINNET_ONLY). */
+export const AAVE_V3_CHAIN_IDS = Object.freeze([
+  1, 10, 56, 100, 137, 146, 232, 324, 1088, 1868, 5000, 42161, 42220, 43114, 57073, 59144, 534352,
+]);
+
+const endpoint = (o = {}) => o.baseUrl || process.env.AAVE_V3_API_URL || AAVE_V3_API;
+
+async function gql(query, variables, opts = {}) {
+  // GraphQL is a POST, so http.mjs will not dedupe or replay it — that is the
+  // correct behaviour for a non-idempotent method even though this one is a read.
+  const res = await httpJson(endpoint(opts), {
+    method: "POST",
+    body: { query, variables },
+    fetchImpl: opts.fetchImpl,
+    timeoutMs: opts.timeoutMs ?? 20_000,
+  });
+  if (res?.errors?.length) {
+    throw new Error(`aave-v3: ${res.errors.map((e) => e?.message || String(e)).join("; ")}`);
+  }
+  return res;
+}
+
+const MARKETS_QUERY = `query Markets($request: MarketsRequest!) {
+  markets(request: $request) {
+    name
+    address
+    chain { chainId name }
+    totalMarketSize
+    totalAvailableLiquidity
+  }
+}`;
+
+const MARKET_RESERVES_QUERY = `query Market($request: MarketRequest!) {
+  market(request: $request) {
+    name
+    address
+    chain { chainId name }
+    totalMarketSize
+    totalAvailableLiquidity
+    reserves {
+      underlyingToken { symbol address decimals }
+      isFrozen
+      isPaused
+      flashLoanEnabled
+      size { amount { value } usd }
+      supplyInfo {
+        apy { value formatted }
+        total { value }
+        supplyCap { amount { value } usd }
+        supplyCapReached
+        canBeCollateral
+        maxLTV { value }
+        liquidationThreshold { value }
+      }
+      borrowInfo {
+        apy { value formatted }
+        total { amount { value } usd }
+        availableLiquidity { amount { value } usd }
+        utilizationRate { value }
+        borrowCap { amount { value } usd }
+        borrowCapReached
+        reserveFactor { value }
+      }
+    }
+  }
+}`;
+
+const CHAINS_QUERY = `query Chains($filter: ChainsFilter!) {
+  chains(filter: $filter) { chainId name isTestnet explorerUrl }
+}`;
+
+function chainIdList(args = {}) {
+  const raw = args.chainIds ?? (args.chainId != null ? [args.chainId] : null);
+  const ids = (Array.isArray(raw) ? raw : [raw ?? 1])
+    .map(Number)
+    .filter((n) => Number.isInteger(n) && n > 0);
+  if (!ids.length) throw new Error("aave-v3: chainIds must contain at least one chain id");
+  return [...new Set(ids)];
+}
+
+/** List Aave V3 markets across one or more chains. */
+export async function aaveMarkets(args = {}, opts = {}) {
+  const request = { chainIds: chainIdList(args) };
+  if (args.user) request.user = String(args.user);
+  const res = await gql(MARKETS_QUERY, { request }, opts);
+  return { markets: res?.data?.markets ?? [] };
+}
+
+/** Full reserve detail for ONE market (pool address + chain). */
+export async function aaveMarketReserves(args = {}, opts = {}) {
+  const address = String(args.address || args.market || args.marketAddress || "").trim();
+  if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+    throw new Error("aave-v3: marketReserves requires an EVM market (pool) address");
+  }
+  const chainId = Number(args.chainId ?? 1);
+  if (!Number.isInteger(chainId) || chainId <= 0) throw new Error("aave-v3: chainId must be a positive integer");
+  const request = { address, chainId };
+  if (args.user) request.user = String(args.user);
+  const res = await gql(MARKET_RESERVES_QUERY, { request }, opts);
+  const market = res?.data?.market ?? null;
+  if (!market) throw new Error(`aave-v3: no market at ${address} on chain ${chainId}`);
+  return { market };
+}
+
+/** Chains Aave V3 is deployed on. filter: MAINNET_ONLY (default) | TESTNET_ONLY | ALL */
+export async function aaveChains(args = {}, opts = {}) {
+  const allowed = new Set(["MAINNET_ONLY", "TESTNET_ONLY", "ALL"]);
+  const filter = String(args.filter || "MAINNET_ONLY").toUpperCase();
+  if (!allowed.has(filter)) throw new Error(`aave-v3: filter must be one of ${[...allowed].join(", ")}`);
+  const res = await gql(CHAINS_QUERY, { filter }, opts);
+  return { chains: res?.data?.chains ?? [] };
+}
+
+export async function aaveHealth(opts = {}) {
+  // The schema exposes a first-class `health: Boolean` — cheapest possible probe.
+  const res = await gql("query { health }", {}, opts);
+  return { ok: res?.data?.health === true, provider: "aave-v3" };
+}