solana-risk-engine 0.4.0 → 0.4.2

package/README.md

@@ -73,7 +73,7 @@ Methods (all accept `{ onProgress(step, fraction) }`):
 | `analyzeToken(mint, { skipCreator })` | `{ lvl, sev, type, lights, reasons, impostor, pair, creator, ... }` |
 | `analyzeWallet(wallet, { minUsd })` | `{ sol, balances, total, hidden, results: [token results] }` |
 | `analyzeAddress(addr)` | `{ kind: "token" \| "wallet", ... }`, detected automatically |
-| `analyzeHolders(mint)` | `{ rows, clusters, hotGroups, creator, ... }`. Best with your own RPC. |
+| `analyzeHolders(mint)` | `{ rows, clusters, groups, hotGroups, creator, mode, ageDays, signals, ... }`. Young tokens (under 14 days) also trace busy wallets; a source over 350 tx/h counts as an exchange; a group over 10% (young) or 15% (mature) of the supply gives a `HOLD_GROUP` signal. Best with your own RPC. |
 | `estimatePnl(wallets)` | `{ pnl: { [wallet]: { realized, unreal, total, ret, st, open } } }`. Needs Helius. |
 | `takeSnapshots(wallets)` | Today's holdings. Store them yourself and pass them to `diffSnapshots(prev, next)`. |
 | `confluence(wallets, { pct, withPnl, pnlFilter })` | Tokens held in common, with risk. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-risk-engine",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Explainable risk analysis for Solana tokens and wallets: creator control, real holder concentration, inflated liquidity, impostor tokens, funder clusters and PnL. Zero dependencies, runs in Node and the browser.",
   "type": "module",
   "main": "./src/index.js",

package/src/holders.js

@@ -64,7 +64,13 @@ export async function findFunder(client, addr) {
     }
     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" }]);
+    // version 1 is needed for recent transactions; an older RPC that does not know it yet gets 0
+    let tx;
+    try { tx = await client.rpc("getTransaction", [earliest, { maxSupportedTransactionVersion: 1, encoding: "jsonParsed" }]); }
+    catch (e) {
+      if (isCancel(e) || !/version|invalid param/i.test(e.message || "")) throw e;
+      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]);
@@ -83,6 +89,44 @@ export async function findFunders(client, wallets, onStep) {
   return out;
 }
 
+// Exchanges and launch platforms move thousands of transactions an hour; the busiest farms and
+// distributors seen in the 28/10 study did 1-150. Above this, a wallet is infrastructure, not a person.
+export const EXCHANGE_PER_HOUR = 350;
+// Young tokens (under 14 days) are read for the team's split, mature ones for what stayed hidden
+export const YOUNG_DAYS = 14;
+// A group (holders sharing the source of their first SOL) over this % of the supply warns
+export const HOLD_GROUP_YOUNG = 10, HOLD_GROUP_MATURE = 15;
+
+// Transactions per hour over a page of signatures (newest first)
+export function perHour(sigs) {
+  if (!sigs || sigs.length < 2) return 0;
+  const span = ((sigs[0].blockTime || 0) - (sigs[sigs.length - 1].blockTime || 0)) / 3600;
+  return span > 0 ? sigs.length / span : sigs.length * 3600;
+}
+
+// Rate of each source wallet (one request each)
+export async function sourceRates(client, addrs, onStep) {
+  const out = {};
+  let done = 0;
+  await pool(addrs, 3, async function (a) {
+    try { out[a] = perHour(await client.rpc("getSignaturesForAddress", [a, { limit: 1000 }])); }
+    catch (e) { if (isCancel(e)) throw e; out[a] = null; }
+    done++; if (onStep) onStep(done, addrs.length);
+  });
+  return out;
+}
+
+// Groups by size of their share of the supply, biggest first: [{id, funder, members, pct}]
+export function groupList(clusters, rows) {
+  const by = {};
+  rows.forEach(function (r) {
+    const c = clusters[r.owner]; if (!c) return;
+    const g = by[c.id] || (by[c.id] = { id: c.id, funder: c.funder, members: [], pct: 0 });
+    g.members.push(r.owner); g.pct += r.pct;
+  });
+  return Object.keys(by).map(function (k) { return by[k]; }).sort(function (a, b) { return b.pct - a.pct; });
+}
+
 // 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).
@@ -153,7 +197,14 @@ export async function creatorInfo(client, mint, onProgress) {
  * 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).
  *
+ * Young tokens (under 14 days: market age from DexScreener, else RugCheck's detectedAt) also trace the
+ * busy wallets: on day one most big holders trade a lot and the team's split hides among them. A group
+ * over 10% of the supply in a young token (bad) or 15% in a mature one (warn) is a HOLD_GROUP signal.
+ *
  * @param [opts.creator=true]  also look up the creator and insider networks on RugCheck
+ * @param [opts.createdAt]     ms when its market started, if the caller knows it
+ * @param [opts.now]
+ * @returns {..., mode: "young"|"mature", ageDays, groups, signals}
  */
 export async function analyzeHolders(client, mint, opts) {
   opts = opts || {};
@@ -163,18 +214,36 @@ export async function analyzeHolders(client, mint, opts) {
   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; });
+  const now = opts.now || Date.now();
+  let created = opts.createdAt || (pair && pair.pairCreatedAt) || null;
+  if (!created) {
+    const rc = await rugcheckReport(client, mint);
+    if (rc && rc.detectedAt) created = Date.parse(rc.detectedAt) || null;
+  }
+  const ageDays = created ? Math.max(0, (now - created) / 86400000) : null;
+  const mode = ageDays !== null && ageDays < YOUNG_DAYS ? "young" : "mature";
+  // who is traced: people always; in young tokens also the busy wallets
+  const traced = hr.rows.filter(function (r) { return r.kind === "wallet" || (mode === "young" && r.kind === "active"); })
+    .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 }); });
+  if (traced.length >= 2) {
+    const funders = await findFunders(client, traced, 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 }); });
+      // a source is an exchange when it moves more than EXCHANGE_PER_HOUR transactions an hour (the bot
+      // test, 200 in 2 days, also caught distributors doing ~50 an hour and hid their groups)
+      const rates = await sourceRates(client, srcs, function (c, n) { progress(onProgress, "exchangeSources", 0.88 + 0.02 * c / Math.max(1, n), { done: c, total: n }); });
+      const hot = {};
+      srcs.forEach(function (f) { if (rates[f] > EXCHANGE_PER_HOUR) hot[f] = true; });
       hotGroups = srcs.filter(function (f) { return hot[f]; }).length;
       if (hotGroups) clusters = clusterByFunder(funders, hot);
     }
   }
