solana-risk-engine 0.0.0-stage → 0.2.0

package/src/risk.js

@@ -0,0 +1,234 @@
+import { EXT_POINTS, RANKS } from "./constants.js";
+import { isCancel } from "./errors.js";
+import { short, sleep } from "./util.js";
+import { getMint, getAuthKinds, getConc } from "./tokens.js";
+import { impostorOf } from "./markets.js";
+import { rugcheckSummary } from "./rugcheck.js";
+
+// Every finding is a "signal": {code, s, data}. `s` is ok | na | warn | bad, `data` holds the numbers
+// behind it. Turning signals into sentences is i18n's job (describe / explainLight), never the engine's.
+function sig(code, s, data) {
+  const o = { code: code, s: s };
+  if (data) o.data = data;
+  return o;
+}
+
+const DAY = 86400000;
+
+/* ---------- old point score: only for tokens without a market, to spot spam ---------- */
+export function score(info) {
+  let pts = 0;
+  const why = [];
+  if (!info) return { pts: 30, why: [sig("NO_INFO", "warn")] };
+  const ak = info.authKind || {};
+  if (info.mintAuth) {
+    if (ak[info.mintAuth] === "program") { pts += 10; why.push(sig("MINT_BY_PROGRAM", "warn")); }
+    else { pts += 25; why.push(sig("MINT_ACTIVE", "bad", { byWallet: ak[info.mintAuth] === "wallet" })); }
+  }
+  if (info.freezeAuth) {
+    if (ak[info.freezeAuth] === "program") { pts += 8; why.push(sig("FREEZE_BY_PROGRAM", "warn")); }
+    else { pts += 20; why.push(sig("FREEZE_ACTIVE", "warn", { byWallet: ak[info.freezeAuth] === "wallet" })); }
+  }
+  info.ext.forEach(function (e) { if (EXT_POINTS[e]) { pts += EXT_POINTS[e]; why.push(sig("EXTENSION", "warn", { ext: e })); } });
+  why.push(sig("NO_MARKET", "na"));
+  return { pts: pts, why: why };
+}
+
+/* ---------- token type ---------- */
+export function tokenType(info, pair, now) {
+  if (!info) return null;
+  now = now || Date.now();
+  const ak = info.authKind || {};
+  const sym = ((pair && pair.baseToken && pair.baseToken.symbol) || "") + " " + ((pair && pair.baseToken && pair.baseToken.name) || "");
+  const price = Number((pair && pair.priceUsd) || 0);
+  const liq = (pair && pair.liquidity && pair.liquidity.usd) || 0;
+  const ageDays = (pair && pair.pairCreatedAt) ? (now - pair.pairCreatedAt) / DAY : 0;
+  // Being called "USD something" is not enough to be judged more leniently than a normal token:
+  // it needs a stable price, real liquidity and some time trading (otherwise a scammer only has to
+  // name the token "USDX" and keep the price near $1 for a while)
+  if (/USD|DOLLAR/i.test(sym) && price > 0.97 && price < 1.03 && liq >= 200000 && ageDays >= 30) return "STABLE";
+  if (info.ext.indexOf("permanentDelegate") >= 0) return "TOKENIZED";
+  const walletAuth = (info.mintAuth && ak[info.mintAuth] !== "program") || (info.freezeAuth && ak[info.freezeAuth] !== "program");
+  if (walletAuth) return "CREATOR";
+  if (info.mintAuth || info.freezeAuth) return "BRIDGED";
+  return "OPEN";
+}
+
+/* ---------- the four traffic lights ---------- */
+function mkLight(k, items, okSignal) {
+  if (!items.length) return { k: k, s: "ok", items: [okSignal] };
+  let st = "ok";
+  items.forEach(function (x) { if (RANKS[x.s] > RANKS[st]) st = x.s; });
+  // na ranks like ok for "worst of", but an unchecked light must stay na so levelFrom can cap it
+  if (st === "ok" && items.some(function (x) { return x.s === "na"; })) st = "na";
+  return { k: k, s: st, items: items };
+}
+
+/**
+ * @param info   mint info from getMint (+ authKind) or null if it could not be read
+ * @param conc   concentration from getConc, {skip:true}, or null if the RPC did not answer
+ * @param pair   best DexScreener pair (required: lights are only built for tokens with a market)
+ * @param value  USD value the analysed wallet holds (0 when checking a token alone)
+ * @param type   tokenType(info, pair)
+ * @param rc     RugCheck summary or null
+ * @returns      [control, concentration, market, dependency]
+ */
+export function buildLights(info, conc, pair, value, type, rc, now) {
+  now = now || Date.now();
+  const ak = (info && info.authKind) || {};
+  let it;
+
+  // 1) creator control
+  it = [];
+  if (!info) it.push(sig("NO_INFO", "warn"));
+  else {
+    if (info.mintAuth && ak[info.mintAuth] !== "program") it.push(sig("CTL_MINT_ACTIVE", "bad"));
+    if (info.freezeAuth && ak[info.freezeAuth] !== "program") it.push(sig("CTL_FREEZE_ACTIVE", "warn"));
+    if (info.ext.indexOf("transferHook") >= 0) it.push(sig("CTL_TRANSFER_HOOK", "warn"));
+    if (info.ext.indexOf("transferFeeConfig") >= 0) it.push(sig("CTL_TRANSFER_FEE", "warn"));
+    if (info.ext.indexOf("nonTransferable") >= 0) it.push(sig("CTL_NON_TRANSFERABLE", "warn"));
+    if (info.ext.indexOf("defaultAccountState") >= 0) it.push(sig("CTL_DEFAULT_FROZEN", "warn"));
+  }
+  const control = mkLight("control", it, sig((info && (info.mintAuth || info.freezeAuth)) ? "CTL_ONLY_PROGRAMS" : "CTL_NONE", "ok"));
+
+  // 2) concentration in people (pools and programs do not count)
+  let concentration;
+  const soft = (type === "STABLE" || type === "TOKENIZED" || type === "BRIDGED");
+  if (conc && conc.skip) concentration = mkLight("concentration", [sig("CON_SKIPPED", "na")]);
+  else if (!conc) concentration = mkLight("concentration", [sig("CON_UNAVAILABLE", "na")]);
+  else if (conc.ok) {
+    let st = "ok";
+    if (conc.w1 > 30 || conc.w10 > 70) st = "bad"; else if (conc.w1 > 15 || conc.w10 > 50) st = "warn";
+    if (soft && st === "bad") st = "warn";
+    const data = { w1: conc.w1, w10: conc.w10, prog: conc.prog, wallets: conc.nW };   // prog >= 20 is worth mentioning
+    const code = !conc.nW ? "CON_ALL_POOLS" : (st === "ok" ? "CON_OK" : "CON_HIGH");
+    concentration = mkLight("concentration", [sig(code, st, data)]);
+  } else {
+    concentration = mkLight("concentration", [sig("CON_UNSPLIT", (conc.top1 > 30 || conc.top10 > 70) ? "warn" : "ok", { top1: conc.top1, top10: conc.top10 })]);
+  }
+
+  // 3) market and exit
+  const liq = (pair.liquidity && pair.liquidity.usd) || 0, vol = (pair.volume && pair.volume.h24) || 0;
+  it = [];
+  if (pair.liqRaw) it.push(sig("MKT_LIQ_INFLATED", "bad", { reported: pair.liqRaw, real: liq }));
+  else if (liq < 10000) it.push(sig("MKT_LIQ_VERY_LOW", "bad", { liq: liq }));
+  else if (liq < 50000) it.push(sig("MKT_LIQ_LOW", "warn", { liq: liq }));
+  if (vol < 1000) it.push(sig("MKT_VOLUME_LOW", "warn", { vol: vol }));
+  if (pair.pairCreatedAt) {
+    const d = (now - pair.pairCreatedAt) / DAY;
+    if (d < 7) it.push(sig("MKT_NEW", "warn", { days: Math.floor(d) }));
+  }
+  if (value > 0 && liq > 0 && value / liq >= 0.1) it.push(sig("MKT_POSITION_HEAVY", "warn", { pct: value / liq * 100 }));
+  // Dollars in the pool do not say who can take them out: if the LP tokens are neither locked nor
+  // burned, the creator can pull the liquidity at any time whatever the rest says. Only for markets
+  // under 90 days: that is when the creator alone provides liquidity and rug pulls are typical. In
+  // veteran tokens (JUP, WIF...) many market makers provide it and unlocked LP is not a signal: applying
+  // it there gave false positives (JUP scored worse than a new memecoin)
+  const young = !pair.pairCreatedAt || (now - pair.pairCreatedAt) / DAY < 90;
+  if (rc && !soft && young && liq > 0 && typeof rc.lpLockedPct === "number" && isFinite(rc.lpLockedPct)) {
+    if (rc.lpLockedPct < 20) it.push(sig("MKT_LP_UNLOCKED", "bad", { pct: rc.lpLockedPct }));
+    else if (rc.lpLockedPct < 60) it.push(sig("MKT_LP_PARTLY_LOCKED", "warn", { pct: rc.lpLockedPct }));
+  }
+  if (type === "BRIDGED" && liq < 50000 && it.length) it[0] = Object.assign({}, it[0], { data: Object.assign({}, it[0].data, { offSolana: true }) });
+  const market = mkLight("market", it, sig("MKT_OK", "ok", { liq: liq, vol: vol }));
+
+  // 4) dependency on an issuer or a bridge
+  it = [];
+  if (info) {
+    if ((info.mintAuth && ak[info.mintAuth] === "program") || (info.freezeAuth && ak[info.freezeAuth] === "program"))
+      it.push(sig("DEP_PROGRAM_AUTHORITY", "warn"));
+    if (info.ext.indexOf("permanentDelegate") >= 0) it.push(sig("DEP_PERMANENT_DELEGATE", "warn"));
+  }
+  if (type === "STABLE") it.push(sig("DEP_STABLE_ISSUER", "warn"));
+  const dependency = mkLight("dependency", it, sig("DEP_NONE", "ok"));
+
+  return [control, concentration, market, dependency];
+}
+
+export function levelFrom(lights) {
+  let b = 0, w = 0, na = 0;
+  lights.forEach(function (l) { if (l.s === "bad") b++; else if (l.s === "warn") w++; else if (l.s === "na") na++; });
+  let lvl = (b >= 2 || (b === 1 && w >= 1)) ? "HIGH" : ((b === 1 || w >= 2) ? "MEDIUM" : "LOW");
+  // What could not be checked does not count as "fine": with a check missing, at best it is medium risk
+  if (lvl === "LOW" && na > 0) lvl = "MEDIUM";
+  // A market under 7 days old has no track record: it is never "low risk", even with nothing else wrong.
+  // Other single warnings stay low: on established tokens they are normal for their type (a staking pool's
+  // program-controlled mint, a transfer hook...); measured on 62 real tokens, this rule moved 9 brand-new
+  // tokens from low to medium and no established one
+  if (lvl === "LOW" && lights.some(function (l) { return (l.items || []).some(function (x) { return x.code === "MKT_NEW"; }); })) lvl = "MEDIUM";
+  return { lvl: lvl, sev: 3 * b + w + (na && !b && !w ? 1 : 0) };
+}
+
+// "Medium" with no concrete signal at all: only because some check could not run (e.g. holders without
+// your own RPC). Callers should say so explicitly so the scanner does not look like it marks everything the same
+export function dataOnly(r) {
+  return r.lvl === "MEDIUM" && !!r.lights && !r.lights.some(function (l) { return l.s === "bad" || l.s === "warn"; }) && r.lights.some(function (l) { return l.s === "na"; });
+}
+
+// The signals worth showing as "why": everything not ok, in light order
+export function reasonsFrom(lights) {
+  const out = [];
+  lights.forEach(function (l) { if (l.s !== "ok") l.items.forEach(function (x) { if (x.s !== "ok") out.push(Object.assign({ k: l.k }, x)); }); });
+  return out;
+}
+
+/**
+ * Full risk assessment of one token.
+ *
+ * @param client
+ * @param mint
+ * @param pair       best DexScreener pair or null (no market)
+ * @param [opts.value]           USD the analysed wallet holds of it (for the "heavy position" check)
+ * @param [opts.marketUnknown]   the DexScreener batch for this mint failed: no data, not "no market"
+ * @param [opts.skipConcentration]
+ * @returns null for NFTs, otherwise {mint, sym, name, lvl, sev, pts, type, lights, reasons, impostor, value, pair, img}
+ */
+export async function assess(client, mint, pair, opts) {
+  opts = opts || {};
+  const value = opts.value || 0;
+  if (opts.marketUnknown) {
+    return {
+      mint: mint, sym: short(mint), name: "", pts: 0, sev: 0, lvl: "NO_DATA",
+      reasons: [sig("MARKET_UNCHECKED", "na")], lights: null, type: null, impostor: null, value: value, pair: null, img: null
+    };
+  }
+  const rcPromise = pair ? rugcheckSummary(client, mint) : Promise.resolve(null);   // in parallel with the RPC calls below
+  let info = null, conc = null;
+  try { info = await getMint(client, mint); } catch (e) { if (isCancel(e)) throw e; }
+  if (info && info.decimals === 0 && info.supply === 1) return null;   // NFT
+  // Without a market concentration is not checked: saves half the requests
+  if (info && pair && (info.mintAuth || info.freezeAuth)) {
+    try { info.authKind = await getAuthKinds(client, info); } catch (e) { if (isCancel(e)) throw e; }
+  }
+  if (info && pair && opts.skipConcentration) conc = { skip: true };
+  else if (info && pair) {
+    // In tokens with millions of holders (BONK) getTokenLargestAccounts sometimes times out: a second try usually works
+    for (let tryC = 0; tryC < 2 && !conc; tryC++) {
+      try { conc = await getConc(client, mint, info.supply); }
+      catch (e) { if (isCancel(e)) throw e; conc = null; if (!tryC) await sleep(client.retryDelayMs === undefined ? 1500 : client.retryDelayMs); }
+    }
+  }
+  const rc = await rcPromise;
+  const base = (pair && pair.baseToken) || {};
+  let lvl, sev = 0, reasons = [], lights = null, type = null, pts = 0, imp = null;
+  if (pair) {
+    type = tokenType(info, pair);
+    lights = buildLights(info, conc, pair, value, type, rc);
+    imp = impostorOf(mint, pair);
+    if (imp) {
+      const prev = lights[0];
+      lights[0] = { k: "control", s: "bad", items: [sig("IMPOSTOR", "bad", { symbol: imp.sym, real: imp.real })].concat(prev.s !== "ok" ? prev.items : []) };
+    }
+    const lf = levelFrom(lights); lvl = lf.lvl; sev = lf.sev; reasons = reasonsFrom(lights);
+    if (imp) { lvl = "HIGH"; sev += 5; }   // a copy is high risk even if everything else looks normal
+  } else {
+    const s = score(info);
+    pts = s.pts; reasons = s.why; lvl = pts >= 25 ? "SPAM" : "NO_MARKET";
+  }
+  return {
+    mint: mint, sym: base.symbol || short(mint), name: base.name || "", pts: pts, sev: sev,
+    lvl: lvl, type: type, lights: lights, reasons: reasons, impostor: imp, value: value, pair: pair,
+    rugcheck: rc ? { lpLockedPct: rc.lpLockedPct, score: rc.score_normalised !== undefined ? rc.score_normalised : rc.score } : null,
+    img: (pair && pair.info && pair.info.imageUrl) || null
+  };
+}

