@oracle-agent/oracle 0.1.0

package/bin/oracle-route.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+// oracle-route -- compare swap and bridge routes across every available source.
+//
+// Usage:
+//   oracle-route swap   <chain> <tokenIn> <tokenOut> [amountIn]
+//   oracle-route bridge <fromChain> <toChain> <token> [amountIn]
+//
+// <chain> is an id (8453) or key (base). --json for machine output.
+
+import { bestSwapRoute, bestBridgeRoute } from "../src/router/index.mjs";
+import { prepareBestRoute } from "../src/router/prepare-route.mjs";
+import { prepareBestBridgeRoute } from "../src/router/prepare-bridge.mjs";
+import { registerBuiltinScanners } from "../src/scanner/chains.config.mjs";
+import { getScanner, listScanners } from "../src/scanner/contract.mjs";
+
+registerBuiltinScanners();
+
+const [cmd, ...rest] = process.argv.slice(2);
+const JSON_OUT = rest.includes("--json");
+const args = rest.filter((a) => a !== "--json");
+const NATIVE = "0x0000000000000000000000000000000000000000";
+
+function chainId(ref) {
+  if (!ref) die("missing <chain>");
+  const n = Number(ref);
+  if (getScanner(n)) return n;
+  const s = listScanners().find((x) => x.key === String(ref).toLowerCase());
+  if (s) return s.chainId;
+  die(`unknown chain "${ref}". Known: ${listScanners().map((x) => x.key).join(", ")}`);
+}
+
+function die(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+
+function fmt(raw, decimals) {
+  const n = Number(raw) / 10 ** decimals;
+  return n.toLocaleString(undefined, { maximumFractionDigits: 6 });
+}
+
+function render(r, decimals) {
+  console.log(`sources: ${r.sourcesAnswered}/${r.sourcesTried} answered`);
+  console.log(`ranked on: ${r.rankedOn}\n`);
+
+  if (!r.routes.length) {
+    console.log("no source returned a usable route.");
+    for (const f of r.failed) console.log(`  ${f.source}: ${f.error}`);
+    return;
+  }
+
+  const w = Math.max(...r.routes.map((x) => x.source.length), 6);
+  console.log(`  ${"source".padEnd(w)}  ${"net out".padStart(14)}  ${"gross".padStart(14)}  cost`);
+  for (const [i, x] of r.routes.entries()) {
+    const mark = i === 0 ? "*" : " ";
+    const cost =
+      x.gasUsd == null
+        ? "gas unknown"
+        : x.gasUsd === 0
+          ? "gasless (solver)"
+          : `$${Number(x.gasUsd + (x.feeUsd ?? 0)).toFixed(2)}`;
+    const dur = x.meta?.durationSeconds != null ? `  ~${x.meta.durationSeconds}s` : "";
+    console.log(
+      `${mark} ${x.source.padEnd(w)}  ${fmt(x.netOut, decimals).padStart(14)}  ` +
+        `${fmt(x.grossOut, decimals).padStart(14)}  ${cost}${dur}`,
+    );
+  }
+
+  for (const f of r.failed) console.log(`  ${f.source.padEnd(w)}  FAILED: ${String(f.error).slice(0, 60)}`);
+
+  console.log(`\n${r.note}`);
+  for (const wn of r.warnings) console.log(`\nWARNING: ${wn}`);
+}
+
+try {
+  switch (cmd) {
+    case "swap": {
+      const cid = chainId(args[0]);
+      if (!args[1] || !args[2]) die("usage: oracle-route swap <chain> <tokenIn> <tokenOut> [amountIn]");
+      const amountIn = args[3] || (10n ** 18n).toString();
+      const scanner = getScanner(cid);
+
+      // Decimals matter twice: ParaSwap needs them to quote at all, and the ranker
+      // needs the destination's to convert gas into output units.
+      const [dIn, dOut] = await Promise.all([
+        scanner.resolveToken(args[1]).then((t) => t.decimals).catch(() => null),
+        scanner.resolveToken(args[2]).then((t) => t.decimals).catch(() => null),
+      ]);
+
+      const r = await bestSwapRoute({
+        chainId: cid,
+        tokenIn: args[1],
+        tokenOut: args[2],
+        amountIn,
+        taker: args[4] || "0x000000000000000000000000000000000000dEaD",
+        decimalsIn: dIn,
+        decimalsOut: dOut,
+      });
+      if (JSON_OUT) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+      else render(r, dOut ?? 18);
+      break;
+    }
+
+    case "bridge": {
+      const from = chainId(args[0]);
+      const to = chainId(args[1]);
+      const token = args[2] || NATIVE;
+      const amountIn = args[3] || (10n ** 18n).toString();
+
+      const r = await bestBridgeRoute({
+        fromChainId: from,
+        toChainId: to,
+        tokenIn: token,
+        tokenOut: token,
+        amountIn,
+        taker: args[4] || "0x000000000000000000000000000000000000dEaD",
+        decimalsOut: 18,
+      });
+      if (JSON_OUT) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+      else render(r, 18);
+      break;
+    }
+
+    case "prepare": {
+      const cid = chainId(args[0]);
+      if (!args[1] || !args[2] || !args[3]) {
+        die("usage: oracle-route prepare <chain> <tokenIn> <tokenOut> <taker> [amountIn] [--source=X]");
+      }
+      // Argument order puts taker BEFORE amount deliberately: preparing without a
+      // real taker is the one mistake that cannot be recovered from downstream.
+      const taker = args[3];
+      const amountIn = args[4] || (10n ** 18n).toString();
+      const srcArg = rest.find((a) => a.startsWith("--source="));
+      const scanner = getScanner(cid);
+
+      const [dIn, dOut] = await Promise.all([
+        scanner.resolveToken(args[1]).then((t) => t.decimals).catch(() => null),
+        scanner.resolveToken(args[2]).then((t) => t.decimals).catch(() => null),
+      ]);
+
+      const r = await prepareBestRoute({
+        chainId: cid,
+        tokenIn: args[1],
+        tokenOut: args[2],
+        amountIn,
+        taker,
+        decimalsIn: dIn,
+        decimalsOut: dOut,
+        source: srcArg ? srcArg.split("=")[1] : undefined,
+      });
+
+      if (JSON_OUT) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        break;
+      }
+
+      if (!r.ok) {
+        console.log(`could not prepare: ${r.reason}`);
+        if (r.failureKind) console.log(`kind: ${r.failureKind}`);
+        if (r.alternative) console.log(`try: --source=${r.alternative}`);
+        process.exit(1);
+      }
+
+      console.log(`source:      ${r.chosen.source}${r.chosen.wasWinner ? " (winner)" : " (override -- NOT the winner)"}`);
+      console.log(`artifact:    ${r.artifactKind}`);
+      console.log(`destination: ${r.destination}`);
+      if (r.minOut) console.log(`minOut:      ${r.minOut}`);
+      if (r.driftBps != null) console.log(`drift:       ${(r.driftBps / 100).toFixed(3)}% vs comparison`);
+      if (r.requiresApproval) {
+        console.log(`\napproval required first:`);
+        console.log(`  token   ${r.requiresApproval.token}`);
+        console.log(`  spender ${r.requiresApproval.spender}`);
+        if (r.requiresApproval.note) console.log(`  note    ${r.requiresApproval.note}`);
+      }
+      if (r.runnersUp?.length) {
+        console.log(`\nrunners-up: ${r.runnersUp.map((x) => x.source).join(", ")}`);
+      }
+      for (const w of r.warnings) console.log(`\nWARNING: ${w}`);
+      console.log(`\n${r.note}`);
+      break;
+    }
+
+    case "prepare-bridge": {
+      const from = chainId(args[0]);
+      const to = chainId(args[1]);
+      if (!args[2]) die("usage: oracle-route prepare-bridge <fromChain> <toChain> <taker> [token] [amountIn] [--source=X]");
+      const taker = args[2];
+      const token = args[3] || NATIVE;
+      const amountIn = args[4] || (10n ** 17n).toString();
+      const srcArg = rest.find((a) => a.startsWith("--source="));
+
+      const r = await prepareBestBridgeRoute({
+        fromChainId: from,
+        toChainId: to,
+        tokenIn: token,
+        tokenOut: token,
+        amountIn,
+        taker,
+        decimalsOut: 18,
+        source: srcArg ? srcArg.split("=")[1] : undefined,
+      });
+
+      if (JSON_OUT) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        break;
+      }
+      if (!r.ok) {
+        console.log(`could not prepare: ${r.reason}`);
+        if (r.failureKind) console.log(`kind: ${r.failureKind}`);
+        if (r.alternative) console.log(`try: --source=${r.alternative}`);
+        process.exit(1);
+      }
+
+      console.log(`source:      ${r.chosen.source}${r.chosen.wasWinner ? " (winner)" : " (override -- NOT the winner)"}`);
+      console.log(`artifact:    ${r.artifactKind}`);
+      console.log(`route:       chain ${r.fromChainId} -> chain ${r.toChainId}`);
+      console.log(`signs:       ${r.transactionCount} transaction(s) on chain ${r.fromChainId}`);
+      console.log(`destination: ${r.destination}`);
+      if (r.minOut) console.log(`minOut:      ${r.minOut}`);
+      if (r.durationSeconds != null) console.log(`eta:         ~${r.durationSeconds}s to credit`);
+      if (r.driftBps != null) console.log(`drift:       ${(r.driftBps / 100).toFixed(3)}% vs comparison`);
+      if (r.requiresApproval) {
+        console.log(`\napproval required first:`);
+        console.log(`  token   ${r.requiresApproval.token}`);
+        console.log(`  spender ${r.requiresApproval.spender}`);
+      }
+      r.transactions.forEach((t, i) => {
+        console.log(`\ntx ${i + 1}/${r.transactionCount}: chain ${t.chainId} -> ${t.to}`);
+      });
+      if (r.runnersUp?.length) console.log(`\nrunners-up: ${r.runnersUp.map((x) => x.source).join(", ")}`);
+      for (const w of r.warnings) console.log(`\nWARNING: ${w}`);
+      console.log(`\n${r.note}`);
+      break;
+    }
+
+    default:
+      console.log(
+        [
+          "oracle-route -- best-execution routing",
+          "",
+          "  oracle-route swap   <chain> <tokenIn> <tokenOut> [amountIn] [taker]",
+          "  oracle-route bridge <fromChain> <toChain> [token] [amountIn] [taker]",
+          "  oracle-route prepare <chain> <tokenIn> <tokenOut> <taker> [amountIn] [--source=X]",
+          "  oracle-route prepare-bridge <fromChain> <toChain> <taker> [token] [amt] [--source=X]",
+          "",
+          "  Ranks by NET output (gross minus gas and fees), not headline quote.",
+          "  A route quoting more but costing more gas can lose. --json for detail.",
+        ].join("\n"),
+      );
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (err) {
+  die(String(err?.message || err));
+}

package/bin/oracle-scan.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// oracle-scan -- exercise the chain-scanner framework from the shell.
+//
+// Useful for two things: checking a chain is actually reachable with your RPC
+// config, and researching a token without wiring up an agent first.
+//
+// Usage:
+//   oracle-scan chains                      coverage matrix for every chain
+//   oracle-scan head <chain>                current block
+//   oracle-scan token <chain> <address>     on-chain ERC-20 identity
+//   oracle-scan pools <chain> <address>     tradeable pools by liquidity
+//   oracle-scan risk  <chain> <address>     structural risk checks
+//
+// <chain> is a chain id (8453) or key (base).
+
+import { registerBuiltinScanners } from "../src/scanner/chains.config.mjs";
+import { getScanner, listScanners, scannerCoverage } from "../src/scanner/contract.mjs";
+
+registerBuiltinScanners();
+
+const [cmd, ...rest] = process.argv.slice(2);
+const JSON_OUT = rest.includes("--json");
+const args = rest.filter((a) => a !== "--json");
+
+function resolve(ref) {
+  if (!ref) die("missing <chain>");
+  const byId = getScanner(Number(ref));
+  if (byId) return byId;
+  const byKey = listScanners().find((s) => s.key === String(ref).toLowerCase());
+  if (byKey) return byKey;
+  die(
+    `unknown chain "${ref}". Known: ${listScanners().map((s) => `${s.key}(${s.chainId})`).join(", ")}`,
+  );
+}
+
+function die(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+
+function out(obj) {
+  process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+}
+
+// A missing RPC is the most common reason a scan fails. Say so precisely instead of
+// surfacing a generic fetch error.
+function rpcHint(scanner, err) {
+  const msg = String(err?.message || err);
+  if (/rpc|fetch|ECONN|timeout|provider/i.test(msg)) {
+    return (
+      `${msg}\n\nThis chain reads its RPC from: ${scanner.rpcEnv.join(" or ")}\n` +
+      `Set one, e.g.:  export ${scanner.rpcEnv[0]}=https://...`
+    );
+  }
+  return msg;
+}
+
+try {
+  switch (cmd) {
+    case "chains": {
+      const cov = scannerCoverage();
+      if (JSON_OUT) {
+        out(cov);
+        break;
+      }
+      console.log(`${cov.chainCount} chains registered\n`);
+      const rows = Object.entries(cov.chains).map(([id, c]) => ({
+        chain: `${c.key} (${id})`,
+        caps: c.supported.length,
+        routing: c.failClosed ? "fail-closed (no verified venue)" : `${c.venueCount} venue(s)`,
+      }));
+      const w = Math.max(...rows.map((r) => r.chain.length));
+      for (const r of rows) {
+        console.log(`  ${r.chain.padEnd(w)}  ${String(r.caps).padStart(2)} caps   ${r.routing}`);
+      }
+      console.log(
+        "\nEvery chain is read/research capable. Routing value requires a verified\n" +
+          "venue -- see CONTRIBUTING.md for the verification rule.",
+      );
+      break;
+    }
+
+    case "head": {
+      const s = resolve(args[0]);
+      out(await s.blockNumber());
+      break;
+    }
+
+    case "token": {
+      const s = resolve(args[0]);
+      if (!args[1]) die("usage: oracle-scan token <chain> <address>");
+      out(await s.resolveToken(args[1]));
+      break;
+    }
+
+    case "pools": {
+      const s = resolve(args[0]);
+      if (!args[1]) die("usage: oracle-scan pools <chain> <address>");
+      const r = await s.resolvePools(args[1]);
+      if (JSON_OUT) {
+        out(r);
+        break;
+      }
+      console.log(`evidence: ${r.evidence}`);
+      if (r.reason) console.log(`reason:   ${r.reason}`);
+      for (const p of r.pools.slice(0, 10)) {
+        const liq = p.liquidityUsd == null ? "?" : `$${Math.round(p.liquidityUsd).toLocaleString()}`;
+        console.log(`  ${p.dex.padEnd(12)} ${liq.padStart(14)}  ${p.pair}`);
+      }
+      if (!r.pools.length) console.log("  (no pools with liquidity found)");
+      break;
+    }
+
+    case "risk": {
+      const s = resolve(args[0]);
+      if (!args[1]) die("usage: oracle-scan risk <chain> <address>");
+      const r = await s.scoreRisk(args[1]);
+      if (JSON_OUT) {
+        out(r);
+        break;
+      }
+      console.log(`verdict: ${r.verdict}\n`);
+      for (const c of r.checks) {
+        console.log(`  ${c.result.padEnd(8)} ${c.check.padEnd(16)} ${c.detail ?? ""}`);
+      }
+      console.log(`\n${r.note}`);
+      break;
+    }
+
+    case "quote": {
+      const s = resolve(args[0]);
+      if (!args[1] || !args[2]) die("usage: oracle-scan quote <chain> <tokenIn> <tokenOut> [amountIn]");
+      if (!s.supports("quote")) {
+        die(
+          `${s.key} has no verified router, so quoting stays fail-closed.\n` +
+            "Add a venue with recorded provenance -- see docs/adding-a-chain.md.",
+        );
+      }
+      const amountIn = args[3] || (10n ** 18n).toString();
+      out(await s.quote({ tokenIn: args[1], tokenOut: args[2], amountIn }));
+      break;
+    }
+
+    case "sell": {
+      // The single most valuable check on a low-cap venue: can you get OUT?
+      const s = resolve(args[0]);
+      if (!args[1]) die("usage: oracle-scan sell <chain> <token> [amountIn]");
+      if (!s.supports("sellSimulation")) {
+        die(
+          `${s.key} has no verified router, so sell simulation is unavailable.\n` +
+            "Without it, treat every token on this chain as unproven for exit.",
+        );
+      }
+      const amountIn = args[2] || (10n ** 16n).toString();
+      const r = await s.sellSimulation({ token: args[1], amountIn });
+      if (JSON_OUT) {
+        out(r);
+        break;
+      }
+      console.log(`verdict:   ${r.verdict}`);
+      console.log(`reason:    ${r.reason ?? ""}`);
+      if (r.retentionBps != null) {
+        console.log(`retention: ${(r.retentionBps / 100).toFixed(2)}%`);
+      }
+      if (r.leg) console.log(`failed at: ${r.leg} leg`);
+      if (r.note) console.log(`\n${r.note}`);
+      break;
+    }
+
+    default:
+      console.log(
+        [
+          "oracle-scan -- chain scanner CLI",
+          "",
+          "  oracle-scan chains                              coverage matrix",
+          "  oracle-scan head  <chain>                       current block",
+          "  oracle-scan token <chain> <address>             ERC-20 identity",
+          "  oracle-scan pools <chain> <address>             pools by liquidity",
+          "  oracle-scan risk  <chain> <address>             structural risk checks",
+          "  oracle-scan quote <chain> <tIn> <tOut> [amt]    live exact-input quote",
+          "  oracle-scan sell  <chain> <token> [amt]         round-trip: can you exit?",
+          "",
+          "  <chain> is an id (8453) or key (base).  --json for machine output.",
+          "  quote/sell need a chain with a verified router (see: oracle-scan chains).",
+        ].join("\n"),
+      );
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (err) {
+  const s = args[0] ? (getScanner(Number(args[0])) || listScanners().find((x) => x.key === args[0])) : null;
+  die(s ? rpcHint(s, err) : String(err?.message || err));
+}

package/docs/adding-a-chain.md

@@ -0,0 +1,229 @@
+# Adding a chain
+
+Oracle treats a chain as **configuration**. You do not write an integration.
+
+## The short version
+
+```js
+import { registerCustomChain } from "@oracle-agent/oracle/scanner";
+
+registerCustomChain({
+  key: "mychain",
+  chainId: 7777,
+  name: "My Chain",
+  rpcEnv: ["MYCHAIN_RPC_URL"],
+  nativeCurrency: { symbol: "MYC", decimals: 18 },
+});
+```
+
+That chain now has block reads, native and ERC-20 balances, on-chain token
+resolution, log scanning, and structural risk checks. No code was written.
+
+```bash
+export MYCHAIN_RPC_URL=https://rpc.mychain.example
+oracle-scan head mychain
+```
+
+## Config fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `key` | yes | lowercase slug, used on the CLI |
+| `chainId` | yes | positive integer |
+| `name` | yes | display name |
+| `rpcEnv` | yes | env var names, `UPPER_SNAKE`. Never a literal URL |
+| `nativeCurrency` | no | `{ symbol, decimals }` |
+| `explorer` | no | base URL |
+| `dexscreenerSlug` | no | enables pool discovery — see below |
+| `venues` | no | verified routers/quoters — required for routing value |
+
+**RPC URLs live in the environment, never in config.** A repo carrying an endpoint
+is both a leak and a rate-limit problem for whoever else uses that key.
+
+## Why `dexscreenerSlug` matters
+
+Pool discovery goes through market data rather than walking a factory. A factory
+walk finds pools that *exist*; a trader needs pools with *liquidity*.
+
+The slug is DexScreener's own chain identifier — not the chain id, and not always
+the obvious name. If you don't know it, **leave it out**. Pool discovery then
+reports `UNAVAILABLE`, which is honest. A wrong slug silently returns another
+chain's pools, which is worse than no answer.
+
+## Adding venues (routing value)
+
+A chain with no verified venue is **fail-closed**: read and research work, routing
+value does not. That is a safe default, not a gap.
+
+To enable routing you must record *provenance*:
+
+```js
+venues: [
+  {
+    kind: "router",
+    address: "0x...",
+    verified: {
+      method: "eth_getCode + protocol /chains API",
+      source: "https://li.quest/v1/chains",
+      date: "2026-07-30",
+    },
+  },
+]
+```
+
+Validation **refuses** a venue without `verified`. This is not bureaucracy: the
+destination allowlist is the highest-leverage control in the system, and
+allowlisting a spoofed router makes every other guard irrelevant.
+
+### How to actually verify
+
+1. **Bytecode exists** — `eth_getCode` must return real code. `0x` means nothing is
+   deployed at that address on that chain.
+2. **The protocol's own API or docs** names that address, for that chain, today.
+   Query the source (e.g. LI.FI's `/v1/chains` returns each chain's official
+   `diamondAddress`) rather than trusting a blog post or a model's recollection.
+3. **Constructor-bound addresses match** — read `factory()`, `WETH9()` back off the
+   deployed contract and confirm they're what you expect.
+4. **Per chain, separately.** An address verified on Arbitrum is not verified on
+   Ethereum, even when the canonical deployment shares an address across chains.
+
+Record how and when. The audit trail has to outlive your session.
+
+## Capabilities
+
+Ten capabilities exist. The generic EVM scanner provides seven out of the box:
+
+| Capability | Generic? | Why |
+|---|---|---|
+| `blockNumber` | yes | standard RPC |
+| `nativeBalance` | yes | standard RPC |
+| `tokenBalance` | yes | ERC-20 is ERC-20 |
+| `resolveToken` | yes | reads metadata off the contract |
+| `resolvePools` | yes* | needs `dexscreenerSlug` |
+| `scanBlocks` | yes | chunked `eth_getLogs` |
+| `scoreRisk` | yes | structural checks |
+| `quote` | venue | needs a verified router |
+| `sellSimulation` | venue | needs a verified router |
+| `prepareUnsignedTx` | venue | needs a verified router |
+
+Calling an unimplemented capability **throws**, naming what is supported. It never
+returns `undefined` that a caller could mistake for "no result."
+
+## Enabling quote / sell / prepare
+
+Add a verified router plus two fields:
+
+```js
+{
+  key: "base",
+  chainId: 8453,
+  // ...
+  venueKind: "uniswap-v2",
+  wrappedNative: "0x4200000000000000000000000000000000000006",
+  venues: [{ kind: "router", address: "0x...", verified: { /* ... */ } }],
+}
+```
+
+`src/scanner/chains.config.mjs` ships **Base** wired this way as the reference. It
+gets all 10 capabilities; every other built-in stays at 7 and fail-closed until
+someone verifies a venue for it.
+
+What you get:
+
+- **`quote`** — live exact-input pricing via `getAmountsOut`
+- **`sellSimulation`** — a state-free round trip (buy then sell back) that catches
+  the honeypot signature: buy leg quotes fine, sell leg fails. This is the single
+  most valuable check on a low-cap venue, because most losses are not bad entries
+  but tokens that cannot be exited
+- **`prepareUnsignedTx`** — an **unsigned** swap with a `minOut` computed from the
+  live quote, a deadline, and an explicit `approve` step listed separately so
+  "approved" and "swapped" are never collapsed into one claim
+
+`scoreRisk` also upgrades automatically: with a router it reports real sellability
+instead of `UNKNOWN`.
+
+### The slippage ceiling is hard
+
+A supplied `slippageBps` is a **maximum**, capped at 100 bps. Above that,
+`prepareUnsignedTx` throws rather than widening:
+
+```
+slippageBps 250 exceeds the 100 bps ceiling. Block and requote or split
+the order -- do not widen the guard to force a fill.
+```
+
+A cap that yields under pressure is decoration.
+
+### V3 / V4 / custom quoters
+
+Two adapters ship:
+
+| `venueKind` | Requires | Prices via |
+|---|---|---|
+| `uniswap-v2` | `router` | `getAmountsOut` on the router |
+| `uniswap-v3` | `quoter` **and** `router` | `quoteExactInputSingle` on QuoterV2 |
+
+V3 is **not** V2 with different addresses: it has no `getAmountsOut`, prices through
+a separate Quoter contract, and needs an explicit fee tier per hop. Encoding a V3
+swap with V2 assumptions yields a transaction that reverts, or worse routes through
+the wrong pool. That is why they are sibling adapters.
+
+The V3 adapter searches all four fee tiers (100 / 500 / 3000 / 10000) and keeps the
+best. This is necessary, not a nicety — liquidity concentrates in one tier and which
+tier varies by pair and chain. On Arbitrum WETH→USDC the 500 tier returns ~2.4% more
+than the 100 tier; defaulting to 0.3% because it is the common choice silently
+misprices stable and exotic pairs alike.
+
+A V3 chain needs **both** a quoter and a router. A router alone stays fail-closed:
+it could encode a swap, but with no priced expectation to guard against — exactly
+the state that produces an unbounded fill.
+
+**V4 and custom-quoter venues still need their own adapter.** Some forks require an
+off-chain signed quote you cannot produce locally. Write a sibling module rather
+than bending an existing one; silently mis-encoding a swap is far worse than
+declaring the capability unsupported.
+
+### Verifying a venue: run the prober
+
+`scripts/verify-v3-venues.mjs` probes candidate addresses on every chain and prints
+a pass/fail with the live price it got:
+
+```bash
+node scripts/verify-v3-venues.mjs
+```
+
+**Codesize is not verification.** The canonical mainnet QuoterV2 address returns
+2109 bytes of bytecode on Base — it is *some* contract, just not a working quoter
+for that chain. A codesize check waves it through; the functional probe caught it
+and pointed at Base's real quoter (8273 bytes, prices WETH→USDC correctly).
+
+The rule: **a contract that correctly prices a pair you can sanity-check IS the
+thing you think it is.** Anything less is a guess with an address attached.
+
+## Honest evidence
+
+Every finding carries a label. Respect the distinction:
+
+- `LIVE` — read this call
+- `CACHED` — recent, within stated TTL
+- `STALE` — older than TTL; usable only with the caveat stated
+- `UNKNOWN` — we tried and could not determine it
+- `UNAVAILABLE` — this chain/provider cannot answer at all
+
+`UNKNOWN` and `UNAVAILABLE` are different facts. Collapsing them is how people end
+up sizing against stale reserves.
+
+Risk verdicts are coarse on purpose — `PASS` / `CAUTION` / `FAIL` / `UNKNOWN`. A
+score like "risk 62/100" invites trading a number nobody understands.
+
+**`UNKNOWN` is not `PASS`.** The generic scanner returns `UNKNOWN` for sellability
+because it cannot prove exitability without a verified router. A token is not
+tradeable until a round-trip sell simulation succeeds.
+
+## Contributing a chain upstream
+
+Append to `CHAIN_CONFIGS` in `src/scanner/chains.config.mjs` and open a PR. Tests
+already assert every built-in config validates and that none embeds an RPC URL, so
+CI will catch a malformed entry.
+
+If you add venues, put the verification method and date in the PR body.