@ar.io/sdk 3.24.0 → 4.0.0-solana.10

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

@@ -0,0 +1,360 @@
+/**
+ * Solana implementation of the AoARIORead interface.
+ *
+ * Reads AR.IO protocol state directly from Solana PDAs using RPC,
+ * returning the same types that the AO implementation returns.
+ * This allows consumers to switch backends transparently.
+ */
+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 { SolanaReadConfig, SolanaRpc } from './types.js';
+/**
+ * Solana-backed read-only client for the AR.IO protocol.
+ *
+ * Usage:
+ * ```ts
+ * import { createSolanaRpc } from '@solana/kit';
+ * import { SolanaARIOReadable } from '@ar.io/sdk/solana';
+ *
+ * const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+ * const ario = new SolanaARIOReadable({ rpc });
+ *
+ * const gateway = await ario.getGateway({ address: 'GatewayOperatorPubkey...' });
+ * const record = await ario.getArNSRecord({ name: 'ardrive' });
+ * ```
+ */
+export declare class SolanaARIOReadable {
+    protected readonly rpc: SolanaRpc;
+    protected readonly commitment: Commitment;
+    protected readonly logger: ILogger;
+    protected readonly coreProgram: Address;
+    protected readonly garProgram: Address;
+    protected readonly arnsProgram: Address;
+    protected readonly antProgram: Address;
+    private _arioMint?;
+    constructor(config: SolanaReadConfig & {
+        logger?: ILogger;
+        coreProgramId?: Address;
+        garProgramId?: Address;
+        arnsProgramId?: Address;
+        antProgramId?: Address;
+    });
+    /** Helper to fetch an encoded account (kit's replacement for Connection.getAccountInfo). */
+    private getAccount;
+    /**
+     * Helper for `getProgramAccounts` with a discriminator memcmp filter.
+     *
+     * Pass the Codama-generated `<NAME>_DISCRIMINATOR: Uint8Array` constant
+     * directly — kit's RPC requires a base58 string for `memcmp.bytes`, so
+     * we bs58-encode here to keep call sites from doing it inline (and to
+     * keep the IDL-derived bytes as the single source of truth).
+     */
+    private getAccountsByDiscriminator;
+    /**
+     * Batch-fetch the `cumulative_reward_per_token` accumulator for every gateway
+     * in `operatorAddresses`. Returns a Map keyed by base58 operator address.
+     * Used by the delegate readers below to compute the live delegation balance
+     * without an on-chain settlement call (see {@link computeLiveDelegationBalance}
+     * and `INVARIANTS.md` in the contracts repo). Missing gateways are silently
+     * skipped — callers fall back to the stale `Delegation.amount` for those
+     * (the accumulator delta is 0 and live == stored anyway when the gateway
+     * has no rewards to distribute).
+     */
+    protected getGatewayAccumulators(operatorAddresses: string[]): Promise<Map<string, bigint>>;
+    /** Read the gateway registry and return addresses in registry index order */
+    protected getRegistryGatewayAddresses(): Promise<string[]>;
+    getInfo(): Promise<{
+        epochSettings?: {
+            epochZeroStartTimestamp: number;
+            durationMs: number;
+            prescribedNameCount: number;
+            maxObservers: number;
+        } | undefined;
+        totalSupply?: number | undefined;
+        protocolBalance?: number | undefined;
+        Ticker: string;
+        Name: string;
+        Logo: string;
+        Denomination: number;
+        Handlers: never[];
+        LastCreatedEpochIndex: number;
+        LastDistributedEpochIndex: number;
+    }>;
+    getTokenSupply(): Promise<AoTokenSupplyData>;
+    /**
+     * Resolve the ARIO SPL mint address from the on-chain `ArioConfig`.
+     *
+     * `ArioConfig` layout: [8 disc][32 authority][32 mint][...]. We decode
+     * the mint at offset 40 and cache it for the lifetime of this instance —
+     * the mint never changes once the protocol is deployed.
+     */
+    protected getArioMint(): Promise<Address>;
+    /**
+     * Liquid ARIO balance for an address.
+     *
+     * On Solana the ARIO token is a real SPL mint, so the canonical liquid
+     * balance lives on the user's Associated Token Account — *not* the
+     * `ario-core::Balance` PDA. The Balance PDA is only populated by the
+     * one-shot AO-to-Solana migration importer for legacy snapshot accounts;
+     * spending it requires a separate claim flow that mints/transfers SPL
+     * tokens to the user's ATA. Steady-state instructions like `buy_name`,
+     * gateway/delegate stake, and ARIO transfers all move SPL tokens, so the
+     * ATA is what every UI and on-chain caller cares about.
+     *
+     * Returns 0 if the user has no ATA initialized yet.
+     */
+    getBalance({ address: owner, }: {
+        address: WalletAddress;
+    }): Promise<number>;
+    /**
+     * Enumerate liquid ARIO balances by querying the SPL Token program for
+     * every initialized token account on the ARIO mint.
+     *
+     * 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>>;
+    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> & {
+        address: WalletAddress;
+    }): Promise<PaginationResult<AoDelegation>>;
+    getAllowedDelegates(params: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
+    getGatewayVaults(params: PaginationParams<AoGatewayVault> & {
+        address: WalletAddress;
+    }): Promise<PaginationResult<AoGatewayVault>>;
+    getArNSRecord({ name }: {
+        name: string;
+    }): Promise<AoArNSNameData>;
+    getArNSRecords(params?: AoGetArNSRecordsParams): Promise<PaginationResult<AoArNSNameDataWithName>>;
+    /**
+     * Fetch every `ArnsRecord` whose `ant` field equals one of `mints`.
+     *
+     * Issues one `getProgramAccounts` per mint with a memcmp filter at
+     * `ARNS_RECORD_ANT_OFFSET`, in parallel. Cheaper than scanning the
+     * whole registry as soon as the caller has fewer mints than the
+     * registry has records (today the break-even is ≈ a few hundred
+     * mints against ≈ 4k records, and rises as the registry grows).
+     *
+     * The shape mirrors `getArNSRecord` / `getArNSRecords` — same
+     * `AoArNSNameDataWithName` items, no pagination wrapper. Callers
+     * that want pagination should drive it via `getArNSRecords({
+     * filters: { processId: mints } })` instead.
+     */
+    getArNSRecordsByAntMints({ mints, }: {
+        mints: ReadonlyArray<string>;
+    }): Promise<AoArNSNameDataWithName[]>;
+    private fetchArnsRecordsByAntMints;
+    /**
+     * Resolve every ArNS record currently controlled by `address`.
+     *
+     * Mirrors the AO backend: walk the on-chain ANT ACL for the wallet
+     * (`Owned ∪ Controlled`), then issue point-queries against the
+     * ArNS registry for those mints. This is semantically *not* a query
+     * over `ArnsRecord.owner` — that field is a write-once "purchase
+     * receipt" and never reflects current control on Solana (see
+     * ISSUES.md). Authoritative control flows through the ANT NFT
+     * owner / `AntControllers`, which is exactly what the ACL
+     * indexes.
+     */
+    getArNSRecordsForAddress(params: PaginationParams<AoArNSNameDataWithName> & {
+        address: WalletAddress;
+        antRegistryProcessId?: string;
+    }): Promise<PaginationResult<AoArNSNameDataWithName>>;
+    getArNSReservedNames(params?: PaginationParams<AoArNSReservedNameDataWithName>): Promise<PaginationResult<AoArNSReservedNameDataWithName>>;
+    getArNSReservedName({ name, }: {
+        name: string;
+    }): Promise<AoArNSReservedNameData>;
+    getArNSReturnedNames(params?: PaginationParams<AoReturnedName>): Promise<PaginationResult<AoReturnedName>>;
+    getArNSReturnedName({ name, }: {
+        name: string;
+    }): Promise<AoReturnedName>;
+    getEpochSettings(): Promise<AoEpochSettings>;
+    /**
+     * Resolve an EpochInput to an epoch index number.
+     * - undefined: returns current epoch index from EpochSettings
+     * - { epochIndex }: returns directly
+     * - { timestamp }: computes from genesis timestamp and epoch duration
+     */
+    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[]>;
+    getPrescribedNames(epoch?: EpochInput): Promise<string[]>;
+    getObservations(epoch?: EpochInput): Promise<AoEpochObservationData>;
+    getDistributions(epoch?: EpochInput): Promise<AoEpochDistributionData>;
+    getEligibleEpochRewards(epoch?: EpochInput, params?: PaginationParams<AoEligibleDistribution>): Promise<PaginationResult<AoEligibleDistribution>>;
+    /**
+     * 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>;
+    getDemandFactor(): Promise<number>;
+    getDemandFactorSettings(): Promise<DemandFactorSettings>;
+    getPrimaryName(params: {
+        address: WalletAddress;
+    } | {
+        name: string;
+    }): Promise<AoPrimaryName>;
+    getPrimaryNameRequest(params: {
+        initiator: WalletAddress;
+    }): Promise<AoPrimaryNameRequest>;
+    getPrimaryNameRequests(params?: PaginationParams<AoPrimaryNameRequest>): Promise<PaginationResult<AoPrimaryNameRequest>>;
+    getPrimaryNames(params?: PaginationParams<AoPrimaryName>): Promise<PaginationResult<AoPrimaryName>>;
+    getRedelegationFee(params: {
+        address: WalletAddress;
+    }): Promise<AoRedelegationFeeInfo>;
+    getGatewayRegistrySettings(): Promise<AoGatewayRegistrySettings>;
+    getAllDelegates(params?: PaginationParams<AoAllDelegates>): Promise<PaginationResult<AoAllDelegates>>;
+    getAllGatewayVaults(params?: PaginationParams<AoAllGatewayVaults>): Promise<PaginationResult<AoAllGatewayVaults>>;
+    /**
+     * Enumerate ArnsRecord PDAs whose lease has fully expired
+     * (`end_timestamp + grace_period + return_auction_duration <= now`).
+     * Permabuys (no `end_timestamp`) are excluded. Pass a unix-seconds `now`.
+     */
+    getExpiredArnsRecords(now: number): Promise<Array<{
+        pubkey: Address;
+        name: string;
+        endTimestamp: bigint;
+    }>>;
+    /**
+     * Enumerate ReturnedName PDAs whose Dutch auction window has fully
+     * elapsed (`returned_at + return_auction_duration <= now`).
+     */
+    getExpiredReturnedNames(now: number): Promise<Array<{
+        pubkey: Address;
+        name: string;
+        returnedAt: bigint;
+    }>>;
+    /**
+     * Enumerate ReservedName PDAs whose `expires_at` has passed.
+     * Permanent reservations (`expires_at: None`) are excluded.
+     */
+    getExpiredReservations(now: number): Promise<Array<{
+        pubkey: Address;
+        name: string;
+    }>>;
+    /**
+     * Enumerate Gateway PDAs in `Joined` status with
+     * `stats.failed_consecutive >= maxFailures`. These are eligible for
+     * `pruneGateway` (slash + remove from registry).
+     */
+    getDeficientGateways(maxFailures: number): Promise<Array<{
+        pubkey: Address;
+        operator: Address;
+        failedConsecutive: number;
+    }>>;
+    /**
+     * Enumerate Gateway PDAs whose `status == Gone` (already left the
+     * network but PDA not yet GC'd). Eligible for `finalizeGone`.
+     */
+    getGoneGateways(): Promise<Array<{
+        pubkey: Address;
+        operator: Address;
+    }>>;
+    /**
+     * Enumerate Delegation PDAs with `amount == 0`. Eligible for
+     * `closeEmptyDelegation` (rent refund to the original delegator).
+     */
+    getEmptyDelegations(): Promise<Array<{
+        pubkey: Address;
+        gateway: Address;
+        delegator: Address;
+    }>>;
+    /**
+     * Enumerate Withdrawal PDAs with `amount == 0` (drained via
+     * fund-from-withdrawal payments). Eligible for `closeDrainedWithdrawal`
+     * (rent refund to owner).
+     */
+    getDrainedWithdrawals(): Promise<Array<{
+        pubkey: Address;
+        owner: Address;
+        withdrawalId: bigint;
+    }>>;
+    /**
+     * Enumerate Vault PDAs whose `end_timestamp` has passed (eligible for
+     * `releaseVault`). Note: `releaseVault` is owner-signed, so the cranker
+     * can only release its own vaults — the helper still surfaces every
+     * expired vault so other consumers (UIs, indexers) can use it too.
+     */
+    getExpiredVaults(now: number): Promise<Array<{
+        pubkey: Address;
+        owner: Address;
+        vaultId: bigint;
+        endTimestamp: bigint;
+    }>>;
+    /**
+     * Enumerate PrimaryNameRequest PDAs whose `expires_at` has passed.
+     * Eligible for `closeExpiredRequest` (rent refund to original initiator).
+     */
+    getExpiredPrimaryNameRequests(now: number): Promise<Array<{
+        pubkey: Address;
+        initiator: Address;
+    }>>;
+    /**
+     * Read the live `ArnsConfig` (used by the cranker to gate
+     * `pruneExpiredNames` / `pruneReturnedNames` on the
+     * `next_*_prune_timestamp` hints).
+     */
+    getArnsConfigRaw(): Promise<{
+        nextRecordsPruneTimestamp: bigint;
+        nextReturnedNamesPruneTimestamp: bigint;
+        gracePeriodSeconds: bigint;
+        returnAuctionDurationSeconds: bigint;
+    } | null>;
+    resolveArNSName({ name }: {
+        name: string;
+    }): Promise<{
+        name: string;
+        txId: string;
+        type: "lease" | "permabuy";
+        processId: string;
+        ttlSeconds: number;
+        undernameLimit: number;
+    }>;
+    /**
+     * Resolve the gateway operator pubkey backing a given observer pubkey.
+     * The `ObserverLookup` PDA is written at `join_network` (and rotated by
+     * `update_observer_address`); when present its `gateway` field is the
+     * operator pubkey. Returns `undefined` when the observer isn't
+     * registered on any gateway.
+     */
+    getObserverLookup(observer: Address): Promise<{
+        gateway: Address;
+        bump: number;
+    } | undefined>;
+    /**
+     * Pre-flight gate for `save_observations` submission. Reads the Epoch
+     * account once and reports whether the given observer pubkey is:
+     *   - `prescribed`: in `epoch.prescribed_observers[..observer_count]`
+     *   - `observerIdx`: position in the array (matches the `has_observed`
+     *     bit index when prescribed)
+     *   - `alreadyObserved`: whether the bit at `observerIdx` is set
+     *   - `windowOpen`: whether `now < epoch.end_timestamp`
+     *
+     * Use this from a sink/wrapper to skip cheap-to-skip cases before
+     * paying for a transaction simulation that would just bounce.
+     */
+    getEpochObservationStatus(epochIndex: number, observer: Address): Promise<{
+        prescribed: boolean;
+        observerIdx: number;
+        alreadyObserved: boolean;
+        windowOpen: boolean;
+        endTimestampSec: number;
+    }>;
+}