package/src/rugcheck.js

@@ -0,0 +1,66 @@
+import { RUGCHECK } from "./constants.js";
+import { isCancel } from "./errors.js";
+import { kindOf } from "./tokens.js";
+import { pool } from "./util.js";
+
+// Extra signal from RugCheck.xyz (public API, no key): mainly the % of liquidity locked or burned,
+// which on-chain data does not show without decoding each DEX's binary layout (Raydium, Orca, Meteora
+// and pump.fun all differ). It is an extra, never a requirement: on failure these return null and the
+// rest of the analysis is exactly the same.
+export function rugcheckSummary(client, mint) {
+  return client.softJson(RUGCHECK + mint + "/report/summary", 6000);
+}
+
+// Full report (~700 KB, so ask once per holder search, never per token of a wallet): who created the
+// token, which other tokens that wallet created and whether RugCheck sees wallet networks linked by
+// transfers (a wider coordination signal than a shared funder).
+export function rugcheckReport(client, mint) {
+  return client.softJson(RUGCHECK + mint + "/report", 10000);
+}
+
+// The report only gives each network's size; this endpoint gives its wallets and holdings
+export async function rugcheckGraph(client, mint) {
+  const g = await client.softJson(RUGCHECK + mint + "/insiders/graph", 8000);
+  if (!Array.isArray(g)) return null;
+  return g.map(function (n) {
+    const nodes = (n.nodes || []).filter(function (x) { return x && x.id && x.participant !== false; })
+      .map(function (x) { return { addr: x.id, hold: Number(x.holdings || 0) }; })
+      .sort(function (a, b) { return b.hold - a.hold; });
+    return { nodes: nodes, hold: nodes.reduce(function (s, x) { return s + x.hold; }, 0) };
+  }).filter(function (n) { return n.nodes.length > 1; }).sort(function (a, b) { return b.hold - a.hold; });
+}
+
+// The graph's "holdings" are not today's balance: a wallet that handed tokens out shows the whole
+// network's total even with 0, and sometimes a network includes a pool. This reads on chain what each
+// one holds today and whether it is a wallet or a program. Mutates the graph (adds now/kind/checked).
+export async function netBalances(client, mint, graph) {
+  let addrs = [];
+  graph.forEach(function (n) { n.nodes.forEach(function (x) { if (addrs.indexOf(x.addr) < 0) addrs.push(x.addr); }); });
+  addrs = addrs.slice(0, client.ownRpc() ? 80 : 25);   // without your own URL each balance goes through the ~1/s queue
+  const bal = {}, kind = {};
+  for (let i = 0; i < addrs.length; i += 100) {
+    const part = addrs.slice(i, i + 100);
+    try {
+      const oa = await client.rpc("getMultipleAccounts", [part, { encoding: "base64", dataSlice: { offset: 0, length: 0 } }]);
+      part.forEach(function (a, k) { kind[a] = kindOf(a, oa.value[k], true); });
+    } catch (e) { if (isCancel(e)) throw e; }
+  }
+  await pool(addrs, 4, async function (a) {
+    try {
+      const r = await client.rpc("getTokenAccountsByOwner", [a, { mint: mint }, { encoding: "jsonParsed" }]);
+      bal[a] = (r && r.value || []).reduce(function (s, c) { return s + Number(c.account.data.parsed.info.tokenAmount.amount || 0); }, 0);
+    } catch (e) { if (isCancel(e)) throw e; }
+  });
+  graph.forEach(function (n) {
+    n.checked = true; n.now = 0;
+    n.nodes.forEach(function (x) {
+      x.kind = kind[x.addr] || null;
+      x.now = bal[x.addr] === undefined ? null : bal[x.addr];
+      if (x.now === null) n.checked = false;
+      else if (x.kind !== "program") n.now += x.now;   // what sits in a pool belongs to nobody in the network
+    });
+    n.nodes.sort(function (a, b) { return (b.now || 0) - (a.now || 0) || b.hold - a.hold; });
+  });
+  graph.sort(function (a, b) { return b.now - a.now || b.hold - a.hold; });
+  return graph;
+}

