Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

22 Commits

Folders and files

Repository files navigation

ClusterPulse logo

ClusterPulse

tests

A 10-second trap-risk score for every pump.fun launch, streamed live from Solana through Solami Mirage.

About 43,000 tokens launch on pump.fun every day (Dune, 19.09–08.10.2026). Most rugs give themselves away in the first block: a bundle that grabs a third of the supply, a dev who shipped twelve tokens this month. Terminals already show bundle % and dev history as raw numbers. Nobody can read those numbers for 43k launches a day, and none of them answers the question a trader actually has: how likely am I to get wrecked if I buy this?

ClusterPulse answers that question. It watches the pump.fun program in real time and scores each launch about 12 seconds after creation. When a launch scores red, a Telegram alert goes out with the reasons and the historical trap rate behind each one.

Launches in pump.fun's mayhem mode are skipped entirely. They are traded by pump.fun's own agent, so there is no human-made trap to warn about, and they are left out of training as well.

πŸ”΄ $TICKER β€” trap risk 31% (market base 3%)
β”œ other wallets bought 35% of supply in the first block β€” 12% of such launches were traps
β”œ fresh dev: no launches in the last 30 days β€” 6% of such launches were traps
β”œ scored 12 s after creation Β· Solami Mirage
β”” pump.fun Β· gmgn Β· GsXo…pump

↳ outcome (last trade 1.4 h after launch): retail put 12.4 SOL, took out 3.1 (βˆ’75%) Β· never graduated Β· dev +4.2 SOL
βœ… trap: the alert was right

Live channel: t.me/cluster_solana Β· Demo video: youtu.be/uRgR4BDfGjw Β· Pitch: youtu.be/-r6rjNmGWyU Β· Built for Colosseum Crypto World's Fair (Solana track) and the Solami sidetrack.

Does it work? Held-out backtest

The model was trained on weeks 1–3 of a full pump.fun census pulled from Dune (19.08–18.09.2026), with a 3-day gap, and scored on week 4, which it never saw.

Level Launches Trap rate vs base Retail SOL in Retail ROI Lost per 1 SOL
πŸ”΄ red (top 2%) 1,144 29.5% 15.8Γ— 67,303 βˆ’33.6% 0.34 SOL
🟑 yellow (next 8%) 4,576 7.1% 3.8Γ— 261,297 βˆ’19.1% 0.19 SOL
🟒 green (rest) 51,479 0.8% 0.4Γ— 2,186,065 βˆ’11.4% 0.11 SOL

57,199 non-mayhem launches with at least 1 SOL of retail money; trap base rate that week 1.9%. AUC 0.865 (weekly 0.898 / 0.906 / 0.865). Generated by python tools/backtest_table.py from model/live_model.json.

Trap means retail (non-dev wallets that first bought after slot 5, high-frequency bots excluded) lost more than half of its SOL on a token that never graduated.

How to read the table:

  • Red is a don't touch / size down filter, not a short signal. 70% of red launches are not traps.
  • Even green launches lose retail money on average. Pump.fun is negative-sum for late buyers. The score tells you where the losses are concentrated, not where the profit is.
  • A live backtest from the 24/7 scorer runs alongside: python live_report.py.

Live, on mainnet

Everything the 24/7 scorer has scored live as of 12.10.2026, 19:00 Kyiv: 44,368 launches, 34,610 followed to their outcome (logsSubscribe from 23.09, Solami Mirage from 10.10). Only launches where retail put in at least 1 SOL are counted.

Level Launches Trap rate Retail ROI (SOL in)
πŸ”΄ red 110 29.1% βˆ’31.3% (5,359)
🟑 yellow 943 11.7% βˆ’19.2% (37,026)
🟒 green 8,572 2.5% βˆ’13.0% (317,753)

Live base rate 3.7%, so red runs at 7.9Γ— the base and 11.6Γ— green, in line with the held-out Dune week (29.5% for red). 110 red launches is still a small sample. Every one of these calls, and its outcome, is public in the channel.

