solana-risk-engine 0.0.0-stage → 0.2.0

package/src/confluence.js

@@ -0,0 +1,120 @@
+import { ADDRESS_RE, KNOWN } from "./constants.js";
+import { ScanError, isCancel } from "./errors.js";
+import { pool, progress, short } from "./util.js";
+import { getTokens } from "./tokens.js";
+import { getMarkets } from "./markets.js";
+import { assess } from "./risk.js";
+import { estimatePnl } from "./pnl.js";
+import { holderBase, holderRows, markBusy } from "./holders.js";
+
+/**
+ * Confluence: tokens that several wallets hold in common, each with its risk.
+ *
+ * @param wallets                 at least 2 addresses
+ * @param [opts.pct=30]           a token must be held by at least this % of the wallets (and never fewer than 2)
+ * @param [opts.withPnl=false]    estimate each wallet's result first (needs Helius)
+ * @param [opts.pnlFilter="all"]  keep only wallets whose result is win | lose | flat | unk (implies withPnl)
+ * @returns {ts, wallets, allWallets, failed, minN, noMarket, marketFailed, rows, pnl, notes}
+ */
+export async function confluence(client, wallets, opts) {
+  opts = opts || {};
+  const onProgress = opts.onProgress;
+  const pct = opts.pct === undefined ? 30 : opts.pct;
+  const filter = opts.pnlFilter || "all";
+  const withPnl = !!opts.withPnl || filter !== "all";
+  if (!wallets || wallets.length < 2) throw new ScanError("TOO_FEW_WALLETS", "add at least 2 wallets", { n: wallets ? wallets.length : 0 });
+  const data = {};
+  let failed = 0, d = 0;
+  await pool(wallets, 3, async function (a) {
+    try { data[a] = (await getTokens(client, a)).tokens; } catch (e) { if (isCancel(e)) throw e; failed++; }
+    d++; progress(onProgress, "wallets", 0.05 + 0.3 * d / wallets.length, { done: d, total: wallets.length });
+  });
+  let ok = wallets.filter(function (a) { return data[a]; });
+  if (ok.length < 2) throw new ScanError("TOO_FEW_WALLETS", "could not read at least 2 wallets", { n: ok.length, total: wallets.length });
+  const okAll = ok, notes = [];
+  let pnlSnap = null;
+  if (withPnl && !client.heliusKey()) {
+    if (filter !== "all") throw new ScanError("HELIUS_REQUIRED", "the result filter needs a Helius API key");
+    notes.push("PNL_NO_HELIUS");
+  } else if (withPnl) {
+    progress(onProgress, "pnl", 0.3);
+    const pr = await estimatePnl(client, ok, data, { onStep: function (dn, n) { progress(onProgress, "pnl", 0.3 + 0.1 * dn / n, { done: dn, total: n }); } });
+    pnlSnap = {};
+    ok.forEach(function (a) { if (pr.pnl[a]) pnlSnap[a] = pr.pnl[a]; });
+    if (pr.down) notes.push("PNL_PARTIAL");
+    if (pr.approx) notes.push("PNL_APPROX");
+    if (filter !== "all") {
+      ok = ok.filter(function (a) { return pr.pnl[a] && pr.pnl[a].st === filter; });
+      if (ok.length < 2) throw new ScanError("TOO_FEW_WALLETS", "only " + ok.length + " wallets pass the result filter", { n: ok.length, total: okAll.length, filter: filter });
+    }
+  }
+  const minN = Math.max(2, Math.ceil(pct / 100 * ok.length));
+  const count = {};
+  ok.forEach(function (a) { Object.keys(data[a]).forEach(function (m) { count[m] = (count[m] || 0) + 1; }); });
+  const cand = Object.keys(count).filter(function (m) { return count[m] >= minN; });
+  progress(onProgress, "markets", 0.4);
+  const mkr = cand.length ? await getMarkets(client, cand, function (dn, n) { progress(onProgress, "markets", 0.4 + 0.15 * dn / n, { done: dn, total: n }); }) : { data: {}, failed: [] };
+  const mk = mkr.data, rows = [];
+  let noMarket = 0;
+  cand.forEach(function (m) {
+    const pair = mk[m], price = Number((pair && pair.priceUsd) || 0);
+    if (!pair || !(price > 0)) { noMarket++; return; }
+    const hs = [];
+    ok.forEach(function (a) { const q = data[a][m]; if (q && q * price >= 1) hs.push({ a: a, v: q * price }); });   // dust (< $1) ignored
+    if (hs.length < minN) return;
+    hs.sort(function (x, y) { return y.v - x.v; });
+    rows.push({ mint: m, pair: pair, hs: hs, n: hs.length, total: hs.reduce(function (s, x) { return s + x.v; }, 0) });
+  });
+  let done = 0;
+  const todo = rows.filter(function (r) { return !KNOWN[r.mint]; });
+  await pool(todo, 3, async function (r) {
+    let a = null;
+    try { a = await assess(client, r.mint, r.pair); } catch (e) { if (isCancel(e)) throw e; }
+    r.a = a; done++;
+    progress(onProgress, "tokens", 0.55 + 0.45 * done / Math.max(1, todo.length), { done: done, total: todo.length });
+  });
+  const out = [];
+  rows.forEach(function (r) {
+    const a = r.a, liq = (r.pair.liquidity && r.pair.liquidity.usd) || 0, common = { n: r.n, total: r.total, liq: liq, pairAddress: r.pair.pairAddress || "", holders: r.hs };
+    if (KNOWN[r.mint]) out.push(Object.assign({ mint: r.mint, sym: KNOWN[r.mint], name: "", lvl: "LOW", sev: 0, type: null, lights: null, known: true, img: null }, common));
+    else if (a) out.push(Object.assign({ mint: r.mint, sym: a.sym, name: a.name, lvl: a.lvl, sev: a.sev, type: a.type, lights: a.lights, known: false, img: a.img }, common));
+  });
+  out.sort(function (x, y) { return y.n - x.n || y.total - x.total; });
+  progress(onProgress, "done", 1);
+  return { ts: Date.now(), wallets: ok.length, allWallets: okAll.length, failed: failed, minN: minN, pct: pct, noMarket: noMarket, marketFailed: mkr.failed.length, rows: out, pnl: pnlSnap, notes: notes };
+}
+
+/**
+ * The reverse: wallets (people, not bots or exchanges) that are top holders of several tokens at once.
+ *
+ * @param mints             2 to 6 token addresses
+ * @param [opts.min=2]      in how many of the tokens a wallet must appear
+ * @returns {ts, tokens, min, rows: [{a, hits: [{m, s, pct}], total}], dropped}
+ */
+export async function commonHolders(client, mints, opts) {
+  opts = opts || {};
+  const onProgress = opts.onProgress;
+  mints = (mints || []).filter(function (x, i, l) { return ADDRESS_RE.test(x) && l.indexOf(x) === i; }).slice(0, 6);
+  if (mints.length < 2) throw new ScanError("TOO_FEW_TOKENS", "give at least 2 token addresses");
+  const map = {}, toks = [];
+  for (let i = 0; i < mints.length; i++) {
+    const b = await holderBase(client, mints[i], function (st, f) { progress(onProgress, "token", (i + f * 0.9) / mints.length * 0.8, { index: i + 1, total: mints.length, sub: st.step }); });
+    const hr = holderRows(b);
+    const sym = (b.pair && b.pair.baseToken && b.pair.baseToken.symbol) || short(mints[i]);
+    toks.push({ mint: mints[i], sym: sym });
+    hr.rows.forEach(function (r) {
+      if (r.kind !== "wallet") return;
+      (map[r.owner] = map[r.owner] || []).push({ m: mints[i], s: sym, pct: r.pct });
+    });
+  }
+  const min = Math.min(Number(opts.min) || 2, mints.length);
+  const cands = Object.keys(map).filter(function (a) { return map[a].length >= min; });
+  const kind = {};
+  cands.forEach(function (a) { kind[a] = "wallet"; });
+  await markBusy(client, kind, cands, function (c, n) { progress(onProgress, "bots", 0.8 + 0.2 * c / Math.max(1, n), { done: c, total: n }); });
+  const keep = cands.filter(function (a) { return kind[a] === "wallet"; });
+  const rows = keep.map(function (a) { return { a: a, hits: map[a], total: map[a].reduce(function (s, x) { return s + x.pct; }, 0) }; })
+    .sort(function (x, y) { return y.hits.length - x.hits.length || y.total - x.total; });
+  progress(onProgress, "done", 1);
+  return { ts: Date.now(), tokens: toks, min: min, rows: rows, dropped: cands.length - keep.length };
+}

