Skip to content

Commit df19b91

Browse files
superchainsuperchain
committed
feat: add remaining tutorials, docs (roadmap, support, troubleshooting), vanity example, and web prompts
1 parent 5226e8e commit df19b91

File tree

13 files changed

+2326
-6
lines changed

13 files changed

+2326
-6
lines changed

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -193,10 +193,13 @@ Consolidates 3 existing production bots into one:
193193
- [RPC Best Practices](docs/rpc-best-practices.md) — Provider selection, batching, rate limiting
194194
- [Performance](docs/performance.md) — Benchmarks, latency, and optimization tips
195195
- [Security Guide](docs/guides/security.md) — Crypto library rules, key management
196+
- [Troubleshooting](docs/troubleshooting.md) — Common issues and solutions
197+
- [Support](docs/support.md) — Getting help, bug reports, feature requests
198+
- [Roadmap](docs/roadmap.md) — Where PumpKit is headed
196199

197200
### Tutorials
198201

199-
22 hands-on guides in [tutorials/](tutorials/):
202+
26 hands-on guides in [tutorials/](tutorials/):
200203

201204
| Tutorial | Topic |
202205
|----------|-------|
@@ -221,6 +224,10 @@ Consolidates 3 existing production bots into one:
221224
| [Error Handling](tutorials/33-error-handling-patterns.md) | Validation and error classes |
222225
| [Security Auditing](tutorials/37-security-auditing-verification.md) | Security audit checklist |
223226
| [AI Enrichment](tutorials/39-channel-bot-ai-enrichment.md) | GitHub + AI-powered cards |
227+
| [Your First Claim Bot](tutorials/40-your-first-claim-bot.md) | Build a claim bot from scratch |
228+
| [Customizing Claim Cards](tutorials/41-customizing-claim-cards.md) | HTML formatting, badges, enrichment |
229+
| [Channel Feed Bot](tutorials/42-channel-feed-bot.md) | Channel broadcasting setup |
230+
| [Understanding Events](tutorials/43-understanding-pumpfun-events.md) | On-chain event types and parsing |
224231

225232
### Community
226233
- [Contributing](CONTRIBUTING.md) — How to contribute

‎docs/README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,11 +50,14 @@ Deep dives into specific protocol topics:
5050
| [Code Examples](reference/examples.md) | 20+ practical code samples |
5151
| [Error Reference](reference/errors.md) | Custom SDK error classes and fixes |
5252
| [RPC Best Practices](reference/rpc-best-practices.md) | Provider selection, batching, rate limiting |
53+
| [Troubleshooting](troubleshooting.md) | Common issues and solutions |
54+
| [Support](support.md) | Getting help, bug reports, feature requests |
55+
| [Roadmap](roadmap.md) | Where PumpKit is headed |
5356

5457
## Tutorials
5558

56-
19 hands-on guides: [tutorials/](../tutorials/)
59+
30 hands-on guides: [tutorials/](../tutorials/)
5760

58-
## Live Dashboards
61+
## Examples
5962

60-
Reference implementations: [live/](../live/)
63+
Reference implementations and dashboards: [examples/](../examples/)

