@oracle-agent/oracle 0.11.0 → 0.13.0

package/src/scanner/chains.config.mjs

@@ -1,430 +0,0 @@
-// 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 },
-    // DexScreener does index this chain under the slug "robinhood" (verified live
-    // 2026-07-31: a CASHCAT search returns pairs tagged chainId "robinhood"). Without
-    // the slug, resolvePools reported UNAVAILABLE on every RH token even though the
-    // data was there.
-    dexscreenerSlug: "robinhood",
-    venueKind: "uniswap-v3",
-    wrappedNative: "0x0bd7d308f8e1639fab988df18a8011f41eacad73",
-    venues: [
-      {
-        kind: "quoter",
-        address: "0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7",
-        label: "Uniswap V3 QuoterV2",
-        verified: {
-          method:
-            "functional probe, not a codesize check: quoteExactInputSingle returned a " +
-            "live sane price (WETH->USDG fee 100 quoted 1866.58 USDG, and USDG->CASHCAT " +
-            "fee 10000 quoted a live amount). A contract that correctly prices known pairs " +
-            "IS a working V3 quoter",
-          source: "live eth_call against rpc.mainnet.chain.robinhood.com",
-          date: "2026-07-31",
-          chainId: 4663,
-        },
-      },
-      {
-        kind: "router",
-        address: "0xcaf681a66d020601342297493863e78c959e5cb2",
-        label: "Uniswap V3 SwapRouter02",
-        verified: {
-          method:
-            "eth_getCode returned real bytecode (24497 bytes) on this chain and the paired " +
-            "quoter at the same deployment passed a live functional quote",
-          source: "live eth_getCode against rpc.mainnet.chain.robinhood.com",
-          date: "2026-07-31",
-          chainId: 4663,
-        },
-      },
-      {
-        kind: "factory",
-        address: "0x1f7d7550b1b028f7571e69a784071f0205fd2efa",
-        label: "Uniswap V3 Factory",
-        verified: {
-          method:
-            "eth_getCode returned real bytecode (24535 bytes) and a PoolCreated log scan " +
-            "over this factory returned 76 pools in ~9000 recent blocks",
-          source: "live eth_getLogs against rpc.mainnet.chain.robinhood.com",
-          date: "2026-07-31",
-          chainId: 4663,
-        },
-      },
-    ],
-  },
-  {
-    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

@@ -1,270 +0,0 @@
-// 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,
-  };
-}