package/src/constants.js

@@ -0,0 +1,55 @@
+// api.mainnet-beta.solana.com answers 403 to anything coming from a browser. PublicNode serves almost
+// everything (accounts, signatures, transactions) quickly, but blocks token-by-owner and largest-holder
+// queries. Those go to Solana Vibe Station, which accepts them without a key but only at ~1 per second,
+// so they go through a queue (see client.js). With your own RPC URL everything goes to that URL.
+export const PUBLIC_RPC = "https://solana-rpc.publicnode.com";
+export const VIBE_RPC = "https://public.rpc.solanavibestation.com";
+export const DEX = "https://api.dexscreener.com/tokens/v1/solana/";
+export const RUGCHECK = "https://api.rugcheck.xyz/v1/tokens/";
+export const HELIUS_API = "https://api.helius.xyz/v0/addresses/";
+export const COINGECKO_SOL = "https://api.coingecko.com/api/v3/coins/solana/market_chart?vs_currency=usd&days=365";
+
+export const TOKEN_PROGRAM = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+export const TOKEN_2022 = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+export const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+
+export const USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export const USDT = "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB";
+export const WSOL = "So11111111111111111111111111111111111111112";
+
+export const KNOWN = {
+  [WSOL]: "SOL (wrapped)",
+  [USDC]: "USDC",
+  [USDT]: "USDT"
+};
+
+// Symbols that scams usually copy, with their official address (checked on DexScreener)
+export const FAMOUS = {
+  USDC, USDT, SOL: WSOL, WSOL,
+  JUP: "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN", BONK: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
+  WIF: "EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm", PYTH: "HZ1JovNiVvGrGNiiYvEozEVgZ58xaU3RKwX8eACQBCt3",
+  JTO: "jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL", RAY: "4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R",
+  PYUSD: "2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo", MSOL: "mSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So",
+  JITOSOL: "J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn", TRUMP: "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
+  PUMP: "pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn", JLP: "27G8MtK7VtTcCHkpASjSDdkWWYfoqT6ggEuKidVJidD4",
+  POPCAT: "7GCihgDB8fe6KNjn2MYtkzZcRjQy3t9GHdC8uHYmW2hr", HNT: "hntyVP6YFm1Hg25TN9WGLqM12b8TQmcknKrdu1oxWux",
+  RENDER: "rndrizKT3MK1iimdxRdWabcF7Zg7AR5T4nud4EkHBof", ORCA: "orcaEKTdK7LKz57vaAYr9QeNsVEPfiu6QeMU1kektZE",
+  DRIFT: "DriFtupJYLTosbwoN8koMbEYSx54aFAVLddWsbksjwg7"
+};
+
+// Token-2022 extensions that add risk, with the points they add to the no-market spam score
+export const EXT_POINTS = {
+  permanentDelegate: 25,
+  transferHook: 15,
+  transferFeeConfig: 10,
+  nonTransferable: 10,
+  defaultAccountState: 10
+};
+
+// Risk levels, from worst to best (also the default sort order of results)
+export const LEVELS = ["HIGH", "MEDIUM", "LOW", "SPAM", "NO_DATA", "NO_MARKET"];
+export const TYPES = ["STABLE", "TOKENIZED", "BRIDGED", "CREATOR", "OPEN"];
+export const LIGHTS = ["control", "concentration", "market", "dependency"];
+export const RANKS = { ok: 0, na: 0, warn: 1, bad: 2 };
+
+export const ADDRESS_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;

