@ar.io/sdk 4.0.0-solana.9 → 4.0.0

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

@@ -1,3 +1,18 @@
+/**
+ * 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.
+ */
 /**
  * Helpers for JSON-RPC reads against {@link SolanaRpc} that return a
  * web3.js-shaped `AccountInfo` (Buffer-backed `data`, plain Address strings).
@@ -5,6 +20,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 +40,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 +69,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/metadata.js

@@ -1,3 +1,18 @@
+/**
+ * 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.
+ */
 /**
  * Metaplex-standard JSON metadata builder for AR.IO ANT NFTs.
  *

package/lib/esm/solana/mpl-core.js

@@ -1,3 +1,18 @@
+/**
+ * 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.
+ */
 /**
  * Reader for the on-chain Metaplex Core asset (`AssetV1` + plugin chain).
  *
@@ -26,11 +41,8 @@
  * `ANT Program` attribute or has a layout the walker doesn't recognise.
  */
 import { fetchEncodedAccount, } from '@solana/kit';
-import { getAssetV1Decoder } from './generated/mpl-core/accounts/assetV1.js';
-import { getPluginHeaderV1Decoder } from './generated/mpl-core/accounts/pluginHeaderV1.js';
-import { getPluginRegistryV1Decoder } from './generated/mpl-core/accounts/pluginRegistryV1.js';
-import { getPluginDecoder } from './generated/mpl-core/types/plugin.js';
-import { PluginType } from './generated/mpl-core/types/pluginType.js';
+import { PluginType, getAssetV1Decoder, getPluginDecoder, getPluginHeaderV1Decoder, getPluginRegistryV1Decoder, } from '@ar.io/solana-contracts/mpl-core';
+import { ARIO_ANT_PROGRAM_ID } from './constants.js';
 /**
  * On-chain trait keys. Marketplaces and DAS indexers query these by
  * exact string match — keep in lock-step with:
@@ -116,6 +128,44 @@ export async function fetchAntProgramFromAsset(rpc, mint, config) {
     // self-grief that surfaces at the next PDA derivation.
     return value;
 }
+/**
+ * Decide which ANT program id to trust for a SIGNING (write) transaction.
+ *
+ * The `ANT Program` trait returned by {@link fetchAntProgramFromAsset} is read
+ * from Metaplex Core asset / RPC data and is NOT authenticated — a malicious
+ * asset owner, or a spoofed/compromised RPC response, can set it to an
+ * attacker-controlled program. Write instructions use this value as the
+ * instruction `programAddress` while including the caller as a signer, so
+ * silently trusting a non-canonical detected value would let an attacker route
+ * a victim's signed transaction to their own program and inherit signer /
+ * writable privileges over the included accounts.
+ *
+ * Trust rules — BYO-ANT (ADR-016 / BD-100) stays supported, but only via
+ * explicit opt-in:
+ *   - An `explicit` program id (the caller passed `antProgramId`) is always
+ *     honored — the caller has taken responsibility for it.
+ *   - Otherwise a detected value is honored only when it is `null` (no trait)
+ *     or equals the canonical {@link ARIO_ANT_PROGRAM_ID}.
+ *   - A detected NON-canonical value with no explicit opt-in throws, rather
+ *     than silently signing against an untrusted program.
+ *
+ * Read-only paths never sign, so they may auto-detect freely; this guard is
+ * only for the write path.
+ */
+export function resolveWriteAntProgram(args) {
+    const canonical = args.canonical ?? ARIO_ANT_PROGRAM_ID;
+    if (args.explicit !== undefined)
+        return args.explicit;
+    if (args.detected === null || args.detected === canonical)
+        return canonical;
+    throw new Error(`ANT.init auto-detected a non-canonical ANT program (${args.detected}) ` +
+        `from the asset's "${TRAIT_KEY_ANT_PROGRAM}" trait. That value is read ` +
+        `from asset/RPC data and is not authenticated, so the SDK refuses to ` +
+        `build a *signed* transaction against it implicitly (doing so could ` +
+        `route your signature to an attacker-controlled program). To use a ` +
+        `third-party (BYO-ANT) program for writes, pass it explicitly: ` +
+        `ANT.init({ ..., antProgramId }).`);
+}
 /**
  * Fetch the current owner of an MPL Core asset. Returns `null` when the
  * account doesn't exist or the AssetV1 layout can't be decoded.

package/lib/esm/solana/pda.js

@@ -1,3 +1,18 @@
+/**
+ * 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.

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;
+}

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

@@ -0,0 +1,258 @@
+/**
+ * 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.
+ */
+/**
+ * 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';
+// ---------------------------------------------------------------------------
+// Adaptive rate gate (token bucket + cooldown)
+// ---------------------------------------------------------------------------
+/** Default ceiling when `maxRequestsPerSecond` is not provided. */
+const DEFAULT_MAX_RPS = 10;
+/** Multiply the current rate by this on a 429 with no usable header. */
+const AIMD_DECREASE = 0.5;
+/** Never throttle below this many requests/second. */
+const MIN_RATE = 1;
+/** Consecutive successes before nudging the rate up by 1 (additive recovery). */
+const RECOVERY_SUCCESSES = 20;
+/** Fraction of a provider-advertised limit to actually use (safety margin). */
+const RATE_SAFETY_FACTOR = 0.9;
+/** Cooldown applied on a 429 that carries no `Retry-After`. */
+const DEFAULT_COOLDOWN_MS = 1_000;
+/**
+ * Token-bucket throttle whose rate can be retuned at runtime and which can be
+ * paused on demand. Tokens refill continuously at the current rate, capped at
+ * one second's worth (the burst allowance); waiters are released FIFO.
+ */
+function createRateGate(initialRate) {
+    let rate = Math.max(MIN_RATE, initialRate);
+    let capacity = Math.max(1, rate);
+    let tokens = capacity;
+    let lastRefill = Date.now();
+    let pausedUntil = 0;
+    const queue = [];
+    let timer = null;
+    const schedule = (ms) => {
+        if (timer !== null)
+            return;
+        timer = setTimeout(() => {
+            timer = null;
+            pump();
+        }, Math.max(ms, 1));
+    };
+    const refill = () => {
+        const now = Date.now();
+        const elapsed = (now - lastRefill) / 1000;
+        if (elapsed > 0) {
+            tokens = Math.min(capacity, tokens + elapsed * rate);
+            lastRefill = now;
+        }
+    };
+    const pump = () => {
+        const now = Date.now();
+        if (pausedUntil > now) {
+            schedule(pausedUntil - now);
+            return;
+        }
+        refill();
+        while (tokens >= 1) {
+            const release = queue.shift();
+            if (!release)
+                break;
+            tokens -= 1;
+            release();
+        }
+        if (queue.length > 0) {
+            // Wake when the next whole token will have accrued.
+            schedule(Math.ceil(((1 - tokens) / rate) * 1000));
+        }
+    };
+    return {
+        acquire: () => new Promise((resolve) => {
+            queue.push(resolve);
+            pump();
+        }),
+        setRate: (ratePerSecond) => {
+            rate = Math.max(MIN_RATE, ratePerSecond);
+            capacity = Math.max(1, rate);
+            tokens = Math.min(tokens, capacity);
+            lastRefill = Date.now();
+            pump();
+        },
+        pauseFor: (ms) => {
+            const until = Date.now() + Math.max(0, ms);
+            if (until > pausedUntil)
+                pausedUntil = until;
+            schedule(ms);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// 429 / rate-limit header parsing
+// ---------------------------------------------------------------------------
+/**
+ * If `err` is a transport HTTP 429, return its response `Headers`; else null.
+ * Duck-typed against the `@solana/errors` HTTP-error context
+ * (`{ statusCode, headers }`) so we avoid a hard dependency on the error code.
+ */
+function http429Headers(err) {
+    const ctx = err
+        ?.context;
+    if (ctx?.statusCode === 429 && ctx.headers instanceof Headers) {
+        return ctx.headers;
+    }
+    return null;
+}
+/** Parse `Retry-After` (delta-seconds or HTTP-date) into ms, or null. */
+function parseRetryAfterMs(headers) {
+    const v = headers.get('retry-after');
+    if (v === null || v === '')
+        return null;
+    const secs = Number(v);
+    if (Number.isFinite(secs))
+        return Math.max(0, secs * 1000);
+    const when = Date.parse(v);
+    return Number.isNaN(when) ? null : Math.max(0, when - Date.now());
+}
+/** Provider-advertised requests/second limit (`x-ratelimit-rps-limit`), or null. */
+function parseRpsLimit(headers) {
+    const v = Number(headers.get('x-ratelimit-rps-limit'));
+    return Number.isFinite(v) && v > 0 ? v : null;
+}
+// ---------------------------------------------------------------------------
+// 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 });
+    // Throttling is always on. `maxRequestsPerSecond` is the *ceiling*: every
+    // request flows through an adaptive token bucket that backs off on HTTP 429
+    // (honoring `Retry-After` and `x-ratelimit-rps-limit` when present, AIMD
+    // otherwise) and recovers back toward the ceiling on sustained success.
+    const ceilingRate = opts.maxRequestsPerSecond !== undefined && opts.maxRequestsPerSecond > 0
+        ? opts.maxRequestsPerSecond
+        : DEFAULT_MAX_RPS;
+    const gate = createRateGate(ceilingRate);
+    let currentRate = ceilingRate;
+    let successStreak = 0;
+    const onError = (err) => {
+        const headers = http429Headers(err);
+        if (!headers)
+            return; // only adapt to rate-limit (429) failures
+        successStreak = 0;
+        const advertised = parseRpsLimit(headers);
+        const next = advertised !== null
+            ? Math.min(ceilingRate, Math.max(MIN_RATE, advertised * RATE_SAFETY_FACTOR))
+            : Math.max(MIN_RATE, currentRate * AIMD_DECREASE);
+        if (next !== currentRate) {
+            currentRate = next;
+            gate.setRate(currentRate);
+        }
+        const retryAfter = parseRetryAfterMs(headers);
+        gate.pauseFor(retryAfter ?? DEFAULT_COOLDOWN_MS);
+        logger.warn(`[rpc-circuit-breaker] 429 — throttling to ${currentRate.toFixed(1)} req/s` +
+            `, cooling down ${retryAfter ?? DEFAULT_COOLDOWN_MS}ms`);
+    };
+    const onSuccess = () => {
+        if (currentRate >= ceilingRate)
+            return;
+        if (++successStreak >= RECOVERY_SUCCESSES) {
+            successStreak = 0;
+            currentRate = Math.min(ceilingRate, currentRate + 1);
+            gate.setRate(currentRate);
+        }
+    };
+    const breaker = new CircuitBreaker((request) => primaryTransport(request), {
+        timeout: opts.timeout ?? 10_000,
+        errorThresholdPercentage: opts.errorThresholdPercentage ?? 25,
+        resetTimeout: opts.resetTimeout ?? 60_000,
+        volumeThreshold: opts.volumeThreshold ?? 3,
+        ...(opts.maxConcurrent !== undefined && opts.maxConcurrent > 0
+            ? { capacity: opts.maxConcurrent }
+            : {}),
+    });
+    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');
+    });
+    // Adapt the rate to the *primary's* health via opossum's events: `failure`
+    // fires whenever the primary call rejects (a 429 included) even when the
+    // fallback then masks it by resolving `fire()`, and `success` fires on a
+    // healthy primary call. A plain try/catch around `fire()` would miss the
+    // fallback-masked 429s entirely.
+    breaker.on('failure', (err) => onError(err));
+    breaker.on('success', () => onSuccess());
+    const transport = (async (request) => {
+        // Throttle entry to the breaker so we stay under the provider's rate
+        // limit; the queue wait sits outside `fire`, so opossum's per-request
+        // timeout only measures the actual transport call.
+        await gate.acquire();
+        return 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;
+}