solana-risk-engine 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 panpontomate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,30 @@
+# solana-risk-engine (español)
+
+Es el motor del Escáner de Wallets convertido en librería: análisis de riesgo explicable para tokens y wallets de Solana. No tiene dependencias, funciona en Node 18+ y en el navegador, y usa RPCs gratuitos si no se le da otro.
+
+El README principal está en inglés ([README.md](README.md)) porque los grants y la mayoría de desarrolladores lo leen así. Las traducciones al español están en `src/i18n/es.js` y conservan los textos del escáner original.
+
+## Uso rápido
+
+```js
+import { createScanner, explainLight, lightLabel, levelLabel } from "solana-risk-engine";
+
+const scanner = createScanner();   // o createScanner({ rpcUrl: "https://mainnet.helius-rpc.com/?api-key=..." })
+const r = await scanner.analyzeToken("JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN");
+
+console.log(levelLabel(r, "es"));                       // "Riesgo bajo"
+for (const l of r.lights) console.log(lightLabel(l.k, "es"), explainLight(l, "es"));
+```
+
+## Línea de comandos
+
+```sh
+npx solana-risk <token-o-wallet>
+npx solana-risk holders <mint> --rpc "https://mainnet.helius-rpc.com/?api-key=..."
+```
+
+## Tests
+
+```sh
+npm test
+```

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# solana-risk-engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Explainable risk analysis for Solana tokens and wallets. **Zero dependencies**, runs in **Node 18+ and the browser**, works with free public RPCs out of the box.
+
+It doesn't stop at a single score. Every verdict comes with the **signals** behind it, as stable codes plus the numbers involved. Apps can show them in any language (Spanish and English are included).
+
+```js
+import { createScanner, explainLight, lightLabel, levelLabel } from "solana-risk-engine";
+
+const scanner = createScanner();                      // free PublicNode + Vibe Station, or { rpcUrl }
+const r = await scanner.analyzeToken("7xKX...gAsU");
+
+console.log(r.lvl);        // "HIGH"
+console.log(r.type);       // "CREATOR"
+for (const l of r.lights)  // the four traffic lights
+  console.log(l.s, lightLabel(l.k, "en"), "-", explainLight(l, "en"));
+// bad  Creator control - The creator can mint more tokens (mint authority active)
+// bad  Concentration   - The largest individual wallet holds 50% and the top 10 hold 60% of the supply
+// bad  Market and exit - Very low liquidity ($5,000). Very new market (3 days)
+// ok   Dependency      - Does not depend on an issuer or a bridge
+```
+
+## What it detects
+
+| 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. |
+| **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. |
+| **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. |
+| **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. |
+| **Creator history** | Other tokens by the same creator and their risk, rugged flag, and insider networks with today's on-chain balances (RugCheck). |
+| **Wallet PnL** | FIFO realized and unrealized PnL from the last ~300 swaps, valued with historical SOL prices (Helius + CoinGecko). |
+| **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.
+
+## Install
+
+```sh
+npm install solana-risk-engine
+```
+
+## API
+
+### `createScanner(options)`
+
+| Option | |
+|---|---|
+| `rpcUrl` | Your own RPC (Helius, Triton, QuickNode...). Without it, PublicNode is used, with Solana Vibe Station (rate-limited queue) for the methods PublicNode blocks. |
+| `heliusApiKey` | For PnL. Taken from `rpcUrl` automatically when that is a Helius URL. It is never sent anywhere else. |
+| `signal` | An `AbortSignal`. Aborting rejects pending work with `ScanError` code `CANCELLED`. |
+| `fetch` | Custom fetch (tests, proxies). |
+
+Methods (all accept `{ onProgress(step, fraction) }`):
+
+| Method | Returns |
+|---|---|
+| `analyzeToken(mint)` | `{ lvl, sev, type, lights, reasons, impostor, pair, ... }` |
+| `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. |
+| `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. |
+| `commonHolders(mints, { min })` | Wallets that are top holders of several tokens. |
+
+Every lower-level function is exported too (`buildLights`, `levelFrom`, `realLiq`, `clusterByFunder`, `chgDiff`, `pnlFromTrades`...). Most are pure functions that are easy to reuse and test.
+
+### Results
+
+```js
+{
+  lvl: "HIGH" | "MEDIUM" | "LOW" | "SPAM" | "NO_DATA" | "NO_MARKET",
+  type: "STABLE" | "TOKENIZED" | "BRIDGED" | "CREATOR" | "OPEN" | null,
+  lights: [                       // null for tokens without a market
+    { k: "control" | "concentration" | "market" | "dependency",
+      s: "ok" | "na" | "warn" | "bad",
+      items: [{ code: "MKT_LIQ_INFLATED", s: "bad", data: { reported: 4e9, real: 2 } }] }
+  ],
+  reasons: [ ...every non-ok signal ],
+  sev: 6                          // for sorting within a level
+}
+```
+
+### Texts and languages
+
+```js
+import { describe, explainLight, levelLabel, typeInfo, describeStep, describeError, addLanguage } from "solana-risk-engine";
+
+describe({ code: "MKT_LIQ_VERY_LOW", data: { liq: 3000 } }, "es");   // "Liquidez muy baja (3.000 $)"
+describeError(err, "en", { ownRpc: true });                          // friendly message for any ScanError
+addLanguage("pt", { signals: { ... }, levels: { ... } });            // same shape as src/i18n/en.js
+```
+
+### Errors
+
+The engine throws `ScanError` with a stable `code`: `CANCELLED`, `HTTP`, `NETWORK`, `RPC`, `DEX_UNREACHABLE`, `HELIUS_REQUIRED`, `SOL_PRICE`, `INVALID_ADDRESS`, `NOT_A_TOKEN`, `IS_NFT`, `NO_HOLDERS`, `TOO_FEW_WALLETS`, `TOO_FEW_TOKENS`.
+
+Optional extras (RugCheck) never throw. If they fail, the analysis goes on without them.
+
+## CLI
+
+```sh
+npx solana-risk <token-or-wallet> --lang en
+npx solana-risk holders <mint> --rpc "https://mainnet.helius-rpc.com/?api-key=..."
+npx solana-risk <mint> --json
+```
+
+## Data sources
+
+- Solana RPC: [PublicNode](https://solana-rpc.publicnode.com), [Solana Vibe Station](https://solanavibestation.com), or yours
+- [DexScreener](https://dexscreener.com): pairs, price, liquidity, volume
+- [RugCheck](https://rugcheck.xyz): LP lock, creator, insider networks (optional)
+- [Helius](https://helius.dev): parsed swap history for PnL (optional, your key)
+- [CoinGecko](https://coingecko.com): SOL price history for PnL
+
+## Development
+
+```sh
+npm test      # node --test, no network needed: the network is mocked
+```
+
+## Disclaimer
+
+This is a heuristic tool, not financial advice. A "low risk" result means the engine found none of the signals it looks for. It does not mean the token is safe.
+
+## License
+
+MIT

package/bin/solana-risk.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// Minimal command line scanner:
+//   node examples/cli.js <token-or-wallet> [--lang en] [--rpc https://...] [--json]
+//   node examples/cli.js holders <mint> --rpc https://mainnet.helius-rpc.com/?api-key=...
+import {
+  createScanner, describe, explainLight, lightLabel, levelLabel, typeInfo, describeStep, describeError, format
+} from "../src/index.js";
+
+const args = process.argv.slice(2);
+function opt(name) { const i = args.indexOf("--" + name); return i >= 0 ? args.splice(i, 2)[1] : undefined; }
+function flag(name) { const i = args.indexOf("--" + name); if (i >= 0) { args.splice(i, 1); return true; } return false; }
+
+const lang = opt("lang") || "es";
+const rpcUrl = opt("rpc") || process.env.SOLANA_RPC_URL;
+const asJson = flag("json");
+const mode = args[0] === "holders" ? args.shift() : "address";
+const addr = args[0];
+
+if (!addr) {
+  console.error("usage: solana-risk <token-or-wallet> [--lang es|en] [--rpc URL] [--json]\n       solana-risk holders <mint> [--rpc URL]");
+  process.exit(1);
+}
+
+const ctrl = new AbortController();
+process.on("SIGINT", () => ctrl.abort());
+const scanner = createScanner({ rpcUrl: rpcUrl, signal: ctrl.signal });
+const f = format(lang);
+const onProgress = asJson ? undefined : (p, frac) => process.stderr.write("\r" + Math.round(frac * 100) + "% " + describeStep(p, lang) + "\x1b[K");
+const ICON = { ok: "🟢", na: "⚪", warn: "🟡", bad: "🔴" };
+
+function printToken(r) {
+  console.log(`\n${r.sym}${r.name ? " · " + r.name : ""}  —  ${levelLabel(r, lang)}`);
+  const t = typeInfo(r.type, lang);
+  if (t) console.log(`${t.label}: ${t.note}`);
+  if (r.lights) r.lights.forEach((l) => console.log(`  ${ICON[l.s]} ${lightLabel(l.k, lang)}: ${explainLight(l, lang)}`));
+  else r.reasons.forEach((x) => console.log(`  • ${describe(x, lang)}`));
+}
+
+try {
+  if (mode === "holders") {
+    const h = await scanner.analyzeHolders(addr, { onProgress });
+    if (onProgress) process.stderr.write("\r\x1b[K");
+    if (asJson) { console.log(JSON.stringify(h, null, 2)); process.exit(0); }
+    console.log(`\n${h.sym} · top holders`);
+    h.rows.slice(0, 20).forEach((r) => {
+      const c = h.clusters[r.owner];
+      console.log(`  #${r.rank} ${f.short(r.owner)}  ${r.pct.toFixed(2)}%  ${f.usd(r.value)}  ${r.kind}${c ? "  group " + c.id + " (" + c.n + ")" : ""}`);
+    });
+    if (h.creator) console.log(`\ncreator ${f.short(h.creator.addr)} · other tokens: ${h.creator.others.length}${h.creator.rugged ? " · RUGGED" : ""}`);
+  } else {
+    const r = await scanner.analyzeAddress(addr, { onProgress });
+    if (onProgress) process.stderr.write("\r\x1b[K");
+    if (asJson) { console.log(JSON.stringify(r, null, 2)); process.exit(0); }
+    if (r.kind === "token") printToken(r.token);
+    else {
+      const w = r.wallet;
+      console.log(`\nwallet ${f.short(w.wallet)} · ${w.sol.toFixed(3)} SOL · ${w.total} tokens (${w.hidden} dust hidden)`);
+      w.results.forEach(printToken);
+    }
+  }
+} catch (e) {
+  if (onProgress) process.stderr.write("\r\x1b[K");
+  console.error(describeError(e, lang, { ownRpc: !!rpcUrl }));
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "solana-risk-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+  "exports": {
+    ".": "./src/index.js",
+    "./i18n": "./src/i18n/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "bin"
+  ],
+  "bin": {
+    "solana-risk": "bin/solana-risk.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "example": "node bin/solana-risk.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "solana",
+    "risk",
+    "rug-pull",
+    "scam-detection",
+    "token",
+    "spl-token",
+    "token-2022",
+    "holders",
+    "dexscreener",
+    "rugcheck"
+  ],
+  "license": "MIT",
+  "author": "panpontomate",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panpontomate/solana-risk-engine.git"
+  },
+  "homepage": "https://github.com/panpontomate/solana-risk-engine#readme",
+  "bugs": "https://github.com/panpontomate/solana-risk-engine/issues"
+}

package/src/changes.js

@@ -0,0 +1,105 @@
+import { USDC, USDT, WSOL } from "./constants.js";
+import { ScanError, isCancel } from "./errors.js";
+import { pool, progress, short } from "./util.js";
+import { getTokens } from "./tokens.js";
+import { getMarkets } from "./markets.js";
+
+// Stablecoins and SOL move all the time for normal reasons: they are not "what this wallet bought"
+const SKIP = { [USDC]: 1, [USDT]: 1, [WSOL]: 1 };
+
+// A snapshot is {mint: {q: amount, v: usd value, s: symbol}} with only priced tokens worth >= $1.
+// A low cap made a token from the tail reappear as "new" on the next check just for having left
+// the picture; 300 entries (a few KB) covers almost any real wallet.
+export function capSnap(h, max) {
+  const ks = Object.keys(h).sort(function (a, b) { return h[b].v - h[a].v; });
+  const out = {};
+  ks.slice(0, max || 300).forEach(function (k) { out[k] = h[k]; });
+  return out;
+}
+
+// Changes between two snapshots of one wallet: new | more | less | sold, with the USD value involved
+export function chgDiff(prev, now) {
+  const out = [];
+  Object.keys(now).forEach(function (m) {
+    const n = now[m], p = prev[m];
+    if (!p) { if (n.v >= 20) out.push({ k: "new", m: m, s: n.s, v: n.v }); return; }
+    if (n.q < p.q * 0.05) return;                                   // treated as "sold"
+    const price = n.v / n.q;
+    if (n.q >= p.q * 1.25 && (n.q - p.q) * price >= 50) out.push({ k: "more", m: m, s: n.s, v: (n.q - p.q) * price });
+    else if (n.q <= p.q * 0.75 && (p.q - n.q) * price >= 50) out.push({ k: "less", m: m, s: n.s, v: (p.q - n.q) * price });
+  });
+  Object.keys(prev).forEach(function (m) {
+    const p = prev[m], n = now[m];
+    if (p.v >= 20 && (!n || n.q < p.q * 0.05)) out.push({ k: "sold", m: m, s: p.s, v: p.v });
+  });
+  return out;
+}
+
+// Across many wallets: which tokens most of them bought and which they sold.
+// rows = [{ch: chgDiff(...)}]; each wallet counts once per token and side.
+export function chgAgg(rows) {
+  const buy = {}, sell = {};
+  rows.forEach(function (r) {
+    const seenB = {}, seenS = {};
+    r.ch.forEach(function (c) {
+      const up = (c.k === "new" || c.k === "more"), M = up ? buy : sell, seen = up ? seenB : seenS;
+      const o = M[c.m] || (M[c.m] = { m: c.m, s: c.s, n: 0, v: 0 });
+      o.v += c.v;
+      if (!seen[c.m]) { o.n++; seen[c.m] = 1; }
+    });
+  });
+  function list(M) { return Object.keys(M).map(function (k) { return M[k]; }).sort(function (a, b) { return b.n - a.n || b.v - a.v; }); }
+  return { buy: list(buy), sell: list(sell) };
+}
+
+/**
+ * Today's snapshot of each wallet. Store it wherever you like (browser, database) and pass the stored
+ * one back to diffSnapshots next time.
+ *
+ * @returns {ts, snapshots: {wallet: snapshot}, failed}
+ */
+export async function takeSnapshots(client, addrs, opts) {
+  opts = opts || {};
+  const onProgress = opts.onProgress;
+  const cur = {};
+  let failed = 0, d = 0;
+  await pool(addrs, 3, async function (a) {
+    try { cur[a] = (await getTokens(client, a)).tokens; } catch (e) { if (isCancel(e)) throw e; failed++; }
+    d++; progress(onProgress, "wallets", 0.05 + 0.4 * d / addrs.length, { done: d, total: addrs.length });
+  });
+  const ok = addrs.filter(function (a) { return cur[a]; });
+  if (!ok.length) throw new ScanError("TOO_FEW_WALLETS", "could not read any wallet", { n: 0, total: addrs.length });
+  const set = {};
+  ok.forEach(function (a) { Object.keys(cur[a]).forEach(function (m) { if (!SKIP[m]) set[m] = 1; }); });
+  progress(onProgress, "markets", 0.5);
+  const ms = Object.keys(set);
+  const mkr = ms.length ? await getMarkets(client, ms, function (dn, n) { progress(onProgress, "markets", 0.5 + 0.45 * dn / n, { done: dn, total: n }); }) : { data: {}, failed: [] };
+  // A partial failure reading prices cannot be treated as "sold everything": better to abort and retry
+  if (mkr.failed.length) throw new ScanError("DEX_UNREACHABLE", "some prices could not be read");
+  const mk = mkr.data, snapshots = {};
+  ok.forEach(function (a) {
+    const now = {};
+    Object.keys(cur[a]).forEach(function (m) {
+      if (SKIP[m]) return;
+      const pair = mk[m], price = Number((pair && pair.priceUsd) || 0), q = cur[a][m], v = q * price;
+      if (price > 0 && v >= 1) now[m] = { q: q, v: Math.round(v * 100) / 100, s: (pair.baseToken && pair.baseToken.symbol) || short(m) };
+    });
+    snapshots[a] = capSnap(now);
+  });
+  progress(onProgress, "done", 1);
+  return { ts: Date.now(), snapshots: snapshots, failed: failed };
+}
+
+/**
+ * @param prev  {wallet: {ts, h: snapshot}} what you stored last time (missing wallets = first check)
+ * @param next  result of takeSnapshots
+ * @returns {rows: [{a, first, since, ch}], agg: chgAgg(rows that had a previous snapshot)}
+ */
+export function diffSnapshots(prev, next) {
+  prev = prev || {};
+  const rows = Object.keys(next.snapshots).map(function (a) {
+    const p = prev[a];
+    return { a: a, first: !p, since: p ? p.ts : 0, ch: p ? chgDiff(p.h, next.snapshots[a]) : [] };
+  });
+  return { rows: rows, agg: chgAgg(rows.filter(function (r) { return !r.first; })) };
+}

package/src/client.js

@@ -0,0 +1,143 @@
+import { PUBLIC_RPC, VIBE_RPC } from "./constants.js";
+import { ScanError, cancelled, isCancel } from "./errors.js";
+import { sleep } from "./util.js";
+
+// Methods PublicNode rejects with 403; if another one shows up it gets added at runtime
+const PN_BLOCKED_DEFAULT = ["getTokenLargestAccounts", "getTokenAccountsByOwner", "getTokenSupply"];
+
+/**
+ * Creates the network client every engine function uses.
+ *
+ * @param {object}   [opts]
+ * @param {string}   [opts.rpcUrl]        your own RPC URL (Helius, Triton...). Without it the free
+ *                                        PublicNode + Solana Vibe Station combination is used.
+ * @param {string}   [opts.heliusApiKey]  Helius key for PnL. If omitted it is taken from rpcUrl when
+ *                                        that URL is a Helius one (the key is never sent anywhere else).
+ * @param {AbortSignal} [opts.signal]     aborts every pending request with a CANCELLED ScanError
+ * @param {Function} [opts.fetch]         fetch implementation (defaults to globalThis.fetch)
+ * @param {number}   [opts.retryDelayMs]  first retry delay, doubled each time (default 1200)
+ * @param {number}   [opts.vibeIntervalMs] spacing of the free Vibe Station queue (default 1100)
+ */
+export function createClient(opts) {
+  opts = opts || {};
+  const fetchImpl = opts.fetch || globalThis.fetch;
+  if (!fetchImpl) throw new Error("no fetch available: pass opts.fetch or use Node 18+");
+  const rpcUrl = (opts.rpcUrl || "").trim() || PUBLIC_RPC;
+  const publicRpc = opts.publicRpc || PUBLIC_RPC;
+  const vibeRpc = opts.vibeRpc || VIBE_RPC;
+  const signal = opts.signal || null;
+  const retryDelay = opts.retryDelayMs === undefined ? 1200 : opts.retryDelayMs;
+  const vibeInterval = opts.vibeIntervalMs === undefined ? 1100 : opts.vibeIntervalMs;
+  const blocked = {};
+  PN_BLOCKED_DEFAULT.forEach(function (m) { blocked[m] = 1; });
+  let vibeNext = 0;
+
+  function checkAbort() {
+    if (signal && signal.aborted) throw cancelled();
+  }
+  function ownRpc() {
+    return rpcUrl !== publicRpc;
+  }
+  function heliusKey() {
+    if (opts.heliusApiKey) return opts.heliusApiKey;
+    // Only use the key if the configured RPC really is Helius: otherwise it is never sent to api.helius.xyz
+    try {
+      const u = new URL(rpcUrl);
+      if (!/(^|\.)helius-rpc\.com$|(^|\.)helius\.xyz$/i.test(u.hostname)) return null;
+      return u.searchParams.get("api-key") || null;
+    } catch (e) { return null; }
+  }
+
+  async function rawFetch(url, init) {
+    checkAbort();
+    try {
+      return await fetchImpl(url, signal ? Object.assign({}, init, { signal: signal }) : init);
+    } catch (e) {
+      if (signal && signal.aborted) throw cancelled();
+      throw e;
+    }
+  }
+
+  // JSON fetch with retries on 429, 5xx and network errors (doubling the wait each time)
+  async function jfetch(url, init, tries) {
+    let wait = retryDelay, last = null;
+    tries = tries || 4;
+    for (let i = 0; i < tries; i++) {
+      checkAbort();
+      try {
+        const r = await rawFetch(url, init);
+        if (r.status === 429 || r.status >= 500) {
+          last = new ScanError("HTTP", "HTTP " + r.status, { status: r.status });
+          await sleep(wait); wait *= 2; continue;
+        }
+        if (!r.ok) throw new ScanError("HTTP", "HTTP " + r.status, { status: r.status });
+        return await r.json();
+      } catch (e) {
+        if (isCancel(e) || (e.code === "HTTP" && e.data.status >= 400 && e.data.status < 500)) throw e;
+        last = e; await sleep(wait); wait *= 2;
+      }
+    }
+    if (last && last.code) throw last;
+    throw new ScanError("NETWORK", (last && last.message) || "no response", { cause: last && last.message });
+  }
+
+  // Fetch that never throws (except on cancel): used for optional extras such as RugCheck,
+  // which must never block the main result if they fail, time out or are down
+  async function softJson(url, timeoutMs) {
+    checkAbort();
+    const ctrl = typeof AbortController !== "undefined" ? new AbortController() : null;
+    let onAbort = null;
+    if (ctrl && signal) { onAbort = function () { ctrl.abort(); }; signal.addEventListener("abort", onAbort); }
+    const to = ctrl ? setTimeout(function () { ctrl.abort(); }, timeoutMs || 8000) : null;
+    try {
+      const r = await fetchImpl(url, ctrl ? { signal: ctrl.signal } : undefined);
+      if (!r.ok) return null;
+      return await r.json();
+    } catch (e) {
+      return null;
+    } finally {
+      if (to) clearTimeout(to);
+      if (onAbort) signal.removeEventListener("abort", onAbort);
+      checkAbort();
+    }
+  }
+
+  async function rpcAt(url, method, params, tries) {
+    const j = await jfetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: method, params: params })
+    }, tries);
+    if (j.error) throw new ScanError("RPC", j.error.message || "RPC error", { rpcCode: j.error.code });
+    return j.result;
+  }
+
+  async function vibeSlot() {
+    const now = Date.now(), at = Math.max(now, vibeNext);
+    vibeNext = at + vibeInterval;
+    if (at > now) await sleep(at - now);
+    checkAbort();
+  }
+
+  async function rpc(method, params) {
+    if (ownRpc()) return rpcAt(rpcUrl, method, params);
+    // PublicNode accepts at most 10 accounts per getMultipleAccounts: split and merge the result
+    if (method === "getMultipleAccounts" && params[0].length > 10) {
+      const parts = [];
+      for (let i = 0; i < params[0].length; i += 10) parts.push(rpc(method, [params[0].slice(i, i + 10)].concat(params.slice(1))));
+      const rs = await Promise.all(parts);
+      return { context: rs[0].context, value: [].concat.apply([], rs.map(function (r) { return r.value; })) };
+    }
+    if (!blocked[method]) {
+      try { return await rpcAt(publicRpc, method, params); }
+      catch (e) {
+        if (isCancel(e) || !(e.code === "HTTP" && (e.data.status === 401 || e.data.status === 403))) throw e;
+        blocked[method] = 1;
+      }
+    }
+    await vibeSlot();
+    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 };
+}