@ar.io/sdk 4.0.0-solana.22 → 4.0.0-solana.23

package/README.md

@@ -3140,6 +3140,110 @@ In the example above, the query will return ArNS records where:
 
 ## Advanced
 
+### RPC Configuration
+
+The SDK accepts any `@solana/kit` RPC client. For read-only usage, only
+`rpc` is required. Write operations additionally need `rpcSubscriptions`
+(WebSocket) for transaction confirmation and a `signer`.
+
+#### Basic (read-only)
+
+```ts
+import { ARIO } from '@ar.io/sdk';
+import { createSolanaRpc } from '@solana/kit';
+
+const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+const ario = ARIO.init({ rpc });
+```
+
+#### With writes (signer + WebSocket subscriptions)
+
+```ts
+import { ARIO } from '@ar.io/sdk';
+import {
+  createSolanaRpc,
+  createSolanaRpcSubscriptions,
+  createKeyPairSignerFromBytes,
+} from '@solana/kit';
+
+const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+const rpcSubscriptions = createSolanaRpcSubscriptions(
+  'wss://api.mainnet-beta.solana.com',
+);
+const signer = await createKeyPairSignerFromBytes(/* ... */);
+
+const ario = ARIO.init({ rpc, rpcSubscriptions, signer });
+```
+
+> **Note:** `rpcSubscriptions` opens a WebSocket connection and is only
+> needed for writes. If your RPC provider doesn't expose a WebSocket
+> endpoint, omit it and use the SDK in read-only mode.
+
+### Circuit Breaker
+
+The SDK ships an [opossum]-backed circuit breaker that wraps the RPC
+transport. When the primary endpoint starts failing (429 rate-limits,
+5xx errors, network timeouts) the circuit opens and subsequent calls
+route transparently to a fallback RPC until the primary recovers.
+
+```ts
+import { ARIO, createCircuitBreakerRpc } from '@ar.io/sdk';
+
+const rpc = createCircuitBreakerRpc({
+  primaryUrl: 'https://my-premium-rpc.example.com',
+  fallbackUrl: 'https://api.mainnet-beta.solana.com',
+});
+
+const ario = ARIO.init({ rpc });
+```
+
+Use `defaultFallbackUrl()` to auto-pick mainnet or devnet based on the
+primary URL:
+
+```ts
+import {
+  createCircuitBreakerRpc,
+  defaultFallbackUrl,
+} from '@ar.io/sdk';
+
+const primaryUrl = 'https://my-premium-rpc.example.com';
+const rpc = createCircuitBreakerRpc({
+  primaryUrl,
+  fallbackUrl: defaultFallbackUrl(primaryUrl), // → mainnet public RPC
+});
+```
+
+Tuning knobs (all optional):
+
+| Option | Default | Description |
+|---|---|---|
+| `timeout` | `10000` | ms before a single request is timed out (`false` to disable) |
+| `errorThresholdPercentage` | `50` | error % at which to open the circuit |
+| `resetTimeout` | `30000` | ms to wait before probing the primary again (half-open) |
+| `volumeThreshold` | `5` | minimum requests in the rolling window before the circuit can trip |
+
+### Automatic Retries
+
+All RPC **read** calls (account fetches, `getProgramAccounts`, etc.)
+automatically retry on transient transport errors with exponential
+back-off. Writes are **not** retried (to avoid double-sends).
+
+Retried errors: HTTP 429/5xx, `fetch failed`, `ECONNRESET`,
+`ETIMEDOUT`, `AbortError` / timeouts. Non-retryable errors (account
+not found, invalid params, deserialization) throw immediately.
+
+Defaults: **6 attempts**, 500 ms base delay, 5 s max delay. Override
+per-call with the exported `withRetry` helper:
+
+```ts
+import { withRetry } from '@ar.io/sdk';
+
+const result = await withRetry(() => rpc.getAccountInfo(addr).send(), {
+  maxAttempts: 3,
+  baseDelayMs: 1000,
+});
+```
+
 ### Generated instruction builders
 
 For custom transaction building, import Codama-emitted typed clients
@@ -3230,6 +3334,7 @@ For more information on how to contribute, please see [CONTRIBUTING.md].
 [ar-io-node repository]: https://github.com/ar-io/ar-io-node
 [ar.io Gateway Documentation]: https://docs.ar.io/gateways/ar-io-node/overview/
 [ANS-104]: https://github.com/ArweaveTeam/arweave-standards/blob/master/ans/ANS-104.md
