@keelage/mcp 0.1.1

package/lib/holders.mjs

@@ -0,0 +1,67 @@
+// holders.mjs - the holder map for one token: top wallets with pools and contracts labeled, the burn share,
+// and the share held by smart accounts (EIP-7702 delegated EOAs, which is how the Robinhood app wallet reads).
+import { bsGet, BS_PACE_MS, sleep, getJson, rpcCall, isAddress, CHAIN, goplusRead } from './gate.mjs';
+import { blockscoutTop10 } from './calc.mjs';
+import { DISCLAIMER } from './render.mjs';
+
+const BURN = new Set(['0x0000000000000000000000000000000000000000', '0x000000000000000000000000000000000000dead', '0x0000000000000000000000000000000000000001']);
+const TOP_N = 20;
+
+// EIP-7702: an EOA whose code is the 23-byte delegation designator 0xef0100 || address.
+async function isSmartAccount(address) {
+  const code = String(await rpcCall('eth_getCode', [address, 'latest']) || '');
+  if (!/^0x[0-9a-fA-F]*$/.test(code)) return null;
+  return code.toLowerCase().startsWith('0xef0100');
+}
+
+export async function holdersFor(address, { withSmartAccounts = true } = {}) {
+  const raw = String(address || '').trim();
+  if (!isAddress(raw)) return { ok: false, address: raw, error: 'not a contract address (0x + 40 hex characters)', disclaimer: DISCLAIMER };
+  const a = raw.toLowerCase();
+  const tk = await bsGet(`/tokens/${a}`); await sleep(BS_PACE_MS);
+  if (tk?.__err) return { ok: false, address: a, error: `blockscout tokens: ${tk.__err}`, disclaimer: DISCLAIMER };
+  const hl = await bsGet(`/tokens/${a}/holders`); await sleep(BS_PACE_MS);
+  if (hl?.__err) return { ok: false, address: a, error: `blockscout holders: ${hl.__err}`, disclaimer: DISCLAIMER };
+  const supply = Number(tk.total_supply || 0);
+  const decimals = Number(tk.decimals || 18);
+  // Pool addresses: every DexScreener pair where this token is base or quote, plus GoPlus dex pairs.
+  const pairs = await getJson(`https://api.dexscreener.com/tokens/v1/${CHAIN}/${a}`);
+  const pools = new Set((Array.isArray(pairs) ? pairs : []).map((p) => String(p.pairAddress || '').toLowerCase()).filter(Boolean));
+  const gp = await goplusRead({ address: a, chain: CHAIN });
+  for (const p of gp?.dexPairs || []) pools.add(String(p).toLowerCase());
+  const items = Array.isArray(hl.items) ? hl.items : [];
+  const t10 = blockscoutTop10(items, [...pools], supply);
+  const rows = [];
+  let burnPct = 0;
+  for (const h of items.slice(0, TOP_N)) {
+    const addr = String(h.address?.hash || '').toLowerCase();
+    const pctSupply = supply ? +((Number(h.value || 0) / supply) * 100).toFixed(2) : null;
+    const isPool = pools.has(addr);
+    const isBurn = BURN.has(addr);
+    if (isBurn && pctSupply) burnPct += pctSupply;
+    rows.push({
+      address: addr, pctSupply, balance: supply ? +(Number(h.value || 0) / 10 ** decimals).toFixed(2) : null,
+      isContract: !!h.address?.is_contract, isPool, isBurn, name: h.address?.name || null, smartAccount: null,
+    });
+  }
+  // Smart-account check on the wallets only (contracts and pools are already labeled).
+  let smartPct = null, smartCount = null;
+  if (withSmartAccounts) {
+    smartPct = 0; smartCount = 0;
+    for (const r of rows) {
+      if (r.isContract || r.isPool || r.isBurn) continue;
+      r.smartAccount = await isSmartAccount(r.address);
+      if (r.smartAccount) { smartCount++; smartPct += r.pctSupply || 0; }
+    }
+    smartPct = +smartPct.toFixed(2);
+  }
+  return {
+    ok: true, address: a, chain: CHAIN, symbol: tk.symbol || null, name: tk.name || null,
+    holderCount: tk.holders_count != null ? Number(tk.holders_count) : null, totalSupply: supply ? +(supply / 10 ** decimals).toFixed(2) : null,
+    top10: { pctExPoolsAndContracts: t10.top10Pct, pctInclPools: t10.top10InclPct, largestWalletPct: t10.maxSinglePct, contracts: t10.contractsInTop10, pools: t10.poolsInTop10 },
+    burnPct: +burnPct.toFixed(2),
+    smartAccounts: withSmartAccounts ? { count: smartCount, pctSupply: smartPct, sampled: rows.filter((r) => !r.isContract && !r.isPool && !r.isBurn).length, note: 'EIP-7702 delegated accounts among the listed wallets; the Robinhood app wallet reads this way' } : null,
+    poolsKnown: [...pools], creator: gp?.creator || null, creatorPct: gp?.creatorPct ?? null,
+    holders: rows, listed: rows.length, readAt: new Date().toISOString(), disclaimer: DISCLAIMER,
+  };
+}

