Migration Guide

Migrate from @solana/web3.js Connection to runicRPC.

Quick Migration

runicRPC is designed as a drop-in replacement:

Before

import { Connection } from '@solana/web3.js';

const connection = new Connection('https://api.mainnet-beta.solana.com');

const slot = await connection.getSlot();
const balance = await connection.getBalance(publicKey);

After

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

const rpc = RunicRPC.create({ useFallback: true });

const slot = await rpc.request('getSlot');
const balance = await rpc.request('getBalance', [publicKey.toString()]);

Key Differences

Method Calls

Connection uses methods:

await connection.getSlot();
await connection.getBalance(publicKey);
await connection.getAccountInfo(publicKey);

runicRPC uses request():

await rpc.request('getSlot');
await rpc.request('getBalance', [publicKey.toString()]);
await rpc.request('getAccountInfo', [publicKey.toString()]);

PublicKey Conversion

Connection accepts PublicKey objects. runicRPC requires strings:

import { PublicKey } from '@solana/web3.js';

const publicKey = new PublicKey('...');

// Connection
await connection.getBalance(publicKey);

// RunicRPC
await rpc.request('getBalance', [publicKey.toString()]);

Common Patterns

Getting Balance

// Before
const balance = await connection.getBalance(publicKey);

// After
const balance = await rpc.request('getBalance', [publicKey.toString()]);

Getting Account Info

// Before
const accountInfo = await connection.getAccountInfo(publicKey);

// After
const accountInfo = await rpc.request('getAccountInfo', [
  publicKey.toString(),
  { encoding: 'base64' }
]);

Sending Transactions

import { Transaction } from '@solana/web3.js';

const transaction = new Transaction().add(/* instructions */);

// Before
const signature = await connection.sendTransaction(transaction, [signer]);

// After
const signature = await rpc.request('sendTransaction', [
  transaction.serialize().toString('base64')
]);

Confirming Transactions

// Before
await connection.confirmTransaction(signature);

// After
await rpc.request('getSignatureStatuses', [[signature]]);

WebSocket Subscriptions

Account Subscribe

// Before
const subscriptionId = connection.onAccountChange(
  publicKey,
  (accountInfo) => {
    console.log('Account changed:', accountInfo);
  }
);

// After
const subscriptionId = await rpc.subscribe(
  'accountSubscribe',
  [publicKey.toString(), { encoding: 'base64' }],
  (accountInfo) => {
    console.log('Account changed:', accountInfo);
  }
);

Cleanup

// Before
connection.removeAccountChangeListener(subscriptionId);

// After
await rpc.unsubscribe(subscriptionId);

Benefits of Migration

1. Automatic Failover

const rpc = RunicRPC.create({
  providers: {
    helius: { apiKey: 'key1' },
    alchemy: { apiKey: 'key2' }
  }
});

// Automatically fails over if one provider is down

2. Circuit Breaker

Prevents cascading failures:

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

3. Intelligent Routing

Routes to fastest endpoint:

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

4. Request Caching

Automatic caching with TTL:

const rpc = RunicRPC.create({
  cache: {
    enabled: true,
    ttl: 1000
  }
});

5. Observability

Comprehensive events and metrics:

const stats = rpc.getStats();
console.log('Cache hit rate:', stats.cacheHitRate);
console.log('Total requests:', stats.totalRequests);

Gradual Migration

You can use both Connection and runicRPC during migration:

import { Connection } from '@solana/web3.js';
import { RunicRPC } from '@runic-rpc/sdk';

const connection = new Connection('https://api.mainnet-beta.solana.com');
const rpc = RunicRPC.create({ useFallback: true });

// Use RunicRPC for high-volume reads
const slot = await rpc.request('getSlot');

// Keep using Connection for complex operations
const transaction = await connection.sendTransaction(...);