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

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

@@ -1,156 +1,38 @@
 /**
- * AR.IO Solana event decoders — consumer-facing API.
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
  *
- * Anchor `#[event]` emits surface as `Program data: <base64>` log lines
- * inside the surrounding instruction's logs. The base64 blob is
- * `[discriminator(8) || borsh_payload]`, where the discriminator is
- * `sha256("event:<EventName>")[..8]`.
+ * 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
  *
- * This module wraps the per-program codecs in
- * `sdk/src/solana/generated/<program>/events/` (auto-emitted by
- * `sdk/scripts/events-codegen.mjs`) into:
- *   - a discriminated union `AnyEvent` covering every event the
- *     AR.IO contracts emit
- *   - per-program union types for filtering
- *   - log-walking utilities that route `Program data:` lines back to
- *     the program that emitted them (so events emitted from a CPI'd
- *     handler get attributed to the correct program)
- *   - a typed `parseTransactionEvents(rpc, signature)` helper
+ *     http://www.apache.org/licenses/LICENSE-2.0
  *
- * Event payloads are returned with `bigint` for u64 / i64 fields and
- * `Address` for pubkey fields, matching the rest of the kit-native
- * SDK. To narrow on a specific event, use the `name` discriminator or
- * the per-event type guards exported alongside the union.
- *
- * Live event subscription (websocket / Helius / Geyser) is out of
- * scope here — this module is the decoder layer that all those
- * mechanisms can build on. See `parseTransactionEvents` for the
- * pull-based model.
- */
-import { type Rpc, type Signature, type SolanaRpcApi } from '@solana/kit';
-import { ARIO_ANT_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/ant';
-import { ARIO_ANT_ESCROW_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/ant-escrow';
-import { ARIO_ARNS_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/arns';
-import { ARIO_CORE_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/core';
-import { ARIO_GAR_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/gar';
-import * as escrowEvents from './generated/ant-escrow/events/index.js';
-import * as antEvents from './generated/ant/events/index.js';
-import * as arnsEvents from './generated/arns/events/index.js';
-import * as coreEvents from './generated/core/events/index.js';
-import * as garEvents from './generated/gar/events/index.js';
-/** Maps event-name → decoded payload type, per program. */
-type CoreEventByName = {
-    [K in keyof typeof coreEvents as K extends `get${infer N}Decoder` ? N : never]: typeof coreEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
-        decode(b: Uint8Array): infer P;
-    } ? P : never : never;
-};
-type GarEventByName = {
-    [K in keyof typeof garEvents as K extends `get${infer N}Decoder` ? N : never]: typeof garEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
-        decode(b: Uint8Array): infer P;
-    } ? P : never : never;
-};
-type ArnsEventByName = {
-    [K in keyof typeof arnsEvents as K extends `get${infer N}Decoder` ? N : never]: typeof arnsEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
-        decode(b: Uint8Array): infer P;
-    } ? P : never : never;
-};
-type AntEventByName = {
-    [K in keyof typeof antEvents as K extends `get${infer N}Decoder` ? N : never]: typeof antEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
-        decode(b: Uint8Array): infer P;
-    } ? P : never : never;
-};
-type EscrowEventByName = {
-    [K in keyof typeof escrowEvents as K extends `get${infer N}Decoder` ? N : never]: typeof escrowEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
-        decode(b: Uint8Array): infer P;
-    } ? P : never : never;
-};
-/** Per-program decoded-event union (each variant tagged by `name`). */
-export type AnyArioCoreEvent = {
-    [K in keyof CoreEventByName]: {
-        programId: typeof ARIO_CORE_PROGRAM_ADDRESS;
-        name: K;
-        data: CoreEventByName[K];
-    };
-}[keyof CoreEventByName];
-export type AnyArioGarEvent = {
-    [K in keyof GarEventByName]: {
-        programId: typeof ARIO_GAR_PROGRAM_ADDRESS;
-        name: K;
-        data: GarEventByName[K];
-    };
-}[keyof GarEventByName];
-export type AnyArioArnsEvent = {
-    [K in keyof ArnsEventByName]: {
-        programId: typeof ARIO_ARNS_PROGRAM_ADDRESS;
-        name: K;
-        data: ArnsEventByName[K];
-    };
-}[keyof ArnsEventByName];
-export type AnyArioAntEvent = {
-    [K in keyof AntEventByName]: {
-        programId: typeof ARIO_ANT_PROGRAM_ADDRESS;
-        name: K;
-        data: AntEventByName[K];
-    };
-}[keyof AntEventByName];
-export type AnyArioAntEscrowEvent = {
-    [K in keyof EscrowEventByName]: {
-        programId: typeof ARIO_ANT_ESCROW_PROGRAM_ADDRESS;
-        name: K;
-        data: EscrowEventByName[K];
-    };
-}[keyof EscrowEventByName];
-/** Top-level union covering every event from every AR.IO program. */
-export type AnyEvent = AnyArioCoreEvent | AnyArioGarEvent | AnyArioArnsEvent | AnyArioAntEvent | AnyArioAntEscrowEvent;
-/** All event-name strings that can appear as `AnyEvent.name`. */
-export type EventName = AnyEvent['name'];
-/**
- * Parse every AR.IO event from a transaction's `log_messages` array.
- *
- * The logs are walked top-down. We track the current program by
- * pushing on `Program <id> invoke [N]` and popping on `Program <id>
- * success` / `failed`. Each `Program data: <base64>` line is attributed
- * to the program at the top of the stack — so a `StakePaymentEvent`
- * emitted by ario-gar from inside an ario-arns CPI is correctly
- * attributed to ario-gar.
- *
- * Lines whose discriminator doesn't match any known AR.IO event are
- * silently skipped — they may be from another program in the same tx
- * (e.g., SPL Token's debit/credit logs aren't event emissions, but
- * other Anchor programs in the same tx might emit unrelated events).
- *
- * Failed instructions inside a tx still emit logs up to the failure
- * point. We don't filter those out — caller can cross-reference the
- * tx's `meta.err` if it cares.
+ * 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.
  */
