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

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

@@ -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).

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

@@ -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/types/solana/mpl-core.d.ts

@@ -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).
  *
@@ -61,6 +76,35 @@ export declare function readAttribute(data: Uint8Array | ReadonlyUint8Array, key
  * 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.

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

@@ -1,4 +1,4 @@
-import { type Commitment, type Instruction, type TransactionSigner } from '@solana/kit';
+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.
@@ -6,11 +6,89 @@ import type { SolanaRpc, SolanaRpcSubscriptions } from './types.js';
  * The caller supplies the core instructions; a compute-unit-limit instruction
  * is prepended automatically.
  */
-export declare function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment, computeUnitLimit, }: {
+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;
+}>;

package/lib/types/solana/spawn-ant.d.ts

@@ -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.
+ */
 /**
  * Solana implementation of `ANT.spawn`.
  *

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

@@ -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.
+ */
 /**
  * Solana-specific types for the AR.IO SDK.
  *

package/lib/types/types/ant-registry.d.ts

@@ -13,8 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { AoMessageResult } from './common.js';
-export interface AoANTRegistryRead {
+import { MessageResult } from './common.js';
+export interface ANTRegistryRead {
     accessControlList(params: {
         address: string;
     }): Promise<{
@@ -61,8 +61,8 @@ export type AclMaintenanceOp = {
     user: string;
     asset: string;
 };
-export interface AoANTRegistryWrite extends AoANTRegistryRead {
+export interface ANTRegistryWrite extends ANTRegistryRead {
     register(params: {
         processId: string;
-    }): Promise<AoMessageResult>;
+    }): Promise<MessageResult>;
 }