@ar.io/sdk 3.24.0 → 4.0.0-alpha.2

package/lib/esm/solana/pda.js

@@ -0,0 +1,332 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { createHash } from 'crypto';
+/**
+ * PDA derivation helpers for AR.IO Solana programs.
+ *
+ * Each function derives the on-chain address for a given account type,
+ * mirroring the seeds defined in the Anchor programs.
+ *
+ * All helpers are async — kit's `getProgramDerivedAddress` is async because
+ * it may perform bump-seed search off the main thread in some environments.
+ */
+import { getAddressEncoder, getProgramDerivedAddress, } from '@solana/kit';
+import { ACL_CONFIG_SEED, ACL_PAGE_SEED, ALLOWLIST_SEED, ANT_CONFIG_SEED, ANT_CONTROLLERS_SEED, ANT_RECORD_META_SEED, ANT_RECORD_SEED, ARIO_ANT_ESCROW_PROGRAM_ID, ARIO_ANT_PROGRAM_ID, ARIO_ARNS_PROGRAM_ID, ARIO_CONFIG_SEED, ARIO_CORE_PROGRAM_ID, ARIO_GAR_PROGRAM_ID, ARNS_RECORD_SEED, ARNS_REGISTRY_SEED, ARNS_SETTINGS_SEED, BALANCE_SEED, DELEGATION_SEED, DEMAND_FACTOR_SEED, EPOCH_SEED, EPOCH_SETTINGS_SEED, ESCROW_ANT_SEED, ESCROW_TOKEN_SEED, ESCROW_VAULT_SEED, GAR_SETTINGS_SEED, GATEWAY_REGISTRY_SEED, GATEWAY_SEED, OBSERVATION_SEED, OBSERVER_LOOKUP_SEED, PRIMARY_NAME_REQUEST_SEED, PRIMARY_NAME_REVERSE_SEED, PRIMARY_NAME_SEED, REDELEGATION_SEED, RESERVED_NAME_SEED, RETURNED_NAME_SEED, VAULT_COUNTER_SEED, VAULT_SEED, WITHDRAWAL_COUNTER_SEED, WITHDRAWAL_SEED, } from './constants.js';
+const addressEncoder = getAddressEncoder();
+/**
+ * Hash a variable-length name for use as PDA seed.
+ * Matches Rust: hash(name.to_lowercase().as_bytes())
+ */
+export function hashName(name) {
+    return createHash('sha256')
+        .update(name.toLowerCase())
+        .digest()
+        .subarray(0, 32);
+}
+// =========================================
+// ario-core PDAs
+// =========================================
+export async function getArioConfigPDA(programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARIO_CONFIG_SEED],
+    });
+}
+export async function getBalancePDA(owner, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [BALANCE_SEED, addressEncoder.encode(owner)],
+    });
+}
+export async function getVaultPDA(owner, vaultId, programId = ARIO_CORE_PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(vaultId));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [VAULT_SEED, addressEncoder.encode(owner), idBuf],
+    });
+}
+export async function getVaultCounterPDA(owner, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [VAULT_COUNTER_SEED, addressEncoder.encode(owner)],
+    });
+}
+export async function getPrimaryNamePDA(owner, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [PRIMARY_NAME_SEED, addressEncoder.encode(owner)],
+    });
+}
+export async function getPrimaryNameRequestPDA(initiator, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [PRIMARY_NAME_REQUEST_SEED, addressEncoder.encode(initiator)],
+    });
+}
+export async function getPrimaryNameReversePDA(name, programId = ARIO_CORE_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [PRIMARY_NAME_REVERSE_SEED, hashName(name)],
+    });
+}
+// =========================================
+// ario-gar PDAs
+// =========================================
+export async function getGatewayRegistryPDA(programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [GATEWAY_REGISTRY_SEED],
+    });
+}
+export async function getGarSettingsPDA(programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [GAR_SETTINGS_SEED],
+    });
+}
+export async function getGatewayPDA(operator, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [GATEWAY_SEED, addressEncoder.encode(operator)],
+    });
+}
+export async function getDelegationPDA(gateway, delegator, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [
+            DELEGATION_SEED,
+            addressEncoder.encode(gateway),
+            addressEncoder.encode(delegator),
+        ],
+    });
+}
+export async function getWithdrawalPDA(owner, withdrawalId, programId = ARIO_GAR_PROGRAM_ID) {
+    const idBuf = Buffer.alloc(8);
+    idBuf.writeBigUInt64LE(BigInt(withdrawalId));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [WITHDRAWAL_SEED, addressEncoder.encode(owner), idBuf],
+    });
+}
+export async function getWithdrawalCounterPDA(owner, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [WITHDRAWAL_COUNTER_SEED, addressEncoder.encode(owner)],
+    });
+}
+export async function getAllowlistPDA(gateway, delegate, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [
+            ALLOWLIST_SEED,
+            addressEncoder.encode(gateway),
+            addressEncoder.encode(delegate),
+        ],
+    });
+}
+export async function getEpochPDA(epochIndex, programId = ARIO_GAR_PROGRAM_ID) {
+    const indexBuf = Buffer.alloc(8);
+    indexBuf.writeBigUInt64LE(BigInt(epochIndex));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [EPOCH_SEED, indexBuf],
+    });
+}
+export async function getEpochSettingsPDA(programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [EPOCH_SETTINGS_SEED],
+    });
+}
+export async function getRedelegationRecordPDA(delegator, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [REDELEGATION_SEED, addressEncoder.encode(delegator)],
+    });
+}
+export async function getObservationPDA(epochIndex, observer, programId = ARIO_GAR_PROGRAM_ID) {
+    const indexBuf = Buffer.alloc(8);
+    indexBuf.writeBigUInt64LE(BigInt(epochIndex));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [OBSERVATION_SEED, indexBuf, addressEncoder.encode(observer)],
+    });
+}
+export async function getObserverLookupPDA(observerAddress, programId = ARIO_GAR_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [OBSERVER_LOOKUP_SEED, addressEncoder.encode(observerAddress)],
+    });
+}
+// =========================================
+// ario-arns PDAs
+// =========================================
+export async function getArnsRegistryPDA(programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARNS_REGISTRY_SEED],
+    });
+}
+export async function getArnsSettingsPDA(programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARNS_SETTINGS_SEED],
+    });
+}
+export async function getArnsRecordPDA(name, programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARNS_RECORD_SEED, hashName(name)],
+    });
+}
+/**
+ * Derive ArNS record PDA from a raw 32-byte name hash.
+ * Used when resolving prescribed name hashes from Epoch data.
+ */
+export async function getArnsRecordPDAFromHash(nameHash, programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ARNS_RECORD_SEED, nameHash],
+    });
+}
+export async function getReservedNamePDA(name, programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [RESERVED_NAME_SEED, hashName(name)],
+    });
+}
+export async function getReturnedNamePDA(name, programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [RETURNED_NAME_SEED, hashName(name)],
+    });
+}
+export async function getDemandFactorPDA(programId = ARIO_ARNS_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [DEMAND_FACTOR_SEED],
+    });
+}
+// =========================================
+// ario-ant PDAs
+// =========================================
+export async function getAntConfigPDA(mint, programId = ARIO_ANT_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ANT_CONFIG_SEED, addressEncoder.encode(mint)],
+    });
+}
+export async function getAntControllersPDA(mint, programId = ARIO_ANT_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ANT_CONTROLLERS_SEED, addressEncoder.encode(mint)],
+    });
+}
+export async function getAntRecordPDA(mint, undername, programId = ARIO_ANT_PROGRAM_ID) {
+    const nameHash = createHash('sha256')
+        .update(undername.toLowerCase())
+        .digest()
+        .subarray(0, 32);
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ANT_RECORD_SEED, addressEncoder.encode(mint), nameHash],
+    });
+}
+export async function getAntRecordMetadataPDA(mint, undername, programId = ARIO_ANT_PROGRAM_ID) {
+    const nameHash = createHash('sha256')
+        .update(undername.toLowerCase())
+        .digest()
+        .subarray(0, 32);
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ANT_RECORD_META_SEED, addressEncoder.encode(mint), nameHash],
+    });
+}
+/**
+ * Derive the `AclConfig` head PDA for a given wallet address.
+ *
+ * Seeds: `["acl_config", user]` under the ario-ant program.
+ *
+ * See ADR-012 (docs/DECISIONS.md): `AclConfig` is the head record for a
+ * user's paginated ACL. It tracks `page_count` (how many `AclPage` PDAs
+ * exist) and `total_entries` (sum across pages). Frontends point-read
+ * this once, then fan out to each `AclPage` via `getMultipleAccountsInfo`.
+ */
+export async function getAclConfigPDA(user, programId = ARIO_ANT_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ACL_CONFIG_SEED, addressEncoder.encode(user)],
+    });
+}
+/**
+ * Derive an `AclPage` PDA for a given user + page index.
+ *
+ * Seeds: `["acl_page", user, page_idx_le]` where `page_idx_le` is the
+ * 8-byte little-endian encoding of `u64` (matches the contract).
+ *
+ * Each page address is content-derivable from `(user, page_idx)`, so any
+ * single page can be loaded in O(1) without scanning sibling pages.
+ */
+export async function getAclPagePDA(user, pageIdx, programId = ARIO_ANT_PROGRAM_ID) {
+    const idxBuf = Buffer.alloc(8);
+    idxBuf.writeBigUInt64LE(BigInt(pageIdx));
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ACL_PAGE_SEED, addressEncoder.encode(user), idxBuf],
+    });
+}
+// =========================================
+// ario-ant-escrow PDAs
+// =========================================
+/**
+ * Derive the EscrowAnt PDA for a given ANT mint. Exactly one escrow per
+ * ANT — re-deriving the address tells you whether an escrow already
+ * exists (look up the account and check `data.length`).
+ *
+ * Seeds: ["escrow_ant", ant_mint]
+ * Source: contracts/programs/ario-ant-escrow/src/state.rs::ESCROW_ANT_SEED
+ */
+export async function getEscrowAntPDA(antMint, programId = ARIO_ANT_ESCROW_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ESCROW_ANT_SEED, addressEncoder.encode(antMint)],
+    });
+}
+/**
+ * Derive the EscrowToken PDA for a given depositor and asset ID.
+ *
+ * Seeds: ["escrow_token", depositor, asset_id]
+ * Source: contracts/programs/ario-ant-escrow/src/state.rs::ESCROW_TOKEN_SEED
+ */
+export async function getEscrowTokenPDA(depositor, assetId, programId = ARIO_ANT_ESCROW_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ESCROW_TOKEN_SEED, addressEncoder.encode(depositor), assetId],
+    });
+}
+/**
+ * Derive the EscrowVault PDA for a given depositor and asset ID.
+ *
+ * Seeds: ["escrow_vault", depositor, asset_id]
+ * Source: contracts/programs/ario-ant-escrow/src/state.rs::ESCROW_VAULT_SEED
+ */
+export async function getEscrowVaultPDA(depositor, assetId, programId = ARIO_ANT_ESCROW_PROGRAM_ID) {
+    return getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: [ESCROW_VAULT_SEED, addressEncoder.encode(depositor), assetId],
+    });
+}

