solana-launch-forensics 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 solana-launch-forensics contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,353 @@
1
+ Metadata-Version: 2.4
2
+ Name: solana-launch-forensics
3
+ Version: 0.2.0
4
+ Summary: Read-only forensics for pump.fun style token launches
5
+ Author: tdkrHuang
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/tdkrHuang/solana-launch-forensics
8
+ Project-URL: Repository, https://github.com/tdkrHuang/solana-launch-forensics
9
+ Project-URL: Issues, https://github.com/tdkrHuang/solana-launch-forensics/issues
10
+ Project-URL: Changelog, https://github.com/tdkrHuang/solana-launch-forensics/releases
11
+ Keywords: solana,pump.fun,forensics,onchain,spl-token
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: License :: OSI Approved :: MIT License
21
+ Classifier: Operating System :: OS Independent
22
+ Classifier: Topic :: Security
23
+ Requires-Python: >=3.9
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=7; extra == "dev"
28
+ Dynamic: license-file
29
+
30
+ # solana-launch-forensics
31
+
32
+ Read-only forensics for pump.fun style token launches. **Standard library only** — no
33
+ API key, no `pip install` of crypto SDKs, no wallet connection.
34
+
35
+ It answers four questions from public chain data alone:
36
+
37
+ 1. **Which mints did a wallet create?**
38
+ 2. **How fast, and did any share a transaction?**
39
+ 3. **How did the SOL leave, and did the payouts repeat one size?**
40
+ 4. **Which mints belong to the same operator, and what is the evidence?**
41
+
42
+ Every output line is traceable to a signature you can paste into an explorer.
43
+ The tool never guesses intent.
44
+
45
+ ```
46
+ $ launchforensics scan GtTg74Zp…4W14 --limit 60
47
+ wallet GtTg74Zp…4W14
48
+ scanned 60 transactions
49
+ creations 13
50
+ window 9m 11s
51
+
52
+ created (UTC) batch mint tx
53
+ 2026-11-16 12:22:27 1 C53a9Fc6…pump ggoZiaudL3jx..6tiw
54
+ 2026-11-16 12:23:07 1 CqAjDktv…pump 5BHGkpzjtjUU..RLY3
55
+ ...
56
+ ```
57
+
58
+ ---
59
+
60
+ ## Install
61
+
62
+ ```bash
63
+ git clone https://github.com/tdkrHuang/solana-launch-forensics
64
+ cd solana-launch-forensics
65
+ python3 -m launchforensics --help
66
+ ```
67
+
68
+ Python 3.9+. Nothing to install.
69
+
70
+ Optionally, as a command:
71
+
72
+ ```bash
73
+ pip install -e .
74
+ launchforensics --help
75
+ ```
76
+
77
+ ---
78
+
79
+ ## Commands
80
+
81
+ ### `scan <wallet>` — mints created by a wallet
82
+
83
+ ```bash
84
+ launchforensics scan <WALLET> --limit 400 --out wallet.json
85
+ ```
86
+
87
+ | Flag | Meaning |
88
+ |---|---|
89
+ | `--limit N` | transactions to inspect (max 1000, newest first) |
90
+ | `--out FILE` | write the full JSON result |
91
+ | `--json` | print JSON to stdout |
92
+
93
+ Reports `creations`, the time `window` between the first and last creation, and any
94
+ transaction that created more than one mint.
95
+
96
+ ### `tx <signature>` — one transaction, decoded
97
+
98
+ ```bash
99
+ launchforensics tx <SIGNATURE>
100
+ ```
101
+
102
+ Resolves which program emitted each `Program log:` line by walking the
103
+ `invoke` / `success` stack, so pump.fun operations are counted separately from
104
+ token-program noise. Output includes signers, fee, pump instruction counts,
105
+ referenced mints, SOL transfers and repeated equal-size outflows.
106
+
107
+ ### `flows <wallet>` — repeated equal-size payouts
108
+
109
+ ```bash
110
+ launchforensics flows <WALLET> --limit 200 --min-sol 0.01 --across-tx
111
+ ```
112
+
113
+ Groups SOL transfers leaving the wallet by exact lamport amount. Scripted splitters
114
+ tend to pay one number to many destinations; humans rarely do.
115
+
116
+ | Flag | Meaning |
117
+ |---|---|
118
+ | `--across-tx` | group identical amounts **across** transactions (default: within one tx) |
119
+ | `--min-count N` | minimum distinct destinations to report |
120
+ | `--min-sol X` | ignore dust below X SOL |
121
+
122
+ Real output — nine wallets received the identical 486,609,148 lamports:
123
+
124
+ ```
125
+ $ launchforensics flows GtTg74Zp… --limit 150 --min-sol 0.4 --across-tx
126
+ 0.486609148 SOL x 9 destinations (9 txs)
127
+ -> 2c5o9kpr…vJq4
128
+ -> 3EyicXms…hPb
129
+ -> 6NmwtSZ5…M2N
130
+ ...
131
+ ```
132
+
133
+ `--across-tx` is the mode that matters for payout analysis: a splitter usually pays
134
+ one destination per transaction, so a within-transaction view finds nothing.
135
+
136
+ ### `cluster <wallet>` — mints that share evidence
137
+
138
+ ```bash
139
+ launchforensics cluster <WALLET> --limit 400
140
+ ```
141
+
142
+ Builds a graph whose nodes are wallets and mints and whose edges are individual,
143
+ signed facts:
144
+
145
+ | Edge | Meaning |
146
+ |---|---|
147
+ | `created` | the wallet paid for the transaction that created the mint |
148
+ | `swept` | the wallet collected that mint's creator fee — only the creator can |
149
+ | `funded` | SOL moved from one wallet to another |
150
+
151
+ Connected components containing at least two mints are printed together, with the
152
+ signature of every link, so any single claim can be checked on an explorer.
153
+
154
+ | Flag | Meaning |
155
+ |---|---|
156
+ | `--min-mints N` | ignore components below N mints (default 2) |
157
+ | `--max-mints N` | mints printed per cluster (default 25) |
158
+ | `--max-edges N` | evidence lines printed per cluster (default 25) |
159
+ | `--out FILE` | write the full JSON result |
160
+ | `--json` | print JSON to stdout |
161
+
162
+ Example output (addresses shortened):
163
+
164
+ ```
165
+ wallet GtTg74ZpUb…4W14
166
+ scanned 5 transactions
167
+ evidence created 3, funded 1, swept 3
168
+ clusters 1 (minimum 2 mints)
169
+
170
+ cluster 1: 3 mints, 2 wallets
171
+ links created 3, funded 1, swept 3
172
+ window 2025-11-16 04:50:00 -> 2025-11-16 05:16:21 (26m 21s)
173
+ wallets
174
+ - GtTg74ZpUb…4W14
175
+ - 8fJ1XKz6Yb…QwZa
176
+ mints
177
+ - EGX8MJT8wd…pump
178
+ - 2ZZhunwtYT…pump
179
+ - 2GoDADTFmh…pump
180
+ evidence
181
+ created GtTg74ZpUb…4W14 -> EGX8MJT8wd…pump create1
182
+ funded 8fJ1XKz6Yb…QwZa -> GtTg74ZpUb…4W14 0.05 SOL fund1
183
+ swept GtTg74ZpUb…4W14 -> EGX8MJT8wd…pump sweep1
184
+ ```
185
+
186
+ A control wallet — one that created a single token and collected nothing — prints
187
+ `No cluster above the threshold.` That silence is the point: the command reports
188
+ links it can sign, not wallets it finds interesting.
189
+
190
+ Shared funding is a link, not proof. Exchanges and faucets fund thousands of
191
+ unrelated wallets, so read the `funded` edges with that in mind; `created` and
192
+ `swept` are the stronger links because both require control of the wallet.
193
+
194
+ ---
195
+
196
+ ## Dataset
197
+
198
+ `datasets/clusters.jsonl` collects reproducible cluster records: the seed wallet,
199
+ the exact command, the scan bound, the evidence counts and a confidence grade.
200
+ The schema is documented in [`datasets/SCHEMA.md`](datasets/SCHEMA.md).
201
+
202
+ ```bash
203
+ python3 tools/build_dataset.py --seeds datasets/seeds.json --limit 200
204
+ python3 tools/build_dataset.py --seeds datasets/seeds.json --dry-run
205
+ ```
206
+
207
+ Grading is by the weakest link used to join the mints:
208
+
209
+ | Grade | Condition |
210
+ |---|---|
211
+ | `high` | at least one `swept` edge — only a creator can collect the fee |
212
+ | `medium` | two or more `created` edges from one wallet |
213
+ | `low` | joined only by funding transfers (dropped by default) |
214
+
215
+ Records are keyed by a hash of their mints, so re-running updates instead of
216
+ duplicating, and a rate-limited run keeps what it already wrote.
217
+
218
+ ---
219
+
220
+ ## What it correctly distinguishes
221
+
222
+ Two traps that produce wrong conclusions:
223
+
224
+ **1. `Program log:` lines carry no program id.**
225
+
226
+ A pump.fun `CreateV2` fans out into Token-2022, which logs its own
227
+ `Instruction: InitializeMint2`. Naive substring counting reports two creations per
228
+ launch. This tool attributes logs through the invoke stack, so `create_count`
229
+ returns `1`.
230
+
231
+ **2. Touching a mint is not creating it.**
232
+
233
+ A creator-fee sweep references seven mints and contains zero creations:
234
+
235
+ ```
236
+ $ launchforensics tx zWcwg1pBsstXjKUw…whEq
237
+ pump ops SweepCreatorFee x7, CollectCreatorFeeV2
238
+ creates 0
239
+ mints 7 referenced
240
+ ```
241
+
242
+ That distinction matters: a sweep across seven mints proves one wallet controls the
243
+ creator-fee accounts of all seven. Calling it "seven launches in one transaction"
244
+ would be wrong, and a reviewer will check.
245
+
246
+ ---
247
+
248
+ ## Output schema
249
+
250
+ `scan` writes:
251
+
252
+ ```json
253
+ {
254
+ "wallet": "...",
255
+ "scanned_transactions": 400,
256
+ "creation_count": 27,
257
+ "window_seconds": 2350,
258
+ "creations": [
259
+ {
260
+ "mint": "...pump",
261
+ "signature": "...",
262
+ "slot": 470014561,
263
+ "block_time": 1763268569,
264
+ "batch_size": 1
265
+ }
266
+ ],
267
+ "batch_transactions": []
268
+ }
269
+ ```
270
+
271
+ `cluster` writes:
272
+
273
+ ```json
274
+ {
275
+ "wallet": "...",
276
+ "scanned_transactions": 400,
277
+ "edge_counts": {"created": 84, "funded": 12, "swept": 61},
278
+ "cluster_count": 2,
279
+ "clusters": [
280
+ {
281
+ "mints": ["...pump", "...pump"],
282
+ "wallets": ["..."],
283
+ "links": {"created": 84, "funded": 12, "swept": 61},
284
+ "first_block_time": 1763268569,
285
+ "last_block_time": 1763272285,
286
+ "edges": [
287
+ {"type": "created", "wallet": "...", "mint": "...pump", "signature": "..."}
288
+ ]
289
+ }
290
+ ]
291
+ }
292
+ ```
293
+
294
+ ---
295
+
296
+ ## Limits, stated plainly
297
+
298
+ - **Public RPC is rate limited.** Default pause is 0.35 s and requests retry with
299
+ backoff. `scan` skips individual failed transactions and reports
300
+ `failed_transactions` instead of aborting. If you see many failures, switch
301
+ endpoint:
302
+
303
+ ```bash
304
+ launchforensics --rpc https://solana-rpc.publicnode.com scan <WALLET> --limit 400
305
+ ```
306
+
307
+ For serious volume, point `--rpc` (or `SOLANA_RPC_URL`) at your own node.
308
+ - **`--limit` caps history.** `scan` reads newest-first; a wallet older than the
309
+ window will appear to have fewer creations. Results say `scanned_transactions`
310
+ so the bound is visible.
311
+ - **pump.fun mints are detected by the `pump` suffix.** Non-pump SPL mints are only
312
+ found when the RPC returns parsed `initializeMint` instructions.
313
+ - **No price or PnL data.** Deliberately. Prices come from third-party APIs with
314
+ their own reliability; this tool only reports what the chain itself records.
315
+ - **Endpoints disagree.** Some public RPCs return an empty signature list for
316
+ addresses they do not index — including wallets that are active. `scan` will
317
+ report `no signatures returned`. Confirm on a second endpoint before treating
318
+ a wallet as inactive, and say which endpoint you used.
319
+ - **Not a verdict.** Repeated equal-size payouts and batched creations are patterns,
320
+ not proof of wrongdoing.
321
+
322
+ ---
323
+
324
+ ## Paid reports
325
+
326
+ Reading the code is free. If you need this applied to a specific wallet — with
327
+ the funding chain, payout reconstruction and a PDF you can hand to a community,
328
+ a lawyer or an exchange — I write those reports with this tool:
329
+
330
+ - **Lite $99** — one wallet, 48h
331
+ - **Standard $299** — up to 5 wallets, 72h
332
+ - **Deep $699** — up to 15 wallets, legal appendix, 5 business days
333
+
334
+ Every claim carries a signature. Sample report (real case, 96 launches):
335
+ [docs/sample-report.md](docs/sample-report.md)
336
+
337
+ ## Tests
338
+
339
+ ```bash
340
+ python3 -m pytest -q
341
+ ```
342
+
343
+ Fixtures in `tests/fixtures.py` mirror real responses, including a versioned
344
+ transaction **without `message.header`** and a Token-2022 `InitializeMint2` nested
345
+ inside a pump.fun call. `tests/test_cluster.py` covers the graph rules: a single
346
+ mint is never a cluster, shared funding joins two wallets, a sweep joins mints to
347
+ the sweeper, and duplicate links collapse without duplicating mints.
348
+
349
+ ---
350
+
351
+ ## License
352
+
353
+ MIT
@@ -0,0 +1,324 @@
1
+ # solana-launch-forensics
2
+
3
+ Read-only forensics for pump.fun style token launches. **Standard library only** — no
4
+ API key, no `pip install` of crypto SDKs, no wallet connection.
5
+
6
+ It answers four questions from public chain data alone:
7
+
8
+ 1. **Which mints did a wallet create?**
9
+ 2. **How fast, and did any share a transaction?**
10
+ 3. **How did the SOL leave, and did the payouts repeat one size?**
11
+ 4. **Which mints belong to the same operator, and what is the evidence?**
12
+
13
+ Every output line is traceable to a signature you can paste into an explorer.
14
+ The tool never guesses intent.
15
+
16
+ ```
17
+ $ launchforensics scan GtTg74Zp…4W14 --limit 60
18
+ wallet GtTg74Zp…4W14
19
+ scanned 60 transactions
20
+ creations 13
21
+ window 9m 11s
22
+
23
+ created (UTC) batch mint tx
24
+ 2026-11-16 12:22:27 1 C53a9Fc6…pump ggoZiaudL3jx..6tiw
25
+ 2026-11-16 12:23:07 1 CqAjDktv…pump 5BHGkpzjtjUU..RLY3
26
+ ...
27
+ ```
28
+
29
+ ---
30
+
31
+ ## Install
32
+
33
+ ```bash
34
+ git clone https://github.com/tdkrHuang/solana-launch-forensics
35
+ cd solana-launch-forensics
36
+ python3 -m launchforensics --help
37
+ ```
38
+
39
+ Python 3.9+. Nothing to install.
40
+
41
+ Optionally, as a command:
42
+
43
+ ```bash
44
+ pip install -e .
45
+ launchforensics --help
46
+ ```
47
+
48
+ ---
49
+
50
+ ## Commands
51
+
52
+ ### `scan <wallet>` — mints created by a wallet
53
+
54
+ ```bash
55
+ launchforensics scan <WALLET> --limit 400 --out wallet.json
56
+ ```
57
+
58
+ | Flag | Meaning |
59
+ |---|---|
60
+ | `--limit N` | transactions to inspect (max 1000, newest first) |
61
+ | `--out FILE` | write the full JSON result |
62
+ | `--json` | print JSON to stdout |
63
+
64
+ Reports `creations`, the time `window` between the first and last creation, and any
65
+ transaction that created more than one mint.
66
+
67
+ ### `tx <signature>` — one transaction, decoded
68
+
69
+ ```bash
70
+ launchforensics tx <SIGNATURE>
71
+ ```
72
+
73
+ Resolves which program emitted each `Program log:` line by walking the
74
+ `invoke` / `success` stack, so pump.fun operations are counted separately from
75
+ token-program noise. Output includes signers, fee, pump instruction counts,
76
+ referenced mints, SOL transfers and repeated equal-size outflows.
77
+
78
+ ### `flows <wallet>` — repeated equal-size payouts
79
+
80
+ ```bash
81
+ launchforensics flows <WALLET> --limit 200 --min-sol 0.01 --across-tx
82
+ ```
83
+
84
+ Groups SOL transfers leaving the wallet by exact lamport amount. Scripted splitters
85
+ tend to pay one number to many destinations; humans rarely do.
86
+
87
+ | Flag | Meaning |
88
+ |---|---|
89
+ | `--across-tx` | group identical amounts **across** transactions (default: within one tx) |
90
+ | `--min-count N` | minimum distinct destinations to report |
91
+ | `--min-sol X` | ignore dust below X SOL |
92
+
93
+ Real output — nine wallets received the identical 486,609,148 lamports:
94
+
95
+ ```
96
+ $ launchforensics flows GtTg74Zp… --limit 150 --min-sol 0.4 --across-tx
97
+ 0.486609148 SOL x 9 destinations (9 txs)
98
+ -> 2c5o9kpr…vJq4
99
+ -> 3EyicXms…hPb
100
+ -> 6NmwtSZ5…M2N
101
+ ...
102
+ ```
103
+
104
+ `--across-tx` is the mode that matters for payout analysis: a splitter usually pays
105
+ one destination per transaction, so a within-transaction view finds nothing.
106
+
107
+ ### `cluster <wallet>` — mints that share evidence
108
+
109
+ ```bash
110
+ launchforensics cluster <WALLET> --limit 400
111
+ ```
112
+
113
+ Builds a graph whose nodes are wallets and mints and whose edges are individual,
114
+ signed facts:
115
+
116
+ | Edge | Meaning |
117
+ |---|---|
118
+ | `created` | the wallet paid for the transaction that created the mint |
119
+ | `swept` | the wallet collected that mint's creator fee — only the creator can |
120
+ | `funded` | SOL moved from one wallet to another |
121
+
122
+ Connected components containing at least two mints are printed together, with the
123
+ signature of every link, so any single claim can be checked on an explorer.
124
+
125
+ | Flag | Meaning |
126
+ |---|---|
127
+ | `--min-mints N` | ignore components below N mints (default 2) |
128
+ | `--max-mints N` | mints printed per cluster (default 25) |
129
+ | `--max-edges N` | evidence lines printed per cluster (default 25) |
130
+ | `--out FILE` | write the full JSON result |
131
+ | `--json` | print JSON to stdout |
132
+
133
+ Example output (addresses shortened):
134
+
135
+ ```
136
+ wallet GtTg74ZpUb…4W14
137
+ scanned 5 transactions
138
+ evidence created 3, funded 1, swept 3
139
+ clusters 1 (minimum 2 mints)
140
+
141
+ cluster 1: 3 mints, 2 wallets
142
+ links created 3, funded 1, swept 3
143
+ window 2025-11-16 04:50:00 -> 2025-11-16 05:16:21 (26m 21s)
144
+ wallets
145
+ - GtTg74ZpUb…4W14
146
+ - 8fJ1XKz6Yb…QwZa
147
+ mints
148
+ - EGX8MJT8wd…pump
149
+ - 2ZZhunwtYT…pump
150
+ - 2GoDADTFmh…pump
151
+ evidence
152
+ created GtTg74ZpUb…4W14 -> EGX8MJT8wd…pump create1
153
+ funded 8fJ1XKz6Yb…QwZa -> GtTg74ZpUb…4W14 0.05 SOL fund1
154
+ swept GtTg74ZpUb…4W14 -> EGX8MJT8wd…pump sweep1
155
+ ```
156
+
157
+ A control wallet — one that created a single token and collected nothing — prints
158
+ `No cluster above the threshold.` That silence is the point: the command reports
159
+ links it can sign, not wallets it finds interesting.
160
+
161
+ Shared funding is a link, not proof. Exchanges and faucets fund thousands of
162
+ unrelated wallets, so read the `funded` edges with that in mind; `created` and
163
+ `swept` are the stronger links because both require control of the wallet.
164
+
165
+ ---
166
+
167
+ ## Dataset
168
+
169
+ `datasets/clusters.jsonl` collects reproducible cluster records: the seed wallet,
170
+ the exact command, the scan bound, the evidence counts and a confidence grade.
171
+ The schema is documented in [`datasets/SCHEMA.md`](datasets/SCHEMA.md).
172
+
173
+ ```bash
174
+ python3 tools/build_dataset.py --seeds datasets/seeds.json --limit 200
175
+ python3 tools/build_dataset.py --seeds datasets/seeds.json --dry-run
176
+ ```
177
+
178
+ Grading is by the weakest link used to join the mints:
179
+
180
+ | Grade | Condition |
181
+ |---|---|
182
+ | `high` | at least one `swept` edge — only a creator can collect the fee |
183
+ | `medium` | two or more `created` edges from one wallet |
184
+ | `low` | joined only by funding transfers (dropped by default) |
185
+
186
+ Records are keyed by a hash of their mints, so re-running updates instead of
187
+ duplicating, and a rate-limited run keeps what it already wrote.
188
+
189
+ ---
190
+
191
+ ## What it correctly distinguishes
192
+
193
+ Two traps that produce wrong conclusions:
194
+
195
+ **1. `Program log:` lines carry no program id.**
196
+
197
+ A pump.fun `CreateV2` fans out into Token-2022, which logs its own
198
+ `Instruction: InitializeMint2`. Naive substring counting reports two creations per
199
+ launch. This tool attributes logs through the invoke stack, so `create_count`
200
+ returns `1`.
201
+
202
+ **2. Touching a mint is not creating it.**
203
+
204
+ A creator-fee sweep references seven mints and contains zero creations:
205
+
206
+ ```
207
+ $ launchforensics tx zWcwg1pBsstXjKUw…whEq
208
+ pump ops SweepCreatorFee x7, CollectCreatorFeeV2
209
+ creates 0
210
+ mints 7 referenced
211
+ ```
212
+
213
+ That distinction matters: a sweep across seven mints proves one wallet controls the
214
+ creator-fee accounts of all seven. Calling it "seven launches in one transaction"
215
+ would be wrong, and a reviewer will check.
216
+
217
+ ---
218
+
219
+ ## Output schema
220
+
221
+ `scan` writes:
222
+
223
+ ```json
224
+ {
225
+ "wallet": "...",
226
+ "scanned_transactions": 400,
227
+ "creation_count": 27,
228
+ "window_seconds": 2350,
229
+ "creations": [
230
+ {
231
+ "mint": "...pump",
232
+ "signature": "...",
233
+ "slot": 470014561,
234
+ "block_time": 1763268569,
235
+ "batch_size": 1
236
+ }
237
+ ],
238
+ "batch_transactions": []
239
+ }
240
+ ```
241
+
242
+ `cluster` writes:
243
+
244
+ ```json
245
+ {
246
+ "wallet": "...",
247
+ "scanned_transactions": 400,
248
+ "edge_counts": {"created": 84, "funded": 12, "swept": 61},
249
+ "cluster_count": 2,
250
+ "clusters": [
251
+ {
252
+ "mints": ["...pump", "...pump"],
253
+ "wallets": ["..."],
254
+ "links": {"created": 84, "funded": 12, "swept": 61},
255
+ "first_block_time": 1763268569,
256
+ "last_block_time": 1763272285,
257
+ "edges": [
258
+ {"type": "created", "wallet": "...", "mint": "...pump", "signature": "..."}
259
+ ]
260
+ }
261
+ ]
262
+ }
263
+ ```
264
+
265
+ ---
266
+
267
+ ## Limits, stated plainly
268
+
269
+ - **Public RPC is rate limited.** Default pause is 0.35 s and requests retry with
270
+ backoff. `scan` skips individual failed transactions and reports
271
+ `failed_transactions` instead of aborting. If you see many failures, switch
272
+ endpoint:
273
+
274
+ ```bash
275
+ launchforensics --rpc https://solana-rpc.publicnode.com scan <WALLET> --limit 400
276
+ ```
277
+
278
+ For serious volume, point `--rpc` (or `SOLANA_RPC_URL`) at your own node.
279
+ - **`--limit` caps history.** `scan` reads newest-first; a wallet older than the
280
+ window will appear to have fewer creations. Results say `scanned_transactions`
281
+ so the bound is visible.
282
+ - **pump.fun mints are detected by the `pump` suffix.** Non-pump SPL mints are only
283
+ found when the RPC returns parsed `initializeMint` instructions.
284
+ - **No price or PnL data.** Deliberately. Prices come from third-party APIs with
285
+ their own reliability; this tool only reports what the chain itself records.
286
+ - **Endpoints disagree.** Some public RPCs return an empty signature list for
287
+ addresses they do not index — including wallets that are active. `scan` will
288
+ report `no signatures returned`. Confirm on a second endpoint before treating
289
+ a wallet as inactive, and say which endpoint you used.
290
+ - **Not a verdict.** Repeated equal-size payouts and batched creations are patterns,
291
+ not proof of wrongdoing.
292
+
293
+ ---
294
+
295
+ ## Paid reports
296
+
297
+ Reading the code is free. If you need this applied to a specific wallet — with
298
+ the funding chain, payout reconstruction and a PDF you can hand to a community,
299
+ a lawyer or an exchange — I write those reports with this tool:
300
+
301
+ - **Lite $99** — one wallet, 48h
302
+ - **Standard $299** — up to 5 wallets, 72h
303
+ - **Deep $699** — up to 15 wallets, legal appendix, 5 business days
304
+
305
+ Every claim carries a signature. Sample report (real case, 96 launches):
306
+ [docs/sample-report.md](docs/sample-report.md)
307
+
308
+ ## Tests
309
+
310
+ ```bash
311
+ python3 -m pytest -q
312
+ ```
313
+
314
+ Fixtures in `tests/fixtures.py` mirror real responses, including a versioned
315
+ transaction **without `message.header`** and a Token-2022 `InitializeMint2` nested
316
+ inside a pump.fun call. `tests/test_cluster.py` covers the graph rules: a single
317
+ mint is never a cluster, shared funding joins two wallets, a sweep joins mints to
318
+ the sweeper, and duplicate links collapse without duplicating mints.
319
+
320
+ ---
321
+
322
+ ## License
323
+
324
+ MIT