@oracle-agent/oracle 0.1.0

package/src/scanner/chains.config.mjs

@@ -0,0 +1,381 @@
+// Built-in chain configs.
+//
+// This file is the "adding a chain is data" claim made concrete. Each entry is pure
+// configuration -- no chain-specific code -- and `defineEvmScanner` turns it into a
+// working scanner.
+//
+// To add a chain: append an entry, set the RPC env var, done. If you also want
+// routing on it, add verified venues (see CONTRIBUTING for the verification rule:
+// bytecode check plus the protocol's own source, recorded per chain).
+//
+// Venues are intentionally EMPTY here. An address is only useful with provenance,
+// and provenance has to be established per chain by whoever adds it. An empty venue
+// list means the chain is read/research-capable and fail-closed for routing, which
+// is the correct default rather than a gap.
+
+import { defineEvmScanner } from "./evm-scanner.mjs";
+import { registerScanner } from "./contract.mjs";
+
+/**
+ * `dexscreenerSlug` is DexScreener's own chain identifier, which is not the chain id
+ * and not always the obvious name. Omit it when unknown -- pool discovery then
+ * reports UNAVAILABLE instead of silently returning another chain's pools.
+ */
+export const CHAIN_CONFIGS = Object.freeze([
+  {
+    key: "ethereum",
+    chainId: 1,
+    name: "Ethereum",
+    rpcEnv: ["ETH_RPC_URL", "ETHEREUM_RPC_URL", "MAINNET_RPC_URL"],
+    nativeCurrency: { symbol: "ETH", decimals: 18 },
+    explorer: "https://etherscan.io",
+    dexscreenerSlug: "ethereum",
+    venueKind: "uniswap-v3",
+    wrappedNative: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+    venues: [
+      {
+        kind: "quoter",
+        address: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+        label: "Uniswap V3 QuoterV2",
+        verified: {
+          method:
+            "functional probe, not a codesize check: quoteExactInputSingle returned a " +
+            "live sane price (WETH->USDC fee 500 quoted 1908.71 USDC). A contract that correctly prices a known pair " +
+            "IS a working V3 quoter",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 1,
+        },
+      },
+      {
+        kind: "router",
+        address: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+        label: "Uniswap V3 SwapRouter02",
+        verified: {
+          method:
+            "eth_getCode returned real bytecode on this chain and the paired quoter " +
+            "at the same deployment passed a live functional quote",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 1,
+        },
+      },
+    ],
+  },
+  {
+    key: "optimism",
+    chainId: 10,
+    name: "OP Mainnet",
+    rpcEnv: ["OPTIMISM_RPC_URL", "OP_RPC_URL"],
+    nativeCurrency: { symbol: "ETH", decimals: 18 },
+    explorer: "https://optimistic.etherscan.io",
+    dexscreenerSlug: "optimism",
+    venueKind: "uniswap-v3",
+    wrappedNative: "0x4200000000000000000000000000000000000006",
+    venues: [
+      {
+        kind: "quoter",
+        address: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+        label: "Uniswap V3 QuoterV2",
+        verified: {
+          method:
+            "functional probe, not a codesize check: quoteExactInputSingle returned a " +
+            "live sane price (WETH->USDC fee 500 quoted 1905.23 USDC). A contract that correctly prices a known pair " +
+            "IS a working V3 quoter",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 10,
+        },
+      },
+      {
+        kind: "router",
+        address: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+        label: "Uniswap V3 SwapRouter02",
+        verified: {
+          method:
+            "eth_getCode returned real bytecode on this chain and the paired quoter " +
+            "at the same deployment passed a live functional quote",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 10,
+        },
+      },
+    ],
+  },
+  {
+    key: "bsc",
+    chainId: 56,
+    name: "BNB Smart Chain",
+    rpcEnv: ["BSC_RPC_URL", "BNB_RPC_URL"],
+    nativeCurrency: { symbol: "BNB", decimals: 18 },
+    explorer: "https://bscscan.com",
+    dexscreenerSlug: "bsc",
+    venueKind: "uniswap-v3",
+    wrappedNative: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
+    venues: [
+      {
+        kind: "quoter",
+        address: "0x78D78E420Da98ad378D7799bE8f4AF69033EB077",
+        label: "Uniswap V3 QuoterV2",
+        verified: {
+          method:
+            "functional probe, not a codesize check: quoteExactInputSingle returned a " +
+            "live sane price (WBNB->USDC fee 500 quoted 413.86 USDC). A contract that correctly prices a known pair " +
+            "IS a working V3 quoter",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 56,
+        },
+      },
+      {
+        kind: "router",
+        address: "0xB971eF87ede563556b2ED4b1C0b0019111Dd85d2",
+        label: "Uniswap V3 SwapRouter02",
+        verified: {
+          method:
+            "eth_getCode returned real bytecode on this chain and the paired quoter " +
+            "at the same deployment passed a live functional quote",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 56,
+        },
+      },
+    ],
+  },
+  {
+    key: "polygon",
+    chainId: 137,
+    name: "Polygon",
+    rpcEnv: ["POLYGON_RPC_URL", "POLYGON_RPC"],
+    nativeCurrency: { symbol: "POL", decimals: 18 },
+    explorer: "https://polygonscan.com",
+    dexscreenerSlug: "polygon",
+    venueKind: "uniswap-v3",
+    wrappedNative: "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270",
+    venues: [
+      {
+        kind: "quoter",
+        address: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+        label: "Uniswap V3 QuoterV2",
+        verified: {
+          method:
+            "functional probe, not a codesize check: quoteExactInputSingle returned a " +
+            "live sane price (WMATIC->USDC fee 500 quoted 0.0720 USDC). A contract that correctly prices a known pair " +
+            "IS a working V3 quoter",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 137,
+        },
+      },
+      {
+        kind: "router",
+        address: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+        label: "Uniswap V3 SwapRouter02",
+        verified: {
+          method:
+            "eth_getCode returned real bytecode on this chain and the paired quoter " +
+            "at the same deployment passed a live functional quote",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 137,
+        },
+      },
+    ],
+  },
+  {
+    key: "stable",
+    chainId: 988,
+    name: "Stable Mainnet",
+    rpcEnv: ["STABLE_RPC_URL", "STABLE_RPC"],
+    // The stablecoin IS the gas token here, 18 decimals native. The same balance
+    // also appears as a 6-decimal ERC-20 mirror -- it is ONE balance, never summed.
+    nativeCurrency: { symbol: "USDT0", decimals: 18 },
+    venues: [],
+  },
+  {
+    key: "hyperevm",
+    chainId: 999,
+    name: "HyperEVM",
+    rpcEnv: ["HYPEREVM_RPC_URL", "HYPER_EVM_RPC"],
+    nativeCurrency: { symbol: "HYPE", decimals: 18 },
+    dexscreenerSlug: "hyperevm",
+    venues: [],
+  },
+  {
+    key: "abstract",
+    chainId: 2741,
+    name: "Abstract",
+    rpcEnv: ["ABSTRACT_RPC_URL", "ABS_RPC_URL"],
+    nativeCurrency: { symbol: "ETH", decimals: 18 },
+    venues: [],
+  },
+  {
+    key: "robinhood",
+    chainId: 4663,
+    name: "Robinhood Chain",
+    rpcEnv: ["RH_CHAIN_RPC", "ROBINHOOD_RPC_URL"],
+    nativeCurrency: { symbol: "ETH", decimals: 18 },
+    venues: [],
+  },
+  {
+    key: "base",
+    chainId: 8453,
+    name: "Base",
+    rpcEnv: ["BASE_RPC_URL"],
+    nativeCurrency: { symbol: "ETH", decimals: 18 },
+    explorer: "https://basescan.org",
+    dexscreenerSlug: "base",
+    // Base runs the V3 adapter: its V3 pools carry far deeper liquidity than the V2
+    // fork, and the chain-specific quoter is verified below. Worth noting how the
+    // address was found -- the CANONICAL mainnet quoter address also returns bytecode
+    // on Base (2109 bytes), so a codesize check would have waved through the wrong
+    // contract. Only the functional probe distinguished them.
+    venueKind: "uniswap-v3",
+    wrappedNative: "0x4200000000000000000000000000000000000006",
+    venues: [
+      {
+        kind: "quoter",
+        address: "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a",
+        label: "Uniswap V3 QuoterV2 (Base)",
+        verified: {
+          method:
+            "functional probe: quoteExactInputSingle returned WETH->USDC at fee 500 " +
+            "= 1908.44 USDC, a live sane price. The canonical mainnet quoter address " +
+            "also has bytecode on Base but does NOT price this pair, which is exactly " +
+            "the false positive a codesize-only check accepts",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 8453,
+        },
+      },
+      {
+        kind: "router",
+        address: "0x2626664c2603336E57B271c5C0b26F421741e481",
+        label: "Uniswap V3 SwapRouter02 (Base)",
+        verified: {
+          method:
+            "eth_getCode returned real bytecode and the paired Base quoter passed a " +
+            "live functional quote",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 8453,
+        },
+      },
+      {
+        // Kept as the V2 reference wiring. Not selected while venueKind is v3, but
+        // it documents a verified alternate route and shows both shapes in one place.
+        kind: "router-v2",
+        address: "0x4752ba5DBc23f44D87826276BF6Fd6b1C372aD24",
+        label: "Uniswap V2 Router02 (Base)",
+        verified: {
+          method:
+            "eth_getCode returned 17891 bytes; live getAmountsOut on WETH->USDC " +
+            "round-tripped to 98.75% (2x0.30% fee + impact)",
+          source: "https://docs.uniswap.org/contracts/v2/reference/smart-contracts/v2-deployments",
+          date: "2026-07-30",
+          chainId: 8453,
+        },
+      },
+    ],
+  },
+  {
+    key: "arbitrum",
+    chainId: 42161,
+    name: "Arbitrum One",
+    rpcEnv: ["ARBITRUM_RPC_URL", "ARB_RPC_URL"],
+    nativeCurrency: { symbol: "ETH", decimals: 18 },
+    explorer: "https://arbiscan.io",
+    dexscreenerSlug: "arbitrum",
+    venueKind: "uniswap-v3",
+    wrappedNative: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+    venues: [
+      {
+        kind: "quoter",
+        address: "0x61fFE014bA17989E743c5F6cB21bF9697530B21e",
+        label: "Uniswap V3 QuoterV2",
+        verified: {
+          method:
+            "functional probe, not a codesize check: quoteExactInputSingle returned a " +
+            "live sane price (WETH->USDC fee 500 quoted 1908.72 USDC). A contract that correctly prices a known pair " +
+            "IS a working V3 quoter",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 42161,
+        },
+      },
+      {
+        kind: "router",
+        address: "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45",
+        label: "Uniswap V3 SwapRouter02",
+        verified: {
+          method:
+            "eth_getCode returned real bytecode on this chain and the paired quoter " +
+            "at the same deployment passed a live functional quote",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 42161,
+        },
+      },
+    ],
+  },
+  {
+    key: "avalanche",
+    chainId: 43114,
+    name: "Avalanche C-Chain",
+    rpcEnv: ["AVALANCHE_RPC_URL", "AVAX_RPC_URL"],
+    nativeCurrency: { symbol: "AVAX", decimals: 18 },
+    explorer: "https://snowtrace.io",
+    dexscreenerSlug: "avalanche",
+    venueKind: "uniswap-v3",
+    wrappedNative: "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
+    venues: [
+      {
+        kind: "quoter",
+        address: "0xbe0F5544EC67e9B3b2D979aaA43f18Fd87E6257F",
+        label: "Uniswap V3 QuoterV2",
+        verified: {
+          method:
+            "functional probe, not a codesize check: quoteExactInputSingle returned a " +
+            "live sane price (WAVAX->USDC fee 500 quoted 6.48 USDC). A contract that correctly prices a known pair " +
+            "IS a working V3 quoter",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 43114,
+        },
+      },
+      {
+        kind: "router",
+        address: "0xbb00FF08d01D300023C629E8fFfFcb65A5a578cE",
+        label: "Uniswap V3 SwapRouter02",
+        verified: {
+          method:
+            "eth_getCode returned real bytecode on this chain and the paired quoter " +
+            "at the same deployment passed a live functional quote",
+          source: "scripts/verify-v3-venues.mjs (re-runnable)",
+          date: "2026-07-30",
+          chainId: 43114,
+        },
+      },
+    ],
+  },
+]);
+
+/** Register every built-in chain. Idempotent. */
+export function registerBuiltinScanners() {
+  return CHAIN_CONFIGS.map((c) => registerScanner(defineEvmScanner(c)));
+}
+
+/**
+ * Register a chain Oracle has never seen.
+ *
+ * This is the whole point: no code change, no PR to this file required.
+ *
+ *   registerCustomChain({
+ *     key: "mychain", chainId: 7777, name: "My Chain",
+ *     rpcEnv: ["MYCHAIN_RPC_URL"],
+ *     nativeCurrency: { symbol: "MYC", decimals: 18 },
+ *   });
+ */
+export function registerCustomChain(config) {
+  return registerScanner(defineEvmScanner(config));
+}

