@keelage/mcp 0.1.1

package/lib/format.mjs

@@ -0,0 +1,166 @@
+// format.mjs - one number grammar and one text card for a token. Plain text, no markup.
+//
+// Rule enforced here: unknown is never zero. A value that was never read renders "unknown", never "$0".
+// Every formatter returns UNK for null, undefined, '' and NaN, so no caller can print a placeholder zero.
+import { baseBand } from './calc.mjs';
+import { xLine } from './x-meta.mjs';
+import { jevLine } from './jev.mjs';
+
+export const UNK = 'unknown';
+export const LOCALE = 'en-US';
+
+// Address key normalization: 0x addresses are stored lowercase everywhere.
+export const keyNorm = (chain, a) => `${chain}:${/^0x/i.test(a) ? String(a).toLowerCase() : a}`;
+
+const bad = (n) => n === null || n === undefined || n === '' || !Number.isFinite(Number(n));
+
+export const usd = (n, dp = 0) => bad(n) ? UNK
+  : `$${Number(n).toLocaleString(LOCALE, { minimumFractionDigits: dp, maximumFractionDigits: dp })}`;
+
+// Compact form for market cap and volume where exact dollars are noise: $1.2M, $350k.
+export const usdC = (n) => {
+  if (bad(n)) return UNK;
+  const v = Number(n), a = Math.abs(v), sign = v < 0 ? '-' : '';
+  if (a >= 1e9) return `${sign}$${(a / 1e9).toFixed(a >= 1e10 ? 0 : 1)}B`;
+  if (a >= 1e6) return `${sign}$${(a / 1e6).toFixed(a >= 1e7 ? 0 : 1)}M`;
+  if (a >= 1e3) return `${sign}$${Math.round(a / 1e3)}k`;
+  return `${sign}$${a.toFixed(0)}`;
+};
+
+// Token prices span many orders of magnitude, so a fixed number of decimals is useless at one end.
+export const price = (n) => {
+  if (bad(n)) return UNK;
+  const v = Number(n), a = Math.abs(v);
+  if (a === 0) return '$0';
+  if (a >= 1) return `$${v.toFixed(2)}`;
+  if (a >= 0.01) return `$${v.toFixed(4)}`;
+  return `$${Number(v.toPrecision(4))}`;
+};
+
+export const pct = (n, dp = 1) => bad(n) ? UNK
+  : `${Number(n) > 0 ? '+' : ''}${Number(n).toFixed(dp)}%`;
+
+// Unsigned percentage, for shares (top-10 28%), not deltas.
+export const pctAbs = (n, dp = 0) => bad(n) ? UNK : `${Number(n).toFixed(dp)}%`;
+
+export const qty = (n, dp = 0) => bad(n) ? UNK
+  : Number(n).toLocaleString(LOCALE, { maximumFractionDigits: dp });
+
+export const age = (d) => bad(d) ? UNK : `${Math.round(Number(d))}d`;
+
+// Minutes-since -> "3h" / "45m" / "2d".
+export const ago = (isoOrMs) => {
+  if (!isoOrMs) return UNK;
+  const t = typeof isoOrMs === 'number' ? isoOrMs : Date.parse(isoOrMs);
+  if (!Number.isFinite(t)) return UNK;
+  const m = Math.max(0, Math.round((Date.now() - t) / 60_000));
+  if (m < 60) return `${m}m`;
+  if (m < 1440) return `${Math.round(m / 60)}h`;
+  return `${Math.round(m / 1440)}d`;
+};
+
+// A pipe-joined field line. Fields whose value is null, undefined or '' are dropped whole, so a line
+// never contains a bare "null".
+export const fields = (pairs) => pairs
+  .filter(([, v]) => v !== null && v !== undefined && v !== '')
+  .map(([k, v]) => (k ? `${k} ${v}` : String(v)))
+  .join(' | ');
+
+// Public pages for a token on Robinhood Chain.
+export function links(address) {
+  if (!address) return [];
+  return [
+    `https://dexscreener.com/robinhood/${address}`,
+    `https://www.geckoterminal.com/robinhood/tokens/${address}`,
+    `https://robinhoodchain.blockscout.com/token/${address}`,
+  ];
+}
+
+const shortAddr = (a) => {
+  const s = String(a ?? '');
+  return s.length > 16 ? `${s.slice(0, 4)}…${s.slice(-4)}` : s;
+};
+
+// Base band in words, then the number. The band is what predicts, so it leads.
+export function baseLabel(o) {
+  const d = o.baseEntry?.distPct ?? o.distFromLow30Pct;
+  const b = baseBand(d);
+  return d == null ? b.label : `${b.label} (${pctAbs(d)} above 30d low)`;
+}
+
+// The token card: fixed field order, every line optional as a whole, no line ever containing null.
+// Gate state vocabulary is exactly PASS / FAIL / UNVERIFIED.
+export function tokenCard(o) {
+  const g = o.gates || {};
+  const gateState = g.gateErr ? 'UNVERIFIED' : (g.pass ? 'PASS' : 'FAIL');
+  const lines = [];
+  const id = (s) => s;
+
+  const head = fields([
+    ['score', o.score ?? null],           // score ranks, never admits
+    ['tier', o.tier || null],
+  ]);
+  lines.push(`${o.symbol || shortAddr(o.address)}${head ? ` | ${head}` : ''}`);
+
+  lines.push(fields([
+    ['liq', o.liqUsd == null ? null : usd(o.liqUsd)],
+    ['vol24', o.vol24 == null ? null : usd(o.vol24)],
+    ['mcap', o.mcapUsd == null ? null : usdC(o.mcapUsd)],
+    ['age', o.ageDays == null ? null : age(o.ageDays)],
+    ['24h', o.priceChange24 == null ? null : pct(o.priceChange24)],
+    ['', o.athDrawdown == null ? null : `${pctAbs(o.athDrawdown)} below ATH`],
+    ['', baseLabel(o)],
+  ]));
+
+  lines.push(fields([
+    ['gates', gateState],
+    ['', g.gateErr ? `provider ${String(g.gateErr).slice(0, 60)}` : null],
+    ['top10', g.top10Pct == null ? null : `${pctAbs(g.top10Pct)}${g.top10Source ? ` (${g.top10Source})` : ''}`],
+    ['', g.maxSinglePct == null ? null : `largest wallet ${pctAbs(g.maxSinglePct)}`],
+    ['creator', g.creatorPct == null ? null : pctAbs(g.creatorPct)],
+    ['holders', g.holderCount == null ? null : qty(g.holderCount)],
+  ]));
+
+  // What the chain says about the contract itself.
+  if (g.source === 'blockscout') {
+    const priv = Object.keys(g.privileges || {}).filter((k) => k !== 'live' && k !== 'maxLimits');
+    lines.push(fields([
+      ['source', g.verified ? 'verified' : 'UNVERIFIED'],
+      ['template', g.template ? `${g.template}${g.templateVerdict && g.templateVerdict !== 'clean' ? ` (${g.templateVerdict})` : ''}` : null],
+      ['', g.implName ? `via ${g.implName} implementation` : null],
+      ['privileges', priv.length ? `${priv.join('+')}${g.ownerRenounced === true ? ', owner renounced' : g.ownerRenounced === false ? ', OWNER ACTIVE' : ', owner unverified'}` : 'none'],
+      ['tax code', g.taxCode == null ? null : (g.taxCode ? 'PRESENT' : 'none')],
+      ['sells 24h', g.sellsClear == null ? null : (g.sellsClear ? `clearing (${g.sells24})` : 'NONE')],
+      ['liq', g.liqDropPct == null ? (g.liqPoints != null ? `history ${g.liqPoints}d` : null) : `${pctAbs(g.liqDropPct)} below its ${g.liqPoints}d peak`],
+    ]));
+    if (g.reasons?.length) lines.push(`FAIL: ${g.reasons.join(' | ').slice(0, 300)}`);
+    if (g.caps?.length) lines.push(`unknown (caps size): ${g.caps.join(' | ').slice(0, 200)}`);
+  }
+
+  // GoPlus corroboration, only where it has a record.
+  lines.push(fields([
+    ['goplus', g.goplusErr ? 'no record' : (g.honeypot == null && g.buyTax == null && g.lpMode == null ? null : 'record')],
+    ['honeypot', g.honeypot == null ? null : (g.honeypot ? 'YES' : 'no')],
+    ['tax', g.buyTax == null && g.sellTax == null ? null : `${g.buyTax ?? '?'}/${g.sellTax ?? '?'}`],
+    ['LP', g.lpMode == null ? null : `${g.lpMode === 'cl' ? 'V3/V4 positions' : g.lpMode}${g.lpHolders != null ? `, ${g.lpHolders} holder(s), top ${pctAbs(g.topLpPct)}` : ''}${g.creatorLpPct ? `, creator ${pctAbs(g.creatorLpPct)}` : ''}`],
+  ]));
+
+  // A paid takeover claim is a caution, not a credential: claimed tokens read -58% median / 11% positive
+  // at 7 days against -13% / 37% unclaimed (n=155 vs 858).
+  const flags = [];
+  if (o.takeoverClaim) flags.push(`TAKEOVER CLAIM x${o.takeoverClaim.count} (latest ${o.takeoverClaim.latest}) - CAUTION: historically the worst-performing bucket`);
+  if (flags.length) lines.push(flags.join(' | '));
+
+  // X and Jev lines are context only: never a gate, never a rank key.
+  const xl = xLine(o.xMeta, id);
+  if (xl) lines.push(xl);
+  const jl = jevLine(o.jev, id);
+  if (jl) lines.push(jl);
+
+  if (o.sizeLine) lines.push(o.sizeLine);
+
+  lines.push(o.address);
+  lines.push(...links(o.address));
+
+  return lines.filter(Boolean).join('\n');
+}