package/src/curve.js

@@ -0,0 +1,34 @@
+// Is a key a normal wallet (a point on the ed25519 curve) or a PDA (off the curve)?
+// Used when an account does not exist on chain: an empty wallet is on the curve, a PDA is not.
+const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const P25519 = (1n << 255n) - 19n;
+
+function fmod(a) { a %= P25519; return a < 0n ? a + P25519 : a; }
+function fpow(b, e) { let r = 1n; b = fmod(b); while (e > 0n) { if (e & 1n) r = r * b % P25519; b = b * b % P25519; e >>= 1n; } return r; }
+const D25519 = fmod(-121665n * fpow(121666n, P25519 - 2n));
+
+// Decodes a base58 address into its 32 bytes, or null if it is not a valid 32-byte key
+export function b58bytes(str) {
+  let n = 0n, i;
+  const out = [];
+  for (i = 0; i < str.length; i++) { const k = B58.indexOf(str[i]); if (k < 0) return null; n = n * 58n + BigInt(k); }
+  while (n > 0n) { out.unshift(Number(n & 255n)); n >>= 8n; }
+  for (i = 0; i < str.length && str[i] === "1"; i++) out.unshift(0);
+  return out.length === 32 ? out : null;
+}
+
+export function onCurve(bytes) {
+  if (!bytes) return false;
+  let y = 0n;
+  for (let i = 31; i >= 0; i--) { let b = BigInt(bytes[i]); if (i === 31) b &= 127n; y = (y << 8n) | b; }
+  if (y >= P25519) return false;
+  const y2 = y * y % P25519, u = fmod(y2 - 1n), v = fmod(D25519 * y2 + 1n);
+  if (v === 0n) return false;
+  const x2 = u * fpow(v, P25519 - 2n) % P25519;
+  if (x2 === 0n) return true;
+  return fpow(x2, (P25519 - 1n) / 2n) === 1n;
+}
+
+export function isOnCurve(address) {
+  return onCurve(b58bytes(address));
+}

