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

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

@@ -0,0 +1,499 @@
+/**
+ * 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.
+ * This allows consumers to switch backends transparently.
+ */
+import { type Address, type Commitment } from '@solana/kit';
+import { type ILogger } from '../common/logger.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.
+ *
+ * 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?;
+    private _accountCache;
+    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;
+    /**
+     * 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.
+     *
+     * 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<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`.
+     *
+     * `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<BalanceWithAddress>): Promise<PaginationResult<BalanceWithAddress>>;
+    getVault({ address: owner, vaultId, }: {
+        address: WalletAddress;
+        vaultId: string;
+    }): 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<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<UserWithdrawal>>;
+    getArNSRecord({ name }: {
+        name: string;
+    }): Promise<ArNSNameData>;
+    getArNSRecords(params?: GetArNSRecordsParams): Promise<PaginationResult<ArNSNameDataWithName>>;
+    /**
+     * 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
+     * `ArNSNameDataWithName` items, no pagination wrapper. Callers
+     * that want pagination should drive it via `getArNSRecords({
+     * filters: { processId: mints } })` instead.
+     */
+    getArNSRecordsByAntMints({ mints, }: {
+        mints: ReadonlyArray<string>;
+    }): Promise<ArNSNameDataWithName[]>;
+    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<ArNSNameDataWithName> & {
+        address: WalletAddress;
+        antRegistryProcessId?: string;
+    }): Promise<PaginationResult<ArNSNameDataWithName>>;
+    getArNSReservedNames(params?: PaginationParams<ArNSReservedNameDataWithName>): Promise<PaginationResult<ArNSReservedNameDataWithName>>;
+    getArNSReservedName({ name, }: {
+        name: string;
+    }): Promise<ArNSReservedNameData>;
+    getArNSReturnedNames(params?: PaginationParams<ReturnedName>): Promise<PaginationResult<ReturnedName>>;
+    getArNSReturnedName({ name, }: {
+        name: string;
+    }): Promise<ReturnedName>;
+    getEpochSettings(): Promise<EpochSettings>;
+    /**
+     * 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<EpochData>;
+    getCurrentEpoch(): Promise<EpochData>;
+    getPrescribedObservers(epoch?: EpochInput): Promise<WeightedObserver[]>;
+    getPrescribedNames(epoch?: EpochInput): Promise<string[]>;
+    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: 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<PrimaryName>;
+    getPrimaryNameRequest(params: {
+        initiator: WalletAddress;
+    }): Promise<PrimaryNameRequest>;
+    getPrimaryNameRequests(params?: PaginationParams<PrimaryNameRequest>): Promise<PaginationResult<PrimaryNameRequest>>;
+    getPrimaryNames(params?: PaginationParams<PrimaryName>): Promise<PaginationResult<PrimaryName>>;
+    getRedelegationFee(params: {
+        address: WalletAddress;
+    }): 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`).
+     * 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 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).
+     */
+    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;
+    }>;
+}