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

package/lib/esm/solana/io-writeable.js

@@ -0,0 +1,3196 @@
+/**
+ * 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 { AccountRole, address, appendTransactionMessageInstructions, compileTransaction, createTransactionMessage, fetchEncodedAccount, getAddressDecoder, getBase64EncodedWireTransaction, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, } from '@solana/kit';
+import { CostIntent, PurchaseType, getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getGetTokenCostInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getMigrateArnsRecordInstruction, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpdateDemandFactorInstruction, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from '@ar.io/solana-contracts/arns';
+import { FundingSourceKind as GeneratedFundingSourceKindEnum } from '@ar.io/solana-contracts/gar';
+import { buildCreateAtaIdempotentIx, getAssociatedTokenAddressKit, } from './ata.js';
+import { deserializeArnsRecord, deserializeDemandFactor, deserializeEpochSettingsFull, deserializePrimaryName, } from './deserialize.js';
+import { buildFundingPlan as buildFundingPlanCore, buildFundingPlanRemainingAccounts, computeResidueIndexes, predictResidueVaults, } from './funding-plan.js';
+/** Maps the SDK's user-facing FundingSourceKind string union to the
+ *  Codama-generated enum used by the on-chain ix payload. */
+function toGeneratedFundingSourceSpec(s) {
+    const kindMap = {
+        balance: GeneratedFundingSourceKindEnum.Balance,
+        delegation: GeneratedFundingSourceKindEnum.Delegation,
+        operatorStake: GeneratedFundingSourceKindEnum.OperatorStake,
+        withdrawal: GeneratedFundingSourceKindEnum.Withdrawal,
+    };
+    return { kind: kindMap[s.kind], amount: s.amount };
+}
+import { getSyncAttributesInstruction } from '@ar.io/solana-contracts/ant';
+import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRemovePrimaryNameInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestAndSetPrimaryNameInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
+import { getDelegationDecoder, getGatewayDecoder, } from '@ar.io/solana-contracts/gar';
+import { Protocol, getAllowDelegateInstructionAsync, getCancelWithdrawalInstruction, getClaimDelegateFromDisabledGatewayInstructionAsync, getClaimDelegateFromLeavingGatewayInstructionAsync, getClaimWithdrawalInstructionAsync, getCloseDrainedWithdrawalInstruction, getCloseEmptyDelegationInstruction, getCloseEpochInstructionAsync, getCloseObservationInstructionAsync, getCompoundDelegationRewardsInstruction, getCreateEpochInstructionAsync, getDecreaseDelegateStakeInstructionAsync, getDecreaseOperatorStakeInstructionAsync, getDelegateStakeInstructionAsync, getDisallowDelegateInstructionAsync, getDistributeEpochInstructionAsync, getFinalizeGoneInstructionAsync, getIncreaseOperatorStakeInstructionAsync, getInstantWithdrawalInstructionAsync, getJoinNetworkInstructionAsync, getLeaveNetworkInstructionAsync, getPrescribeEpochInstructionAsync, getPruneGatewayInstructionAsync, getRedelegateStakeInstructionAsync, getSaveObservationsInstructionAsync, getSetAllowlistEnabledInstructionAsync, getTallyWeightsInstructionAsync, getUpdateGatewaySettingsInstructionAsync, getUpdateObserverAddressInstructionAsync, } from '@ar.io/solana-contracts/gar';
+import { getTransferCheckedInstruction } from '@solana-program/token';
+import { ARIO_ANT_PROGRAM_ID, TOKEN_DECIMALS } from './constants.js';
+import { SolanaARIOReadable } from './io-readable.js';
+import { getAntConfigPDA, getAntRecordPDA, getArioConfigPDA, getArnsRecordPDA, getArnsRegistryPDA, getArnsSettingsPDA, getDelegationPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getObservationPDA, getObserverLookupPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getPrimaryNameReversePDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, getWithdrawalCounterPDA, getWithdrawalPDA, hashName, } from './pda.js';
+import { predictPrescribedObservers, } from './predict-prescribed-observers.js';
+import { reclaimLookupTablesForSigner, sendAndConfirm, sendWithEphemeralLookupTable, } from './send.js';
+const addressDecoder = getAddressDecoder();
+/** Resolve mARIOToken | number to a plain number */
+function toAmount(qty) {
+    if (typeof qty === 'number')
+        return qty;
+    return qty.valueOf();
+}
+/**
+ * Append additional `AccountMeta`s to a Codama-generated instruction.
+ *
+ * The generated `getXInstruction[Async]` builders return frozen objects with
+ * a typed, fixed `accounts` tuple. The Solana program accepts extra
+ * `remaining_accounts` for epoch crank ops (gateway PDAs, name registry) and
+ * for primary-name authorization (arnsRecord, demandFactor, antRecord — see
+ * `_buildPrimaryNameValidationAccounts`), but
+ * Codama has no typed surface for them — so we splice them in here.
+ */
+function withRemainingAccounts(ix, remaining) {
+    const accounts = [
+        ...(ix.accounts ?? []),
+        ...remaining,
+    ];
+    return { ...ix, accounts };
+}
+/**
+ * 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 function selectFinalizeGoneSwapOperator(registryIndex, registryAddresses) {
+    if (registryIndex < 0 || registryIndex >= registryAddresses.length) {
+        throw new Error(`finalizeGone: registry index ${registryIndex} is outside the active ` +
+            `registry count ${registryAddresses.length}`);
+    }
+    const lastIndex = registryAddresses.length - 1;
+    return registryIndex === lastIndex ? null : registryAddresses[lastIndex];
+}
+/**
+ * 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 function splitPrimaryName(name) {
+    const lower = name.toLowerCase();
+    const ix = lower.indexOf('_');
+    if (ix === -1) {
+        return { isUndername: false, baseName: lower, undername: null };
+    }
+    return {
+        isUndername: true,
+        baseName: lower.slice(ix + 1),
+        undername: lower.slice(0, ix),
+    };
+}
+/**
+ * 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 });
+ * ```
+ */
+// =========================================================================
+// save_observations encoding helpers
+// =========================================================================
+// Extracted as pure functions so the bitmap-pack + base64url-decode logic
+// can be unit-tested without standing up the rpc/signer plumbing of the
+// SolanaARIOWriteable class. The on-chain ABI:
+//   - gateway_results: [u8; 375]   bit i = 1 (pass) / 0 (fail) for the
+//                                  gateway at registry index i.
+//   - gateway_count:   u16         must equal epoch.active_gateway_count.
+//   - report_tx_id:    [u8; 32]    raw 32-byte Arweave hash (base64url
+//                                  decoded from its 43-char string form).
+/** 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 function buildObservationBitmap(registryAddresses, failedGateways) {
+    const buf = Buffer.alloc(375, 0xff);
+    const failedSet = new Set(failedGateways);
+    for (let i = 0; i < registryAddresses.length; i++) {
+        if (failedSet.has(registryAddresses[i])) {
+            buf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+        }
+    }
+    // Clear bits beyond the active gateway count so the bitmap is exactly
+    // the prescribed shape (1s only at indices < gatewayCount that passed).
+    for (let i = registryAddresses.length; i < 3000; i++) {
+        buf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+    }
+    return buf;
+}
+/** 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 function encodeReportTxId(reportTxId) {
+    const out = Buffer.alloc(32);
+    if (reportTxId === undefined || reportTxId === '') {
+        return out;
+    }
+    // base64url → base64. The 43-char Arweave form has no padding; add it
+    // back so Node's `Buffer.from(_, 'base64')` accepts the input.
+    const padded = reportTxId
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(reportTxId.length / 4) * 4, '=');
+    // Reject non-base64url chars up front — `Buffer.from` silently
+    // tolerates them, which would mask typos.
+    if (!/^[A-Za-z0-9+/=]+$/.test(padded)) {
+        throw new Error(`reportTxId contains non-base64url characters: "${reportTxId}". ` +
+            `Expected a 43-char Arweave TX ID using A-Z, a-z, 0-9, -, _.`);
+    }
+    const decoded = Buffer.from(padded, 'base64');
+    if (decoded.length !== 32) {
+        throw new Error(`reportTxId must be a 43-char base64url Arweave TX ID decoding to 32 bytes; ` +
+            `got ${reportTxId.length} chars decoding to ${decoded.length} bytes.`);
+    }
+    decoded.copy(out);
+    return out;
+}
+/**
+ * Max `compound_delegation_rewards` instructions packed into one batched tx.
+ * Each carries a gateway + delegation + delegator account; 12 stays well within
+ * the per-tx account/1232-byte budget even when none share a gateway.
+ */
+const MAX_COMPOUND_BATCH = 12;
+/** Observation PDAs closed per tx before close_epoch (each ix carries Epoch +
+ *  Observation + payer + system accounts — keep well under the tx account cap). */
+const MAX_CLOSE_OBSERVATION_BATCH = 8;
+/** Demand-factor period length (seconds) — mirrors `PERIOD_LENGTH_SECONDS` in ario-arns. */
+const DEMAND_FACTOR_PERIOD_SECONDS = 86_400;
+/**
+ * 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 function isInvalidGatewayAccountError(error) {
+    const parts = [];
+    let cur = error;
+    for (let i = 0; cur != null && i < 8; i++) {
+        const e = cur;
+        if (e.message)
+            parts.push(e.message);
+        if (Array.isArray(e.context?.logs))
+            parts.push(e.context.logs.join('\n'));
+        cur = e.cause;
+    }
+    const text = parts.join('\n');
+    return (text.includes('InvalidGatewayAccount') ||
+        text.includes('Invalid gateway account'));
+}
+export class SolanaARIOWriteable extends SolanaARIOReadable {
+    signer;
+    rpcSubscriptions;
+    constructor(config) {
+        super(config);
+        this.signer = config.signer;
+        this.rpcSubscriptions = config.rpcSubscriptions;
+    }
+    /** The signer's on-chain address. */
+    get signerAddress() {
+        return this.signer.address;
+    }
+    async sendTransaction(instructions, computeUnitLimit = 400_000) {
+        return sendAndConfirm({
+            rpc: this.rpc,
+            rpcSubscriptions: this.rpcSubscriptions,
+            signer: this.signer,
+            instructions,
+            commitment: this.commitment,
+            computeUnitLimit,
+        });
+    }
+    /** Helper to get the ARIO mint and treasury from ArioConfig */
+    async getCoreConfig() {
+        const [configPda] = await getArioConfigPDA(this.coreProgram);
+        const account = await fetchEncodedAccount(this.rpc, configPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            throw new Error('ArioConfig not found');
+        const data = Buffer.from(account.data);
+        // ArioConfig: [8 disc][32 authority][32 mint][32 arns_program][32 treasury]
+        const mint = addressDecoder.decode(data.subarray(40, 72));
+        const treasury = addressDecoder.decode(data.subarray(104, 136));
+        return { mint, treasury };
+    }
+    async getMint() {
+        return (await this.getCoreConfig()).mint;
+    }
+    /** Helper to get ArNS config fields (mint and treasury) */
+    async getArnsConfig() {
+        const [settingsPda] = await getArnsSettingsPDA(this.arnsProgram);
+        const account = await fetchEncodedAccount(this.rpc, settingsPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            throw new Error('ArnsConfig not found');
+        const data = Buffer.from(account.data);
+        // ArnsConfig layout: [8 disc][32 authority][32 mint][32 treasury]...
+        const mint = addressDecoder.decode(data.subarray(40, 72));
+        const treasury = addressDecoder.decode(data.subarray(72, 104));
+        return { mint, treasury };
+    }
+    /** Helper to get GAR config fields (mint, stake pool, protocol pool) */
+    async getGarConfig() {
+        const [settingsPda] = await getGarSettingsPDA(this.garProgram);
+        const account = await fetchEncodedAccount(this.rpc, settingsPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            throw new Error('GarSettings not found');
+        const data = Buffer.from(account.data);
+        // GarSettings: [8 disc][32 authority][32 mint][8+8+8+8+8+8=48 u64s][4 u32][1 bool]
+        //   [32 migration_authority][32 stake_token_account][32 protocol_token_account][1 bump]
+        const mint = addressDecoder.decode(data.subarray(40, 72));
+        const stakeTokenAccount = addressDecoder.decode(data.subarray(157, 189));
+        const protocolTokenAccount = addressDecoder.decode(data.subarray(189, 221));
+        return { mint, stakeTokenAccount, protocolTokenAccount };
+    }
+    // =========================================
+    // Codama default-PDA injection helpers
+    // =========================================
+    //
+    // Codama's auto-generated `getXInstructionAsync` builders fall back to
+    // calling `find<Account>Pda()` (no args) when a "defaultable" account is
+    // omitted from the input. Those `find*Pda` helpers default to the
+    // **placeholder** program addresses baked into the generated client
+    // (`ARioArnsProgXXX...`, `ArioCoreProgXXX...`, etc.), *not* the env- or
+    // constructor-overridden program ID we actually deploy at. The result is a
+    // PDA derived against the wrong program id, which on-chain shows up as
+    // Anchor `AccountNotInitialized` (#3012) for `config` / `demand_factor` /
+    // `name_registry` / `settings` / etc.
+    //
+    // The wrappers below pre-derive each program's defaultable PDAs against
+    // the **real** program id and merge them into the input so codama never
+    // touches its placeholder defaults. Caller-provided values still win
+    // because spread order is `(...defaults, ...input)`.
+    /**
+     * 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`).
+     */
+    async withArnsDefaults(input) {
+        const [config] = await getArnsSettingsPDA(this.arnsProgram);
+        const [demandFactor] = await getDemandFactorPDA(this.arnsProgram);
+        const [nameRegistry] = await getArnsRegistryPDA(this.arnsProgram);
+        return { config, demandFactor, nameRegistry, ...input };
+    }
+    /**
+     * 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.
+     */
+    async _buildMigrateArnsRecordIxIfNeeded(name) {
+        const [arnsRecordPda] = await getArnsRecordPDA(name, this.arnsProgram);
+        const account = await fetchEncodedAccount(this.rpc, arnsRecordPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return [];
+        const data = Buffer.from(account.data);
+        const expectedHash = hashName(name);
+        const storedHash = data.subarray(8, 40);
+        if (storedHash.equals(expectedHash))
+            return [];
+        return [
+            getMigrateArnsRecordInstruction({
+                record: arnsRecordPda,
+                payer: this.signer,
+            }, { programAddress: this.arnsProgram }),
+        ];
+    }
+    /** Inject ARIO core default PDAs (config). */
+    async withCoreDefaults(input) {
+        const [config] = await getArioConfigPDA(this.coreProgram);
+        return { config, ...input };
+    }
+    /** Inject GAR default PDAs (settings, epochSettings, registry). */
+    async withGarDefaults(input) {
+        const [settings] = await getGarSettingsPDA(this.garProgram);
+        const [epochSettings] = await getEpochSettingsPDA(this.garProgram);
+        const [registry] = await getGatewayRegistryPDA(this.garProgram);
+        return { settings, epochSettings, registry, ...input };
+    }
+    /** Read WithdrawalCounter's next_id (returns 0n if not yet created) */
+    async getNextWithdrawalId(owner) {
+        const [counterPda] = await getWithdrawalCounterPDA(owner, this.garProgram);
+        const account = await fetchEncodedAccount(this.rpc, counterPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return 0n;
+        // WithdrawalCounter: [8 disc][32 owner][8 next_id]
+        return Buffer.from(account.data).readBigUInt64LE(40);
+    }
+    // =========================================
+    // Token operations (ario-core)
+    // =========================================
+    async transfer(params, _options) {
+        const amount = toAmount(params.qty);
+        const recipient = address(params.target);
+        const mint = await this.getMint();
+        const fromATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const toATA = await getAssociatedTokenAddressKit(mint, recipient);
+        // SPL `transferChecked` requires the recipient ATA to exist; bundle
+        // an idempotent ATA-create so fresh recipients just work. Same
+        // pattern as `vaultedTransfer` below.
+        const createToAtaIx = buildCreateAtaIdempotentIx(this.signer.address, toATA, recipient, mint);
+        // Standard SPL Token `transferChecked`. The custom `ario-core::transfer`
+        // ix is deprecated — it added no protocol-level accounting, just wrapped
+        // this same CPI plus a `TransferEvent` emission that no major Solana
+        // indexer needs (Helius, Solscan, etc. all track SPL transfers natively).
+        // See `docs/REMOVE_CUSTOM_TRANSFER_PLAN.md` in `ar-io/solana-ar-io`.
+        // `transferChecked` (vs `transfer`) validates the mint + decimals
+        // on-chain, preventing cross-mint mistakes.
+        const ix = getTransferCheckedInstruction({
+            source: fromATA,
+            mint,
+            destination: toATA,
+            authority: this.signer,
+            amount,
+            decimals: TOKEN_DECIMALS,
+        });
+        const sig = await this.sendTransaction([createToAtaIx, ix]);
+        return { id: sig };
+    }
+    async vaultedTransfer(params, _options) {
+        const amount = toAmount(params.quantity);
+        const lockSeconds = Math.floor(params.lockLengthMs / 1000);
+        const recipient = address(params.recipient);
+        const mint = await this.getMint();
+        // Vault PDA depends on the recipient's *current* vault counter id, which
+        // the codegen builder can't infer — derive it manually.
+        const nextId = await this.getNextVaultId(recipient);
+        const [vaultPda] = await getVaultPDA(recipient, nextId, this.coreProgram);
+        const senderATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const ix = await getVaultedTransferInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            senderTokenAccount: senderATA,
+            vaultTokenAccount: vaultATA,
+            recipient,
+            sender: this.signer,
+            amount,
+            lockDurationSeconds: lockSeconds,
+            revocable: params.revokable ?? false,
+        }), { programAddress: this.coreProgram });
+        // The on-chain CreateVault / VaultedTransfer constraint is
+        // `Account<TokenAccount>` (NOT `init`) — Anchor expects the vault ATA to
+        // already exist. Bundle an idempotent CreateAssociatedTokenAccount in
+        // the same tx so the caller doesn't need a separate setup step.
+        const createVaultAtaIx = buildCreateAtaIdempotentIx(this.signer.address, vaultATA, vaultPda, mint);
+        const sig = await this.sendTransaction([createVaultAtaIx, ix]);
+        return { id: sig };
+    }
+    async createVault(params, _options) {
+        const amount = toAmount(params.quantity);
+        const lockSeconds = Math.floor(params.lockLengthMs / 1000);
+        const mint = await this.getMint();
+        const nextId = await this.getNextVaultId(this.signer.address);
+        const [vaultPda] = await getVaultPDA(this.signer.address, nextId, this.coreProgram);
+        const ownerATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const ix = await getCreateVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            ownerTokenAccount: ownerATA,
+            vaultTokenAccount: vaultATA,
+            owner: this.signer,
+            amount,
+            lockDurationSeconds: lockSeconds,
+        }), { programAddress: this.coreProgram });
+        // See note in vaultedTransfer above — vault ATA is not init'd by the
+        // on-chain handler; bundle the create.
+        const createVaultAtaIx = buildCreateAtaIdempotentIx(this.signer.address, vaultATA, vaultPda, mint);
+        const sig = await this.sendTransaction([createVaultAtaIx, ix]);
+        return { id: sig };
+    }
+    /** Read VaultCounter's next_id (returns 0n if not yet created). */
+    async getNextVaultId(owner) {
+        // VaultCounter PDA derivation lives in pda.ts as getVaultCounterPDA.
+        const { getVaultCounterPDA } = await import('./pda.js');
+        const [counterPda] = await getVaultCounterPDA(owner, this.coreProgram);
+        const account = await fetchEncodedAccount(this.rpc, counterPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return 0n;
+        return Buffer.from(account.data).readBigUInt64LE(40);
+    }
+    async extendVault(params, _options) {
+        const additionalSeconds = Math.floor(params.extendLengthMs / 1000);
+        const [vaultPda] = await getVaultPDA(this.signer.address, BigInt(params.vaultId), this.coreProgram);
+        const ix = await getExtendVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            owner: this.signer,
+            additionalSeconds,
+        }), { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async increaseVault(params, _options) {
+        const amount = toAmount(params.quantity);
+        const mint = await this.getMint();
+        const [vaultPda] = await getVaultPDA(this.signer.address, BigInt(params.vaultId), this.coreProgram);
+        const ownerATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const ix = await getIncreaseVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            ownerTokenAccount: ownerATA,
+            vaultTokenAccount: vaultATA,
+            owner: this.signer,
+            amount,
+        }), { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async revokeVault(params, _options) {
+        const recipient = address(params.recipient);
+        const mint = await this.getMint();
+        const [vaultPda] = await getVaultPDA(recipient, BigInt(params.vaultId), this.coreProgram);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const controllerATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const ix = await getRevokeVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            vaultTokenAccount: vaultATA,
+            controllerTokenAccount: controllerATA,
+            controller: this.signer,
+        }), { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Gateway operations (ario-gar)
+    // =========================================
+    async joinNetwork(params, _options) {
+        const garConfig = await this.getGarConfig();
+        const operatorATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const observerAddress = params.observerAddress
+            ? address(params.observerAddress)
+            : this.signer.address;
+        const [observerLookupPda] = await getObserverLookupPDA(observerAddress, this.garProgram);
+        const ix = await getJoinNetworkInstructionAsync(await this.withGarDefaults({
+            operatorTokenAccount: operatorATA,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            observerLookup: observerLookupPda,
+            operator: this.signer,
+            operatorStake: BigInt(params.operatorStake),
+            label: params.label ?? '',
+            fqdn: params.fqdn ?? '',
+            port: params.port ?? 443,
+            protocol: Protocol.Https,
+            properties: params.properties ?? null,
+            note: params.note ?? null,
+            allowDelegatedStaking: params.allowDelegatedStaking === true ||
+                params.allowDelegatedStaking === 'allowlist',
+            delegateRewardShareRatio: params.delegateRewardShareRatio ?? 0,
+            minDelegateStake: params.minDelegatedStake !== undefined
+                ? BigInt(params.minDelegatedStake)
+                : null,
+            observerAddress,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async leaveNetwork(_options) {
+        // BD-102: leave_network may produce 1 or 2 Withdrawal PDAs. The
+        // protected exit vault uses `next_id`; the optional excess vault
+        // uses `next_id + 1`. The SDK always derives both PDAs and passes
+        // them to the codama-emitted builder — the contract's
+        // `Option<UncheckedAccount>` excess slot is consumed only when the
+        // post-stake excess is positive. Passing it unconditionally keeps
+        // the SDK side stateless (no need to fetch gateway.operator_stake +
+        // settings.min_operator_stake to decide).
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [exitVaultPda] = await getWithdrawalPDA(this.signer.address, nextId, this.garProgram);
+        const [excessVaultPda] = await getWithdrawalPDA(this.signer.address, nextId + 1n, this.garProgram);
+        const ix = await getLeaveNetworkInstructionAsync(await this.withGarDefaults({
+            withdrawal: exitVaultPda,
+            excessWithdrawal: excessVaultPda,
+            operator: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async updateGatewaySettings(params, _options) {
+        const ixs = [];
+        // Settings fields (label, fqdn, port, etc.) — only emit when at least one
+        // non-observer field is provided so we don't send a no-op instruction.
+        const { observerAddress: _observer, ...settingsFields } = params;
+        if (Object.keys(settingsFields).length > 0) {
+            const settingsIx = await getUpdateGatewaySettingsInstructionAsync(await this.withGarDefaults({
+                operator: this.signer,
+                label: params.label ?? null,
+                fqdn: params.fqdn ?? null,
+                port: params.port ?? null,
+                // Codama exposes `protocol` as Option<Protocol>. We only ever updated
+                // the URL parts above, so leave protocol untouched (None).
+                protocol: null,
+                properties: params.properties ?? null,
+                note: params.note ?? null,
+                allowDelegatedStaking: typeof params.allowDelegatedStaking === 'boolean'
+                    ? params.allowDelegatedStaking
+                    : null,
+                delegateRewardShareRatio: params.delegateRewardShareRatio ?? null,
+                minDelegateStake: params.minDelegatedStake !== undefined
+                    ? BigInt(params.minDelegatedStake)
+                    : null,
+            }), { programAddress: this.garProgram });
+            ixs.push(settingsIx);
+        }
+        // Observer address update — uses a separate on-chain instruction that
+        // swaps the observer lookup PDA from old → new.
+        if (params.observerAddress !== undefined) {
+            const newObserver = address(params.observerAddress);
+            const gateway = await this.getGateway({
+                address: this.signer.address,
+            });
+            const oldObserver = address(gateway.observerAddress);
+            const [oldObserverLookupPda] = await getObserverLookupPDA(oldObserver, this.garProgram);
+            const [newObserverLookupPda] = await getObserverLookupPDA(newObserver, this.garProgram);
+            const observerIx = await getUpdateObserverAddressInstructionAsync(await this.withGarDefaults({
+                operator: this.signer,
+                oldObserverLookup: oldObserverLookupPda,
+                newObserverLookup: newObserverLookupPda,
+                newObserver,
+            }), { programAddress: this.garProgram });
+            ixs.push(observerIx);
+        }
+        const sig = await this.sendTransaction(ixs, 1_000_000);
+        return { id: sig };
+    }
+    async increaseOperatorStake(params, _options) {
+        const amount = toAmount(params.increaseQty);
+        const garConfig = await this.getGarConfig();
+        const operatorATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getIncreaseOperatorStakeInstructionAsync(await this.withGarDefaults({
+            operatorTokenAccount: operatorATA,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            operator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async decreaseOperatorStake(params, _options) {
+        const amount = toAmount(params.decreaseQty);
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, nextId, this.garProgram);
+        const ix = await getDecreaseOperatorStakeInstructionAsync(await this.withGarDefaults({
+            withdrawal: withdrawalPda,
+            operator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async delegateStake(params, _options) {
+        const amount = toAmount(params.stakeQty);
+        const target = address(params.target);
+        const garConfig = await this.getGarConfig();
+        const [gatewayPda] = await getGatewayPDA(target, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(target, this.signer.address, this.garProgram);
+        const delegatorATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getDelegateStakeInstructionAsync(await this.withGarDefaults({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            delegatorTokenAccount: delegatorATA,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            delegator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async decreaseDelegateStake(params, _options) {
+        const amount = toAmount(params.decreaseQty);
+        const target = address(params.target);
+        const [gatewayPda] = await getGatewayPDA(target, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(target, this.signer.address, this.garProgram);
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, nextId, this.garProgram);
+        const ix = await getDecreaseDelegateStakeInstructionAsync(await this.withGarDefaults({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            withdrawal: withdrawalPda,
+            delegator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        if (!params.instant) {
+            return { id: sig };
+        }
+        // Instant boolean on decrease delegated stake (vs protected exit vault) is not currently supported by the contract — Instead we call InstantWithdrawal after creating the withdrawal, which achieves the same effect but requires two transactions. The protected exit vault is still created in the first transaction, but will be empty and can be ignored when instant = true.
+        await this.instantWithdrawal({ vaultId: nextId.toString() }, _options);
+        return { id: sig };
+    }
+    async instantWithdrawal(params, _options) {
+        const garConfig = await this.getGarConfig();
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, BigInt(params.vaultId), this.garProgram);
+        const ownerATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getInstantWithdrawalInstructionAsync(await this.withGarDefaults({
+            withdrawal: withdrawalPda,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            ownerTokenAccount: ownerATA,
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            owner: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async cancelWithdrawal(params, _options) {
+        const gateway = params.gatewayAddress
+            ? address(params.gatewayAddress)
+            : this.signer.address;
+        const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, BigInt(params.vaultId), this.garProgram);
+        const isDelegate = gateway !== this.signer.address;
+        const delegation = isDelegate
+            ? (await getDelegationPDA(gateway, this.signer.address, this.garProgram))[0]
+            : undefined;
+        const [settingsPda] = await getGarSettingsPDA(this.garProgram);
+        const ix = getCancelWithdrawalInstruction({
+            settings: settingsPda,
+            gateway: gatewayPda,
+            withdrawal: withdrawalPda,
+            delegation,
+            owner: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async saveObservations(params, _options) {
+        let epochIndex;
+        if (params.epochIndex !== undefined) {
+            epochIndex = params.epochIndex;
+        }
+        else {
+            const [settingsPda] = await getEpochSettingsPDA(this.garProgram);
+            const settingsAccount = await fetchEncodedAccount(this.rpc, settingsPda, {
+                commitment: this.commitment,
+            });
+            if (!settingsAccount.exists)
+                throw new Error('EpochSettings not found');
+            const settings = deserializeEpochSettingsFull(Buffer.from(settingsAccount.data));
+            epochIndex = settings.currentEpochIndex;
+        }
+        // Build the [u8; 375] gateway_results bitfield. On-chain convention:
+        //   bit set (1) = passed, bit clear (0) = failed.
+        let resultsBuf;
+        let gatewayCount;
+        if (params.gatewayResults) {
+            resultsBuf = Buffer.alloc(375);
+            resultsBuf.set(params.gatewayResults.subarray(0, 375));
+            gatewayCount = params.gatewayCount ?? 0;
+        }
+        else {
+            const registryAddresses = await this.getRegistryGatewayAddresses();
+            gatewayCount = registryAddresses.length;
+            resultsBuf = buildObservationBitmap(registryAddresses, params.failedGateways);
+        }
+        const reportTxId = encodeReportTxId(params.reportTxId);
+        const ix = await getSaveObservationsInstructionAsync({
+            observer: this.signer,
+            epochIndex: BigInt(epochIndex),
+            gatewayResults: new Uint8Array(resultsBuf),
+            gatewayCount,
+            reportTxId: new Uint8Array(reportTxId),
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async redelegateStake(params, _options) {
+        const amount = toAmount(params.stakeQty);
+        const source = address(params.source);
+        const target = address(params.target);
+        const garConfig = await this.getGarConfig();
+        const [sourceGatewayPda] = await getGatewayPDA(source, this.garProgram);
+        const [targetGatewayPda] = await getGatewayPDA(target, this.garProgram);
+        const [sourceDelegationPda] = await getDelegationPDA(source, this.signer.address, this.garProgram);
+        const [targetDelegationPda] = await getDelegationPDA(target, this.signer.address, this.garProgram);
+        const delegatorATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getRedelegateStakeInstructionAsync(await this.withGarDefaults({
+            sourceGateway: sourceGatewayPda,
+            targetGateway: targetGatewayPda,
+            sourceDelegation: sourceDelegationPda,
+            targetDelegation: targetDelegationPda,
+            delegatorTokenAccount: delegatorATA,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            delegator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
+    // ArNS operations (ario-arns)
+    // =========================================
+    async buyRecord(params, _options) {
+        const arnsConfig = await this.getArnsConfig();
+        const buyerATA = await getAssociatedTokenAddressKit(arnsConfig.mint, this.signer.address);
+        const antPubkey = address(params.processId ?? '11111111111111111111111111111111');
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const [reservedNameCheck] = await getReservedNamePDA(params.name, this.arnsProgram);
+        const [returnedNameCheck] = await getReturnedNamePDA(params.name, this.arnsProgram);
+        const buyNameParams = {
+            name: params.name,
+            purchaseType: params.type === 'permabuy' ? PurchaseType.Permabuy : PurchaseType.Lease,
+            years: params.years ?? 1,
+            ant: antPubkey,
+        };
+        // Phase 4 of FUND_FROM_PLAN.md: dispatch on params.fundFrom. The pre-Phase-4
+        // path always fell through to the balance-funded `buyName` ix even when
+        // CLI-set `--fund-from stakes`; we now route to the corresponding on-chain
+        // wrapper for each mode.
+        let ix;
+        if (params.fundFrom === 'stakes' && params.gatewayAddress) {
+            const gatewayAddr = address(params.gatewayAddress);
+            const garConfig = await this.getGarConfig();
+            const [garSettings] = await getGarSettingsPDA(this.garProgram);
+            const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+            const baseShared = {
+                config: await this.arnsConfigPda(),
+                demandFactor: await this.demandFactorPda(),
+                arnsRecord,
+                nameRegistry: await this.nameRegistryPda(),
+                reservedNameCheck,
+                returnedNameCheck,
+                garSettings,
+                gateway: gatewayPda,
+                stakeTokenAccount: garConfig.stakeTokenAccount,
+                protocolTokenAccount: arnsConfig.treasury,
+                buyer: this.signer,
+                garProgram: this.garProgram,
+                params: buyNameParams,
+            };
+            if (params.fundAsOperator) {
+                ix = await getBuyNameFromOperatorStakeInstructionAsync(baseShared, {
+                    programAddress: this.arnsProgram,
+                });
+            }
+            else {
+                const [delegationPda] = await getDelegationPDA(gatewayAddr, this.signer.address, this.garProgram);
+                ix = await getBuyNameFromDelegationInstructionAsync({ ...baseShared, delegation: delegationPda }, { programAddress: this.arnsProgram });
+            }
+        }
+        else if (params.fundFrom === 'withdrawal' &&
+            params.withdrawalId !== undefined) {
+            const garConfig = await this.getGarConfig();
+            const [garSettings] = await getGarSettingsPDA(this.garProgram);
+            const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, params.withdrawalId, this.garProgram);
+            ix = await getBuyNameFromWithdrawalInstructionAsync({
+                config: await this.arnsConfigPda(),
+                demandFactor: await this.demandFactorPda(),
+                arnsRecord,
+                nameRegistry: await this.nameRegistryPda(),
+                reservedNameCheck,
+                returnedNameCheck,
+                garSettings,
+                withdrawal: withdrawalPda,
+                stakeTokenAccount: garConfig.stakeTokenAccount,
+                protocolTokenAccount: arnsConfig.treasury,
+                buyer: this.signer,
+                garProgram: this.garProgram,
+                params: buyNameParams,
+            }, { programAddress: this.arnsProgram });
+        }
+        else if (params.fundFrom === 'plan' ||
+            params.fundFrom === 'any' ||
+            params.fundFrom === 'stakes' ||
+            params.fundFrom === 'withdrawal') {
+            // 'stakes'/'withdrawal' WITHOUT an explicit gatewayAddress/withdrawalId
+            // land here (the single-source branches above handle the explicit case).
+            // Route through the funding planner, which constrains sources to the
+            // chosen mode — it never silently spends liquid balance and auto-splits
+            // across the caller's delegations/vaults. (Previously these fell through
+            // to the balance path below, silently draining liquid ARIO.)
+            ix = await this._buildBuyNameFromFundingPlanIx({
+                params,
+                antPubkey,
+                arnsRecord,
+                reservedNameCheck,
+                returnedNameCheck,
+                buyNameParams,
+                arnsConfig,
+            });
+        }
+        else if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            // Direct balance-funded buy.
+            ix = await getBuyNameInstructionAsync(await this.withArnsDefaults({
+                arnsRecord,
+                buyerTokenAccount: buyerATA,
+                protocolTokenAccount: arnsConfig.treasury,
+                reservedNameCheck,
+                returnedNameCheck,
+                buyer: this.signer,
+                params: buyNameParams,
+            }), { programAddress: this.arnsProgram });
+        }
+        else {
+            throw new Error(`unsupported fundFrom mode '${params.fundFrom}' for buyRecord`);
+        }
+        // Sprint 4 / ADR-016: bundle `ant.sync_attributes` IFF the buyer
+        // owns the ANT (preserves BD-096 — non-holder buys defer the trait
+        // sync to a later `syncAttributes()` call by the actual owner).
+        // Pass `antPubkey` as assetOverride: the ArnsRecord PDA is CREATED
+        // by the buy_name ix, so it doesn't exist on-chain at SDK build
+        // time — the helper would 404 if it tried to read it.
+        const syncIx = await this._buildSyncAttributesIxIfOwner(params.name, antPubkey);
+        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        return { id: sig };
+    }
+    /**
+     * 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`.
+     */
+    async _resolveFundingPlan(params, amountNeeded) {
+        // `'plan'` is the explicit "I'll supply my own sources, skip discovery"
+        // mode (per FUNDING_MODES.md). Fail loudly if a caller picks `'plan'`
+        // without sources — pre-2026-05 the SDK silently fell through to
+        // discovery, making `'plan'` a synonym for `'any'`. The new semantic
+        // matches the doc: `'any'` discovers, `'plan'` uses what you give it.
+        if (params.fundFrom === 'plan' && !params.sources?.length) {
+            throw new Error("fundFrom: 'plan' requires explicit `sources`. Pass them via " +
+                "params.sources, or use fundFrom: 'any' to let the SDK discover " +
+                'and plan automatically.');
+        }
+        if (params.sources?.length) {
+            // Caller supplied an explicit plan; build the FundingPlan envelope
+            // around it without source discovery. Each Delegation/OperatorStake
+            // source MUST carry an explicit `gateway` field so the executor knows
+            // which gateway PDA to slot in. Earlier single-gateway flows used
+            // `params.gatewayAddress` as a fallback for the first stake source —
+            // we preserve that for back-compat in the explicit-plan path.
+            const hasBalance = params.sources.some((s) => s.kind === 'balance');
+            const fallbackGateway = params.gatewayAddress
+                ? address(params.gatewayAddress)
+                : undefined;
+            const gatewayPerSource = params.sources.map((s) => {
+                if (s.kind !== 'delegation' && s.kind !== 'operatorStake')
+                    return undefined;
+                const explicit = s.gateway;
+                if (explicit)
+                    return address(explicit);
+                if (fallbackGateway)
+                    return fallbackGateway;
+                throw new Error('sources includes delegation/operatorStake but no gateway is set on that source and gatewayAddress is unset');
+            });
+            // Auto-detect residue: for each Delegation source, fetch the live
+            // Delegation + Gateway PDAs and compute the post-drain. If it lands
+            // in (0, min_delegation_amount), that source will trigger an on-
+            // chain residue auto-vault and we must reserve a residue PDA slot.
+            const residueDelegationIndexes = await this._detectResidueIndexes(params.sources, gatewayPerSource);
+            return {
+                sources: params.sources.map((s) => ({
+                    kind: s.kind,
+                    amount: s.amount,
+                    ...(s.withdrawalId !== undefined
+                        ? { withdrawalId: s.withdrawalId }
+                        : {}),
+                })),
+                gatewayPerSource,
+                residueDelegationIndexes,
+                hasBalanceSource: hasBalance,
+            };
+        }
+        // No explicit sources: discover + plan.
+        this.logger.debug(`[funding] discovering sources for ${this.signer.address}`, {
+            fundFrom: params.fundFrom,
+            amountNeeded: amountNeeded.toString(),
+        });
+        const arnsConfig = await this.getArnsConfig();
+        const { discoverFundingSources } = await import('./funding-plan.js');
+        const sources = await discoverFundingSources(this.rpc, this.signer.address, {
+            arioMint: arnsConfig.mint,
+            garProgram: this.garProgram,
+        });
+        this.logger.debug(`[funding] discovered ${sources.length} source(s)`, {
+            sources: sources.map((s) => {
+                if (s.kind === 'balance')
+                    return { kind: s.kind, available: s.available.toString() };
+                if (s.kind === 'delegation')
+                    return {
+                        kind: s.kind,
+                        gateway: s.gateway,
+                        available: s.available.toString(),
+                        minDelegationAmount: s.minDelegationAmount.toString(),
+                    };
+                if (s.kind === 'operatorStake')
+                    return {
+                        kind: s.kind,
+                        gateway: s.gateway,
+                        available: s.available.toString(),
+                    };
+                return {
+                    kind: s.kind,
+                    withdrawalId: s.withdrawalId.toString(),
+                    gateway: s.gateway,
+                    available: s.available.toString(),
+                    availableAt: s.availableAt.toString(),
+                };
+            }),
+        });
+        const plan = buildFundingPlanCore(sources, amountNeeded, {
+            fundFrom: params.fundFrom,
+            preferGateway: params.gatewayAddress
+                ? address(params.gatewayAddress)
+                : undefined,
+            fundAsOperator: params.fundAsOperator,
+        });
+        if ('kind' in plan) {
+            this.logger.debug(`[funding] plan failed: ${plan.message}`);
+            const err = new Error(plan.message);
+            err.cause = plan;
+            throw err;
+        }
+        this.logger.debug(`[funding] built plan with ${plan.sources.length} source(s)`, {
+            sources: plan.sources.map((s, i) => ({
+                kind: s.kind,
+                amount: s.amount.toString(),
+                gateway: plan.gatewayPerSource[i] ?? null,
+            })),
+            residueDelegationIndexes: plan.residueDelegationIndexes,
+            hasBalanceSource: plan.hasBalanceSource,
+        });
+        return plan;
+    }
+    /**
+     * 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.
+     */
+    async _buildBuyNameFromFundingPlanIx(args) {
+        const garConfig = await this.getGarConfig();
+        const [garSettings] = await getGarSettingsPDA(this.garProgram);
+        const buyerATA = await getAssociatedTokenAddressKit(args.arnsConfig.mint, this.signer.address);
+        const cost = await this._simulateTokenCost({
+            intent: CostIntent.BuyName,
+            name: args.buyNameParams.name,
+            years: args.buyNameParams.years,
+            purchaseType: args.buyNameParams.purchaseType,
+        });
+        const plan = await this._resolveFundingPlan(args.params, cost);
+        const { remainingAccounts, withdrawalCounter, residueVaultCount } = await this._materializeFundingPlan(args.params, plan);
+        return await getBuyNameFromFundingPlanInstructionAsync({
+            config: await this.arnsConfigPda(),
+            demandFactor: await this.demandFactorPda(),
+            arnsRecord: args.arnsRecord,
+            nameRegistry: await this.nameRegistryPda(),
+            reservedNameCheck: args.reservedNameCheck,
+            returnedNameCheck: args.returnedNameCheck,
+            garSettings,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: args.arnsConfig.treasury,
+            payerTokenAccount: plan.hasBalanceSource ? buyerATA : undefined,
+            buyer: this.signer,
+            withdrawalCounter,
+            garProgram: this.garProgram,
+            params: args.buyNameParams,
+            sources: plan.sources.map(toGeneratedFundingSourceSpec),
+            discountAccountCount: 0,
+            residueVaultCount,
+        }, {
+            programAddress: this.arnsProgram,
+        }).then((ix) => remainingAccounts.length > 0
+            ? withRemainingAccounts(ix, remainingAccounts)
+            : ix);
+    }
+    /**
+     * 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.
+     */
+    async _detectResidueIndexes(sources, gatewayPerSource) {
+        const delegationIndexes = sources
+            .map((s, i) => ({ s, i }))
+            .filter(({ s }) => s.kind === 'delegation');
+        if (delegationIndexes.length === 0)
+            return [];
+        const owner = this.signer.address;
+        const reads = await Promise.all(delegationIndexes.map(async ({ i }) => {
+            const gateway = gatewayPerSource[i];
+            if (!gateway) {
+                throw new Error(`funding plan source #${i} is a Delegation but gatewayPerSource[${i}] is undefined; set source.gateway or params.gatewayAddress`);
+            }
+            const [delegationPda] = await getDelegationPDA(gateway, owner, this.garProgram);
+            const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+            const [delAcct, gwAcct] = await Promise.all([
+                fetchEncodedAccount(this.rpc, delegationPda, {
+                    commitment: this.commitment,
+                }),
+                fetchEncodedAccount(this.rpc, gatewayPda, {
+                    commitment: this.commitment,
+                }),
+            ]);
+            if (!delAcct.exists) {
+                throw new Error(`residue auto-detect failed: Delegation PDA ${delegationPda} not found for source #${i} (gateway ${gateway}); ensure the delegation exists or pass an explicit funding plan with residue hints`);
+            }
+            if (!gwAcct.exists) {
+                throw new Error(`residue auto-detect failed: Gateway PDA ${gatewayPda} not found for source #${i}`);
+            }
+            return { i, delAcct, gwAcct };
+        }));
+        const delegationDecoder = getDelegationDecoder();
+        const gatewayDecoder = getGatewayDecoder();
+        const states = new Array(sources.length).fill(undefined);
+        for (const { i, delAcct, gwAcct } of reads) {
+            const delegation = delegationDecoder.decode(delAcct.data);
+            const gateway = gatewayDecoder.decode(gwAcct.data);
+            states[i] = {
+                delegationAmount: delegation.amount,
+                minDelegationAmount: gateway.settings.minDelegationAmount,
+            };
+        }
+        return computeResidueIndexes(sources, states);
+    }
+    /**
+     * 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).
+     */
+    async _materializeFundingPlan(params, plan) {
+        // Resolve withdrawalIds: prefer per-source `spec.withdrawalId` (the
+        // multi-withdrawal canonical path — discoverFundingSources sets it
+        // and explicit caller plans can too); fall back to params.withdrawalId
+        // for single-withdrawal CLI back-compat.
+        const withdrawalSpecs = (params.sources ?? plan.sources).filter((s) => s.kind === 'withdrawal');
+        const withdrawalIds = withdrawalSpecs.map((s, idx) => {
+            const specId = s.withdrawalId;
+            if (specId !== undefined)
+                return BigInt(specId);
+            if (params.withdrawalId !== undefined && idx === 0) {
+                return BigInt(params.withdrawalId);
+            }
+            throw new Error(`funding plan Withdrawal source #${idx} has no withdrawalId; set it on the source spec or pass params.withdrawalId for single-withdrawal plans`);
+        });
+        const { residueVaults, withdrawalCounter } = await predictResidueVaults(this.rpc, this.signer.address, plan, { garProgram: this.garProgram });
+        const remainingAccounts = await buildFundingPlanRemainingAccounts(plan, this.signer.address, { withdrawalIds, residueVaults, garProgram: this.garProgram });
+        return {
+            remainingAccounts: remainingAccounts,
+            withdrawalCounter,
+            residueVaultCount: residueVaults.length,
+        };
+    }
+    /**
+     * 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.
+     */
+    async _simulateTokenCost(params) {
+        const demandFactorAddr = await this.demandFactorPda();
+        this.logger.debug(`[funding] simulating token cost`, {
+            intent: params.intent,
+            name: params.name,
+            years: params.years,
+            quantity: params.quantity,
+            purchaseType: params.purchaseType,
+            arnsProgram: this.arnsProgram,
+            demandFactor: demandFactorAddr,
+        });
+        // Roll the demand factor to the current period BEFORE pricing. The
+        // `GetTokenCost` view reads the STORED demand factor, which is stale until a
+        // crank (or a buy/extend) rolls it — but the `*FromFundingPlan` handlers
+        // roll it inline before computing the cost. Without this, at a period
+        // rollover the plan is sized to the old factor while the program charges
+        // the new one → FundingPlanAmountMismatch (#6066). `update_demand_factor`
+        // is permissionless + idempotent (no-op within the same period), and the
+        // write is local to this simulation; the subsequent `GetTokenCost` in the
+        // same tx sees the rolled value.
+        const updateDfIx = getUpdateDemandFactorInstruction({ demandFactor: demandFactorAddr, payer: this.signer }, { programAddress: this.arnsProgram });
+        const ix = await getGetTokenCostInstructionAsync({
+            demandFactor: demandFactorAddr,
+            payer: this.signer,
+            intent: params.intent,
+            name: params.name,
+            years: params.years ?? null,
+            quantity: params.quantity ?? null,
+            purchaseType: params.purchaseType ?? null,
+        }, { programAddress: this.arnsProgram });
+        const { value: latestBlockhash } = await this.rpc
+            .getLatestBlockhash()
+            .send();
+        const message = pipe(createTransactionMessage({ version: 0 }), (m) => setTransactionMessageFeePayerSigner(this.signer, m), (m) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, m), (m) => appendTransactionMessageInstructions([updateDfIx, ix], m));
+        const compiled = compileTransaction(message);
+        const wire = getBase64EncodedWireTransaction(compiled);
+        const sim = await this.rpc
+            .simulateTransaction(wire, {
+            sigVerify: false,
+            replaceRecentBlockhash: true,
+            encoding: 'base64',
+        })
+            .send();
+        if (sim.value.err) {
+            throw new Error(`get_token_cost simulation failed (arnsProgram=${this.arnsProgram}, demandFactor=${demandFactorAddr}): ${JSON.stringify(sim.value.err)}` +
+                (sim.value.logs ? '\n' + sim.value.logs.join('\n') : ''));
+        }
+        const returnData = sim.value.returnData;
+        if (!returnData?.data?.[0]) {
+            throw new Error('get_token_cost simulation returned no data; expected a u64 cost');
+        }
+        const buf = Buffer.from(returnData.data[0], 'base64');
+        if (buf.length < 8) {
+            throw new Error(`get_token_cost return data too short: ${buf.length} bytes (expected 8)`);
+        }
+        const dv = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+        const cost = dv.getBigUint64(0, true);
+        this.logger.debug(`[funding] simulated token cost: ${cost} mARIO`, {
+            name: params.name,
+        });
+        return cost;
+    }
+    async arnsConfigPda() {
+        // The ArNS config (`Settings`) PDA is seeded with `arns_config` — NOT
+        // the `ario_config` seed used by the ario-core `Config` PDA. Earlier
+        // revisions of this helper called `getArioConfigPDA(this.arnsProgram)`
+        // which composes the wrong seed against the right program; the
+        // resulting PDA points at an account that never exists, and every
+        // fund-from-stakes / withdrawal / funding-plan path simulated as
+        // AccountNotInitialized (#3012) on the `config` slot.
+        const [pda] = await getArnsSettingsPDA(this.arnsProgram);
+        return pda;
+    }
+    async demandFactorPda() {
+        const [pda] = await getDemandFactorPDA(this.arnsProgram);
+        return pda;
+    }
+    async nameRegistryPda() {
+        const [pda] = await getArnsRegistryPDA(this.arnsProgram);
+        return pda;
+    }
+    async upgradeRecord(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
+        const ix = await this._buildManageStakeIx({
+            params,
+            operation: 'upgrade',
+        });
+        const syncIx = await this._buildSyncAttributesIxIfOwner(params.name);
+        const sig = await this.sendTransaction(syncIx ? [...migrateIxs, ix, syncIx] : [...migrateIxs, ix]);
+        return { id: sig };
+    }
+    async syncAttributes(params, _options) {
+        // Public method — caller is asking explicitly to sync. Build the ix
+        // unconditionally; if they don't actually own the ANT, the on-chain
+        // handler returns NotNftHolder. (The bundle path uses
+        // `_buildSyncAttributesIxIfOwner`, which skips when not the owner so
+        // the wrapping arns ix can still succeed for non-holder management
+        // — see BD-095.)
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
+        const ix = await this._buildSyncAttributesIxUnconditional(params.name);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
+        return { id: sig };
+    }
+    /**
+     * 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.
+     */
+    async _buildSyncAttributesIxIfOwner(name, assetOverride) {
+        let asset;
+        if (assetOverride !== undefined) {
+            asset = assetOverride;
+        }
+        else {
+            const record = await this.getArNSRecord({ name });
+            asset = address(record.processId);
+        }
+        const { fetchMplCoreOwner } = await import('./mpl-core.js');
+        const owner = await fetchMplCoreOwner(this.rpc, asset, {
+            commitment: this.commitment,
+        });
+        if (owner === null || owner !== this.signer.address) {
+            return null;
+        }
+        return this._buildSyncAttributesIxFor(name, asset);
+    }
+    /**
+     * 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.
+     */
+    async _buildSyncAttributesIxUnconditional(name) {
+        const record = await this.getArNSRecord({ name });
+        return this._buildSyncAttributesIxFor(name, address(record.processId));
+    }
+    /** Pure builder; no RPC. Used by both gated + unconditional helpers. */
+    async _buildSyncAttributesIxFor(name, asset) {
+        const [arnsRecord] = await getArnsRecordPDA(name, this.arnsProgram);
+        return getSyncAttributesInstruction({
+            asset,
+            payer: this.signer,
+            authority: this.signer,
+            arnsRecord,
+            name,
+        }, { programAddress: this.antProgram });
+    }
+    async extendLease(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
+        const ix = await this._buildManageStakeIx({
+            params,
+            operation: 'extend',
+            years: params.years,
+        });
+        // BD-095: extend_lease changes only `end_timestamp`, which isn't
+        // mirrored in any Metaplex Attributes plugin trait. No bundle.
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
+        return { id: sig };
+    }
+    async increaseUndernameLimit(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
+        const ix = await this._buildManageStakeIx({
+            params,
+            operation: 'increaseUndername',
+            quantity: params.increaseCount,
+        });
+        const syncIx = await this._buildSyncAttributesIxIfOwner(params.name);
+        const sig = await this.sendTransaction(syncIx ? [...migrateIxs, ix, syncIx] : [...migrateIxs, ix]);
+        return { id: sig };
+    }
+    /**
+     * 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).
+     */
+    async _buildManageStakeIx(args) {
+        const arnsConfig = await this.getArnsConfig();
+        const callerATA = await getAssociatedTokenAddressKit(arnsConfig.mint, this.signer.address);
+        const [arnsRecord] = await getArnsRecordPDA(args.params.name, this.arnsProgram);
+        // Balance / undefined → original direct-transfer ix (matches pre-Phase-4).
+        if (!args.params.fundFrom ||
+            args.params.fundFrom === 'balance' ||
+            args.params.fundFrom === 'turbo') {
+            const baseAccounts = await this.withArnsDefaults({
+                arnsRecord,
+                callerTokenAccount: callerATA,
+                protocolTokenAccount: arnsConfig.treasury,
+                caller: this.signer,
+            });
+            if (args.operation === 'upgrade') {
+                return getUpgradeNameInstructionAsync(baseAccounts, {
+                    programAddress: this.arnsProgram,
+                });
+            }
+            if (args.operation === 'extend') {
+                return getExtendLeaseInstructionAsync({ ...baseAccounts, years: args.years }, { programAddress: this.arnsProgram });
+            }
+            return getIncreaseUndernameLimitInstructionAsync({ ...baseAccounts, quantity: args.quantity }, { programAddress: this.arnsProgram });
+        }
+        // Stake / withdrawal / funding-plan paths share an account skeleton.
+        const garConfig = await this.getGarConfig();
+        const [garSettings] = await getGarSettingsPDA(this.garProgram);
+        const sharedManageBase = {
+            config: await this.arnsConfigPda(),
+            demandFactor: await this.demandFactorPda(),
+            arnsRecord,
+            garSettings,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: arnsConfig.treasury,
+            caller: this.signer,
+            garProgram: this.garProgram,
+        };
+        if (args.params.fundFrom === 'stakes' && args.params.gatewayAddress) {
+            const gatewayAddr = address(args.params.gatewayAddress);
+            const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+            const stakeBase = { ...sharedManageBase, gateway: gatewayPda };
+            if (args.params.fundAsOperator) {
+                if (args.operation === 'upgrade')
+                    return getUpgradeNameFromOperatorStakeInstructionAsync(stakeBase, {
+                        programAddress: this.arnsProgram,
+                    });
+                if (args.operation === 'extend')
+                    return getExtendLeaseFromOperatorStakeInstructionAsync({ ...stakeBase, years: args.years }, { programAddress: this.arnsProgram });
+                return getIncreaseUndernameLimitFromOperatorStakeInstructionAsync({ ...stakeBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+            }
+            const [delegationPda] = await getDelegationPDA(gatewayAddr, this.signer.address, this.garProgram);
+            const delBase = { ...stakeBase, delegation: delegationPda };
+            if (args.operation === 'upgrade')
+                return getUpgradeNameFromDelegationInstructionAsync(delBase, {
+                    programAddress: this.arnsProgram,
+                });
+            if (args.operation === 'extend')
+                return getExtendLeaseFromDelegationInstructionAsync({ ...delBase, years: args.years }, { programAddress: this.arnsProgram });
+            return getIncreaseUndernameLimitFromDelegationInstructionAsync({ ...delBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+        }
+        if (args.params.fundFrom === 'withdrawal' &&
+            args.params.withdrawalId !== undefined) {
+            const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, args.params.withdrawalId, this.garProgram);
+            const wBase = { ...sharedManageBase, withdrawal: withdrawalPda };
+            if (args.operation === 'upgrade')
+                return getUpgradeNameFromWithdrawalInstructionAsync(wBase, {
+                    programAddress: this.arnsProgram,
+                });
+            if (args.operation === 'extend')
+                return getExtendLeaseFromWithdrawalInstructionAsync({ ...wBase, years: args.years }, { programAddress: this.arnsProgram });
+            return getIncreaseUndernameLimitFromWithdrawalInstructionAsync({ ...wBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+        }
+        if (args.params.fundFrom === 'plan' ||
+            args.params.fundFrom === 'any' ||
+            args.params.fundFrom === 'stakes' ||
+            args.params.fundFrom === 'withdrawal') {
+            // 'stakes'/'withdrawal' without an explicit gatewayAddress/withdrawalId
+            // route here (the single-source branches above handle the explicit
+            // case). The planner constrains sources to the chosen mode and never
+            // spends liquid balance.
+            // Cost estimation for manage variants: each operation has its own
+            // pricing path. Keep it pragmatic — let the planner build the plan
+            // around the user's desired total (caller can pass explicit sources
+            // to bypass cost estimation entirely).
+            const intentMap = {
+                upgrade: CostIntent.UpgradeName,
+                extend: CostIntent.ExtendLease,
+                increaseUndername: CostIntent.IncreaseUndernameLimit,
+            };
+            const cost = await this._simulateTokenCost({
+                intent: intentMap[args.operation],
+                name: args.params.name,
+                years: args.years,
+                quantity: args.quantity,
+            });
+            const plan = await this._resolveFundingPlan(args.params, cost);
+            const buyerATA = await getAssociatedTokenAddressKit(arnsConfig.mint, this.signer.address);
+            const { remainingAccounts, withdrawalCounter, residueVaultCount } = await this._materializeFundingPlan(args.params, plan);
+            const fpBase = {
+                config: await this.arnsConfigPda(),
+                demandFactor: await this.demandFactorPda(),
+                arnsRecord,
+                garSettings,
+                stakeTokenAccount: garConfig.stakeTokenAccount,
+                protocolTokenAccount: arnsConfig.treasury,
+                payerTokenAccount: plan.hasBalanceSource ? buyerATA : undefined,
+                caller: this.signer,
+                withdrawalCounter,
+                garProgram: this.garProgram,
+                sources: plan.sources.map(toGeneratedFundingSourceSpec),
+                discountAccountCount: 0,
+                residueVaultCount,
+            };
+            let ix;
+            if (args.operation === 'upgrade')
+                ix = await getUpgradeNameFromFundingPlanInstructionAsync(fpBase, {
+                    programAddress: this.arnsProgram,
+                });
+            else if (args.operation === 'extend')
+                ix = await getExtendLeaseFromFundingPlanInstructionAsync({ ...fpBase, years: args.years }, { programAddress: this.arnsProgram });
+            else
+                ix = await getIncreaseUndernameLimitFromFundingPlanInstructionAsync({ ...fpBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+            return remainingAccounts.length > 0
+                ? withRemainingAccounts(ix, remainingAccounts)
+                : ix;
+        }
+        throw new Error(`unsupported fundFrom mode '${args.params.fundFrom}' for ${args.operation}`);
+    }
+    // =========================================
+    // Primary name operations (ario-core)
+    // =========================================
+    /**
+     * 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.
+     */
+    async _buildRemoveExistingPrimaryNameIxs() {
+        const [primaryNamePda] = await getPrimaryNamePDA(this.signer.address, this.coreProgram);
+        const account = await fetchEncodedAccount(this.rpc, primaryNamePda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return [];
+        const { name: oldName } = deserializePrimaryName(Buffer.from(account.data));
+        const [primaryNameReversePda] = await getPrimaryNameReversePDA(oldName, this.coreProgram);
+        const reverseAccount = await fetchEncodedAccount(this.rpc, primaryNameReversePda, { commitment: this.commitment });
+        if (!reverseAccount.exists) {
+            // Fail fast with an actionable message. See method docstring for
+            // why request_and_set would reject this regardless.
+            throw new Error(`Cannot change primary name: signer "${this.signer.address}" has a ` +
+                `legacy PrimaryName ("${oldName}") with no paired PrimaryNameReverse PDA ` +
+                `(${primaryNameReversePda}). The on-chain remove_primary_name and ` +
+                `request_and_set_primary_name ixs both require the reverse PDA — ` +
+                `request_and_set will reject with MustRemoveExistingPrimaryName (code 6022). ` +
+                `Run \`yarn workspace @ar-io/migration-import backfill:primary-name-reverse\` ` +
+                `against this cluster's ario-core program to materialize the missing reverse ` +
+                `PDA, then retry.`);
+        }
+        return [
+            await getRemovePrimaryNameInstructionAsync({
+                primaryName: primaryNamePda,
+                primaryNameReverse: primaryNameReversePda,
+                owner: this.signer,
+                reverseLookupHash: hashName(oldName),
+            }, { programAddress: this.coreProgram }),
+        ];
+    }
+    /**
+     * 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).
+     */
+    async _buildPrimaryNameValidationAccounts(name, variant) {
+        const { isUndername, baseName, undername } = splitPrimaryName(name);
+        const [arnsRecordPda] = await getArnsRecordPDA(baseName, this.arnsProgram);
+        const remaining = [
+            { address: arnsRecordPda, role: AccountRole.READONLY },
+        ];
+        // Fee-charging variants need the demand factor for fee scaling.
+        if (variant === 'request' || variant === 'requestAndSet') {
+            const [demandFactorPda] = await getDemandFactorPDA(this.arnsProgram);
+            remaining.push({ address: demandFactorPda, role: AccountRole.READONLY });
+        }
+        // ANT-auth variants need the AntRecord PDA. We have to read the
+        // ArnsRecord first to recover the ANT mint, then read the asset's
+        // `ANT Program` trait (ADR-016 / BD-100) to pick the right program
+        // for the AntRecord PDA derivation.
+        let antProgram = this.antProgram;
+        if (variant !== 'request') {
+            const arnsAccount = await fetchEncodedAccount(this.rpc, arnsRecordPda, {
+                commitment: this.commitment,
+            });
+            if (!arnsAccount.exists) {
+                throw new Error(`ArNS record not found for base name: ${baseName}`);
+            }
+            const arnsRecord = deserializeArnsRecord(Buffer.from(arnsAccount.data));
+            const antMint = address(arnsRecord.processId);
+            const { fetchAntProgramFromAsset } = await import('./mpl-core.js');
+            const detected = await fetchAntProgramFromAsset(this.rpc, antMint, {
+                commitment: this.commitment,
+            });
+            // SECURITY (BD-100 / SDK ANT-program auth finding): the asset's
+            // `ANT Program` trait is untrusted asset/RPC data. Only honor a detected
+            // value when it matches the canonical program or the program this client
+            // was explicitly configured with (`this.antProgram`); otherwise fall back
+            // to the configured program so a spoofed trait can't redirect the
+            // AntRecord PDA derivation. This path only derives a READONLY validation
+            // account (the instruction itself targets the canonical core program), so
+            // the fallback is silent rather than a throw — but the gate keeps an
+            // attacker from steering PDA derivation. Heterogeneous BYO-ANT primary
+            // names (an asset on a non-configured program) await the contract-side
+            // resolution of the `ant_program == ario_ant::ID` pin; see the
+            // accompanying security note.
+            antProgram =
+                detected !== null &&
+                    (detected === ARIO_ANT_PROGRAM_ID || detected === this.antProgram)
+                    ? detected
+                    : this.antProgram;
+            // removeForBaseName always uses the "@" undername (the base-name
+            // owner's record). The other ANT-auth variants use the undername
+            // part if the primary name is an undername.
+            const antUndername = variant === 'removeForBaseName' || !isUndername || undername === null
+                ? '@'
+                : undername;
+            const [antRecordPda] = await getAntRecordPDA(antMint, antUndername, antProgram);
+            remaining.push({ address: antRecordPda, role: AccountRole.READONLY });
+            // AntConfig PDA (ANT-level owner snapshot). ario-core reads
+            // `AntConfig.last_known_owner` as the implicit-owner source and to
+            // freshness-gate the per-record `AntRecord.owner` delegate (BD-097 /
+            // BD-109). Derived under the SAME resolved `antProgram` as the
+            // AntRecord above. Required trailing account for all three ANT-auth
+            // variants (and the funding-plan variant, whose validation_account_count
+            // is derived from this array's length downstream).
+            const [antConfigPda] = await getAntConfigPDA(antMint, antProgram);
+            remaining.push({ address: antConfigPda, role: AccountRole.READONLY });
+        }
+        return { remaining, antProgram };
+    }
+    async requestPrimaryName(params, _options) {
+        // If the caller already has a primary name, prepend remove ixs so
+        // the on-chain handler doesn't reject with MustRemoveExistingPrimaryName.
+        const removeIxs = await this._buildRemoveExistingPrimaryNameIxs();
+        const { baseName } = splitPrimaryName(params.name);
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(baseName);
+        const coreConfig = await this.getCoreConfig();
+        const signerATA = await getAssociatedTokenAddressKit(coreConfig.mint, this.signer.address);
+        const { remaining } = await this._buildPrimaryNameValidationAccounts(params.name, 'request');
+        // Phase 4 of FUND_FROM_PLAN.md: dispatch primary-name funding via the
+        // funding-plan ix when caller asks for stakes/withdrawal/plan/any. The
+        // direct-transfer ix stays the path for fundFrom='balance' / undefined.
+        let ix;
+        if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            ix = withRemainingAccounts(await getRequestPrimaryNameInstructionAsync(await this.withCoreDefaults({
+                initiatorTokenAccount: signerATA,
+                protocolTokenAccount: coreConfig.treasury,
+                initiator: this.signer,
+                name: params.name,
+            }), { programAddress: this.coreProgram }), remaining);
+        }
+        else {
+            ix = await this._buildPrimaryNameFromFundingPlanIx({
+                params,
+                coreConfig,
+                validationAccounts: remaining,
+                operation: 'request',
+            });
+        }
+        const sig = await this.sendTransaction([...removeIxs, ...migrateIxs, ix]);
+        return { id: sig };
+    }
+    async setPrimaryName(params, _options) {
+        // setPrimaryName routes to the on-chain `request_and_set_primary_name`
+        // path — the auto-approve flow when the caller owns the AntRecord
+        // for the matching name (undername part, or "@" for base names).
+        // If the caller already has a primary name, prepend remove ixs so
+        // the "change" is atomic in a single transaction.
+        const removeIxs = await this._buildRemoveExistingPrimaryNameIxs();
+        const { baseName } = splitPrimaryName(params.name);
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(baseName);
+        const coreConfig = await this.getCoreConfig();
+        const signerATA = await getAssociatedTokenAddressKit(coreConfig.mint, this.signer.address);
+        const { remaining, antProgram } = await this._buildPrimaryNameValidationAccounts(params.name, 'requestAndSet');
+        let ix;
+        if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            ix = withRemainingAccounts(await getRequestAndSetPrimaryNameInstructionAsync(await this.withCoreDefaults({
+                initiatorTokenAccount: signerATA,
+                protocolTokenAccount: coreConfig.treasury,
+                initiator: this.signer,
+                name: params.name,
+                reverseLookupHash: hashName(params.name),
+                antProgramId: antProgram,
+            }), { programAddress: this.coreProgram }), remaining);
+        }
+        else {
+            ix = await this._buildPrimaryNameFromFundingPlanIx({
+                params,
+                coreConfig,
+                validationAccounts: remaining,
+                operation: 'requestAndSet',
+                antProgramId: antProgram,
+            });
+        }
+        const sig = await this.sendTransaction([...removeIxs, ...migrateIxs, ix]);
+        return { id: sig };
+    }
+    /**
+     * 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.
+     */
+    async _buildPrimaryNameFromFundingPlanIx(args) {
+        const fee = await this._simulateTokenCost({
+            intent: CostIntent.PrimaryNameRequest,
+            name: args.params.name,
+        });
+        const plan = await this._resolveFundingPlan(args.params, fee);
+        const garConfig = await this.getGarConfig();
+        const [garSettings] = await getGarSettingsPDA(this.garProgram);
+        const initiatorATA = await getAssociatedTokenAddressKit(args.coreConfig.mint, this.signer.address);
+        const { remainingAccounts: fundingRemaining, withdrawalCounter, residueVaultCount, } = await this._materializeFundingPlan(args.params, plan);
+        const allRemaining = [
+            ...args.validationAccounts,
+            ...fundingRemaining,
+        ];
+        const validationAccountCount = args.validationAccounts.length;
+        const baseFp = {
+            config: await this._coreConfigPda(),
+            garSettings,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: args.coreConfig.treasury,
+            payerTokenAccount: plan.hasBalanceSource ? initiatorATA : undefined,
+            initiator: this.signer,
+            withdrawalCounter,
+            garProgram: this.garProgram,
+            sources: plan.sources.map(toGeneratedFundingSourceSpec),
+            validationAccountCount,
+            residueVaultCount,
+        };
+        let ix;
+        if (args.operation === 'request') {
+            const [requestPda] = await getPrimaryNameRequestPDA(this.signer.address, this.coreProgram);
+            ix = await getRequestPrimaryNameFromFundingPlanInstructionAsync({ ...baseFp, request: requestPda, name: args.params.name }, { programAddress: this.coreProgram });
+        }
+        else {
+            const [primaryNamePda] = await getPrimaryNamePDA(this.signer.address, this.coreProgram);
+            const [primaryNameReversePda] = await getPrimaryNameReversePDA(args.params.name, this.coreProgram);
+            ix = await getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync({
+                ...baseFp,
+                primaryName: primaryNamePda,
+                primaryNameReverse: primaryNameReversePda,
+                name: args.params.name,
+                reverseLookupHash: hashName(args.params.name),
+                antProgramId: args.antProgramId ?? this.antProgram,
+            }, { programAddress: this.coreProgram });
+        }
+        return allRemaining.length > 0
+            ? withRemainingAccounts(ix, allRemaining)
+            : ix;
+    }
+    async _coreConfigPda() {
+        const [pda] = await getArioConfigPDA(this.coreProgram);
+        return pda;
+    }
+    /**
+     * 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].
+     */
+    async approvePrimaryName(params, _options) {
+        const { baseName } = splitPrimaryName(params.name);
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(baseName);
+        const [requestPda] = await getPrimaryNameRequestPDA(params.initiator, this.coreProgram);
+        const [primaryNamePda] = await getPrimaryNamePDA(params.initiator, this.coreProgram);
+        const [primaryNameReversePda] = await getPrimaryNameReversePDA(params.name, this.coreProgram);
+        const { remaining, antProgram } = await this._buildPrimaryNameValidationAccounts(params.name, 'approve');
+        // withCoreDefaults injects `config` as the ArioConfig PDA derived against
+        // *this.coreProgram*. Without it, Codama's `findConfigPda()` fallback
+        // resolves to the source-pinned `ARioCoreProgramXXXX...` placeholder
+        // program id (declare_id! literal pre-anchor-keys-sync), which on any
+        // non-mainnet deployment produces an unallocated PDA → Anchor #3012
+        // AccountNotInitialized on `config`. requestPrimaryName /
+        // requestAndSetPrimaryName already use withCoreDefaults; this was the
+        // last setPrimaryName-family entrypoint missing it.
+        const ix = withRemainingAccounts(await getApprovePrimaryNameInstructionAsync(await this.withCoreDefaults({
+            request: requestPda,
+            initiator: params.initiator,
+            primaryName: primaryNamePda,
+            primaryNameReverse: primaryNameReversePda,
+            nameOwner: this.signer,
+            reverseLookupHash: hashName(params.name),
+            antProgramId: antProgram,
+        }), { programAddress: this.coreProgram }), remaining);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Vault release (ario-core)
+    // =========================================
+    /** Release tokens from an unlocked vault back to the owner. */
+    async releaseVault(params, _options) {
+        const mint = await this.getMint();
+        const [vaultPda] = await getVaultPDA(this.signer.address, BigInt(params.vaultId), this.coreProgram);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const ownerATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const ix = await getReleaseVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            vaultTokenAccount: vaultATA,
+            ownerTokenAccount: ownerATA,
+            owner: this.signer,
+        }), { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Close expired primary name request (ario-core)
+    // =========================================
+    /** Close an expired primary name request (permissionless — anyone can call). */
+    async closeExpiredRequest(params, _options) {
+        const initiatorPubkey = address(params.initiator);
+        const [requestPda] = await getPrimaryNameRequestPDA(initiatorPubkey, this.coreProgram);
+        const ix = getCloseExpiredRequestInstruction({
+            request: requestPda,
+            initiator: initiatorPubkey,
+            payer: this.signer,
+        }, { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Withdrawal claim (ario-gar)
+    // =========================================
+    /** Claim tokens from a completed withdrawal (after lock period). */
+    async claimWithdrawal(params, _options) {
+        const garConfig = await this.getGarConfig();
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, BigInt(params.withdrawalId), this.garProgram);
+        const ownerATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getClaimWithdrawalInstructionAsync(await this.withGarDefaults({
+            withdrawal: withdrawalPda,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            ownerTokenAccount: ownerATA,
+            owner: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
+    // Claim delegation from leaving gateway (ario-gar)
+    // =========================================
+    /** Claim delegated stake from a gateway that is leaving the network. */
+    async claimDelegateFromLeavingGateway(params, _options) {
+        const gateway = address(params.gatewayAddress);
+        const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(gateway, this.signer.address, this.garProgram);
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, nextId, this.garProgram);
+        // The on-chain handler is permissionless since `af38a40` (delegator +
+        // payer split — anyone can crank). The IDL exposes both fields:
+        // `delegator: Address` (no signature, just the seeds-derivation key)
+        // and `payer: Signer` (covers rent on the init_if_needed withdrawal
+        // counter + the new withdrawal account). The SDK's primary self-
+        // claim path passes the signer for both roles; cranker callers can
+        // pass distinct addresses by adding a `payer?` param to this method
+        // (out of scope here — feature gap; tracked in
+        // docs/E2E_TEST_COVERAGE_PLAN.md Phase 3.3).
+        const ix = await getClaimDelegateFromLeavingGatewayInstructionAsync({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            withdrawal: withdrawalPda,
+            delegator: this.signer.address,
+            payer: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
+    // Claim delegation from gateway with delegation DISABLED (ario-gar, Fix #6)
+    // =========================================
+    /**
+     * 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).
+     */
+    async claimDelegateFromDisabledGateway(params, _options) {
+        const gateway = address(params.gatewayAddress);
+        const delegator = params.delegatorAddress
+            ? address(params.delegatorAddress)
+            : this.signer.address;
+        const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(gateway, delegator, this.garProgram);
+        // Withdrawal counter + vault are PDA-seeded by the delegator, not the payer.
+        const nextId = await this.getNextWithdrawalId(delegator);
+        const [withdrawalPda] = await getWithdrawalPDA(delegator, nextId, this.garProgram);
+        const ix = await getClaimDelegateFromDisabledGatewayInstructionAsync({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            withdrawal: withdrawalPda,
+            // `delegator` is an unsigned seeds-derivation key; `payer` (the signer)
+            // covers rent on the init_if_needed counter + the new withdrawal.
+            delegator,
+            payer: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
+    // Delegation allowlist (ario-gar)
+    // =========================================
+    /** Add an address to the gateway's delegation allowlist. */
+    async allowDelegate(params, _options) {
+        const ix = await getAllowDelegateInstructionAsync({
+            delegate: address(params.delegate),
+            operator: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    /** Remove an address from the gateway's delegation allowlist. */
+    async disallowDelegate(params, _options) {
+        const ix = await getDisallowDelegateInstructionAsync({
+            delegate: address(params.delegate),
+            operator: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    /** Enable or disable the delegation allowlist for the gateway. */
+    async setAllowlistEnabled(params, _options) {
+        const ix = await getSetAllowlistEnabledInstructionAsync(await this.withGarDefaults({
+            operator: this.signer,
+            enabled: params.enabled,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
+    // Buy returned name (ario-arns)
+    // =========================================
+    /**
+     * 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).
+     */
+    async buyReturnedName(params, _options) {
+        const arnsConfig = await this.getArnsConfig();
+        const buyerATA = await getAssociatedTokenAddressKit(arnsConfig.mint, this.signer.address);
+        const antPubkey = address(params.processId);
+        // Read the ReturnedName to find the original initiator (gets the premium).
+        const [returnedNamePda] = await getReturnedNamePDA(params.name, this.arnsProgram);
+        const returnedNameAccount = await fetchEncodedAccount(this.rpc, returnedNamePda, { commitment: this.commitment });
+        if (!returnedNameAccount.exists) {
+            throw new Error(`Returned name not found: ${params.name}`);
+        }
+        const returnedNameData = Buffer.from(returnedNameAccount.data);
+        const nameLen = returnedNameData.readUInt32LE(8);
+        const initiatorOffset = 8 + 4 + nameLen + 32;
+        const initiator = addressDecoder.decode(returnedNameData.subarray(initiatorOffset, initiatorOffset + 32));
+        const initiatorATA = await getAssociatedTokenAddressKit(arnsConfig.mint, initiator);
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const buyParams = {
+            name: params.name,
+            purchaseType: params.type === 'permabuy' ? PurchaseType.Permabuy : PurchaseType.Lease,
+            years: params.years ?? 1,
+            ant: antPubkey,
+        };
+        // Returned-name price is a per-slot-decaying Dutch auction, so the
+        // multi-source funding plan (which pre-commits exact source amounts) can't
+        // match the execution-time cost → FundingPlanAmountMismatch (#6066). Prefer
+        // a single-source stake path: it carries no amount, so the program computes
+        // and draws the live cost itself. When the caller asked to fund from
+        // stakes/withdrawal/any without naming a specific gateway/vault,
+        // auto-resolve a single source with enough stake to cover the
+        // (premium-inclusive) cost.
+        let resolvedGateway = params.gatewayAddress;
+        let resolvedFundAsOperator = params.fundAsOperator ?? false;
+        let resolvedWithdrawalId = params.withdrawalId;
+        const wantsStake = params.fundFrom === 'stakes' ||
+            params.fundFrom === 'withdrawal' ||
+            params.fundFrom === 'any';
+        if (wantsStake &&
+            resolvedGateway === undefined &&
+            resolvedWithdrawalId === undefined &&
+            !params.sources?.length) {
+            const picked = await this._autoPickReturnedNameStakeSource(params);
+            if (picked?.kind === 'delegation') {
+                resolvedGateway = picked.gateway;
+                resolvedFundAsOperator = false;
+            }
+            else if (picked?.kind === 'operatorStake') {
+                resolvedGateway = picked.gateway;
+                resolvedFundAsOperator = true;
+            }
+            else if (picked?.kind === 'withdrawal') {
+                resolvedWithdrawalId = picked.withdrawalId;
+            }
+            else if (params.fundFrom !== 'any') {
+                // 'stakes'/'withdrawal' explicitly requested but nothing covers it.
+                throw new Error(`buyReturnedName: no ${params.fundFrom === 'withdrawal'
+                    ? 'matured withdrawal vault'
+                    : 'delegation/operator stake'} large enough to fund '${params.name}' was found for ` +
+                    `${this.signer.address}. Fund from balance, or add stake first.`);
+            }
+            // 'any' with nothing found → falls through to the balance path.
+        }
+        let ix;
+        const useBalance = !params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo' ||
+            (params.fundFrom === 'any' &&
+                resolvedGateway === undefined &&
+                resolvedWithdrawalId === undefined &&
+                !params.sources?.length);
+        if (useBalance) {
+            ix = await getBuyReturnedNameInstructionAsync(await this.withArnsDefaults({
+                arnsRecord,
+                returnedName: returnedNamePda,
+                buyerTokenAccount: buyerATA,
+                protocolTokenAccount: arnsConfig.treasury,
+                initiatorTokenAccount: initiatorATA,
+                buyer: this.signer,
+                params: buyParams,
+            }), { programAddress: this.arnsProgram });
+        }
+        else {
+            const garConfig = await this.getGarConfig();
+            const [garSettings] = await getGarSettingsPDA(this.garProgram);
+            const sharedReturnedBase = {
+                config: await this.arnsConfigPda(),
+                demandFactor: await this.demandFactorPda(),
+                returnedName: returnedNamePda,
+                arnsRecord,
+                nameRegistry: await this.nameRegistryPda(),
+                buyerTokenAccount: buyerATA,
+                initiatorTokenAccount: initiatorATA,
+                garSettings,
+                stakeTokenAccount: garConfig.stakeTokenAccount,
+                protocolTokenAccount: arnsConfig.treasury,
+                buyer: this.signer,
+                garProgram: this.garProgram,
+                params: buyParams,
+            };
+            if (resolvedGateway !== undefined) {
+                const gatewayAddr = address(resolvedGateway);
+                const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+                if (resolvedFundAsOperator) {
+                    ix = await getBuyReturnedNameFromOperatorStakeInstructionAsync({ ...sharedReturnedBase, gateway: gatewayPda }, { programAddress: this.arnsProgram });
+                }
+                else {
+                    const [delegationPda] = await getDelegationPDA(gatewayAddr, this.signer.address, this.garProgram);
+                    ix = await getBuyReturnedNameFromDelegationInstructionAsync({
+                        ...sharedReturnedBase,
+                        gateway: gatewayPda,
+                        delegation: delegationPda,
+                    }, { programAddress: this.arnsProgram });
+                }
+            }
+            else if (resolvedWithdrawalId !== undefined) {
+                const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, resolvedWithdrawalId, this.garProgram);
+                ix = await getBuyReturnedNameFromWithdrawalInstructionAsync({ ...sharedReturnedBase, withdrawal: withdrawalPda }, { programAddress: this.arnsProgram });
+            }
+            else if (params.fundFrom === 'plan' && params.sources?.length) {
+                // Explicit caller-supplied plan only: the caller owns the source
+                // amounts and accepts the decay risk (the price moves per slot, so a
+                // stale plan trips FundingPlanAmountMismatch). We do NOT auto-discover
+                // a multi-source plan for returned names — see the single-source note
+                // above.
+                const cost = await this._simulateTokenCost({
+                    intent: CostIntent.BuyName,
+                    name: params.name,
+                    years: buyParams.years,
+                    purchaseType: buyParams.purchaseType,
+                });
+                const plan = await this._resolveFundingPlan(params, cost);
+                const { remainingAccounts, withdrawalCounter, residueVaultCount } = await this._materializeFundingPlan(params, plan);
+                ix = await getBuyReturnedNameFromFundingPlanInstructionAsync({
+                    ...sharedReturnedBase,
+                    payerTokenAccount: plan.hasBalanceSource ? buyerATA : undefined,
+                    withdrawalCounter,
+                    sources: plan.sources.map(toGeneratedFundingSourceSpec),
+                    discountAccountCount: 0,
+                    residueVaultCount,
+                }, { programAddress: this.arnsProgram });
+                if (remainingAccounts.length > 0)
+                    ix = withRemainingAccounts(ix, remainingAccounts);
+            }
+            else {
+                throw new Error(`unsupported fundFrom mode '${params.fundFrom}' for buyReturnedName`);
+            }
+        }
+        // The on-chain `buy_returned_name*` handlers take `initiator_token_account`
+        // and `buyer_token_account` as `Account<TokenAccount>` (NOT `init`), so
+        // Anchor requires both ATAs to already exist or fails with
+        // AccountNotInitialized (#3012). The original initiator may never have held
+        // ARIO, and the premium always settles from the buyer's liquid ATA — bundle
+        // idempotent ATA creates so the buy succeeds without a separate setup step
+        // (mirrors the vault-ATA handling above). Idempotent: ~1500 CU each, no-op
+        // when the account already exists.
+        const createInitiatorAtaIx = buildCreateAtaIdempotentIx(this.signer.address, initiatorATA, initiator, arnsConfig.mint);
+        const createBuyerAtaIx = buildCreateAtaIdempotentIx(this.signer.address, buyerATA, this.signer.address, arnsConfig.mint);
+        // Sprint 4 / ADR-016: bundle ant.sync_attributes after the buy so the
+        // Attributes plugin reflects the new record holder. assetOverride =
+        // antPubkey because the ArnsRecord PDA is created by buy_returned_name
+        // and doesn't exist on-chain at SDK build time.
+        const syncIx = await this._buildSyncAttributesIxIfOwner(params.name, antPubkey);
+        const sig = await this.sendTransaction([
+            createBuyerAtaIx,
+            createInitiatorAtaIx,
+            ix,
+            ...(syncIx ? [syncIx] : []),
+        ]);
+        return { id: sig };
+    }
+    /**
+     * 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.
+     */
+    async _autoPickReturnedNameStakeSource(params) {
+        const estimate = BigInt(Math.ceil(await this.getTokenCost({
+            intent: 'Buy-Name',
+            name: params.name,
+            type: params.type,
+            years: params.years ?? 1,
+        })));
+        const arnsConfig = await this.getArnsConfig();
+        const { discoverFundingSources } = await import('./funding-plan.js');
+        const sources = await discoverFundingSources(this.rpc, this.signer.address, { arioMint: arnsConfig.mint, garProgram: this.garProgram });
+        // 'withdrawal' mode → matured withdrawal vaults only; otherwise prefer
+        // operator stake when the caller asked, else a delegation.
+        const wantKind = params.fundFrom === 'withdrawal'
+            ? 'withdrawal'
+            : params.fundAsOperator === true
+                ? 'operatorStake'
+                : 'delegation';
+        const candidates = sources
+            .filter((s) => s.kind === wantKind && s.available >= estimate)
+            .sort((a, b) => b.available > a.available ? 1 : b.available < a.available ? -1 : 0);
+        return candidates[0] ?? null;
+    }
+    // =========================================
+    // Name management (ario-arns)
+    // =========================================
+    /** Reassign an ArNS name to a different ANT. */
+    async reassignName(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
+        const newAnt = address(params.processId);
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const record = await this.getArNSRecord({ name: params.name });
+        const antAsset = address(record.processId);
+        const ix = await getReassignNameInstructionAsync(await this.withArnsDefaults({
+            arnsRecord,
+            antAsset,
+            caller: this.signer,
+            newAnt,
+        }), { programAddress: this.arnsProgram });
+        // Post-reassign the record points at `newAnt`. The bundled
+        // `sync_attributes` MUST target `newAnt` — without the override, the
+        // helper would read the on-chain record at SDK build time (still
+        // pointing at the OLD asset), build a sync ix for the OLD asset, and
+        // fail the post-reassign `record.ant == asset.key()` check. The
+        // owner-check inside _buildSyncAttributesIxIfOwner runs against
+        // `newAnt`, so the bundle fires only when the reassign caller is also
+        // the new ANT's holder; otherwise the ix is sent alone and the new
+        // owner runs `syncAttributes()` later (BD-095/096).
+        const syncIx = await this._buildSyncAttributesIxIfOwner(params.name, newAnt);
+        const reassignWithMetas = withRemainingAccounts(ix, [
+            { address: newAnt, role: AccountRole.READONLY },
+        ]);
+        const sig = await this.sendTransaction(syncIx
+            ? [...migrateIxs, reassignWithMetas, syncIx]
+            : [...migrateIxs, reassignWithMetas]);
+        return { id: sig };
+    }
+    /** Release a permabuy name back to the registry (creates a returned name auction). */
+    async releaseName(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
+        const [returnedNamePda] = await getReturnedNamePDA(params.name, this.arnsProgram);
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const record = await this.getArNSRecord({ name: params.name });
+        const antAsset = address(record.processId);
+        const ix = await getReleaseNameInstructionAsync(await this.withArnsDefaults({
+            arnsRecord,
+            returnedName: returnedNamePda,
+            antAsset,
+            caller: this.signer,
+        }), { programAddress: this.arnsProgram });
+        // Note: no sync_attributes bundle here — release_name closes the
+        // ArnsRecord PDA, so a follow-up sync would fail PDA validation. The
+        // asset's stale traits remain pointing at the released name; off-chain
+        // resolvers should treat ArnsRecord as the source of truth and ignore
+        // a "ArNS Name" trait that no longer resolves.
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Lazy-state crank steps — materialize accumulator/period state.
+    // Both are permissionless + idempotent (safe to crank on a schedule).
+    // =========================================
+    /**
+     * 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.
+     */
+    async updateDemandFactor(_options) {
+        const [demandFactorPda] = await getDemandFactorPDA(this.arnsProgram);
+        const ix = getUpdateDemandFactorInstruction({ demandFactor: demandFactorPda, payer: this.signer }, { programAddress: this.arnsProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * 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.
+     */
+    async compoundDelegationRewards(params, _options) {
+        const ix = await this.buildCompoundDelegationRewardsInstruction(params);
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * 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.
+     */
+    async compoundDelegationRewardsBatch(delegations, _options) {
+        if (delegations.length === 0) {
+            throw new Error('compoundDelegationRewardsBatch: delegations list is empty');
+        }
+        const ixs = await Promise.all(delegations.map((d) => this.buildCompoundDelegationRewardsInstruction(d)));
+        const sig = await this.sendTransaction(ixs, 1_400_000);
+        return { id: sig };
+    }
+    /**
+     * 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.
+     */
+    async buildCompoundDelegationRewardsInstruction(params) {
+        const gateway = address(params.gateway);
+        const delegator = address(params.delegator);
+        const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(gateway, delegator, this.garProgram);
+        return getCompoundDelegationRewardsInstruction({ gateway: gatewayPda, delegation: delegationPda, delegator }, { programAddress: this.garProgram });
+    }
+    // =========================================
+    // Epoch cranking (ario-gar) — permissionless
+    // =========================================
+    /**
+     * Create a new epoch. Permissionless — anyone can call when the next
+     * epoch's start time has arrived.
+     */
+    async createEpoch(_options) {
+        const garConfig = await this.getGarConfig();
+        const [epochSettingsPda] = await getEpochSettingsPDA(this.garProgram);
+        const settingsAccount = await fetchEncodedAccount(this.rpc, epochSettingsPda, { commitment: this.commitment });
+        if (!settingsAccount.exists)
+            throw new Error('EpochSettings not found');
+        const settings = deserializeEpochSettingsFull(Buffer.from(settingsAccount.data));
+        const epochIndex = settings.currentEpochIndex;
+        const [epochPda] = await getEpochPDA(epochIndex, this.garProgram);
+        const ix = await getCreateEpochInstructionAsync(await this.withGarDefaults({
+            epoch: epochPda,
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            payer: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * 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`.
+     */
+    async tallyWeights(params, _options) {
+        const ix = await getTallyWeightsInstructionAsync(await this.withGarDefaults({
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const remaining = params.gatewayAccounts.map((address) => ({
+            address,
+            role: AccountRole.WRITABLE,
+        }));
+        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * 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.
+     */
+    async prescribeEpoch(params, _options) {
+        const ix = await getPrescribeEpochInstructionAsync(await this.withGarDefaults({
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const remaining = params.gatewayAccounts.map((address) => ({
+            address,
+            role: AccountRole.READONLY,
+        }));
+        if (params.nameRegistryAccount) {
+            remaining.push({
+                address: params.nameRegistryAccount,
+                role: AccountRole.READONLY,
+            });
+        }
+        const fullIx = withRemainingAccounts(ix, remaining);
+        // A prescribe tx with the selected observer set (~50 PDAs) exceeds Solana's
+        // 1232-byte limit once there are more than ~24 remaining accounts, so route
+        // those through an ephemeral Address Lookup Table (create → extend →
+        // compressed v0 tx). Small sets (sparse testnets) take the cheaper inline
+        // path. `prescribe_epoch` searches `remaining_accounts` by PDA, so serving
+        // them via the ALT (which preserves instruction account order) is
+        // transparent — incl. NameRegistry staying last. Validated on staging
+        // (667 gateways, 50 observers): 428k CU, name prescription intact.
+        if (remaining.length > 24) {
+            const id = await sendWithEphemeralLookupTable({
+                rpc: this.rpc,
+                rpcSubscriptions: this.rpcSubscriptions,
+                signer: this.signer,
+                instruction: fullIx,
+                lookupAddresses: remaining.map((a) => a.address),
+                commitment: this.commitment,
+                computeUnitLimit: 1_000_000,
+            });
+            return { id };
+        }
+        const sig = await this.sendTransaction([fullIx], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Distribute rewards for a completed epoch in batches. Permissionless —
+     * call after epoch ends. Gateway PDAs appended as `remaining_accounts`.
+     */
+    async distributeEpoch(params, _options) {
+        const garConfig = await this.getGarConfig();
+        // ario_gar::distribute_epoch CPIs into ario_core::release_treasury_to_recipient
+        // (signed by the ArioConfig PDA — the canonical treasury authority). The
+        // generated builder expects `arioConfig` + `arioCoreProgram` accounts at
+        // positions 6+7 (post-PR-19 in ar-io-solana-contracts). Pin both to the
+        // configured core program so devnet/testnet deployments don't fall back
+        // to the bundled mainnet default.
+        const [arioConfig] = await getArioConfigPDA(this.coreProgram);
+        const ix = await getDistributeEpochInstructionAsync(await this.withGarDefaults({
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            arioConfig,
+            arioCoreProgram: this.coreProgram,
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const remaining = params.gatewayAccounts.map((address) => ({
+            address,
+            role: AccountRole.WRITABLE,
+        }));
+        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Close an old epoch account and reclaim rent. Permissionless — call after
+     * the epoch is distributed and at least 7 epochs have passed.
+     */
+    async closeEpoch(params, _options) {
+        const ix = await getCloseEpochInstructionAsync(await this.withGarDefaults({
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Cranker helpers
+    // =========================================
+    /**
+     * Get gateway PDAs for a batch starting at registryIndex.
+     * Reads the GatewayRegistry and derives PDAs for the next `batchSize`
+     * active gateways.
+     */
+    async getRegistryGatewayPDAs(startIndex, batchSize) {
+        const [registryPda] = await getGatewayRegistryPDA(this.garProgram);
+        const registryAccount = await fetchEncodedAccount(this.rpc, registryPda, {
+            commitment: this.commitment,
+        });
+        if (!registryAccount.exists)
+            return [];
+        const registryData = Buffer.from(registryAccount.data);
+        const count = registryData.readUInt32LE(40); // 8 disc + 32 authority
+        const slotsOffset = 48; // 8 + 32 + 4 + 4
+        // GatewaySlot: address(32) + composite_weight(8) + start_timestamp(8)
+        //            + status(1) + _padding(7) = 56 bytes.
+        const SLOT_STRIDE = 56;
+        const pdas = [];
+        const end = Math.min(startIndex + batchSize, count);
+        const zero = '11111111111111111111111111111111';
+        for (let i = startIndex; i < end && i < 3000; i++) {
+            const slotOffset = slotsOffset + i * SLOT_STRIDE;
+            const addr = addressDecoder.decode(registryData.subarray(slotOffset, slotOffset + 32));
+            if (addr === zero)
+                continue;
+            const [gatewayPda] = await getGatewayPDA(addr, this.garProgram);
+            pdas.push(gatewayPda);
+        }
+        return pdas;
+    }
+    /** Get ALL active gateway PDAs from the registry. */
+    async getAllRegistryGatewayPDAs() {
+        const [registryPda] = await getGatewayRegistryPDA(this.garProgram);
+        const registryAccount = await fetchEncodedAccount(this.rpc, registryPda, {
+            commitment: this.commitment,
+        });
+        if (!registryAccount.exists)
+            return [];
+        const registryData = Buffer.from(registryAccount.data);
+        const count = registryData.readUInt32LE(40);
+        const slotsOffset = 48;
+        const SLOT_STRIDE = 56;
+        const pdas = [];
+        const zero = '11111111111111111111111111111111';
+        for (let i = 0; i < count && i < 3000; i++) {
+            const slotOffset = slotsOffset + i * SLOT_STRIDE;
+            const addr = addressDecoder.decode(registryData.subarray(slotOffset, slotOffset + 32));
+            if (addr === zero)
+                continue;
+            const [gatewayPda] = await getGatewayPDA(addr, this.garProgram);
+            pdas.push(gatewayPda);
+        }
+        return pdas;
+    }
+    /**
+     * 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.
+     */
+    async getPredictedObserverPDAs(epochIndex) {
+        // --- Epoch: hashchain (frozen entropy) + active_gateway_count (walk bound) ---
+        const [epochPda] = await getEpochPDA(epochIndex, this.garProgram);
+        const epochAccount = await fetchEncodedAccount(this.rpc, epochPda, {
+            commitment: this.commitment,
+        });
+        if (!epochAccount.exists)
+            throw new Error(`Epoch ${epochIndex} not found`);
+        const epochData = Buffer.from(epochAccount.data);
+        // After the 8-byte discriminator (see fetchEpochRawFields): 9×u64 = 72
+        // bytes, then hashchain[32], then active_gateway_count(u32).
+        const EPOCH_BASE = 8;
+        const hashchain = epochData.subarray(EPOCH_BASE + 72, EPOCH_BASE + 72 + 32);
+        const activeGatewayCount = epochData.readUInt32LE(EPOCH_BASE + 104);
+        // --- Registry: slots[0..activeGatewayCount] (address + composite_weight) ---
+        const [registryPda] = await getGatewayRegistryPDA(this.garProgram);
+        const registryAccount = await fetchEncodedAccount(this.rpc, registryPda, {
+            commitment: this.commitment,
+        });
+        if (!registryAccount.exists)
+            throw new Error('GatewayRegistry not found');
+        const registryData = Buffer.from(registryAccount.data);
+        const registryCount = registryData.readUInt32LE(40); // 8 disc + 32 authority
+        const SLOTS_OFFSET = 48; // 8 + 32 + 4 count + 4 pad
+        const SLOT_STRIDE = 56; // address(32)+weight(8)+start_ts(8)+status(1)+pad(7)
+        // Walk exactly the on-chain prefix. The roulette uses
+        // registry.gateways[0..epoch.active_gateway_count]; include zero-weight
+        // slots so the cumulative walk and weight sum match byte-for-byte.
+        const walkCount = Math.min(activeGatewayCount, registryCount, 3000);
+        const slots = [];
+        for (let i = 0; i < walkCount; i++) {
+            const slotOffset = SLOTS_OFFSET + i * SLOT_STRIDE;
+            slots.push({
+                address: addressDecoder.decode(registryData.subarray(slotOffset, slotOffset + 32)),
+                compositeWeight: registryData.readBigUInt64LE(slotOffset + 32),
+            });
+        }
+        // --- Epoch settings: prescribed_observer_count ---
+        const [epochSettingsPda] = await getEpochSettingsPDA(this.garProgram);
+        const settingsAccount = await fetchEncodedAccount(this.rpc, epochSettingsPda, {
+            commitment: this.commitment,
+        });
+        if (!settingsAccount.exists)
+            throw new Error('EpochSettings not found');
+        const settings = deserializeEpochSettingsFull(Buffer.from(settingsAccount.data));
+        // --- Predict selected operators, then derive their Gateway PDAs ---
+        const operators = predictPrescribedObservers(hashchain, slots, settings.prescribedObserverCount);
+        const pdas = [];
+        for (const operator of operators) {
+            const [gatewayPda] = await getGatewayPDA(operator, this.garProgram);
+            pdas.push(gatewayPda);
+        }
+        return pdas;
+    }
+    /**
+     * 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.
+     */
+    async reclaimLookupTableRent(opts) {
+        return reclaimLookupTablesForSigner({
+            rpc: this.rpc,
+            rpcSubscriptions: this.rpcSubscriptions,
+            signer: this.signer,
+            allowedEntryOwners: [this.garProgram, this.arnsProgram],
+            commitment: this.commitment,
+            maxTables: opts?.maxTables,
+            scanLimit: opts?.scanLimit,
+        });
+    }
+    /** Read and deserialize the full EpochSettings account. */
+    async getEpochSettingsFull() {
+        const [esPda] = await getEpochSettingsPDA(this.garProgram);
+        const account = await fetchEncodedAccount(this.rpc, esPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            throw new Error('EpochSettings not found');
+        return deserializeEpochSettingsFull(Buffer.from(account.data));
+    }
+    /**
+     * 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).
+     */
+    async prescribeWithPrediction(epochIndex, nameRegistryAccount) {
+        const submit = async () => this.prescribeEpoch({
+            epochIndex,
+            gatewayAccounts: await this.getPredictedObserverPDAs(epochIndex),
+            nameRegistryAccount,
+        });
+        try {
+            return await submit();
+        }
+        catch (err) {
+            if (!isInvalidGatewayAccountError(err))
+                throw err;
+            return submit();
+        }
+    }
+    /**
+     * 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.
+     */
+    async crankEpochStep(opts = {}) {
+        // tally_weights / distribute_epoch append the batch's Gateway PDAs as
+        // remaining_accounts. distribute also CPIs into ario-core (treasury
+        // release) so it carries 10 named accounts; with ~18+ gateway PDAs on top
+        // the tx exceeds Solana's 1232-byte limit. Cap the lifecycle batch at 18 so
+        // an oversized caller `batchSize` can't produce an unsendable tx (verified:
+        // 30 gateways → 1527B; 18 → ~1050B). prescribe is the exception — it needs
+        // ALL selected observers in one tx, so it uses an ALT instead (see
+        // prescribeEpoch).
+        const MAX_LIFECYCLE_BATCH = 18;
+        const batchSize = Math.min(opts.batchSize ?? MAX_LIFECYCLE_BATCH, MAX_LIFECYCLE_BATCH);
+        const enableClose = opts.enableClose ?? true;
+        const retention = opts.epochRetention ?? 7;
+        const enableCompound = opts.enableCompound ?? true;
+        const compoundMinPending = opts.compoundMinPendingRewards ?? 0;
+        const enableDemandFactorRoll = opts.enableDemandFactorRoll ?? true;
+        const enablePrune = opts.enablePrune ?? true;
+        const now = opts.now ?? Math.floor(Date.now() / 1000);
+        const settings = await this.getEpochSettingsFull();
+        if (!settings.enabled)
+            return { action: 'idle', reason: 'epochs_disabled' };
+        const currentIndex = settings.currentEpochIndex;
+        // currentIndex is the NEXT epoch to create; the live one is currentIndex-1.
+        const targetEpochIndex = currentIndex > 0 ? currentIndex - 1 : 0;
+        const nextEpochStart = settings.genesisTimestamp + currentIndex * settings.epochDuration;
+        const epoch = await this.getEpochRaw(targetEpochIndex);
+        // Cold start: the live epoch (targetEpochIndex) doesn't exist yet. Two cases,
+        // handled identically — `create_epoch` always creates epoch[currentIndex] and
+        // then increments the counter, so the NEXT crank finds it live at currentIndex-1:
+        //   1. Genesis: currentIndex === 0 → create epoch 0.
+        //   2. AO→Solana continuity cold start: `admin_set_current_epoch_index` jumped
+        //      currentIndex to e.g. 454 with NO prior epochs on-chain (the AO-side
+        //      epochs were never created on Solana). targetEpochIndex (453) points at
+        //      an epoch that will never exist, so the old `currentIndex === 0`-only
+        //      bootstrap deadlocked here ('waiting_for_epoch' forever). Create
+        //      epoch[currentIndex] (454) directly — its start was re-anchored to ≈now.
+        if (!epoch) {
+            if (now < nextEpochStart)
+                return {
+                    action: 'idle',
+                    reason: currentIndex === 0 ? 'waiting_for_genesis' : 'waiting_for_epoch',
+                };
+            const { id } = await this.createEpoch();
+            return { action: 'create', epochIndex: currentIndex, txId: id };
+        }
+        // Tally (batched). activeGatewayCount===0 still needs one tx to flip the flag.
+        if (epoch.weightsTallied === 0) {
+            const gatewayAccounts = epoch.activeGatewayCount > 0
+                ? await this.getRegistryGatewayPDAs(epoch.tallyIndex, batchSize)
+                : [];
+            const { id } = await this.tallyWeights({
+                epochIndex: targetEpochIndex,
+                gatewayAccounts,
+            });
+            return {
+                action: 'tally',
+                epochIndex: targetEpochIndex,
+                txId: id,
+                progress: { index: epoch.tallyIndex, total: epoch.activeGatewayCount },
+            };
+        }
+        // Prescribe (predicted observers only — the size-safe path).
+        if (epoch.prescriptionsDone === 0) {
+            const nameRegistryAccount = opts.nameRegistryAccount === null
+                ? undefined
+                : (opts.nameRegistryAccount ??
+                    (await getArnsRegistryPDA(this.arnsProgram))[0]);
+            const { id } = await this.prescribeWithPrediction(targetEpochIndex, nameRegistryAccount);
+            return { action: 'prescribe', epochIndex: targetEpochIndex, txId: id };
+        }
+        // Observations happen while the epoch is live. This is the dominant idle
+        // window — fold returned-name pruning in here so it isn't starved on
+        // clusters whose epochs park here (e.g. imported gateways that can't
+        // observe → distribution never advances → the post-distribution tail below
+        // is never reached).
+        if (now < epoch.endTimestamp) {
+            if (enablePrune) {
+                const pruned = await this.maybePruneReturnedNamesStep(opts, now);
+                if (pruned)
+                    return pruned;
+            }
+            return { action: 'idle', reason: 'waiting_for_observations' };
+        }
+        // Distribute (batched).
+        if (epoch.rewardsDistributed === 0) {
+            const gatewayAccounts = epoch.activeGatewayCount > 0
+                ? await this.getRegistryGatewayPDAs(epoch.distributionIndex, batchSize)
+                : [];
+            const { id } = await this.distributeEpoch({
+                epochIndex: targetEpochIndex,
+                gatewayAccounts,
+            });
+            return {
+                action: 'distribute',
+                epochIndex: targetEpochIndex,
+                txId: id,
+                progress: {
+                    index: epoch.distributionIndex,
+                    total: epoch.activeGatewayCount,
+                },
+            };
+        }
+        // Close a fully-distributed epoch past retention (GAR-006).
+        //
+        // CRITICAL: this is cleanup of OLD epochs and must NEVER block creation of
+        // NEW ones. `close_epoch` reverts with EpochObservationsNotClosed until the
+        // epoch's Observation PDAs are closed (observations_closed ==
+        // observations_submitted), so we close those FIRST. The whole branch is
+        // wrapped so any failure falls through to create-next instead of throwing
+        // out of crankEpochStep — otherwise a single un-closeable epoch wedges epoch
+        // progression network-wide (every operator's crank hits the same wall).
+        if (enableClose && targetEpochIndex >= retention) {
+            const closeTarget = targetEpochIndex - retention;
+            try {
+                const old = await this.getEpochRaw(closeTarget);
+                if (old && old.rewardsDistributed === 1) {
+                    if (old.observationsSubmitted > old.observationsClosed) {
+                        // Open observations remain — close a batch before close_epoch.
+                        const observers = await this.getEpochObservers(closeTarget);
+                        if (observers.length > 0) {
+                            const batch = observers.slice(0, MAX_CLOSE_OBSERVATION_BATCH);
+                            const { id } = await this.closeObservations({
+                                epochIndex: closeTarget,
+                                observers: batch,
+                            });
+                            return {
+                                action: 'close_observation',
+                                epochIndex: closeTarget,
+                                txId: id,
+                                progress: { index: batch.length, total: observers.length },
+                            };
+                        }
+                        // Counter says open but no Observation PDA exists (orphaned counter):
+                        // can't close it, so don't attempt close_epoch (it would revert) and
+                        // don't wedge — fall through to create-next.
+                    }
+                    else {
+                        const { id } = await this.closeEpoch({ epochIndex: closeTarget });
+                        return { action: 'close', epochIndex: closeTarget, txId: id };
+                    }
+                }
+            }
+            catch {
+                // Best-effort cleanup — never block epoch creation. Retried next tick.
+            }
+        }
+        // Lazy-state maintenance — lower urgency than the lifecycle, reached only
+        // once the live epoch is fully distributed (rewardsDistributed === 1 here).
+        // Compound FIRST so delegated stake reflects the just-distributed rewards
+        // before the next epoch's tally weights it; then roll the demand factor if
+        // its period elapsed. Both are permissionless + idempotent, and run BEFORE
+        // creating the next epoch so the compounded stake is in place for its tally.
+        if (enableCompound) {
+            const compounded = await this.maybeCompoundStep(compoundMinPending);
+            if (compounded)
+                return compounded;
+        }
+        if (enableDemandFactorRoll) {
+            const rolled = await this.maybeRollDemandFactorStep(now);
+            if (rolled)
+                return rolled;
+        }
+        if (enablePrune) {
+            const pruned = await this.maybePruneReturnedNamesStep(opts, now);
+            if (pruned)
+                return pruned;
+        }
+        // Current epoch fully processed — create the next once its start arrives.
+        if (now >= nextEpochStart) {
+            const { id } = await this.createEpoch();
+            return { action: 'create', epochIndex: currentIndex, txId: id };
+        }
+        return { action: 'idle', reason: 'epoch_complete' };
+    }
+    /**
+     * 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.
+     */
+    async maybeCompoundStep(minPendingRewards) {
+        const pending = await this.getDelegationsToCompound({ minPendingRewards });
+        if (pending.length === 0)
+            return null;
+        const batch = pending.slice(0, MAX_COMPOUND_BATCH).map((p) => ({
+            gateway: p.gatewayAddress,
+            delegator: p.delegatorAddress,
+        }));
+        const { id } = await this.compoundDelegationRewardsBatch(batch);
+        return {
+            action: 'compound',
+            txId: id,
+            progress: { index: batch.length, total: pending.length },
+        };
+    }
+    /**
+     * 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.
+     */
+    async maybeRollDemandFactorStep(now) {
+        const state = await this.getDemandFactorPeriodState();
+        if (!state)
+            return null;
+        const elapsed = now - state.periodZeroStartTimestamp;
+        const periodForNow = elapsed < 0 ? 1 : Math.floor(elapsed / DEMAND_FACTOR_PERIOD_SECONDS) + 1;
+        if (periodForNow <= state.currentPeriod)
+            return null; // same period — no-op
+        const { id } = await this.updateDemandFactor();
+        return { action: 'update_demand_factor', txId: id };
+    }
+    /** Wall-clock (ms) of the last returned-name prune scan; throttles the
+     *  getProgramAccounts scan below the crank poll rate. */
+    lastReturnedNamePruneScanMs = 0;
+    /**
+     * 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.
+     */
+    async maybePruneReturnedNamesStep(opts, now) {
+        const scanInterval = opts.pruneScanIntervalMs ?? 60_000;
+        const wallNow = Date.now();
+        if (wallNow - this.lastReturnedNamePruneScanMs < scanInterval)
+            return null;
+        this.lastReturnedNamePruneScanMs = wallNow;
+        const expired = await this.getExpiredReturnedNames(now);
+        if (expired.length === 0)
+            return null;
+        const batchSize = opts.pruneBatchSize ?? 15;
+        const batch = expired.slice(0, batchSize).map((r) => r.pubkey);
+        const { id } = await this.pruneReturnedNames({
+            maxNames: batch.length,
+            returnedNames: batch,
+        });
+        return {
+            action: 'prune_returned_names',
+            txId: id,
+            progress: { index: batch.length, total: expired.length },
+        };
+    }
+    /**
+     * The DemandFactor account's stored period + period-zero start (seconds) —
+     * the gate for {@link maybeRollDemandFactorStep}. `null` if the account
+     * doesn't exist (pre-genesis).
+     */
+    async getDemandFactorPeriodState() {
+        const [pda] = await getDemandFactorPDA(this.arnsProgram);
+        const account = await fetchEncodedAccount(this.rpc, pda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return null;
+        const df = deserializeDemandFactor(Buffer.from(account.data));
+        return {
+            currentPeriod: df.currentPeriod,
+            periodZeroStartTimestamp: df.periodZeroStartTimestamp,
+        };
+    }
+    /**
+     * Read the raw epoch account data for cranker state inspection.
+     * Returns null if the epoch account doesn't exist yet.
+     */
+    async getEpochRaw(epochIndex) {
+        const [epochPda] = await getEpochPDA(epochIndex, this.garProgram);
+        const account = await fetchEncodedAccount(this.rpc, epochPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return null;
+        try {
+            return this.fetchEpochRawFields(Buffer.from(account.data));
+        }
+        catch {
+            return 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.
+     */
+    fetchEpochRawFields(data) {
+        const base = 8;
+        const endTimestamp = Number(data.readBigInt64LE(base + 16));
+        const activeGatewayCount = data.readUInt32LE(base + 104);
+        const distributionIndex = data.readUInt32LE(base + 108);
+        const tallyIndex = data.readUInt32LE(base + 112);
+        const observationsSubmitted = data.readUInt8(base + 118);
+        const rewardsDistributed = data.readUInt8(base + 119);
+        const weightsTallied = data.readUInt8(base + 120);
+        const prescriptionsDone = data.readUInt8(base + 121);
+        const observationsClosed = data.readUInt8(base + 123);
+        return {
+            tallyIndex,
+            distributionIndex,
+            weightsTallied,
+            prescriptionsDone,
+            rewardsDistributed,
+            observationsSubmitted,
+            observationsClosed,
+            activeGatewayCount,
+            endTimestamp,
+        };
+    }
+    // =========================================
+    // Prune / cleanup (permissionless crank)
+    // =========================================
+    //
+    // These mirror `tick()`-driven lazy pruning in the Lua source — on Solana
+    // each is a discrete instruction someone has to call. All are
+    // permissionless except `releaseVault`, which the on-chain handler still
+    // gates on `owner: Signer` (ADR / vault.rs::ReleaseVault). See
+    // docs/CRANKER_PRUNING_PLAN.md for the full design.
+    /**
+     * 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.
+     */
+    async pruneExpiredNames(params, _options) {
+        const ix = await getPruneExpiredNamesInstructionAsync(await this.withArnsDefaults({
+            payer: this.signer,
+            maxNames: params.maxNames,
+        }), { programAddress: this.arnsProgram });
+        const remaining = params.arnsRecords.map((a) => ({
+            address: address(a),
+            role: AccountRole.WRITABLE,
+        }));
+        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Convert a single expired-but-not-yet-returned lease into a `ReturnedName`
+     * (kicks off the Dutch auction). Permissionless.
+     */
+    async pruneNameToReturned(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const [returnedName] = await getReturnedNamePDA(params.name, this.arnsProgram);
+        const ix = await getPruneNameToReturnedInstructionAsync(await this.withArnsDefaults({
+            arnsRecord,
+            returnedName,
+            payer: this.signer,
+        }), { programAddress: this.arnsProgram });
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
+        return { id: sig };
+    }
+    /**
+     * 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).
+     */
+    async pruneReturnedNames(params, _options) {
+        const ix = await getPruneReturnedNamesInstructionAsync(await this.withArnsDefaults({
+            payer: this.signer,
+            maxNames: params.maxNames,
+        }), { programAddress: this.arnsProgram });
+        const remaining = params.returnedNames.map((a) => ({
+            address: address(a),
+            role: AccountRole.WRITABLE,
+        }));
+        // Match `pruneExpiredNames` (1M CU) — both dispatch the same batched
+        // shape over `remaining_accounts`, and the default 400K is too tight
+        // when the cranker batches near `maxNames` (≈15) on a busy registry.
+        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Close a single expired ReservedName PDA. Permissionless after
+     * `expires_at`.
+     */
+    async pruneExpiredReservation(params, _options) {
+        const [reservedName] = await getReservedNamePDA(params.name, this.arnsProgram);
+        const ix = getPruneExpiredReservationInstruction({
+            reservedName,
+            payer: this.signer,
+        }, { programAddress: this.arnsProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * 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.
+     */
+    async pruneGateway(params, _options) {
+        const gatewayAddr = address(params.gateway);
+        const garConfig = await this.getGarConfig();
+        const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+        const [withdrawalCounterPda] = await getWithdrawalCounterPDA(gatewayAddr, this.garProgram);
+        const nextId = await this.getNextWithdrawalId(gatewayAddr);
+        const [withdrawalPda] = await getWithdrawalPDA(gatewayAddr, nextId, this.garProgram);
+        const [excessWithdrawalPda] = await getWithdrawalPDA(gatewayAddr, nextId + 1n, this.garProgram);
+        const ix = await getPruneGatewayInstructionAsync(await this.withGarDefaults({
+            gateway: gatewayPda,
+            withdrawalCounter: withdrawalCounterPda,
+            withdrawal: withdrawalPda,
+            excessWithdrawal: excessWithdrawalPda,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            payer: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * GC a `Leaving`/`Gone` gateway whose leave window has fully elapsed.
+     * Closes the Gateway PDA and refunds rent to the caller. Permissionless.
+     */
+    async finalizeGone(params, _options) {
+        const gatewayAddr = address(params.gateway);
+        const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+        // `finalize_gone` reclaims this gateway's compact-registry slot by
+        // swap-removing the LAST active slot into it. When this gateway is not the
+        // last slot, the on-chain handler rewrites the swapped gateway's stored
+        // registry_index and therefore requires that swapped Gateway PDA as
+        // writable remaining_accounts[0]
+        // (programs/ario-gar/src/instructions/gateway.rs::finalize_gone). Read the
+        // gateway's slot index + the active registry to decide.
+        const gatewayAccount = await fetchEncodedAccount(this.rpc, gatewayPda, {
+            commitment: this.commitment,
+        });
+        if (!gatewayAccount.exists) {
+            throw new Error(`Gateway not found for operator ${params.gateway}`);
+        }
+        const gateway = getGatewayDecoder().decode(gatewayAccount.data);
+        const registryAddresses = await this.getRegistryGatewayAddresses();
+        const swappedOperator = selectFinalizeGoneSwapOperator(gateway.registryIndex.index, registryAddresses);
+        const ix = await getFinalizeGoneInstructionAsync(await this.withGarDefaults({
+            gateway: gatewayPda,
+            caller: this.signer,
+        }), { programAddress: this.garProgram });
+        let finalIx = ix;
+        if (swappedOperator !== null) {
+            const [swappedGatewayPda] = await getGatewayPDA(address(swappedOperator), this.garProgram);
+            finalIx = withRemainingAccounts(ix, [
+                { address: swappedGatewayPda, role: AccountRole.WRITABLE },
+            ]);
+        }
+        const sig = await this.sendTransaction([finalIx]);
+        return { id: sig };
+    }
+    /**
+     * Reclaim rent from an Observation PDA whose epoch has been distributed.
+     * Permissionless. Pass `epochIndex` and the `observer` address used as
+     * the Observation seed.
+     */
+    async closeObservation(params, _options) {
+        const observerAddr = address(params.observer);
+        const [observationPda] = await getObservationPDA(params.epochIndex, observerAddr, this.garProgram);
+        const ix = await getCloseObservationInstructionAsync({
+            observation: observationPda,
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * 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.
+     */
+    async closeObservations(params, _options) {
+        if (params.observers.length === 0) {
+            throw new Error('closeObservations: observers must be non-empty');
+        }
+        const ixs = await Promise.all(params.observers.map(async (obs) => {
+            const [observationPda] = await getObservationPDA(params.epochIndex, address(obs), this.garProgram);
+            return getCloseObservationInstructionAsync({
+                observation: observationPda,
+                payer: this.signer,
+                epochIndex: BigInt(params.epochIndex),
+            }, { programAddress: this.garProgram });
+        }));
+        const sig = await this.sendTransaction(ixs);
+        return { id: sig };
+    }
+    /**
+     * Close an empty Delegation PDA (`amount == 0`) and refund rent to the
+     * original delegator (NOT the caller — see GAR-016, prevents griefing).
+     * Permissionless.
+     */
+    async closeEmptyDelegation(params, _options) {
+        const gatewayAddr = address(params.gateway);
+        const delegatorAddr = address(params.delegator);
+        const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(gatewayAddr, delegatorAddr, this.garProgram);
+        const ix = getCloseEmptyDelegationInstruction({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            delegator: delegatorAddr,
+            payer: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Close a drained Withdrawal PDA (`amount == 0`) and refund rent to the
+     * original owner (NOT the caller). Permissionless.
+     */
+    async closeDrainedWithdrawal(params, _options) {
+        const ownerAddr = address(params.owner);
+        const [withdrawalPda] = await getWithdrawalPDA(ownerAddr, BigInt(params.withdrawalId), this.garProgram);
+        const ix = getCloseDrainedWithdrawalInstruction({
+            withdrawal: withdrawalPda,
+            owner: ownerAddr,
+            closer: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+}