-export declare function parseEventsFromLogs(logs: readonly string[]): AnyEvent[];
-export declare function parseEventsFromLogs<N extends EventName>(logs: readonly string[], filter: N): Array<Extract<AnyEvent, {
-    name: N;
-}>>;
 /**
- * Fetch a transaction by signature and return its decoded events.
+ * AR.IO Solana event decoders — STUB.
  *
- * Uses `getTransaction` with `maxSupportedTransactionVersion: 0` and
- * `commitment: 'confirmed'` by default. Returns `[]` if the tx is
- * still pending, missing, or had no logs (rare — Anchor programs
- * always log).
+ * The local event codegen pipeline has been removed. Event decoders will be
+ * restored once `@ar.io/solana-contracts` publishes them. Until then, the
+ * parse functions return empty arrays and the union types are `never`.
  */
-export declare function parseTransactionEvents(rpc: Rpc<SolanaRpcApi>, signature: Signature, opts?: {
+import type { Rpc, Signature, SolanaRpcApi } from '@solana/kit';
+/** Placeholder — no event variants are available until the contracts package ships event decoders. */
+export type AnyArioCoreEvent = never;
+export type AnyArioGarEvent = never;
+export type AnyArioArnsEvent = never;
+export type AnyArioAntEvent = never;
+export type AnyArioAntEscrowEvent = never;
+export type AnyEvent = AnyArioCoreEvent | AnyArioGarEvent | AnyArioArnsEvent | AnyArioAntEvent | AnyArioAntEscrowEvent;
+export type EventName = never;
+export declare function parseEventsFromLogs(_logs: readonly string[]): AnyEvent[];
+export declare function parseTransactionEvents(_rpc: Rpc<SolanaRpcApi>, _signature: Signature, _opts?: {
     commitment?: 'processed' | 'confirmed' | 'finalized';
 }): Promise<AnyEvent[]>;
-/**
- * Generic type-narrowing predicate for any event name.
- *
- * ```ts
- * for (const ev of events) {
- *   if (isEvent(ev, 'NamePurchasedEvent')) {
- *     // ev.data is typed as NamePurchasedEvent here
- *     console.log(ev.data.buyer, ev.data.cost);
- *   }
- * }
- * ```
- */
-export declare function isEvent<N extends EventName>(ev: AnyEvent, name: N): ev is Extract<AnyEvent, {
+export declare function isEvent<N extends EventName>(ev: AnyEvent, _name: N): ev is Extract<AnyEvent, {
     name: N;
 }>;
-export {};

package/lib/types/solana/funding-plan.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.
+ */
 /**
  * Multi-source, multi-gateway funding plan builder + executor for the AR.IO
  * Solana SDK.

package/lib/types/solana/index.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 backend for the AR.IO SDK.
  *
@@ -38,8 +53,12 @@
  * });
  * ```
  */
+export * from '../common/index.js';
+export * from '../types/index.js';
+export * from '../utils/index.js';
+export { ARWEAVE_TX_REGEX, AR_IO_PROTOCOL, arweaveUri, FQDN_REGEX, MARIO_PER_ARIO, } from '../constants.js';
 export { SolanaARIOReadable } from './io-readable.js';
-export { SolanaARIOWriteable } from './io-writeable.js';
+export { type CrankAction, type CrankEpochStepOptions, type CrankEpochStepResult, isInvalidGatewayAccountError, SolanaARIOWriteable, } from './io-writeable.js';
 export { SolanaANTReadable } from './ant-readable.js';
 export { SolanaANTWriteable } from './ant-writeable.js';
 export { SolanaANTRegistryReadable } from './ant-registry-readable.js';
@@ -47,17 +66,22 @@ export type { SolanaANTRegistryConfig } from './ant-registry-readable.js';
 export { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
 export type { SolanaANTRegistryWriteableConfig } from './ant-registry-writeable.js';
 export type { AclMaintenanceOp, AclMaintenanceRole, } from '../types/ant-registry.js';
-export { ANTEscrow, TokenEscrow } from './escrow.js';
+export { ANTEscrow, TokenEscrow, assertVaultClaimable, isVaultClaimable, CLOCK_SKEW_TOLERANCE_SECONDS, } from './escrow.js';
 export type { ANTEscrowConfig, EscrowAntState, EscrowAssetType, EscrowProtocol, EscrowTokenState, } from './escrow.js';
-export { canonicalMessage, canonicalMessageV2, bytesToHexLower, } from './canonical-message.js';
+export { canonicalMessage, canonicalMessageV2, deriveRecipientId, bytesToHexLower, } from './canonical-message.js';
 export type { CanonicalMessageInput, CanonicalMessageV2Input, EscrowNetwork, } from './canonical-message.js';
 export { spawnSolanaANT, ARIO_LOGO_TX_ID, DEFAULT_ANT_TRANSACTION_ID, } from './spawn-ant.js';
 export type { SpawnSolanaANTParams, SpawnSolanaANTResult, SpawnSolanaANTState, } from './spawn-ant.js';
 export { hashName, getArioConfigPDA, getBalancePDA, getVaultPDA, getVaultCounterPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getGatewayRegistryPDA, getGarSettingsPDA, getGatewayPDA, getDelegationPDA, getWithdrawalPDA, getWithdrawalCounterPDA, getAllowlistPDA, getEpochPDA, getEpochSettingsPDA, getObservationPDA, getArnsRegistryPDA, getArnsSettingsPDA, getArnsRecordPDA, getArnsRecordPDAFromHash, getReservedNamePDA, getReturnedNamePDA, getDemandFactorPDA, getPrimaryNameReversePDA, getRedelegationRecordPDA, getAntConfigPDA, getAntControllersPDA, getAntRecordPDA, getAclConfigPDA, getAclPagePDA, getEscrowAntPDA, getEscrowTokenPDA, getEscrowVaultPDA, } from './pda.js';
 export { BorshReader, BorshWriter, deserializeGateway, deserializeArnsRecord, deserializeVault, deserializeDelegation, deserializeBalance, deserializeEpochSettings, deserializeArioConfig, deserializeDemandFactor, deserializeReservedName, deserializeReturnedName, deserializeWithdrawal, deserializeRedelegationRecord, deserializePrimaryNameRequest, deserializePrimaryName, deserializeAllowlist, deserializeGarSettings, deserializeEpochSettingsFull, deserializeEpoch, deserializeObservation, deserializeAntConfig, deserializeAntControllers, deserializeAntRecord, deserializeAclConfig, deserializeAclPage, } from './deserialize.js';
 export type { DeserializedAclEntry } from './deserialize.js';
+export { predictPrescribedObservers, type RegistrySlotWeight, } from './predict-prescribed-observers.js';
 export * from './constants.js';
 export * from './clusters.js';
+export { createCircuitBreakerRpc, defaultFallbackUrl, } from './rpc-circuit-breaker.js';
+export type { CircuitBreakerRpcConfig, CircuitBreakerRpcOptions, } from './rpc-circuit-breaker.js';
+export { withRetry, isRetryableError } from './retry.js';
+export type { RetryOptions } from './retry.js';
 export type { SolanaConfig, SolanaReadConfig, SolanaWriteConfig, SolanaRpc, SolanaRpcSubscriptions, SolanaSigner, SolanaTransactionResult, AccountData, } from './types.js';
 export { parseTransactionEvents, parseEventsFromLogs, isEvent, } from './events.js';
 export type { AnyEvent, AnyArioCoreEvent, AnyArioGarEvent, AnyArioArnsEvent, AnyArioAntEvent, AnyArioAntEscrowEvent, EventName, } from './events.js';

package/lib/types/solana/instruction.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.
+ */
 /**
  * Common Solana program/sysvar addresses used by the SDK.
  *

package/lib/types/solana/io-readable.d.ts

@@ -1,5 +1,20 @@
 /**
- * Solana implementation of the AoARIORead interface.
+ * 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 the ARIORead interface.
  *
  * Reads AR.IO protocol state directly from Solana PDAs using RPC,
  * returning the same types that the AO implementation returns.
@@ -7,8 +22,8 @@
  */
 import { type Address, type Commitment } from '@solana/kit';
 import { type ILogger } from '../common/logger.js';
-import type { AoPrimaryName, AoPrimaryNameRequest, AoRedelegationFeeInfo, WalletAddress } from '../types/common.js';
-import type { AoAddressParams, AoAllDelegates, AoAllGatewayVaults, AoArNSNameData, AoArNSNameDataWithName, AoArNSReservedNameData, AoArNSReservedNameDataWithName, AoBalanceWithAddress, AoDelegation, AoEligibleDistribution, AoEpochData, AoEpochDistributionData, AoEpochObservationData, AoEpochSettings, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoGatewayWithAddress, AoGetArNSRecordsParams, AoGetCostDetailsParams, AoPaginatedAddressParams, AoRegistrationFees, AoReturnedName, AoTokenCostParams, AoTokenSupplyData, AoVaultData, AoWalletVault, AoWeightedObserver, CostDetailsResult, DemandFactorSettings, EpochInput, PaginationParams, PaginationResult } from '../types/io.js';
+import type { PrimaryName, PrimaryNameRequest, RedelegationFeeInfo, WalletAddress } from '../types/common.js';
+import type { AddressParams, AllDelegates, AllGatewayVaults, ArNSNameData, ArNSNameDataWithName, ArNSReservedNameData, ArNSReservedNameDataWithName, BalanceWithAddress, CostDetailsResult, Delegation, DemandFactorSettings, EligibleDistribution, EpochData, EpochDistributionData, EpochInput, EpochObservationData, EpochSettings, Gateway, GatewayDelegateWithAddress, GatewayRegistrySettings, GatewayVault, GatewayWithAddress, GetArNSRecordsParams, GetCostDetailsParams, PaginatedAddressParams, PaginationParams, PaginationResult, RegistrationFees, ReturnedName, TokenCostParams, TokenSupplyData, UserWithdrawal, VaultData, WalletVault, WeightedObserver } from '../types/io.js';
 import type { SolanaReadConfig, SolanaRpc } from './types.js';
 /**
  * Solana-backed read-only client for the AR.IO protocol.
@@ -34,6 +49,7 @@ export declare class SolanaARIOReadable {
     protected readonly arnsProgram: Address;
     protected readonly antProgram: Address;
     private _arioMint?;
+    private _accountCache;
     constructor(config: SolanaReadConfig & {
         logger?: ILogger;
         coreProgramId?: Address;
@@ -43,6 +59,13 @@ export declare class SolanaARIOReadable {
     });
     /** Helper to fetch an encoded account (kit's replacement for Connection.getAccountInfo). */
     private getAccount;
+    /**
+     * Like {@link getAccount} but caches the result per-PDA for `ttlMs`. Use only
+     * for accounts that change slowly (DemandFactor, ArnsConfig) where a few
+     * seconds of staleness is acceptable in exchange for collapsing repeated
+     * reads. A successful fetch is cached; misses (`exists: false`) are not.
+     */
+    private getCachedAccount;
     /**
      * Helper for `getProgramAccounts` with a discriminator memcmp filter.
      *
@@ -82,7 +105,16 @@ export declare class SolanaARIOReadable {
         LastCreatedEpochIndex: number;
         LastDistributedEpochIndex: number;
     }>;
-    getTokenSupply(): Promise<AoTokenSupplyData>;
+    getTokenSupply(): Promise<TokenSupplyData>;
+    /**
+     * Read the `amount` (in mARIO) of an SPL token account directly by address.
+     * Returns `null` if the account doesn't exist or is too small to be a token
+     * account, so callers can distinguish "absent" from a real zero balance.
+     *
+     * Uses a portable little-endian u64 decode — some browser bundlers strip the
+     * BigInt readers from the `buffer` shim's prototype (see `getBalance`).
+     */
+    private getTokenAccountAmount;
     /**
      * Resolve the ARIO SPL mint address from the on-chain `ArioConfig`.
      *
@@ -115,27 +147,55 @@ export declare class SolanaARIOReadable {
      * Filters: token-account size = 165, mint at offset 0. We then decode
      * `owner` (offset 32) and `amount` (offset 64) from each.
      */
-    getBalances(params?: PaginationParams<AoBalanceWithAddress>): Promise<PaginationResult<AoBalanceWithAddress>>;
+    getBalances(params?: PaginationParams<BalanceWithAddress>): Promise<PaginationResult<BalanceWithAddress>>;
     getVault({ address: owner, vaultId, }: {
         address: WalletAddress;
         vaultId: string;
-    }): Promise<AoVaultData>;
-    getVaults(params?: PaginationParams<AoWalletVault>): Promise<PaginationResult<AoWalletVault>>;
-    getGateway({ address: addr }: AoAddressParams): Promise<AoGateway>;
-    getGateways(params?: PaginationParams<AoGatewayWithAddress>): Promise<PaginationResult<AoGatewayWithAddress>>;
-    getGatewayDelegates(params: AoAddressParams & PaginationParams<AoGatewayDelegateWithAddress>): Promise<PaginationResult<AoGatewayDelegateWithAddress>>;
-    getGatewayDelegateAllowList(params: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
-    getDelegations(params: PaginationParams<AoDelegation> & {
+    }): Promise<VaultData>;
+    getVaults(params?: PaginationParams<WalletVault>): Promise<PaginationResult<WalletVault>>;
+    getGateway({ address: addr }: AddressParams): Promise<Gateway>;
+    getGateways(params?: PaginationParams<GatewayWithAddress>): Promise<PaginationResult<GatewayWithAddress>>;
+    getGatewayDelegates(params: AddressParams & PaginationParams<GatewayDelegateWithAddress>): Promise<PaginationResult<GatewayDelegateWithAddress>>;
+    getGatewayDelegateAllowList(params: PaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
+    /**
+     * Returns every delegation a wallet currently has, covering both halves
+     * of the `Delegation` union:
+     *
+     * - `type: 'stake'` — active `Delegation` PDAs (filtered by delegator at
+     *   memcmp offset 40 = 8 disc + 32 gateway).
+     * - `type: 'vault'` — pending delegate-stake withdrawals: `Withdrawal`
+     *   PDAs filtered by owner at memcmp offset 8 (= 8 disc), then narrowed
+     *   client-side to `isDelegate: true`. Operator-stake withdrawals are
+     *   excluded — those are surfaced via `getWithdrawals` /
+     *   `getGatewayVaults`.
+     *
+     * Both queries run in parallel; consumers see a single merged result
+     * matching the cross-backend interface contract.
+     */
+    getDelegations(params: PaginationParams<Delegation> & {
+        address: WalletAddress;
+    }): Promise<PaginationResult<Delegation>>;
+    getAllowedDelegates(params: PaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
+    getGatewayVaults(params: PaginationParams<GatewayVault> & {
         address: WalletAddress;
-    }): Promise<PaginationResult<AoDelegation>>;
-    getAllowedDelegates(params: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
-    getGatewayVaults(params: PaginationParams<AoGatewayVault> & {
+    }): Promise<PaginationResult<GatewayVault>>;
+    /**
+     * Return every pending stake withdrawal owned by `address` — operator-stake
+     * decreases (`isDelegate: false`) and delegate-stake decreases
+     * (`isDelegate: true`) in one paginated result. A withdrawal is claimable
+     * when `Date.now() >= endTimestamp`; release the funds via
+     * `claimWithdrawal({ withdrawalId: item.vaultId })`.
+     *
+     * Solana-only: AO releases withdrawals automatically at maturity and has no
+     * equivalent per-owner read; the AO backend throws.
+     */
+    getWithdrawals(params: PaginationParams<UserWithdrawal> & {
         address: WalletAddress;
-    }): Promise<PaginationResult<AoGatewayVault>>;
+    }): Promise<PaginationResult<UserWithdrawal>>;
     getArNSRecord({ name }: {
         name: string;
-    }): Promise<AoArNSNameData>;
-    getArNSRecords(params?: AoGetArNSRecordsParams): Promise<PaginationResult<AoArNSNameDataWithName>>;
+    }): Promise<ArNSNameData>;
+    getArNSRecords(params?: GetArNSRecordsParams): Promise<PaginationResult<ArNSNameDataWithName>>;
     /**
      * Fetch every `ArnsRecord` whose `ant` field equals one of `mints`.
      *
@@ -146,13 +206,13 @@ export declare class SolanaARIOReadable {
      * mints against ≈ 4k records, and rises as the registry grows).
      *
      * The shape mirrors `getArNSRecord` / `getArNSRecords` — same
-     * `AoArNSNameDataWithName` items, no pagination wrapper. Callers
+     * `ArNSNameDataWithName` items, no pagination wrapper. Callers
      * that want pagination should drive it via `getArNSRecords({
      * filters: { processId: mints } })` instead.
      */
     getArNSRecordsByAntMints({ mints, }: {
         mints: ReadonlyArray<string>;
-    }): Promise<AoArNSNameDataWithName[]>;
+    }): Promise<ArNSNameDataWithName[]>;
     private fetchArnsRecordsByAntMints;
     /**
      * Resolve every ArNS record currently controlled by `address`.
@@ -166,19 +226,19 @@ export declare class SolanaARIOReadable {
      * owner / `AntControllers`, which is exactly what the ACL
      * indexes.
      */
-    getArNSRecordsForAddress(params: PaginationParams<AoArNSNameDataWithName> & {
+    getArNSRecordsForAddress(params: PaginationParams<ArNSNameDataWithName> & {
         address: WalletAddress;
         antRegistryProcessId?: string;
-    }): Promise<PaginationResult<AoArNSNameDataWithName>>;
-    getArNSReservedNames(params?: PaginationParams<AoArNSReservedNameDataWithName>): Promise<PaginationResult<AoArNSReservedNameDataWithName>>;
+    }): Promise<PaginationResult<ArNSNameDataWithName>>;
+    getArNSReservedNames(params?: PaginationParams<ArNSReservedNameDataWithName>): Promise<PaginationResult<ArNSReservedNameDataWithName>>;
     getArNSReservedName({ name, }: {
         name: string;
-    }): Promise<AoArNSReservedNameData>;
-    getArNSReturnedNames(params?: PaginationParams<AoReturnedName>): Promise<PaginationResult<AoReturnedName>>;
+    }): Promise<ArNSReservedNameData>;
+    getArNSReturnedNames(params?: PaginationParams<ReturnedName>): Promise<PaginationResult<ReturnedName>>;
     getArNSReturnedName({ name, }: {
         name: string;
-    }): Promise<AoReturnedName>;
-    getEpochSettings(): Promise<AoEpochSettings>;
+    }): Promise<ReturnedName>;
+    getEpochSettings(): Promise<EpochSettings>;
     /**
      * Resolve an EpochInput to an epoch index number.
      * - undefined: returns current epoch index from EpochSettings
@@ -188,40 +248,82 @@ export declare class SolanaARIOReadable {
     private resolveEpochIndex;
     /** Fetch and deserialize an Epoch account by index */
     private fetchEpoch;
