solana-risk-engine 0.4.7 → 0.4.9

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. |
 | **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.7",
+  "version": "0.4.9",
   "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

@@ -162,6 +162,27 @@ export const ISSUERS = [
     "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", 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", 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", keys: [
+    // USDT Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB (FAMOUS.USDT)
+    "Q6XprfkF8RQQKoQVG33xT88H7wi8Uk1B1CC7YAs69Gi"     // USDT mint and freeze
   ] }
 ];
 

package/src/i18n/en.js

@@ -43,12 +43,13 @@ export default {
     COPYCAT: (d) => "There " + (d.n === 1 ? "is another token" : "are " + d.n + " more tokens") + " with the same name and ticker; the oldest one with a real market (" + short(d.original) + ", " + d.days + (d.days === 1 ? " day" : " days") + " old) is not this one: check you have the right address",
     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",
+    IMPOSTOR: (d) => "Not the original " + d.symbol + ". Make sure it is the token you want",
 
     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_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",
 

package/src/i18n/es.js

@@ -46,12 +46,13 @@ export default {
     COPYCAT: (d) => "Hay " + (d.n === 1 ? "otro token" : d.n + " tokens más") + " con el mismo nombre y ticker; el más antiguo con mercado real (" + short(d.original) + ", de hace " + d.days + (d.days === 1 ? " día" : " días") + ") no es este: comprueba que tienes la dirección correcta",
     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",
+    IMPOSTOR: (d) => "No es el " + d.symbol + " original. Comprueba que es el token que buscas",
 
     CON_SKIPPED: () => "Sin comprobar la concentración de holders",
     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_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",
 

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";
@@ -115,7 +115,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
@@ -139,7 +140,10 @@ export function buildLights(info, conc, pair, value, type, rc, now, launches) {
     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 +152,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 }));
@@ -274,7 +280,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 +294,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) {