package/src/tokens.js

@@ -0,0 +1,103 @@
+import { TOKEN_PROGRAM, TOKEN_2022, SYSTEM_PROGRAM } from "./constants.js";
+import { isCancel } from "./errors.js";
+import { onCurve, b58bytes } from "./curve.js";
+import { uniq } from "./util.js";
+
+// SOL balance and every token the wallet holds (classic SPL + Token-2022), summed by mint
+export async function getTokens(client, wallet) {
+  const res = await Promise.all([
+    client.rpc("getBalance", [wallet]),
+    client.rpc("getTokenAccountsByOwner", [wallet, { programId: TOKEN_PROGRAM }, { encoding: "jsonParsed" }]),
+    client.rpc("getTokenAccountsByOwner", [wallet, { programId: TOKEN_2022 }, { encoding: "jsonParsed" }])
+  ]);
+  const tokens = {};
+  [res[1], res[2]].forEach(function (r) {
+    r.value.forEach(function (c) {
+      const info = c.account.data.parsed.info;
+      const q = Number(info.tokenAmount.uiAmount || 0);
+      if (q > 0) tokens[info.mint] = (tokens[info.mint] || 0) + q;
+    });
+  });
+  return { sol: res[0].value / 1e9, tokens: tokens };
+}
+
+// A mint account belongs to a token program; a wallet belongs to the System Program
+export async function isMint(client, addr) {
+  try {
+    const r = await client.rpc("getAccountInfo", [addr, { encoding: "jsonParsed" }]);
+    const v = r && r.value;
+    return !!(v && (v.owner === TOKEN_PROGRAM || v.owner === TOKEN_2022) && v.data && v.data.parsed && v.data.parsed.type === "mint");
+  } catch (e) { if (isCancel(e)) throw e; return false; }   // if it cannot be known, treat it as a wallet
+}
+
+export async function getMint(client, mint) {
+  const r = await client.rpc("getAccountInfo", [mint, { encoding: "jsonParsed" }]);
+  const p = r && r.value && r.value.data && r.value.data.parsed && r.value.data.parsed.info;
+  if (!p) return null;
+  return {
+    mintAuth: p.mintAuthority || null, freezeAuth: p.freezeAuthority || null,
+    supply: Number(p.supply || 0), decimals: Number(p.decimals || 0),
+    ext: (p.extensions || []).map(function (e) { return e.extension; })
+  };
+}
+
+// A key off the ed25519 curve has no private key: only a program can sign for it (a PDA), whoever
+// owns its account. PDAs that hold SOL (stake pool and AMM authorities) are owned by the System
+// Program like any wallet, so the owner alone would count them as people.
+export function kindOf(key, account, missingIsWallet) {
+  if (!onCurve(b58bytes(key))) return "program";
+  if (account) return account.owner === SYSTEM_PROGRAM ? "wallet" : "program";
+  return missingIsWallet ? "wallet" : "program";
+}
+
+// "wallet" or "program" for each address
+export async function accountKinds(client, addrs, missingIsWallet) {
+  if (!addrs.length) return {};
+  const r = await client.rpc("getMultipleAccounts", [addrs, { encoding: "base64", dataSlice: { offset: 0, length: 0 } }]);
+  const out = {};
+  addrs.forEach(function (k, i) { out[k] = kindOf(k, r.value[i], missingIsWallet); });
+  return out;
+}
+
+// Who controls the mint and freeze authorities: a person's wallet or a program (bridge, protocol)
+export async function getAuthKinds(client, info) {
+  const keys = [];
+  [info.mintAuth, info.freezeAuth].forEach(function (a) { if (a && keys.indexOf(a) < 0) keys.push(a); });
+  if (!keys.length) return {};
+  return accountKinds(client, keys, true);   // no account but on the curve: an empty wallet
+}
+
+// Concentration of the supply. Each large account is traced to its owner: a pool or a program
+// holding tokens is not a whale, so w1/w10 count only people's wallets.
+export async function getConc(client, mint, supply) {
+  const r = await client.rpc("getTokenLargestAccounts", [mint]);
+  const v = (r && r.value) || [];
+  if (!v.length || supply <= 0) throw new Error("no holder data");
+  const amts = v.map(function (x) { return Number(x.amount); });
+  const out = {
+    ok: false,
+    top1: amts[0] / supply * 100,
+    top10: amts.slice(0, 10).reduce(function (s, x) { return s + x; }, 0) / supply * 100
+  };
+  const addrs = v.map(function (x) { return x.address; });
+  if (addrs.some(function (x) { return !x; })) return out;
+  try {
+    const ta = await client.rpc("getMultipleAccounts", [addrs, { encoding: "jsonParsed" }]);
+    const owners = ta.value.map(function (x) {
+      return x && x.data && x.data.parsed && x.data.parsed.info && x.data.parsed.info.owner || null;
+    });
+    if (owners.some(function (o) { return !o; })) return out;
+    const kind = await accountKinds(client, uniq(owners), false);
+    const agg = {};
+    owners.forEach(function (o, i) { agg[o] = (agg[o] || 0) + amts[i]; });
+    const ws = [];
+    let prog = 0;
+    Object.keys(agg).forEach(function (o) { if (kind[o] === "wallet") ws.push(agg[o]); else prog += agg[o]; });
+    ws.sort(function (x, y) { return y - x; });
+    out.ok = true; out.nW = ws.length;
+    out.w1 = ws.length ? ws[0] / supply * 100 : 0;
+    out.w10 = ws.slice(0, 10).reduce(function (s, x) { return s + x; }, 0) / supply * 100;
+    out.prog = prog / supply * 100;
+  } catch (e) { if (isCancel(e)) throw e; }
+  return out;
+}

