solana-risk-engine 0.4.8 → 0.4.10

package/README.md

@@ -31,7 +31,7 @@ for (const l of r.lights)  // the four traffic lights
 | **Serial creators** | For markets under 7 days: how many other tokens the creator launched in the last 24 h (RugCheck). 2 or more is a warning, 5 or more a red flag. `recentLaunches(client, wallet)` counts the same on chain for the wallet that *paid* a launch, which catches farms that name a fresh creator each time. |
 | **Impostors** | Tokens using the symbol or name of a famous token (USDC, JUP, BONK, WIF, BTC, ETH...) with a different address. |
 | **Real brands** | About 320 real companies with no token on Solana (Spotify, Nike, Zara, Ferrari...). A token called just that is a red flag and **HIGH**; the brand as one word of a longer name is a warning. Everyday words that are also brands (Shell, Target, Puma) are left out, and markets at least 30 days old with $100k+ liquidity are not checked. |
-| **Known issuers and official tokens** | Tokenized shares from xStocks (recognised by their control keys) and official tokens from exchanges and Socios.com (bnSOL, bbSOL, cbBTC, club fan tokens..., by mint address) are shown as dependency on the issuer. Their Solana pools are often tiny because they trade on the exchange: that is a warning, not a red flag. |
+| **Known issuers and official tokens** | Stablecoins from Paxos (PYUSD, USDG), Circle (USDC, EURC) and Tether (USDT), tokenized shares from xStocks (all recognised by their control keys, taken from mints the issuer lists on its own pages) and official tokens from exchanges and Socios.com (bnSOL, bbSOL, cbBTC, club fan tokens..., by mint address) are shown as dependency on the issuer. Their large holders (treasury, custodians, exchanges) are shown but do not count as concentration, a 0% transfer fee is not a warning, and a tiny Solana pool is a warning, not a red flag. A short **trusted** list (Circle, Paxos, Tether, xStocks; `trustedIssuer()`) goes further: every light green, holders not checked. |
 | **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. |
 | **Bots and exchanges** | Wallets that made 200 transactions in under 2 days are marked `active` and are not counted as whales. |
 | **Funder clusters** | The fee payer of each holder's *first* transaction reveals who created it. Holders sharing a funder are grouped, since that is often one team splitting the supply. Exchange hot wallets are excluded as sources. |

package/package.json

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