package/lib/io.mjs

@@ -0,0 +1,43 @@
+// io.mjs - the one place the library touches storage. Node reads and writes files. Another runtime (a hosted
+// function) installs its own store with the data files embedded and caches kept in memory.
+import { readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+
+let impl = {
+  read: (p) => readFileSync(p, 'utf8'),
+  write: (p, text) => writeFileSync(p, text),
+  list: (dir) => readdirSync(dir),
+  mkdir: (dir) => mkdirSync(dir, { recursive: true }),
+};
+export const io = {
+  read: (p) => impl.read(p),
+  write: (p, text) => impl.write(p, text),
+  list: (dir) => impl.list(dir),
+  mkdir: (dir) => impl.mkdir(dir),
+};
+export function setIO(next) { impl = { ...impl, ...next }; }
+
+// An in-memory store. `files` maps a path suffix ('data/thresholds.json') to its text or parsed JSON; a read matches
+// on that suffix, a write lands in memory, a listing names the embedded and written entries of that directory.
+export function memoryIO(files = {}) {
+  const norm = (p) => String(p).replace(/\\/g, '/');
+  const mem = new Map();
+  const text = (v) => (typeof v === 'string' ? v : JSON.stringify(v));
+  return {
+    read: (p) => {
+      const n = norm(p);
+      if (mem.has(n)) return mem.get(n);
+      for (const k of Object.keys(files)) if (n === k || n.endsWith('/' + k)) return text(files[k]);
+      const e = new Error(`ENOENT: no such file, ${p}`); e.code = 'ENOENT'; throw e;
+    },
+    write: (p, t) => { mem.set(norm(p), String(t)); },
+    list: (dir) => {
+      const d = norm(dir).replace(/\/$/, '');
+      const out = new Set();
+      const consider = (k) => { const i = k.lastIndexOf('/'); const kd = i < 0 ? '' : k.slice(0, i); if (d === kd || d.endsWith('/' + kd)) out.add(k.slice(i + 1)); };
+      Object.keys(files).forEach(consider);
+      for (const k of mem.keys()) consider(k);
+      return [...out];
+    },
+    mkdir: () => {},
+  };
+}

package/lib/jev.mjs

@@ -0,0 +1,104 @@
+// jev.mjs - Jev (TypeSafe AI) probabilities as CONTEXT on a verdict.
+//
+// Display only. It never admits, blocks, sizes or orders a token. Jev answers a typed question about a
+// state with a calibrated probability; the three answers ride on the verdict so they can be tested against
+// outcomes like every other stored fact.
+//
+//   jevJudge(c)  -> { up7d, halve7d, organicX, model, ms, tokens, at } | null (no key) ; never throws
+//   jevState(c)  -> the state sent: the token's facts at scan time only. No outcome.
+//   jevLine(j)   -> the text line for the card (pure)
+//
+// Key: TYPESAFE_API_KEY. Cache: <state>/jev-cache.json per token, JEV_TTL_H (6h); failures are never cached.
+// Import-safe: no network at import, no top-level await, no argv reads.
+import { io } from './io.mjs';
+import { statePath } from './state.mjs';
+import { line } from './calc.mjs';
+
+export const JEV_TTL_H = Number(process.env.JEV_TTL_H || 6);
+const URL_ = 'https://api.typesafe.ai/v1/systemone';
+const MODEL = process.env.JEV_MODEL || 'jev-latest';
+
+const keyOf = (c) => `${c.chain}:${String(c.address || '').toLowerCase()}`;
+const readCache = () => { try { return JSON.parse(io.read(statePath('jev-cache.json'))); } catch { return {}; } };
+const writeCache = (v) => { try { io.write(statePath('jev-cache.json'), JSON.stringify(v, null, 1)); } catch {} };
+const num = (v, d = 2) => (v == null || !Number.isFinite(Number(v)) ? null : +Number(v).toFixed(d));
+const clip = (s, n) => (s == null ? null : String(s).slice(0, n));
+
+/** What Jev judges: the token as the scan saw it. Unknown stays null, never a placeholder zero. */
+export function jevState(c) {
+  const g = c.gates || {}, x = c.xMeta || null;
+  return {
+    coin: { symbol: clip(c.symbol, 20), chain: c.chain ?? null, ageDays: num(c.ageDays, 1), tier: c.tier ?? null },
+    market: { priceUsd: c.priceUsd ?? null, mcapUsd: num(c.mcapUsd, 0), liquidityUsd: num(c.liqUsd, 0), volume24hUsd: num(c.vol24, 0),
+      turnover24h: c.vol24 != null && c.mcapUsd > 0 ? num(c.vol24 / c.mcapUsd, 3) : null, volumeLastHourUsd: num(c.volH1, 0),
+      priceChange1hPct: num(c.priceChange1), priceChange6hPct: num(c.priceChange6), priceChange24hPct: num(c.priceChange24),
+      buysLastHour: c.h1Buys ?? null, sellsLastHour: c.h1Sells ?? null, medianDailyRange14dPct: num(c.adr14, 1), daysMoving14d: c.moveDays14 ?? null },
+    location: { pctBelowAllTimeHigh: num(c.athDrawdown, 1), pctAbove30dLow: num(c.distFromLow30Pct, 1), baseBand: c.baseEntry?.band ?? c.baseEntry ?? null, entryBlock: c.entryBlock || null },
+    structure: { structuralGatePass: g.pass ?? null, top10HoldersPct: num(g.top10Pct, 1), holderCount: g.holderCount ?? null, creatorPct: num(g.creatorPct, 1),
+      lpLockedOrBurned: g.lpLockedOrBurned ?? null, ownerRenounced: g.ownerRenounced ?? null, sellsClearing: g.sellsClear ?? null, honeypot: g.honeypot ?? null, liquidityDrop30dPct: num(g.liqDropPct, 1), failReasons: (g.reasons || []).slice(0, 5) },
+    communityTakeoverClaims: c.takeoverClaim ? { count: c.takeoverClaim.count ?? null, latest: c.takeoverClaim.latest ?? null } : null,
+    xLast24h: x && x.posts24 != null ? { posts: x.posts24, accounts: x.accounts24 ?? null, accountsOver10kFollowers: x.accountsBig ?? null, views: x.views24 ?? null,
+      copyPasteSharePct: x.copyPasteShare ?? null, tone: x.tone ?? null, postsNamingThisChain: x.chainMentions ?? null, postsNamingAnotherChain: x.otherChainMentions ?? null,
+      largestAccounts: (x.bigAccounts || []).slice(0, 5).map((b) => ({ handle: b.handle, followers: b.followers, aboutAnotherChain: b.otherChain ?? null })), meta: clip(x.meta, 120) } : null,
+    note: 'A post-abandonment memecoin with an existing community, being judged for a swing entry. Unknown = not readable, not zero.',
+  };
+}
+
+const QUESTIONS = {
+  up7d: { type: 'noul', instructions: 'Seven days from now, will this coin trade ABOVE its current price?',
+    criteria: { true: 'Attention is building on real accounts, volume and buyers are rising from a base well below the ATH, the structure is clean and liquidity holds.',
+      false: 'A stale or coordinated campaign, sellers outnumber buyers, mid-dump or at the base with nothing moving, structural flags, liquidity thinning.' } },
+  halve7d: { type: 'noul', instructions: 'Within the next seven days, will this coin lose HALF or more of its current price?',
+    criteria: { true: 'Fragile: thin liquidity for the volume, a top-heavy holder base, a fading or paid X campaign, a recent pump that is unwinding.',
+      false: 'Deep liquidity, spread holders, steady organic attention, price already sitting at a long base.' } },
+  organicX: { type: 'noul', instructions: 'Is the X attention on this coin organic rather than a paid or coordinated campaign?',
+    criteria: { true: 'Many distinct accounts writing in their own words, larger profiles engaging, a low copy-paste share, posts about this chain\'s token.',
+      false: 'A high share of repeated templates, a few accounts producing most posts, engagement farming, posts mostly about another chain\'s token of the same name.' } },
+};
+
+/** The fresh cache entry for a token, or null. */
+export function cachedJev(c) { const hit = readCache()[keyOf(c)]; return hit && hit.v === 1 && Date.now() - Date.parse(hit.at || 0) < JEV_TTL_H * 3600_000 ? hit : null; }
+
+/** One Jev call for a token, cached JEV_TTL_H. null without a key. Never throws. */
+export async function jevJudge(c, { log = console.error, force = false, timeoutMs = Number(process.env.JEV_TIMEOUT_MS || 10_000) } = {}) {
+  const key = process.env.TYPESAFE_API_KEY; if (!key) return null;
+  const k = keyOf(c), cache = readCache(), hit = cache[k];
+  if (!force && hit && hit.v === 1 && Date.now() - Date.parse(hit.at || 0) < JEV_TTL_H * 3600_000) return hit;
+  const t0 = Date.now(); let r, j;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      r = await fetch(URL_, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` }, body: JSON.stringify({ model: MODEL, state: jevState(c), questions: QUESTIONS }), signal: AbortSignal.timeout(timeoutMs) });
+      if (r.status === 429 || r.status === 529) { await new Promise((res) => setTimeout(res, 2000 * (attempt + 1))); continue; }
+      j = await r.json(); break;
+    } catch (e) { log(`[jev] ${c.symbol}: ${e.message}`); return hit || null; }
+  }
+  if (!r?.ok || !j?.answers) { log(`[jev] ${c.symbol}: status ${r?.status}${j?.error ? ' ' + JSON.stringify(j.error).slice(0, 120) : ''}`); return hit || null; } // provider error, never cached
+  const p = (q) => (typeof j.answers[q]?.noul === 'number' ? +j.answers[q].noul.toFixed(3) : null);
+  const out = { v: 1, at: new Date().toISOString(), up7d: p('up7d'), halve7d: p('halve7d'), organicX: c.xMeta && c.xMeta.posts24 != null ? p('organicX') : null, model: j.model || MODEL, ms: Date.now() - t0, tokens: j.usage?.input_tokens ?? null };
+  const fresh = readCache(); fresh[k] = out; writeCache(fresh);
+  return out;
+}
+
+// Calibration from a backtest of 423 past alerts against their actual 7-day return (24 Sep 2026): halve 7d is
+// calibrated and separates (Spearman -0.47, monotone bands); up 7d does not (0.09-0.11), so no words are put on
+// it. Bands are frozen with their n. Observation only.
+const CUTS = line('jev.halveBands');
+export const HALVE_BANDS = [ // [lo, hi, label, n, halvedPct, medianPct]
+  [0, CUTS[0], 'holding up', 29, 0, -4], [CUTS[0], CUTS[1], 'leans safe', 67, 1, -7], [CUTS[1], CUTS[2], 'coin flip', 171, 32, -26], [CUTS[2], CUTS[3], 'likely to bleed', 120, 52, -51], [CUTS[3], 1.01, 'likely dead', 36, 83, -83],
+];
+export function jevRead(j) {
+  if (!j || j.halve7d == null) return null;
+  const b = HALVE_BANDS.find(([lo, hi]) => j.halve7d >= lo && j.halve7d < hi); if (!b) return null;
+  const [, , label, n, halved, median] = b;
+  return { label, n, halved, median, words: `${label} - at this level ${halved}% of ${n} past alerts halved within 7d (median ${median >= 0 ? '+' : ''}${median}%)` };
+}
+
+/** The card lines. Pure; `esc` is an optional output escaper (identity for plain text). */
+export function jevLine(j, esc = (s) => String(s ?? '')) {
+  if (!j || (j.up7d == null && j.halve7d == null)) return null;
+  const pc = (v) => (v == null ? 'n/a' : `${Math.round(100 * v)}%`);
+  const parts = [`Jev: up 7d ${pc(j.up7d)}`, `halve 7d ${pc(j.halve7d)}`];
+  if (j.organicX != null) parts.push(`X organic ${pc(j.organicX)}`);
+  const r = jevRead(j);
+  return esc(parts.join(' | ')) + (r ? '\n' + esc(`Jev read: ${r.words}. Observation only, not a gate.`) : esc(' (context only)'));
+}

package/lib/record.mjs

@@ -0,0 +1,19 @@
+// record.mjs - the published track record, as data. Every figure carries its date and n.
+import { io } from './io.mjs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { DISCLAIMER } from './render.mjs';
+import { THRESHOLDS } from './calc.mjs';
+
+// A bundled runtime has no import.meta.url; paths then only serve as keys for the embedded store.
+const HERE = (() => { try { return dirname(fileURLToPath(import.meta.url)); } catch { return '/keelage/' + 'lib'; } })();
+let _rec;
+export function trackRecord({ study = null } = {}) {
+  if (_rec === undefined) _rec = JSON.parse(io.read(join(HERE, '..', 'data', 'track-record.json')));
+  const out = { ...(_rec), rules: THRESHOLDS, disclaimer: DISCLAIMER };
+  if (study) {
+    const s = (out.studies || []).find((x) => x.key === study);
+    return s ? { ...s, disclaimer: DISCLAIMER } : { ok: false, error: `no study "${study}"`, studies: (out.studies || []).map((x) => x.key), disclaimer: DISCLAIMER };
+  }
+  return out;
+}

package/lib/render.mjs

@@ -0,0 +1,56 @@
+// render.mjs - the JSON shape of a scan. One object, fixed keys, null for unknown, never a placeholder zero.
+import { baseBand, rulesetOf } from './calc.mjs';
+import { links } from './format.mjs';
+import { sizeFor, verdictFor } from './gate.mjs';
+import { jevRead } from './jev.mjs';
+
+export const DISCLAIMER = 'Research only, not financial advice.';
+const n = (v) => (v === undefined ? null : v);
+
+export function renderScanJson(res) {
+  if (!res?.ok) {
+    return { ok: false, address: n(res?.address), chain: 'robinhood', error: n(res?.err) || 'unknown error', verdict: null, scannedAt: new Date().toISOString(), disclaimer: DISCLAIMER };
+  }
+  const c = res.c, g = c.gates || {}, v = c.verdict || verdictFor(c), s = sizeFor(c), rs = rulesetOf(c);
+  const dist = c.baseEntry?.distPct ?? c.distFromLow30Pct ?? null;
+  return {
+    ok: true,
+    address: c.address, chain: c.chain, symbol: n(c.symbol), name: n(c.name), scannedAt: c.scannedAt,
+    // The verdict is a policy under a named, dated ruleset: `overrides` lists the lines the caller changed (empty for a preset).
+    verdict: { key: v.key, head: v.head, why: v.why, status: 'beta', ruleset: { name: rs.name, date: rs.date, overrides: [...rs.overrides], version: rs.date, handSetLines: rs.handSetLines, derivedLines: rs.derivedLines, note: 'The facts in this answer are measured and timestamped. The verdict is a policy over them under this ruleset and is in beta.' } },
+    tier: n(c.tier), actionable: !!c.actionable, entryBlock: n(c.entryBlock), score: n(c.score),
+    size: { usd: s.sizeUsd, onePctOfPoolUsd: s.onePctOfPoolUsd, tierCapUsd: s.tierCapUsd, rule: 'lower of 1% of pool and the tier cap, only when entry-eligible' },
+    market: {
+      priceUsd: n(c.priceUsd), liquidityUsd: n(c.liqUsd), marketCapUsd: n(c.mcapUsd), volume24hUsd: n(c.vol24),
+      buys24h: n(c.buys24), sells24h: n(c.sells24), priceChange24hPct: n(c.priceChange24), ageDays: n(c.ageDays),
+      pairAddress: n(c.pairAddress), dexId: n(c.dexId), quoteSymbol: n(c.quoteSymbol),
+    },
+    location: {
+      pctBelowAth: n(c.athDrawdown), pctAbove30dLow: dist, baseBand: baseBand(dist, rs).label,
+      ath: n(c.ath), low30: n(c.low30), medianDailyRange14dPct: n(c.adr14), daysMoving14d: n(c.moveDays14),
+    },
+    structure: {
+      pass: n(g.pass), unverified: !!g.gateErr, providerError: n(g.gateErr), reasons: g.reasons || [], caps: g.caps || [],
+      source: n(g.source), verifiedSource: n(g.verified), contractName: n(g.contractName), implementationName: n(g.implName), proxyType: n(g.proxyType),
+      creator: n(g.creator), template: g.template ? { key: g.template, verdict: n(g.templateVerdict), matchedBy: n(g.templateBy) } : null,
+      privileges: Object.keys(g.privileges || {}).filter((k) => k !== 'live'), livePrivilege: !!g.privileges?.live,
+      ownerRenounced: n(g.ownerRenounced), ownerAddress: n(g.ownerAddress),
+      transferTaxCode: n(g.taxCode), taxIdentifierHits: n(g.taxHits), reflectionIdentifierHits: n(g.reflectHits),
+      sellsClearing24h: n(g.sellsClear), liquidityDropPct: n(g.liqDropPct), liquidityHistoryDays: n(g.liqPoints),
+    },
+    holders: {
+      count: n(g.holderCount), top10Pct: n(g.top10Pct), top10Source: n(g.top10Source), top10InclPoolsPct: n(g.top10RawPct),
+      largestWalletPct: n(g.maxSinglePct), contractsInTop10: n(g.contractsInTop10), poolsInTop10: n(g.poolAcctsInTop10), creatorPct: n(g.creatorPct),
+    },
+    goplus: g.goplusErr ? { record: false, note: g.goplusErr } : {
+      record: true, honeypot: n(g.honeypot), buyTax: n(g.buyTax), sellTax: n(g.sellTax), mintable: n(g.mintable), pausable: n(g.pausable),
+      lpMode: n(g.lpMode), lpHolders: n(g.lpHolders), topLpPct: n(g.topLpPct), creatorLpPct: n(g.creatorLpPct), lpLockedOrBurned: n(g.lpLockedOrBurned),
+    },
+    takeoverClaim: c.takeoverClaim ? { count: c.takeoverClaim.count, latest: c.takeoverClaim.latest, note: 'caution: historically the worst-performing bucket' } : null,
+    discoveryShape: n(c.shapeNote),
+    x: n(c.xMeta),
+    jev: c.jev ? { halve7d: n(c.jev.halve7d), up7d: n(c.jev.up7d), organicX: n(c.jev.organicX), read: jevRead(c.jev), model: n(c.jev.model), at: n(c.jev.at), note: 'Context only. Never a gate, never a rank key. The halve-7d band is calibrated (423 alerts, 24 Sep 2026); up-7d is not and carries no words.' } : null,
+    links: links(c.address),
+    disclaimer: DISCLAIMER,
+  };
+}

package/lib/state.mjs

@@ -0,0 +1,17 @@
+// state.mjs - where caches live. One directory, created on first use, overridable with KEELAGE_STATE_DIR.
+import { io } from './io.mjs';
+import { homedir, tmpdir } from 'os';
+import { join } from 'path';
+
+function pick() {
+  if (process.env.KEELAGE_STATE_DIR) return process.env.KEELAGE_STATE_DIR;
+  const home = homedir();
+  return home ? join(home, '.cache', 'keelage') : join(tmpdir(), 'keelage');
+}
+export const STATE_DIR = pick();
+let made = false;
+export function stateDir() {
+  if (!made) { try { io.mkdir(STATE_DIR); } catch {} made = true; }
+  return STATE_DIR;
+}
+export const statePath = (name) => join(stateDir(), name);

package/lib/template.mjs

@@ -0,0 +1,22 @@
+// template.mjs - which launcher template a contract came from, and what the ABI and source say on their own.
+import { contractFacts, isAddress, CHAIN, templates } from './gate.mjs';
+import { DISCLAIMER } from './render.mjs';
+
+export async function templateFor(address) {
+  const raw = String(address || '').trim();
+  if (!isAddress(raw)) return { ok: false, address: raw, error: 'not a contract address (0x + 40 hex characters)', disclaimer: DISCLAIMER };
+  const a = raw.toLowerCase();
+  const f = await contractFacts(a);
+  if (f.err) return { ok: false, address: a, error: f.err, disclaimer: DISCLAIMER };
+  const reg = templates();
+  const t = (reg?.templates || []).find((x) => x.key === f.template.key) || null;
+  return {
+    ok: true, address: a, chain: CHAIN, symbol: f.tokenSymbol, name: f.tokenName,
+    template: { key: f.template.key, verdict: f.template.verdict, matchedBy: f.template.by || null, feeModel: f.template.feeModel || null, note: t?.note || f.template.note || null },
+    contract: { verifiedSource: f.verified, verifiedAt: f.verifiedAt, compiler: f.compiler, contractName: f.contractName, implementationName: f.implName, implementationAddress: f.implAddr, proxyType: f.proxyType, creator: f.creator, functionCount: f.fns.length },
+    privileges: Object.entries(f.priv).filter(([k, v]) => v && k !== 'live').map(([k]) => k), livePrivilege: !!f.priv.live,
+    taxCode: { taxIdentifierHits: f.tax.taxHits, reflectionIdentifierHits: f.tax.reflectHits, present: f.tax.taxCode, countsAgainst: f.priv.feeSetter || (f.tax.taxCode && f.template.feeModel !== 'uniswap-pool-fee') },
+    registry: { version: reg?.version || null, templates: (reg?.templates || []).map((x) => ({ key: x.key, verdict: x.verdict })) },
+    readAt: new Date().toISOString(), disclaimer: DISCLAIMER,
+  };
+}

package/lib/templates.json

@@ -0,0 +1,100 @@
+{
+ "version": "2026-09-09",
+ "note": "Robinhood Chain (4663) launcher templates, judged once from the ABI and verified source of a 384-contract census. A token inherits its template's verdict; an unregistered template is judged by ABI and source alone and rendered as unregistered. verdict: clean = no live privilege, no transfer tax (fee words are Uniswap pool-fee reads); exclude = not a memecoin candidate; review = resolve the implementation and judge its ABI at run time.",
+ "templates": [
+  {
+   "key": "pons-launcher",
+   "verdict": "clean",
+   "feeModel": "uniswap-pool-fee",
+   "match": {
+    "creators": [
+     "0x0c37a24F5D23A486FA692d1500881d698B1F77a4",
+     "0xA5aAb3F0c6EeadF30Ef1D3Eb997108E976351feB",
+     "0x3711ceA4feaDE896C913C68F01Eda97Cb06D1A42",
+     "0xdD89f26beA3916233d002D1189F973B78D38aA70",
+     "0x2bA793Fd69Bf251Fd1Af90b576bE8B9fA6Be46DB"
+    ],
+    "contractNames": [
+     "PonsLauncherToken",
+     "PonsV2LauncherToken",
+     "LemonLauncherToken"
+    ]
+   },
+   "note": "PonsLaunchFactory / PonsV2LaunchDeployer / Lemon fork. No owner, no setters; poolFee/fee() are Uniswap V3 pool-tier reads, not a transfer tax; maxTxBps/maxWalletBps anti-whale limits for restrictionBlocks after launch. 141 tokens in the census, -57% median since first sight: population quality, not a rug vector."
+  },
+  {
+   "key": "launchtoken",
+   "verdict": "clean",
+   "feeModel": "uniswap-pool-fee",
+   "match": {
+    "creators": [
+     "0x98De89729dea2Df7739802C2D367D07dE926985d",
+     "0xD09639274b0E0A1a9586F7756ccFe134Cc525d09",
+     "0xD9eC2db5f3D1b236843925949fe5bd8a3836FCcB"
+    ],
+    "contractNames": [
+     "LaunchToken"
+    ]
+   },
+   "note": "Factory 0xD9eC2db5 (unnamed on Blockscout). Same ABI shape as Pons minus setInitialBuyRecipient. 61 tokens, -39% median."
+  },
+  {
+   "key": "uerc20-pools-trade",
+   "verdict": "clean",
+   "match": {
+    "creators": [
+     "0x000000e200088D55C39a11F609E5F667729ad49b"
+    ],
+    "contractNames": [
+     "UERC20"
+    ]
+   },
+   "note": "UERC20Factory (Pools Trade). No owner, no mint, permit + tokenURI only. 16 tokens."
+  },
+  {
+   "key": "robinhood-stock",
+   "verdict": "exclude",
+   "match": {
+    "creators": [
+     "0x4783C67b63dE2B358Ac5951a7D41F47A38F3C046"
+    ],
+    "implNames": [
+     "Stock"
+    ],
+    "contractNames": [
+     "BeaconProxy"
+    ]
+   },
+   "note": "Robinhood's tokenized equities (NVDA, SPY, ...): eip1967 beacon proxies to the Stock implementation with registry-controlled mint/burn/pause. Not a memecoin candidate: excluded as a class, never gated."
+  },
+  {
+   "key": "doppler",
+   "verdict": "clean",
+   "match": {
+    "creators": [
+     "0x1B37D3a72082029c44B35B604Ea473617580b69a"
+    ],
+    "implNames": [
+     "DopplerERC20V1"
+    ]
+   },
+   "note": "DopplerERC20V1Factory: eip1167 minimal proxies (token unverified) to a verified DopplerERC20V1 implementation. Owner exists (ownership handover) but no mint, pause, blacklist or fee setter; balance limit + lockPool + vesting. Judged from the implementation ABI. 32 tokens, -29% median."
+  },
+  {
+   "key": "party",
+   "verdict": "clean",
+   "match": {
+    "creators": [
+     "0x626C3d09B65bF5d1D40E0D5F25e19fa49783B3D4"
+    ],
+    "contractNames": [
+     "PartyToken"
+    ]
+   },
+   "note": "3 tokens, 11 functions, no privileges."
+  }
+ ],
+ "excludeImplNames": [
+  "Stock"
+ ]
+}