package/src/errors.js

@@ -0,0 +1,33 @@
+// Every error the engine throws on purpose is a ScanError with a stable `code`, so callers can
+// show their own message (see i18n describeError) instead of parsing English text.
+//
+// Codes:
+//   CANCELLED          the AbortSignal passed to the client fired
+//   HTTP               a service answered with an HTTP error (data.status)
+//   NETWORK            no answer after all retries
+//   RPC                the RPC answered with a JSON-RPC error
+//   DEX_UNREACHABLE    DexScreener could not be reached at all
+//   HELIUS_REQUIRED    PnL needs a Helius API key
+//   SOL_PRICE          no SOL price available to value trades
+//   INVALID_ADDRESS    not a Solana address
+//   NOT_A_TOKEN        the address is not a token mint
+//   IS_NFT             the mint is an NFT (decimals 0, supply 1)
+//   NO_HOLDERS         the RPC returned no holder data
+//   TOO_FEW_WALLETS    fewer readable wallets than needed (data.n, data.total)
+//   TOO_FEW_TOKENS     fewer valid mints than needed
+export class ScanError extends Error {
+  constructor(code, message, data) {
+    super(message || code);
+    this.name = "ScanError";
+    this.code = code;
+    if (data) this.data = data;
+  }
+}
+
+export function isCancel(e) {
+  return !!e && e.code === "CANCELLED";
+}
+
+export function cancelled() {
+  return new ScanError("CANCELLED", "cancelled");
+}

package/src/holders.js

