solana-flow/AGENTS.md

AGENTS.md - Solana Swap Flow

Project Overview

Real-time Solana DEX swap flow visualization dashboard. Displays a force-directed network graph showing token trading flows across Solana DEXes (Pump, Raydium, Meteora, Orca, Jupiter), powered by Helius API.

Architecture

Helius WebSocket (logsSubscribe for 9 DEX programs)
  → Collect tx signatures from logsNotification
  → Batch parse via Helius Enhanced Transactions API (100/batch, 3 concurrent, every 1.5s)
  → Extract SwapEvent { signature, timestamp, source, tokenIn, tokenOut }
  → Emit to listeners:
      ├── SSE endpoint → browser EventSource → Zustand store → D3 force graph
      └── DB writer → SQLite (swaps.db, 24h retention)

Tech Stack

Technology	Purpose
Next.js 16 (App Router) + TypeScript	Framework
D3.js (d3-force) + Canvas	Force-directed network graph rendering
Tailwind CSS v4	Dark theme styling
Zustand	Client state management
better-sqlite3	Persistent swap storage (24h retention)
ws	Server-side WebSocket to Helius RPC
lru-cache	Token metadata caching

Key Data Flow

1. WebSocket (src/lib/helius/websocket.ts): Connects to Helius RPC, subscribes to DEX program logs, collects transaction signatures. Includes ping/pong heartbeat (30s) and 60s silence auto-reconnect.

2. Batch Parser (src/lib/helius/batchParser.ts): Queues signatures, processes 3x100 batches every 1.5s via Helius Enhanced Transactions REST API. Caps pending queue at 3000.

3. Swap Parser (src/lib/helius/parseSwap.ts): Extracts SwapEvent from Helius parsed transaction response (events.swap field).

4. DB Writer (src/lib/db/writer.ts): Registers as batch parser listener, writes swap batches to SQLite transactionally. Prune job runs every 5 minutes.

5. SSE Endpoint (src/app/api/stream/route.ts): Streams real-time swaps to browser via Server-Sent Events. Supports AMM source filtering.

6. REST API (src/app/api/swaps/route.ts): Returns historical swaps from SQLite for selected timeframe (5m/30m/1h/12h/24h).

7. Client Store (src/lib/store.ts): Zustand store with swapBuffer, aggregation, graph nodes/links, timeframe/filter state.

8. Aggregator (src/lib/graph/aggregator.ts): Rolling window aggregation. Computes per-token inflow/outflow/netFlow, top pairs by volume. Limits graph to top 100 tokens by volume.

9. Graph Builder (src/lib/graph/graphBuilder.ts): Converts aggregated data to GraphNode[] + GraphLink[] with log-scale sizing, green/red coloring by net flow.

10. Force Graph Engine (src/components/ForceGraph/ForceGraphEngine.ts): D3 force simulation with Canvas rendering. SOL fixed at center. Supports zoom/pan/drag/click/hover.

Project Structure

src/
├── app/
│   ├── layout.tsx                    # Root layout, dark theme, Geist Mono font
│   ├── page.tsx                      # Renders <Dashboard />
│   ├── globals.css                   # Tailwind v4 CSS config
│   └── api/
│       ├── stream/route.ts           # SSE endpoint (real-time swaps)
│       ├── swaps/route.ts            # REST endpoint (historical from SQLite)
│       └── token/route.ts            # Token metadata (Helius DAS API)
├── components/
│   ├── Dashboard.tsx                 # Main layout + historical fetch effect
│   ├── Header.tsx                    # Status, stats, timeframe selector
│   ├── TimeframeSelector.tsx         # 5m/30m/1h/12h/24h buttons
│   ├── AMMFilter.tsx                 # Pump/Raydium/Meteora/Orca/Jupiter toggle
│   ├── ForceGraph/
│   │   ├── ForceGraph.tsx            # React canvas wrapper
│   │   └── ForceGraphEngine.ts       # D3 force simulation + Canvas render
│   └── Sidebar/
│       ├── TopPairs.tsx              # Top 30 trading pairs by volume
│       └── TokenDetail.tsx           # Token info card on click
├── hooks/
│   ├── useSwapStream.ts             # Client SSE hook + auto metadata fetch
│   └── useTokenMetadata.ts          # Single token metadata fetch
└── lib/
    ├── store.ts                     # Zustand store
    ├── timeframes.ts                # Timeframe type + config
    ├── utils.ts                     # Formatters
    ├── db/
    │   ├── index.ts                 # SQLite singleton (WAL mode, prepared stmts)
    │   └── writer.ts                # Batch parser → DB writer
    ├── graph/
    │   ├── aggregator.ts            # Rolling window aggregation (top 100 tokens)
    │   └── graphBuilder.ts          # Aggregated data → graph nodes/links
    └── helius/
        ├── constants.ts             # DEX program IDs, API URLs, known tokens
        ├── websocket.ts             # Helius WebSocket (logsSubscribe)
        ├── batchParser.ts           # Batch signature parser
        ├── parseSwap.ts             # Helius tx → SwapEvent
        └── tokenMetadata.ts         # DAS API getAsset + LRU cache

## Environment Variables

- `HELIUS_API_KEY` — Required. Helius API key for WebSocket and REST API access.

## Development

bash npm install cp .env.example .env.local # Set HELIUS_API_KEY npm run dev # Starts on port 3456

## Important Patterns

- **globalThis singleton**: `websocket.ts`, `batchParser.ts`, `db/index.ts` all use `globalThis` to persist state across Next.js HMR reloads.
- **Canvas rendering**: D3 force graph uses HTML Canvas (not SVG) for performance with 100+ nodes.
- **Top 100 filter**: Aggregator limits displayed tokens to top 100 by total volume. SOL always included.
- **WAL mode SQLite**: Allows concurrent reads (REST API) while writes (batch parser) happen.