System Architecture
Comprehensive overview of runicRPC's technical architecture, component interactions, and data flow patterns.
High-Level Architecture
Application Layer
Your Solana application interacts with runicRPC through the standard @solana/web3.js Connection interface. No code changes required.
const connection = runicRpc.getConnection();
await connection.getBalance(pubkey);runicRPC Core
The orchestration layer that manages routing, circuit breaking, retries, and health checks. All decisions are made in sub-millisecond timeframes.
- •Routing engine with 4 strategies
- •Circuit breakers per endpoint
- •Request/response pipeline
Transport Layer
Manages HTTP and WebSocket connections with automatic reconnection, subscription management, and failover logic.
- •HTTP client with connection pooling
- •WebSocket manager with auto-reconnect
- •Subscription tracking & recovery
RPC Providers
Multiple Solana RPC providers configured as endpoints. runicRPC abstracts the complexity of managing multiple providers.
- •Helius, Alchemy, QuickNode
- •Public Solana endpoints
- •Custom provider support
Request Flow
Request Received & Middleware
Application makes RPC call. beforeRequest middleware transforms params if configured. Request enters the pipeline.
Cache Check
For cacheable methods (configurable), check LRU cache with fair eviction. If hit, return immediately (0.2ms latency).
Deduplication
Check if identical request is already in-flight. If yes, attach to existing promise instead of making duplicate call.
Endpoint Selection
Provider-specific routing for special methods, or standard routing strategy based on latency, success rate, and health.
Circuit Breaker Check
Verify endpoint circuit is closed. If open, skip this endpoint and try next one.
Rate Limit Check
Token bucket algorithm checks if request can proceed without violating rate limits.
Execute Request
Send RPC request to selected provider via HTTP or WebSocket. Track latency and outcome.
Retry on Failure
If request fails with retryable error, apply exponential backoff and try again (up to maxRetries).
Update Metrics
Record latency, update EWMA, adjust success rates, and emit observability events.
Return Response & Middleware
Apply afterResponse middleware if configured. Store in cache if applicable. Return transformed response to application.