@@ -0,0 +1,189 @@
+import { ADDRESS_RE } from "./constants.js";
+import { ScanError, isCancel } from "./errors.js";
+import { pool, progress, short, uniq } from "./util.js";
+import { getMint, accountKinds } from "./tokens.js";
+import { getMarkets } from "./markets.js";
+import { rugcheckReport, rugcheckGraph, rugcheckSummary, netBalances } from "./rugcheck.js";
+
+// Largest accounts of a token, each traced to its owner, and whether each owner is a wallet or a program
+export async function holderBase(client, mint, onProgress) {
+  progress(onProgress, "token", 0.08);
+  const res = await Promise.all([
+    getMint(client, mint),
+    client.rpc("getTokenLargestAccounts", [mint]),
+    getMarkets(client, [mint]).catch(function (e) { if (isCancel(e)) throw e; return { data: {}, failed: [mint] }; })
+  ]);
+  const info = res[0], largest = (res[1] && res[1].value) || [], pair = res[2].data[mint] || null;
+  if (!info) throw new ScanError("NOT_A_TOKEN", "that address is not a token");
+  if (!largest.length) throw new ScanError("NO_HOLDERS", "the RPC returned no holder data");
+  progress(onProgress, "owners", 0.4);
+  const ta = await client.rpc("getMultipleAccounts", [largest.map(function (a) { return a.address; }), { encoding: "jsonParsed" }]);
+  const owners = ta.value.map(function (v) {
+    return v && v.data && v.data.parsed && v.data.parsed.info && v.data.parsed.info.owner || null;
+  });
+  const owned = uniq(owners.filter(Boolean));
+  progress(onProgress, "kinds", 0.7);
+  const kind = await accountKinds(client, owned, false);
+  return { mint: mint, info: info, pair: pair, largest: largest, owners: owners, uniq: owned, kind: kind };
+}
+
+// People's wallets rarely move hundreds of transactions in a couple of days; exchanges, bots and
+// market makers do. Checked with the last 200 signatures. Marks them kind[o] = "active" (mutates kind)
+// and returns {address: hours it took to do those 200}.
+export async function markBusy(client, kind, wallets, onStep) {
+  const busy = {};
+  let chk = 0;
+  await pool(wallets, 3, async function (o) {
+    try {
+      const sg = await client.rpc("getSignaturesForAddress", [o, { limit: 200 }]);
+      if (sg && sg.length >= 200) {
+        const t1 = sg[0].blockTime, t0 = sg[sg.length - 1].blockTime;
+        if (t1 && t0 && (t1 - t0) < 2 * 86400) { kind[o] = "active"; busy[o] = Math.max(1, Math.round((t1 - t0) / 3600)); }
+      }
+    } catch (e) { if (isCancel(e)) throw e; }
+    chk++; if (onStep) onStep(chk, wallets.length);
+  });
+  return busy;
+}
+
+/* ---------- wallets funded from the same source (maybe one owner split into several accounts) ---------- */
+// By Solana protocol, account 0 of any transaction is always the fee payer. Looking at who paid the
+// very first transaction of each wallet shows who "created" it with the first SOL transfer. If several
+// wallets that look like different holders share that source, they are most likely the same person or
+// team splitting the supply to look decentralised. If the wallet is too active to find its first
+// transaction reliably (more than 3000 signatures), it is left without data rather than guessing wrong.
+export async function findFunder(client, addr) {
+  try {
+    let sigs = null, before = null, reachedEnd = false;
+    for (let i = 0; i < 3; i++) {
+      const page = await client.rpc("getSignaturesForAddress", [addr, before ? { limit: 1000, before: before } : { limit: 1000 }]);
+      if (!page || !page.length) { reachedEnd = true; break; }
+      sigs = page;
+      if (page.length < 1000) { reachedEnd = true; break; }
+      before = page[page.length - 1].signature;
+    }
+    if (!reachedEnd || !sigs || !sigs.length) return null;
+    const earliest = sigs[sigs.length - 1].signature;
+    const tx = await client.rpc("getTransaction", [earliest, { maxSupportedTransactionVersion: 0, encoding: "jsonParsed" }]);
+    const keys = tx && tx.transaction && tx.transaction.message && tx.transaction.message.accountKeys;
+    if (!keys || !keys.length) return null;
+    const payer = keys[0] && (keys[0].pubkey !== undefined ? keys[0].pubkey : keys[0]);
+    if (!payer || payer === addr) return null;   // it paid for itself: there is no outside source to look at
+    return payer;
+  } catch (e) { if (isCancel(e)) throw e; return null; }
+}
+
+export async function findFunders(client, wallets, onStep) {
+  const out = {};
+  let done = 0;
+  await pool(wallets, 3, async function (a) {
+    out[a] = await findFunder(client, a);
+    done++; if (onStep) onStep(done, wallets.length);
+  });
+  return out;
+}
+
+// An exchange pays the withdrawals of thousands of customers from the same wallet: if that is the
+// source, the "group" joins strangers. So sources that pass the same very-active test used to separate
+// bots are ignored (hot = markBusy result over the sources).
+export function clusterByFunder(funders, hot) {
+  const byFunder = {};
+  Object.keys(funders).forEach(function (a) {
+    const f = funders[a]; if (!f || (hot && hot[f])) return;
+    (byFunder[f] = byFunder[f] || []).push(a);
+  });
+  const clusters = {}, LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+  let n = 0;
+  Object.keys(byFunder).forEach(function (f) {
+    const ws = byFunder[f];
+    if (ws.length < 2) return;   // a single wallet with that source is not a pattern
+    const id = LETTERS[n] || ("G" + n); n++;
+    ws.forEach(function (a) { clusters[a] = { id: id, n: ws.length, funder: f }; });
+  });
+  return clusters;
+}
+
+// One row per owner (several token accounts of the same owner are summed), sorted by % of supply
+export function holderRows(b, busy) {
+  busy = busy || {};
+  const agg = {};
+  b.largest.forEach(function (a, i) {
+    const o = b.owners[i] || a.address;
+    if (!agg[o]) agg[o] = { owner: o, kind: b.kind[o] || "program", raw: 0, busy: busy[o] || 0 };
+    agg[o].raw += Number(a.amount);
+  });
+  const price = Number((b.pair && b.pair.priceUsd) || 0);
+  const rows = Object.keys(agg).map(function (k) {
+    const r = agg[k];
+    r.pct = b.info.supply > 0 ? r.raw / b.info.supply * 100 : 0;
+    r.tokens = r.raw / Math.pow(10, b.info.decimals);
+    r.value = r.tokens * price;
+    return r;
+  }).sort(function (a, c) { return c.pct - a.pct; });
+  rows.forEach(function (r, i) { r.rank = i + 1; });
+  return { rows: rows, price: price };
+}
+
+// Who created the token, what else they created (and how risky it is) and RugCheck's insider networks
+export async function creatorInfo(client, mint, onProgress) {
+  try {
+    const rcs = await Promise.all([rugcheckReport(client, mint), rugcheckGraph(client, mint)]), rc = rcs[0];
+    if (!rc || !rc.creator) return null;
+    const others = (rc.creatorTokens || []).filter(function (t) { return t.mint !== mint; })
+      .sort(function (a, b) { return new Date(b.createdAt || 0) - new Date(a.createdAt || 0); });
+    const toCheck = others.slice(0, 10), riskMap = {};
+    if (toCheck.length) {
+      progress(onProgress, "creatorTokens", 0.94);
+      await pool(toCheck, 3, async function (t) { riskMap[t.mint] = await rugcheckSummary(client, t.mint); });
+    }
+    const creator = {
+      addr: rc.creator, balance: rc.creatorBalance || 0, rugged: !!rc.rugged,
+      launchpad: (rc.launchpad && rc.launchpad.name) || null, others: others, checked: toCheck.length,
+      riskMap: riskMap, insiderNetworks: rc.insiderNetworks || [], graph: rcs[1], supply: (rc.token && rc.token.supply) || 0
+    };
+    if (creator.graph && creator.graph.length) {
+      progress(onProgress, "networks", 0.97);
+      await netBalances(client, mint, creator.graph);
+    }
+    return creator;
+  } catch (e) { if (isCancel(e)) throw e; return null; }   // like RugCheck in general: never blocks the main result
+}
+
+/**
+ * Whale finder: top holders, with bots/exchanges separated from people, people grouped by who funded
+ * them, and the creator's history. Works best with your own RPC (it needs getTokenLargestAccounts).
+ *
+ * @param [opts.creator=true]  also look up the creator and insider networks on RugCheck
+ */
+export async function analyzeHolders(client, mint, opts) {
+  opts = opts || {};
+  const onProgress = opts.onProgress;
+  if (!ADDRESS_RE.test(mint || "")) throw new ScanError("INVALID_ADDRESS", "not a Solana address");
+  const b = await holderBase(client, mint, onProgress);
+  const wal = b.uniq.filter(function (o) { return b.kind[o] === "wallet"; });
+  const busy = await markBusy(client, b.kind, wal, function (c, n) { progress(onProgress, "bots", 0.65 + 0.15 * c / Math.max(1, n), { done: c, total: n }); });
+  const hr = holderRows(b, busy), pair = b.pair;
+  const people = hr.rows.filter(function (r) { return r.kind === "wallet"; }).map(function (r) { return r.owner; });
+  let clusters = {}, hotGroups = 0;
+  if (people.length >= 2) {
+    const funders = await findFunders(client, people, function (c, n) { progress(onProgress, "funders", 0.8 + 0.08 * c / Math.max(1, n), { done: c, total: n }); });
+    clusters = clusterByFunder(funders);
+    const srcs = uniq(Object.keys(clusters).map(function (a) { return clusters[a].funder; }));
+    if (srcs.length) {
+      const hot = await markBusy(client, {}, srcs, function (c, n) { progress(onProgress, "exchangeSources", 0.88 + 0.02 * c / Math.max(1, n), { done: c, total: n }); });
+      hotGroups = srcs.filter(function (f) { return hot[f]; }).length;
+      if (hotGroups) clusters = clusterByFunder(funders, hot);
+    }
+  }
+  let creator = null;
+  if (opts.creator !== false) {
+    progress(onProgress, "creator", 0.9);
+    creator = await creatorInfo(client, mint, onProgress);
+  }
+  progress(onProgress, "done", 1);
+  return {
+    mint: mint, sym: (pair && pair.baseToken && pair.baseToken.symbol) || short(mint),
+    name: (pair && pair.baseToken && pair.baseToken.name) || "", price: hr.price, rows: hr.rows,
+    mintAuth: !!b.info.mintAuth, freezeAuth: !!b.info.freezeAuth, clusters: clusters, hotGroups: hotGroups, creator: creator
+  };
+}