What we learned (and why the name is half wrong)

We started as a wallet-cluster detector. The data disagreed:

  • Counting wallets in one transaction barely predicts traps by money. Inside non-mayhem launches it gives 1.3Γ— the base.
  • Bundles measured by volume do. Non-dev wallets taking more than 30% of supply in the first block gives 4.5Γ—.
  • Clusters do hurt small wallets. On the label "most retail wallets lost more than half", multi-wallet transactions give 2.3Γ— and 3+ wallets in one transaction give 2.75Γ—. Bundles hit many small buyers more than they drain the big ones.
  • Fresh devs are riskier than serial ones. A dev wallet with no launches in the previous 30 days is behind a trap 5.8% of the time, twice the base. Devs with 50+ launches a month sit far below it (0.7–1%): they run volume, not one-off rugs.

So the product is the risk score. Cluster and bundle signals are its explanations. Numbers: model/fork_a.txt.

And then the live data showed us where clusters do matter: in the outcome itself. "Retail" in our label is every non-dev wallet that bought after slot 5. A dev's own bundle wallets, the ones painting the chart with small buys, land in that bucket too, and their break-even trades hide what real people lost. So every red alert now gets a funding check five minutes in (below), and the outcome reply reports real buyers separately.

Funding check: who is actually buying

Five minutes after a red alert, ClusterPulse takes up to 40 early buyers and finds who funded each of them: the last incoming SOL transfer (β‰₯ 0.01 SOL) before their first buy, through Solami RPC (live/funding.py). Then:

  • Dev's cluster: wallets funded by the dev, by the dev's own funder, or by each other.
  • Shared-funder group: 3+ early buyers fed by one wallet that is neither an exchange (Dune CEX labels) nor a hub (1,000+ transactions a day).
  • Links to other launches: the dev's funder is itself a dev in our 2M-launch history; the same group funder fed early buyers of another launch earlier.

The result goes out as a second reply under the alert. When the launch goes quiet, the outcome reply splits money into all retail versus real buyers outside the dev's cluster. Wallets that sold without ever buying on the curve, meaning they received tokens by transfer, count as insiders too.

What it found on the first night:

  • $P- and $NUBI were one operator. The P- dev wallet got 22.6 SOL from the NUBI dev wallet minutes before launch, so it only looked like a "fresh dev". In both launches one wallet (6vae…qxWx) funded most of the early buyers: 25 of 37 in P-, 21 of 36 in NUBI. Those bundle wallets lost 8% and 25%, the cost of running volume. The dev made +14% and +44%.
  • "Retail βˆ’2%" was really βˆ’73%. In $PIN, 39 early buyers shared one funder and carried almost all the "retail" volume (32 SOL in, 31.4 out). The real buyers outside that group put 1.1 SOL in and got 0.3 back. The same pattern shows up in $MAPS (βˆ’7% vs βˆ’33%) and $SWISH (βˆ’4% vs βˆ’41%).

Re-run the check for any past launch: python tools/funding_check.py <mint> (needs an RPC key). It also prints full PnL for the dev, the cluster, the groups and everyone else.

How it works

flowchart LR
  A[Solana mainnet<br/>pump.fun program] -->|Yellowstone SubscribeUpdate<br/>over WebSocket| B[Solami Mirage<br/>saved filter: pump program]
  B --> C[live/mirage.py<br/>protobuf β†’ emit_cpi events]
  C --> D[live/state.py<br/>per-launch state,<br/>10-second feature window]
  D --> E[live/model.py<br/>gradient-boosted trees, 12 features]
  E -->|red| F[Telegram channel]
  E -->|red, +5 min| K[live/funding.py<br/>who funded the early buyers<br/>Solami RPC]
  K -->|reply: dev cluster| F
  E --> G[(live.db<br/>scores Β· funding Β· outcomes)]
  H[(devdb.sqlite<br/>2M launches, dev history)] --> D
  I[Dune census<br/>retro/] -->|train_live.py| E
