@keelage/mcp 0.1.1

package/lib/gate.mjs

@@ -0,0 +1,638 @@
+// gate.mjs - the Robinhood Chain structural pass, sizing tier, entry test, score and verdict for one token.
+//
+// Import-safe: no network at import, no top-level await, no argv reads. State it touches: the OHLCV cache
+// (<state>/ohlcv-cache.json, 6h TTL for ATH and 30-day low). Liquidity history for the "liquidity intact"
+// clause is injected through setLiquidityHistory(); without it the clause reads "not yet judgeable".
+//
+// Vocabulary, fixed: score ranks, it never admits; unknown facts cap size (caps[]); only evidence blocks (reasons[]).
+
+import { io } from './io.mjs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { evmTop10, tierFromTop10, goplusUnindexed, lpModeOf, lpStats, abiPrivileges, taxCodeScan, resolveTemplate, liqDrawdown, blockscoutTop10, line, THRESHOLDS, DEFAULT_RULESET, resolveRuleset, rulesetOf, RulesetError } from './calc.mjs';
+export { THRESHOLDS, DEFAULT_RULESET, resolveRuleset, rulesetOf, RulesetError };
+import { statePath } from './state.mjs';
+import { tokenCard, keyNorm } from './format.mjs';
+import { xMeta } from './x-meta.mjs';
+import { jevJudge } from './jev.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'; } })();
+export const CHAIN = 'robinhood';
+export const CHAIN_ID = '4663';
+
+// ---------- Config ----------
+// Market shape of the post-abandonment revival thesis: what discovery goes looking for. Informational on
+// a single scan; a token outside the shape is still judged.
+export const DISCOVERY_SHAPE = {
+  minAgeDays: 14,          // paid attention on a token this old = revival-shaped, not launch hype
+  minAgeDaysClaimed: 5,    // an explicit paid takeover claim replaces age as proof
+  maxAgeDays: 400,
+  minLiqUsd: 5_000,        // below = untradeable
+  maxLiqUsd: 500_000,      // above = not an early revival
+  minMcapUsd: 10_000,
+  maxMcapUsd: 5_000_000,   // beyond = the revival already happened
+};
+export const GATE_CFG = {
+  creatorMaxPct: line('deployer.max'), // deployer still holding more than this = not exited
+  goplusChainId: CHAIN_ID,
+};
+export const GT_NETWORK = 'robinhood';
+
+// 0x + 40 hex = a contract address on Robinhood Chain. Anything else is unjudgeable, never a verdict.
+export function isAddress(a) { return /^0x[0-9a-fA-F]{40}$/.test(String(a || '').trim()); }
+
+export const OHLCV_CACHE_PATH = () => statePath('ohlcv-cache.json');
+export const readJsonSafe = (p) => { try { return JSON.parse(io.read(p)); } catch { return {}; } };
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export { keyNorm };
+
+// Optional CoinGecko Pro routing. With CG_PRO_API_KEY unset the URL and headers are untouched.
+const CG_PRO_API_KEY = process.env.CG_PRO_API_KEY || '';
+function proRoute(url) {
+  if (!CG_PRO_API_KEY) return { url, headers: { accept: 'application/json' } };
+  const headers = { accept: 'application/json', 'x-cg-pro-api-key': CG_PRO_API_KEY };
+  if (url.startsWith('https://api.geckoterminal.com/api/v2/')) {
+    return { url: url.replace('https://api.geckoterminal.com/api/v2/', 'https://pro-api.coingecko.com/api/v3/onchain/'), headers };
+  }
+  if (url.startsWith('https://api.coingecko.com/api/v3/')) {
+    return { url: url.replace('https://api.coingecko.com/api/v3/', 'https://pro-api.coingecko.com/api/v3/'), headers };
+  }
+  return { url, headers };
+}
+
+export async function getJson(rawUrl, tries = 3) {
+  const { url, headers } = proRoute(rawUrl);
+  for (let i = 0; i < tries; i++) {
+    try {
+      const r = await fetch(url, { headers });
+      if (r.status === 429) { await sleep(5000 * (i + 1)); continue; }
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      return await r.json();
+    } catch (e) {
+      if (i === tries - 1) return { __err: String(e.message || e) };
+      await sleep(1500 * (i + 1));
+    }
+  }
+  // A 429 on every try falls out of the loop. Fail loudly and let callers decide.
+  return { __err: `429 exhausted after ${tries} tries` };
+}
+
+// ---------- Paid takeover claim (DexScreener orders) ----------
+// Rendered as a caution where present. It never scores: claimed tokens were the worst-performing bucket.
+export async function checkClaim(c) {
+  const d = await getJson(`https://api.dexscreener.com/orders/v1/${c.chain}/${c.address}`);
+  const claims = (d?.orders || []).filter((o) => o.type === 'communityTakeover' && o.status === 'approved');
+  if (claims.length) {
+    c.takeoverClaim = { count: claims.length, latest: new Date(Math.max(...claims.map((o) => o.paymentTimestamp))).toISOString().slice(0, 10) };
+  }
+  return !!claims.length;
+}
+
+// ---------- GoPlus: corroboration only ----------
+// Where it has a record it supplies honeypot, mintable, owner, creator share and LP-holder statistics.
+// Where it has none, the on-chain pass still decides. GoPlus indexes this chain lazily: one re-ask after a
+// pause, then "no record". The comma-separated batch form returns only already-cached tokens, so never batch.
+export async function goplusRead(c) {
+  const url = `https://api.gopluslabs.io/api/v1/token_security/${GATE_CFG.goplusChainId}?contract_addresses=${c.address}`;
+  let d = await getJson(url);
+  let r = d?.result?.[c.address.toLowerCase()];
+  if (!r && !d?.__err) { await sleep(3000); d = await getJson(url); r = d?.result?.[c.address.toLowerCase()]; if (r) c._goplusLazy = true; }
+  if (!r) return { goplusErr: `goplus: ${d?.__err || 'no record after 2 asks (lazy index)'}` };
+  if (goplusUnindexed(r)) return { goplusErr: 'goplus: partial record (no honeypot/holders/LP data)' };
+  const num = (x) => (x === undefined || x === null || x === '' ? null : Number(x));
+  const { top10Pct, top10RawPct, poolAcctsInTop10 } = evmTop10(r);
+  const lpMode = lpModeOf(r);
+  const lp = lpStats(r);
+  const lpLockedOrBurned = lp.lockedOrBurned;
+  const creatorRaw = num(r.creator_percent);
+  const creatorPct = creatorRaw === null ? null : +(creatorRaw * 100).toFixed(2);
+  const buyTax = num(r.buy_tax), sellTax = num(r.sell_tax);
+  return {
+    honeypot: num(r.is_honeypot), buyTax, sellTax,
+    mintable: num(r.is_mintable), ownerRenounced: r.owner_address === '0x0000000000000000000000000000000000000000' || r.owner_address === '',
+    holderCount: num(r.holder_count),
+    pausable: num(r.transfer_pausable), lpLockedOrBurned,
+    lpMode, lpHolders: lp.lpHolders, topLpPct: lp.topLpPct, creatorLpPct: lp.creatorLpPct,
+    taxKnown: buyTax !== null && sellTax !== null,
+    slippageModifiable: num(r.slippage_modifiable), antiWhale: num(r.is_anti_whale), tradingCooldown: num(r.trading_cooldown),
+    goplusLazy: !!c._goplusLazy,
+    top10Pct, top10RawPct, poolAcctsInTop10,
+    creator: r.creator_address || null, creatorPct,
+    ownerAddress: r.owner_address || null,
+    dexPairs: (r.dex || []).map((x) => x.pair).filter(Boolean),
+  };
+}
+
+// ---------- Blockscout (robinhoodchain.blockscout.com, API v2) ----------
+// The host sits behind a challenge that 403s bare API clients on most paths; a full browser header set
+// gets 200. BLOCKSCOUT_IP pins the A record where a resolver misdirects this host.
+export const BS_HOST = 'robinhoodchain.blockscout.com';
+const BS_HEADERS = {
+  'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36',
+  Accept: 'application/json, text/plain, */*', 'Accept-Language': 'en-US,en;q=0.9',
+  Referer: `https://${BS_HOST}/`, Origin: `https://${BS_HOST}`,
+  'sec-ch-ua': '"Chromium";v="128", "Not;A=Brand";v="24", "Google Chrome";v="128"', 'sec-ch-ua-mobile': '?0', 'sec-ch-ua-platform': '"macOS"',
+  'sec-fetch-dest': 'empty', 'sec-fetch-mode': 'cors', 'sec-fetch-site': 'same-origin',
+};
+export const BS_PACE_MS = 600;
+async function bsGetRaw(path) {
+  const ip = process.env.BLOCKSCOUT_IP || '';
+  if (ip) { const { default: https } = await import('node:https'); return bsGetPinned(path, ip, https); }
+  try {
+    const r = await fetch(`https://${BS_HOST}/api/v2${path}`, { headers: BS_HEADERS, signal: AbortSignal.timeout(20_000) });
+    if (r.status !== 200) return { __err: `http ${r.status}` };
+    try { return await r.json(); } catch { return { __err: 'bad json' }; }
+  } catch (e) { return { __err: (e && e.name === 'TimeoutError' ? 'timeout' : String(e && e.message || e)).slice(0, 60) }; }
+}
+// With BLOCKSCOUT_IP set the request is pinned to that address over node's https (a Node-only path).
+function bsGetPinned(path, ip, https) {
+  return new Promise((resolve) => {
+    const req = https.request({
+      host: BS_HOST, servername: BS_HOST, path: `/api/v2${path}`, method: 'GET', headers: BS_HEADERS, timeout: 20_000,
+      ...(ip ? { lookup: (h, o, cb) => cb(null, [{ address: ip, family: 4 }]) } : {}),
+    }, (res) => {
+      let b = ''; res.on('data', (ch) => (b += ch));
+      res.on('end', () => { if (res.statusCode !== 200) return resolve({ __err: `http ${res.statusCode}` }); try { resolve(JSON.parse(b)); } catch { resolve({ __err: 'bad json' }); } });
+    });
+    req.on('timeout', () => req.destroy(new Error('timeout')));
+    req.on('error', (e) => resolve({ __err: String(e.message || e).slice(0, 60) }));
+    req.end();
+  });
+}
+// Circuit breaker. After BS_TRIP_AFTER consecutive 5xx / timeouts the circuit opens for BS_TRIP_OPEN_MS:
+// every read answers { __err: 'blockscout down' } at once (callers file the token UNVERIFIED), no socket,
+// no retry. When the window lapses the next read is a probe: a good answer closes the circuit, a bad one
+// re-opens it. Matters in a long-lived server process.
+const BS_TRIP_AFTER = Math.max(2, Number(process.env.BS_TRIP_AFTER || 6));
+const BS_TRIP_OPEN_MS = Number(process.env.BS_TRIP_OPEN_MS || 10 * 60_000);
+const bsCircuit = { fails: 0, openUntil: 0, trips: 0 };
+export function bsCircuitState() { return { ...bsCircuit, open: Date.now() < bsCircuit.openUntil }; }
+const bsBad = (d) => /^http 5\d\d$/.test(d?.__err || '') || d?.__err === 'hard timeout' || d?.__err === 'timeout';
+export async function bsGet(path) {
+  if (Date.now() < bsCircuit.openUntil) return { __err: 'blockscout down' };
+  const probing = bsCircuit.trips > 0 && bsCircuit.fails >= BS_TRIP_AFTER;
+  const race = () => Promise.race([bsGetRaw(path), new Promise((r) => setTimeout(() => r({ __err: 'hard timeout' }), 20_000))]);
+  let d = await race();
+  if (d?.__err === 'http 429') { await sleep(4000); d = await race(); }
+  else if (/^http 5\d\d$/.test(d?.__err || '') && !probing && bsCircuit.fails + 1 < BS_TRIP_AFTER) { await sleep(2500); d = await race(); }
+  if (bsBad(d)) {
+    bsCircuit.fails++;
+    if (bsCircuit.fails >= BS_TRIP_AFTER) {
+      bsCircuit.openUntil = Date.now() + BS_TRIP_OPEN_MS; bsCircuit.trips++;
+      console.error(`[blockscout] circuit OPEN after ${bsCircuit.fails} consecutive 5xx/timeouts (last: ${d.__err} on ${path.split('/').slice(0, 2).join('/')}) - reads answer 'blockscout down' for ${Math.round(BS_TRIP_OPEN_MS / 60_000)} min`);
+    }
+  } else if (!d?.__err || d.__err === 'http 404') {
+    if (bsCircuit.trips > 0 && bsCircuit.fails >= BS_TRIP_AFTER) console.error('[blockscout] circuit CLOSED - probe answered');
+    bsCircuit.fails = 0;
+  }
+  return d;
+}
+
+// ---------- RPC ----------
+// owner() via eth_call. ROBINHOOD_RPC_URL overrides the public endpoint. A failed read is null (unknown)
+// and the caller fails closed on live privileges.
+export const RPC_URL = () => process.env.ROBINHOOD_RPC_URL || 'https://rpc.mainnet.chain.robinhood.com';
+export async function rpcCall(method, params, { timeoutMs = 10_000 } = {}) {
+  try {
+    const r = await fetch(RPC_URL(), { method: 'POST', headers: { 'Content-Type': 'application/json' }, signal: AbortSignal.timeout(timeoutMs),
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }) });
+    const j = await r.json();
+    return j?.result ?? null;
+  } catch { return null; }
+}
+async function ownerOf(address) {
+  const hex = String(await rpcCall('eth_call', [{ to: address, data: '0x8da5cb5b' }, 'latest']) || '');
+  if (!/^0x[0-9a-fA-F]{64}$/.test(hex)) return null;
+  return '0x' + hex.slice(-40).toLowerCase();
+}
+
+let _templates;
+export function templates() {
+  if (_templates === undefined) { try { _templates = JSON.parse(io.read(join(HERE, 'templates.json'))); } catch (e) { console.error(`[gate] templates.json unreadable: ${e.message} - every template reads unregistered`); _templates = null; } }
+  return _templates;
+}
+
+// Liquidity history hook: fn(chain, address) -> [[day, liqUsd], ...] | null. Absent = no history.
+let _liqHistory = null;
+export function setLiquidityHistory(fn) { _liqHistory = typeof fn === 'function' ? fn : null; }
+const liqHistoryFor = (chain, address) => (_liqHistory ? _liqHistory(chain, address) || null : null);
+
+// ---------- Contract facts from Blockscout (shared by the scan and the template tool) ----------
+export async function contractFacts(address) {
+  const a = address;
+  const ad = await bsGet(`/addresses/${a}`); await sleep(BS_PACE_MS);
+  if (ad?.__err) return { err: `blockscout addresses: ${ad.__err}` };
+  if (ad.is_contract === false) return { err: 'blockscout: address is not a contract' };
+  const creator = ad.creator_address_hash || null;
+  const proxyType = ad.proxy_type || null;
+  const impl = (ad.implementations || [])[0];
+  const implAddr = impl ? (impl.address || impl.address_hash || null) : null;
+  const codeAddr = implAddr || a;
+  const sc = await bsGet(`/smart-contracts/${codeAddr}`); await sleep(BS_PACE_MS);
+  if (sc?.__err && sc.__err !== 'http 404') return { err: `blockscout smart-contracts: ${sc.__err}` };
+  const verified = !!sc?.is_verified;
+  const contractName = implAddr ? (ad.name || null) : (sc?.name || null);
+  const implName = implAddr ? (sc?.name || impl.name || null) : null;
+  const fns = (sc?.abi || []).filter((f) => f.type === 'function').map((f) => f.name);
+  const priv = abiPrivileges(fns);
+  const src = (sc?.source_code || '') + (sc?.additional_sources || []).map((x) => x.source_code || '').join('');
+  const tax = taxCodeScan(src);
+  const template = resolveTemplate(templates(), { creator, contractName: sc?.name || contractName, implName, proxyType });
+  return { creator, proxyType, implAddr, codeAddr, verified, contractName, implName, fns, priv, tax, template, verifiedAt: sc?.verified_at || null, compiler: sc?.compiler_version || null, tokenName: ad.token?.name || null, tokenSymbol: ad.token?.symbol || null };
+}
+
+// ---------- Structural pass: facts from the chain, GoPlus as corroboration ----------
+// The pass: verified source (following a proxy to its implementation), a template whose verdict is not
+// `exclude`, no live owner privilege (mint / pause / blacklist / fee setter / trading toggle / upgrade in the
+// ABI unless owner() is the zero address), no transfer-tax code, sells clearing on DexScreener in the last 24h,
+// liquidity not drained more than 70% from its recorded peak, and no honeypot flag from GoPlus or GeckoTerminal.
+// Concentration stays a sizing TIER (Blockscout holders, pools and contracts removed).
+export async function gateRobinhood(c) {
+  const a = c.address, rs = rulesetOf(c), creatorMaxPct = rs.line('deployer.max');
+  const f = await contractFacts(a);
+  if (f.err) return { gateErr: f.err };
+  const { creator, proxyType, implAddr, codeAddr, verified, contractName, implName, priv, tax, template } = f;
+  const [hl, tk] = [await bsGet(`/tokens/${a}/holders`), await (sleep(BS_PACE_MS), bsGet(`/tokens/${a}`))]; await sleep(BS_PACE_MS);
+  const gp = await goplusRead(c);
+  const poolAddrs = [c.pairAddress, ...((gp?.dexPairs) || [])].filter(Boolean);
+  const bs = hl?.__err || tk?.__err ? null : blockscoutTop10(hl?.items, poolAddrs, tk?.total_supply);
+  const gt = await gtTokenInfo(c);
+  const top10Pct = bs?.top10Pct ?? gt?.top10 ?? gp?.top10Pct ?? null;
+  const top10Source = bs?.top10Pct != null ? 'blockscout ex-pool' : gt?.top10 != null ? 'geckoterminal incl. pools' : gp?.top10Pct != null ? 'goplus (partial list)' : null;
+  const holderCount = (tk && !tk.__err && tk.holders_count != null) ? Number(tk.holders_count) : (gp?.holderCount ?? gt?.count ?? null);
+  // owner: zero address = renounced; no owner function = nothing to renounce
+  let ownerRenounced = null, ownerAddress = null;
+  if (priv.owner) {
+    ownerAddress = await ownerOf(a) ?? (gp?.ownerAddress ? String(gp.ownerAddress).toLowerCase() : null);
+    ownerRenounced = ownerAddress === null ? null : /^0x0{40}$/.test(ownerAddress);
+  } else ownerRenounced = true;
+  const sellsClear = c.sells24 == null ? null : c.sells24 > 0;
+  const liq = liqDrawdown(liqHistoryFor(c.chain, a), c.liqUsd);
+  const creatorPct = gp?.creatorPct ?? null;
+  const taxCode = priv.feeSetter || (tax.taxCode && template.feeModel !== 'uniswap-pool-fee');
+  const reasons = [], caps = [];
+  if (template.verdict === 'exclude') reasons.push(`excluded template: ${template.note || template.key}`);
+  if (!verified) reasons.push(implAddr ? `implementation ${implName || codeAddr.slice(0, 10)} unverified` : 'source unverified');
+  if (priv.live && ownerRenounced !== true) reasons.push(`live privilege (${['mint', 'pause', 'blacklist', 'feeSetter', 'tradingToggle', 'upgrade'].filter((k) => priv[k]).join('+')}) with owner ${ownerRenounced === false ? 'active' : 'unverified'}`);
+  if (taxCode) reasons.push(`transfer-tax code in source (${tax.taxHits} tax, ${tax.reflectHits} reflection ids${priv.feeSetter ? ', fee setter in ABI' : ''})`);
+  if (gp?.honeypot === 1) reasons.push('GoPlus honeypot flag');
+  if (gt?.isHoneypot === true) reasons.push('GeckoTerminal honeypot flag');
+  if (sellsClear === false && (c.buys24 || 0) > 0) reasons.push(`no sells in 24h against ${c.buys24} buys - sells not clearing`);
+  if (liq.liqDropPct !== null && liq.liqDropPct > rs.line('liquidity.maxDrawdown')) reasons.push(`liquidity down ${liq.liqDropPct}% from its recorded peak $${Math.round(liq.liqPeak).toLocaleString('en-US')}`);
+  if (creatorPct !== null && creatorPct > creatorMaxPct) reasons.push(`creator holds ${creatorPct}% (max ${creatorMaxPct}%)`);
+  if (creatorPct === null) caps.push('creator balance unknown (no GoPlus record)');
+  if (sellsClear === null) caps.push('sell flow unknown');
+  if (liq.liqDropPct === null) caps.push(`liq history ${liq.points} day(s) - intact clause not yet judgeable`);
+  if (template.verdict === 'unregistered') caps.push(`unregistered template ${template.note || ''}`.trim());
+  return {
+    pass: reasons.length === 0, reasons, caps, source: 'blockscout',
+    verified, contractName, implName, proxyType, creator, template: template.key, templateVerdict: template.verdict, templateBy: template.by || null,
+    privileges: Object.fromEntries(Object.entries(priv).filter(([, v]) => v === true).map(([k]) => [k, true])),
+    ownerRenounced, ownerAddress, taxHits: tax.taxHits, reflectHits: tax.reflectHits, taxCode,
+    sellsClear, buys24: c.buys24 ?? null, sells24: c.sells24 ?? null, liqDropPct: liq.liqDropPct, liqPeak: liq.liqPeak, liqPoints: liq.points,
+    top10Pct, top10RawPct: bs?.top10InclPct ?? gp?.top10RawPct ?? null, poolAcctsInTop10: bs?.poolsInTop10 ?? gp?.poolAcctsInTop10 ?? null,
+    contractsInTop10: bs?.contractsInTop10 ?? null, maxSinglePct: bs?.maxSinglePct ?? null, top10Source,
+    holderCount, creatorPct,
+    honeypot: gp?.honeypot ?? null, buyTax: gp?.buyTax ?? null, sellTax: gp?.sellTax ?? null, mintable: gp?.mintable ?? null, pausable: gp?.pausable ?? null,
+    lpLockedOrBurned: gp?.lpLockedOrBurned ?? null, lpMode: gp?.lpMode ?? null, lpHolders: gp?.lpHolders ?? null, topLpPct: gp?.topLpPct ?? null, creatorLpPct: gp?.creatorLpPct ?? null,
+    taxKnown: gp?.taxKnown ?? null, goplusLazy: gp?.goplusLazy ?? null, goplusErr: gp?.goplusErr ?? null,
+  };
+}
+
+export async function gateFor(c) {
+  if (c.chain === CHAIN) return gateRobinhood(c);
+  return { gateErr: `no gate provider for chain ${c.chain}` };
+}
+
+// ---------- Sizing tier ----------
+export function tierOf(c) {
+  const g = c.gates;
+  if (!g || g.gateErr) return 'unknown';
+  if (!g.pass) return 'structural-fail';
+  return tierFromTop10(g.top10Pct, c.liqUsd, rulesetOf(c));
+}
+
+// The only tiers that may be presented as entry-eligible. A whitelist: a tier added later is non-actionable
+// until deliberately admitted (in tablesFrom, calc.mjs). This is the default ruleset's set.
+export const ACTIONABLE_TIERS = DEFAULT_RULESET.ACTIONABLE_TIERS;
+
+// ---------- Score: ranks, never admits ----------
+export function score(c) {
+  const rs = rulesetOf(c), E = entryFor(rs), bars = rs.TIER_BARS;
+  let s = 0;
+  if (c.gates?.pass) s += 30;                                   // structural pass
+  // A paid takeover claim scores 0: measured over 1,013 first-alert rows it was the strongest negative signal.
+  const t = c.gates?.top10Pct;
+  const tKnown = t !== null && t !== undefined;                 // unknown earns nothing, either way
+  if (c.gates?.pass && tKnown && t <= bars.conviction) s += 15;
+  else if (c.gates?.pass && tKnown && t <= bars.scout) s += 5;
+  else if (tKnown && t > bars.scout) s -= 10;
+  if (c.types.includes('profile')) s += 10;                     // paid profile on an aged token
+  if (c.types.includes('boost') || c.types.includes('boost-top')) s += 10;
+  if ((c.gates?.creatorPct ?? 100) === 0) s += 10;              // deployer fully exited
+  // A living remnant is HOLDERS, not transactions: a transaction count is earnable by one wallet round-tripping.
+  const holders = c.gates?.holderCount;
+  if (holders != null && holders >= 1_000) s += 10;
+  else if (holders != null && holders >= E.minHolders) s += 5;
+  if (c.ageDays >= 30) s += 5;                                  // survived a full cycle
+  const liqRatio = c.liqUsd / Math.max(c.mcapUsd, 1);
+  const turnover = (c.vol24 || 0) / Math.max(c.liqUsd || 1, 1);
+  // Turnover is required too, or this term rewards fabricated liquidity.
+  if (liqRatio >= 0.05 && turnover >= E.minTurnover24) s += 10;
+  // Entry at base: a candidate that already ran is a missed trade. A missing 24h change earns nothing.
+  if (c.priceChange24 != null) {
+    if (c.priceChange24 > 30) s -= 20;
+    else if (c.priceChange24 < 10) s += 10;
+  }
+  c.tier = tierOf(c);
+  c.convictionEligible = c.tier === rs.TIERS.CONVICTION;
+  return s;
+}
+
+// ---------- Price history: ATH drawdown and the 30-day low ----------
+// "How far from the top" and "are we at a base" are different questions; both come from one OHLCV pull,
+// memoized per token and cached 6h per pair. Failures are not cached.
+export async function poolHistory(c) {
+  if (c._hist !== undefined) return c._hist;
+  if (!c.pairAddress) { c._hist = null; return null; }
+  const ck = keyNorm(c.chain, c.pairAddress);
+  const cachePath = OHLCV_CACHE_PATH();
+  const ohlcvCache = readJsonSafe(cachePath);
+  const cached = ohlcvCache[ck];
+  if (cached && Date.now() - cached.t < 6 * 3600_000) { c._hist = cached.hist; return c._hist; }
+  const gtGap = Date.now() - poolHistory._lastGt;
+  if (gtGap < 2500) await sleep(2500 - gtGap);
+  poolHistory._lastGt = Date.now();
+  const ohlcvUrl = `https://api.geckoterminal.com/api/v2/networks/${GT_NETWORK}/pools/${c.pairAddress}/ohlcv/day?aggregate=1&limit=365`;
+  let d = await getJson(ohlcvUrl);
+  if (d?.__err && /429/.test(d.__err)) { await sleep(20_000); d = await getJson(ohlcvUrl); }
+  // Candles price the pool's BASE token. When this token is the QUOTE, ask for the quote side.
+  const baseAddr = String(d?.meta?.base?.address || '').toLowerCase();
+  const quoteAddr = String(d?.meta?.quote?.address || '').toLowerCase();
+  if (baseAddr && quoteAddr && quoteAddr === String(c.address).toLowerCase() && baseAddr !== quoteAddr) {
+    await sleep(600);
+    const dq = await getJson(`${ohlcvUrl}&token=quote`);
+    if (dq && !dq.__err) { d = dq; c._histSide = 'quote'; }
+    else console.error(`[history] ${c.symbol} is the QUOTE token of its pool and the quote-side read failed (${dq?.__err}) - treated as no history`), d = { __err: 'quote side unavailable' };
+  }
+  if (d?.__err) console.error(`[history] ${c.symbol} ohlcv failed: ${d.__err} - treated as no history`);
+  const list = d?.data?.attributes?.ohlcv_list;
+  if (!Array.isArray(list) || !list.length) { c._hist = null; return null; }
+  const ath = Math.max(...list.map((r) => +r[2] || 0));
+  const recent = [...list].sort((a, b) => (+b[0] || 0) - (+a[0] || 0)).slice(0, 30);
+  const lows = recent.map((r) => +r[3]).filter((n) => n > 0);
+  const low30 = lows.length ? Math.min(...lows) : null;
+  // Daily movement: adr14 = median daily range over the newest 14 days; moveDays14 = days that closed 10%+ from the open.
+  const last14 = recent.slice(0, 14);
+  const ranges = last14.map((r) => (+r[1] > 0 ? ((+r[2] - +r[3]) / +r[1]) * 100 : null)).filter((n) => n != null && Number.isFinite(n));
+  const closes = last14.map((r) => (+r[1] > 0 ? (Math.abs(+r[4] - +r[1]) / +r[1]) * 100 : null)).filter((n) => n != null && Number.isFinite(n));
+  const median = (a) => { const v = [...a].sort((x, y) => x - y); return v.length ? v[Math.floor((v.length - 1) / 2)] : null; };
+  c._hist = {
+    ath, low30,
+    adr14: ranges.length >= 3 ? +median(ranges).toFixed(1) : null,
+    moveDays14: closes.length ? closes.filter((n) => n >= 10).length : null,
+    candleDays: last14.length,
+    // 99.5%+ below ATH on a token that trades today is a unit mismatch between candles and the live price: unknown, never a verdict.
+    athDrawdown: ath && c.priceUsd ? ((1 - c.priceUsd / ath) * 100 >= 99.5 && (c.sells24 || 0) > 0 ? null : +((1 - c.priceUsd / ath) * 100).toFixed(1)) : null,
+    distFromLow30Pct: low30 && c.priceUsd ? +(((c.priceUsd - low30) / low30) * 100).toFixed(1) : null,
+  };
+  ohlcvCache[ck] = { t: Date.now(), hist: c._hist };
+  try { io.write(cachePath, JSON.stringify(ohlcvCache, null, 1)); } catch {}
+  return c._hist;
+}
+poolHistory._lastGt = 0;
+export async function athDrawdown(c) { const h = await poolHistory(c); return h ? h.athDrawdown : null; }
+
+// ---------- Entry test ----------
+// The entry lines under one ruleset. The two environment knobs still win over the default; a line the
+// caller overrode in the ruleset is what the caller asked for, so it is not quietly replaced by the env.
+export function entryFor(rs = DEFAULT_RULESET) {
+  const env = (name, key, v) => (rs.overrides.includes(key) ? v : Number(process.env[name] || v));
+  return {
+    minHolders: rs.line('holders.min'),
+    maxDistFromLow30Pct: rs.line('base.atBase'),                   // label only: the "at the base" band
+    minAthDrawdownConviction: rs.line('entry.convictionBelowPeak'),
+    maxPriceChange24Pct: rs.line('entry.midPump'),
+    minTurnover24: rs.line('entry.deepPoolTurnover') / 100,       // share of the pool
+    deepLiqUsd: 100_000,                                          // only judge pool turnover where the pool is this deep
+    minVol24Usd: env('ENTRY_MIN_VOL24_USD', 'entry.minVolume24h', rs.line('entry.minVolume24h')),
+    minTurnoverMcap: env('ENTRY_MIN_TURNOVER_MCAP', 'entry.minTurnoverOfMcap', rs.line('entry.minTurnoverOfMcap') / 100),
+  };
+}
+export const ENTRY = entryFor(DEFAULT_RULESET);
+
+// Second source for holder count, plus an independent top-10 figure as a cross-check.
+export async function gtTokenInfo(c) {
+  if (c._gtInfo !== undefined) return c._gtInfo;
+  const d = await getJson(`https://api.geckoterminal.com/api/v2/networks/${GT_NETWORK}/tokens/${c.address}/info`);
+  if (d?.__err) console.error(`[holders] ${c.symbol} gt info failed: ${d.__err} - holder count stays unknown (caps size, never blocks)`);
+  const at = d?.data?.attributes;
+  const h = at?.holders;
+  const t10 = h?.distribution_percentage?.top_10;
+  c._gtInfo = h ? { count: h.count ?? null, top10: t10 == null ? null : +(+t10).toFixed(1), isHoneypot: at?.is_honeypot === true ? true : at?.is_honeypot === false ? false : null } : null;
+  return c._gtInfo;
+}
+
+// Populate the price-history fields on the token whatever else happens. Reporting only; no gate changes.
+export async function recordHistory(c) {
+  const h = await poolHistory(c);
+  if (!h) return null;
+  c.low30 = h.low30;
+  c.ath = h.ath;
+  c.distFromLow30Pct = h.distFromLow30Pct;
+  if (c.athDrawdown == null) c.athDrawdown = h.athDrawdown;
+  c.adr14 = h.adr14 ?? null; c.moveDays14 = h.moveDays14 ?? null; c.candleDays = h.candleDays ?? null;
+  return h;
+}
+
+// Returns null when the token may be presented as entry-eligible, else the reason it may not.
+// Unknown data fails CLOSED, except where absence of evidence is not evidence of absence, in which case
+// it caps SIZE rather than killing the candidate (the holder-count branch).
+export async function entryChecks(c) {
+  const rs = rulesetOf(c), ENTRY = entryFor(rs), TIERS = rs.TIERS;
+  const h = await recordHistory(c);
+  let holders = c.gates?.holderCount;
+  c.holderSource = holders == null ? null : 'gate-provider';
+  if (holders == null) {
+    const gi = await gtTokenInfo(c);
+    if (gi?.count != null) { holders = gi.count; c.holderSource = 'geckoterminal'; }
+    if (gi?.top10 != null) c.gtTop10Pct = gi.top10;
+  }
+  c.holderCount = holders ?? null;
+  if (holders != null && holders < ENTRY.minHolders) return `only ${holders} holders < ${ENTRY.minHolders} - no remnant community`;
+  if (holders == null && c.tier === TIERS.CONVICTION) {
+    c.tier = TIERS.SCOUT_CLUSTER;
+    c.tierDowngraded = 'holder count unavailable from both sources - capped at scout size';
+  }
+  if ((c.liqUsd || 0) >= ENTRY.deepLiqUsd) {
+    const turnover = (c.vol24 || 0) / Math.max(c.liqUsd, 1);
+    if (turnover < ENTRY.minTurnover24) {
+      return `$${Math.round(c.liqUsd).toLocaleString('en-US')} pool doing ${(turnover * 100).toFixed(3)}% 24h turnover - liquidity is fabricated or dead`;
+    }
+  }
+  const vol24 = Number(c.vol24) || 0;
+  if (vol24 < ENTRY.minVol24Usd) return `quiet: $${Math.round(vol24).toLocaleString('en-US')} 24h volume under the $${ENTRY.minVol24Usd.toLocaleString('en-US')} floor`;
+  const mcapForTurnover = Number(c.mcapUsd) || 0;
+  if (mcapForTurnover > 0 && vol24 / mcapForTurnover < ENTRY.minTurnoverMcap) return `quiet: 24h turnover ${(100 * vol24 / mcapForTurnover).toFixed(1)}% of mcap under the ${Math.round(100 * ENTRY.minTurnoverMcap)}% floor`;
+  if (c.priceChange24 == null) return 'no 24h price change data - cannot confirm it is not mid-pump';
+  if (c.priceChange24 > ENTRY.maxPriceChange24Pct) return `mid-pump: 24h +${c.priceChange24}% over the +${ENTRY.maxPriceChange24Pct}% ceiling - a candidate that already ran is a missed trade`;
+  // Base proximity ranks and renders; it does not block. The drawdown from ATH is the entry thesis.
+  const base = baseEntryPenalty(h, rs);
+  c.baseEntry = base;
+  c.score += base.penalty;
+  if (c.tier === TIERS.CONVICTION) {
+    if (c.athDrawdown == null) return `ATH drawdown unknown (no usable price history) - CONVICTION needs a measured >=${ENTRY.minAthDrawdownConviction}% decline from ATH`;
+    if (c.athDrawdown < ENTRY.minAthDrawdownConviction) return `only ${c.athDrawdown}% below ATH - CONVICTION needs >=${ENTRY.minAthDrawdownConviction}% (post-abandonment, not a chart in progress)`;
+  }
+  return null;
+}
+
+// Graduated score penalty for distance above the 30-day low.
+export function baseEntryPenalty(h, rs = DEFAULT_RULESET) {
+  const d = h?.distFromLow30Pct;
+  const [atBase, justOff, wellOff] = rs.BASE_BANDS.map((b) => b.max);
+  if (d == null) return { distPct: null, penalty: -5, note: 'base entry unconfirmed - no usable 30d low' };
+  if (d <= atBase) return { distPct: d, penalty: 0, note: `at the base (${d}% above 30d low)` };
+  if (d <= justOff) return { distPct: d, penalty: -5, note: `${d}% above 30d low - just off the base` };
+  if (d <= wellOff) return { distPct: d, penalty: -10, note: `${d}% above 30d low - well off the base` };
+  return { distPct: d, penalty: -20, note: `${d}% above 30d low - already ran hard` };
+}
+
+// ---------- One token, the full pass ----------
+
+// The deepest DexScreener pair where this token is the BASE. A token that only appears as the QUOTE of its
+// pools has no DexScreener price of its own: null, and the caller says so.
+export function candidateFromPairs(chain, address, pairs) {
+  const raw = String(address || '').trim();
+  const key = raw.toLowerCase();
+  let p = null;
+  for (const x of Array.isArray(pairs) ? pairs : []) {
+    if (String(x?.baseToken?.address || '').toLowerCase() !== key) continue;
+    if (!p || (x.liquidity?.usd || 0) > (p.liquidity?.usd || 0)) p = x;
+  }
+  if (!p || !p.pairCreatedAt) return null;
+  const ageDays = (Date.now() - p.pairCreatedAt) / 864e5;
+  const liq = p.liquidity?.usd || 0;
+  const mcap = p.marketCap || p.fdv || 0;
+  return {
+    chain, address: key, types: ['scan'],
+    buys24: p.txns?.h24?.buys || 0, sells24: p.txns?.h24?.sells || 0,
+    symbol: p.baseToken.symbol, name: p.baseToken.name, priceUsd: +p.priceUsd || null,
+    ageDays: +ageDays.toFixed(1), liqUsd: Math.round(liq), mcapUsd: Math.round(mcap),
+    vol24: Math.round(p.volume?.h24 || 0), tx24: (p.txns?.h24?.buys || 0) + (p.txns?.h24?.sells || 0),
+    priceChange24: p.priceChange?.h24 ?? null,
+    pairAddress: p.pairAddress, dexId: p.dexId,
+    url: p.url || `https://dexscreener.com/${chain}/${p.pairAddress}`,
+    quoteSymbol: p.quoteToken?.symbol || null,
+  };
+}
+
+// Where the token sits against the discovery shape. Informational only.
+export function shapeNote(c) {
+  const out = [];
+  const usd = (n) => `$${Number(n).toLocaleString('en-US')}`;
+  if (c.ageDays != null && c.ageDays < DISCOVERY_SHAPE.minAgeDaysClaimed) out.push(`age ${c.ageDays}d under ${DISCOVERY_SHAPE.minAgeDaysClaimed}d`);
+  else if (c.ageDays != null && c.ageDays < DISCOVERY_SHAPE.minAgeDays && !c.takeoverClaim) out.push(`age ${c.ageDays}d under ${DISCOVERY_SHAPE.minAgeDays}d with no takeover claim`);
+  if (c.ageDays != null && c.ageDays > DISCOVERY_SHAPE.maxAgeDays) out.push(`age ${c.ageDays}d over ${DISCOVERY_SHAPE.maxAgeDays}d`);
+  if (c.liqUsd != null && c.liqUsd < DISCOVERY_SHAPE.minLiqUsd) out.push(`liq ${usd(c.liqUsd)} under ${usd(DISCOVERY_SHAPE.minLiqUsd)}`);
+  if (c.liqUsd != null && c.liqUsd > DISCOVERY_SHAPE.maxLiqUsd) out.push(`liq ${usd(c.liqUsd)} over ${usd(DISCOVERY_SHAPE.maxLiqUsd)}`);
+  if (c.mcapUsd != null && c.mcapUsd < DISCOVERY_SHAPE.minMcapUsd) out.push(`mcap ${usd(c.mcapUsd)} under ${usd(DISCOVERY_SHAPE.minMcapUsd)}`);
+  if (c.mcapUsd != null && c.mcapUsd > DISCOVERY_SHAPE.maxMcapUsd) out.push(`mcap ${usd(c.mcapUsd)} over ${usd(DISCOVERY_SHAPE.maxMcapUsd)}`);
+  return out.length ? `Discovery shape: outside (${out.join('; ')})` : null;
+}
+
+// The size rule: the lower of 1% of the pool and the cap for the tier, only on an entry-eligible token.
+export function sizeFor(c) {
+  const onePct = Math.floor((c.liqUsd || 0) / 100);
+  const cap = rulesetOf(c).TIER_CAP[c.tier] ?? 100;
+  return { onePctOfPoolUsd: onePct, tierCapUsd: cap, sizeUsd: c.actionable ? Math.min(onePct, cap) : null };
+}
+export function sizeLineFor(c) {
+  const s = sizeFor(c), rs = rulesetOf(c);
+  if (c.actionable) return `size $${s.sizeUsd.toLocaleString('en-US')} (lower of 1% of pool $${s.onePctOfPoolUsd.toLocaleString('en-US')} and the ${c.tier} cap $${s.tierCapUsd.toLocaleString('en-US')})`;
+  return `NOT entry-eligible${c.entryBlock ? ` - ${c.entryBlock}` : (c.tier === rs.TIERS.WATCH_ONLY ? ` - the 10 largest wallets hold over ${rs.TIER_BARS.scout}% of the supply; structure passed, judge the concentration yourself` : '')}`;
+}
+
+// The one-line answer. Four states, no fifth:
+//   UNVERIFIED   - a provider failed; structure unknown; never a verdict
+//   FAIL         - the chain says no (the reasons)
+//   NOT_ELIGIBLE - structure passes, but the tier or the entry test says not now (why)
+//   ELIGIBLE     - structure passes, tier actionable, entry test clear, with the size rule
+export function verdictFor(c) {
+  const g = c.gates || {}, rs = rulesetOf(c), TIERS = rs.TIERS, scoutLine = rs.TIER_BARS.scout;
+  if (g.gateErr) return { key: 'UNVERIFIED', head: 'UNVERIFIED - no verdict', why: `A gate provider failed (${g.gateErr}). Structure unknown - do not size. Try again in a minute.` };
+  if (!g.pass) return { key: 'FAIL', head: 'STRUCTURAL FAIL - not a buy', why: `FAIL: ${(g.reasons || []).join(' | ') || 'gates failed'}` };
+  if (c.actionable) {
+    const conviction = c.tier === TIERS.CONVICTION;
+    const caps = (g.caps || []).length ? ` Unknowns cap the size: ${g.caps.join(' | ')}.` : '';
+    return {
+      key: 'ELIGIBLE', head: `ENTRY-ELIGIBLE - ${c.tier}`,
+      why: `Structure passes on-chain, tier ${conviction ? 'CONVICTION' : 'scout'}, entry test clear.${caps}${conviction ? ' Above scout size: your own small buy and sell first.' : ''}`,
+    };
+  }
+  const why = c.entryBlock
+    || (c.tier === TIERS.WATCH_ONLY ? `the 10 largest wallets hold ${g.top10Pct != null ? g.top10Pct + '%' : `more than ${scoutLine}%`} of the supply, over the ${scoutLine}% line - every structural check passed, judge the concentration yourself`
+      : c.tier === TIERS.DIST_UNKNOWN ? 'holder distribution unknown from every source - cannot size'
+        : `tier ${c.tier} is not entry-eligible`);
+  return { key: 'NOT_ELIGIBLE', head: 'NOT ENTRY-ELIGIBLE - gates pass, not now', why: `Why: ${why}` };
+}
+
+// The whole pass for one address. Returns { ok:true, c } with the verdict on c, or { ok:false, err } when
+// there is nothing to judge (bad address, no pair, DexScreener down). An error is never a verdict.
+// `ruleset` is "default", a preset name, or { lines: [{ key, value }] } (see resolveRuleset in calc.mjs). A bad
+// one is answered before any network call, as an error result, never a verdict.
+export async function scanOne(address, { log = console.error, liquidityHistory = null, withX = true, withJev = true, ruleset = 'default' } = {}) {
+  const raw = String(address || '').trim();
+  if (!isAddress(raw)) return { ok: false, address: raw, err: 'not a contract address (0x + 40 hex characters)' };
+  const chain = CHAIN;
+  const a = raw.toLowerCase();
+  let rs;
+  try { rs = resolveRuleset(ruleset); } catch (e) { if (e instanceof RulesetError) return { ok: false, address: a, err: e.message }; throw e; }
+  if (liquidityHistory) setLiquidityHistory(liquidityHistory);
+  try {
+    const d = await getJson(`https://api.dexscreener.com/tokens/v1/${chain}/${a}`);
+    if (d?.__err) return { ok: false, address: a, err: `dexscreener: ${d.__err}` };
+    const c = candidateFromPairs(chain, a, d);
+    if (c) c.ruleset = rs;
+    if (!c) {
+      const asQuote = (Array.isArray(d) ? d : []).find((x) => String(x?.quoteToken?.address || '').toLowerCase() === a);
+      return {
+        ok: false, address: a,
+        err: asQuote
+          ? `only trades as the QUOTE side of a ${asQuote.baseToken?.symbol || '?'} pool on DexScreener - no price of its own to judge`
+          : `no DexScreener pair on ${chain} for this address (not traded here, or a different chain)`,
+      };
+    }
+    await sleep(1100);
+    await checkClaim(c);
+    await sleep(1100);
+    c.gates = await gateFor(c);
+    if (c.gates?.gateErr) log(`[scan] ${c.symbol} UNVERIFIED: ${c.gates.gateErr}`);
+    c.score = score(c); // sets c.tier
+    const structuralOk = !c.gates?.gateErr && !!c.gates?.pass && rs.ACTIONABLE_TIERS.has(c.tier);
+    c.entryBlock = structuralOk ? await entryChecks(c) : null;
+    // ATH and 30-day-low context on every verdict, pass or fail.
+    if (c.athDrawdown == null && c.distFromLow30Pct == null) { await sleep(700); await recordHistory(c); }
+    c.actionable = structuralOk && !c.entryBlock;
+    if (withX) { try { c.xMeta = await xMeta(c, { log }); } catch (e) { log(`[scan] x-meta ${c.symbol}: ${e.message}`); c.xMeta = null; } }
+    // Jev probabilities ride along as context when a key is present. Never a gate, never a rank key.
+    if (withJev) { try { c.jev = await jevJudge(c, { log }); } catch (e) { log(`[scan] jev ${c.symbol}: ${e.message}`); c.jev = null; } }
+    c.shapeNote = shapeNote(c);
+    c.verdict = verdictFor(c);
+    c.scannedAt = new Date().toISOString();
+    delete c._hist; delete c._gtInfo;
+    return { ok: true, c };
+  } finally { if (liquidityHistory) setLiquidityHistory(null); }
+}
+
+// Plain-text body: verdict, why, context lines, then the token card with the size line.
+export function renderScanText(res) {
+  if (!res?.ok) return [`NO VERDICT`, String(res?.err || 'unknown error'), res?.address || null].filter(Boolean).join('\n');
+  const c = res.c, v = c.verdict || verdictFor(c);
+  const lines = [v.head, v.why];
+  if (c.shapeNote) lines.push(c.shapeNote);
+  lines.push('', tokenCard({ ...c, sizeLine: sizeLineFor(c) }));
+  lines.push('', 'Research only, not financial advice.');
+  return lines.join('\n');
+}