Configuration

Complete reference for runicRPC configuration options.

Configuration Sources

runicRPC loads configuration from multiple sources with this priority (highest first):

1. Code config - Passed directly to create() or constructor
2. Environment variables - .env file or system env vars
3. Config file - runic.config.json

// Auto-load from env and config file
const rpc = RunicRPC.create();

// Override specific settings
const rpc = RunicRPC.create({
  strategy: 'round-robin',
  logLevel: 'debug'
});

Configuration Object

interface RunicRPCConfig {
  endpoints?: EndpointConfig[];
  providers?: ProviderConfig;
  strategy?: 'round-robin' | 'latency-based' | 'weighted' | 'random';
  cache?: CacheConfig;
  retry?: RetryConfig;
  circuitBreaker?: CircuitBreakerConfig;
  healthCheck?: HealthCheckConfig;
  rateLimit?: number;
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
  useFallback?: boolean;
}

Routing Strategies

Round Robin

Distributes requests evenly across healthy endpoints:

const rpc = RunicRPC.create({
  strategy: 'round-robin'
});

Use when: You want equal load distribution

Latency-Based (Recommended)

Routes to the fastest endpoint based on EWMA latency and success rate:

const rpc = RunicRPC.create({
  strategy: 'latency-based'
});

Use when: You want optimal performance

Weighted

Routes based on configured weights:

const rpc = RunicRPC.create({
  strategy: 'weighted',
  endpoints: [
    { name: 'primary', rpcUrl: '...', weight: 3 },
    { name: 'secondary', rpcUrl: '...', weight: 1 }
  ]
});

Use when: You want to prioritize certain endpoints

Random

Randomly selects from healthy endpoints:

const rpc = RunicRPC.create({
  strategy: 'random'
});

Use when: You want simple load distribution

Cache Configuration

const rpc = RunicRPC.create({
  cache: {
    enabled: true,
    ttl: 1000, // milliseconds
    maxSize: 1000, // max entries
    cacheableMethods: ['getSlot', 'getBalance', 'getAccountInfo'] // custom list
  }
});

Default cached methods: getSlot, getBalance, getAccountInfo, getBlockHeight, getEpochInfo, getHealth, getVersion, getGenesisHash

You can customize which methods are cached using cacheableMethods.

Retry Configuration

const rpc = RunicRPC.create({
  retry: {
    maxAttempts: 3,
    initialDelay: 100, // milliseconds
    maxDelay: 5000,
    backoffMultiplier: 2
  }
});

Circuit Breaker

const rpc = RunicRPC.create({
  circuitBreaker: {
    failureThreshold: 5, // consecutive failures before opening
    successThreshold: 2, // consecutive successes to close
    timeout: 30000 // milliseconds before trying HALF_OPEN
  }
});

Health Checks

const rpc = RunicRPC.create({
  healthCheck: {
    enabled: true,
    interval: 30000, // check every 30 seconds
    timeout: 5000, // 5 second timeout per check
    unhealthyThreshold: 3, // failures before marking unhealthy
    healthyThreshold: 2, // successes before marking healthy
    probeMethod: 'getHealth', // primary health check method
    probeFallback: 'getSlot' // fallback if primary fails
  }
});

Rate Limiting

const rpc = RunicRPC.create({
  rateLimit: 100 // requests per second per endpoint
});

Logging

const rpc = RunicRPC.create({
  logLevel: 'info' // 'debug' | 'info' | 'warn' | 'error'
});

Complete Example

With auto-loading from .env (recommended):

// Just set HELIUS_API_KEY and ALCHEMY_API_KEY in .env
const rpc = RunicRPC.create({
  strategy: 'latency-based',
  cache: {
    enabled: true,
    ttl: 1000,
    maxSize: 1000
  },
  retry: {
    maxAttempts: 3,
    initialDelay: 100,
    maxDelay: 5000
  },
  circuitBreaker: {
    failureThreshold: 5,
    timeout: 30000
  },
  healthCheck: {
    enabled: true,
    interval: 30000
  },
  rateLimit: 100,
  logLevel: 'info'
});

Or with explicit provider config:

const rpc = RunicRPC.create({
  providers: {
    helius: { apiKey: process.env.HELIUS_API_KEY! },
    alchemy: { apiKey: process.env.ALCHEMY_API_KEY! }
  },
  strategy: 'latency-based'
});

Environment Variables

runicRPC supports full configuration via environment variables:

Provider Keys

HELIUS_API_KEY=your-key
ALCHEMY_API_KEY=your-key
QUICKNODE_RPC_URL=https://...
QUICKNODE_WS_URL=wss://...

Core Settings

RUNIC_STRATEGY=latency-based
RUNIC_LOG_LEVEL=info
RUNIC_RATE_LIMIT=100
RUNIC_USE_FALLBACK=true

Cache Settings

RUNIC_CACHE_ENABLED=true
RUNIC_CACHE_TTL=1000
RUNIC_CACHE_MAX_SIZE=1000

Retry Settings

RUNIC_RETRY_MAX_ATTEMPTS=3
RUNIC_RETRY_INITIAL_DELAY=100
RUNIC_RETRY_MAX_DELAY=5000
RUNIC_RETRY_BACKOFF_MULTIPLIER=2

Circuit Breaker Settings

RUNIC_CB_FAILURE_THRESHOLD=5
RUNIC_CB_SUCCESS_THRESHOLD=2
RUNIC_CB_TIMEOUT=30000

Health Check Settings

RUNIC_HC_ENABLED=true
RUNIC_HC_INTERVAL=30000
RUNIC_HC_TIMEOUT=5000
RUNIC_HC_UNHEALTHY_THRESHOLD=3
RUNIC_HC_HEALTHY_THRESHOLD=2
RUNIC_HC_PROBE_METHOD=getHealth
RUNIC_HC_PROBE_FALLBACK=getSlot

Middleware Configuration

Add request/response middleware:

const rpc = RunicRPC.create({
  middleware: {
    beforeRequest: async (method, params) => {
      // Transform params before request
      return params;
    },
    afterResponse: async (method, result) => {
      // Transform result after response
      return result;
    },
    onError: async (method, error) => {
      // Handle errors
    }
  }
});