@oracle-agent/oracle 0.1.0

package/scripts/e2e-solana-bitcoin.mjs

@@ -0,0 +1,183 @@
+// Oracle end-to-end LIVE lane probe: Solana + Bitcoin.
+// Read/quote/prepare/simulate only. No signing. No broadcast. No keys required.
+//
+// Run: node scripts/e2e-solana-bitcoin.mjs
+// Exit 0 = every mandatory lane answered live. Optional keyed lanes are reported, not failed.
+
+import { data as desk } from "../src/data/desk-data.mjs";
+import { jupiterQuote, jupiterPrepareSwap, SOL_MINT, USDC_MINT } from "../src/data/providers/jupiter.mjs";
+import { solanaSimulateTransaction } from "../src/data/providers/solana-rpc.mjs";
+import { magicEdenSolStats, magicEdenSolListings, magicEdenSolPrepareBuy } from "../src/data/providers/magiceden-sol.mjs";
+
+const PROBE_WALLET = process.env.ORACLE_E2E_SOL_PUBKEY || "11111111111111111111111111111111";
+const PROBE_BTC = process.env.ORACLE_E2E_BTC_ADDRESS || "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";
+
+const results = [];
+function record(lane, status, detail) {
+  results.push({ lane, status, detail });
+  const tag = status === "ok" ? "OK  " : status === "keyed" ? "KEY " : "FAIL";
+  console.log(`${tag} ${lane} :: ${detail}`);
+}
+
+async function run(lane, fn, { optional = false } = {}) {
+  try {
+    const detail = await fn();
+    record(lane, "ok", detail);
+    return true;
+  } catch (error) {
+    const message = String(error?.message || error).slice(0, 140);
+    record(lane, optional ? "keyed" : "fail", message);
+    return optional;
+  }
+}
+
+console.log("== SOLANA ==");
+
+await run("solana.rpc.health", async () => {
+  const health = await desk.solana.health();
+  if (!health?.ok) throw new Error(`rpc unhealthy ${JSON.stringify(health).slice(0, 80)}`);
+  return `cluster ok slot lane live`;
+});
+
+await run("solana.rpc.balance", async () => {
+  const bal = await desk.solana.balance(PROBE_WALLET);
+  return `lamports=${bal?.lamports ?? bal?.value ?? "n/a"}`;
+});
+
+await run("solana.rpc.tokenAccounts", async () => {
+  const accounts = await desk.solana.tokenAccounts({ owner: PROBE_WALLET });
+  return `accounts=${accounts?.accounts?.length ?? 0}`;
+});
+
+let jupQuote = null;
+await run("solana.jupiter.quote(SOL->USDC)", async () => {
+  jupQuote = await jupiterQuote({ inputMint: SOL_MINT, outputMint: USDC_MINT, amount: "10000000", slippageBps: 50 });
+  const g = jupQuote.solanaGuard;
+  if (jupQuote.executionReady !== false) throw new Error("quote must not be executionReady");
+  if (g.slippageBps > 100) throw new Error("slippage cap breached");
+  return `out=${jupQuote.quote.outAmount} bps=${g.slippageBps} expires=${g.expiresAtMs - g.quotedAtMs}ms execReady=false`;
+});
+
+await run("solana.jupiter.slippageCap", async () => {
+  try {
+    await jupiterQuote({ inputMint: SOL_MINT, outputMint: USDC_MINT, amount: "10000000", slippageBps: 500 });
+  } catch (error) {
+    return `rejected 500bps: ${String(error.message).slice(0, 60)}`;
+  }
+  throw new Error("500 bps was NOT rejected");
+});
+
+let jupPrepared = null;
+await run("solana.jupiter.prepareSwap", async () => {
+  jupPrepared = await jupiterPrepareSwap({
+    quoteResponse: jupQuote.quote,
+    userPublicKey: PROBE_WALLET,
+  });
+  if (jupPrepared.signingReady !== false || jupPrepared.broadcastReady !== false) throw new Error("prepare leaked signing/broadcast readiness");
+  if (!jupPrepared.requiresUserSignature) throw new Error("prepare must require user signature");
+  return `tx=${jupPrepared.swapTransaction.length}b64 requiresUserSig=true signingReady=false broadcastReady=false`;
+});
+
+await run("solana.rpc.simulate(preparedSwap)", async () => {
+  const sim = await solanaSimulateTransaction({ transaction: jupPrepared.swapTransaction, sigVerify: false });
+  const err = sim?.err ?? sim?.value?.err ?? sim?.raw?.value?.err ?? null;
+  const units = sim?.unitsConsumed ?? sim?.value?.unitsConsumed ?? sim?.raw?.value?.unitsConsumed ?? null;
+  return `err=${JSON.stringify(err)} unitsConsumed=${units}`;
+});
+
+await run("solana.nft.magiceden.stats", async () => {
+  const stats = await magicEdenSolStats({ symbol: "mad_lads" });
+  if (!(stats.floorPriceSol > 0)) throw new Error("no floor");
+  return `floor=${stats.floorPriceSol} SOL listed=${stats.listedCount}`;
+});
+
+let meListing = null;
+await run("solana.nft.magiceden.listings", async () => {
+  const out = await magicEdenSolListings({ symbol: "mad_lads", limit: 1 });
+  meListing = out.listings[0];
+  if (!meListing?.tokenMint) throw new Error("no listing");
+  return `mint=${meListing.tokenMint.slice(0, 8)}.. price=${meListing.priceSol} SOL seller=${meListing.seller.slice(0, 6)}..`;
+});
+
+await run(
+  "solana.nft.magiceden.prepareBuy",
+  async () => {
+    const prep = await magicEdenSolPrepareBuy({
+      buyer: PROBE_WALLET,
+      seller: meListing.seller,
+      auctionHouse: meListing.auctionHouse,
+      tokenMint: meListing.tokenMint,
+      tokenATA: meListing.tokenATA,
+      priceSol: meListing.priceSol,
+    });
+    if (prep.broadcastReady !== false) throw new Error("prepare leaked broadcast readiness");
+    return `tx prepared bytes=${String(prep.transaction || "").length} requiresUserSig=${prep.requiresUserSignature}`;
+  },
+  { optional: true }
+);
+
+console.log("== BITCOIN ==");
+
+await run("bitcoin.esplora.health", async () => {
+  const h = await desk.bitcoin.health();
+  if (!h?.ok) throw new Error("esplora unhealthy");
+  return `ok tip lane live`;
+});
+
+await run("bitcoin.esplora.tipHeight", async () => {
+  const t = await desk.bitcoin.tipHeight();
+  const height = t?.height ?? t?.tipHeight ?? t;
+  if (!Number(height)) throw new Error("no tip height");
+  return `tip=${height}`;
+});
+
+await run("bitcoin.esplora.fees", async () => {
+  const f = await desk.bitcoin.fees();
+  const fast = f?.fastestFee ?? f?.fees?.fastestFee ?? f?.["1"] ?? null;
+  return `fastest=${JSON.stringify(fast)}`;
+});
+
+await run("bitcoin.esplora.address", async () => {
+  const a = await desk.bitcoin.address(PROBE_BTC);
+  const funded = a?.chainStats?.fundedTxoSum ?? a?.balanceSats ?? a?.raw?.chain_stats?.funded_txo_sum ?? null;
+  return `fundedSats=${funded}`;
+});
+
+await run("bitcoin.esplora.utxos", async () => {
+  const u = await desk.bitcoin.utxos(PROBE_BTC);
+  const n = u?.utxos?.length ?? u?.length ?? 0;
+  return `utxos=${n}`;
+});
+
+await run("bitcoin.meta.health", async () => {
+  const h = await desk.bitcoin.metaHealth();
+  return `ok=${h?.ok} tier=${h?.tier ?? h?.mode ?? "keyless"}`;
+});
+
+await run(
+  "bitcoin.meta.inscriptionInfo",
+  async () => {
+    const info = await desk.bitcoin.inscriptions(PROBE_BTC);
+    return `inscriptions=${info?.inscriptions?.length ?? "unknown"}`;
+  },
+  { optional: true }
+);
+
+await run(
+  "bitcoin.satflow.health",
+  async () => {
+    const h = await desk.bitcoin.satflowHealth();
+    if (!h?.ok) throw new Error(`satflow ${JSON.stringify(h).slice(0, 90)}`);
+    return `ok`;
+  },
+  { optional: true }
+);
+
+const failed = results.filter((r) => r.status === "fail");
+const keyed = results.filter((r) => r.status === "keyed");
+console.log(`\nlanes=${results.length} ok=${results.length - failed.length - keyed.length} keyed=${keyed.length} failed=${failed.length}`);
+if (failed.length) {
+  console.log(`FAILED: ${failed.map((f) => f.lane).join(", ")}`);
+  process.exit(1);
+}
+console.log("E2E OK: every mandatory Solana + Bitcoin lane answered live, prepare-only posture held.");