+  const groups = groupList(clusters, hr.rows), signals = [];
+  const limit = mode === "young" ? HOLD_GROUP_YOUNG : HOLD_GROUP_MATURE;
+  if (groups[0] && groups[0].pct > limit)
+    signals.push({ code: "HOLD_GROUP", s: mode === "young" ? "bad" : "warn", data: { n: groups[0].members.length, pct: groups[0].pct, id: groups[0].id, funder: groups[0].funder } });
   let creator = null;
   if (opts.creator !== false) {
     progress(onProgress, "creator", 0.9);
@@ -184,6 +253,7 @@ export async function analyzeHolders(client, mint, opts) {
   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
+    mintAuth: !!b.info.mintAuth, freezeAuth: !!b.info.freezeAuth, clusters: clusters, hotGroups: hotGroups, creator: creator,
+    mode: mode, ageDays: ageDays, groups: groups, signals: signals
   };
 }

package/src/i18n/en.js

@@ -37,6 +37,7 @@ export default {
     CTL_ONLY_PROGRAMS: () => "Only program-controlled authorities (see dependency)",
     CTL_NONE: () => "No active authorities: nobody can mint more or freeze",
     CTL_SERIAL_CREATOR: (d) => "The creator launched " + d.n + " other tokens in the last 24 h (per RugCheck): a serial launcher, who usually drops each token as soon as buyers arrive",
+    HOLD_GROUP: (d) => d.n + " holders got their first SOL from the same wallet and together hold " + pct(d.pct) + " of the supply: most likely one person or team",
     CTL_CREATOR_HISTORY: (d) => "Of the " + d.old + " tokens the creator launched before (over 24 h ago), " + d.dead + " stayed under $10,000 market cap (per RugCheck): their launches rarely take off",
     IMPOSTOR: (d) => "Impersonates " + d.symbol + ": the real " + d.symbol + " has another address (" + short(d.real) + "). It is a copy, almost certainly a scam",
 

package/src/i18n/es.js

@@ -40,6 +40,7 @@ export default {
     CTL_ONLY_PROGRAMS: () => "Solo hay autoridades controladas por un programa (ver dependencia)",
     CTL_NONE: () => "Sin autoridades activas: nadie puede crear más ni congelar",
     CTL_SERIAL_CREATOR: (d) => "El creador ha lanzado " + d.n + " tokens más en las últimas 24 h (según RugCheck): es un lanzador en serie, que suele abandonar cada token en cuanto llegan compradores",
+    HOLD_GROUP: (d) => d.n + " holders recibieron su primer SOL de la misma wallet y juntos tienen el " + pct(d.pct) + " del suministro: probablemente son la misma persona o equipo",
     CTL_CREATOR_HISTORY: (d) => "De los " + d.old + " tokens que el creador lanzó antes (hace más de 24 h), " + d.dead + " se quedaron por debajo de 10.000 $ de capitalización (según RugCheck): sus lanzamientos no suelen despegar",
     IMPOSTOR: (d) => "Se hace pasar por " + d.symbol + ": el " + d.symbol + " de verdad tiene otra dirección (" + short(d.real) + "). Es una copia, casi seguro una estafa",
 

package/src/index.js

@@ -49,7 +49,8 @@ export { rugcheckSummary, rugcheckReport, rugcheckGraph, netBalances, creatorLau
 export { score, tokenType, buildLights, levelFrom, dataOnly, reasonsFrom, assess, SERIAL_WARN, SERIAL_BAD, HISTORY_MIN, HISTORY_WARN, HISTORY_BAD_MIN, HISTORY_BAD } from "./risk.js";
 export { recentLaunches } from "./launch.js";
 export { analyzeToken, analyzeWallet, analyzeAddress, sortResults } from "./wallet.js";
-export { holderBase, markBusy, findFunder, findFunders, clusterByFunder, holderRows, creatorInfo, analyzeHolders } from "./holders.js";
+export { holderBase, markBusy, findFunder, findFunders, clusterByFunder, holderRows, creatorInfo, analyzeHolders,
+  perHour, sourceRates, groupList, EXCHANGE_PER_HOUR, YOUNG_DAYS, HOLD_GROUP_YOUNG, HOLD_GROUP_MATURE } from "./holders.js";
 export { fetchSwaps, solHistory, priceSeries, parseTrades, pnlFromTrades, pnlStatus, estimatePnl } from "./pnl.js";
 export { capSnap, chgDiff, chgAgg, takeSnapshots, diffSnapshots } from "./changes.js";
 export { confluence, commonHolders } from "./confluence.js";

package/src/tokens.js

@@ -1,103 +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;
-}
+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;
+}