+[opossum]: https://nodeshift.dev/opossum/
 
 ```
 

package/lib/esm/cli/commands/escrowCommands.js

@@ -21,10 +21,11 @@
  * - Ethereum: `--recipient-ethereum 0x...` parses the 20-byte hex address.
  */
 import { readFileSync } from 'node:fs';
-import { address, createKeyPairSignerFromBytes, createSolanaRpc, createSolanaRpcSubscriptions, } from '@solana/kit';
+import { address, createKeyPairSignerFromBytes, createSolanaRpcSubscriptions, } from '@solana/kit';
 import bs58 from 'bs58';
 import { ARIO_ANT_ESCROW_PROGRAM_ID } from '../../solana/constants.js';
 import { ANTEscrow } from '../../solana/escrow.js';
+import { createCircuitBreakerRpc, defaultFallbackUrl, } from '../../solana/rpc-circuit-breaker.js';
 // =========================================
 // Wiring helpers
 // =========================================
@@ -39,7 +40,10 @@ function escrowProgramIdFrom(options) {
 async function readEscrowReader(options) {
     const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ANTEscrow.init({
-        rpc: createSolanaRpc(rpcUrl),
+        rpc: createCircuitBreakerRpc({
+            primaryUrl: rpcUrl,
+            fallbackUrl: defaultFallbackUrl(rpcUrl),
+        }),
         programId: escrowProgramIdFrom(options),
     });
 }
@@ -58,7 +62,10 @@ async function writeEscrowFromOptions(options) {
     const signer = await createKeyPairSignerFromBytes(secretKey);
     const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ANTEscrow.init({
-        rpc: createSolanaRpc(rpcUrl),
+        rpc: createCircuitBreakerRpc({
+            primaryUrl: rpcUrl,
+            fallbackUrl: defaultFallbackUrl(rpcUrl),
+        }),
         rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
         signer,
         programId: escrowProgramIdFrom(options),

package/lib/esm/cli/utils.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { readFileSync } from 'fs';
-import { address, createKeyPairSignerFromBytes, createSolanaRpc, createSolanaRpcSubscriptions, } from '@solana/kit';
+import { address, createKeyPairSignerFromBytes, createSolanaRpcSubscriptions, } from '@solana/kit';
 import bs58 from 'bs58';
 import { program } from 'commander';
 import prompts from 'prompts';
@@ -22,6 +22,7 @@ import { ANTRegistry } from '../common/ant-registry.js';
 import { ANT } from '../common/ant.js';
 import { ARIO } from '../common/io.js';
 import { Logger } from '../common/logger.js';
+import { createCircuitBreakerRpc, defaultFallbackUrl, } from '../solana/rpc-circuit-breaker.js';
 import { fundFromOptions, isValidFundFrom, isValidIntent, validIntents, } from '../types/io.js';
 import { ARIOToken, mARIOToken } from '../types/token.js';
 import { globalOptions } from './options.js';
@@ -84,7 +85,7 @@ export function readARIOFromOptions(options) {
     setLoggerIfDebug(options);
     const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ARIO.init({
-        rpc: createSolanaRpc(rpcUrl),
+        rpc: createCliRpc(rpcUrl),
         ...(options.coreProgramId
             ? { coreProgramId: address(options.coreProgramId) }
             : {}),
@@ -100,7 +101,7 @@ export async function readANTRegistryFromOptions(options) {
     setLoggerIfDebug(options);
     const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ANTRegistry.init({
-        rpc: createSolanaRpc(rpcUrl),
+        rpc: createCliRpc(rpcUrl),
         ...(options.antProgramId
             ? { antProgramId: address(options.antProgramId) }
             : {}),
@@ -129,6 +130,16 @@ function wsUrlFromRpcUrl(rpcUrl) {
     url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
     return url.toString().replace(/\/$/, '');
 }
+/**
+ * Create a {@link SolanaRpc} wrapped with a circuit-breaker that falls back to
+ * the cluster's public RPC when the primary endpoint becomes unhealthy.
+ */
+function createCliRpc(rpcUrl) {
+    return createCircuitBreakerRpc({
+        primaryUrl: rpcUrl,
+        fallbackUrl: defaultFallbackUrl(rpcUrl),
+    });
+}
 /**
  * Load a Solana KeyPairSigner from --private-key (base58) or --wallet-file
  * (JSON array of bytes). Throws with a helpful message if neither is set.
@@ -155,7 +166,7 @@ export async function writeARIOFromOptions(options) {
     const signer = await loadSolanaSignerFromOptions(options);
     return {
         ario: ARIO.init({
-            rpc: createSolanaRpc(rpcUrl),
+            rpc: createCliRpc(rpcUrl),
             rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
             signer,
             // Forward program-id overrides so localnet / devnet writes target the
@@ -427,7 +438,7 @@ export async function readANTFromOptions(options) {
     const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ANT.init({
         processId: requiredProcessIdFromOptions(options),
-        rpc: createSolanaRpc(rpcUrl),
+        rpc: createCliRpc(rpcUrl),
         ...(options.antProgramId
             ? { antProgramId: address(options.antProgramId) }
             : {}),
@@ -438,7 +449,7 @@ export async function writeANTFromOptions(options) {
     const kitSigner = await loadSolanaSignerFromOptions(options);
     return ANT.init({
         processId: requiredProcessIdFromOptions(options),
-        rpc: createSolanaRpc(rpcUrl),
+        rpc: createCliRpc(rpcUrl),
         rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
         signer: kitSigner,
         ...(options.antProgramId
@@ -524,7 +535,7 @@ export async function spawnSolanaANTFromOptions(options) {
             'See sdk/scripts/devnet-validation/populate-ant.ts for an end-to-end example.');
     }
     return spawnSolanaANT({
-        rpc: createSolanaRpc(rpcUrl),
+        rpc: createCliRpc(rpcUrl),
         rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
         signer: kitSigner,
         state: {

package/lib/esm/solana/ant-readable.js

@@ -9,6 +9,7 @@
  */
 import { address, fetchEncodedAccount, } from '@solana/kit';
 import bs58 from 'bs58';
+import { withRetry } from './retry.js';
 // AntRecordMetadata discriminator — regenerate via `yarn codegen` after IDL rebase
 // to expose ANT_RECORD_METADATA_DISCRIMINATOR. Until then, compute inline.
 import { createHash as __createHash } from 'crypto';
@@ -102,9 +103,9 @@ export class SolanaANTReadable {
         });
     }
     async getAccount(pda) {
-        return fetchEncodedAccount(this.rpc, pda, {
+        return withRetry(() => fetchEncodedAccount(this.rpc, pda, {
             commitment: this.commitment,
-        });
+        }));
     }
     // =========================================
     // Config reads
@@ -204,20 +205,20 @@ export class SolanaANTReadable {
             },
         ];
         const [recordAccounts, metaAccounts] = (await Promise.all([
-            this.rpc
+            withRetry(() => this.rpc
                 .getProgramAccounts(this.antProgram, {
                 commitment: this.commitment,
                 encoding: 'base64',
                 filters: gpaFilter(bs58.encode(ANT_RECORD_DISCRIMINATOR)),
             })
-                .send(),
-            this.rpc
+                .send()),
+            withRetry(() => this.rpc
                 .getProgramAccounts(this.antProgram, {
                 commitment: this.commitment,
                 encoding: 'base64',
                 filters: gpaFilter(bs58.encode(ANT_RECORD_METADATA_DISCRIMINATOR)),
             })
-                .send(),
+                .send()),
         ]));
         // Index metadata by undername hash for O(1) lookup.
         // AntRecordMetadata has undername_hash at offset 40 (8 disc + 32 mint).

package/lib/esm/solana/index.js

@@ -95,6 +95,10 @@ export * from './constants.js';
 // `/devnet-config.json` — kept in sync via the drift guard test
 // `clusters.test.ts`.
 export * from './clusters.js';
+// RPC circuit breaker (opossum-backed transparent fallback)
+export { createCircuitBreakerRpc, defaultFallbackUrl, } from './rpc-circuit-breaker.js';
+// Retry utility (exponential back-off for transient RPC errors)
+export { withRetry, isRetryableError } from './retry.js';
 // Event decoders
 //
 // `parseTransactionEvents(rpc, signature)` and `parseEventsFromLogs(logs)`

package/lib/esm/solana/io-readable.js

@@ -18,6 +18,7 @@ import { computeLiveDelegationBalance } from './delegation-math.js';
 import { deserializeAllowlist, deserializeArioConfig, deserializeArnsRecord, deserializeDelegation, deserializeDemandFactor, deserializeEpoch, deserializeEpochSettings, deserializeEpochSettingsFull, deserializeGarSettings, deserializeGarSupplyCounters, deserializeGateway, deserializeGatewayWithAccumulator, deserializeObservation, deserializePrimaryName, deserializePrimaryNameRequest, deserializeRedelegationRecord, deserializeReservedName, deserializeReturnedName, deserializeVault, deserializeWithdrawal, } from './deserialize.js';
 import { TOKEN_PROGRAM_ADDRESS } from './instruction.js';
 import { getArioConfigPDA, getArnsRecordPDA, getArnsRecordPDAFromHash, getArnsSettingsPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getObserverLookupPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, } from './pda.js';
+import { withRetry } from './retry.js';
 const addressDecoder = getAddressDecoder();
 /** All-zero address — equivalent of web3.js `PublicKey.default`. */
 const DEFAULT_ADDRESS = address('11111111111111111111111111111111');
@@ -141,9 +142,9 @@ export class SolanaARIOReadable {
     }
     /** Helper to fetch an encoded account (kit's replacement for Connection.getAccountInfo). */
     async getAccount(pda) {
-        return fetchEncodedAccount(this.rpc, pda, {
+        return withRetry(() => fetchEncodedAccount(this.rpc, pda, {
             commitment: this.commitment,
-        });
+        }));
     }
     /**
      * Helper for `getProgramAccounts` with a discriminator memcmp filter.
@@ -168,7 +169,7 @@ export class SolanaARIOReadable {
         // when called without `withContext: true`. With `encoding: 'base64'`, each
         // account's `data` is a `[base64, 'base64']` tuple. We bypass kit's strict
         // generic overload typing here with a cast — the runtime shape is stable.
-        const result = (await this.rpc
+        const result = await withRetry(() => this.rpc
             .getProgramAccounts(programId, {
             commitment: this.commitment,
             encoding: 'base64',
@@ -195,9 +196,9 @@ export class SolanaARIOReadable {
         if (unique.length === 0)
             return new Map();
         const pdas = await Promise.all(unique.map(async (op) => (await getGatewayPDA(address(op), this.garProgram))[0]));
-        const accounts = await fetchEncodedAccounts(this.rpc, pdas, {
+        const accounts = await withRetry(() => fetchEncodedAccounts(this.rpc, pdas, {
             commitment: this.commitment,
-        });
+        }));
         const out = new Map();
         for (let i = 0; i < accounts.length; i++) {
             const acct = accounts[i];
@@ -387,7 +388,7 @@ export class SolanaARIOReadable {
                 },
             },
         ];
-        const result = (await this.rpc
+        const result = await withRetry(() => this.rpc
             .getProgramAccounts(TOKEN_PROGRAM_ADDRESS, {
             commitment: this.commitment,
             encoding: 'base64',

package/lib/esm/solana/json-rpc.js

@@ -5,6 +5,7 @@
  * the RPC client's response shape.
  */
 import { address } from '@solana/kit';
+import { withRetry } from './retry.js';
 /**
  * Map an arbitrary commitment string to one of kit's three supported tiers.
  * Anything we don't recognise (or `undefined`) falls back to `confirmed`,
@@ -24,12 +25,12 @@ function toKitCommitment(commitment) {
  * doesn't exist (so callers can handle "missing PDA" without try/catch).
  */
 export async function getAccountInfoLegacy(rpc, pda, commitment) {
-    const res = await rpc
+    const res = await withRetry(() => rpc
         .getAccountInfo(pda, {
         encoding: 'base64',
         commitment: toKitCommitment(commitment),
     })
-        .send();
+        .send());
     if (!res.value)
         return null;
     const [dataB64] = res.value.data;
@@ -53,12 +54,12 @@ export async function getAccountInfoLegacy(rpc, pda, commitment) {
 export async function getMultipleAccountsInfoLegacy(rpc, pdas, commitment) {
     if (pdas.length === 0)
         return [];
-    const res = await rpc
+    const res = await withRetry(() => rpc
         .getMultipleAccounts(pdas, {
         encoding: 'base64',
         commitment: toKitCommitment(commitment),
     })
-        .send();
+        .send());
     return res.value.map((acct) => {
         if (!acct)
             return null;

package/lib/esm/solana/retry.js

@@ -0,0 +1,102 @@
+/**
+ * Lightweight retry helper with exponential back-off + jitter for Solana RPC
+ * read calls.
+ *
+ * Wraps any async function so transient transport errors (HTTP 429/5xx,
+ * network timeouts, etc.) are retried automatically while "normal" failures
+ * (account-not-found, deserialization) bubble immediately.
+ *
+ * Usage:
+ * ```ts
+ * const account = await withRetry(() => fetchEncodedAccount(rpc, pda));
+ * ```
+ */
+import { Logger } from '../common/logger.js';
+const logger = new Logger({ level: 'error' });
+const DEFAULT_MAX_ATTEMPTS = 6;
+const DEFAULT_BASE_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 5_000;
+/**
+ * Default retryable-error heuristic.
+ *
+ * We retry on:
+ * - Network / fetch errors (`TypeError: fetch failed`)
+ * - HTTP 429 (rate-limit) and 5xx (server) surfaced by kit's transport as
+ *   `SolanaError` with "HTTP error (4xx|5xx)" in the message.
+ * - Timeout errors from opossum or native `AbortError`.
+ *
+ * We do NOT retry on:
+ * - JSON-RPC application errors (account not found, invalid params, etc.)
+ * - Deserialization / decoding errors
+ * - Any error without a recognisable transport signature
+ */
+export function isRetryableError(error) {
+    if (error == null)
+        return false;
+    const name = error.name ?? '';
+    const message = String(error.message ?? '');
+    const code = error.context
+        ?.__code;
+    // SolanaError from kit's transport for HTTP 429 / 5xx
+    if (/HTTP error \(4(?:0[89]|[1-9]\d)|HTTP error \(5\d\d\)/.test(message))
+        return true;
+    // Specific 429 match (rate-limit) — always retry
+    if (/HTTP error \(429\)/.test(message))
+        return true;
+    // Network-level failures: fetch failed, ECONNRESET, ETIMEDOUT, etc.
+    if (name === 'TypeError' && /fetch failed/i.test(message))
+        return true;
+    if (/ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN/i.test(message))
+        return true;
+    // Abort / timeout
+    if (name === 'AbortError' || name === 'TimeoutError')
+        return true;
+    if (/timed out/i.test(message))
+        return true;
+    // Opossum circuit-breaker open — the breaker itself will fallback, but if
+    // we're layered on top we shouldn't retry (the breaker handles it).
+    if (/breaker is open/i.test(message))
+        return false;
+    // Numeric Solana JSON-RPC codes that indicate transient overload
+    if (typeof code === 'number' && (code === -32005 || code === -32016))
+        return true;
+    return false;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function jitteredDelay(base, attempt, cap) {
+    const exponential = base * 2 ** attempt;
+    const capped = Math.min(exponential, cap);
+    return capped * (0.5 + Math.random() * 0.5);
+}
+/**
+ * Execute `fn` with automatic retries on transient failures.
+ *
+ * ```ts
+ * const data = await withRetry(() => rpc.getAccountInfo(addr).send());
+ * ```
+ */
+export async function withRetry(fn, opts) {
+    const maxAttempts = opts?.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    const baseDelayMs = opts?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+    const maxDelayMs = opts?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const retryable = opts?.isRetryable ?? isRetryableError;
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            const isLast = attempt === maxAttempts - 1;
+            if (isLast || !retryable(error)) {
+                throw error;
+            }
+            const delay = jitteredDelay(baseDelayMs, attempt, maxDelayMs);
+            logger.debug(`[retry] attempt ${attempt + 1}/${maxAttempts} failed, retrying in ${Math.round(delay)}ms`, { error: String(error) });
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}

package/lib/esm/solana/rpc-circuit-breaker.js

@@ -0,0 +1,75 @@
+/**
+ * Circuit-breaker wrapper for Solana RPC transports using
+ * [opossum](https://nodeshift.dev/opossum/).
+ *
+ * When the primary RPC endpoint starts failing (rate-limits, downtime, etc.)
+ * the circuit opens and subsequent calls are routed transparently to a
+ * fallback RPC until the primary recovers.
+ *
+ * Works at the **transport level** — no Proxy magic required. Every RPC
+ * method (`getAccountInfo`, `sendTransaction`, etc.) goes through the same
+ * transport function, so a single circuit breaker covers them all.
+ *
+ * Usage:
+ * ```ts
+ * import { ARIO, createCircuitBreakerRpc } from '@ar.io/sdk';
+ *
+ * const rpc = createCircuitBreakerRpc({
+ *   primaryUrl: 'https://my-premium-rpc.example.com',
+ *   fallbackUrl: 'https://api.mainnet-beta.solana.com',
+ * });
+ *
+ * const ario = ARIO.init({ rpc });
+ * ```
+ */
+import { createDefaultRpcTransport, createSolanaRpcFromTransport, } from '@solana/kit';
+import CircuitBreaker from 'opossum';
+import { Logger } from '../common/logger.js';
+const logger = new Logger({ level: 'error' });
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULT_MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
+const DEFAULT_DEVNET_RPC = 'https://api.devnet.solana.com';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Create a {@link SolanaRpc} whose transport is backed by an opossum circuit
+ * breaker. Reads and writes flow through the primary transport; when it
+ * becomes unhealthy the circuit opens and subsequent calls are routed to
+ * the fallback transport until the primary recovers.
+ */
+export function createCircuitBreakerRpc({ primaryUrl, fallbackUrl, circuitBreakerOptions: opts = {}, }) {
+    const primaryTransport = createDefaultRpcTransport({ url: primaryUrl });
+    const fallbackTransport = createDefaultRpcTransport({ url: fallbackUrl });
+    const breaker = new CircuitBreaker((request) => primaryTransport(request), {
+        timeout: opts.timeout ?? 10_000,
+        errorThresholdPercentage: opts.errorThresholdPercentage ?? 50,
+        resetTimeout: opts.resetTimeout ?? 30_000,
+        volumeThreshold: opts.volumeThreshold ?? 5,
+    });
+    breaker.fallback((request) => fallbackTransport(request));
+    breaker.on('open', () => {
+        logger.warn('[rpc-circuit-breaker] circuit OPEN — routing to fallback RPC');
+    });
+    breaker.on('halfOpen', () => {
+        logger.info('[rpc-circuit-breaker] circuit HALF-OPEN — probing primary RPC');
+    });
+    breaker.on('close', () => {
+        logger.info('[rpc-circuit-breaker] circuit CLOSED — primary RPC recovered');
+    });
+    const transport = ((request) => breaker.fire(request));
+    return createSolanaRpcFromTransport(transport);
+}
+/**
+ * Convenience: pick a sensible public fallback URL based on the primary URL.
+ *
+ * - Primary contains `devnet` → devnet public RPC
+ * - Everything else → mainnet-beta public RPC
+ */
+export function defaultFallbackUrl(primaryUrl) {
+    if (/devnet/i.test(primaryUrl))
+        return DEFAULT_DEVNET_RPC;
+    return DEFAULT_MAINNET_RPC;
+}

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '4.0.0-solana.22';
+export const version = '4.0.0-solana.23';

package/lib/types/solana/index.d.ts

@@ -62,6 +62,10 @@ export { BorshReader, BorshWriter, deserializeGateway, deserializeArnsRecord, de
 export type { DeserializedAclEntry } from './deserialize.js';
 export * from './constants.js';
 export * from './clusters.js';
+export { createCircuitBreakerRpc, defaultFallbackUrl, } from './rpc-circuit-breaker.js';
+export type { CircuitBreakerRpcConfig, CircuitBreakerRpcOptions, } from './rpc-circuit-breaker.js';
+export { withRetry, isRetryableError } from './retry.js';
+export type { RetryOptions } from './retry.js';
 export type { SolanaConfig, SolanaReadConfig, SolanaWriteConfig, SolanaRpc, SolanaRpcSubscriptions, SolanaSigner, SolanaTransactionResult, AccountData, } from './types.js';
 export { parseTransactionEvents, parseEventsFromLogs, isEvent, } from './events.js';
 export type { AnyEvent, AnyArioCoreEvent, AnyArioGarEvent, AnyArioArnsEvent, AnyArioAntEvent, AnyArioAntEscrowEvent, EventName, } from './events.js';

package/lib/types/solana/retry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Lightweight retry helper with exponential back-off + jitter for Solana RPC
+ * read calls.
+ *
+ * Wraps any async function so transient transport errors (HTTP 429/5xx,
+ * network timeouts, etc.) are retried automatically while "normal" failures
+ * (account-not-found, deserialization) bubble immediately.
+ *
+ * Usage:
+ * ```ts
+ * const account = await withRetry(() => fetchEncodedAccount(rpc, pda));
+ * ```
+ */
+export interface RetryOptions {
+    /** Maximum number of attempts (first call + retries). @default 6 */
+    maxAttempts?: number;
+    /** Base delay in ms before the first retry. Doubled each attempt. @default 500 */
+    baseDelayMs?: number;
+    /** Cap on any single delay in ms. @default 5_000 */
+    maxDelayMs?: number;
+    /** Predicate that decides whether a thrown error is retryable.
+     *  Defaults to {@link isRetryableError}. */
+    isRetryable?: (error: unknown) => boolean;
+}
+/**
+ * Default retryable-error heuristic.
+ *
+ * We retry on:
+ * - Network / fetch errors (`TypeError: fetch failed`)
+ * - HTTP 429 (rate-limit) and 5xx (server) surfaced by kit's transport as
+ *   `SolanaError` with "HTTP error (4xx|5xx)" in the message.
+ * - Timeout errors from opossum or native `AbortError`.
+ *
+ * We do NOT retry on:
+ * - JSON-RPC application errors (account not found, invalid params, etc.)
+ * - Deserialization / decoding errors
+ * - Any error without a recognisable transport signature
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Execute `fn` with automatic retries on transient failures.
+ *
+ * ```ts
+ * const data = await withRetry(() => rpc.getAccountInfo(addr).send());
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;

