solana-risk-engine 0.1.0 → 0.2.0

package/README.md

@@ -24,9 +24,9 @@ for (const l of r.lights)  // the four traffic lights
 
 | Check | How |
 |---|---|
-| **Creator control** | Mint/freeze authority still active, and whether it sits in a person's wallet or a program (bridge/protocol). For keys with no account, it checks whether the key is on the ed25519 curve. Risky Token-2022 extensions: permanent delegate, transfer hook, transfer fee, non-transferable, default-frozen accounts. |
+| **Creator control** | Mint/freeze authority still active, and whether it sits in a person's wallet or a program (bridge, protocol, staking pool). A key off the ed25519 curve is always a program (PDA), even when the System Program owns its account. Risky Token-2022 extensions: permanent delegate, transfer hook, transfer fee, non-transferable, default-frozen accounts. |
 | **Real concentration** | Largest accounts are traced to their owners. Pools and programs are separated from people, so `w1`/`w10` measure *people*, not AMM vaults. |
-| **Inflated liquidity** | DexScreener values both sides of a pool at the pool's price. A pool with 4B of a token against 2 USDC shows "$4,000M liquidity". The engine recomputes it from the real side (USDC/USDT/SOL) only. |
+| **Inflated liquidity** | DexScreener values both sides of a pool at the pool's price. A pool with 4B of a token against 2 USDC shows "$4,000M liquidity". The engine recomputes it from the real side (USDC/USDT/SOL). It only flags extreme gaps (real side under 5%), because concentrated-liquidity pools are lopsided by nature. |
 | **Unlocked LP** | % of LP locked/burned via RugCheck. It only counts for markets under 90 days old, so veteran tokens don't get false positives. |
 | **Impostors** | Tokens using the symbol or name of a famous token (USDC, JUP, BONK, WIF...) with a different address. |
 | **Token type** | `STABLE`, `TOKENIZED`, `BRIDGED`, `CREATOR`, `OPEN`. Each type is judged by the rules that fit it: a bridged token normally has a program as mint authority, a memecoin does not. |
@@ -37,7 +37,16 @@ for (const l of r.lights)  // the four traffic lights
 | **Confluence** | Tokens held in common by a group of wallets, each one risk-assessed. Also the reverse: people who are top holders of several tokens. |
 | **Change tracking** | Snapshots and diffs (new / bought more / sold part / sold all) per wallet and aggregated across many wallets. |
 
-Anything that could not be checked is marked `na`. It never counts as "fine": a token with a missing check can be **medium** at best, and `dataOnly(r)` tells you when that is the only reason.
+### How the level is decided
+
+- Two red lights, or one red and one yellow, give **HIGH**.
+- One red, or two yellows, give **MEDIUM**.
+- Otherwise the level is **LOW**, with two exceptions that raise it to **MEDIUM**:
+  - **A check could not run.** Lights that could not be checked are marked `na`, and they never count as "fine". `dataOnly(r)` tells you when this is the only reason.
+  - **The market is under 7 days old.** It has no track record yet.
+- An impostor of a famous token is always **HIGH**.
+
+A single yellow on an established token stays LOW, because those warnings are normal for its type (a staking pool's program-controlled mint, for example). This was measured on 62 real tokens: the 7-day rule moved 9 brand-new tokens from low to medium and no established one.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-risk-engine",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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/client.js

@@ -139,5 +139,5 @@ export function createClient(opts) {
     return rpcAt(vibeRpc, method, params, 6);   // more retries: its limit sometimes trips even when the queue is respected
   }
 
-  return { rpc: rpc, jfetch: jfetch, softJson: softJson, ownRpc: ownRpc, heliusKey: heliusKey, checkAbort: checkAbort, rpcUrl: rpcUrl };
+  return { rpc: rpc, jfetch: jfetch, softJson: softJson, ownRpc: ownRpc, heliusKey: heliusKey, checkAbort: checkAbort, rpcUrl: rpcUrl, retryDelayMs: opts.retryDelayMs };
 }

package/src/index.js

@@ -43,8 +43,8 @@ export { createClient };
 export { ScanError, isCancel } from "./errors.js";
 export * from "./constants.js";
 export { isOnCurve, onCurve, b58bytes } from "./curve.js";