Loading
  1. Stream. A Solami Mirage subscription filters the chain to transactions that touch the pump.fun program. Frames arrive as binary Yellowstone SubscribeUpdate over a plain WebSocket.
  2. Decode. live/mirage.py reads the protobuf by hand, without protoc or generated code. It pulls the pump.fun CreateEvent, TradeEvent and CompleteEvent out of the emit_cpi inner instructions and resolves address-lookup-table accounts.
  3. Features. For each launch: first-block supply split between dev and others, buyers and multi-wallet transactions in slots 0–5, net supply bought in 10 s, the dev's launches and graduations over 30 days, and same-ticker launches in the last 30 minutes. Every definition mirrors the Dune SQL the model was trained on (retro/census.sql), so live inputs match training inputs.
  4. Score. A HistGradientBoosting model, exported to JSON and evaluated in pure Python, with no sklearn in production. Red is the top 2% of scores, yellow the next 8%.
  5. Funding check for red alerts at +5 minutes (section above).
  6. Outcome. Every launch is followed until it goes quiet. Graduation, retail SOL in and out, and the dev's PnL are stored, so the live backtest builds itself. Every red alert in the channel then gets a reply with what actually happened (retail in/out, graduated or not, dev PnL, trap or not), so anyone can check the calls, misses included.

Why Solami Mirage

The first version used logsSubscribe. Busy pump.fun transactions can exceed the log limit and arrive as Log truncated, with the events cut off. In our recorded mainnet sample that happened to 0.7% of transactions. Every such transaction needed a getTransaction refetch, which costs seconds and RPC credits, exactly where the 10-second window is tight. Mirage delivers the whole transaction, inner instructions included, so the events are never truncated and nothing needs refetching. The filter lives on Solami's side, and the client is just a WebSocket.

Mirage is the default source whenever SOLAMI_API_KEY is set. If the internet drops, the scorer keeps reconnecting to Mirage and marks the gap. If Solami rejects the key (a trial ended, say), it falls back to logsSubscribe (Solami WebSocket or Helius) with refetch.

Measured on mainnet (tools/solami_check.py, 40 s, 10.10.2026): 2,540 pump.fun transactions (about 63 per second) carried 1,932 events, including 20 launches. The first frame arrived 0.4 s after connecting, and the median lag from block time to decoded event was 1.8 s. Block time only has whole-second resolution, so this number is rough.

tests/test_mirage.py replays a recorded mainnet stream through both paths. 6,712 transactions decode to identical events, and the full scorer produces identical scores. The recording (raw_sample.jsonl) stays local; without it the test runs only its synthetic part.

Quick start

pip install -r requirements.txt
cp .env.example .env          # then fill it in, see below
python tools/solami_check.py  # key, RPC, Mirage subscription, 30 s of live pump events
python live_scorer.py         # live: Mirage if SOLAMI_API_KEY is set, else logsSubscribe
Variable Needed for Notes
SOLAMI_API_KEY Mirage stream (default source), Solami WS/RPC Standard key with MirageStream + MirageManage (+ DataApi). WebSocket and Mirage are not on Solami's Free plan
SOLAMI_MIRAGE_ID optional Use an existing Mirage subscription instead of creating clusterpulse-pump
HELIUS_API_KEY fallback source Used when Solami is not configured or unreachable
WS_URL, RPC_URL optional Any other Solana WebSocket / RPC for the logsSubscribe path
TG_BOT_TOKEN, TG_CHAT_ID alerts Bot must be an admin of the channel; TG_CHAT_ID=@channel works for public channels
ALERT_LANG optional en (default) or ru
DECIDE_AFTER optional Seconds after creation before scoring (default 12: 10-s window plus confirmation lag)
MIN_WALLETS_ALERT optional Minimum wallets in 10 s before a red launch goes to Telegram (default 3)
DUNE_API_KEY retraining only Census queries in retro/