package/lib/esm/solana/predict-prescribed-observers.js

@@ -0,0 +1,110 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Off-chain prediction of `prescribe_epoch`'s observer selection.
+ *
+ * `ario_gar::prescribe_epoch` selects observers INTERNALLY via a weighted
+ * roulette over the `GatewayRegistry`, then uses `remaining_accounts` only as a
+ * lookup table for the ~50 selected Gateway PDAs (+ NameRegistry). A cranker
+ * that instead supplies every registry gateway hits Solana's
+ * `MAX_TX_ACCOUNT_LOCKS = 64` on large registries and the tx is rejected at
+ * pre-flight. This helper mirrors the on-chain selection so the caller can
+ * supply exactly the selected set.
+ *
+ * The selection is deterministic from on-chain state that is stable once
+ * `epoch.weights_tallied == 1`: the frozen `epoch.hashchain` entropy beacon and
+ * the live `registry.gateways[*].composite_weight`.
+ *
+ * Cross-language parity with the Rust handler
+ * (`ar-io-solana-contracts/programs/ario-gar/src/instructions/epoch.rs`, the
+ * `prescribe_epoch` observer-selection block) is asserted in
+ * `predict-prescribed-observers.test.ts` against vectors generated by the Rust
+ * reference example `programs/ario-gar/examples/predict_prescribed_observers.rs`.
+ * If you change this algorithm, update that example and the test together.
+ */
+import { createHash } from 'crypto';
+function sha256(data) {
+    return createHash('sha256').update(data).digest();
+}
+/** `u128::from_le_bytes(bytes[0..16])` — little-endian, first 16 bytes only. */
+function leU128(bytes) {
+    let v = 0n;
+    for (let i = 15; i >= 0; i--) {
+        v = (v << 8n) | BigInt(bytes[i]);
+    }
+    return v;
+}
+/**
+ * Predict the operator pubkeys `prescribe_epoch` will select as observers.
+ *
+ * Returns the selected `GatewaySlot.address` values (operator pubkeys) in
+ * selection order, at most `maxObservers`. These correspond 1:1 to the on-chain
+ * `epoch.prescribed_observer_gateways` array, and are what Gateway PDAs are
+ * derived from (`[GATEWAY_SEED, operator]`). NOTE this is NOT
+ * `epoch.prescribed_observers`, which `prescribe_epoch` later overwrites with
+ * each gateway's resolved `observer_address`.
+ *
+ * @param epochHashchain `epoch.hashchain` — exactly 32 bytes, frozen at
+ *   `create_epoch`.
+ * @param slots `registry.gateways[0 .. epoch.active_gateway_count]` in registry
+ *   (slot-index) order. Pass the whole prefix including any zero-weight slots —
+ *   order and the live weight sum must match the on-chain walk exactly. Empty /
+ *   zero-weight slots contribute nothing and can never be selected.
+ * @param maxObservers `epoch_settings.prescribed_observer_count`. Clamped to
+ *   `slots.length` (the on-chain `min(prescribed_observer_count, active_count)`).
+ */
+export function predictPrescribedObservers(epochHashchain, slots, maxObservers) {
+    if (epochHashchain.length !== 32) {
+        throw new Error(`epochHashchain must be 32 bytes, got ${epochHashchain.length}`);
+    }
+    const activeCount = slots.length;
+    const cap = Math.min(maxObservers, activeCount);
+    // Live total weight (epoch.rs: `for i in 0..active_count { total += w }`).
+    // u128 sum of u64 weights over <=3000 slots cannot overflow, so the Rust
+    // `saturating_add` never actually saturates; plain BigInt addition matches.
+    let totalWeight = 0n;
+    for (const slot of slots) {
+        totalWeight += slot.compositeWeight;
+    }
+    const selected = [];
+    if (totalWeight === 0n || activeCount === 0 || cap === 0) {
+        return selected;
+    }
+    // Initial entropy: sha256(hashchain).
+    let hashBytes = sha256(epochHashchain);
+    // GAR-019: bounded retries, up to cap * 10 rounds.
+    const maxRounds = cap * 10;
+    for (let round = 0; round < maxRounds; round++) {
+        if (selected.length >= cap)
+            break;
+        const randomValue = leU128(hashBytes.subarray(0, 16)) % totalWeight;
+        let cumulative = 0n;
+        for (const slot of slots) {
+            cumulative += slot.compositeWeight;
+            if (cumulative > randomValue && slot.compositeWeight > 0n) {
+                // Anti-duplicate: skip if already chosen, but the round still consumes
+                // the roulette hit — break the walk either way (epoch.rs).
+                if (!selected.includes(slot.address)) {
+                    selected.push(slot.address);
+                }
+                break;
+            }
+        }
+        // Re-hash for the next round: sha256(hash_bytes).
+        hashBytes = sha256(hashBytes);
+    }
+    return selected;
+}

package/lib/esm/solana/retry.js

@@ -0,0 +1,117 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 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 = 3;
+const DEFAULT_BASE_DELAY_MS = 1_000;
+const DEFAULT_MAX_DELAY_MS = 10_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;
+}