‎docs/roadmap.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Roadmap
2+
3+
> Where PumpKit is headed. Community input welcome — [open a discussion](https://github.com/nirholas/pumpkit/discussions).
4+
5+
---
6+
7+
## Legend
8+
9+
| Status | Meaning |
10+
|--------|---------|
11+
| ✅ Done | Shipped and available |
12+
| 🚧 In Progress | Actively being worked on |
13+
| 📋 Planned | Scoped and scheduled |
14+
| 💡 Exploring | Under research |
15+
16+
---
17+
18+
## Phase 1 — Foundation ✅
19+
20+
| Feature | Status | Details |
21+
|---------|--------|---------|
22+
| Monorepo setup | ✅ Done | Turborepo with 6 packages |
23+
| `@pumpkit/core` | ✅ Done | Shared utilities: logger, config, health, shutdown, types |
24+
| `@pumpkit/monitor` | ✅ Done | All-in-one PumpFun monitor (claims, launches, graduations, whales, CTO) |
25+
| `@pumpkit/tracker` | ✅ Done | Group call-tracking bot with leaderboards and PNL cards |
26+
| `@pumpkit/channel` | ✅ Done | Read-only Telegram channel feed for token events |
27+
| `@pumpkit/claim` | ✅ Done | Fee claim tracker by token CA or X handle |
28+
| Documentation | ✅ Done | 20+ docs, 30 tutorials, example dashboards |
29+
| Railway deployment | ✅ Done | Dockerfiles and configs for all bots |
30+
31+
## Phase 2 — npm Publishing 🚧
32+
33+
| Feature | Status | Details |
34+
|---------|--------|---------|
35+
| npm organization | 🚧 In Progress | `@pumpkit` scope on npm registry |
36+
| Package versioning | 📋 Planned | Semantic versioning with changesets |
37+
| CI/CD publish pipeline | 📋 Planned | GitHub Actions → npm on release tag |
38+
| Package README badges | 📋 Planned | npm version, downloads, license badges |
39+
| Peer dependency alignment | 📋 Planned | Shared versions across packages |
40+
41+
## Phase 3 — Frontend UI 📋
42+
43+
| Feature | Status | Details |
44+
|---------|--------|---------|
45+
| `@pumpkit/web` | 📋 Planned | React dashboard for bot monitoring |
46+
| Claim feed viewer | 📋 Planned | Real-time claim activity feed in browser |
47+
| Bot status dashboard | 📋 Planned | Health, uptime, message counts per bot |
48+
| Token analytics | 📋 Planned | Charts for bonding curve progress, market cap, trade volume |
49+
| Configuration UI | 💡 Exploring | Web-based bot config editor (env vars, channels, thresholds) |
50+
51+
## Phase 4 — Ecosystem Growth 💡
52+
53+
| Feature | Status | Details |
54+
|---------|--------|---------|
55+
| Plugin system | 💡 Exploring | Custom event handlers and formatters as plugins |
56+
| Multi-chain support | 💡 Exploring | Extend tracker bot beyond Solana |
57+
| Alert routing | 💡 Exploring | Discord, Slack, webhooks in addition to Telegram |
58+
| Hosted bots | 💡 Exploring | One-click bot deployment without self-hosting |
59+
| AI-powered insights | 💡 Exploring | GPT/Claude-based token analysis in claim cards |

‎docs/support.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Getting Help
2+
3+
> Need help with PumpKit? Here's how to get support.
4+
5+
---
6+
7+
## Documentation
8+
9+
| Resource | What It Covers |
10+
|----------|----------------|
11+
| [README](../README.md) | Quick start, packages, features |
12+
| [Getting Started](./getting-started.md) | Setup walkthrough |
13+
| [Architecture](./architecture.md) | How PumpKit is structured |
14+
| [Core API](./core-api.md) | `@pumpkit/core` API reference |
15+
| [Deployment](./deployment.md) | Railway and Docker deployment |
16+
| [Troubleshooting](./troubleshooting.md) | Common issues and fixes |
17+
| [FAQ](./faq.md) | Frequently asked questions |
18+
| [Error Reference](./errors.md) | Error classes and codes |
19+
| [Tutorials](../tutorials/README.md) | 30 hands-on guides |
20+
21+
---
22+
23+
## Found a Bug?
24+
25+
[Open a bug report](https://github.com/nirholas/pumpkit/issues/new) with:
26+
27+
- Your environment (OS, Node.js version, package versions)
28+
- Steps to reproduce
29+
- Expected vs actual behavior
30+
- Relevant logs (redact any tokens or keys)
31+
32+
---
33+
34+
## Feature Request?
35+
36+
[Open a feature request](https://github.com/nirholas/pumpkit/issues/new) describing:
37+
38+
- What you want to build
39+
- Why existing features don't cover it
40+
- Suggested approach (if any)
41+
42+
---
43+
44+
## Community
45+
46+
- [GitHub Discussions](https://github.com/nirholas/pumpkit/discussions) — Questions, ideas, show & tell
47+
- [GitHub Issues](https://github.com/nirholas/pumpkit/issues) — Bugs and feature requests
48+
49+
---
50+
51+
## Related Projects
52+
53+
| Project | Description |
54+
|---------|-------------|
55+
| [pump-fun-sdk](https://github.com/nirholas/pump-fun-sdk) | Core TypeScript SDK for PumpFun protocol |
56+
| [Pump Protocol Docs](https://github.com/pump-fun/pump-public-docs) | Official on-chain program documentation |

‎docs/troubleshooting.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Troubleshooting
2+
3+
> Common issues and solutions for PumpKit bots. Can't find your answer? [Open a discussion](https://github.com/nirholas/pumpkit/discussions).
4+
5+
---
6+
7+
## Installation Issues
8+
9+
### `Cannot find module '@pumpkit/core'`
10+
11+
Make sure you're in the monorepo root and have installed dependencies:
12+
13+
```bash
14+
cd pumpkit
15+
npm install
16+
```
17+
18+
If running a specific package, use the workspace flag:
19+
20+
```bash
21+
npm run dev --workspace=@pumpkit/monitor
22+
```
23+
24+
### TypeScript compilation errors
25+
26+
```bash
27+
npm run build
28+
```
29+
30+
If errors persist, clean and rebuild:
31+
32+
```bash
33+
rm -rf packages/*/dist
34+
npm run build
35+
```
36+
37+
---
38+
39+
## Telegram Bot Issues
40+
41+
### Bot not responding to commands
42+
43+
1. **Check bot token** — Verify `TELEGRAM_BOT_TOKEN` in `.env` matches [@BotFather](https://t.me/BotFather)
44+
2. **Check polling vs webhook** — grammy defaults to long polling. If deploying behind a reverse proxy, configure webhooks
45+
3. **Check bot permissions** — For channel bots, the bot must be added as an admin
46+
4. **Check logs** — Look for grammy errors in stdout
47+
48+
```bash
49+
# Run locally with verbose logging
50+
LOG_LEVEL=debug npm run dev --workspace=@pumpkit/monitor
51+
```
52+
53+
### Channel bot not posting
54+
55+
- The bot must be a **channel administrator** with "Post Messages" permission
56+
- `TELEGRAM_CHANNEL_ID` must include the `-100` prefix for supergroups: `-1001234567890`
57+
- Test with a direct message first to confirm the bot is alive
58+
59+
### Rate limiting from Telegram
60+
61+
Telegram limits bots to ~30 messages/second. If you're posting claim alerts for high-volume tokens:
62+
63+
- Batch messages with a queue
64+
- Use `parse_mode: "HTML"` to combine multiple alerts into one message
65+
- Consider a minimum claim threshold to filter noise
66+
67+
### Grammy `GrammyError: Call to 'sendMessage' failed`
68+
69+
Common causes:
70+
- Bot was removed from the group/channel
71+
- Message too long (Telegram limit: 4096 chars)
72+
- Invalid HTML formatting (unclosed tags)
73+
- Bot blocked by user (for DM bots)
74+
75+
---
76+
77+
## Solana RPC Issues
78+
79+
### `Error: 429 Too Many Requests`
80+
81+
You're hitting RPC rate limits:
82+
83+
1. Use a dedicated RPC provider (Helius, QuickNode, Triton)
84+
2. Batch requests with `getMultipleAccountsInfo`
85+
3. Add retry logic with exponential backoff
86+
87+
```typescript
88+
const [acctA, acctB] = await connection.getMultipleAccountsInfo([pdaA, pdaB]);
89+
```
90+
91+
### `Error: failed to get info about account`
92+
93+
- The bonding curve may not exist yet (token not created)
94+
- The mint address may be wrong
95+
- The token may have graduated and the account closed
96+
97+
### WebSocket connection drops
98+
99+
Solana RPC WebSockets can be unstable. PumpKit bots should:
100+
101+
- Auto-reconnect on disconnect (monitor bot does this)
102+
- Use `onLogs` with a confirmed commitment level
103+
- Have a fallback HTTP polling mode
104+
105+
---
106+
107+
## Railway Deployment Issues
108+
109+
### Build fails on Railway
110+
111+
- Ensure `Dockerfile` is in the package root
112+
- Check that `tsconfig.json` `outDir` matches the Dockerfile `CMD` path
113+
- Verify all env vars are set in Railway dashboard
114+
115+
### Bot crashes with `ENOMEM`
116+
117+
Railway Hobby plan has 512MB RAM. Solutions:
118+
119+
- Use `--max-old-space-size=384` in your start command
120+
- Reduce concurrent RPC connections
121+
- Use SQLite instead of in-memory stores for large datasets
122+
123+
### Health check fails
124+
125+
Railway expects an HTTP health endpoint. PumpKit core provides one:
126+
127+
```typescript
128+
import { startHealthServer } from '@pumpkit/core';
129+
130+
startHealthServer({ port: parseInt(process.env.PORT || '3000') });
131+
```
132+
133+
---
134+
135+
## Claim Detection Issues
136+
137+
### Claims not being detected
138+
139+
1. **Check program IDs** — Ensure you're monitoring all 3 Pump programs:
140+
- Pump: `6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P`
141+
- PumpAMM: `pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA`
142+
- PumpFees: `pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ`
143+
2. **Check event parsing** — Log raw transaction data to verify events are being decoded
144+
3. **Check RPC commitment** — Use `confirmed` or `finalized`, not `processed`
145+
146+
### Wrong token displayed for claim
147+
148+
One social fee PDA can be a shareholder in multiple `SharingConfig` accounts (one per token). The `SocialFeeIndex` maps PDA → Set of mints. When multiple mints match:
149+
150+
- All candidate mints are fetched
151+
- The highest market cap token is displayed as primary
152+
- All linked tokens are shown in the message
153+
154+
### First-claim detection resets after redeploy
155+
156+
Local state is lost on redeploy. Solutions:
157+
158+
- Persist claim state to disk (PumpKit uses JSON files in `/data/`)
159+
- Cross-check with on-chain lifetime data via `getCreatorVaultBalanceBothPrograms`
160+
- Use the `-1` sentinel value for ambiguous first claims
161+
162+
---
163+
164+
## Still Stuck?
165+
166+
1. Check [FAQ](./faq.md) for quick answers
167+
2. Check [Error Reference](./errors.md) for specific error codes
168+
3. [Open a discussion](https://github.com/nirholas/pumpkit/discussions) on GitHub
169+
4. Review [RPC Best Practices](./rpc-best-practices.md) for connection issues

0 commit comments

Comments
 (0)