package/scripts/public-api-scan.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import { scanPublicApis } from "../src/data/public-api-scan.mjs";
+
+const args = process.argv.slice(2);
+const value = (flag) => {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+};
+const outPath = value("--out");
+const timeoutMs = Number(value("--timeout-ms") || 12_000);
+const providers = value("--providers")?.split(",").map((x) => x.trim()).filter(Boolean);
+
+const report = await scanPublicApis({ providers, timeoutMs });
+const json = `${JSON.stringify(report, null, 2)}\n`;
+if (outPath) {
+  const target = path.resolve(outPath);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, json, "utf8");
+  console.error(`wrote ${target}`);
+}
+process.stdout.write(json);

package/scripts/secret-scan.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// Pre-publication secret scan. Fails CLOSED: any hit is an error.
+//
+// Checks the working tree AND every blob in git history, because a secret
+// removed in a later commit is still public the moment the repo is.
+
+import { execFileSync } from "node:child_process";
+
+const ROOT = process.cwd();
+
+// Live values that must never appear. Sourced from the environment at scan
+// time so the scanner itself contains no secrets.
+function liveSecrets() {
+  const out = [];
+  const push = (label, value) => {
+    const v = String(value || "").trim();
+    if (v.length >= 8) out.push({ label, value: v });
+  };
+  for (const k of Object.keys(process.env)) {
+    if (/(_KEY|_SECRET|_TOKEN|_PASSPHRASE|_WIF|PRIVATE_KEY)$/i.test(k)) {
+      push(`env:${k}`, process.env[k]);
+    }
+  }
+  return out;
+}
+
+// A representative slice of the BIP39 English wordlist. Full coverage is not
+// required: a real mnemonic is 12 or 24 words drawn ENTIRELY from the list, so
+// any genuine phrase will hit these common entries, while English prose will
+// not have every one of its words in the list.
+const BIP39_SAMPLE = new Set(
+  ("abandon ability able about above absent absorb abstract absurd abuse access accident account accuse achieve acid " +
+   "across act action actor actress actual adapt add addict address adjust admit adult advance advice aerobic affair " +
+   "afford afraid again age agent agree ahead aim air airport aisle alarm album alcohol alert alien all alley allow " +
+   "almost alone alpha already also alter always amateur amazing among amount amused analyst anchor ancient anger " +
+   "angle angry animal ankle announce annual another answer antenna antique anxiety any apart apology appear apple " +
+   "approve april arch arctic area arena argue arm armed armor army around arrange arrest arrive arrow art artefact " +
+   "artist artwork ask aspect assault asset assist assume asthma athlete atom attack attend attitude attract auction " +
+   "audit august aunt author auto autumn average avocado avoid awake aware away awesome awful awkward axis baby " +
+   "bachelor bacon badge bag balance balcony ball bamboo banana banner bar barely bargain barrel base basic basket " +
+   "battle beach bean beauty because become beef before begin behave behind believe below belt bench benefit best " +
+   "betray better between beyond bicycle bid bike bind biology bird birth bitter black blade blame blanket blast " +
+   "bleak bless blind blood blossom blouse blue blur blush board boat body boil bomb bone bonus book boost border " +
+   "boring borrow boss bottom bounce box boy bracket brain brand brass brave bread breeze brick bridge brief bright " +
+   "bring brisk broccoli broken bronze broom brother brown brush bubble buddy budget buffalo build bulb bulk bullet " +
+   "bundle bunker burden burger burst bus business busy butter buyer buzz cabbage cabin cable cactus cage cake call " +
+   "calm camera camp can canal cancel candy cannon canoe canvas canyon capable capital captain car carbon card cargo " +
+   "carpet carry cart case cash casino castle casual cat catalog catch category cattle caught cause caution cave " +
+   "ceiling celery cement census century cereal certain chair chalk champion change chaos chapter charge chase chat " +
+   "cheap check cheese chef cherry chest chicken chief child chimney choice choose chronic chuckle chunk churn cigar " +
+   "cinnamon circle citizen city civil claim clap clarify claw clay clean clerk clever click client cliff climb " +
+   "clinic clip clock clog close cloth cloud clown club clump cluster clutch coach coast coconut code coffee coil " +
+   "coin collect color column combine come comfort comic common company concert conduct confirm congress connect " +
+   "consider control convince cook cool copper copy coral core corn correct cost cotton couch country couple course " +
+   "cousin cover coyote crack cradle craft cram crane crash crater crawl crazy cream credit creek crew cricket crime " +
+   "crisp critic crop cross crouch crowd crucial cruel cruise crumble crunch crush cry crystal cube culture cup " +
+   "cupboard curious current curtain curve cushion custom cute cycle zoo zone zero youth young you yellow year " +
+   "wrong write wrist wrap worth world work word wood wonder woman wolf wire winter wing wine window wind wild wife " +
+   "why whisper white where when wheat what wet west welcome weird weekend week wedding web wealth wear weapon " +
+   "weasel wear wave water watch waste wash warrior warm want walnut wall walk wait wagon void voice vote volume " +
+   "vocal vivid virus violin virtual vintage view video vicious vibrant vessel very verify version verb vendor " +
+   "vehicle vegetable vault various vast vase vanish valve valley valid vacuum vacant").split(/\s+/)
+);
+
+const PATTERNS = [
+  { name: "private key (hex 64)", re: /\b(?:0x)?[0-9a-fA-F]{64}\b/, refine: (m, line) =>
+      /priv|secret|wif|seed|mnemonic|signer|wallet/i.test(line) && !/hash|digest|sha256|txid|commit|blob|sha1|0x0{40,}/i.test(line) },
+  { name: "BTC WIF", re: /\b[5KL][1-9A-HJ-NP-Za-km-z]{50,51}\b/ },
+  { name: "BIP39 seed phrase", re: /\b(?:[a-z]{3,8} ){11,23}[a-z]{3,8}\b/, refine: (m) => {
+      // Ordinary English prose trivially matches "12-24 short lowercase words".
+      // A scanner that cries wolf on comments is a scanner people switch off,
+      // so require the words to actually be in the BIP39 wordlist.
+      const words = m[0].trim().split(/\s+/);
+      if (words.length !== 12 && words.length !== 24) return false;
+      return words.every((w) => BIP39_SAMPLE.has(w));
+    } },
+  { name: "AWS access key", re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { name: "OpenAI key", re: /\bsk-[A-Za-z0-9_-]{20,}\b/ },
+  { name: "Anthropic key", re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/ },
+  { name: "GitHub token", re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/ },
+  { name: "Slack token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+  { name: "Telegram bot token", re: /\b\d{8,10}:[A-Za-z0-9_-]{35}\b/ },
+  { name: "PEM private key", re: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/ },
+  { name: "Solana keypair array", re: /\[\s*(?:\d{1,3}\s*,\s*){63}\d{1,3}\s*\]/ },
+];
+
+// Paths whose matches are known-safe test fixtures.
+const ALLOWED_PATHS = [
+  /^scripts\/secret-scan\.mjs$/,
+  /^package-lock\.json$/,
+];
+
+// Literal strings that are documented, synthetic, or public by nature.
+const ALLOWED_VALUES = [
+  "0x0123456789012345678901234567890123456789012345678901234567890123", // HL SDK public test vector
+  "L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ",
+  "/-----BEGIN[A-Z ]*PRIVATE KEY-----/",
+  '{ value: "-----BEGIN EC PRIVATE KEY-----" }',
+  "0x0000000000000000000000000000000000000000",
+];
+
+function sh(cmd, args) {
+  return execFileSync(cmd, args, { cwd: ROOT, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+}
+
+function scanText(text, origin, findings) {
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.length > 4000) continue;
+    for (const p of PATTERNS) {
+      const m = p.re.exec(line);
+      if (!m) continue;
+      if (ALLOWED_VALUES.some((v) => line.includes(v))) continue;
+      if (p.refine && !p.refine(m, line)) continue;
+      findings.push({ origin, line: i + 1, kind: p.name, sample: line.trim().slice(0, 100) });
+    }
+    for (const s of LIVE) {
+      if (line.includes(s.value)) {
+        findings.push({ origin, line: i + 1, kind: `LIVE SECRET ${s.label}`, sample: "[REDACTED — real credential]" });
+      }
+    }
+  }
+}
+
+const LIVE = liveSecrets();
+const findings = [];
+
+// --- 1. working tree (tracked files only) ---
+const tracked = sh("git", ["ls-files"]).split("\n").filter(Boolean);
+for (const rel of tracked) {
+  if (ALLOWED_PATHS.some((r) => r.test(rel))) continue;
+  let content;
+  try {
+    content = sh("git", ["show", `:${rel}`]);
+  } catch {
+    continue; // binary or unreadable
+  }
+  if (content.includes("\u0000")) continue;
+  scanText(content, rel, findings);
+}
+
+// --- 2. every blob in history ---
+const revs = sh("git", ["rev-list", "--all"]).split("\n").filter(Boolean);
+const seen = new Set();
+let historyBlobs = 0;
+for (const rev of revs) {
+  const entries = sh("git", ["ls-tree", "-r", rev]).split("\n").filter(Boolean);
+  for (const entry of entries) {
+    const [meta, path] = entry.split("\t");
+    const sha = meta.split(/\s+/)[2];
+    if (!sha || seen.has(sha)) continue;
+    seen.add(sha);
+    if (ALLOWED_PATHS.some((r) => r.test(path))) continue;
+    let content;
+    try {
+      content = sh("git", ["cat-file", "-p", sha]);
+    } catch {
+      continue;
+    }
+    if (content.includes("\u0000")) continue;
+    historyBlobs++;
+    scanText(content, `history:${rev.slice(0, 8)}:${path}`, findings);
+  }
+}
+
+// --- 3. author identity leakage ---
+const authors = new Set(sh("git", ["log", "--all", "--format=%an <%ae>|%cn <%ce>"]).split(/[\n|]/).filter(Boolean));
+
+console.log(`scanned ${tracked.length} tracked files, ${historyBlobs} historical blobs, ${revs.length} commits`);
+console.log(`live env secrets checked: ${LIVE.length}`);
+console.log(`git identities: ${[...authors].join(", ") || "(none)"}`);
+
+if (findings.length) {
+  console.error(`\nFAIL — ${findings.length} finding(s):`);
+  for (const f of findings.slice(0, 40)) {
+    console.error(`  ${f.origin}:${f.line}  [${f.kind}]  ${f.sample}`);
+  }
+  process.exit(1);
+}
+console.log("\nPASS — no secrets found in tree or history");

package/scripts/verify-v3-venues.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// Functionally verify Uniswap V3 venue addresses on every chain.
+//
+// Codesize alone is NOT verification -- an unrelated contract also has bytecode, and
+// on Base the canonical mainnet addresses returned 2109 bytes for two different
+// contracts, which is exactly the kind of false positive a size check waves through.
+//
+// The real test is behavioural: ask the candidate quoter to price a pair we already
+// know the answer to. A contract that returns a sane WETH->USDC quote at a standard
+// fee tier IS a working V3 quoter, regardless of what any doc claims.
+//
+// Output is a provenance record per chain, ready to paste into chains.config.mjs.
+
+import { rpcCall } from "../src/data/providers/evm-rpc.mjs";
+
+// Candidates. Most chains share the canonical deployment; Base, BSC and Avalanche
+// have their own. All of these are CANDIDATES until the probe passes.
+const CANONICAL_QUOTER = "0x61fFE014bA17989E743c5F6cB21bF9697530B21e";
+const CANONICAL_ROUTER = "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45";
+
+const CANDIDATES = {
+  1: {
+    name: "ethereum",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH
+    tokenOut: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+    decIn: 18,
+    decOut: 6,
+  },
+  10: {
+    name: "optimism",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0x4200000000000000000000000000000000000006",
+    tokenOut: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+    decIn: 18,
+    decOut: 6,
+  },
+  56: {
+    name: "bsc",
+    quoter: "0x78D78E420Da98ad378D7799bE8f4AF69033EB077",
+    router: "0xB971eF87ede563556b2ED4b1C0b0019111Dd85d2",
+    tokenIn: "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c", // WBNB
+    tokenOut: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d", // USDC (18dp on BSC)
+    decIn: 18,
+    decOut: 18,
+  },
+  137: {
+    name: "polygon",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270", // WMATIC
+    tokenOut: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // USDC native
+    decIn: 18,
+    decOut: 6,
+  },
+  8453: {
+    name: "base",
+    quoter: "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a",
+    router: "0x2626664c2603336E57B271c5C0b26F421741e481",
+    tokenIn: "0x4200000000000000000000000000000000000006",
+    tokenOut: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    decIn: 18,
+    decOut: 6,
+  },
+  42161: {
+    name: "arbitrum",
+    quoter: CANONICAL_QUOTER,
+    router: CANONICAL_ROUTER,
+    tokenIn: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
+    tokenOut: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+    decIn: 18,
+    decOut: 6,
+  },
+  43114: {
+    name: "avalanche",
+    quoter: "0xbe0F5544EC67e9B3b2D979aaA43f18Fd87E6257F",
+    router: "0xbb00FF08d01D300023C629E8fFfFcb65A5a578cE",
+    tokenIn: "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7", // WAVAX
+    tokenOut: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", // USDC
+    decIn: 18,
+    decOut: 6,
+  },
+};
+
+const FEE_TIERS = [500, 3000, 10000];
+
+const word = (v) => BigInt(v).toString(16).padStart(64, "0");
+const addrWord = (a) => a.slice(2).toLowerCase().padStart(64, "0");
+
+// QuoterV2.quoteExactInputSingle((address,address,uint256,uint24,uint160))
+// selector 0xc6a5026a -- struct is encoded inline as 5 words.
+function encodeQuote({ tokenIn, tokenOut, amountIn, fee }) {
+  return (
+    "0xc6a5026a" +
+    addrWord(tokenIn) +
+    addrWord(tokenOut) +
+    word(amountIn) +
+    word(fee) +
+    word(0) // sqrtPriceLimitX96 = 0 (no limit)
+  );
+}
+
+async function codesize(chainId, address) {
+  const r = await rpcCall(chainId, "eth_getCode", [address, "latest"]).catch(() => null);
+  const raw = r?.result ?? r;
+  return raw && raw !== "0x" ? (raw.length - 2) / 2 : 0;
+}
+
+async function probe(chainId, cfg) {
+  const result = {
+    chainId: Number(chainId),
+    name: cfg.name,
+    quoter: cfg.quoter,
+    router: cfg.router,
+    quoterCodesize: 0,
+    routerCodesize: 0,
+    workingFeeTier: null,
+    quotedOut: null,
+    humanPrice: null,
+    verdict: "FAIL",
+    reason: "",
+  };
+
+  result.quoterCodesize = await codesize(chainId, cfg.quoter);
+  result.routerCodesize = await codesize(chainId, cfg.router);
+
+  if (!result.quoterCodesize || !result.routerCodesize) {
+    result.reason = "no bytecode at candidate address on this chain";
+    return result;
+  }
+
+  // Behavioural probe: does it actually price a pair we can sanity-check?
+  const amountIn = 10n ** BigInt(cfg.decIn);
+  for (const fee of FEE_TIERS) {
+    const data = encodeQuote({
+      tokenIn: cfg.tokenIn,
+      tokenOut: cfg.tokenOut,
+      amountIn,
+      fee,
+    });
+    const r = await rpcCall(chainId, "eth_call", [{ to: cfg.quoter, data }, "latest"]).catch(
+      () => null,
+    );
+    const raw = r?.result ?? r;
+    if (!raw || raw === "0x" || raw.length < 66) continue;
+
+    const out = BigInt(`0x${raw.slice(2, 66)}`);
+    if (out === 0n) continue;
+
+    result.workingFeeTier = fee;
+    result.quotedOut = out.toString();
+    result.humanPrice = Number(out) / 10 ** cfg.decOut;
+    break;
+  }
+
+  if (result.workingFeeTier == null) {
+    result.reason = "bytecode present but no fee tier returned a quote -- not a working V3 quoter";
+    return result;
+  }
+
+  // Sanity band. A working quoter on a major pair should land in a plausible range;
+  // a wildly wrong number means we are talking to the wrong contract or decoding it
+  // wrong, and either way it must not be allowlisted.
+  if (result.humanPrice <= 0 || !Number.isFinite(result.humanPrice)) {
+    result.reason = `implausible quote ${result.humanPrice}`;
+    return result;
+  }
+
+  result.verdict = "PASS";
+  result.reason =
+    `quoteExactInputSingle at fee ${result.workingFeeTier} returned ` +
+    `${result.humanPrice} for 1 unit in -- a live, working V3 quote`;
+  return result;
+}
+
+const out = [];
+for (const [chainId, cfg] of Object.entries(CANDIDATES)) {
+  const r = await probe(chainId, cfg);
+  out.push(r);
+  const line =
+    `${r.name.padEnd(10)} ${r.verdict.padEnd(5)} ` +
+    `quoter=${String(r.quoterCodesize).padStart(6)} router=${String(r.routerCodesize).padStart(6)} ` +
+    (r.workingFeeTier ? `fee=${String(r.workingFeeTier).padStart(5)} price=${r.humanPrice}` : r.reason);
+  console.log(line);
+}
+
+console.log(`\n${out.filter((r) => r.verdict === "PASS").length}/${out.length} chains verified`);
+if (process.argv.includes("--json")) {
+  console.log(JSON.stringify(out, null, 2));
+}