-    getEpoch(epoch?: EpochInput): Promise<AoEpochData>;
-    getCurrentEpoch(): Promise<AoEpochData>;
-    getPrescribedObservers(epoch?: EpochInput): Promise<AoWeightedObserver[]>;
+    getEpoch(epoch?: EpochInput): Promise<EpochData>;
+    getCurrentEpoch(): Promise<EpochData>;
+    getPrescribedObservers(epoch?: EpochInput): Promise<WeightedObserver[]>;
     getPrescribedNames(epoch?: EpochInput): Promise<string[]>;
-    getObservations(epoch?: EpochInput): Promise<AoEpochObservationData>;
-    getDistributions(epoch?: EpochInput): Promise<AoEpochDistributionData>;
-    getEligibleEpochRewards(epoch?: EpochInput, params?: PaginationParams<AoEligibleDistribution>): Promise<PaginationResult<AoEligibleDistribution>>;
+    getObservations(epoch?: EpochInput): Promise<EpochObservationData>;
+    /**
+     * Observer pubkeys that have an OPEN Observation PDA for `epochIndex`. Lean —
+     * reads only the Observation accounts (no gateway-registry decode like
+     * {@link getObservations}). Used by the crank to close observations before
+     * `close_epoch`, whose `observations_closed == observations_submitted`
+     * precondition would otherwise wedge epoch progression.
+     */
+    getEpochObservers(epochIndex: number): Promise<Address[]>;
+    getDistributions(epoch?: EpochInput): Promise<EpochDistributionData>;
+    getEligibleEpochRewards(epoch?: EpochInput, params?: PaginationParams<EligibleDistribution>): Promise<PaginationResult<EligibleDistribution>>;
     /**
      * Compute the token cost for an ArNS operation.
      *
      * Mirrors the Rust pricing functions in ario-arns/src/pricing.rs.
      * Uses BigInt for u128-equivalent overflow-safe arithmetic.
      */
