npm package: @runic-rpc/sdk
Description: Production-grade Solana RPC load balancer with circuit breaking, retries, and health checks
Author: RunicRPC
Latest version: 0.1.2

# @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

### Helius

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

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

### Alchemy

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

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

### QuickNode

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

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

### Public Fallback

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

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

## License

MIT