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

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

@@ -54,7 +54,7 @@ export { ARWEAVE_TX_REGEX, AR_IO_PROTOCOL, arweaveUri, FQDN_REGEX, MARIO_PER_ARI
 // Solana implementation classes (still exported for advanced/direct usage —
 // the `ARIO` / `ANT` factories above wrap these).
 export { SolanaARIOReadable } from './io-readable.js';
-export { SolanaARIOWriteable } from './io-writeable.js';
+export { isInvalidGatewayAccountError, SolanaARIOWriteable, } from './io-writeable.js';
 // ANT classes
 export { SolanaANTReadable } from './ant-readable.js';
 export { SolanaANTWriteable } from './ant-writeable.js';
@@ -88,6 +88,8 @@ export { hashName, getArioConfigPDA, getBalancePDA, getVaultPDA, getVaultCounter
 // `ANT_RECORD_DISCRIMINATOR`). Pull them from there instead of asking
 // this module — single source of truth, derived from the IDL.
 export { BorshReader, BorshWriter, deserializeGateway, deserializeArnsRecord, deserializeVault, deserializeDelegation, deserializeBalance, deserializeEpochSettings, deserializeArioConfig, deserializeDemandFactor, deserializeReservedName, deserializeReturnedName, deserializeWithdrawal, deserializeRedelegationRecord, deserializePrimaryNameRequest, deserializePrimaryName, deserializeAllowlist, deserializeGarSettings, deserializeEpochSettingsFull, deserializeEpoch, deserializeObservation, deserializeAntConfig, deserializeAntControllers, deserializeAntRecord, deserializeAclConfig, deserializeAclPage, } from './deserialize.js';
+// Off-chain prediction of prescribe_epoch's observer selection (cranker helper)
+export { predictPrescribedObservers, } from './predict-prescribed-observers.js';
 // Constants
 export * from './constants.js';
 // Cluster-specific deployment constants (devnet program IDs, RPC URL,
@@ -95,6 +97,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',