@runic-rpc/sdk

> Ancient reliability for modern Solana infrastructure

Production-grade Solana RPC load balancer with zero runtime dependencies.

Features

- Zero dependencies (only peer @solana/web3.js)
- Circuit breaker prevents cascading failures
- Intelligent routing (round-robin, latency-based, weighted, random)
- Automatic retries with exponential backoff
- Rate limiting per endpoint
- Request caching with TTL
- Request deduplication
- Health checks with configurable intervals
- WebSocket support with auto-reconnect
- Comprehensive events for observability
- Prometheus metrics export

Installation

``bash
npm install @runic-rpc/sdk @solana/web3.js


or

pnpm add @runic-rpc/sdk @solana/web3.js

or

yarn add @runic-rpc/sdk @solana/web3.js
`

Quick Start

`typescript
import { RunicRPC, createHeliusEndpoint } from '@runic-rpc/sdk';

// Simple configuration with Helius
const rpc = new RunicRPC({
providers: {
helius: { apiKey: 'your-api-key' },
},
strategy: 'latency-based',
});

// Make RPC requests
const slot = await rpc.request('getSlot');
const balance = await rpc.request('getBalance', [publicKey]);

// Subscribe to WebSocket events
const subId = await rpc.subscribe(
'accountSubscribe',
[publicKey, { encoding: 'jsonParsed' }],
(data) => {
console.log('Account updated:', data);
}
);

// Cleanup
await rpc.close();
`

Advanced Configuration

`typescript
import { RunicRPC } from '@runic-rpc/sdk';

const rpc = new RunicRPC({
// Multiple providers
providers: {
helius: { apiKey: 'helius-key' },
alchemy: { apiKey: 'alchemy-key' },
},

// Routing strategy
strategy: 'latency-based', // or 'round-robin', 'weighted', 'random'

// Cache configuration
cache: {
enabled: true,
ttl: 1000, // 1 second
maxSize: 1000,
},

// Retry configuration
retry: {
maxAttempts: 3,
initialDelay: 100,
maxDelay: 5000,
backoffMultiplier: 2,
},

// Circuit breaker
circuitBreaker: {
failureThreshold: 5,
successThreshold: 2,
timeout: 30000, // 30 seconds
},

// Health checks
healthCheck: {
enabled: true,
interval: 30000, // 30 seconds
timeout: 5000,
unhealthyThreshold: 3,
healthyThreshold: 2,
},

// Rate limiting
rateLimit: 100, // requests per second per endpoint

// Logging
logLevel: 'info', // 'debug', 'info', 'warn', 'error'
});
`

Events

`typescript
// Listen for events
rpc.on('endpoint:healthy', (event) => {
console.log('Endpoint healthy:', event.endpoint);
});

rpc.on('endpoint:unhealthy', (event) => {
console.log('Endpoint unhealthy:', event.endpoint, event.reason);
});

rpc.on('circuit:open', (event) => {
console.log('Circuit opened:', event.endpoint);
});

rpc.on('request:retry', (event) => {
console.log('Retrying request:', event.method, 'attempt:', event.attempt);
});

rpc.on('cache:hit', (event) => {
console.log('Cache hit:', event.method);
});
`

Metrics

`typescript
// Get statistics
const stats = rpc.getStats();
console.log('Total requests:', stats.totalRequests);
console.log('Total errors:', stats.totalErrors);
console.log('Cache hit rate:', stats.cacheHitRate);

// Export Prometheus metrics
const metrics = rpc.exportPrometheusMetrics();
`

Providers

$3

`typescript
import { createHeliusEndpoint } from '@runic-rpc/sdk';

const endpoint = createHeliusEndpoint('your-api-key');
`

$3

`typescript
import { createAlchemyEndpoint } from '@runic-rpc/sdk';

const endpoint = createAlchemyEndpoint('your-api-key');
`

$3

`typescript
import { createQuicknodeEndpoint } from '@runic-rpc/sdk';

const endpoint = createQuicknodeEndpoint(
'https://your-endpoint.quiknode.pro/token/',
'wss://your-endpoint.quiknode.pro/token/'
);
`

$3

`typescript
import { createPublicEndpoint } from '@runic-rpc/sdk';

const endpoint = createPublicEndpoint();
// ⚠️ Warning: Public endpoints have strict rate limits
``

License

MIT