Dev history. python -m live.devdb --seed builds devdb.sqlite from Dune census exports (retro/census_run.py), and --append closes gaps (retro/devgap.sql). Without it the scorer still runs, but the dev-history features stay empty until it has watched launches for a while.

Exchange labels. The funding check skips exchange wallets using dune_out/cex_solana.csv.gz, a Dune export that isn't in the repo. Without it, only the 1,000+ transactions a day rule marks a funder as a hub.

Running 24/7. On Windows, scripts\scorer_24x7.bat restarts the scorer on exit and writes daily logs. On Linux, use deploy/clusterpulse-scorer.service (systemd, Restart=always).

Offline.

python tests/test_live.py                       # synthetic events β†’ decoder β†’ features β†’ score
python tests/test_mirage.py                     # Mirage decoder vs logs on a recorded stream
python tests/test_funding.py                    # funding check on a fake RPC
python tests/test_funding_check.py              # funding report end to end, fake RPC
python live_scorer.py --record raw.jsonl        # record raw messages (frames in Mirage mode)
python live_scorer.py --replay raw.jsonl        # replay without network, into replay/live.db
python live_report.py                           # live levels vs outcomes from live.db

Retraining

pip install -r requirements-retro.txt              # pandas, numpy, scikit-learn
python retro/census_run.py 2026-08-19 2026-09-18   # Dune census, one CSV per day (needs DUNE_API_KEY)
python retro/train_live.py                         # weekly AUC, holdout, thresholds -> model/live_model_new.json
python tools/backtest_table.py                     # held-out table -> model/backtest.md

retro/dq.py wraps the Dune API with a per-run credit budget. --submit and --collect handle shells that can't wait for long queries.

Repository layout

Path What
live_scorer.py Live scorer: stream, timers, alerts, SQLite
live/ mirage.py (Solami Mirage), pump_events.py (pump.fun IDL decoding), state.py (features), model.py (inference), devdb.py (dev history), funding.py (who funded the early buyers)
retro/ Dune SQL and the training pipeline
model/ Production model, held-out backtest, fork-A analysis
tools/ Solami smoke test, funding check for one launch, backtest table
tests/ Offline tests, run on every push by GitHub Actions
scripts/ Windows launchers: live scorer, 24/7 restart loop, Solami check, funding check
legacy/ Pre-hackathon code (see below)
docs/archive/ Early concept documents. Their latency and architecture claims are outdated

Limitations and roadmap

  • AMM phase is not tracked. A token that graduates counts as "not a trap", even if it dumps on the AMM afterwards.
  • pump.fun only, SOL-quoted launches only. Other launchpads (Meteora DBC, LaunchLab) are next.
  • The funding check is one hop. Bundles funded through exchanges, mixers or several hops are not linked yet, and on most red launches it finds no cluster at all. Each check costs about 100 RPC calls.
  • The model was trained on the contaminated retail label. Retraining on "real buyers" needs the funding check run over the historical census. That is the next step, and we expect it to raise the red trap rate.
  • Research, not yet in production: a wallet organicity index (how much of a buyer's balance went through real price risk in the last 30 days). It may matter more for anti-sybil filtering than for rug prediction.
  • Next: a JSON/WebSocket feed for trading bots, and on-chain score attestations that any program can read.

Prior work disclosure

legacy/ holds code written before the hackathon (April 2026): a pump.fun collector, a dev-history scanner and a Google-Sheets scorer for finding good devs. Everything else was built during Colosseum Crypto World's Fair (from 14.09.2026): the live scorer, the Mirage transport, the pump.fun event decoder, the Dune census and training pipeline, the model, the tests and the tools.

License

Licensed under the PolyForm Noncommercial License 1.0.0. Free for personal, research, academic, and evaluation use. Commercial exploitation, reselling, or hosting as a commercial service is strictly prohibited without explicit written permission.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages