@oracle-agent/oracle 0.13.1 → 0.14.1

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,
+  };
+}

package/src/scanner/evm-scanner.mjs

@@ -0,0 +1,394 @@
+// Generic EVM scanner.
+//
+// This is the payoff of the contract: a chain becomes a CONFIG entry rather than a
+// bespoke integration. Everything here works on any EVM chain that exposes standard
+// JSON-RPC -- balances, ERC-20 metadata, log scanning, and pool discovery via the
+// public market-data providers.
+//
+// What it deliberately does NOT do: sign, broadcast, or invent a venue. Routing and
+// quoting need chain-specific verified addresses, so a chain supplies those in its
+// config and anything absent stays fail-closed.
+
+import { rpcCall, rpcBlockNumber, rpcGetBalance, erc20BalanceOf } from "../data/providers/evm-rpc.mjs";
+import { dexscreenerToken } from "../data/providers/dexscreener.mjs";
+import { EVIDENCE, RISK } from "./contract.mjs";
+import { v2VenueCapabilities } from "./v2-venue.mjs";
+import { v3VenueCapabilities } from "./v3-venue.mjs";
+
+// --- minimal ABI encoding, so the scanner has no ABI-library dependency -------
+
+const SELECTORS = {
+  decimals: "0x313ce567",
+  symbol: "0x95d89b41",
+  name: "0x06fdde03",
+  totalSupply: "0x18160ddd",
+  owner: "0x8da5cb5b",
+};
+
+function hexToBigInt(hex) {
+  if (!hex || hex === "0x") return null;
+  try {
+    return BigInt(hex);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decode a Solidity `string` return value.
+ *
+ * Handles both the ABI-encoded dynamic string and the legacy bytes32 form that some
+ * older tokens still return. Getting this wrong shows the user mojibake instead of a
+ * symbol, which erodes trust in every other number on the screen.
+ */
+function decodeString(hex) {
+  if (!hex || hex === "0x") return null;
+  const body = hex.slice(2);
+
+  // Dynamic string: offset(32) + length(32) + data
+  if (body.length >= 128) {
+    const len = Number(BigInt(`0x${body.slice(64, 128)}`));
+    if (len > 0 && len <= 256 && body.length >= 128 + len * 2) {
+      const bytes = body.slice(128, 128 + len * 2);
+      const s = Buffer.from(bytes, "hex").toString("utf8").replace(/\0+$/, "");
+      if (s) return s;
+    }
+  }
+
+  // bytes32: right-padded with zeros
+  const trimmed = Buffer.from(body.slice(0, 64), "hex")
+    .toString("utf8")
+    .replace(/\0+$/, "");
+  return trimmed || null;
+}
+
+function padAddress(addr) {
+  return addr.toLowerCase().replace(/^0x/, "").padStart(64, "0");
+}
+
+// --- capability implementations ----------------------------------------------
+
+function makeCapabilities(config) {
+  const { chainId } = config;
+
+  async function call(to, data, opts) {
+    return rpcCall(chainId, "eth_call", [{ to, data }, "latest"], opts);
+  }
+
+  return {
+    async blockNumber(opts = {}) {
+      const n = await rpcBlockNumber(chainId, opts);
+      return { chainId, blockNumber: n?.blockNumber ?? n, evidence: EVIDENCE.LIVE };
+    },
+
+    async nativeBalance(address, opts = {}) {
+      const r = await rpcGetBalance(chainId, address, opts);
+      return {
+        chainId,
+        address,
+        wei: r?.wei ?? r?.balance ?? null,
+        symbol: config.nativeCurrency?.symbol ?? null,
+        decimals: config.nativeCurrency?.decimals ?? 18,
+        evidence: EVIDENCE.LIVE,
+      };
+    },
+
+    async tokenBalance({ token, owner }, opts = {}) {
+      const r = await erc20BalanceOf({ chainId, token, owner }, opts);
+      return { chainId, token, owner, raw: r?.balance ?? r, evidence: EVIDENCE.LIVE };
+    },
+
+    /**
+     * Resolve an ERC-20's on-chain identity.
+     *
+     * Reads metadata from the contract itself rather than a token list, because a
+     * token list can be stale or omit a two-hour-old launch -- and because the
+     * on-chain answer is the one that governs an actual transfer.
+     */
+    async resolveToken(token, opts = {}) {
+      if (!/^0x[0-9a-fA-F]{40}$/.test(token || "")) {
+        return {
+          chainId,
+          token,
+          evidence: EVIDENCE.UNKNOWN,
+          error: "resolveToken needs a 20-byte address; symbol lookup is a market-data concern",
+        };
+      }
+
+      const [dec, sym, nm, supply] = await Promise.all([
+        call(token, SELECTORS.decimals, opts).catch(() => null),
+        call(token, SELECTORS.symbol, opts).catch(() => null),
+        call(token, SELECTORS.name, opts).catch(() => null),
+        call(token, SELECTORS.totalSupply, opts).catch(() => null),
+      ]);
+
+      const decimals = hexToBigInt(dec?.result ?? dec);
+      const isContract = decimals !== null || sym?.result || nm?.result;
+
+      return {
+        chainId,
+        address: token,
+        decimals: decimals === null ? null : Number(decimals),
+        symbol: decodeString(sym?.result ?? sym),
+        name: decodeString(nm?.result ?? nm),
+        totalSupply: (hexToBigInt(supply?.result ?? supply) ?? null)?.toString() ?? null,
+        // A "token" that answers none of the standard calls is not an ERC-20.
+        evidence: isContract ? EVIDENCE.LIVE : EVIDENCE.UNKNOWN,
+        warning: isContract
+          ? undefined
+          : "no ERC-20 metadata returned -- may not be a token contract",
+      };
+    },
+
+    /**
+     * Find tradeable pools via public market data.
+     *
+     * Deliberately routed through DexScreener rather than a factory walk: a factory
+     * walk finds pools that EXIST, while what a trader needs is pools with real
+     * liquidity. Pools with no liquidity are noise that gets people filled badly.
+     */
+    async resolvePools(token, opts = {}) {
+      const slug = config.dexscreenerSlug;
+      if (!slug) {
+        return {
+          chainId,
+          token,
+          pools: [],
+          evidence: EVIDENCE.UNAVAILABLE,
+          reason:
+            "no dexscreenerSlug configured for this chain; pool discovery is unavailable rather than guessed",
+        };
+      }
+
+      const res = await dexscreenerToken(token, opts).catch(() => null);
+      const pairs = (res?.pairs || res?.data?.pairs || []).filter(
+        (p) => String(p.chainId).toLowerCase() === String(slug).toLowerCase(),
+      );
+
+      const pools = pairs
+        .map((p) => ({
+          pair: p.pairAddress,
+          dex: p.dexId,
+          base: p.baseToken?.address,
+          quote: p.quoteToken?.address,
+          liquidityUsd: p.liquidity?.usd ?? null,
+          priceUsd: p.priceUsd ?? null,
+          volume24hUsd: p.volume?.h24 ?? null,
+          createdAt: p.pairCreatedAt ?? null,
+        }))
+        .sort((a, b) => (b.liquidityUsd ?? 0) - (a.liquidityUsd ?? 0));
+
+      return {
+        chainId,
+        token,
+        pools,
+        evidence: pools.length ? EVIDENCE.LIVE : EVIDENCE.UNKNOWN,
+      };
+    },
+
+    /**
+     * Scan a block range for logs.
+     *
+     * Chunked, because every public RPC caps range width and an unchunked scan fails
+     * confusingly at the provider rather than here.
+     */
+    async scanBlocks({ fromBlock, toBlock, address, topics, chunkSize = 2000 } = {}, opts = {}) {
+      if (!Number.isInteger(fromBlock) || !Number.isInteger(toBlock)) {
+        throw new Error("scanBlocks requires integer fromBlock and toBlock");
+      }
+      if (toBlock < fromBlock) throw new Error("toBlock must be >= fromBlock");
+
+      const logs = [];
+      const chunks = [];
+      for (let start = fromBlock; start <= toBlock; start += chunkSize) {
+        const end = Math.min(start + chunkSize - 1, toBlock);
+        chunks.push([start, end]);
+      }
+
+      for (const [start, end] of chunks) {
+        const filter = {
+          fromBlock: `0x${start.toString(16)}`,
+          toBlock: `0x${end.toString(16)}`,
+        };
+        if (address) filter.address = address;
+        if (topics) filter.topics = topics;
+
+        const res = await rpcCall(chainId, "eth_getLogs", [filter], opts).catch((e) => ({
+          error: String(e?.message || e),
+        }));
+        if (res?.error) {
+          // Report the partial scan honestly instead of pretending the range was clean.
+          return {
+            chainId,
+            fromBlock,
+            toBlock,
+            logs,
+            complete: false,
+            failedAt: [start, end],
+            error: res.error,
+            evidence: EVIDENCE.UNKNOWN,
+          };
+        }
+        for (const l of res?.result ?? res ?? []) logs.push(l);
+      }
+
+      return {
+        chainId,
+        fromBlock,
+        toBlock,
+        logs,
+        complete: true,
+        chunks: chunks.length,
+        evidence: EVIDENCE.LIVE,
+      };
+    },
+
+    /**
+     * Structural risk assessment.
+     *
+     * Returns UNKNOWN rather than PASS when checks could not run -- the distinction
+     * that keeps "we couldn't tell" from reading as "it's fine".
+     */
+    async scoreRisk(token, opts = {}) {
+      const checks = [];
+      let verdict = RISK.PASS;
+
+      const downgrade = (v) => {
+        const order = { [RISK.PASS]: 0, [RISK.CAUTION]: 1, [RISK.UNKNOWN]: 2, [RISK.FAIL]: 3 };
+        if (order[v] > order[verdict]) verdict = v;
+      };
+
+      const meta = await this.resolveToken(token, opts);
+      if (meta.evidence !== EVIDENCE.LIVE) {
+        checks.push({ check: "erc20-metadata", result: RISK.UNKNOWN, detail: meta.warning });
+        downgrade(RISK.UNKNOWN);
+      } else {
+        checks.push({ check: "erc20-metadata", result: RISK.PASS, detail: `${meta.symbol} / ${meta.decimals}d` });
+      }
+
+      const pools = await this.resolvePools(token, opts);
+      if (pools.evidence === EVIDENCE.UNAVAILABLE) {
+        checks.push({ check: "liquidity", result: RISK.UNKNOWN, detail: pools.reason });
+        downgrade(RISK.UNKNOWN);
+      } else if (!pools.pools.length) {
+        checks.push({ check: "liquidity", result: RISK.FAIL, detail: "no pool with liquidity found" });
+        downgrade(RISK.FAIL);
+      } else {
+        const top = pools.pools[0];
+        const liq = top.liquidityUsd ?? 0;
+        if (liq < 5_000) {
+          checks.push({ check: "liquidity", result: RISK.CAUTION, detail: `top pool only $${liq}` });
+          downgrade(RISK.CAUTION);
+        } else {
+          checks.push({ check: "liquidity", result: RISK.PASS, detail: `$${liq} on ${top.dex}` });
+        }
+
+        if (top.createdAt && Date.now() - top.createdAt < 24 * 3600 * 1000) {
+          checks.push({ check: "age", result: RISK.CAUTION, detail: "pool under 24h old" });
+          downgrade(RISK.CAUTION);
+        }
+      }
+
+      // Sellability. This is the check that actually separates a tradeable token
+      // from a trap, so run it for real when the chain has a verified router and say
+      // plainly that it is unproven when it does not.
+      if (typeof this.sellSimulation === "function") {
+        const sim = await this.sellSimulation(
+          { token, amountIn: (10n ** 16n).toString() },
+          opts,
+        ).catch((e) => ({ verdict: RISK.UNKNOWN, reason: String(e?.message || e) }));
+
+        checks.push({
+          check: "sellability",
+          result: sim.verdict,
+          detail:
+            sim.retentionBps != null
+              ? `round trip returns ${(sim.retentionBps / 100).toFixed(2)}% -- ${sim.reason}`
+              : sim.reason,
+        });
+        downgrade(sim.verdict);
+      } else {
+        checks.push({
+          check: "sellability",
+          result: RISK.UNKNOWN,
+          detail:
+            "no verified router on this chain, so a round-trip sell simulation cannot " +
+            "run. Treat as unproven -- a buy path is not an exit path.",
+        });
+        downgrade(RISK.UNKNOWN);
+      }
+
+      return {
+        chainId,
+        token,
+        verdict,
+        checks,
+        note:
+          "Structural checks only. UNKNOWN is not PASS. A token is not tradeable " +
+          "until a sell simulation succeeds.",
+      };
+    },
+  };
+}
+
+/**
+ * Build a scanner definition for any EVM chain from config alone.
+ *
+ * @param {object} config
+ * @param {string} config.key                 lowercase slug
+ * @param {number} config.chainId
+ * @param {string} config.name
+ * @param {string[]} config.rpcEnv            env var names holding the RPC url
+ * @param {object} [config.nativeCurrency]    { symbol, decimals }
+ * @param {string} [config.explorer]
+ * @param {string} [config.dexscreenerSlug]   enables pool discovery
+ * @param {object[]} [config.venues]          verified routers/quoters/factories
+ */
+export function defineEvmScanner(config) {
+  const caps = makeCapabilities(config);
+
+  // Single object holding BOTH generic and venue capabilities, so every capability
+  // sees the others through `this`. This matters for scoreRisk: it calls
+  // this.sellSimulation, which only exists once venue caps are merged in. Binding
+  // generic caps to their own object first would leave scoreRisk permanently blind to
+  // the real sell check and silently report sellability as UNKNOWN on a chain that
+  // can actually prove it.
+  const surface = { ...caps };
+
+  // Venue adapters are selected by declared shape. V3 cannot reuse the V2 adapter --
+  // it has no getAmountsOut, prices through a separate Quoter, and needs an explicit
+  // fee tier -- so encoding one with the other's assumptions yields a transaction
+  // that reverts or routes through the wrong pool.
+  const kinds = new Set((config.venues || []).map((v) => v.kind));
+  if (config.venueKind === "uniswap-v3" && kinds.has("quoter") && kinds.has("router")) {
+    Object.assign(
+      surface,
+      v3VenueCapabilities({
+        chainId: config.chainId,
+        wrappedNative: config.wrappedNative,
+      }),
+    );
+  } else if (config.venueKind === "uniswap-v2" && kinds.has("router")) {
+    Object.assign(
+      surface,
+      v2VenueCapabilities({
+        chainId: config.chainId,
+        wrappedNative: config.wrappedNative,
+      }),
+    );
+  }
+
+  const bound = {};
+  for (const [k, fn] of Object.entries(surface)) bound[k] = fn.bind(surface);
+
+  return {
+    key: config.key,
+    chainId: config.chainId,
+    name: config.name,
+    rpcEnv: config.rpcEnv,
+    nativeCurrency: config.nativeCurrency,
+    explorer: config.explorer,
+    venues: config.venues || [],
+    capabilities: bound,
+  };
+}

package/src/scanner/index.mjs

@@ -0,0 +1,9 @@
+// Public scanner package subpath.
+//
+// Keep this as the stable API for README examples. `contract.mjs` defines the
+// scanner contract/registry; `chains.config.mjs` defines built-in and custom EVM
+// registration helpers. Export both here so package consumers do not need to know
+// the internal file split.
+
+export * from "./contract.mjs";
+export { CHAIN_CONFIGS, registerBuiltinScanners, registerCustomChain } from "./chains.config.mjs";