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

package/lib/types/solana/json-rpc.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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).
+ * Used by the ACL/AntRegistry path so the deserializers can stay agnostic of
+ * the RPC client's response shape.
+ */
+import { type Address } from '@solana/kit';
+import type { SolanaRpc } from './types.js';
+/** Raw account layout used by SDK readers (matches legacy web3 `AccountInfo` fields). */
+export type SolanaAccountInfo = {
+    data: Buffer;
+    owner: Address;
+    lamports: number;
+    executable: boolean;
+    rentEpoch: number;
+};
+/**
+ * Fetch a single account and decode its data into a Buffer-backed shape that
+ * looks like the legacy `web3.js` `AccountInfo`. Returns `null` if the account
+ * doesn't exist (so callers can handle "missing PDA" without try/catch).
+ */
+export declare function getAccountInfoLegacy(rpc: SolanaRpc, pda: Address, commitment: string | undefined): Promise<SolanaAccountInfo | null>;
+/**
+ * Fetch multiple accounts in a single RPC round-trip and decode each into
+ * the legacy `AccountInfo` shape. Missing accounts come back as `null`,
+ * preserving 1:1 alignment with the input `pdas` array.
+ *
+ * Used by paginated readers (ACL pages, etc.) to load all sibling pages
+ * via `getMultipleAccountsInfo` rather than firing N parallel
+ * `getAccountInfo` calls.
+ */
+export declare function getMultipleAccountsInfoLegacy(rpc: SolanaRpc, pdas: Address[], commitment: string | undefined): Promise<(SolanaAccountInfo | null)[]>;

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

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ *
+ * The Core asset's `uri` field on chain points at a JSON file with this
+ * shape; marketplaces and DAS providers fetch + parse it for their
+ * inline name/image/description display. The 3 ArNS traits (`ArNS Name`,
+ * `Type`, `Undername Limit`) live in the on-chain Attributes plugin, NOT
+ * in this JSON — see ADR-012.
+ *
+ * This helper produces the exact same JSON shape as the migration import
+ * (`migration/import/src/metadata.ts::buildAntMetadata`); the two paths
+ * MUST stay in lock-step or migrated and freshly-spawned ANTs will
+ * render differently in marketplace UIs. A regression test in
+ * `spawn-ant.test.ts` asserts byte-equality between the two for matching
+ * inputs.
+ *
+ * Pure function. No network, no Turbo, no dependencies. Caller handles
+ * uploading the resulting JSON to Arweave (e.g. via `@ardrive/turbo-sdk`
+ * with a `HexSolanaSigner` — free for files under 100 KiB) and passes the
+ * resulting `ar://${txid}` to `spawnSolanaANT`'s `state.uri`.
+ */
+export { ARIO_LOGO_TX_ID, AR_IO_PROTOCOL as AR_PROTOCOL, } from '../constants.js';
+/** Metaplex-standard JSON metadata shape. */
+export interface NftMetadataJson {
+    name: string;
+    symbol: string;
+    description: string;
+    image: string;
+    external_url?: string;
+    properties?: {
+        files?: Array<{
+            uri: string;
+            type: string;
+        }>;
+        /** Metaplex standard categories: image | video | audio | vr | html. */
+        category?: string;
+    };
+}
+/** Inputs to `buildAntMetadata`. */
+export interface AntMetadataParams {
+    /** Display name for the NFT — usually the ArNS name when one is set. */
+    name: string;
+    /** ArNS name this ANT controls (if any). When set, becomes the JSON
+     *  `name` and is also used in `external_url`. */
+    arnsName?: string;
+    /** Ticker / symbol. Defaults to "ANT". */
+    ticker?: string;
+    /** Description. Auto-generated from arnsName when omitted. */
+    description?: string;
+    /** Logo TX id (43-char Arweave id). Defaults to the AR.IO logo. */
+    logoTxId?: string;
+    /**
+     * Optional gateway hostname (e.g. `"turbo-gateway.com"` or `"arweave.net"`).
+     * When provided, all Arweave references in the JSON resolve to
+     * `https://${gateway}/raw/${txid}` instead of `ar://${txid}`. Useful when
+     * you need consumers (like Helius DAS or the Metaplex Core explorer) to
+     * fetch the JSON immediately without waiting for Wayfinder-aware
+     * resolution; ADR-012's canonical scheme is still `ar://`.
+     */
+    gateway?: string;
+}
+/**
+ * Build ANT NFT JSON metadata.
+ *
+ * Output is byte-identical to the migration import's `buildAntMetadata`
+ * for matching inputs. Defaults to `ar://` URLs (ADR-012 canonical); pass
+ * `gateway` to opt into https URLs.
+ */
+export declare function buildAntMetadata(params: AntMetadataParams): NftMetadataJson;