-    getTokenCost(params: AoTokenCostParams): Promise<number>;
-    getCostDetails(params: AoGetCostDetailsParams): Promise<CostDetailsResult>;
-    getRegistrationFees(): Promise<AoRegistrationFees>;
+    getTokenCost(params: TokenCostParams): Promise<number>;
+    getCostDetails(params: GetCostDetailsParams): Promise<CostDetailsResult>;
+    /**
+     * Project Solana on-chain state into the cross-backend `FundingPlan`
+     * shape consumed by UI flows like "how short are you on this purchase,
+     * and from which sources?". Always returns the wallet's `balance` and
+     * full per-gateway `stakes` breakdown (active delegations + pending
+     * delegate-stake withdrawals); `shortfall` is computed against the
+     * specific `fundFrom` semantics.
+     *
+     * Note: the internal `src/solana/funding-plan.ts` `FundingPlan` is a
+     * different type — that's the multi-source instruction-building plan
+     * used by `buyRecord({ fundFrom: 'any' })`. The two share a concept but
+     * not a shape; the public type here is what consumer UIs see.
+     */
+    private buildPublicFundingPlan;
+    getRegistrationFees(): Promise<RegistrationFees>;
     getDemandFactor(): Promise<number>;
     getDemandFactorSettings(): Promise<DemandFactorSettings>;
     getPrimaryName(params: {
         address: WalletAddress;
     } | {
         name: string;
-    }): Promise<AoPrimaryName>;
+    }): Promise<PrimaryName>;
     getPrimaryNameRequest(params: {
         initiator: WalletAddress;
-    }): Promise<AoPrimaryNameRequest>;
-    getPrimaryNameRequests(params?: PaginationParams<AoPrimaryNameRequest>): Promise<PaginationResult<AoPrimaryNameRequest>>;
-    getPrimaryNames(params?: PaginationParams<AoPrimaryName>): Promise<PaginationResult<AoPrimaryName>>;
+    }): Promise<PrimaryNameRequest>;
+    getPrimaryNameRequests(params?: PaginationParams<PrimaryNameRequest>): Promise<PaginationResult<PrimaryNameRequest>>;
+    getPrimaryNames(params?: PaginationParams<PrimaryName>): Promise<PaginationResult<PrimaryName>>;
     getRedelegationFee(params: {
         address: WalletAddress;
-    }): Promise<AoRedelegationFeeInfo>;
-    getGatewayRegistrySettings(): Promise<AoGatewayRegistrySettings>;
-    getAllDelegates(params?: PaginationParams<AoAllDelegates>): Promise<PaginationResult<AoAllDelegates>>;
-    getAllGatewayVaults(params?: PaginationParams<AoAllGatewayVaults>): Promise<PaginationResult<AoAllGatewayVaults>>;
+    }): Promise<RedelegationFeeInfo>;
+    getGatewayRegistrySettings(): Promise<GatewayRegistrySettings>;
+    getAllDelegates(params?: PaginationParams<AllDelegates>): Promise<PaginationResult<AllDelegates>>;
+    /**
+     * Enumerate every delegation that has pending (unsettled) rewards — the work
+     * list for the permissionless `compound_delegation_rewards` crank. Pending is
+     * computed from the gateway's reward-per-share accumulator (mirrors
+     * {@link computeLiveDelegationBalance}); the crank only changes balances, so
+     * rewards already accrue correctly without it.
+     *
+     * Skips delegations whose gateway is `Leaving` (those settle through
+     * `claim_delegate_from_leaving_gateway`, not compounding) and any below
+     * `minPendingRewards` — compounding sub-threshold dust just advances
+     * `reward_debt` for no balance gain. Feed the result, chunked, to
+     * `SolanaARIOWriteable.compoundDelegationRewardsBatch`.
+     */
+    getDelegationsToCompound(params?: {
+        minPendingRewards?: number;
+    }): Promise<Array<{
+        gatewayAddress: string;
+        delegatorAddress: string;
+        pendingRewards: number;
+    }>>;
+    getAllGatewayVaults(params?: PaginationParams<AllGatewayVaults>): Promise<PaginationResult<AllGatewayVaults>>;
     /**
      * Enumerate ArnsRecord PDAs whose lease has fully expired
      * (`end_timestamp + grace_period + return_auction_duration <= now`).
@@ -260,13 +362,50 @@ export declare class SolanaARIOReadable {
         failedConsecutive: number;
     }>>;
     /**
-     * Enumerate Gateway PDAs whose `status == Gone` (already left the
-     * network but PDA not yet GC'd). Eligible for `finalizeGone`.
+     * Enumerate Gateway PDAs that are candidates for `finalizeGone` GC — i.e.
+     * those whose `status == Leaving`.
+     *
+     * NOTE: despite the historical name, this returns `Leaving` (not `Gone`)
+     * gateways. `Gone` is NOT a persistent discovery state: the on-chain
+     * `finalize_gone` instruction accepts a `Leaving` gateway, flips it to
+     * `Gone`, and closes the Gateway PDA in the *same* instruction
+     * (programs/ario-gar/src/instructions/gateway.rs::finalize_gone), so a
+     * gateway is never observably parked at `Gone`. Filtering on `Gone` matched
+     * nothing and left Leaving gateways un-GC'd. Time/delegation eligibility is
+     * still enforced on-chain (`finalize_gone` reverts early if the leave window
+     * hasn't elapsed or delegations remain), so over-returning not-yet-eligible
+     * Leaving gateways is safe — the tx just no-ops/reverts.
+     *
+     * @deprecated Prefer {@link getLeavingGateways} — same result, accurate name.
      */
     getGoneGateways(): Promise<Array<{
         pubkey: Address;
         operator: Address;
     }>>;
