Skip to content

IMPLEMENTATION_SUMMARY.md

Latest commit

 

History

History
345 lines (281 loc) · 8.73 KB

IMPLEMENTATION_SUMMARY.md

File metadata and controls

345 lines (281 loc) · 8.73 KB

Implementation Summary: Solana Pump.fun Launch Radar

What Was Created

A complete, production-ready TypeScript application for detecting and analyzing Pump.fun token launches on Solana.

File Structure

solana-pump-radar/
├── .github/
│   └── workflows/
│       └── solana-pump-radar-ci.yml    # CI/CD pipeline
├── docs/
│   ├── PRD.md                          # Product requirements
│   ├── DECISION_LOG.md                 # Technical decisions
│   ├── RISK_REGISTER.md                # Risk analysis (FMEA)
│   ├── RUNBOOK.md                      # Operations guide
│   ├── CODEX_SAFE.md                   # AI dev guidelines
│   └── HELLFIRE_MODE.md                # Quality gates
├── fixtures/
│   └── pumpfun-create.sample.json      # Sample webhook payload
├── prisma/
│   └── schema.prisma                   # Database schema
├── scripts/
│   └── replay-fixture.ts               # Webhook replay tool
├── src/
│   ├── detector/
│   │   ├── pumpfun-detector.ts         # Instruction detection
│   │   └── pumpfun-detector.test.ts    # Detector tests
│   ├── queue/
│   │   └── processing-queue.ts         # Async job queue
│   ├── risk/
│   │   └── risk-scorer.ts              # Risk computation
│   ├── routes/
│   │   ├── webhook.ts                  # Webhook endpoint
│   │   └── api.ts                      # REST API endpoints
│   ├── schemas/
│   │   └── webhook-schemas.ts          # Zod validation
│   ├── config.ts                       # Config management
│   ├── db.ts                           # Prisma client
│   ├── logger.ts                       # Pino logger
│   └── index.ts                        # Main entry point
├── .env.example                        # Environment template
├── .eslintrc.json                      # ESLint config
├── .gitignore                          # Git ignore rules
├── .prettierrc                         # Prettier config
├── package.json                        # Dependencies & scripts
├── tsconfig.json                       # TypeScript config
├── vitest.config.ts                    # Test config
└── README.md                           # Documentation

Key Components

1. Webhook Handler (src/routes/webhook.ts)

  • Accepts POST requests with raw Solana transactions
  • Validates Authorization header (Bearer token)
  • Parses and validates payload with Zod
  • Detects Pump.fun creates
  • Stores in database (idempotent via UNIQUE signature)
  • Enqueues for risk scoring
  • Returns 200 immediately

2. Detector (src/detector/pumpfun-detector.ts)

  • Matches Pump.fun program ID: 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P
  • Checks instruction discriminator: [24, 30, 200, 40, 5, 28, 7, 119]
  • Extracts mint address from accounts[0]
  • Handles base58 decoding and binary parsing

3. Risk Scorer (src/risk/risk-scorer.ts)

  • Fetches mint info via @solana/spl-token
  • Checks mint/freeze authorities (+35/+25 points)
  • Computes holder concentration (+10-30 points)
  • Checks for Metaplex metadata (+5 if missing)
  • Produces score (0-100), label (LOW/MED/HIGH), and reasons

4. Processing Queue (src/queue/processing-queue.ts)

  • Uses p-queue for concurrency control
  • Deduplicates by mint address
  • Processes risk scoring async
  • Configurable concurrency (default 3)

5. REST API (src/routes/api.ts)

  • GET /launches - List recent launches
  • GET /tokens/:mint - Token detail + risk report
  • GET /healthz - Health check

6. Database (Prisma + SQLite)

  • LaunchEvent table (signature UNIQUE)
  • TokenRiskReport table (mint UNIQUE)
  • Automatic type generation
  • Easy migration path to PostgreSQL

Setup Steps

1. Initial Setup

cd solana-pump-radar
cp .env.example .env

Edit .env:

SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"  # Use Helius/QuickNode for production
WEBHOOK_SECRET="$(openssl rand -hex 32)"              # Generate secure secret

2. Install & Migrate

npm install
npm run db:generate
npm run db:migrate

3. Run Locally

npm run dev

Server runs on http://localhost:3000

4. Test Webhook

# In another terminal
npm run replay

5. Verify

curl http://localhost:3000/healthz
curl http://localhost:3000/launches

