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

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

@@ -0,0 +1,893 @@
+/**
+ * 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 ARIOWrite interface.
+ *
+ * Extends SolanaARIOReadable with write operations that build and send
+ * Solana transactions via Codama-generated instruction builders.
+ *
+ * All instruction encoding (discriminators, account ordering, Borsh codecs,
+ * default value resolution for token/system programs) is delegated to the
+ * generated builders in `./generated/{core,gar,arns}/instructions/`. The
+ * builders are derived from the on-chain IDL and stay in sync via codegen.
+ *
+ * This file's job is just to:
+ *   1. Translate the AO-style SDK params into the builder's input shape.
+ *   2. Pre-derive the PDAs that the *Async builders can't infer (the ones
+ *      whose seeds depend on runtime state — e.g. the next withdrawal id
+ *      from the on-chain counter, or the buyer's ATA from a runtime mint).
+ *   3. Append remaining_accounts (gateway PDAs, name registry) for the
+ *      epoch crank instructions, since Codama doesn't generate a typed
+ *      surface for them.
+ */
+import { type Address, type Instruction } from '@solana/kit';
+import type { ILogger } from '../common/logger.js';
+import type { MessageResult, WriteOptions } from '../types/common.js';
+import type { ArNSPurchaseParams, BuyRecordParams, CreateVaultParams, DelegateStakeParams, ExtendLeaseParams, ExtendVaultParams, IncreaseUndernameLimitParams, IncreaseVaultParams, JoinNetworkParams, RedelegateStakeParams, RevokeVaultParams, UpdateGatewaySettingsParams, VaultedTransferParams } from '../types/io.js';
+import type { mARIOToken } from '../types/token.js';
+import { deserializeEpochSettingsFull } from './deserialize.js';
+import { SolanaARIOReadable } from './io-readable.js';
+import type { SolanaRpcSubscriptions, SolanaSigner, SolanaWriteConfig } from './types.js';
+/**
+ * Pick the swapped-gateway operator that `finalize_gone` needs as a writable
+ * `remaining_accounts[0]`.
+ *
+ * `finalize_gone` reclaims a gateway's slot from the compact GatewayRegistry by
+ * moving the LAST active slot into it and rewriting that swapped gateway's
+ * stored `registry_index`. When the finalized gateway is NOT already the last
+ * slot, the on-chain handler requires the swapped Gateway PDA (writable) at
+ * `remaining_accounts[0]`; when it IS the last slot, no swap occurs and no
+ * extra account is needed. See
+ * `programs/ario-gar/src/instructions/gateway.rs::finalize_gone`.
+ *
+ * `registryAddresses` MUST be the active registry operator addresses in slot
+ * order (`getRegistryGatewayAddresses()` — length === on-chain
+ * `registry.count`), so `registryAddresses[length - 1]` is exactly the
+ * `registry.gateways[count - 1].address` the on-chain swap reads.
+ *
+ * @returns the swapped gateway's operator address, or `null` when the finalized
+ *   gateway already occupies the last slot.
+ * @throws if `registryIndex` is outside the active registry count (mirrors the
+ *   on-chain `index < registry.count` guard, surfacing a stale index early).
+ */
+export declare function selectFinalizeGoneSwapOperator(registryIndex: number, registryAddresses: string[]): string | null;
+/**
+ * Split a primary name into its undername + base parts using the same rule
+ * as the on-chain `splitn(2, '_')` in `programs/ario-core/src/instructions/primary_name.rs`:
+ * everything before the first '_' is the undername, the rest is the base.
+ *
+ * Exposed as a top-level helper so it can be unit-tested without spinning up
+ * an `SolanaARIOWriteable`. Lowercases the input to match contract behavior.
+ */
+export declare function splitPrimaryName(name: string): {
+    isUndername: boolean;
+    baseName: string;
+    undername: string | null;
+};
+/**
+ * Solana-backed read-write client for the AR.IO protocol.
+ *
+ * Usage:
+ * ```ts
+ * import {
+ *   createSolanaRpc,
+ *   createSolanaRpcSubscriptions,
+ *   generateKeyPairSigner,
+ * } from '@solana/kit';
+ * import { SolanaARIOWriteable } from '@ar.io/sdk/solana';
+ *
+ * const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+ * const rpcSubscriptions = createSolanaRpcSubscriptions('wss://api.mainnet-beta.solana.com');
+ * const signer = await generateKeyPairSigner();
+ * const ario = new SolanaARIOWriteable({ rpc, rpcSubscriptions, signer });
+ *
+ * await ario.transfer({ target: 'RecipientPubkey...', qty: 100_000_000 });
+ * ```
+ */
+/** Build the gateway_results bitmap for save_observations.
+ *  All bits start as 1 (pass) for the first `registryAddresses.length`
+ *  positions; positions named in `failedGateways` get cleared to 0; all
+ *  positions beyond `registryAddresses.length` are 0. */
+export declare function buildObservationBitmap(registryAddresses: string[], failedGateways: string[]): Buffer;
+/** Encode an Arweave TX ID into the on-chain `[u8; 32]` slot.
+ *
+ *  An Arweave TX ID **is** a 32-byte SHA-256 hash; the 43-char base64url
+ *  string is just its presentation encoding. We decode here so the
+ *  on-chain bytes are the raw hash — lossless and trivially reversible
+ *  via base64url-encode on the consumer side. Without this, on-chain
+ *  bytes alone couldn't be used to look up the original report bundle
+ *  on permaweb (the whole point of recording the txid for auditability).
+ *
+ *  Empty / undefined input → 32 zero bytes ("no permaweb archive
+ *  configured for this submission" — the report still lives off-chain
+ *  in the observer's local sinks but isn't anchored on Arweave).
+ *
+ *  Throws on malformed input: the base64url string must be exactly 43
+ *  chars and decode to 32 bytes. Strict validation here is desirable —
+ *  silently truncating or accepting bad input would erode the
+ *  auditability that the field exists for.
+ */
+export declare function encodeReportTxId(reportTxId: string | undefined): Buffer;
+/** The single on-chain action a {@link SolanaARIOWriteable.crankEpochStep} call performed. */
+export type CrankAction = 'create' | 'tally' | 'prescribe' | 'distribute' | 'compound' | 'update_demand_factor' | 'prune_returned_names' | 'close_observation' | 'close' | 'idle';
+/** Options for {@link SolanaARIOWriteable.crankEpochStep}. */
+export interface CrankEpochStepOptions {
+    /** Gateways per tally/distribute batch. Default 30. */
+    batchSize?: number;
+    /**
+     * NameRegistry account for the name-prescription leg. Defaults to the
+     * registry derived from the configured ArNS program. Pass `null` to disable
+     * name prescription entirely.
+     */
+    nameRegistryAccount?: Address | null;
+    /** Close fully-distributed epochs older than `epochRetention`. Default true. */
+    enableClose?: boolean;
+    /** Epochs of retention before an epoch may be closed (GAR-006). Default 7. */
+    epochRetention?: number;
+    /**
+     * Compound pending delegate rewards (settle the reward-per-share accumulator
+     * into delegated stake) once the live epoch is fully distributed, so the next
+     * epoch's tally weights the compounded stake. Default true. The delegate
+     * rewards are correct in the accumulator regardless — this only materializes
+     * them on-chain. Each step compounds one batch; runs only in the otherwise-
+     * idle tail (never during tally/distribute).
+     */
+    enableCompound?: boolean;
+    /**
+     * Skip compounding delegations whose pending reward is at/below this (mARIO).
+     * Avoids dust compounds that only advance `reward_debt`. Default 0.
+     */
+    compoundMinPendingRewards?: number;
+    /**
+     * Roll the demand factor forward when its (wall-clock) period has elapsed.
+     * Idempotent — only sends a tx when the stored period is behind. Pricing is
+     * always lazily correct without this; it keeps the STORED factor (and reads
+     * between buys) current. Default true. Runs only in the idle tail.
+     */
+    enableDemandFactorRoll?: boolean;
+    /**
+     * Prune expired ReturnedName PDAs (auction window elapsed) as part of the
+     * crank. Default true. Runs whenever the epoch lifecycle is otherwise idle
+     * (the live observation window AND the post-distribution tail), one batch per
+     * step. It scans the ReturnedName PDAs DIRECTLY (via getExpiredReturnedNames)
+     * and does NOT consult `config.next_returned_names_prune_timestamp` — that
+     * hint is only set for on-chain returns and is never updated for imported
+     * returned names, so trusting it strands imported auctions forever.
+     */
+    enablePrune?: boolean;
+    /** ReturnedName PDAs to prune per tx (u8, max 255). Default 15. */
+    pruneBatchSize?: number;
+    /**
+     * Minimum wall-clock gap between returned-name prune SCANS (ms). The scan is a
+     * `getProgramAccounts` over ReturnedName PDAs, so this throttles it below the
+     * crank poll rate. Default 60_000 (1 min). Set 0 to scan every step (tests).
+     */
+    pruneScanIntervalMs?: number;
+    /** Unix seconds; defaults to the wall clock. Injectable for testing. */
+    now?: number;
+}
+/** Result of a single {@link SolanaARIOWriteable.crankEpochStep} call. */
+export interface CrankEpochStepResult {
+    /** The action performed (or `'idle'` when nothing was due). */
+    action: CrankAction;
+    /** The epoch the action targeted (absent for `'idle'`). */
+    epochIndex?: number;
+    /** Confirmed transaction signature, when an action was submitted. */
+    txId?: string;
+    /** Batch progress for `'tally'` / `'distribute'`. */
+    progress?: {
+        index: number;
+        total: number;
+    };
+    /** For `action: 'idle'`, why nothing was done. */
+    reason?: 'epochs_disabled' | 'waiting_for_genesis' | 'waiting_for_epoch' | 'waiting_for_observations' | 'epoch_complete';
+}
+/**
+ * Detect the GAR `InvalidGatewayAccount` error by Anchor error name/message
+ * (walking the cause chain + `context.logs`), NOT by numeric code — codes are
+ * `6000 + enum-index` and shift across program versions, but the name and
+ * message are stable. `prescribe_epoch` raises this when a supplied observer
+ * Gateway PDA is missing/spoofed (e.g. a predicted observer left the registry
+ * between prediction and tx landing).
+ */
+export declare function isInvalidGatewayAccountError(error: unknown): boolean;
+export declare class SolanaARIOWriteable extends SolanaARIOReadable {
+    protected readonly signer: SolanaSigner;
+    protected readonly rpcSubscriptions: SolanaRpcSubscriptions;
+    constructor(config: SolanaWriteConfig & {
+        logger?: ILogger;
+        coreProgramId?: Address;
+        garProgramId?: Address;
+        arnsProgramId?: Address;
+        antProgramId?: Address;
+    });
+    /** The signer's on-chain address. */
+    protected get signerAddress(): Address;
+    protected sendTransaction(instructions: Instruction[], computeUnitLimit?: number): Promise<string>;
+    /** Helper to get the ARIO mint and treasury from ArioConfig */
+    private getCoreConfig;
+    private getMint;
+    /** Helper to get ArNS config fields (mint and treasury) */
+    private getArnsConfig;
+    /** Helper to get GAR config fields (mint, stake pool, protocol pool) */
+    private getGarConfig;
+    /**
+     * Inject ARNS default PDAs (config, demandFactor, nameRegistry).
+     *
+     * Extra fields not consumed by a given builder are harmlessly ignored
+     * (codama only reads the named keys from `input`).
+     */
+    private withArnsDefaults;
+    /**
+     * If the on-chain ArnsRecord for `name` hasn't been migrated to the
+     * current schema (name_hash at offset 8 doesn't match the expected
+     * hash), return a `migrate_arns_record` instruction that must be
+     * prepended to any operation referencing the record with PDA seed
+     * verification.
+     *
+     * Returns an empty array when the record is already up-to-date or
+     * doesn't exist.
+     */
+    private _buildMigrateArnsRecordIxIfNeeded;
+    /** Inject ARIO core default PDAs (config). */
+    private withCoreDefaults;
+    /** Inject GAR default PDAs (settings, epochSettings, registry). */
+    private withGarDefaults;
+    /** Read WithdrawalCounter's next_id (returns 0n if not yet created) */
+    private getNextWithdrawalId;
+    transfer(params: {
+        target: string;
+        qty: number | mARIOToken;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    vaultedTransfer(params: VaultedTransferParams, _options?: WriteOptions): Promise<MessageResult>;
+    createVault(params: CreateVaultParams, _options?: WriteOptions): Promise<MessageResult>;
+    /** Read VaultCounter's next_id (returns 0n if not yet created). */
+    private getNextVaultId;
+    extendVault(params: ExtendVaultParams, _options?: WriteOptions): Promise<MessageResult>;
+    increaseVault(params: IncreaseVaultParams, _options?: WriteOptions): Promise<MessageResult>;
+    revokeVault(params: RevokeVaultParams, _options?: WriteOptions): Promise<MessageResult>;
+    joinNetwork(params: JoinNetworkParams, _options?: WriteOptions): Promise<MessageResult>;
+    leaveNetwork(_options?: WriteOptions): Promise<MessageResult>;
+    updateGatewaySettings(params: UpdateGatewaySettingsParams, _options?: WriteOptions): Promise<MessageResult>;
+    increaseOperatorStake(params: {
+        increaseQty: number | mARIOToken;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    decreaseOperatorStake(params: {
+        decreaseQty: number | mARIOToken;
+        instant?: boolean;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    delegateStake(params: DelegateStakeParams, _options?: WriteOptions): Promise<MessageResult>;
+    decreaseDelegateStake(params: {
+        target: string;
+        decreaseQty: number | mARIOToken;
+        instant?: boolean;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    instantWithdrawal(params: {
+        gatewayAddress?: string;
+        vaultId: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    cancelWithdrawal(params: {
+        gatewayAddress?: string;
+        vaultId: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    saveObservations(params: {
+        reportTxId: string;
+        failedGateways: string[];
+        epochIndex?: number;
+        /** Raw 256-byte gateway results bitfield (if provided, overrides failedGateways) */
+        gatewayResults?: Uint8Array;
+        gatewayCount?: number;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    redelegateStake(params: RedelegateStakeParams, _options?: WriteOptions): Promise<MessageResult>;
+    buyRecord(params: BuyRecordParams, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Resolve a `FundingPlan` for a fee-paying ArNS ix. When `params.sources`
+     * is set, use it verbatim (caller-supplied plan); otherwise discover the
+     * user's sources and build a plan via the Lua-faithful planner.
+     *
+     * Throws `InsufficientFundingError` (as a thrown Error with the structured
+     * payload as `cause`) when no plan covers `amountNeeded`.
+     */
+    private _resolveFundingPlan;
+    /**
+     * Build a `buy_name_from_funding_plan` ix using the funding-plan module.
+     * Resolves per-source PDAs (Delegation, Withdrawal) and the residue-vault
+     * PDA prediction in one shot.
+     */
+    private _buildBuyNameFromFundingPlanIx;
+    /**
+     * For an explicit caller-supplied plan, detect which Delegation sources
+     * will trigger an on-chain residue auto-vault. Reads each (Delegation,
+     * Gateway) pair in parallel; computes post-drain; flags `(0, min)`.
+     *
+     * Hard-fails on RPC error or missing PDA — silently skipping would let
+     * the on-chain handler reject the tx with `MissingResidueVault` and
+     * burn fees. The error message points at remediation.
+     */
+    private _detectResidueIndexes;
+    /**
+     * Materialize a `FundingPlan` into the on-chain ix's per-source remaining
+     * accounts, residue-vault PDAs, and the withdrawal_counter slot. Shared
+     * across all 5 ArNS funding-plan ix dispatches and the 2 ario-core
+     * primary-name funding-plan dispatches.
+     *
+     * Throws when the plan has Withdrawal sources whose ids cannot be
+     * resolved from either `spec.withdrawalId` (preferred) or
+     * `params.withdrawalId` (single-withdrawal back-compat).
+     */
+    private _materializeFundingPlan;
+    /**
+     * Simulate the on-chain `get_token_cost` instruction and return the exact
+     * cost as a `bigint` (mARIO). This guarantees byte-exact agreement with the
+     * on-chain pricing math, avoiding integer-division rounding divergences
+     * that plagued the previous client-side reimplementation.
+     *
+     * The program writes a LE-u64 cost into the transaction's return data;
+     * we parse it from the simulation result.
+     */
+    private _simulateTokenCost;
+    private arnsConfigPda;
+    private demandFactorPda;
+    private nameRegistryPda;
+    upgradeRecord(params: ArNSPurchaseParams, _options?: WriteOptions): Promise<MessageResult>;
+    syncAttributes(params: {
+        name: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Build a `sync_attributes` instruction for `name` IFF the signer is
+     * the current MPL Core asset owner. Returns `null` otherwise.
+     *
+     * Sprint 4 / ADR-016: bundle helper for `buyRecord`, `upgradeRecord`,
+     * `increaseUndernameLimit`, `reassignName`, and `buyReturnedName`.
+     * Returning `null` lets the caller send the arns ix alone — preserves
+     * BD-095 (non-holder ArNS lease management) and BD-096 (deferred
+     * trait sync for non-holder buyers). The actual ANT owner reconciles
+     * state later via the public `syncAttributes()`.
+     *
+     * `extendLease` is NOT a caller of this helper — extend_lease changes
+     * only `end_timestamp`, which isn't mirrored in any Attributes-plugin
+     * trait (BD-095 last row). `releaseName` is also excluded — release_name
+     * closes the ArnsRecord PDA, so a follow-up `sync_attributes` would
+     * fail the PDA-existence check.
+     *
+     * `assetOverride` MUST be set when the bundling ix mutates
+     * `record.ant` mid-tx (i.e. `reassign_name`). The on-chain record
+     * still points at the OLD asset at SDK build time, so without the
+     * override the bundled sync would target the wrong asset and fail
+     * the post-reassign `record.ant == asset.key()` check. The owner
+     * check runs against the supplied asset (= new ANT for reassign),
+     * matching the pre-reshape "new owner reconciles later" semantic.
+     */
+    private _buildSyncAttributesIxIfOwner;
+    /**
+     * Build a `sync_attributes` instruction unconditionally (no owner
+     * check). Used by the public `syncAttributes()` method, where the
+     * caller is asking explicitly — if they aren't the owner the chain
+     * returns NotNftHolder.
+     */
+    private _buildSyncAttributesIxUnconditional;
+    /** Pure builder; no RPC. Used by both gated + unconditional helpers. */
+    private _buildSyncAttributesIxFor;
+    extendLease(params: ExtendLeaseParams, _options?: WriteOptions): Promise<MessageResult>;
+    increaseUndernameLimit(params: IncreaseUndernameLimitParams, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Shared dispatch helper for the 3 manage variants (upgrade / extend /
+     * increaseUndername). They share the same account shape per the
+     * `manage_from_delegation_accounts!` / `manage_from_operator_stake_accounts!`
+     * macros in `programs/ario-arns/src/instructions/manage_from_stake.rs`.
+     * Only the operation-specific extra args differ (years for extend,
+     * quantity for increaseUndername).
+     */
+    private _buildManageStakeIx;
+    /**
+     * If the signer already has a primary name set, build the instruction(s)
+     * needed to remove it so they can be prepended to a request/set tx —
+     * enabling single-tx "change primary name" flows.
+     *
+     * Returns an empty array when the signer has no existing primary name.
+     *
+     * Throws when the signer has a legacy primary-name state (forward
+     * `PrimaryName` PDA exists but its paired `PrimaryNameReverse` PDA does
+     * NOT). Both `remove_primary_name` AND `request_and_set_primary_name`
+     * require the reverse PDA on-chain — the latter rejects with
+     * `MustRemoveExistingPrimaryName` (0x1786, code 6022) any time a
+     * forward record already exists for the signer, regardless of reverse
+     * state. Silently skipping the remove would queue a tx guaranteed to
+     * fail with that opaque error. Surfacing it at the client with a clear
+     * remediation pointer is the only safe behavior.
+     *
+     * The legacy state should not exist on any cluster post-snapshot/import
+     * PR #159 (which emits PrimaryNameReverse in lockstep with PrimaryName)
+     * — it's a relic of pre-#159 imports. Operators on affected clusters
+     * must run `yarn workspace @ar-io/migration-import backfill:primary-name-reverse`
+     * (in the solana-ar-io repo) before this method can succeed.
+     */
+    private _buildRemoveExistingPrimaryNameIxs;
+    /**
+     * Build the `remaining_accounts` slice + the `antProgramId` arg the
+     * four ario-core primary-name instructions consume. Sprint 2/5
+     * reshape (ADR-016): ario-core no longer reads MPL Core asset bytes.
+     * Authorization is "caller is the effective AntRecord owner for this
+     * name", resolved from the `AntRecord` + `AntConfig` PDAs (freshness-
+     * gated against `AntConfig.last_known_owner` — see ario-core BD-097 /
+     * BD-109). Both are program-PDA-pinned lookups.
+     *
+     * Layouts the on-chain handlers expect:
+     *   request_primary_name:               [arnsRecord, demandFactor]
+     *   request_and_set_primary_name:       [arnsRecord, demandFactor, antRecord, antConfig]
+     *   approve_primary_name:               [arnsRecord, antRecord, antConfig]
+     *   remove_primary_name_for_base_name:  [arnsRecord, antRecord(@), antConfig]
+     *
+     * `antRecord` keys off the undername part for undernames (e.g.
+     * "blog_arweave" → AntRecord at "blog") or the canonical "@" sentinel
+     * for base names. `removeForBaseName` is special — it always uses "@"
+     * regardless of whether the primary name being removed is an undername,
+     * since the *base* name owner is the one revoking it.
+     *
+     * `antProgram` honors ADR-016 / BD-100 pluggability: the asset's
+     * `ANT Program` Attributes-plugin trait selects which program owns the
+     * AntRecord PDA. Absent / unparseable → canonical fallback. The detected
+     * trait is untrusted asset/RPC data, so it is honored only when it matches
+     * the canonical program or this client's explicitly-configured
+     * `this.antProgram`; any other value falls back to the configured program
+     * (see the SECURITY note in the body). Both the PDA derivation here and the
+     * `ant_program_id` arg the caller passes to the on-chain ix MUST agree (the
+     * handler re-derives and rejects mismatches).
+     */
+    private _buildPrimaryNameValidationAccounts;
+    requestPrimaryName(params: ArNSPurchaseParams, _options?: WriteOptions): Promise<MessageResult>;
+    setPrimaryName(params: ArNSPurchaseParams, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Build a `request_primary_name_from_funding_plan` or
+     * `request_and_set_primary_name_from_funding_plan` ix. Forwards both:
+     *   - validation accounts (ArnsRecord + DemandFactor [+ ant_asset
+     *     [+ AntRecord]]) — passed via remaining_accounts at indices
+     *     [0..validation_account_count)
+     *   - per-source PDAs from the funding plan — passed at indices
+     *     [validation_account_count..)
+     *
+     * The on-chain handler (programs/ario-core/src/instructions/primary_name.rs)
+     * splits remaining_accounts at `validation_account_count` and forwards the
+     * funding-source slice to ario-gar's pay_from_funding_plan via CPI.
+     */
+    private _buildPrimaryNameFromFundingPlanIx;
+    private _coreConfigPda;
+    /**
+     * Approve a previously-created primary name request. The signer must be
+     * the AntRecord.owner for the requested name (undername part for
+     * undernames, "@" for base names) — Sprint 2 / ADR-016 reshape.
+     *
+     * Mirrors the on-chain `approve_primary_name` instruction
+     * (`programs/ario-core/src/instructions/primary_name.rs`).
+     * remaining_accounts: [arns_record(base), ant_record(undername | @), ant_config].
+     */
+    approvePrimaryName(params: {
+        initiator: Address;
+        name: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /** Release tokens from an unlocked vault back to the owner. */
+    releaseVault(params: {
+        vaultId: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /** Close an expired primary name request (permissionless — anyone can call). */
+    closeExpiredRequest(params: {
+        initiator: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /** Claim tokens from a completed withdrawal (after lock period). */
+    claimWithdrawal(params: {
+        withdrawalId: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /** Claim delegated stake from a gateway that is leaving the network. */
+    claimDelegateFromLeavingGateway(params: {
+        gatewayAddress: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Claim a delegate's stake out of a gateway that has DISABLED delegation
+     * (`allow_delegated_staking == false`), moving it into the delegate's own
+     * withdrawal vault (WP §6.3 / Fix #6). This is the disabled-gateway analog of
+     * {@link claimDelegateFromLeavingGateway}: the on-chain instruction is
+     * permissionless, so a cranker can sweep delegates out (the operator cannot
+     * re-enable delegation until `total_delegated_stake == 0` and the cooldown
+     * elapses). The withdrawal-counter and withdrawal PDAs are seeded by the
+     * DELEGATOR, so a cranker must pass that delegate's `delegatorAddress`.
+     *
+     * @param params.gatewayAddress  The gateway whose delegation was disabled.
+     * @param params.delegatorAddress  The delegate to claim for. Defaults to the
+     *   signer (self-claim). Pass another address to crank on a delegate's behalf;
+     *   the signer covers rent (`payer`) but stake still routes to the delegate's
+     *   own vault (the delegator key is bound by the delegation PDA seeds).
+     */
+    claimDelegateFromDisabledGateway(params: {
+        gatewayAddress: string;
+        delegatorAddress?: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /** Add an address to the gateway's delegation allowlist. */
+    allowDelegate(params: {
+        delegate: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /** Remove an address from the gateway's delegation allowlist. */
+    disallowDelegate(params: {
+        delegate: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /** Enable or disable the delegation allowlist for the gateway. */
+    setAllowlistEnabled(params: {
+        enabled: boolean;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Buy a name from the returned name auction (Dutch auction with premium).
+     *
+     * Phase 4: now dispatches on `params.fundFrom`. Note that for
+     * `buyReturnedName`, only the protocol share funds from the chosen source;
+     * the initiator share is always a direct buyer-ATA → initiator-ATA SPL
+     * transfer (matches the on-chain `_from_*` variant behavior).
+     */
+    buyReturnedName(params: {
+        name: string;
+        type: 'lease' | 'permabuy';
+        years?: number;
+        processId: string;
+    } & Partial<ArNSPurchaseParams>, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Pick a single stake-derived funding source that can cover a returned-name
+     * purchase, for the single-source `buy_returned_name_from_*` paths.
+     *
+     * Returned-name prices decay per slot, so the multi-source funding plan
+     * (which pre-commits exact amounts) can't match the execution-time cost. The
+     * single-source paths carry no amount — the program draws the live cost — so
+     * we only need to pick ONE source with enough stake. We size the pick against
+     * the premium-inclusive estimate (an upper bound, since the price only falls
+     * from now) and choose the largest matching source. Returns `null` when no
+     * single source covers the estimate.
+     */
+    private _autoPickReturnedNameStakeSource;
+    /** Reassign an ArNS name to a different ANT. */
+    reassignName(params: {
+        name: string;
+        processId: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /** Release a permabuy name back to the registry (creates a returned name auction). */
+    releaseName(params: {
+        name: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Roll the demand factor forward to the current period. Permissionless and
+     * idempotent — a no-op within the same period. Pricing already rolls the
+     * factor inline on every buy/extend, so this only refreshes the STORED
+     * factor that `getDemandFactor` and between-buy price previews read; a
+     * periodic crank (~once per 24h `PERIOD_LENGTH_SECONDS`) keeps it current.
+     */
+    updateDemandFactor(_options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Materialize a single delegate's pending rewards into their delegated
+     * stake by settling the gateway's reward-per-share accumulator.
+     * Permissionless — there is no signer beyond the fee payer; `delegator` is
+     * only a PDA-derivation seed. Rewards always accrue correctly in the
+     * accumulator regardless of this call; compounding makes the on-chain
+     * `delegatedStake` reflect them (and earn compound interest in the next
+     * epoch's weighting). Idempotent — a no-op once already settled.
+     */
+    compoundDelegationRewards(params: {
+        gateway: string;
+        delegator: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Compound many delegates' rewards in a SINGLE transaction — one
+     * `compound_delegation_rewards` instruction per entry. Idempotent and
+     * permissionless, so partial batches are safe to retry. Keep each batch
+     * within the per-tx account/CU budget; grouping entries that share a gateway
+     * lowers the unique-account count (the gateway account is reused across
+     * instructions). Typical cranker usage: enumerate with
+     * `SolanaARIOReadable.getDelegationsToCompound`, chunk, then call this.
+     */
+    compoundDelegationRewardsBatch(delegations: Array<{
+        gateway: string;
+        delegator: string;
+    }>, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Build a single `compound_delegation_rewards` instruction (shared by the
+     * single + batch methods). PDAs are derived under the configured gar program
+     * so the program-id override always targets the right cluster.
+     */
+    private buildCompoundDelegationRewardsInstruction;
+    /**
+     * Create a new epoch. Permissionless — anyone can call when the next
+     * epoch's start time has arrived.
+     */
+    createEpoch(_options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Tally weights for a batch of gateways. Permissionless — call repeatedly
+     * until all gateways are processed. Pass gateway PDAs as
+     * `gatewayAccounts`; they're appended as `remaining_accounts`.
+     */
+    tallyWeights(params: {
+        epochIndex: number;
+        gatewayAccounts: Address[];
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Prescribe observers and names for an epoch. Permissionless — call after
+     * weights are tallied.
+     *
+     * `gatewayAccounts` MUST be the Gateway PDAs of the SELECTED observers only
+     * — at most `epoch_settings.prescribed_observer_count` (≤50), NOT the whole
+     * registry. The selection is computed on-chain; mirror it off-chain with
+     * {@link predictPrescribedObservers} / {@link getPredictedObserverPDAs} to
+     * learn the set. Passing every registry gateway (e.g. via
+     * {@link getAllRegistryGatewayPDAs}) hits Solana's `MAX_TX_ACCOUNT_LOCKS = 64`
+     * on large registries and the tx fails at pre-flight.
+     *
+     * The selected PDAs are appended as `remaining_accounts`, followed by the
+     * optional `nameRegistryAccount` (must be LAST) which enables the name
+     * prescription leg.
+     *
+     * If a selected gateway leaves between prediction and tx landing, the tx
+     * fails with `InvalidGatewayAccount` — retry once with a fresh prediction.
+     */
+    prescribeEpoch(params: {
+        epochIndex: number;
+        gatewayAccounts: Address[];
+        /** Optional NameRegistry account — pass to enable name prescription */
+        nameRegistryAccount?: Address;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Distribute rewards for a completed epoch in batches. Permissionless —
+     * call after epoch ends. Gateway PDAs appended as `remaining_accounts`.
+     */
+    distributeEpoch(params: {
+        epochIndex: number;
+        gatewayAccounts: Address[];
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Close an old epoch account and reclaim rent. Permissionless — call after
+     * the epoch is distributed and at least 7 epochs have passed.
+     */
+    closeEpoch(params: {
+        epochIndex: number;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Get gateway PDAs for a batch starting at registryIndex.
+     * Reads the GatewayRegistry and derives PDAs for the next `batchSize`
+     * active gateways.
+     */
+    getRegistryGatewayPDAs(startIndex: number, batchSize: number): Promise<Address[]>;
+    /** Get ALL active gateway PDAs from the registry. */
+    getAllRegistryGatewayPDAs(): Promise<Address[]>;
+    /**
+     * Predict the Gateway PDAs that `prescribe_epoch` will select as observers
+     * for `epochIndex`, mirroring the on-chain weighted-roulette selection.
+     *
+     * Returns at most `epoch_settings.prescribed_observer_count` (≤50) PDAs
+     * regardless of registry size — the set to pass as `gatewayAccounts` to
+     * {@link prescribeEpoch}. This is the size-safe replacement for
+     * {@link getAllRegistryGatewayPDAs} on the prescribe path (which oversupplies
+     * and trips `MAX_TX_ACCOUNT_LOCKS = 64` on large registries).
+     *
+     * Reads three accounts (epoch, registry, epoch settings) at the configured
+     * commitment so the prediction reflects live registry weights. If a selected
+     * gateway races out before the tx lands, `prescribeEpoch` throws
+     * `InvalidGatewayAccount` — re-call this and retry once.
+     */
+    getPredictedObserverPDAs(epochIndex: number): Promise<Address[]>;
+    /**
+     * Reclaim rent from the ephemeral Address Lookup Tables this signer created
+     * for `prescribe_epoch` (see {@link sendWithEphemeralLookupTable}). Each
+     * prescribe leaves a single-use table allocated (~0.0126 SOL); reclaiming
+     * needs a deactivate → ~513-slot cooldown → close sequence, so it can't run
+     * inline. Call this from a throttled/permissionless cleanup pass (cranker /
+     * observer) to deactivate active tables and close cooled-down ones, refunding
+     * the rent to the signer.
+     *
+     * Discovery reads the signer's transaction history (RPC-portable; the ALT
+     * program can't be enumerated via `getProgramAccounts`). The GAR + ArNS
+     * program IDs are passed as the entry-ownership fingerprint so only genuine
+     * prescribe tables are touched. Best-effort: at most `maxTables` submissions
+     * per call, scanning at most `scanLimit` recent signatures.
+     */
+    reclaimLookupTableRent(opts?: {
+        maxTables?: number;
+        scanLimit?: number;
+    }): Promise<{
+        deactivated: number;
+        closed: number;
+        candidates: number;
+        scannedSignatures: number;
+    }>;
+    /** Read and deserialize the full EpochSettings account. */
+    getEpochSettingsFull(): Promise<ReturnType<typeof deserializeEpochSettingsFull>>;
+    /**
+     * Submit `prescribe_epoch` using the off-chain-predicted observer set, with a
+     * single re-predict-and-retry on `InvalidGatewayAccount` (covers a gateway
+     * leaving the registry between the prediction read and the tx landing).
+     */
+    protected prescribeWithPrediction(epochIndex: number, nameRegistryAccount?: Address): Promise<MessageResult>;
+    /**
+     * Advance the epoch lifecycle by ONE on-chain action and return what it did.
+     *
+     * Stateless and idempotent: it reads `EpochSettings` + the current `Epoch`,
+     * determines the single next required step
+     * (`create` → `tally` → `prescribe` → `distribute` → `close`), submits it,
+     * and returns a {@link CrankEpochStepResult}. Call it repeatedly on your own
+     * schedule — it owns *which* on-chain action is correct and *which accounts*
+     * it needs; you own scheduling, logging, error classification, and any
+     * permissionless cleanup.
+     *
+     * Crucially, the `prescribe` leg uses {@link getPredictedObserverPDAs} (only
+     * the ~`prescribed_observer_count` selected Gateway PDAs), so it never trips
+     * `MAX_TX_ACCOUNT_LOCKS = 64` on large registries — and it re-predicts and
+     * retries once on `InvalidGatewayAccount`.
+     *
+     * Errors propagate to the caller (classify/retry as you see fit); the only
+     * internally-handled error is the prescribe `InvalidGatewayAccount` retry.
+     */
+    crankEpochStep(opts?: CrankEpochStepOptions): Promise<CrankEpochStepResult>;
+    /**
+     * One compound batch over delegations with pending rewards (≤
+     * {@link MAX_COMPOUND_BATCH} per tx), or `null` when none are due. Settling
+     * is idempotent, so this converges over a few crank steps then no-ops until
+     * the next epoch's distribution advances the accumulator again.
+     */
+    private maybeCompoundStep;
+    /**
+     * Roll the demand factor forward if its (wall-clock) period elapsed since the
+     * last stored roll, else `null`. Mirrors the on-chain period math; the roll
+     * itself is idempotent.
+     */
+    private maybeRollDemandFactorStep;
+    /** Wall-clock (ms) of the last returned-name prune scan; throttles the
+     *  getProgramAccounts scan below the crank poll rate. */
+    private lastReturnedNamePruneScanMs;
+    /**
+     * One prune batch over ReturnedName PDAs whose 14-day auction window has
+     * elapsed (≤ {@link CrankEpochStepOptions.pruneBatchSize} per tx), or `null`
+     * when none are due / the scan is throttled. Scans the PDAs directly — it does
+     * NOT gate on `config.next_returned_names_prune_timestamp`, which is never set
+     * for imported returned names and would strand them. The contract re-checks
+     * each account's window, so a slightly-skewed client clock is safe.
+     */
+    private maybePruneReturnedNamesStep;
+    /**
+     * The DemandFactor account's stored period + period-zero start (seconds) —
+     * the gate for {@link maybeRollDemandFactorStep}. `null` if the account
+     * doesn't exist (pre-genesis).
+     */
+    getDemandFactorPeriodState(): Promise<{
+        currentPeriod: number;
+        periodZeroStartTimestamp: number;
+    } | null>;
+    /**
+     * Read the raw epoch account data for cranker state inspection.
+     * Returns null if the epoch account doesn't exist yet.
+     */
+    getEpochRaw(epochIndex: number): Promise<{
+        tallyIndex: number;
+        distributionIndex: number;
+        weightsTallied: number;
+        prescriptionsDone: number;
+        rewardsDistributed: number;
+        observationsSubmitted: number;
+        observationsClosed: number;
+        activeGatewayCount: number;
+        endTimestamp: number;
+    } | null>;
+    /**
+     * Parse raw epoch account data for cranker-relevant fields.
+     * Offsets match the Rust Epoch zero-copy struct (repr(C)).
+     *
+     * Layout after 8-byte discriminator:
+     *   [8 epoch_index][8 start_ts][8 end_ts][8 total_eligible][8 per_gw]
+     *   [8 per_obs][8 reward_rate][8 weight_lo][8 weight_hi][32 hashchain]
+     *   [4 active_gw_count][4 dist_idx][4 tally_idx]
+     *   [1 observer_count][1 name_count][1 obs_submitted][1 rewards_dist]
+     *   [1 weights_tallied][1 prescriptions_done][1 bump][1 obs_closed]
+     *   [6000 failure_counts][1600 prescribed_observers]
+     *   [1600 prescribed_observer_gateways][64 prescribed_names]
+     *   [7 has_observed][5 _pad2]
+     *
+     * NOTE: byte +123 is `observations_closed` (NOT padding) — `close_epoch`
+     * reverts with EpochObservationsNotClosed until it equals obs_submitted.
+     */
+    private fetchEpochRawFields;
+    /**
+     * Batch-prune expired ArnsRecord PDAs from the NameRegistry. The caller
+     * supplies the eligible records as `arnsRecords` — they're appended as
+     * `remaining_accounts` and the on-chain handler verifies each is past
+     * `end_timestamp + grace_period + return_auction_duration` before closing.
+     * `maxNames` caps the per-tx work (u8). Submit in batches of ~10-15.
+     */
+    pruneExpiredNames(params: {
+        maxNames: number;
+        arnsRecords: string[];
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Convert a single expired-but-not-yet-returned lease into a `ReturnedName`
+     * (kicks off the Dutch auction). Permissionless.
+     */
+    pruneNameToReturned(params: {
+        name: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Batch-prune expired ReturnedName PDAs (auction window elapsed). Caller
+     * supplies the eligible PDAs as `returnedNames`; they're appended as
+     * `remaining_accounts`. `maxNames` caps per-tx work (u8).
+     */
+    pruneReturnedNames(params: {
+        maxNames: number;
+        returnedNames: string[];
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Close a single expired ReservedName PDA. Permissionless after
+     * `expires_at`.
+     */
+    pruneExpiredReservation(params: {
+        name: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Slash and remove a deficient gateway (`stats.failed_consecutive >=
+     * max_consecutive_failures`). Builds the protected exit vault for the
+     * post-slash min portion plus the optional excess vault for any surplus.
+     * The contract's `excess_withdrawal: Option<UncheckedAccount>` slot is
+     * always passed (PDA derived from `next_id + 1`); the handler consumes
+     * it only when the post-slash stake exceeds `min_operator_stake`.
+     * Permissionless.
+     */
+    pruneGateway(params: {
+        gateway: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * GC a `Leaving`/`Gone` gateway whose leave window has fully elapsed.
+     * Closes the Gateway PDA and refunds rent to the caller. Permissionless.
+     */
+    finalizeGone(params: {
+        gateway: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Reclaim rent from an Observation PDA whose epoch has been distributed.
+     * Permissionless. Pass `epochIndex` and the `observer` address used as
+     * the Observation seed.
+     */
+    closeObservation(params: {
+        epochIndex: number;
+        observer: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Close multiple Observation PDAs for one epoch in a single tx (each
+     * `close_observation` increments the parent Epoch's `observations_closed`).
+     * Permissionless; rent is refunded to the payer. Used by the crank to satisfy
+     * `close_epoch`'s `observations_closed == observations_submitted` precondition
+     * before closing a retention-aged epoch. Keep the batch small — each ix carries
+     * the Epoch + Observation + payer + system accounts.
+     */
+    closeObservations(params: {
+        epochIndex: number;
+        observers: string[];
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Close an empty Delegation PDA (`amount == 0`) and refund rent to the
+     * original delegator (NOT the caller — see GAR-016, prevents griefing).
+     * Permissionless.
+     */
+    closeEmptyDelegation(params: {
+        gateway: string;
+        delegator: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Close a drained Withdrawal PDA (`amount == 0`) and refund rent to the
+     * original owner (NOT the caller). Permissionless.
+     */
+    closeDrainedWithdrawal(params: {
+        owner: string;
+        withdrawalId: number | bigint;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+}