Pool Discovery Service - Architectural Update

Date: January 1, 2026 Status: 🚨 Important - Service Responsibility Change Related: 25-POOL-DISCOVERY-DESIGN.md, 30.6-POOL-STATE-OWNERSHIP.md

Summary

The Pool Discovery Service has been simplified to focus ONLY on discovering new pools. Pool state management (WebSocket subscriptions, RPC updates, caching) has been moved to the Local Quote Service.

What Changed?

OLD (Dual Responsibility)

Pool Discovery Service:
├─ Discover new pools (RPC scanning)
├─ Update pool state (WebSocket subscriptions) ❌ REMOVED
├─ RPC backup polling ❌ REMOVED
└─ Redis persistence ❌ REMOVED

NEW (Single Responsibility)

Pool Discovery Service:
├─ Discover new pools (RPC scanning) ✅
├─ Solscan enrichment (initial only) ✅
├─ Default reserves (1T units) ✅
└─ NATS event publishing ✅

Local Quote Service:
├─ WebSocket subscriptions (all pools) ← MOVED HERE
├─ RPC backup polling ← MOVED HERE
├─ In-memory cache ← MOVED HERE
└─ Redis persistence (backup) ← MOVED HERE

Current Responsibilities

Pool Discovery Service

ONLY Does:

1. RPC Scanning: Discover new pools via GetProgramAccountsWithOpts
   • Bidirectional queries (forward + reverse)
   • 6 DEX protocols supported
   • Deduplication by pool ID
2. Solscan Enrichment: Fetch initial pool data
   • TVL (liquidity USD)
   • Reserve amounts (base + quote)
   • Token decimals
   • Best effort: If fails, use default reserves
3. Default Reserves: Set large defaults to avoid premature filtering
   • BaseReserve: 1,000,000,000,000 (1 trillion units)
   • QuoteReserve: 1,000,000,000,000 (1 trillion units)
   • Never nil, never zero
4. NATS Event Publishing: Notify downstream services
   • pool.discovered.{dex}: New pool found
   • pool.enriched.{dex}: Solscan data added
   • Payload includes pool metadata + reserves

Does NOT Do:

• ❌ WebSocket subscriptions
• ❌ Pool state updates
• ❌ RPC backup polling
• ❌ Redis writes

Local Quote Service

New Responsibilities:

1. Subscribe to NATS pool.discovered.* events
2. Manage WebSocket subscriptions for all pool types
3. Handle pool updates via WebSocket account notifications
4. RPC backup polling (30s interval on WebSocket failure)
5. In-memory cache (hot pools: <1μs access)
6. Redis persistence (async, 10s interval, backup only)

Why This Change?

Problems with Dual Responsibility

1. Complexity: Two services managing pool state
2. Redis Bottleneck: 1-2ms access vs <1μs in-memory
3. Unavoidable RPC: Quote Service needed RPC anyway for CLMM/DLMM ticks (too large for Redis)
4. Debugging Difficulty: Pool updates tracked in two places
5. Deployment Coordination: Changes to one service affected the other

Benefits of Single Responsibility

✅ 1000x faster pool access: In-memory <1μs vs Redis 1-2ms ✅ Single source of truth: Quote Service owns all pool state ✅ Simpler debugging: All pool updates in one service ✅ WebSocket-first updates: Sub-second freshness vs 10s polling ✅ Clear ownership: No coordination needed between services

Impact on Existing Documentation

25-POOL-DISCOVERY-DESIGN.md

Sections Still Accurate:

• ✅ Problem Analysis (unidirectional matching, bidirectional solution)
• ✅ Token pair management (LST/SOL, triangular arbitrage)
• ✅ Protocol support (6 DEXes)
• ✅ RPC discovery logic
• ✅ Solscan enrichment
• ✅ NATS event publishing

Sections Now Historical (moved to Local Quote Service):

• ⚠️ WebSocket subscription management
• ⚠️ RPC backup polling
• ⚠️ Redis pool state writes
• ⚠️ “Three-tier hybrid architecture”

Interpretation: The document remains valuable for understanding discovery logic, but WebSocket/RPC update sections describe features now in Local Quote Service.

New Documentation

• 30.6-POOL-STATE-OWNERSHIP.md: Complete architecture of the new design
  • Pool state ownership migration
  • WebSocket subscription management (in Quote Service)
  • In-memory cache architecture
  • Redis as backup only
  • Migration timeline

Migration Status

Quick Reference

Pool Discovery Service

File: go/cmd/pool-discovery-service/main.go

Key Functions:

ScanForPools(ctx, baseMint, quoteMint) error
  └─ Bidirectional RPC queries
  └─ Solscan enrichment (best effort)
  └─ Default reserves (1T units)
  └─ Publish NATS events

publishPoolDiscovered(pool) error
  └─ NATS: pool.discovered.{dex}

NATS Events:

• Subject: pool.discovered.raydium_amm
• Subject: pool.discovered.raydium_clmm
• Subject: pool.discovered.meteora_dlmm
• Subject: pool.enriched.{dex}

Local Quote Service

File: go/cmd/local-quote-service/main.go

Key Functions:

subscribeToPoolDiscovery(ctx) error
  └─ NATS: pool.discovered.*
  └─ Add to in-memory cache
  └─ Subscribe WebSocket
  └─ Queue RPC refresh

handlePoolDiscovered(event) error
  └─ Validate reserves (never nil/zero)
  └─ Add to cache
  └─ WebSocket subscribe
  └─ High-priority RPC refresh

WebSocket Manager:

• Subscription management
• Reconnection logic
• Account update handling
• Pool-specific decoders

Related Documents

1. 25-POOL-DISCOVERY-DESIGN.md: Original service design (historical WebSocket/RPC sections)
2. 30-QUOTE-SERVICE-ARCHITECTURE.md: Main Quote Service architecture
3. 30.6-POOL-STATE-OWNERSHIP.md: Detailed migration architecture ⭐ READ THIS

Document Version: 1.0 Last Updated: January 1, 2026 Maintainer: Solution Architect Team