+    /**
+     * Enumerate Gateway PDAs whose `status == Leaving` — the persistent
+     * pre-finalization state that `finalizeGone` GC's. Alias for
+     * {@link getGoneGateways} with a name that matches the on-chain state.
+     */
+    getLeavingGateways(): Promise<Array<{
+        pubkey: Address;
+        operator: Address;
+    }>>;
+    /**
+     * Enumerate Joined Gateway PDAs whose delegation has been DISABLED
+     * (`allow_delegated_staking == false`) yet still hold delegated stake
+     * (`total_delegated_stake > 0`) — i.e. delegates that an operator's disable
+     * left stranded (WP §6.3 / Fix #6). Each such gateway's delegates must be
+     * cranked out via
+     * {@link SolanaARIOWriteable.claimDelegateFromDisabledGateway} (enumerate
+     * them with {@link getGatewayDelegates}) before the operator can re-enable
+     * delegation. This is the discovery primitive a cranker uses to sweep them.
+     */
+    getDisabledGatewaysWithDelegatedStake(): Promise<Array<{
+        pubkey: Address;
+        operator: Address;
+        totalDelegatedStake: bigint;
+    }>>;
     /**
      * Enumerate Delegation PDAs with `amount == 0`. Eligible for
      * `closeEmptyDelegation` (rent refund to the original delegator).