-export { getTokens, getMint, getConc, getAuthKinds, isMint, accountKinds } from "./tokens.js";
-export { getMarkets, realLiq, impostorOf } from "./markets.js";
+export { getTokens, getMint, getConc, getAuthKinds, isMint, accountKinds, kindOf } from "./tokens.js";
+export { getMarkets, realLiq, impostorOf, INFLATED_RATIO } from "./markets.js";
 export { rugcheckSummary, rugcheckReport, rugcheckGraph, netBalances } from "./rugcheck.js";
 export { score, tokenType, buildLights, levelFrom, dataOnly, reasonsFrom, assess } from "./risk.js";
 export { analyzeToken, analyzeWallet, analyzeAddress, sortResults } from "./wallet.js";

package/src/markets.js

@@ -5,14 +5,19 @@ import { sleep } from "./util.js";
 // DexScreener values both sides of a pool at the pool's own price. A scammer creates a pool with
 // 4 billion of their token against 2 real USDC and it shows "liquidity $4,000M". What you can actually
 // take out when selling is the real-token side (USDC, USDT or SOL): if that is much smaller, it wins.
+// Concentrated-liquidity pools (Orca Whirlpools, Raydium CLMM, Meteora DLMM) are lopsided by nature,
+// often 10-20% real side, so only an extreme gap counts: real side under 5% of the reported value.
+// The scams this targets sit far below that (2 USDC against "$4,000M" is 0.00000005%).
 // Mutates the pair: keeps the reported figure in liqRaw and replaces liquidity.usd with the real one.
+export const INFLATED_RATIO = 0.05;
+
 export function realLiq(p) {
   const l = p.liquidity, qa = p.quoteToken && p.quoteToken.address;
   if (!l || !l.usd || (qa !== USDC && qa !== USDT && qa !== WSOL)) return;
   const pn = Number(p.priceNative), pu = Number(p.priceUsd), q = Number(l.quote);
   if (!(pn > 0 && pu > 0 && q >= 0)) return;
   const real = 2 * q * pu / pn;   // pu/pn = USD price of the real token
-  if (real < 0.25 * l.usd) { p.liqRaw = l.usd; p.liquidity = Object.assign({}, l, { usd: real }); }
+  if (real < INFLATED_RATIO * l.usd) { p.liqRaw = l.usd; p.liquidity = Object.assign({}, l, { usd: real }); }
 }
 
 // A token using the symbol (or name) of a famous one but with another address is a copy

package/src/risk.js

@@ -151,6 +151,11 @@ export function levelFrom(lights) {
   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) };
 }
 
@@ -200,7 +205,7 @@ export async function assess(client, mint, pair, opts) {
     // 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(opts.retryDelayMs === undefined ? 1500 : opts.retryDelayMs); }
+      catch (e) { if (isCancel(e)) throw e; conc = null; if (!tryC) await sleep(client.retryDelayMs === undefined ? 1500 : client.retryDelayMs); }
     }
   }
   const rc = await rcPromise;

package/src/rugcheck.js

@@ -1,6 +1,6 @@
-import { RUGCHECK, SYSTEM_PROGRAM } from "./constants.js";
+import { RUGCHECK } from "./constants.js";
 import { isCancel } from "./errors.js";
-import { onCurve, b58bytes } from "./curve.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,
@@ -42,7 +42,7 @@ export async function netBalances(client, mint, graph) {
     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) { const v = oa.value[k]; kind[a] = v ? (v.owner === SYSTEM_PROGRAM ? "wallet" : "program") : (onCurve(b58bytes(a)) ? "wallet" : "program"); });
+      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) {

package/src/tokens.js

@@ -41,16 +41,21 @@ export async function getMint(client, mint) {
   };
 }
 
-// "wallet" or "program" for each address, from who owns its account (or the curve when it has none)
-export async function accountKinds(client, addrs, curveFallback) {
+// 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) {
-    const v = r.value[i];
-    if (v) out[k] = v.owner === SYSTEM_PROGRAM ? "wallet" : "program";
-    else out[k] = curveFallback ? (onCurve(b58bytes(k)) ? "wallet" : "program") : "program";
-  });
+  addrs.forEach(function (k, i) { out[k] = kindOf(k, r.value[i], missingIsWallet); });
   return out;
 }
 
@@ -59,7 +64,7 @@ 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: an empty wallet is on the curve, a PDA is not
+  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