@ar.io/sdk 4.0.0-solana.21 → 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/ant-writeable.js

@@ -264,21 +264,37 @@ export class SolanaANTWriteable extends SolanaANTReadable {
         const newOwnerDest = await this.registry.resolveDestinationAclAccounts({
             user: newOwner,
         });
-        // Resolve the old owner's source ACL accounts. The current owner
-        // *must* have a live `(asset, Owner)` entry — every spawn /
-        // import path seeds it, so a missing entry indicates state
-        // corruption. We surface that as `AclEntryNotFound` from the
-        // contract by passing the derived PDAs as a fallback rather than
-        // failing client-side here.
+        // Resolve the old owner's source ACL accounts. If the entry is
+        // missing (e.g. the ANT was acquired via a marketplace transfer or
+        // before the ACL system existed), heal it by bootstrapping the
+        // config/page and recording the owner entry so the on-chain
+        // transfer handler can successfully remove it.
         const oldOwnerSource = await this.registry.resolveSourceAclAccountsForEntry({
             user: oldOwner,
             asset: this.mint,
             role: 'owner',
         });
-        const oldOwnerAclConfigPda = oldOwnerSource?.aclConfigPda ??
-            (await this.registry.deriveAclConfigPda(oldOwner));
-        const oldOwnerAclPagePda = oldOwnerSource?.aclPagePda ??
-            (await this.registry.deriveAclPagePda(oldOwner, 0n));
+        let oldOwnerAclConfigPda;
+        let oldOwnerAclPagePda;
+        const oldOwnerHealIxs = [];
+        if (oldOwnerSource) {
+            oldOwnerAclConfigPda = oldOwnerSource.aclConfigPda;
+            oldOwnerAclPagePda = oldOwnerSource.aclPagePda;
+        }
+        else {
+            const dest = await this.registry.resolveDestinationAclAccounts({
+                user: oldOwner,
+            });
+            oldOwnerAclConfigPda = dest.aclConfigPda;
+            oldOwnerAclPagePda = dest.aclPagePda;
+            oldOwnerHealIxs.push(...dest.prepIxs);
+            oldOwnerHealIxs.push(await this.registry.buildRecordIx({
+                user: oldOwner,
+                asset: this.mint,
+                role: 'owner',
+                pageIdx: dest.pageIdx,
+            }));
+        }
         const transferIx = await getTransferInstructionAsync({
             asset: this.mint,
             caller: this.signer,
@@ -306,6 +322,7 @@ export class SolanaANTWriteable extends SolanaANTReadable {
             controllers: exControllers,
         });
         const sig = await this.sendTransaction([
+            ...oldOwnerHealIxs,
             ...newOwnerDest.prepIxs,
             transferIx,
             ...cleanupIxs,

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/io-writeable.js

@@ -19,10 +19,10 @@
  *      surface for them.
  */
 import { AccountRole, address, fetchEncodedAccount, getAddressDecoder, } from '@solana/kit';
-import { PurchaseType, getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from '@ar.io/solana-contracts/arns';
+import { PurchaseType, getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getMigrateArnsRecordInstruction, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from '@ar.io/solana-contracts/arns';
 import { FundingSourceKind as GeneratedFundingSourceKindEnum } from '@ar.io/solana-contracts/gar';
 import { buildCreateAtaIdempotentIx, getAssociatedTokenAddressKit, } from './ata.js';
-import { deserializeArnsRecord, deserializeEpochSettingsFull, } from './deserialize.js';
+import { deserializeArnsRecord, deserializeEpochSettingsFull, deserializePrimaryName, } from './deserialize.js';
 import { buildFundingPlan as buildFundingPlanCore, buildFundingPlanRemainingAccounts, computeResidueIndexes, predictResidueVaults, } from './funding-plan.js';
 /** Maps the SDK's user-facing FundingSourceKind string union to the
  *  Codama-generated enum used by the on-chain ix payload. */
@@ -36,7 +36,7 @@ function toGeneratedFundingSourceSpec(s) {
     return { kind: kindMap[s.kind], amount: s.amount };
 }
 import { getSyncAttributesInstruction } from '@ar.io/solana-contracts/ant';
-import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestAndSetPrimaryNameInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
+import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRemovePrimaryNameInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestAndSetPrimaryNameInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
 import { getDelegationDecoder, getGatewayDecoder, } from '@ar.io/solana-contracts/gar';
 import { Protocol, getAllowDelegateInstructionAsync, getCancelWithdrawalInstruction, getClaimDelegateFromLeavingGatewayInstructionAsync, getClaimWithdrawalInstructionAsync, getCloseDrainedWithdrawalInstruction, getCloseEmptyDelegationInstruction, getCloseEpochInstructionAsync, getCloseObservationInstructionAsync, getCreateEpochInstructionAsync, getDecreaseDelegateStakeInstructionAsync, getDecreaseOperatorStakeInstructionAsync, getDelegateStakeInstructionAsync, getDisallowDelegateInstructionAsync, getDistributeEpochInstructionAsync, getFinalizeGoneInstructionAsync, getIncreaseOperatorStakeInstructionAsync, getInstantWithdrawalInstructionAsync, getJoinNetworkInstructionAsync, getLeaveNetworkInstructionAsync, getPrescribeEpochInstructionAsync, getPruneGatewayInstructionAsync, getRedelegateStakeInstructionAsync, getSaveObservationsInstructionAsync, getSetAllowlistEnabledInstructionAsync, getTallyWeightsInstructionAsync, getUpdateGatewaySettingsInstructionAsync, } from '@ar.io/solana-contracts/gar';
 import { getTransferCheckedInstruction } from '@solana-program/token';
@@ -280,6 +280,35 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         const [nameRegistry] = await getArnsRegistryPDA(this.arnsProgram);
         return { config, demandFactor, nameRegistry, ...input };
     }
+    /**
+     * If the on-chain ArnsRecord for `name` hasn't been migrated to the
+     * current schema (name_hash at offset 8 doesn't match the expected
+     * hash), return a `migrate_arns_record` instruction that must be
+     * prepended to any operation referencing the record with PDA seed
+     * verification.
+     *
+     * Returns an empty array when the record is already up-to-date or
+     * doesn't exist.
+     */
+    async _buildMigrateArnsRecordIxIfNeeded(name) {
+        const [arnsRecordPda] = await getArnsRecordPDA(name, this.arnsProgram);
+        const account = await fetchEncodedAccount(this.rpc, arnsRecordPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return [];
+        const data = Buffer.from(account.data);
+        const expectedHash = hashName(name);
+        const storedHash = data.subarray(8, 40);
+        if (storedHash.equals(expectedHash))
+            return [];
+        return [
+            getMigrateArnsRecordInstruction({
+                record: arnsRecordPda,
+                payer: this.signer,
+            }, { programAddress: this.arnsProgram }),
+        ];
+    }
     /** Inject ARIO core default PDAs (config). */
     async withCoreDefaults(input) {
         const [config] = await getArioConfigPDA(this.coreProgram);
@@ -1046,12 +1075,13 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         return pda;
     }
     async upgradeRecord(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const ix = await this._buildManageStakeIx({
             params,
             operation: 'upgrade',
         });
         const syncIx = await this._buildSyncAttributesIxIfOwner(params.name);
-        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        const sig = await this.sendTransaction(syncIx ? [...migrateIxs, ix, syncIx] : [...migrateIxs, ix]);
         return { id: sig };
     }
     async syncAttributes(params, _options) {
@@ -1061,8 +1091,9 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         // `_buildSyncAttributesIxIfOwner`, which skips when not the owner so
         // the wrapping arns ix can still succeed for non-holder management
         // — see BD-095.)
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const ix = await this._buildSyncAttributesIxUnconditional(params.name);
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -1130,6 +1161,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         }, { programAddress: this.antProgram });
     }
     async extendLease(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const ix = await this._buildManageStakeIx({
             params,
             operation: 'extend',
@@ -1137,17 +1169,18 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         });
         // BD-095: extend_lease changes only `end_timestamp`, which isn't
         // mirrored in any Metaplex Attributes plugin trait. No bundle.
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     async increaseUndernameLimit(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const ix = await this._buildManageStakeIx({
             params,
             operation: 'increaseUndername',
             quantity: params.increaseCount,
         });
         const syncIx = await this._buildSyncAttributesIxIfOwner(params.name);
-        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        const sig = await this.sendTransaction(syncIx ? [...migrateIxs, ix, syncIx] : [...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -1312,6 +1345,60 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     // =========================================
     // Primary name operations (ario-core)
     // =========================================
+    /**
+     * If the signer already has a primary name set, build the instruction(s)
+     * needed to remove it so they can be prepended to a request/set tx —
+     * enabling single-tx "change primary name" flows.
+     *
+     * Returns an empty array when the signer has no existing primary name.
+     *
+     * Throws when the signer has a legacy primary-name state (forward
+     * `PrimaryName` PDA exists but its paired `PrimaryNameReverse` PDA does
+     * NOT). Both `remove_primary_name` AND `request_and_set_primary_name`
+     * require the reverse PDA on-chain — the latter rejects with
+     * `MustRemoveExistingPrimaryName` (0x1786, code 6022) any time a
+     * forward record already exists for the signer, regardless of reverse
+     * state. Silently skipping the remove would queue a tx guaranteed to
+     * fail with that opaque error. Surfacing it at the client with a clear
+     * remediation pointer is the only safe behavior.
+     *
+     * The legacy state should not exist on any cluster post-snapshot/import
+     * PR #159 (which emits PrimaryNameReverse in lockstep with PrimaryName)
+     * — it's a relic of pre-#159 imports. Operators on affected clusters
+     * must run `yarn workspace @ar-io/migration-import backfill:primary-name-reverse`
+     * (in the solana-ar-io repo) before this method can succeed.
+     */
+    async _buildRemoveExistingPrimaryNameIxs() {
+        const [primaryNamePda] = await getPrimaryNamePDA(this.signer.address, this.coreProgram);
+        const account = await fetchEncodedAccount(this.rpc, primaryNamePda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return [];
+        const { name: oldName } = deserializePrimaryName(Buffer.from(account.data));
+        const [primaryNameReversePda] = await getPrimaryNameReversePDA(oldName, this.coreProgram);
+        const reverseAccount = await fetchEncodedAccount(this.rpc, primaryNameReversePda, { commitment: this.commitment });
+        if (!reverseAccount.exists) {
+            // Fail fast with an actionable message. See method docstring for
+            // why request_and_set would reject this regardless.
+            throw new Error(`Cannot change primary name: signer "${this.signer.address}" has a ` +
+                `legacy PrimaryName ("${oldName}") with no paired PrimaryNameReverse PDA ` +
+                `(${primaryNameReversePda}). The on-chain remove_primary_name and ` +
+                `request_and_set_primary_name ixs both require the reverse PDA — ` +
+                `request_and_set will reject with MustRemoveExistingPrimaryName (code 6022). ` +
+                `Run \`yarn workspace @ar-io/migration-import backfill:primary-name-reverse\` ` +
+                `against this cluster's ario-core program to materialize the missing reverse ` +
+                `PDA, then retry.`);
+        }
+        return [
+            await getRemovePrimaryNameInstructionAsync({
+                primaryName: primaryNamePda,
+                primaryNameReverse: primaryNameReversePda,
+                owner: this.signer,
+                reverseLookupHash: hashName(oldName),
+            }, { programAddress: this.coreProgram }),
+        ];
+    }
     /**
      * Build the `remaining_accounts` slice + the `antProgramId` arg the
      * four ario-core primary-name instructions consume. Sprint 2/5
@@ -1399,6 +1486,11 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         return { remaining, antProgram };
     }
     async requestPrimaryName(params, _options) {
+        // If the caller already has a primary name, prepend remove ixs so
+        // the on-chain handler doesn't reject with MustRemoveExistingPrimaryName.
+        const removeIxs = await this._buildRemoveExistingPrimaryNameIxs();
+        const { baseName } = splitPrimaryName(params.name);
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(baseName);
         const coreConfig = await this.getCoreConfig();
         const signerATA = await getAssociatedTokenAddressKit(coreConfig.mint, this.signer.address);
         const { remaining } = await this._buildPrimaryNameValidationAccounts(params.name, 'request');
@@ -1424,13 +1516,18 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 operation: 'request',
             });
         }
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...removeIxs, ...migrateIxs, ix]);
         return { id: sig };
     }
     async setPrimaryName(params, _options) {
         // setPrimaryName routes to the on-chain `request_and_set_primary_name`
         // path — the auto-approve flow when the caller owns the AntRecord
         // for the matching name (undername part, or "@" for base names).
+        // If the caller already has a primary name, prepend remove ixs so
+        // the "change" is atomic in a single transaction.
+        const removeIxs = await this._buildRemoveExistingPrimaryNameIxs();
+        const { baseName } = splitPrimaryName(params.name);
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(baseName);
         const coreConfig = await this.getCoreConfig();
         const signerATA = await getAssociatedTokenAddressKit(coreConfig.mint, this.signer.address);
         const { remaining, antProgram } = await this._buildPrimaryNameValidationAccounts(params.name, 'requestAndSet');
@@ -1456,7 +1553,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 antProgramId: antProgram,
             });
         }
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...removeIxs, ...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -1544,6 +1641,8 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      * remaining_accounts: [arns_record(base), ant_record(undername | @)].
      */
     async approvePrimaryName(params, _options) {
+        const { baseName } = splitPrimaryName(params.name);
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(baseName);
         const [requestPda] = await getPrimaryNameRequestPDA(params.initiator, this.coreProgram);
         const [primaryNamePda] = await getPrimaryNamePDA(params.initiator, this.coreProgram);
         const [primaryNameReversePda] = await getPrimaryNameReversePDA(params.name, this.coreProgram);
@@ -1565,7 +1664,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             reverseLookupHash: hashName(params.name),
             antProgramId: antProgram,
         }), { programAddress: this.coreProgram }), remaining);
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     // =========================================
@@ -1803,18 +1902,14 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     // =========================================
     /** Reassign an ArNS name to a different ANT. */
     async reassignName(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const newAnt = address(params.processId);
         const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
-        // The on-chain `reassign_name` (PR #73 / BD-106 / BD-095) now authorizes
-        // against the CURRENT Metaplex Core holder of `record.ant` via a named
-        // `ant_asset` account constrained to `arns_record.ant`. We must read the
-        // current record to know which asset to pass — that's the OLD ant (the
-        // one we're reassigning AWAY FROM), not `newAnt`.
-        const currentRecord = await this.getArNSRecord({ name: params.name });
-        const currentAnt = address(currentRecord.processId);
+        const record = await this.getArNSRecord({ name: params.name });
+        const antAsset = address(record.processId);
         const ix = await getReassignNameInstructionAsync(await this.withArnsDefaults({
             arnsRecord,
-            antAsset: currentAnt,
+            antAsset,
             caller: this.signer,
             newAnt,
         }), { programAddress: this.arnsProgram });
@@ -1828,21 +1923,25 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         // the new ANT's holder; otherwise the ix is sent alone and the new
         // owner runs `syncAttributes()` later (BD-095/096).
         const syncIx = await this._buildSyncAttributesIxIfOwner(params.name, newAnt);
-        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        const reassignWithMetas = withRemainingAccounts(ix, [
+            { address: newAnt, role: AccountRole.READONLY },
+        ]);
+        const sig = await this.sendTransaction(syncIx
+            ? [...migrateIxs, reassignWithMetas, syncIx]
+            : [...migrateIxs, reassignWithMetas]);
         return { id: sig };
     }
     /** Release a permabuy name back to the registry (creates a returned name auction). */
     async releaseName(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const [returnedNamePda] = await getReturnedNamePDA(params.name, this.arnsProgram);
         const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
-        // PR #73 / BD-106: `release_name` now authorizes against the current
-        // Metaplex Core holder of `record.ant` via a named `ant_asset` account
-        // constrained to `arns_record.ant`. Fetch the record to know which.
-        const currentRecord = await this.getArNSRecord({ name: params.name });
+        const record = await this.getArNSRecord({ name: params.name });
+        const antAsset = address(record.processId);
         const ix = await getReleaseNameInstructionAsync(await this.withArnsDefaults({
             arnsRecord,
             returnedName: returnedNamePda,
-            antAsset: address(currentRecord.processId),
+            antAsset,
             caller: this.signer,
         }), { programAddress: this.arnsProgram });
         // Note: no sync_attributes bundle here — release_name closes the
@@ -1850,7 +1949,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         // asset's stale traits remain pointing at the released name; off-chain
         // resolvers should treat ArnsRecord as the source of truth and ignore
         // a "ArNS Name" trait that no longer resolves.
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     // =========================================
@@ -2100,6 +2199,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      * (kicks off the Dutch auction). Permissionless.
      */
     async pruneNameToReturned(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
         const [returnedName] = await getReturnedNamePDA(params.name, this.arnsProgram);
         const ix = await getPruneNameToReturnedInstructionAsync(await this.withArnsDefaults({
@@ -2107,7 +2207,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             returnedName,
             payer: this.signer,
         }), { programAddress: this.arnsProgram });
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     /**

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.21';
+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/io-writeable.d.ts

@@ -109,6 +109,17 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      * (codama only reads the named keys from `input`).
      */
     private withArnsDefaults;
+    /**
+     * If the on-chain ArnsRecord for `name` hasn't been migrated to the
+     * current schema (name_hash at offset 8 doesn't match the expected
+     * hash), return a `migrate_arns_record` instruction that must be
+     * prepended to any operation referencing the record with PDA seed
+     * verification.
+     *
+     * Returns an empty array when the record is already up-to-date or
+     * doesn't exist.
+     */
+    private _buildMigrateArnsRecordIxIfNeeded;
     /** Inject ARIO core default PDAs (config). */
     private withCoreDefaults;
     /** Inject GAR default PDAs (settings, epochSettings, registry). */
@@ -266,6 +277,30 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      * Reads the live DemandFactor account + applies the on-chain pricing math.
      */
     private _estimateManageStakeCost;
+    /**
+     * If the signer already has a primary name set, build the instruction(s)
+     * needed to remove it so they can be prepended to a request/set tx —
+     * enabling single-tx "change primary name" flows.
+     *
+     * Returns an empty array when the signer has no existing primary name.
+     *
+     * Throws when the signer has a legacy primary-name state (forward
+     * `PrimaryName` PDA exists but its paired `PrimaryNameReverse` PDA does
+     * NOT). Both `remove_primary_name` AND `request_and_set_primary_name`
+     * require the reverse PDA on-chain — the latter rejects with
+     * `MustRemoveExistingPrimaryName` (0x1786, code 6022) any time a
+     * forward record already exists for the signer, regardless of reverse
+     * state. Silently skipping the remove would queue a tx guaranteed to
+     * fail with that opaque error. Surfacing it at the client with a clear
+     * remediation pointer is the only safe behavior.
+     *
+     * The legacy state should not exist on any cluster post-snapshot/import
+     * PR #159 (which emits PrimaryNameReverse in lockstep with PrimaryName)
+     * — it's a relic of pre-#159 imports. Operators on affected clusters
+     * must run `yarn workspace @ar-io/migration-import backfill:primary-name-reverse`
+     * (in the solana-ar-io repo) before this method can succeed.
+     */
+    private _buildRemoveExistingPrimaryNameIxs;
     /**
      * Build the `remaining_accounts` slice + the `antProgramId` arg the
      * four ario-core primary-name instructions consume. Sprint 2/5

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.20";
+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.21",
+  "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",
@@ -122,17 +123,18 @@
     "typescript": "^5.1.6"
   },
   "dependencies": {
-    "@ar.io/solana-contracts": "^0.4.0",
+    "@ar.io/solana-contracts": "0.4.0",
     "@solana-program/compute-budget": "^0.15.0",
     "@solana-program/token": "^0.13.0",
     "@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"]
   }
 }