package/lib/types/solana/mpl-core.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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).
+ *
+ * The codama-generated decoders in `generated/mpl-core` only cover the
+ * fixed-shape header section (`AssetV1`, `PluginHeaderV1`, etc.) — they
+ * don't know how to follow the variable-offset registry chain to a
+ * specific plugin payload. This module fills that gap with a small
+ * walker that:
+ *
+ *   1. decodes the `AssetV1` prefix (key + owner + update authority +
+ *      name + uri + seq);
+ *   2. follows the `PluginHeaderV1.pluginRegistryOffset` to the
+ *      `PluginRegistryV1`;
+ *   3. iterates registry records to find the requested plugin variant;
+ *   4. decodes the `Plugin` enum at the registry record's offset.
+ *
+ * The same walk lives on-chain in `programs/ario-arns/src/state/mod.rs`
+ * (`read_mpl_core_attribute`) and `programs/ario-core/src/mpl_core.rs`
+ * (`read_ant_program`). The three implementations are pinned against
+ * each other by the migration import's edge-case fixtures and unit
+ * tests at all three layers.
+ *
+ * Reading is best-effort: any parse failure returns `null` rather than
+ * throwing, so callers can fall back to canonical defaults
+ * (e.g. `ARIO_ANT_PROGRAM_ID`) when an asset was minted without the
+ * `ANT Program` attribute or has a layout the walker doesn't recognise.
+ */
+import { type Address, type FetchAccountConfig, type ReadonlyUint8Array, fetchEncodedAccount } from '@solana/kit';
+/**
+ * On-chain trait keys. Marketplaces and DAS indexers query these by
+ * exact string match — keep in lock-step with:
+ *   - `migration/import/src/phases/phase2-ants.ts`
+ *   - `programs/ario-arns/src/mpl_core_cpi.rs::TRAIT_KEY_*`
+ *   - `programs/ario-core/src/mpl_core.rs::TRAIT_KEY_ANT_PROGRAM`
+ */
+export declare const TRAIT_KEY_ARNS_NAME: "ArNS Name";
+export declare const TRAIT_KEY_TYPE: "Type";
+export declare const TRAIT_KEY_UNDERNAME_LIMIT: "Undername Limit";
+export declare const TRAIT_KEY_ANT_PROGRAM: "ANT Program";
+/**
+ * Read a single attribute value from a Metaplex Core asset's Attributes
+ * plugin. Returns `null` when the asset has no plugin section, has no
+ * Attributes plugin, the requested key is absent, or any layer of the
+ * walk fails to decode. This is a best-effort lookup — callers should
+ * use a canonical default rather than treating absence as an error.
+ *
+ * `data` is the raw account data (post-discriminator? no — MPL Core
+ * doesn't use the 8-byte Anchor discriminator, the asset is the
+ * account's full data starting from the `Key` enum byte).
+ */
+export declare function readAttribute(data: Uint8Array | ReadonlyUint8Array, key: string): string | null;
+/**
+ * Convenience wrapper: fetch the asset account and parse its
+ * `ANT Program` attribute. Returns `null` when the account doesn't
+ * exist, has no `ANT Program` trait, or the value can't be parsed —
+ * callers should fall back to the canonical `ARIO_ANT_PROGRAM_ID`.
+ *
+ * Importing this here (rather than wiring it directly into the resolver
+ * paths) lets `ant-readable.ts` keep its constructor synchronous and
+ * have a separate async `fromAsset(rpc, mint)` factory that does the
+ * lookup once and caches the result.
+ */
+export declare function fetchAntProgramFromAsset(rpc: Parameters<typeof fetchEncodedAccount>[0], mint: Address, config?: FetchAccountConfig): Promise<Address | null>;
+/**
+ * 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 declare function resolveWriteAntProgram(args: {
+    explicit?: Address;
+    detected: Address | null;
+    canonical?: Address;
+}): Address;
+/**
+ * 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.
+ *
+ * Used by `SolanaARIOWriteable` to decide whether to bundle
+ * `ant.sync_attributes` into a buy / manage tx. The Attributes plugin's
+ * `BasePluginAuthority` is `Owner`, so only the current asset holder
+ * can sign the inner CPI; if the caller isn't the holder, bundling
+ * would abort the whole tx (BD-095 — non-holder ArNS lease management
+ * must continue to succeed; the actual ANT owner can call the public
+ * `syncAttributes` later to converge state).
+ */
+export declare function fetchMplCoreOwner(rpc: Parameters<typeof fetchEncodedAccount>[0], mint: Address, config?: FetchAccountConfig): Promise<Address | null>;

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