package/src/i18n/en.js

@@ -0,0 +1,106 @@
+function usd(n) {
+  if (!n) return "$0";
+  if (n < 0.01) return "<$0.01";
+  return "$" + n.toLocaleString("en-US", { minimumFractionDigits: n < 1000 ? 2 : 0, maximumFractionDigits: n < 1000 ? 2 : 0 });
+}
+function pct(n) { return Math.round(n) + "%"; }
+function short(a) { return a.slice(0, 4) + "…" + a.slice(-4); }
+function prog(d) { return d && d.prog >= 20 ? ". Pools and programs hold " + pct(d.prog) : ""; }
+
+const EXT = {
+  permanentDelegate: "The issuer can move or burn your tokens (permanent delegate). Normal for tokenized stocks, but you have to trust the issuer",
+  transferHook: "Has a transfer hook: runs external code on every transfer",
+  transferFeeConfig: "Charges a fee on every transfer",
+  nonTransferable: "Cannot be transferred",
+  defaultAccountState: "New accounts can be created frozen"
+};
+
+export default {
+  fmt: { usd: usd, pct: pct, short: short },
+  signals: {
+    NO_INFO: () => "Could not read the token's information",
+    MINT_BY_PROGRAM: () => "A program controls the mint (usually a bridge or protocol): you have to trust that code",
+    MINT_ACTIVE: (d) => "The creator can still mint more tokens (mint authority active" + (d && d.byWallet ? ", held by a wallet" : "") + ")",
+    FREEZE_BY_PROGRAM: () => "A program controls freezing: it can freeze accounts according to its code",
+    FREEZE_ACTIVE: (d) => "The creator can freeze accounts (freeze authority active" + (d && d.byWallet ? ", held by a wallet" : "") + ")",
+    EXTENSION: (d) => EXT[d.ext] || ("Extension " + d.ext),
+    NO_MARKET: () => "No market on DexScreener (no price or liquidity)",
+    MARKET_UNCHECKED: () => "Could not check this token's market (network error reaching DexScreener): analyse it again to check",
+    KNOWN_TOKEN: () => "Well-known token",
+
+    CTL_MINT_ACTIVE: () => "The creator can mint more tokens (mint authority active)",
+    CTL_FREEZE_ACTIVE: () => "The creator can freeze accounts (freeze authority active)",
+    CTL_TRANSFER_HOOK: () => "Runs external code on every transfer",
+    CTL_TRANSFER_FEE: () => "Charges a fee on every transfer",
+    CTL_NON_TRANSFERABLE: () => "Cannot be transferred",
+    CTL_DEFAULT_FROZEN: () => "New accounts can be created frozen",
+    CTL_ONLY_PROGRAMS: () => "Only program-controlled authorities (see dependency)",
+    CTL_NONE: () => "No active authorities: nobody can mint more or freeze",
+    IMPOSTOR: (d) => "Impersonates " + d.symbol + ": the real " + d.symbol + " has another address (" + short(d.real) + "). It is a copy, almost certainly a scam",
+
+    CON_SKIPPED: () => "Holder concentration not checked",
+    CON_UNAVAILABLE: () => "Could not check holder concentration (the service did not answer; try again in a while)",
+    CON_ALL_POOLS: (d) => "Almost all the supply is in pools or programs" + prog(d),
+    CON_OK: (d) => "No worrying concentration (largest individual wallet: " + pct(d.w1) + ")" + prog(d),
+    CON_HIGH: (d) => "The largest individual wallet holds " + pct(d.w1) + " and the top 10 hold " + pct(d.w10) + " of the supply" + prog(d),
+    CON_UNSPLIT: (d) => "Could not separate pools from people. The largest account holds " + pct(d.top1) + " of the supply",
+
+    MKT_LIQ_INFLATED: (d) => "Inflated liquidity: DexScreener says " + usd(d.reported) + ", but the pool only has about " + usd(d.real) + " in real tokens (USDC, USDT or SOL). That is the most you could get out when selling",
+    MKT_LIQ_VERY_LOW: (d) => "Very low liquidity (" + usd(d.liq) + ")",
+    MKT_LIQ_LOW: (d) => "Low liquidity (" + usd(d.liq) + ")",
+    MKT_VOLUME_LOW: (d) => "Almost no 24h volume (" + usd(d.vol) + ")",
+    MKT_NEW: (d) => "Very new market (" + (d.days < 1 ? "less than a day" : d.days + (d.days === 1 ? " day" : " days")) + ")",
+    MKT_POSITION_HEAVY: (d) => "This wallet's position equals " + pct(d.pct) + " of the liquidity: selling at once would move the price a lot",
+    MKT_LP_UNLOCKED: (d) => "Only " + pct(d.pct) + " of the liquidity is locked or burned (per RugCheck): the rest can be pulled at once",
+    MKT_LP_PARTLY_LOCKED: (d) => "Only " + pct(d.pct) + " of the liquidity is locked or burned (per RugCheck)",
+    MKT_OK: (d) => "Liquidity " + usd(d.liq) + " · 24h volume " + usd(d.vol),
+
+    DEP_PROGRAM_AUTHORITY: () => "A program controls the mint or freeze (bridge or protocol): you have to trust its code",
+    DEP_PERMANENT_DELEGATE: () => "The issuer can move or burn your tokens (permanent delegate): you trust the issuer",
+    DEP_STABLE_ISSUER: () => "Its value depends on whoever issues and backs it",
+    DEP_NONE: () => "Does not depend on an issuer or a bridge"
+  },
+  offSolana: " and its main market may be outside Solana",
+  levels: {
+    HIGH: "High risk", MEDIUM: "Medium risk", LOW: "Low risk", SPAM: "Likely spam",
+    NO_DATA: "Not checked", NO_MARKET: "No market", MEDIUM_DATA_ONLY: "Medium due to missing data"
+  },
+  types: {
+    STABLE: { label: "Stablecoin", note: "Judged by its liquidity and trust in the issuer; concentration matters less." },
+    TOKENIZED: { label: "Tokenized or regulated", note: "The issuer normally keeps control (permanent delegate). The real risk is trusting the issuer and having liquidity to exit." },
+    BRIDGED: { label: "Bridged or protocol", note: "A program normally controls the mint. The real risk is trusting that bridge and its Solana market being small, since the main one may be on another chain." },
+    CREATOR: { label: "Creator-controlled", note: "A wallet can mint more or freeze accounts: the typical scam pattern, so it is judged more strictly." },
+    OPEN: { label: "Open token", note: "No creator authorities, typical of memecoins and new projects. Concentration in people and liquidity matter most." }
+  },
+  lights: { control: "Creator control", concentration: "Concentration", market: "Market and exit", dependency: "Dependency" },
+  missing: { control: "who controls the token", concentration: "holder concentration", market: "the market", dependency: "issuer dependency" },
+  steps: {
+    address: "Checking the address…", wallet: "Reading the wallet…", markets: "Fetching prices and liquidity…",
+    tokens: "Reviewing tokens…", token: "Reading the token…", owners: "Finding who owns each account…",
+    kinds: "Telling wallets from pools and programs…", bots: "Separating people from bots and exchanges…",
+    funders: "Looking for wallets funded from the same source…", exchangeSources: "Checking whether each group's source is an exchange…",
+    creator: "Looking up who created the token (RugCheck)…", creatorTokens: "Reviewing the creator's other tokens…",
+    networks: "Checking what wallet networks hold today…", wallets: "Reading wallets…",
+    pnl: "Estimating each wallet's result…", done: "Done"
+  },
+  notes: {
+    PNL_NO_HELIUS: "Wallet results were not estimated because there is no Helius key.",
+    PNL_PARTIAL: "Some wallets' history could not be read.",
+    PNL_APPROX: "SOL price history was unavailable: today's price was used and results may be far off."
+  },
+  errors: {
+    CANCELLED: () => "Cancelled.",
+    INVALID_ADDRESS: () => "That does not look like a Solana address. They are 32 to 44 letters and digits and do not start with 0x.",
+    NOT_A_TOKEN: () => "That address is not a token.",
+    IS_NFT: () => "That address is an NFT, not a token. The scanner does not review NFTs.",
+    NO_HOLDERS: () => "The RPC returned no holder data.",
+    HELIUS_REQUIRED: () => "Estimating results needs a Helius API key (or a Helius RPC URL with the key).",
+    SOL_PRICE: () => "Could not get the SOL price to compute the result. Try again in a while.",
+    DEX_UNREACHABLE: () => "Could not connect to DexScreener. Check your internet connection and try again.",
+    TOO_FEW_WALLETS: (d) => d && d.filter ? "Only " + d.n + (d.n === 1 ? " wallet passes" : " wallets pass") + " the result filter (of " + d.total + " read)." : "At least 2 readable wallets are needed.",
+    TOO_FEW_TOKENS: () => "Give at least 2 Solana token addresses.",
+    NETWORK_PUBLIC: () => "The free Solana services did not answer (they get saturated sometimes). Wait a minute and try again, or use your own RPC URL (Helius has a free plan).",
+    NETWORK_OWN: () => "Could not connect to your RPC URL. Check it was copied correctly (with the key at the end).",
+    UNKNOWN: (d) => "Something failed: " + d.message + ". Try again or use another RPC."
+  }
+};