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

package/lib/types/common/io.d.ts

@@ -1,266 +1,74 @@
-import Arweave from 'arweave';
-import { ARIOWithFaucet, AoARIORead, AoARIOWrite, AoAllDelegates, AoAllGatewayVaults, AoArNSNameData, AoArNSNameDataWithName, AoArNSPurchaseParams, AoArNSReservedNameData, AoArNSReservedNameDataWithName, AoBalanceWithAddress, AoBuyRecordParams, AoCreatePrimaryNameRequest, AoCreateVaultParams, AoDelegation, AoEligibleDistribution, AoEpochData, AoEpochDistributed, AoEpochDistributionData, AoEpochDistributionTotalsData, AoEpochObservationData, AoEpochSettings, AoExtendLeaseParams, AoExtendVaultParams, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoGatewayWithAddress, AoGetCostDetailsParams, AoIncreaseUndernameLimitParams, AoIncreaseVaultParams, AoJoinNetworkParams, AoMessageResult, AoPaginatedAddressParams, AoPrimaryName, AoPrimaryNameRequest, AoRedelegationFeeInfo, AoRegistrationFees, AoReturnedName, AoRevokeVaultParams, AoTokenSupplyData, AoUpdateGatewaySettingsParams, AoVaultData, AoVaultedTransferParams, AoWalletVault, AoWeightedObserver, ArNSNameResolutionData, ArNSNameResolver, BuyArNSNameProgressEvents, CostDetailsResult, DemandFactorSettings, EpochInput, OptionalArweave, OptionalPaymentUrl, PaginationParams, PaginationResult, ProcessConfiguration, SetPrimaryNameProgressEvents, TransactionId, WalletAddress, WithSigner, WriteOptions, mARIOToken } from '../types/index.js';
-import { AOProcess } from './contracts/ao-process.js';
-import { HB } from './hyperbeam/hb.js';
-import { Logger } from './logger.js';
-import { TurboArNSPaymentProviderAuthenticated, TurboArNSPaymentProviderUnauthenticated } from './turbo.js';
-type ARIOConfigNoSigner = OptionalPaymentUrl<OptionalArweave<ProcessConfiguration & {
-    hyperbeamUrl?: string;
-}>>;
-type ARIOConfigWithSigner = WithSigner<OptionalPaymentUrl<OptionalArweave<ProcessConfiguration & {
-    hyperbeamUrl?: string;
-}>>>;
-export declare class ARIO {
-    static init(): AoARIORead;
-    static init(config: ARIOConfigWithSigner): AoARIOWrite;
-    static init(config: ARIOConfigNoSigner): AoARIORead;
-    static mainnet(): AoARIORead;
-    static mainnet(config: ARIOConfigNoSigner): AoARIORead;
-    static mainnet(config: ARIOConfigWithSigner): AoARIOWrite;
-    static testnet(): ARIOWithFaucet<AoARIORead>;
-    static testnet(config: ARIOConfigNoSigner & {
-        faucetUrl?: string;
-    }): ARIOWithFaucet<AoARIORead>;
-    static testnet(config: ARIOConfigWithSigner & {
-        faucetUrl?: string;
-    }): ARIOWithFaucet<AoARIOWrite>;
-}
-export declare class ARIOReadable implements AoARIORead, ArNSNameResolver {
-    readonly process: AOProcess;
-    protected epochSettings: AoEpochSettings | undefined;
-    protected arweave: Arweave;
-    protected hyperbeamUrl: string | undefined;
-    protected paymentProvider: TurboArNSPaymentProviderUnauthenticated;
-    protected logger: Logger;
-    protected hb: HB | undefined;
-    constructor(config?: ARIOConfigNoSigner);
-    getInfo(): Promise<{
-        Name: string;
-        Ticker: string;
-        Logo: string;
-        Denomination: number;
-        Handlers: string[];
-        LastCreatedEpochIndex: number;
-        LastDistributedEpochIndex: number;
-    }>;
-    getTokenSupply(): Promise<AoTokenSupplyData>;
-    private computeEpochIndexForTimestamp;
-    private computeCurrentEpochIndex;
-    private computeEpochIndex;
-    getEpochSettings(): Promise<AoEpochSettings>;
-    getEpoch(): Promise<AoEpochData<AoEpochDistributionTotalsData>>;
-    getEpoch(epoch: EpochInput): Promise<AoEpochData<AoEpochDistributed>>;
-    getArNSRecord({ name }: {
-        name: string;
-    }): Promise<AoArNSNameData>;
-    getArNSRecords(params?: PaginationParams<AoArNSNameDataWithName>): Promise<PaginationResult<AoArNSNameDataWithName>>;
-    getArNSReservedNames(params?: PaginationParams<AoArNSReservedNameDataWithName>): Promise<PaginationResult<AoArNSReservedNameDataWithName>>;
-    getArNSReservedName({ name, }: {
-        name: string;
-    }): Promise<AoArNSReservedNameData>;
-    getBalance({ address }: {
-        address: WalletAddress;
-    }): Promise<number>;
-    getBalances(params?: PaginationParams<AoBalanceWithAddress>): Promise<PaginationResult<AoBalanceWithAddress>>;
-    getVault({ address, vaultId, }: {
-        address: WalletAddress;
-        vaultId: string;
-    }): Promise<AoVaultData>;
-    getVaults(params?: PaginationParams<AoWalletVault>): Promise<PaginationResult<AoWalletVault>>;
-    getGateway({ address, }: {
-        address: WalletAddress;
-    }): Promise<AoGateway>;
-    getGatewayDelegates({ address, ...pageParams }: {
-        [x: string]: any;
-        address: any;
-    }): Promise<PaginationResult<AoGatewayDelegateWithAddress>>;
-    getGatewayDelegateAllowList({ address, ...pageParams }: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
-    getGateways(pageParams?: PaginationParams<AoGatewayWithAddress>): Promise<PaginationResult<AoGatewayWithAddress>>;
-    getCurrentEpoch(): Promise<AoEpochData<AoEpochDistributionTotalsData>>;
-    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>>;
-    getTokenCost(params: {
-        intent: 'Buy-Record' | 'Buy-Name';
-        type: 'permabuy' | 'lease';
-        years: number;
-        name: string;
-    }): Promise<number>;
-    getTokenCost(params: {
-        intent: 'Extend-Lease';
-        years: number;
-        name: string;
-    }): Promise<number>;
-    getTokenCost(params: {
-        intent: 'Increase-Undername-Limit';
-        quantity: number;
-        name: string;
-    }): Promise<number>;
-    getTokenCost(params: {
-        intent: 'Upgrade-Name';
-        name: string;
-    }): Promise<number>;
-    getTokenCost(params: {
-        intent: 'Primary-Name-Request';
-        name: string;
-    }): Promise<number>;
-    getCostDetails({ intent, type, years, name, quantity, fromAddress, fundFrom, }: AoGetCostDetailsParams): Promise<CostDetailsResult>;
-    getRegistrationFees(): Promise<AoRegistrationFees>;
-    getDemandFactor(): Promise<number>;
-    getDemandFactorSettings(): Promise<DemandFactorSettings>;
-    getArNSReturnedNames(params?: PaginationParams<AoReturnedName>): Promise<PaginationResult<AoReturnedName>>;
-    getArNSReturnedName({ name, }: {
-        name: string;
-    }): Promise<AoReturnedName>;
-    getDelegations(params: PaginationParams<AoDelegation> & {
-        address: WalletAddress;
-    }): Promise<PaginationResult<AoDelegation>>;
-    getAllowedDelegates(params: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
-    getGatewayVaults(params: PaginationParams<AoGatewayVault> & {
-        address: WalletAddress;
-    }): Promise<PaginationResult<AoGatewayVault>>;
-    getPrimaryNameRequest(params: {
-        initiator: WalletAddress;
-    }): Promise<AoPrimaryNameRequest>;
-    getPrimaryNameRequests(params?: PaginationParams<AoPrimaryNameRequest>): Promise<PaginationResult<AoPrimaryNameRequest>>;
-    getPrimaryName(params: {
-        address: WalletAddress;
-    } | {
-        name: string;
-    }): Promise<AoPrimaryName>;
-    getPrimaryNames(params: PaginationParams<AoPrimaryName>): Promise<PaginationResult<AoPrimaryName>>;
-    /**
-     * Get current redelegation fee percentage for address
-     *
-     * @param {Object} params - The parameters for fetching redelegation fee
-     * @param {string} params.address - The address to fetch the fee for
-     * @returns {Promise<AoMessageResult>} The redelegation fee result
-     */
-    getRedelegationFee(params: {
-        address: WalletAddress;
-    }): Promise<AoRedelegationFeeInfo>;
-    getGatewayRegistrySettings(): Promise<AoGatewayRegistrySettings>;
-    getAllDelegates(params?: PaginationParams<AoAllDelegates>): Promise<PaginationResult<AoAllDelegates>>;
-    getAllGatewayVaults(params?: PaginationParams<AoAllGatewayVaults>): Promise<PaginationResult<AoAllGatewayVaults>>;
-    resolveArNSName({ name, }: {
-        name: string;
-    }): Promise<ArNSNameResolutionData>;
+/**
+ * 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.
+ */
+import type { Address, Commitment } from '@solana/kit';
+import type { SolanaRpc, SolanaRpcSubscriptions, SolanaSigner } from '../solana/types.js';
+import type { ARIORead, ARIOWrite } from '../types/index.js';
+/**
+ * Configuration for ARIO.init().
+ *
+ * Program ID overrides (`coreProgramId`, `garProgramId`, `arnsProgramId`,
+ * `antProgramId`) are required against any cluster other than mainnet —
+ * devnet, localnet, and the Surfpool harness all deploy programs at addresses
+ * derived from per-cluster keypair files, not the placeholder constants in
+ * `src/solana/constants.ts`. On localnet, source these from
+ * `migration/localnet/out/localnet.env`.
+ */
+export type ARIOConfig = {
+    rpc: SolanaRpc;
+    /** Required for write operations (needed by kit's sendAndConfirm). */
+    rpcSubscriptions?: SolanaRpcSubscriptions;
+    commitment?: Commitment;
+    signer?: SolanaSigner;
+    coreProgramId?: Address;
+    garProgramId?: Address;
+    arnsProgramId?: Address;
     /**
-     * Get all ARNS names associated with an address using the provided ANT registry address.
-     *
-     * By default it will use the mainnet ANT registry address.
-     *
-     * @param {Object} params - The parameters for fetching ARNS names
-     * @param {string} params.address - The address to fetch the ARNS names for
-     * @returns {Promise<AoArNSNameData[]>} The ARNS names associated with the address
+     * Override the deployed `ario-ant` program id. Required for the
+     * ACL-driven `getArNSRecordsForAddress` pipeline on any cluster
+     * other than mainnet (devnet, localnet, Surfpool).
      */
-    getArNSRecordsForAddress(params: PaginationParams<AoArNSNameDataWithName> & {
-        antRegistryProcessId?: string;
-        address: WalletAddress;
-    }): Promise<PaginationResult<AoArNSNameDataWithName>>;
-}
-export declare class ARIOWriteable extends ARIOReadable implements AoARIOWrite {
-    private signer;
-    protected paymentProvider: TurboArNSPaymentProviderAuthenticated | TurboArNSPaymentProviderUnauthenticated;
-    constructor({ signer, paymentUrl, ...config }: ARIOConfigWithSigner);
-    transfer({ target, qty, }: {
-        target: string;
-        qty: number | mARIOToken;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    vaultedTransfer({ recipient, quantity, lockLengthMs, revokable, }: AoVaultedTransferParams, options?: WriteOptions): Promise<AoMessageResult>;
-    revokeVault({ vaultId, recipient }: AoRevokeVaultParams, options?: WriteOptions): Promise<AoMessageResult>;
-    createVault({ lockLengthMs, quantity }: AoCreateVaultParams, options?: WriteOptions): Promise<AoMessageResult>;
-    extendVault({ vaultId, extendLengthMs }: AoExtendVaultParams, options?: WriteOptions): Promise<AoMessageResult>;
-    increaseVault({ vaultId, quantity }: AoIncreaseVaultParams, options?: WriteOptions): Promise<AoMessageResult>;
-    joinNetwork({ operatorStake, allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, services, }: AoJoinNetworkParams, options?: WriteOptions): Promise<AoMessageResult>;
-    leaveNetwork(options?: WriteOptions): Promise<AoMessageResult>;
-    updateGatewaySettings({ allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, services, }: AoUpdateGatewaySettingsParams, options?: WriteOptions): Promise<AoMessageResult>;
-    delegateStake(params: {
-        target: string;
-        stakeQty: number | mARIOToken;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    decreaseDelegateStake(params: {
-        target: string;
-        decreaseQty: number | mARIOToken;
-        instant?: boolean;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    /**
-     * Initiates an instant withdrawal from a gateway.
-     *
-     * @param {Object} params - The parameters for initiating an instant withdrawal
-     * @param {string} params.address - The gateway address of the withdrawal, if not provided, the signer's address will be used
-     * @param {string} params.vaultId - The vault ID of the withdrawal
-     * @returns {Promise<AoMessageResult>} The result of the withdrawal
-     */
-    instantWithdrawal(params: {
-        gatewayAddress?: string;
-        vaultId: string;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    increaseOperatorStake(params: {
-        increaseQty: number | mARIOToken;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    decreaseOperatorStake(params: {
-        decreaseQty: number | mARIOToken;
-        instant?: boolean;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    saveObservations(params: {
-        reportTxId: TransactionId;
-        failedGateways: WalletAddress[];
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    buyRecord(params: AoBuyRecordParams, options?: WriteOptions<keyof BuyArNSNameProgressEvents, BuyArNSNameProgressEvents[keyof BuyArNSNameProgressEvents]>): Promise<AoMessageResult>;
+    antProgramId?: Address;
+};
+export declare const DEFAULT_SOLANA_RPC_URL = "https://api.mainnet-beta.solana.com";
+export declare class ARIO {
     /**
-     * Upgrades an existing leased record to a permabuy.
+     * Create an ARIO client bound to a Solana RPC transport.
      *
-     * @param {Object} params - The parameters for upgrading a record
-     * @param {string} params.name - The name of the record to upgrade
-     * @param {Object} [options] - The options for the upgrade
-     * @returns {Promise<AoMessageResult>} The result of the upgrade
-     */
-    upgradeRecord(params: AoArNSPurchaseParams, options?: WriteOptions): Promise<AoMessageResult>;
-    /**
-     * Extends the lease of an existing leased record.
+     * The return type is selected by the {@link ARIOConfig} you pass:
+     * - **Read-write** — when `signer` (a {@link SolanaSigner}) is provided. A
+     *   {@link SolanaRpcSubscriptions} client is then also required so
+     *   `@solana/kit`'s `sendAndConfirmTransaction` can await confirmations;
+     *   omitting it throws. Returns {@link ARIOWrite}.
+     * - **Read-only** — when `signer` is omitted. Returns {@link ARIORead}.
      *
-     * @param {Object} params - The parameters for extending a lease
-     * @param {string} params.name - The name of the record to extend
-     * @param {number} params.years - The number of years to extend the lease
-     * @param {Object} [options] - The options for the extension
-     * @returns {Promise<AoMessageResult>} The result of the extension
-     */
-    extendLease(params: AoExtendLeaseParams, options?: WriteOptions): Promise<AoMessageResult>;
-    increaseUndernameLimit(params: AoIncreaseUndernameLimitParams, options?: WriteOptions): Promise<AoMessageResult>;
-    /**
-     * Cancel a withdrawal from a gateway.
-     *
-     * @param {Object} params - The parameters for cancelling a withdrawal
-     * @param {string} [params.address] - The address of the withdrawal (optional). If not provided, the signer's address will be used.
-     * @param {string} params.vaultId - The vault ID of the withdrawal.
-     * @param {Object} [options] - The options for the cancellation
-     * @returns {Promise<AoMessageResult>} The result of the cancellation
-     */
-    cancelWithdrawal(params: {
-        gatewayAddress?: WalletAddress;
-        vaultId: string;
-    }, options?: WriteOptions | undefined): Promise<AoMessageResult>;
-    requestPrimaryName(params: AoArNSPurchaseParams, options?: WriteOptions): Promise<AoMessageResult<AoCreatePrimaryNameRequest>>;
-    setPrimaryName(params: AoArNSPurchaseParams, options?: WriteOptions<keyof SetPrimaryNameProgressEvents, SetPrimaryNameProgressEvents[keyof SetPrimaryNameProgressEvents]>): Promise<AoMessageResult>;
-    /**
-     * Redelegate stake from one gateway to another gateway.
+     * Program-id overrides (`coreProgramId` / `garProgramId` / `arnsProgramId` /
+     * `antProgramId`) are required on any non-mainnet cluster (devnet, localnet,
+     * Surfpool); see {@link ARIOConfig}.
      *
-     * @param {Object} params - The parameters for redelegating stake
-     * @param {string} params.target - The target gateway address
-     * @param {string} params.source - The source gateway address
-     * @param {number} params.stakeQty - The quantity of stake to redelegate
-     * @param {string} params.vaultId - An optional vault ID to redelegate from
-     * @param {Object} [options] - The options for the redelegation
-     * @returns {Promise<AoMessageResult>} The result of the redelegation
+     * @param config - RPC transport, optional signer/subscriptions, and
+     *   per-cluster program-id overrides.
+     * @returns {@link ARIOWrite} when a signer is supplied, otherwise
+     *   {@link ARIORead}.
+     * @throws If a signer is supplied without `rpcSubscriptions`.
      */
-    redelegateStake(params: {
-        target: string;
-        source: string;
-        stakeQty: number | mARIOToken;
-        vaultId?: string;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
+    static init(config: ARIOConfig & {
+        signer: SolanaSigner;
+        rpcSubscriptions: SolanaRpcSubscriptions;
+    }): ARIOWrite;
+    static init(config: ARIOConfig & {
+        signer?: never;
+    }): ARIORead;
 }
-export {};

package/lib/types/constants.d.ts

@@ -14,24 +14,17 @@
  * limitations under the License.
  */
 export declare const ARWEAVE_TX_REGEX: RegExp;
+/** ar:// protocol prefix for location-independent Arweave references */
+export declare const AR_IO_PROTOCOL = "ar://";
+/** Default AR.IO logo Arweave TX ID (32x32 PNG) */
+export declare const ARIO_LOGO_TX_ID = "WMLnh8pQL-UIXZMpdU2NUIriHfcFB5Bc49V8jTHjsZc";
+/**
+ * Construct an ar:// URI from an Arweave TX ID or ArNS name.
+ *
+ * - ar://{txId} — raw 43-char TX ID, resolved by wallets via arweave.net gateway
+ * - ar://{arnsName} — ArNS name, resolved by AR.IO gateways and Wayfinder SDK
+ */
+export declare function arweaveUri(txIdOrName: string): string;
 /** FQDN regex that matches the one used in the ArNS contract. */
 export declare const FQDN_REGEX: RegExp;
-export declare const ARIO_DEVNET_PROCESS_ID = "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc";
-export declare const arioDevnetProcessId = "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc";
-export declare const ARIO_TESTNET_PROCESS_ID = "agYcCFJtrMG6cqMuZfskIkFTGvUPddICmtQSBIoPdiA";
-export declare const ARIO_MAINNET_PROCESS_ID = "qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE";
-export declare const ANT_REGISTRY_TESTNET_ID = "RR0vheYqtsKuJCWh6xj0beE35tjaEug5cejMw9n2aa8";
-export declare const ANT_REGISTRY_ID = "i_le_yKKPVstLTDSmkHRqf-wYphMnwB9OhleiTgMkWc";
-export declare const MARKETPLACE_CONTRACT_ID = "wPh88ziUF4meLpHfffmgdA6IFtzmXHgdeg-epzBjkao";
 export declare const MARIO_PER_ARIO = 1000000;
-/**
- * @deprecated - use ANT.versions.getLatestANTVersion() to get latest ANT module
- **/
-export declare const AOS_MODULE_ID = "nEjlSFA_8narJlVHApbczDPkMc9znSqYtqtf1iOdoxM";
-/**
- * @deprecated - use ANT.versions.getLatestANTVersion() to get latest ANT module
- **/
-export declare const ANT_LUA_ID = "sOW9Sdm1yoPRrzerC5iu1nsupp4e6I-HnJyYVHzvzQo";
-export declare const AO_AUTHORITY = "fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY";
-export declare const DEFAULT_SCHEDULER_ID = "_GQ33BkPtZrqxA84vM8Zk-N2aO0toNNu_C-l-rawrBA";
-export declare const DEFAULT_CU_URL = "https://cu.ardrive.io";

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

@@ -0,0 +1,180 @@
+/**
+ * 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 (Arweave Name Token) read interface.
+ *
+ * Reads ANT state from Metaplex Core NFT + PDA accounts on Solana.
+ * Each ANT is a Metaplex Core NFT with extended state in PDAs:
+ *   - AntConfig: name, ticker, logo, description, keywords, owner
+ *   - AntControllers: list of controller pubkeys
+ *   - AntRecord: undername records (transactionId, ttl, priority, etc.)
+ */
+import { type Address, type Commitment } from '@solana/kit';
+import { type ILogger } from '../common/logger.js';
+import type { ANTHandler, ANTInfo, ANTRecord, ANTState, ANTSummary, AntReadOptions, SortedANTRecords } from '../types/ant.js';
+import type { WalletAddress } from '../types/common.js';
+import { SolanaANTRegistryReadable } from './ant-registry-readable.js';
+import type { SolanaRpc } from './types.js';
+/**
+ * Solana-backed read-only client for a single ANT (Arweave Name Token).
+ *
+ * Usage:
+ * ```ts
+ * import { createSolanaRpc } from '@solana/kit';
+ * import { SolanaANTReadable } from '@ar.io/sdk/solana';
+ *
+ * const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+ * const ant = new SolanaANTReadable({
+ *   rpc,
+ *   processId: 'MetaplexCoreAssetAddress...',
+ * });
+ *
+ * const owner = await ant.getOwner();
+ * const record = await ant.getRecord({ undername: '@' });
+ * ```
+ */
+export declare class SolanaANTReadable {
+    readonly processId: string;
+    protected readonly rpc: SolanaRpc;
+    protected readonly commitment: Commitment;
+    protected readonly logger: ILogger;
+    protected readonly antProgram: Address;
+    protected readonly mint: Address;
+    /**
+     * Composed registry instance — the source of truth for the per-user
+     * paginated ACL (ADR-012). Sharing one instance across the read and
+     * write classes keeps program id / commitment / RPC configuration
+     * coherent for both `accessControlList` reads and the maintenance
+     * planner used during writes.
+     */
+    readonly registry: SolanaANTRegistryReadable;
+    constructor(config: {
+        rpc: SolanaRpc;
+        processId: string;
+        commitment?: Commitment;
+        logger?: ILogger;
+        antProgramId?: Address;
+        /**
+         * Pre-built registry to compose. When omitted we build a readable
+         * registry from `rpc` / `commitment` / `antProgramId` so the simple
+         * "just give me an ANT" call path keeps working with a single arg.
+         */
+        registry?: SolanaANTRegistryReadable;
+    });
+    /**
+     * Build a `SolanaANTReadable` whose program id is read from the
+     * asset's `ANT Program` Attributes-plugin entry (ADR-016 / BD-100).
+     *
+     * Falls back to the canonical `ARIO_ANT_PROGRAM_ID` when the asset
+     * has no plugin section, no `ANT Program` trait, or any layer of the
+     * walk fails to decode — matching the on-chain leniency in
+     * `programs/ario-core/src/mpl_core.rs::read_ant_program`. This is the
+     * factory resolution paths should reach for: it does the asset fetch
+     * once, hands the resulting program id to the constructor, and
+     * shares one `SolanaANTRegistryReadable` instance with the new ANT.
+     *
+     * Use the plain constructor when the program id is already known
+     * (e.g. inside a freshly-spawned ANT flow where you've just minted
+     * the asset and know the program you targeted).
+     */
+    static fromAsset(config: {
+        rpc: SolanaRpc;
+        processId: string;
+        commitment?: Commitment;
+        logger?: ILogger;
+    }): Promise<SolanaANTReadable>;
+    private getAccount;
+    private fetchConfig;
+    private fetchControllers;
+    /**
+     * Fetch AntConfig + AntControllers in a single `getMultipleAccounts` round
+     * trip (instead of two single-account reads). Used by `getState` to shave one
+     * RPC per ANT — meaningful when a UI loads many ANTs.
+     */
+    private _fetchConfigAndControllers;
+    getOwner(_opts?: AntReadOptions): Promise<WalletAddress>;
+    /** Get the on-chain schema version of this ANT's config. */
+    getConfigVersion(): Promise<number>;
+    /** Check if this ANT needs a schema migration to the latest version. */
+    needsMigration(): Promise<boolean>;
+    getName(_opts?: AntReadOptions): Promise<string>;
+    getTicker(_opts?: AntReadOptions): Promise<string>;
+    getLogo(_opts?: AntReadOptions): Promise<string>;
+    getControllers(): Promise<WalletAddress[]>;
+    getRecord({ undername }: {
+        undername: string;
+    }, _opts?: AntReadOptions): Promise<ANTRecord | undefined>;
+    getRecords(opts?: AntReadOptions): Promise<SortedANTRecords>;
+    /**
+     * Bulk-load lightweight {@link ANTSummary} state for many ANTs in a handful
+     * of `getMultipleAccounts` calls instead of `N × getState`. For each mint it
+     * batches AntConfig + AntControllers + the apex (`@`) AntRecord — everything a
+     * portfolio/names table needs. Full undername records are NOT loaded here;
+     * fetch them lazily per-ANT via {@link getRecords}/{@link getState} when a
+     * name is opened.
+     *
+     * Requests: ~`ceil(3N / 100)` calls for N mints (10 → 1, 250 → 8), versus
+     * ~`4N` with per-ANT `getState`. Assumes every mint is deployed under this
+     * instance's `antProgram` (true for the standard AR.IO ANT program).
+     *
+     * Mints whose AntConfig doesn't exist are omitted from the result.
+     */
+    getANTSummaries(mints: ReadonlyArray<string>): Promise<Record<string, ANTSummary>>;
+    /**
+     * Bulk-load FULL {@link ANTState} (including all undername records) for many
+     * ANTs in a handful of calls instead of `N × getState`:
+     *   - AntConfig + AntControllers for every mint via `getMultipleAccounts`
+     *     (chunked at 100), and
+     *   - ALL undername records via a SINGLE program-wide `getProgramAccounts`
+     *     scan grouped by mint (offset 8), instead of one mint-filtered scan per
+     *     ANT.
+     *
+     * Requests: ~`ceil(2N / 100) + 1` (+1 when `includeMetadata`) regardless of
+     * N — e.g. 10 ANTs → 2 calls, 250 → ~6 — versus ~`2N` with per-ANT
+     * `getState`. The records scan reads every ANT's records program-wide (cheap
+     * per account, one round trip); prefer per-ANT {@link getState} when you only
+     * need one ANT. Mints with no AntConfig are omitted.
+     */
+    getANTStates(mints: ReadonlyArray<string>, opts?: AntReadOptions): Promise<Record<string, ANTState>>;
+    /**
+     * Group every AntRecord (+ optional metadata) in the program by mint via a
+     * single `getProgramAccounts` scan (the mint sits at offset 8). Used by
+     * {@link getANTStates} to load all ANTs' undername records in one round trip
+     * instead of one mint-filtered scan per ANT.
+     */
+    private _recordsByMint;
+    getBalance({ address: queryAddress }: {
+        address: WalletAddress;
+    }, _opts?: AntReadOptions): Promise<number>;
+    getBalances(_opts?: AntReadOptions): Promise<Record<WalletAddress, number>>;
+    getState(opts?: AntReadOptions): Promise<ANTState>;
+    getInfo(_opts?: AntReadOptions): Promise<ANTInfo>;
+    getHandlers(): Promise<ANTHandler[]>;
+    getModuleId(_opts?: {
+        graphqlUrl?: string;
+        retries?: number;
+    }): Promise<string>;
+    getVersion(_opts?: {
+        antRegistryId?: string;
+        graphqlUrl?: string;
+        retries?: number;
+    }): Promise<string>;
+    isLatestVersion(_opts?: {
+        antRegistryId?: string;
+        graphqlUrl?: string;
+        retries?: number;
+    }): Promise<boolean>;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+/**
+ * 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
+ */
+/**
+ * Solana implementation of the ANT Registry read interface.
+ *
+ * Backed by the per-user paginated ACL (ADR-012): a head `AclConfig` PDA
+ * and N content-addressable `AclPage` PDAs, each holding up to
+ * `MAX_ACL_PAGE_ENTRIES` `(asset, role)` tuples. Frontends can fetch a
+ * user's ANTs in two RPC calls — one `getAccountInfo` for `AclConfig` plus
+ * one `getMultipleAccountsInfo` for every page — instead of a
+ * `getProgramAccounts` scan, a DAS provider, or a foundation-hosted
+ * indexer.
+ *
+ * Usage:
+ * ```ts
+ * import { createSolanaRpc } from '@solana/kit';
+ * import { ANTRegistry } from '@ar.io/sdk';
+ *
+ * const registry = ANTRegistry.init({
+ *   backend: 'solana',
+ *   rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
+ * });
+ *
+ * const { Owned, Controlled } = await registry.accessControlList({
+ *   address: 'SomeSolanaWalletAddress...',
+ * });
+ * ```
+ *
+ * When a user has no on-chain `AclConfig` (never registered / not yet
+ * populated), both lists return empty. The write path (SDK ANT write
+ * methods + migration tooling) is responsible for keeping the ACL in sync
+ * as owners / controllers change.
+ */
+import { type Address, type Commitment } from '@solana/kit';
+import { type ILogger } from '../common/logger.js';
+import type { ANTRegistryRead } from '../types/ant-registry.js';
+import type { SolanaRpc } from './types.js';
+export type SolanaANTRegistryConfig = {
+    rpc: SolanaRpc;
+    commitment?: Commitment;
+    logger?: ILogger;
+    /**
+     * Override the ario-ant program ID. Required against any cluster other
+     * than mainnet — devnet, localnet, and the Surfpool harness all deploy
+     * programs at addresses derived from per-cluster keypair files.
+     */
+    antProgramId?: Address;
+};
+export declare class SolanaANTRegistryReadable implements ANTRegistryRead {
+    protected readonly rpc: SolanaRpc;
+    protected readonly commitment: Commitment;
+    /** Deployed `ario-ant` program id this registry talks to. */
+    readonly antProgram: Address;
+    protected readonly logger: ILogger;
+    constructor(config: SolanaANTRegistryConfig);
+    /**
+     * Read a user's `AclConfig` head plus every `AclPage` and return owned +
+     * controlled ANT mint lists. Returns empty lists if the head PDA does not
+     * exist yet.
+     *
+     * **Note:** This is an eventually-consistent secondary index, not a
+     * canonical source of truth. Marketplace transfers update NFT ownership
+     * on-chain immediately but the ACL is only updated when someone calls
+     * `record_acl_owner` / `remove_acl_owner`. For real-time accuracy on a
+     * specific ANT, check the Metaplex Core asset owner directly.
+     */
+    accessControlList({ address: addr, }: {
+        address: string;
+    }): Promise<{
+        Owned: string[];
+        Controlled: string[];
+    }>;
+    /**
+     * Cleaner alias for `accessControlList` — matches the AO backend so
+     * consumers can switch backends without renaming calls.
+     */
+    getAntsForAddress({ address, }: {
+        address: string;
+    }): Promise<{
+        Owned: string[];
+        Controlled: string[];
+    }>;
+}