@@ -0,0 +1,95 @@
+/**
+ * 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 { type Address } from '@solana/kit';
+/** Return shape for every PDA helper: `[pdaAddress, bumpSeed]`. */
+export type Pda = readonly [Address, number];
+/**
+ * Hash a variable-length name for use as PDA seed.
+ * Matches Rust: hash(name.to_lowercase().as_bytes())
+ */
+export declare function hashName(name: string): Buffer;
+export declare function getArioConfigPDA(programId?: Address): Promise<Pda>;
+export declare function getBalancePDA(owner: Address, programId?: Address): Promise<Pda>;
+export declare function getVaultPDA(owner: Address, vaultId: bigint | number, programId?: Address): Promise<Pda>;
+export declare function getVaultCounterPDA(owner: Address, programId?: Address): Promise<Pda>;
+export declare function getPrimaryNamePDA(owner: Address, programId?: Address): Promise<Pda>;
+export declare function getPrimaryNameRequestPDA(initiator: Address, programId?: Address): Promise<Pda>;
+export declare function getPrimaryNameReversePDA(name: string, programId?: Address): Promise<Pda>;
+export declare function getGatewayRegistryPDA(programId?: Address): Promise<Pda>;
+export declare function getGarSettingsPDA(programId?: Address): Promise<Pda>;
+export declare function getGatewayPDA(operator: Address, programId?: Address): Promise<Pda>;
+export declare function getDelegationPDA(gateway: Address, delegator: Address, programId?: Address): Promise<Pda>;
+export declare function getWithdrawalPDA(owner: Address, withdrawalId: bigint | number, programId?: Address): Promise<Pda>;
+export declare function getWithdrawalCounterPDA(owner: Address, programId?: Address): Promise<Pda>;
+export declare function getAllowlistPDA(gateway: Address, delegate: Address, programId?: Address): Promise<Pda>;
+export declare function getEpochPDA(epochIndex: number, programId?: Address): Promise<Pda>;
+export declare function getEpochSettingsPDA(programId?: Address): Promise<Pda>;
+export declare function getRedelegationRecordPDA(delegator: Address, programId?: Address): Promise<Pda>;
+export declare function getObservationPDA(epochIndex: number, observer: Address, programId?: Address): Promise<Pda>;
+export declare function getObserverLookupPDA(observerAddress: Address, programId?: Address): Promise<Pda>;
+export declare function getArnsRegistryPDA(programId?: Address): Promise<Pda>;
+export declare function getArnsSettingsPDA(programId?: Address): Promise<Pda>;
+export declare function getArnsRecordPDA(name: string, programId?: Address): Promise<Pda>;
+/**
+ * Derive ArNS record PDA from a raw 32-byte name hash.
+ * Used when resolving prescribed name hashes from Epoch data.
+ */
+export declare function getArnsRecordPDAFromHash(nameHash: Buffer, programId?: Address): Promise<Pda>;
+export declare function getReservedNamePDA(name: string, programId?: Address): Promise<Pda>;
+export declare function getReturnedNamePDA(name: string, programId?: Address): Promise<Pda>;
+export declare function getDemandFactorPDA(programId?: Address): Promise<Pda>;
+export declare function getAntConfigPDA(mint: Address, programId?: Address): Promise<Pda>;
+export declare function getAntControllersPDA(mint: Address, programId?: Address): Promise<Pda>;
+export declare function getAntRecordPDA(mint: Address, undername: string, programId?: Address): Promise<Pda>;
+export declare function getAntRecordMetadataPDA(mint: Address, undername: string, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getAclConfigPDA(user: Address, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getAclPagePDA(user: Address, pageIdx: bigint | number, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getEscrowAntPDA(antMint: Address, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getEscrowTokenPDA(depositor: Address, assetId: Uint8Array, programId?: Address): Promise<Pda>;
+/**
+ * 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 declare function getEscrowVaultPDA(depositor: Address, assetId: Uint8Array, programId?: Address): Promise<Pda>;

package/lib/types/solana/predict-prescribed-observers.d.ts

@@ -0,0 +1,28 @@
+import { type Address } from '@solana/kit';
+/** One registry slot's selection-relevant fields (`GatewaySlot`). */
+export interface RegistrySlotWeight {
+    /** `GatewaySlot.address` — the operator pubkey. Gateway PDAs derive from this. */
+    address: Address;
+    /** `GatewaySlot.composite_weight` (u64, mARIO-scaled). */
+    compositeWeight: bigint;
+}
+/**
+ * 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 declare function predictPrescribedObservers(epochHashchain: Uint8Array, slots: RegistrySlotWeight[], maxObservers: number): Address[];

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

@@ -0,0 +1,62 @@
+/**
+ * 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));
+ * ```
+ */
+export interface RetryOptions {
+    /** Maximum number of attempts (first call + retries). @default 3 */
+    maxAttempts?: number;
+    /** Base delay in ms before the first retry. Doubled each attempt. @default 1_000 */
+    baseDelayMs?: number;
+    /** Cap on any single delay in ms. @default 10_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,78 @@
+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 25
+     */
+    errorThresholdPercentage?: number;
+    /**
+     * Time in ms to wait before entering half-open state and retrying
+     * the primary.
+     * @default 60_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 3
+     */
+    volumeThreshold?: number;
+    /**
+     * Ceiling for requests allowed through per second. Implemented as an
+     * adaptive token bucket *in front of* the breaker: excess requests are
+     * queued (FIFO) until a token frees, smoothing bursts so you stay under a
+     * provider's rate limit (avoids HTTP 429 / Solana error #8100002).
+     *
+     * The bucket auto-tunes on 429s: it honors `Retry-After`, drops to
+     * `x-ratelimit-rps-limit` when the provider advertises one (public Solana
+     * RPC does; QuickNode generally does not), otherwise halves the rate
+     * (AIMD). It recovers back up toward this ceiling on sustained success.
+     *
+     * The queue wait happens *before* `breaker.fire`, so it does NOT count
+     * against {@link CircuitBreakerRpcOptions.timeout}.
+     *
+     * Throttling is always on; omitting this (or passing `<= 0`) uses the
+     * {@link DEFAULT_MAX_RPS} default. To effectively remove the limit, pass a
+     * very large number.
+     * @default 10
+     */
+    maxRequestsPerSecond?: number;
+    /**
+     * Maximum number of concurrent in-flight requests (opossum `capacity`
+     * semaphore). Unlike {@link CircuitBreakerRpcOptions.maxRequestsPerSecond},
+     * excess requests are **rejected immediately** rather than queued — this is
+     * concurrency control, not a rate limit. For avoiding 429s you usually want
+     * `maxRequestsPerSecond` instead.
+     * @default undefined (unlimited)
+     */
+    maxConcurrent?: 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/solana/send.d.ts

@@ -0,0 +1,94 @@
+import { type Address, type Commitment, type Instruction, type TransactionSigner } from '@solana/kit';
+import type { SolanaRpc, SolanaRpcSubscriptions } from './types.js';
+/**
+ * Build, sign, send, and confirm a transaction in one call.
+ *
+ * The caller supplies the core instructions; a compute-unit-limit instruction
+ * is prepended automatically.
+ */
+export declare function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment, computeUnitLimit, addressLookupTables, }: {
+    rpc: SolanaRpc;
+    rpcSubscriptions: SolanaRpcSubscriptions;
+    signer: TransactionSigner;
+    instructions: Instruction[];
+    commitment?: Commitment;
+    computeUnitLimit?: number;
+    /**
+     * Address Lookup Tables to compress the (v0) message against, as
+     * `{ [tableAddress]: addresses }`. Accounts present in a table are referenced
+     * by 1-byte index instead of their 32-byte key, shrinking the transaction —
+     * required when an instruction touches more accounts than fit inline (e.g.
+     * `prescribe_epoch` with ~50 observer PDAs). The tables MUST already be
+     * on-chain and active. See {@link sendWithEphemeralLookupTable}.
+     */
+    addressLookupTables?: Record<string, Address[]>;
+}): Promise<string>;
+/**
+ * Submit `instruction` in a v0 transaction whose `lookupAddresses` (read-only
+ * accounts) are served from a freshly-created, ephemeral Address Lookup Table,
+ * so an instruction touching far more accounts than fit inline (e.g.
+ * `prescribe_epoch` with ≤50 observer PDAs + NameRegistry, ~2 KB of keys) still
+ * fits Solana's 1232-byte transaction-size limit.
+ *
+ * Three confirmed steps: create the table, extend it with the addresses (in
+ * ≤20-address batches to stay within the extend tx size), then send
+ * `instruction` compressed against the table. The sequential confirmations
+ * satisfy the rule that appended addresses are only usable the slot AFTER they
+ * are added. `signer` is the table's authority + payer; the table's (tiny) rent
+ * is left allocated — a future cleanup pass can deactivate + close it.
+ */
+export declare function sendWithEphemeralLookupTable({ rpc, rpcSubscriptions, signer, instruction, lookupAddresses, commitment, computeUnitLimit, }: {
+    rpc: SolanaRpc;
+    rpcSubscriptions: SolanaRpcSubscriptions;
+    signer: TransactionSigner;
+    instruction: Instruction;
+    lookupAddresses: Address[];
+    commitment?: Commitment;
+    computeUnitLimit?: number;
+}): Promise<string>;
+/**
+ * Reclaim rent from the ephemeral Address Lookup Tables `signer` created for
+ * prescribe (see {@link sendWithEphemeralLookupTable}). Each prescribe leaves a
+ * single-use table allocated (~0.0126 SOL of rent); reclaiming needs a
+ * deactivate → ~513-slot cooldown → close sequence, so it can't run inline — a
+ * throttled permissionless cleanup pass (cranker / observer) calls this.
+ *
+ * Discovery is RPC-portable. `getProgramAccounts` on the Address Lookup Table
+ * program is rejected by Agave RPCs (`Invalid param: WrongSize`, on public
+ * devnet/mainnet-beta and dedicated providers alike — the ALT program can't be
+ * enumerated), so instead we read the signer's own transaction history
+ * (`getSignaturesForAddress` + `getTransaction`) and collect the tables it
+ * referenced via `message.addressTableLookups` — a prescribe ALT is used in
+ * exactly one transaction.
+ *
+ * Safety fingerprint: a candidate is only touched when EVERY one of its entries
+ * is owned by a program in `allowedEntryOwners` (the GAR + ArNS programs — i.e.
+ * observer Gateway PDAs + the ArNS NameRegistry). That composition uniquely
+ * identifies a prescribe ephemeral, so the pass never deactivates/closes an
+ * unrelated table even if `signer` is also used to author Address Lookup Tables
+ * for other purposes.
+ *
+ * DEACTIVATES still-active matches (starts the cooldown) and CLOSES deactivated
+ * matches past the cooldown (refunding rent to `signer`). At most `maxTables`
+ * submissions per call; scans at most `scanLimit` recent signatures. Best-effort:
+ * per-table failures are skipped and retried on the next pass.
+ */
+export declare function reclaimLookupTablesForSigner({ rpc, rpcSubscriptions, signer, allowedEntryOwners, commitment, maxTables, scanLimit, }: {
+    rpc: SolanaRpc;
+    rpcSubscriptions: SolanaRpcSubscriptions;
+    signer: TransactionSigner;
+    /**
+     * Program IDs that EVERY entry of a reclaimable prescribe ALT must be owned by
+     * — pass the GAR + ArNS program IDs. The fingerprint that keeps reclamation
+     * from touching unrelated lookup tables.
+     */
+    allowedEntryOwners: Address[];
+    commitment?: Commitment;
+    maxTables?: number;
+    scanLimit?: number;
+}): Promise<{
+    deactivated: number;
+    closed: number;
+    candidates: number;
+    scannedSignatures: number;
+}>;