@@ -157,11 +157,34 @@ export const OFFICIAL_TOKENS = {
 // (anyone can hand the mint authority to someone else's wallet) is not enough. Their control is the point of
 // the product: it is shown as dependency on the issuer, not as a creator who can rug
 export const ISSUERS = [
-  { name: "xStocks (Backed)", keys: [
+  // trusted: a short list SolFlag vouches for (1/11/2026: Circle, Paxos, Tether, xStocks): every light green,
+  // holders not checked. Other verified issuers and official tokens keep the dependency in yellow
+  { name: "xStocks (Backed)", trusted: true, keys: [
     "7pt9tkctJPK7PPNQJ77GKg8ZffSF6QxoMiCFYHxrtaCj",   // mint
     "JDq14BWvqCRFNu1krb12bcRpbGtJZ1FLEakMw6FdxJNs",   // freeze and pause (program)
     "5aMNNLQJwAEeoemTEMkv5NVjqKwvvefRYCQ5Z67HFvEq",   // permanent delegate, transfer hook, confidential transfers
     "S7vYFFWH6BjJyEsdrPQpqpYTqLTrPRK6KW3VwsJuRaS"     // share-split multiplier (scaled UI amount)
+  ] },
+  // Each mint below is listed by its issuer (URL); the keys are the ones those mints carry on-chain (1/11/2026).
+  // An issuer is only added with an official page for its mints: FDUSD was left out for lack of one.
+  { name: "Paxos", trusted: true, keys: [
+    // PYUSD 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo  https://docs.paxos.com/guides/stablecoin/pyusd/mainnet
+    // USDG  2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH  https://docs.paxos.com/guides/stablecoin/usdg/mainnet
+    "AxJkHRY3puoofyj7Pn512M1SGBgWroXMkEdNPQypkzbu",   // PYUSD mint
+    "2e99QgqSDtiJSi5omGRVeZJuqNFRZdpy2YgG3mBd1AB4",   // USDG mint
+    "2apBGMsS6ti9RyF5TwQTDswXBWskiJP2LD4cUEDqYJjk"    // freeze, permanent delegate, hook, fee (both)
+  ] },
+  { name: "Circle", trusted: true, keys: [
+    // USDC EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, EURC HzwqbKZw8HxMN6bF2yFZNrht3c2iXXzpKcFu7uBEDKtr
+    // https://developers.circle.com/stablecoins/usdc-contract-addresses , .../eurc-contract-addresses
+    "BJE5MMbqXjVwjAF7oxwPYXnTXDyspzZyt4vwenNw5ruG",   // USDC mint
+    "7dGbd2QZcCKcTndnHcTL8q7SMVXAkp688NTQYwrRCrar",   // USDC freeze
+    "Hy9168u7b2Toujh8SJKtKK8DWbyaBbXPzxm337R4o4XY",   // EURC mint
+    "6FF2CPcL6fat16QVJH6W27DeBcX7TSqbwY3a5wtyVJLC"    // EURC freeze
+  ] },
+  { name: "Tether", trusted: true, keys: [
+    // USDT Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB (FAMOUS.USDT)
+    "Q6XprfkF8RQQKoQVG33xT88H7wi8Uk1B1CC7YAs69Gi"     // USDT mint and freeze
   ] }
 ];
 

package/src/i18n/en.js

@@ -49,6 +49,8 @@ export default {
     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_TRUSTED: (d) => "Not counted: in a token from " + d.issuer + " the large holders are its treasury, custodians, exchanges and protocols",
+    CON_ISSUER: (d) => "The largest wallet holds " + pct(d.w1) + " and the top 10 hold " + pct(d.w10) + ": with a verified issuer these are usually its treasury, custodians, exchanges or protocols, so it does not count as a risk" + 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",
 
@@ -65,6 +67,7 @@ export default {
     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_TRUSTED_ISSUER: (d) => "Issued by " + d.issuer + ", one of the few regulated issuers SolFlag trusts. Like any issuer, it can freeze or claw back tokens under a legal order",
     DEP_KNOWN_ISSUER: (d) => "Issued by " + d.issuer + ": it can mint, freeze or move tokens, like any regulated issuer. You trust the issuer",
     DEP_NONE: () => "Does not depend on an issuer or a bridge"
   },

package/src/i18n/es.js

@@ -52,6 +52,8 @@ export default {
     CON_UNAVAILABLE: () => "No se pudo comprobar la concentración de holders (el servicio no respondió; prueba otra vez en un rato)",
     CON_ALL_POOLS: (d) => "Casi todo el supply está en pools o programas" + prog(d),
     CON_OK: (d) => "Sin concentración preocupante (mayor wallet individual: " + pct(d.w1) + ")" + prog(d),
+    CON_TRUSTED: (d) => "No cuenta: en un token de " + d.issuer + " los grandes holders son su tesorería, custodios, exchanges y protocolos",
+    CON_ISSUER: (d) => "La mayor wallet tiene el " + pct(d.w1) + " y las 10 mayores el " + pct(d.w10) + ": con un emisor verificado suelen ser su tesorería, custodios, exchanges o protocolos, no cuenta como riesgo" + prog(d),
     CON_HIGH: (d) => "La mayor wallet individual tiene el " + pct(d.w1) + " y las 10 mayores el " + pct(d.w10) + " del supply" + prog(d),
     CON_UNSPLIT: (d) => "No se pudo separar pools de personas. La mayor cuenta tiene el " + pct(d.top1) + " del supply",
 
@@ -68,6 +70,7 @@ export default {
     DEP_PROGRAM_AUTHORITY: () => "Un programa controla el mint o el freeze (puente o protocolo): hay que confiar en su código",
     DEP_PERMANENT_DELEGATE: () => "El emisor puede mover o quemar tus tokens (delegado permanente): confías en el emisor",
     DEP_STABLE_ISSUER: () => "Su valor depende de quien la emite y la respalda",
+    DEP_TRUSTED_ISSUER: (d) => "Lo emite " + d.issuer + ", un emisor regulado de los pocos que SolFlag considera de confianza. Como cualquier emisor, puede congelar o retirar tokens por orden legal",
     DEP_KNOWN_ISSUER: (d) => "Lo emite " + d.issuer + ": puede crear, congelar o mover tokens, como cualquier emisor regulado. Confías en el emisor",
     DEP_NONE: () => "No depende de un emisor ni de un puente"
   },

package/src/index.js

@@ -48,7 +48,7 @@ export { isOnCurve, onCurve, b58bytes } from "./curve.js";
 export { getTokens, getMint, getConc, getAuthKinds, isMint, accountKinds, kindOf } from "./tokens.js";
 export { getMarkets, realLiq, impostorOf, INFLATED_RATIO, geckoLiquidity, geckoPair, brandOf, copiesOf, fakeLiquidity, FAKE_LIQ_RATIO } from "./markets.js";
 export { rugcheckSummary, rugcheckReport, rugcheckGraph, netBalances, creatorLaunches, CREATOR_DEAD_MCAP } from "./rugcheck.js";
-export { score, issuerOf, tokenType, buildLights, levelFrom, dataOnly, reasonsFrom, assess, SERIAL_WARN, SERIAL_BAD, HISTORY_MIN, HISTORY_WARN, HISTORY_BAD_MIN, HISTORY_BAD } from "./risk.js";
+export { score, issuerOf, trustedIssuer, 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, onlyReceives, PASSIVE_SAMPLE, findFunder, findFunders, clusterByFunder, holderRows, creatorInfo, analyzeHolders,

package/src/risk.js

@@ -1,4 +1,4 @@
-import { EXT_POINTS, RANKS, PUMP_CURVE_DEXES, ISSUERS, OFFICIAL_TOKENS } from "./constants.js";
+import { EXT_POINTS, RANKS, PUMP_CURVE_DEXES, ISSUERS, OFFICIAL_TOKENS, FAMOUS } from "./constants.js";
 import { isCancel } from "./errors.js";
 import { short, sleep } from "./util.js";
 import { getMint, getAuthKinds, getConc } from "./tokens.js";
@@ -53,6 +53,9 @@ export function tokenType(info, pair, now) {
   // 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";
+  // a verified issuer's dollar or euro token is a stablecoin whatever pair DexScreener found (USDC showed
+  // "bridged" because its pair as base token is recent)
+  if (/USD|DOLLAR|EUR/i.test(sym) && issuerOf(info, pair && pair.baseToken && pair.baseToken.address)) 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";
@@ -72,6 +75,12 @@ export function issuerOf(info, mint) {
   return found ? found.name : null;
 }
 
+// Name of the issuer when it is on SolFlag's short trusted list, or null
+export function trustedIssuer(info, mint) {
+  const name = issuerOf(info, mint);
+  return name && ISSUERS.some(function (i) { return i.trusted && i.name === name; }) ? name : null;
+}
+
 // Extensions that only matter as they are set: a hook with no program and nobody able to add one does
 // nothing, and new accounts are only born frozen when the default state says "frozen". Mint info without
 // those details (older callers) keeps the old behaviour: the extension alone is enough
@@ -102,6 +111,7 @@ export function buildLights(info, conc, pair, value, type, rc, now, launches) {
   now = now || Date.now();
   const ak = (info && info.authKind) || {};
   const issuer = issuerOf(info, pair && pair.baseToken && pair.baseToken.address);
+  const trusted = issuer && trustedIssuer(info, pair && pair.baseToken && pair.baseToken.address);
   let it;
 
   // 1) creator control
@@ -115,7 +125,8 @@ export function buildLights(info, conc, pair, value, type, rc, now, launches) {
       if (info.ext.indexOf("transferHook") >= 0 && hookActive(info)) it.push(sig("CTL_TRANSFER_HOOK", "warn"));
       if (info.ext.indexOf("defaultAccountState") >= 0 && bornFrozen(info)) it.push(sig("CTL_DEFAULT_FROZEN", "warn"));
     }
-    if (info.ext.indexOf("transferFeeConfig") >= 0) it.push(sig("CTL_TRANSFER_FEE", "warn"));
+    // PYUSD and USDG carry the fee extension at 0%: under a known issuer that is how the product is built
+    if (info.ext.indexOf("transferFeeConfig") >= 0 && !(issuer && info.feeBps === 0)) it.push(sig("CTL_TRANSFER_FEE", "warn"));
     if (info.ext.indexOf("nonTransferable") >= 0) it.push(sig("CTL_NON_TRANSFERABLE", "warn"));
   }
   // Launch farms put out a token every few minutes and drop each one as soon as buyers arrive: in a
@@ -132,14 +143,18 @@ export function buildLights(info, conc, pair, value, type, rc, now, launches) {
   // 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")]);
+  if (trusted) concentration = mkLight("concentration", [sig("CON_TRUSTED", "ok", { issuer: issuer })]);
+  else 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");
+    let code = !conc.nW ? "CON_ALL_POOLS" : (st === "ok" ? "CON_OK" : "CON_HIGH");
+    // under a verified issuer the big holders are its treasury, custodians, exchanges and lending
+    // protocols, not someone about to dump: shown, not counted (PYUSD 56% in one wallet, 1/11)
+    if (issuer && code === "CON_HIGH") { code = "CON_ISSUER"; st = "ok"; }
     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 })]);
@@ -148,7 +163,9 @@ export function buildLights(info, conc, pair, value, type, rc, now, launches) {
   // 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 }));
+  // a verified issuer's token with little real liquidity on Solana trades elsewhere: not a trap
+  if (pair.liqRaw && issuer) it.push(sig(liq < 10000 ? "MKT_LIQ_VERY_LOW" : "MKT_LIQ_LOW", "warn", { liq: liq, offSolana: true }));
+  else 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 }));
@@ -180,13 +197,14 @@ export function buildLights(info, conc, pair, value, type, rc, now, launches) {
 
   // 4) dependency on an issuer or a bridge
   it = [];
-  if (issuer) it.push(sig("DEP_KNOWN_ISSUER", "warn", { issuer: issuer }));
+  if (trusted) it.push(sig("DEP_TRUSTED_ISSUER", "ok", { issuer: issuer }));
+  else if (issuer) it.push(sig("DEP_KNOWN_ISSUER", "warn", { issuer: issuer }));
   else 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"));
+  if (type === "STABLE" && !trusted) it.push(sig("DEP_STABLE_ISSUER", "warn"));
   const dependency = mkLight("dependency", it, sig("DEP_NONE", "ok"));
 
   return [control, concentration, market, dependency];
@@ -253,7 +271,9 @@ export async function assess(client, mint, pair, opts) {
   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 };
+  // a trusted issuer's holders are not checked (its treasury and exchanges; from the browser the public RPC
+  // often cannot list USDC's holders, which left it "unchecked" and medium)
+  if (info && pair && (opts.skipConcentration || trustedIssuer(info, mint))) 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++) {
@@ -274,7 +294,10 @@ export async function assess(client, mint, pair, opts) {
     const front = [];
     if (imp) front.push(sig("IMPOSTOR", "bad", { symbol: imp.sym, real: imp.real }));
     if (brand) front.push(sig(brand.exact ? "BRAND_COPY" : "BRAND_NAME", brand.exact ? "bad" : "warn", { brand: brand.brand }));
-    if (copies && !imp && !official) {
+    // the real USDC/USDT is rarely the base token of a DexScreener pair, so the search found an older
+    // "USDC" and called the real one the copy (USDC and USDT showed HIGH, 1/11)
+    const canon = Object.keys(FAMOUS).some(function (k) { return FAMOUS[k] === mint; }) || !!issuerOf(info, mint);
+    if (copies && !imp && !official && !canon) {
       const strong = copies.origLiq >= 50000 && copies.origLiq >= 10 * Math.max(copies.liq, 1);
       front.push(sig("COPYCAT", strong ? "bad" : "warn", copies));
     }
@@ -285,7 +308,7 @@ export async function assess(client, mint, pair, opts) {
     const lf = levelFrom(lights); lvl = lf.lvl; sev = lf.sev; reasons = reasonsFrom(lights);
     // a copy of a famous token or a real company, or liquidity faked 100 times over, is high risk even
     // when everything else looks normal: it is built to look like something it is not
-    if (imp || (brand && brand.exact) || fakeLiquidity(pair)) { if (lvl !== "HIGH") sev += 5; lvl = "HIGH"; }
+    if (imp || (brand && brand.exact) || (fakeLiquidity(pair) && !issuerOf(info, mint))) { if (lvl !== "HIGH") sev += 5; lvl = "HIGH"; }
   } else {
     const s = score(info);
     pts = s.pts; reasons = s.why; lvl = pts >= 25 ? "SPAM" : "NO_MARKET";

package/src/tokens.js

@@ -45,11 +45,18 @@ export async function getMint(client, mint) {
     // "default account state" only matters when new accounts are born frozen
     hook: { program: hook.programId || null, auth: hook.authority || null },
     defaultState: state("defaultAccountState").accountState || null,
+    // transfer fee in basis points (the higher of the current and the scheduled one); null when not set
+    feeBps: feeBps(state("transferFeeConfig")),
     // every key that controls something in the extensions (delegate, hook, pause, metadata...)
     extKeys: extKeys(exts)
   };
 }
 
+function feeBps(s) {
+  const a = s.newerTransferFee && s.newerTransferFee.transferFeeBasisPoints, b = s.olderTransferFee && s.olderTransferFee.transferFeeBasisPoints;
+  return (typeof a === "number" || typeof b === "number") ? Math.max(Number(a) || 0, Number(b) || 0) : null;
+}
+
 function extKeys(exts) {
   const out = [];
   exts.forEach(function (e) {