Production Deployment

Quick Deploy

npm ci --only=production
npm run db:generate
npm run db:migrate
npm run build
npm start

With PM2

pm2 start npm --name "pump-radar" -- start
pm2 save
pm2 startup

Environment Variables (Production)

PORT=3000
NODE_ENV=production
DATABASE_URL=file:./prod.db  # Or PostgreSQL connection string
SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
WEBHOOK_SECRET=<secure-secret>
QUEUE_CONCURRENCY=5
MAX_LAUNCHES_RESPONSE=100

Webhook Provider Setup

Helius (Recommended)

  1. Dashboard → Webhooks → Create
  2. Type: Raw Transaction
  3. URL: https://your-domain.com/webhooks/helius
  4. Auth Header: Bearer <WEBHOOK_SECRET>
  5. Account Address: 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P
  6. Transaction Types: All

Testing

Use Helius test button or:

npm run replay

CI/CD

GitHub Actions workflow runs on every PR:

  • ✓ Lint (ESLint + Prettier)
  • ✓ Type check (TypeScript strict mode)
  • ✓ Tests (Vitest)
  • ✓ Build (TypeScript compilation)

All must pass before merge.

Testing

Run Tests

npm test          # Watch mode
npm run test:ci   # CI mode

Test Coverage

  • Detector unit tests (instruction matching)
  • Webhook validation tests (Zod schemas)
  • Mock-based risk scorer tests (optional - add as needed)

Manual Testing

# Health check
curl http://localhost:3000/healthz

# Replay fixture
npm run replay

# Check launches
curl http://localhost:3000/launches

# Check specific token (after launch detected)
curl http://localhost:3000/tokens/<MINT_ADDRESS>

Architecture Decisions

Why SQLite?

  • Zero-config for MVP
  • Type-safe with Prisma
  • Easy migration to PostgreSQL later

Why Raw Webhooks?

  • Reliable instruction parsing
  • Provider-agnostic
  • Better for discriminator matching

Why Heuristic Scoring?

  • Explainable to users
  • Fast computation
  • No training data needed
  • Easy to iterate

See DECISION_LOG.md for full rationale.

Quality Gates (Hellfire Mode)

All enforced by CI:

  1. ✓ All tests pass
  2. ✓ TypeScript compiles (strict mode)
  3. ✓ ESLint clean
  4. ✓ Build succeeds

Manual gates: 5. ✓ Idempotency (duplicate webhooks handled) 6. ✓ Input validation (Zod schemas) 7. ✓ Observability (structured logging) 8. ✓ No secrets in code

See HELLFIRE_MODE.md for details.

Monitoring

Key Metrics

  • Webhook latency (p50, p95, p99)
  • Risk scoring duration
  • Queue depth
  • Launch detection rate
  • RPC error rate

Health Checks

# Database connectivity
curl http://localhost:3000/healthz

# Recent activity
curl http://localhost:3000/launches?limit=10

Logs

Structured JSON logs with Pino:

{
  "level": "info",
  "time": 1704067200000,
  "msg": "Detected Pump.fun creates",
  "detected": 2
}

Troubleshooting

Webhook 401 Error

# Check secret matches
echo $WEBHOOK_SECRET
# Update provider config with correct Bearer token

No Launches Detected

# Test with fixture
npm run replay

# Check webhook provider dashboard
# Verify account filter: 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P

Risk Scores Not Computing

# Check RPC connectivity
curl $SOLANA_RPC_URL -X POST -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

# Check queue stats (add endpoint or check logs)
# Increase QUEUE_CONCURRENCY if needed

See RUNBOOK.md for comprehensive troubleshooting.

Next Steps

Immediate

  1. Set up production RPC provider (Helius, QuickNode, Alchemy)
  2. Configure webhook provider
  3. Deploy with process manager (PM2/systemd)
  4. Set up monitoring/alerting
  5. Configure database backups

Future Enhancements

  • PostgreSQL migration for scale
  • WebSocket updates for real-time feeds
  • Historical backfill for past launches
  • Advanced ML-based risk models
  • Social sentiment integration
  • Multi-chain support
  • Alerting system (Discord/Telegram)

Support

Compliance

✓ No secrets committed ✓ Idempotent operations ✓ Input validation ✓ Error handling ✓ Structured logging ✓ CI/CD pipeline ✓ Comprehensive documentation ✓ Production-ready code