package/src/util.js

@@ -0,0 +1,29 @@
+export function sleep(ms) {
+  return new Promise(function (r) { setTimeout(r, ms); });
+}
+
+export function short(a) {
+  return a.slice(0, 4) + "…" + a.slice(-4);
+}
+
+// Runs fn over items with at most n in flight
+export async function pool(items, n, fn) {
+  let i = 0;
+  const workers = [];
+  for (let w = 0; w < Math.min(n, items.length); w++) {
+    workers.push((async function () {
+      while (i < items.length) { const k = i++; await fn(items[k], k); }
+    })());
+  }
+  await Promise.all(workers);
+}
+
+export function uniq(list) {
+  return list.filter(function (x, i) { return list.indexOf(x) === i; });
+}
+
+// Calls onProgress({step, ...data}, fraction) if the caller gave one; the engine never touches a UI
+// itself. Steps are codes (see i18n describeStep) so each app words them in its own language.
+export function progress(onProgress, step, frac, data) {
+  if (onProgress) onProgress(Object.assign({ step: step }, data), Math.max(0, Math.min(1, frac)));
+}

package/src/wallet.js

@@ -0,0 +1,80 @@
+import { ADDRESS_RE, KNOWN, LEVELS } from "./constants.js";
+import { ScanError } from "./errors.js";
+import { pool, progress } from "./util.js";
+import { getTokens, isMint } from "./tokens.js";
+import { getMarkets } from "./markets.js";
+import { assess } from "./risk.js";
+
+function checkAddress(addr) {
+  if (!ADDRESS_RE.test(addr || "")) throw new ScanError("INVALID_ADDRESS", "not a Solana address");
+}
+
+export function sortResults(list) {
+  return list.sort(function (a, b) {
+    return LEVELS.indexOf(a.lvl) - LEVELS.indexOf(b.lvl) || (b.sev || 0) - (a.sev || 0) || b.pts - a.pts || b.value - a.value;
+  });
+}
+
+/** Risk of a single token. Throws IS_NFT for NFTs. */
+export async function analyzeToken(client, mint, opts) {
+  opts = opts || {};
+  checkAddress(mint);
+  progress(opts.onProgress, "markets", 0.15);
+  const mkr = await getMarkets(client, [mint]);
+  progress(opts.onProgress, "token", 0.45);
+  const r = await assess(client, mint, mkr.data[mint] || null, { marketUnknown: mkr.failed.length > 0, skipConcentration: opts.skipConcentration });
+  if (!r) throw new ScanError("IS_NFT", "that address is an NFT, not a token");
+  progress(opts.onProgress, "done", 1);
+  return r;
+}
+
+/**
+ * Risk of every token a wallet holds.
+ *
+ * @param [opts.minUsd=1]      hide priced tokens worth less than this (dust)
+ * @param [opts.concurrency=3]
+ * @returns {wallet, sol, balances, total, hidden, results}
+ */
+export async function analyzeWallet(client, wallet, opts) {
+  opts = opts || {};
+  checkAddress(wallet);
+  const minUsd = opts.minUsd === undefined ? 1 : opts.minUsd;
+  const onProgress = opts.onProgress;
+  progress(onProgress, "wallet", 0.02);
+  const w = await getTokens(client, wallet);
+  const mints = Object.keys(w.tokens);
+  const res = { wallet: wallet, sol: w.sol, balances: w.tokens, total: mints.length, hidden: 0, results: [] };
+  if (!mints.length) return res;
+  progress(onProgress, "markets", 0.08);
+  const mkr = await getMarkets(client, mints, function (d, n) { progress(onProgress, "markets", 0.08 + 0.12 * d / n, { done: d, total: n }); });
+  const mk = mkr.data, failedMk = {};
+  mkr.failed.forEach(function (m) { failedMk[m] = 1; });
+
+  const out = [], todo = [];
+  mints.forEach(function (m) {
+    const pair = mk[m], price = Number((pair && pair.priceUsd) || 0);
+    let value = w.tokens[m] * price;
+    if (pair && pair.liqRaw) value = Math.min(value, pair.liquidity.usd);   // with inflated liquidity the price is fake too
+    if (KNOWN[m]) { out.push({ mint: m, sym: KNOWN[m], name: "", pts: 0, sev: 0, lvl: "LOW", known: true, type: null, lights: null, reasons: [{ code: "KNOWN_TOKEN", s: "ok" }], value: value, pair: pair, img: null }); return; }
+    if (price > 0 && value < minUsd) { res.hidden++; return; }
+    todo.push({ mint: m, pair: pair, value: value, unknown: !!failedMk[m] });
+  });
+
+  let done = 0;
+  await pool(todo, opts.concurrency || 3, async function (t) {
+    const r = await assess(client, t.mint, t.pair, { value: t.value, marketUnknown: t.unknown, skipConcentration: opts.skipConcentration });
+    if (r) out.push(r);
+    done++;
+    progress(onProgress, "tokens", 0.2 + 0.8 * done / Math.max(1, todo.length), { done: done, total: todo.length });
+  });
+  res.results = sortResults(out);
+  return res;
+}
+
+/** Detects whether the address is a token mint or a wallet and analyses it accordingly. */
+export async function analyzeAddress(client, addr, opts) {
+  checkAddress(addr);
+  progress(opts && opts.onProgress, "address", 0.01);
+  if (await isMint(client, addr)) return { kind: "token", token: await analyzeToken(client, addr, opts) };
+  return { kind: "wallet", wallet: await analyzeWallet(client, addr, opts) };
+}