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

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

@@ -1,5 +1,20 @@
 /**
- * Solana implementation of AoARIOWrite interface.
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Solana implementation of ARIOWrite interface.
  *
  * Extends SolanaARIOReadable with write operations that build and send
  * Solana transactions via Codama-generated instruction builders.
@@ -20,11 +35,35 @@
  */
 import { type Address, type Instruction } from '@solana/kit';
 import type { ILogger } from '../common/logger.js';
-import type { AoMessageResult, WriteOptions } from '../types/common.js';
-import type { AoArNSPurchaseParams, AoBuyRecordParams, AoCreateVaultParams, AoDelegateStakeParams, AoExtendLeaseParams, AoExtendVaultParams, AoIncreaseUndernameLimitParams, AoIncreaseVaultParams, AoJoinNetworkParams, AoRedelegateStakeParams, AoRevokeVaultParams, AoUpdateGatewaySettingsParams, AoVaultedTransferParams } from '../types/io.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`:
@@ -82,6 +121,102 @@ export declare function buildObservationBitmap(registryAddresses: string[], fail
  *  auditability that the field exists for.
  */
 export declare function encodeReportTxId(reportTxId: string | undefined): Buffer;
+/**
+ * Max `compound_delegation_rewards` instructions packed into one batched tx.
+ * Each is a SEPARATE instruction carrying a gateway + delegation + delegator
+ * account, so — unlike the single-ix `remaining_accounts` lifecycle batch (see
+ * `MAX_LIFECYCLE_BATCH`) and unlike prescribe (which uses an ALT) — the per-item
+ * tx cost is high and there is nothing to compress. Cap low enough that a full
+ * worst-case batch (all-distinct gateways → no account dedup) stays under
+ * Solana's 1232-byte transaction limit. A full batch of 12 overflows it and
+ * wedged epoch progression on staging-V2 (the RPC rejected the tx — observed at
+ * 1928B base64, well over the 1232B raw cap). Exported so the regression test in
+ * `compound-crank.test.ts` asserts this invariant against the live constant.
+ */
+export declare const MAX_COMPOUND_BATCH = 6;
+/** 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;
@@ -109,6 +244,17 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      * (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). */
@@ -118,38 +264,38 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     transfer(params: {
         target: string;
         qty: number | mARIOToken;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
-    vaultedTransfer(params: AoVaultedTransferParams, _options?: WriteOptions): Promise<AoMessageResult>;
-    createVault(params: AoCreateVaultParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _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: AoExtendVaultParams, _options?: WriteOptions): Promise<AoMessageResult>;
-    increaseVault(params: AoIncreaseVaultParams, _options?: WriteOptions): Promise<AoMessageResult>;
-    revokeVault(params: AoRevokeVaultParams, _options?: WriteOptions): Promise<AoMessageResult>;
-    joinNetwork(params: AoJoinNetworkParams, _options?: WriteOptions): Promise<AoMessageResult>;
-    leaveNetwork(_options?: WriteOptions): Promise<AoMessageResult>;
-    updateGatewaySettings(params: AoUpdateGatewaySettingsParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    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<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     decreaseOperatorStake(params: {
         decreaseQty: number | mARIOToken;
         instant?: boolean;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
-    delegateStake(params: AoDelegateStakeParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    delegateStake(params: DelegateStakeParams, _options?: WriteOptions): Promise<MessageResult>;
     decreaseDelegateStake(params: {
         target: string;
         decreaseQty: number | mARIOToken;
         instant?: boolean;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     instantWithdrawal(params: {
         gatewayAddress?: string;
         vaultId: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     cancelWithdrawal(params: {
         gatewayAddress?: string;
         vaultId: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     saveObservations(params: {
         reportTxId: string;
         failedGateways: string[];
@@ -157,9 +303,9 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
         /** Raw 256-byte gateway results bitfield (if provided, overrides failedGateways) */
         gatewayResults?: Uint8Array;
         gatewayCount?: number;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
-    redelegateStake(params: AoRedelegateStakeParams, _options?: WriteOptions): Promise<AoMessageResult>;
-    buyRecord(params: AoBuyRecordParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _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
@@ -197,24 +343,22 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      */
     private _materializeFundingPlan;
     /**
-     * Best-effort cost estimation for `buy_name`. Reads the live DemandFactor
-     * + ArnsConfig and applies the on-chain pricing math. Used by the funding-
-     * plan path so callers don't have to compute cost client-side.
+     * 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 estimate may be 1-2 mARIO higher than the actual on-chain cost when a
-     * demand-factor period rolls during the tx; the on-chain handler reads the
-     * live demand-factor and verifies sum(sources) == cost, so an overestimate
-     * fails fast with `FundingPlanAmountMismatch`. Callers should retry with a
-     * fresh estimate on that error.
+     * The program writes a LE-u64 cost into the transaction's return data;
+     * we parse it from the simulation result.
      */
-    private _estimateBuyNameCost;
+    private _simulateTokenCost;
     private arnsConfigPda;
     private demandFactorPda;
     private nameRegistryPda;
-    upgradeRecord(params: AoArNSPurchaseParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    upgradeRecord(params: ArNSPurchaseParams, _options?: WriteOptions): Promise<MessageResult>;
     syncAttributes(params: {
         name: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Build a `sync_attributes` instruction for `name` IFF the signer is
      * the current MPL Core asset owner. Returns `null` otherwise.
@@ -250,8 +394,8 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     private _buildSyncAttributesIxUnconditional;
     /** Pure builder; no RPC. Used by both gated + unconditional helpers. */
     private _buildSyncAttributesIxFor;
-    extendLease(params: AoExtendLeaseParams, _options?: WriteOptions): Promise<AoMessageResult>;
-    increaseUndernameLimit(params: AoIncreaseUndernameLimitParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    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
@@ -262,22 +406,43 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      */
     private _buildManageStakeIx;
     /**
-     * Cost estimate for manage operations (upgrade / extend / increaseUndername).
-     * Reads the live DemandFactor account + applies the on-chain pricing math.
+     * 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 _estimateManageStakeCost;
+    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 AntRecord.owner for this name" via
-     * PDA-seed-pinned lookup.
+     * 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]
-     *   approve_primary_name:               [arnsRecord, antRecord]
-     *   remove_primary_name_for_base_name:  [arnsRecord, antRecord(@)]
+     *   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
@@ -287,14 +452,17 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      *
      * `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. 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).
+     * 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: AoArNSPurchaseParams, _options?: WriteOptions): Promise<AoMessageResult>;
-    setPrimaryName(params: AoArNSPurchaseParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    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:
@@ -317,40 +485,60 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      *
      * Mirrors the on-chain `approve_primary_name` instruction
      * (`programs/ario-core/src/instructions/primary_name.rs`).
-     * remaining_accounts: [arns_record(base), ant_record(undername | @)].
+     * remaining_accounts: [arns_record(base), ant_record(undername | @), ant_config].
      */
     approvePrimaryName(params: {
         initiator: Address;
         name: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /** Release tokens from an unlocked vault back to the owner. */
     releaseVault(params: {
         vaultId: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /** Close an expired primary name request (permissionless — anyone can call). */
     closeExpiredRequest(params: {
         initiator: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /** Claim tokens from a completed withdrawal (after lock period). */
     claimWithdrawal(params: {
         withdrawalId: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /** Claim delegated stake from a gateway that is leaving the network. */
     claimDelegateFromLeavingGateway(params: {
         gatewayAddress: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _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<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /** Remove an address from the gateway's delegation allowlist. */
     disallowDelegate(params: {
         delegate: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /** Enable or disable the delegation allowlist for the gateway. */
     setAllowlistEnabled(params: {
         enabled: boolean;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Buy a name from the returned name auction (Dutch auction with premium).
      *
@@ -364,21 +552,74 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
         type: 'lease' | 'permabuy';
         years?: number;
         processId: string;
-    } & Partial<AoArNSPurchaseParams>, _options?: WriteOptions): Promise<AoMessageResult>;
+    } & 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<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /** Release a permabuy name back to the registry (creates a returned name auction). */
     releaseName(params: {
         name: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _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<AoMessageResult>;
+    createEpoch(_options?: WriteOptions): Promise<MessageResult>;
     /**
      * Tally weights for a batch of gateways. Permissionless — call repeatedly
      * until all gateways are processed. Pass gateway PDAs as
@@ -387,19 +628,32 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     tallyWeights(params: {
         epochIndex: number;
         gatewayAccounts: Address[];
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Prescribe observers and names for an epoch. Permissionless — call after
-     * weights are tallied. Gateway PDAs are appended as `remaining_accounts`,
-     * and the optional `nameRegistryAccount` (must be last) enables the name
+     * 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<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Distribute rewards for a completed epoch in batches. Permissionless —
      * call after epoch ends. Gateway PDAs appended as `remaining_accounts`.
@@ -407,14 +661,14 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     distributeEpoch(params: {
         epochIndex: number;
         gatewayAccounts: Address[];
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _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<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Get gateway PDAs for a batch starting at registryIndex.
      * Reads the GatewayRegistry and derives PDAs for the next `batchSize`
@@ -423,6 +677,108 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     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.
@@ -433,6 +789,8 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
         weightsTallied: number;
         prescriptionsDone: number;
         rewardsDistributed: number;
+        observationsSubmitted: number;
+        observationsClosed: number;
         activeGatewayCount: number;
         endTimestamp: number;
     } | null>;
@@ -445,10 +803,13 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      *   [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 _pad1]
+     *   [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;
     /**
@@ -461,14 +822,14 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     pruneExpiredNames(params: {
         maxNames: number;
         arnsRecords: string[];
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _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<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Batch-prune expired ReturnedName PDAs (auction window elapsed). Caller
      * supplies the eligible PDAs as `returnedNames`; they're appended as
@@ -477,14 +838,14 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     pruneReturnedNames(params: {
         maxNames: number;
         returnedNames: string[];
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Close a single expired ReservedName PDA. Permissionless after
      * `expires_at`.
      */
     pruneExpiredReservation(params: {
         name: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Slash and remove a deficient gateway (`stats.failed_consecutive >=
      * max_consecutive_failures`). Builds the protected exit vault for the
@@ -496,14 +857,14 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      */
     pruneGateway(params: {
         gateway: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _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<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Reclaim rent from an Observation PDA whose epoch has been distributed.
      * Permissionless. Pass `epochIndex` and the `observer` address used as
@@ -512,7 +873,19 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     closeObservation(params: {
         epochIndex: number;
         observer: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _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).
@@ -521,7 +894,7 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     closeEmptyDelegation(params: {
         gateway: string;
         delegator: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Close a drained Withdrawal PDA (`amount == 0`) and refund rent to the
      * original owner (NOT the caller). Permissionless.
@@ -529,5 +902,5 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     closeDrainedWithdrawal(params: {
         owner: string;
         withdrawalId: number | bigint;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
 }