package/lib/types/solana/rpc-circuit-breaker.d.ts

@@ -0,0 +1,49 @@
+import type { SolanaRpc } from './types.js';
+export interface CircuitBreakerRpcOptions {
+    /**
+     * Time in ms before a single RPC request is considered timed-out.
+     * Set to `false` to disable the opossum-level timeout (rely on the
+     * underlying transport timeout only).
+     * @default 10_000
+     */
+    timeout?: number | false;
+    /**
+     * Error percentage (0-100) at which to open the circuit.
+     * @default 50
+     */
+    errorThresholdPercentage?: number;
+    /**
+     * Time in ms to wait before entering half-open state and retrying
+     * the primary.
+     * @default 30_000
+     */
+    resetTimeout?: number;
+    /**
+     * Minimum number of requests within the rolling window before the
+     * circuit can trip. Prevents opening the circuit after a single failure.
+     * @default 5
+     */
+    volumeThreshold?: number;
+}
+export interface CircuitBreakerRpcConfig {
+    /** URL for the primary (preferred) RPC endpoint. */
+    primaryUrl: string;
+    /** URL for the fallback RPC endpoint (used when the circuit opens). */
+    fallbackUrl: string;
+    /** Opossum circuit-breaker tuning knobs. */
+    circuitBreakerOptions?: CircuitBreakerRpcOptions;
+}
+/**
+ * Create a {@link SolanaRpc} whose transport is backed by an opossum circuit
+ * breaker. Reads and writes flow through the primary transport; when it
+ * becomes unhealthy the circuit opens and subsequent calls are routed to
+ * the fallback transport until the primary recovers.
+ */
+export declare function createCircuitBreakerRpc({ primaryUrl, fallbackUrl, circuitBreakerOptions: opts, }: CircuitBreakerRpcConfig): SolanaRpc;
+/**
+ * Convenience: pick a sensible public fallback URL based on the primary URL.
+ *
+ * - Primary contains `devnet` → devnet public RPC
+ * - Everything else → mainnet-beta public RPC
+ */
+export declare function defaultFallbackUrl(primaryUrl: string): string;

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "4.0.0-solana.21";
+export declare const version = "4.0.0-solana.22";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.0.0-solana.22",
+  "version": "4.0.0-solana.23",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"
@@ -87,6 +87,7 @@
     "@swc/core": "^1.11.22",
     "@trivago/prettier-plugin-sort-imports": "^4.2.0",
     "@types/node": "^22.14.1",
+    "@types/opossum": "^8.1.9",
     "@types/prompts": "^2.4.9",
     "@types/sinon": "^10.0.15",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
@@ -128,11 +129,12 @@
     "@solana/kit": "^6.8.0",
     "bs58": "^6.0.0",
     "commander": "^12.1.0",
+    "opossum": "^9.0.0",
     "prompts": "^2.4.2",
     "zod": "^3.25.76"
   },
   "lint-staged": {
-    "**/*.{ts,js,mjs,cjs,md,json}": ["biome format --write"],
+    "**/*.{ts,js,mjs,cjs,json}": ["biome format --write"],
     "**/README.md": ["markdown-toc-gen insert --max-depth 2"]
   }
 }