package/src/scanner/contract.mjs

@@ -0,0 +1,270 @@
+// Chain scanner contract.
+//
+// The problem this solves: Oracle knows 11 chains today, and every one of them was
+// wired by hand. Adding the 12th shouldn't mean writing another bespoke integration
+// -- it should mean filling in a config and, at most, one adapter function.
+//
+// So a scanner is defined by DATA (what the chain is) plus a small set of CAPABILITY
+// functions (what we can actually do on it). Anything unimplemented is absent, not
+// faked, and `capabilities()` reports the truth. This mirrors the data catalog's
+// honesty rule: coverage is not capability.
+//
+// Nothing here signs. A scanner's terminal output is an UNSIGNED transaction.
+
+/**
+ * The capability surface a scanner may implement. Every one is optional; a chain
+ * with only `blockNumber` and `resolveToken` is a legitimate, useful scanner.
+ *
+ * Ordered roughly by how much you need to know about the chain to provide it.
+ */
+export const SCANNER_CAPABILITIES = Object.freeze([
+  "blockNumber",       // current head
+  "nativeBalance",     // native token balance for an address
+  "tokenBalance",      // ERC-20 balance
+  "resolveToken",      // address or symbol -> { address, symbol, decimals, name }
+  "resolvePools",      // token -> tradeable pools, with liquidity
+  "scanBlocks",        // range scan for events (launches, transfers)
+  "scoreRisk",         // structured risk assessment, honestly labelled
+  "quote",             // price a route
+  "sellSimulation",    // can it be sold? round-trip check
+  "prepareUnsignedTx", // build a transaction for the USER to sign
+]);
+
+/**
+ * Evidence freshness labels. A scanner must say which one applies to each finding,
+ * because "no data" and "data from 40 minutes ago" lead to different decisions and
+ * conflating them is how people size against stale reserves.
+ */
+export const EVIDENCE = Object.freeze({
+  LIVE: "LIVE",               // read this call, from the chain
+  CACHED: "CACHED",           // read recently, within the stated ttl
+  STALE: "STALE",             // older than ttl; usable only with the caveat stated
+  UNKNOWN: "UNKNOWN",         // we tried and could not determine it
+  UNAVAILABLE: "UNAVAILABLE", // this chain/provider cannot answer at all
+});
+
+/**
+ * Risk verdicts. Deliberately coarse: a false sense of precision ("risk 62/100")
+ * invites people to trade a number they don't understand.
+ */
+export const RISK = Object.freeze({
+  PASS: "PASS",       // checks ran and found nothing disqualifying
+  CAUTION: "CAUTION", // something real to know before sizing
+  FAIL: "FAIL",       // disqualifying: do not trade
+  UNKNOWN: "UNKNOWN", // could not assess -- NOT the same as PASS
+});
+
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+
+/**
+ * Validate a chain scanner definition.
+ *
+ * Fails closed on the things that cause real losses: an unverified venue, a
+ * placeholder address, a chain id that doesn't match the RPC, a scanner that claims
+ * a capability it didn't implement.
+ *
+ * @param {object} def
+ * @returns {{ok: boolean, errors: string[], warnings: string[]}}
+ */
+export function validateScanner(def = {}) {
+  const errors = [];
+  const warnings = [];
+
+  if (!def || typeof def !== "object") {
+    return { ok: false, errors: ["definition must be an object"], warnings };
+  }
+
+  if (!Number.isInteger(def.chainId) || def.chainId <= 0) {
+    errors.push("chainId must be a positive integer");
+  }
+  if (typeof def.key !== "string" || !/^[a-z][a-z0-9-]*$/.test(def.key || "")) {
+    errors.push('key must be a lowercase slug (e.g. "base")');
+  }
+  if (typeof def.name !== "string" || !def.name.trim()) {
+    errors.push("name is required");
+  }
+
+  // RPC discovery is env-var driven so a public repo never carries endpoints.
+  if (!Array.isArray(def.rpcEnv) || def.rpcEnv.length === 0) {
+    errors.push("rpcEnv must list at least one environment variable name");
+  } else {
+    for (const v of def.rpcEnv) {
+      if (typeof v !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(v)) {
+        errors.push(`rpcEnv entry "${v}" should be an UPPER_SNAKE env var name`);
+      }
+    }
+  }
+
+  if (def.nativeCurrency) {
+    const nc = def.nativeCurrency;
+    if (typeof nc.symbol !== "string" || !nc.symbol) {
+      errors.push("nativeCurrency.symbol is required when nativeCurrency is set");
+    }
+    if (!Number.isInteger(nc.decimals)) {
+      errors.push("nativeCurrency.decimals must be an integer");
+    }
+  }
+
+  // Venue addresses: every one must be well-formed AND carry provenance. An
+  // allowlisted spoofed router defeats every other control in the system, so
+  // "where did this address come from" is required, not documentation.
+  for (const [i, v] of (def.venues || []).entries()) {
+    const at = `venues[${i}]`;
+    if (!v || typeof v !== "object") {
+      errors.push(`${at} must be an object`);
+      continue;
+    }
+    if (!ADDRESS_RE.test(v.address || "")) {
+      errors.push(`${at}.address is not a valid 20-byte address`);
+    }
+    if (/^0x0{40}$/.test(v.address || "")) {
+      errors.push(`${at}.address is the zero address -- placeholder left in place?`);
+    }
+    if (!v.kind) errors.push(`${at}.kind is required (router|quoter|factory|...)`);
+    if (!v.verified) {
+      errors.push(
+        `${at} must record verification: { verified: { method, source, date } }. ` +
+          "An unverified venue stays blocked.",
+      );
+    } else {
+      if (!v.verified.method) errors.push(`${at}.verified.method is required`);
+      if (!v.verified.source) errors.push(`${at}.verified.source is required`);
+      if (!v.verified.date) warnings.push(`${at}.verified.date missing -- add one so staleness is visible`);
+    }
+  }
+
+  // Capability honesty: declaring a capability you didn't implement is the exact
+  // failure mode the data catalog's tier labels exist to prevent.
+  const impl = def.capabilities || {};
+  for (const name of Object.keys(impl)) {
+    if (!SCANNER_CAPABILITIES.includes(name)) {
+      errors.push(`unknown capability "${name}"`);
+    } else if (typeof impl[name] !== "function") {
+      errors.push(`capability "${name}" must be a function`);
+    }
+  }
+  if (Object.keys(impl).length === 0) {
+    warnings.push("scanner implements no capabilities -- it can only be registered, not used");
+  }
+
+  // prepareUnsignedTx without a quote is a footgun: you would be building a
+  // transaction with no priced expectation to check the result against.
+  if (impl.prepareUnsignedTx && !impl.quote) {
+    warnings.push(
+      "prepareUnsignedTx without quote: no priced expectation to validate the built tx against",
+    );
+  }
+  // A chain where you can buy but cannot verify you can sell.
+  if (impl.prepareUnsignedTx && !impl.sellSimulation) {
+    warnings.push(
+      "prepareUnsignedTx without sellSimulation: cannot prove an asset is exitable before buying",
+    );
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Wrap a validated definition into a usable scanner.
+ *
+ * The wrapper's job is to make unimplemented capabilities fail LOUDLY and
+ * consistently, rather than each call site inventing its own undefined-check.
+ */
+export function createScanner(def) {
+  const { ok, errors, warnings } = validateScanner(def);
+  if (!ok) {
+    throw new Error(`invalid scanner for ${def?.key ?? "<unknown>"}:\n  - ${errors.join("\n  - ")}`);
+  }
+
+  const impl = def.capabilities || {};
+  const supported = SCANNER_CAPABILITIES.filter((c) => typeof impl[c] === "function");
+
+  const scanner = {
+    key: def.key,
+    chainId: def.chainId,
+    name: def.name,
+    rpcEnv: [...def.rpcEnv],
+    nativeCurrency: def.nativeCurrency ? { ...def.nativeCurrency } : null,
+    explorer: def.explorer || null,
+    venues: (def.venues || []).map((v) => ({ ...v })),
+    warnings,
+
+    /** Honest capability report: what this chain can actually do. */
+    capabilities() {
+      return {
+        chainId: def.chainId,
+        key: def.key,
+        supported: [...supported],
+        unsupported: SCANNER_CAPABILITIES.filter((c) => !supported.includes(c)),
+      };
+    },
+
+    supports(cap) {
+      return supported.includes(cap);
+    },
+  };
+
+  // Bind each capability; refuse the rest with an actionable message.
+  for (const cap of SCANNER_CAPABILITIES) {
+    if (supported.includes(cap)) {
+      scanner[cap] = async (...args) => impl[cap](...args, { scanner });
+    } else {
+      scanner[cap] = async () => {
+        throw new Error(
+          `${def.key} (chain ${def.chainId}) does not implement "${cap}". ` +
+            `Supported: ${supported.join(", ") || "none"}. ` +
+            "An unimplemented capability is absent, not assumed -- implement it or " +
+            "treat this chain as fail-closed for that operation.",
+        );
+      };
+    }
+  }
+
+  return Object.freeze(scanner);
+}
+
+/** In-memory scanner registry. */
+const REGISTRY = new Map();
+
+export function registerScanner(def) {
+  const scanner = createScanner(def);
+  REGISTRY.set(scanner.chainId, scanner);
+  return scanner;
+}
+
+export function getScanner(chainId) {
+  return REGISTRY.get(Number(chainId)) || null;
+}
+
+export function listScanners() {
+  return [...REGISTRY.values()];
+}
+
+export function __clearScanners() {
+  REGISTRY.clear();
+}
+
+/**
+ * Coverage matrix across registered scanners: which chains can do what.
+ *
+ * This is what answers "can we trade on X" with a tier instead of a yes/no.
+ */
+export function scannerCoverage() {
+  const chains = {};
+  for (const s of REGISTRY.values()) {
+    chains[s.chainId] = {
+      key: s.key,
+      name: s.name,
+      ...s.capabilities(),
+      venueCount: s.venues.length,
+      // A chain with no verified venue cannot route value, by design.
+      failClosed: s.venues.length === 0,
+    };
+  }
+  return {
+    generatedAt: new Date().toISOString(),
+    chainCount: REGISTRY.size,
+    capabilities: [...SCANNER_CAPABILITIES],
+    chains,
+  };
+}