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

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

@@ -1,5 +1,20 @@
 /**
- * Solana implementation of AoARIOWrite interface.
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Solana implementation of ARIOWrite interface.
  *
  * Extends SolanaARIOReadable with write operations that build and send
  * Solana transactions via Codama-generated instruction builders.
@@ -18,11 +33,11 @@
  *      epoch crank instructions, since Codama doesn't generate a typed
  *      surface for them.
  */
-import { AccountRole, address, fetchEncodedAccount, getAddressDecoder, } from '@solana/kit';
-import { PurchaseType, getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from '@ar.io/solana-contracts/arns';
+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, deserializeEpochSettingsFull, } from './deserialize.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. */
@@ -36,14 +51,15 @@ function toGeneratedFundingSourceSpec(s) {
     return { kind: kindMap[s.kind], amount: s.amount };
 }
 import { getSyncAttributesInstruction } from '@ar.io/solana-contracts/ant';
-import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestAndSetPrimaryNameInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
+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, getClaimDelegateFromLeavingGatewayInstructionAsync, getClaimWithdrawalInstructionAsync, getCloseDrainedWithdrawalInstruction, getCloseEmptyDelegationInstruction, getCloseEpochInstructionAsync, getCloseObservationInstructionAsync, getCreateEpochInstructionAsync, getDecreaseDelegateStakeInstructionAsync, getDecreaseOperatorStakeInstructionAsync, getDelegateStakeInstructionAsync, getDisallowDelegateInstructionAsync, getDistributeEpochInstructionAsync, getFinalizeGoneInstructionAsync, getIncreaseOperatorStakeInstructionAsync, getInstantWithdrawalInstructionAsync, getJoinNetworkInstructionAsync, getLeaveNetworkInstructionAsync, getPrescribeEpochInstructionAsync, getPruneGatewayInstructionAsync, getRedelegateStakeInstructionAsync, getSaveObservationsInstructionAsync, getSetAllowlistEnabledInstructionAsync, getTallyWeightsInstructionAsync, getUpdateGatewaySettingsInstructionAsync, } 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 { TOKEN_DECIMALS } from './constants.js';
+import { ARIO_ANT_PROGRAM_ID, TOKEN_DECIMALS } from './constants.js';
 import { SolanaARIOReadable } from './io-readable.js';
-import { 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 { sendAndConfirm } from './send.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) {
@@ -68,6 +84,36 @@ function withRemainingAccounts(ix, 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`:
@@ -181,6 +227,47 @@ export function encodeReportTxId(reportTxId) {
     decoded.copy(out);
     return out;
 }
+/**
+ * Max `compound_delegation_rewards` instructions packed into one batched tx.
+ * Each is a SEPARATE instruction carrying a gateway + delegation + delegator
+ * account, so — unlike the single-ix `remaining_accounts` lifecycle batch (see
+ * `MAX_LIFECYCLE_BATCH`) and unlike prescribe (which uses an ALT) — the per-item
+ * tx cost is high and there is nothing to compress. Cap low enough that a full
+ * worst-case batch (all-distinct gateways → no account dedup) stays under
+ * Solana's 1232-byte transaction limit. A full batch of 12 overflows it and
+ * wedged epoch progression on staging-V2 (the RPC rejected the tx — observed at
+ * 1928B base64, well over the 1232B raw cap). Exported so the regression test in
+ * `compound-crank.test.ts` asserts this invariant against the live constant.
+ */
+export const MAX_COMPOUND_BATCH = 6;
+/** 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;
@@ -280,6 +367,35 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         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);
@@ -493,25 +609,50 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         return { id: sig };
     }
     async updateGatewaySettings(params, _options) {
-        const ix = 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 });
-        const sig = await this.sendTransaction([ix], 1_000_000);
+        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) {
@@ -572,6 +713,11 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             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) {
@@ -745,7 +891,16 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 params: buyNameParams,
             }, { programAddress: this.arnsProgram });
         }
-        else if (params.fundFrom === 'plan' || params.fundFrom === 'any') {
+        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,
@@ -756,8 +911,10 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 arnsConfig,
             });
         }
-        else {
-            // 'balance' or undefined falls through to the original direct-buy path.
+        else if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            // Direct balance-funded buy.
             ix = await getBuyNameInstructionAsync(await this.withArnsDefaults({
                 arnsRecord,
                 buyerTokenAccount: buyerATA,
@@ -768,6 +925,9 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 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).
@@ -837,12 +997,42 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             };
         }
         // 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
@@ -851,10 +1041,20 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             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;
     }
     /**
@@ -866,7 +1066,12 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         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._estimateBuyNameCost(args.buyNameParams);
+        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({
@@ -979,52 +1184,75 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         };
     }
     /**
-     * Best-effort cost estimation for `buy_name`. Reads the live DemandFactor
-     * + ArnsConfig and applies the on-chain pricing math. Used by the funding-
-     * plan path so callers don't have to compute cost client-side.
+     * Simulate the on-chain `get_token_cost` instruction and return the exact
+     * cost as a `bigint` (mARIO). This guarantees byte-exact agreement with the
+     * on-chain pricing math, avoiding integer-division rounding divergences
+     * that plagued the previous client-side reimplementation.
      *
-     * The estimate may be 1-2 mARIO higher than the actual on-chain cost when a
-     * demand-factor period rolls during the tx; the on-chain handler reads the
-     * live demand-factor and verifies sum(sources) == cost, so an overestimate
-     * fails fast with `FundingPlanAmountMismatch`. Callers should retry with a
-     * fresh estimate on that error.
+     * The program writes a LE-u64 cost into the transaction's return data;
+     * we parse it from the simulation result.
      */
-    async _estimateBuyNameCost(buyNameParams) {
-        // Importing the pricing helpers from generated/ would couple the SDK to
-        // codegen layout; instead we re-implement the same math (see
-        // programs/ario-arns/src/pricing.rs::calculate_registration_fee).
-        const [demandFactorPda] = await getDemandFactorPDA(this.arnsProgram);
-        const dfAccount = await fetchEncodedAccount(this.rpc, demandFactorPda, {
-            commitment: this.commitment,
+    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,
         });
-        if (!dfAccount.exists)
-            throw new Error('DemandFactor not found');
-        const data = Buffer.from(dfAccount.data);
-        const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
-        const demandFactor = dv.getBigUint64(8, true);
-        // DemandFactor layout (Borsh, packed; ario-arns/src/state/mod.rs):
-        //   disc(8) + current_demand_factor(u64) + current_period(u64) +
-        //   purchases_this_period(u64) + revenue_this_period(u64) +
-        //   consecutive_periods_with_min_demand_factor(u32) +
-        //   trailing_period_purchases([u64; 7]) +
-        //   trailing_period_revenues([u64; 7]) + fees([u64; 51]) + ...
-        // -> fees starts at 8 + 8 + 8 + 8 + 8 + 4 + 56 + 56 = 156.
-        const FEES_OFFSET = 156;
-        if (data.length < FEES_OFFSET + 51 * 8) {
-            throw new Error('DemandFactor account data too short for fees array');
-        }
-        const nameLen = buyNameParams.name.length;
-        const idx = Math.min(Math.max(nameLen, 1), 51) - 1;
-        const baseFee = dv.getBigUint64(FEES_OFFSET + idx * 8, true);
-        const SCALE = 1000000n; // DEMAND_FACTOR_SCALE
-        if (buyNameParams.purchaseType === PurchaseType.Permabuy) {
-            // Permabuy = base_fee * 20% * 20 (annual share × 20 years cap)
-            const permabuy = (baseFee * 200000n) / SCALE; // 20% annual
-            return (permabuy * 20n * demandFactor) / SCALE;
-        }
-        // Lease: base_fee * (1 + 0.20 * years) * demand_factor
-        const leasePct = SCALE + 200000n * BigInt(buyNameParams.years);
-        return (((baseFee * leasePct) / SCALE) * demandFactor) / SCALE;
+        // 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
@@ -1046,12 +1274,13 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         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 ? [ix, syncIx] : [ix]);
+        const sig = await this.sendTransaction(syncIx ? [...migrateIxs, ix, syncIx] : [...migrateIxs, ix]);
         return { id: sig };
     }
     async syncAttributes(params, _options) {
@@ -1061,8 +1290,9 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         // `_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([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -1130,6 +1360,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         }, { programAddress: this.antProgram });
     }
     async extendLease(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const ix = await this._buildManageStakeIx({
             params,
             operation: 'extend',
@@ -1137,17 +1368,18 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         });
         // 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([ix]);
+        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 ? [ix, syncIx] : [ix]);
+        const sig = await this.sendTransaction(syncIx ? [...migrateIxs, ix, syncIx] : [...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -1230,13 +1462,25 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 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') {
+        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 cost = await this._estimateManageStakeCost({
-                operation: args.operation,
+            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,
@@ -1274,56 +1518,77 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         }
         throw new Error(`unsupported fundFrom mode '${args.params.fundFrom}' for ${args.operation}`);
     }
+    // =========================================
+    // Primary name operations (ario-core)
+    // =========================================
     /**
-     * Cost estimate for manage operations (upgrade / extend / increaseUndername).
-     * Reads the live DemandFactor account + applies the on-chain pricing math.
+     * If the signer already has a primary name set, build the instruction(s)
+     * needed to remove it so they can be prepended to a request/set tx —
+     * enabling single-tx "change primary name" flows.
+     *
+     * Returns an empty array when the signer has no existing primary name.
+     *
+     * Throws when the signer has a legacy primary-name state (forward
+     * `PrimaryName` PDA exists but its paired `PrimaryNameReverse` PDA does
+     * NOT). Both `remove_primary_name` AND `request_and_set_primary_name`
+     * require the reverse PDA on-chain — the latter rejects with
+     * `MustRemoveExistingPrimaryName` (0x1786, code 6022) any time a
+     * forward record already exists for the signer, regardless of reverse
+     * state. Silently skipping the remove would queue a tx guaranteed to
+     * fail with that opaque error. Surfacing it at the client with a clear
+     * remediation pointer is the only safe behavior.
+     *
+     * The legacy state should not exist on any cluster post-snapshot/import
+     * PR #159 (which emits PrimaryNameReverse in lockstep with PrimaryName)
+     * — it's a relic of pre-#159 imports. Operators on affected clusters
+     * must run `yarn workspace @ar-io/migration-import backfill:primary-name-reverse`
+     * (in the solana-ar-io repo) before this method can succeed.
      */
-    async _estimateManageStakeCost(args) {
-        const [demandFactorPda] = await getDemandFactorPDA(this.arnsProgram);
-        const dfAccount = await fetchEncodedAccount(this.rpc, demandFactorPda, {
+    async _buildRemoveExistingPrimaryNameIxs() {
+        const [primaryNamePda] = await getPrimaryNamePDA(this.signer.address, this.coreProgram);
+        const account = await fetchEncodedAccount(this.rpc, primaryNamePda, {
             commitment: this.commitment,
         });
-        if (!dfAccount.exists)
-            throw new Error('DemandFactor not found');
-        const data = Buffer.from(dfAccount.data);
-        const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
-        const demandFactor = dv.getBigUint64(8, true);
-        const FEES_OFFSET = 156; // see DemandFactor layout note above
-        const idx = Math.min(Math.max(args.name.length, 1), 51) - 1;
-        const baseFee = dv.getBigUint64(FEES_OFFSET + idx * 8, true);
-        const SCALE = 1000000n;
-        if (args.operation === 'upgrade') {
-            // Permabuy upgrade: 20% × 20 × demand_factor
-            const permabuy = (baseFee * 200000n) / SCALE;
-            return (permabuy * 20n * demandFactor) / SCALE;
-        }
-        if (args.operation === 'extend') {
-            // Lease extension fee: base_fee * 0.20 * years * demand_factor
-            return ((baseFee * 200000n * BigInt(args.years) * demandFactor) /
-                SCALE /
-                SCALE);
-        }
-        // increaseUndername: base_fee * UNDERNAME_LEASE_FEE_PCT * quantity * demand_factor
-        // UNDERNAME_LEASE_FEE_PCT = 1% = 10_000 in RATE_SCALE = 1_000_000.
-        return ((baseFee * 10000n * BigInt(args.quantity) * demandFactor) /
-            SCALE /
-            SCALE);
+        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 }),
+        ];
     }
-    // =========================================
-    // Primary name operations (ario-core)
-    // =========================================
     /**
      * Build the `remaining_accounts` slice + the `antProgramId` arg the
      * four ario-core primary-name instructions consume. Sprint 2/5
      * reshape (ADR-016): ario-core no longer reads MPL Core asset bytes.
-     * Authorization is "caller is the AntRecord.owner for this name" via
-     * PDA-seed-pinned lookup.
+     * Authorization is "caller is the effective AntRecord owner for this
+     * name", resolved from the `AntRecord` + `AntConfig` PDAs (freshness-
+     * gated against `AntConfig.last_known_owner` — see ario-core BD-097 /
+     * BD-109). Both are program-PDA-pinned lookups.
      *
      * Layouts the on-chain handlers expect:
      *   request_primary_name:               [arnsRecord, demandFactor]
-     *   request_and_set_primary_name:       [arnsRecord, demandFactor, antRecord]
-     *   approve_primary_name:               [arnsRecord, antRecord]
-     *   remove_primary_name_for_base_name:  [arnsRecord, antRecord(@)]
+     *   request_and_set_primary_name:       [arnsRecord, demandFactor, antRecord, antConfig]
+     *   approve_primary_name:               [arnsRecord, antRecord, antConfig]
+     *   remove_primary_name_for_base_name:  [arnsRecord, antRecord(@), antConfig]
      *
      * `antRecord` keys off the undername part for undernames (e.g.
      * "blog_arweave" → AntRecord at "blog") or the canonical "@" sentinel
@@ -1333,10 +1598,13 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      *
      * `antProgram` honors ADR-016 / BD-100 pluggability: the asset's
      * `ANT Program` Attributes-plugin trait selects which program owns the
-     * AntRecord PDA. Absent / unparseable → canonical fallback. Both the
-     * PDA derivation here and the `ant_program_id` arg the caller passes
-     * to the on-chain ix MUST agree (the handler re-derives and rejects
-     * mismatches).
+     * AntRecord PDA. Absent / unparseable → canonical fallback. The detected
+     * trait is untrusted asset/RPC data, so it is honored only when it matches
+     * the canonical program or this client's explicitly-configured
+     * `this.antProgram`; any other value falls back to the configured program
+     * (see the SECURITY note in the body). Both the PDA derivation here and the
+     * `ant_program_id` arg the caller passes to the on-chain ix MUST agree (the
+     * handler re-derives and rejects mismatches).
      */
     async _buildPrimaryNameValidationAccounts(name, variant) {
         const { isUndername, baseName, undername } = splitPrimaryName(name);
@@ -1364,10 +1632,26 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             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 =
-                (await fetchAntProgramFromAsset(this.rpc, antMint, {
-                    commitment: this.commitment,
-                })) ?? this.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.
@@ -1376,10 +1660,24 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 : 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');
@@ -1405,13 +1703,18 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 operation: 'request',
             });
         }
-        const sig = await this.sendTransaction([ix]);
+        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');
@@ -1437,7 +1740,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 antProgramId: antProgram,
             });
         }
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...removeIxs, ...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -1454,19 +1757,10 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      * funding-source slice to ario-gar's pay_from_funding_plan via CPI.
      */
     async _buildPrimaryNameFromFundingPlanIx(args) {
-        // Estimate the fee — primary-name fee = PRIMARY_NAME_REQUEST_BASE_FEE *
-        // demand_factor / DEMAND_FACTOR_SCALE. Read demand_factor from chain.
-        const [demandFactorPda] = await getDemandFactorPDA(this.arnsProgram);
-        const dfAccount = await fetchEncodedAccount(this.rpc, demandFactorPda, {
-            commitment: this.commitment,
+        const fee = await this._simulateTokenCost({
+            intent: CostIntent.PrimaryNameRequest,
+            name: args.params.name,
         });
-        if (!dfAccount.exists)
-            throw new Error('DemandFactor not found');
-        const dv = new DataView(dfAccount.data.buffer, dfAccount.data.byteOffset, dfAccount.data.byteLength);
-        const demandFactor = dv.getBigUint64(8, true);
-        const PRIMARY_NAME_REQUEST_BASE_FEE = 200000n; // 0.2 ARIO in mARIO
-        const SCALE = 1000000n;
-        const fee = (PRIMARY_NAME_REQUEST_BASE_FEE * demandFactor) / SCALE;
         const plan = await this._resolveFundingPlan(args.params, fee);
         const garConfig = await this.getGarConfig();
         const [garSettings] = await getGarSettingsPDA(this.garProgram);
@@ -1522,14 +1816,24 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      *
      * Mirrors the on-chain `approve_primary_name` instruction
      * (`programs/ario-core/src/instructions/primary_name.rs`).
-     * remaining_accounts: [arns_record(base), ant_record(undername | @)].
+     * remaining_accounts: [arns_record(base), ant_record(undername | @), ant_config].
      */
     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');
-        const ix = withRemainingAccounts(await getApprovePrimaryNameInstructionAsync({
+        // 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,
@@ -1537,8 +1841,8 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             nameOwner: this.signer,
             reverseLookupHash: hashName(params.name),
             antProgramId: antProgram,
-        }, { programAddress: this.coreProgram }), remaining);
-        const sig = await this.sendTransaction([ix]);
+        }), { programAddress: this.coreProgram }), remaining);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     // =========================================
@@ -1621,6 +1925,47 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         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. */
@@ -1683,10 +2028,54 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             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;
-        if (!params.fundFrom ||
+        const useBalance = !params.fundFrom ||
             params.fundFrom === 'balance' ||
-            params.fundFrom === 'turbo') {
+            params.fundFrom === 'turbo' ||
+            (params.fundFrom === 'any' &&
+                resolvedGateway === undefined &&
+                resolvedWithdrawalId === undefined &&
+                !params.sources?.length);
+        if (useBalance) {
             ix = await getBuyReturnedNameInstructionAsync(await this.withArnsDefaults({
                 arnsRecord,
                 returnedName: returnedNamePda,
@@ -1715,10 +2104,10 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 garProgram: this.garProgram,
                 params: buyParams,
             };
-            if (params.fundFrom === 'stakes' && params.gatewayAddress) {
-                const gatewayAddr = address(params.gatewayAddress);
+            if (resolvedGateway !== undefined) {
+                const gatewayAddr = address(resolvedGateway);
                 const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
-                if (params.fundAsOperator) {
+                if (resolvedFundAsOperator) {
                     ix = await getBuyReturnedNameFromOperatorStakeInstructionAsync({ ...sharedReturnedBase, gateway: gatewayPda }, { programAddress: this.arnsProgram });
                 }
                 else {
@@ -1730,21 +2119,21 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                     }, { programAddress: this.arnsProgram });
                 }
             }
-            else if (params.fundFrom === 'withdrawal' &&
-                params.withdrawalId !== undefined) {
-                const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, params.withdrawalId, this.garProgram);
+            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.fundFrom === 'any') {
-                // Returned-name pricing is dynamic (Dutch auction premium); we trust
-                // explicit caller-supplied sources here and skip auto-discovery if
-                // sources is provided. For 'any' without sources, we fall back to a
-                // best-effort estimate using the plain registration fee — caller can
-                // always retry with explicit sources on FundingPlanAmountMismatch.
-                const cost = await this._estimateBuyNameCost({
+            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,
-                    purchaseType: buyParams.purchaseType,
                     years: buyParams.years,
+                    purchaseType: buyParams.purchaseType,
                 });
                 const plan = await this._resolveFundingPlan(params, cost);
                 const { remainingAccounts, withdrawalCounter, residueVaultCount } = await this._materializeFundingPlan(params, plan);
@@ -1763,54 +2152,108 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 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(syncIx ? [ix, syncIx] : [ix]);
+        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 });
-        // The on-chain handler validates the new ANT via `remaining_accounts[0]`
-        // (must be MPL-Core-owned + key matches `newAnt`). The codama builder
-        // for reassign_name only encodes the typed accounts above, so we tag
-        // the new ANT asset on as a readonly remaining account.
-        //
-        // Sprint 4 / ADR-016: 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).
+        // 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 ? [reassignWithMetas, syncIx] : [reassignWithMetas]);
+        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
@@ -1818,9 +2261,69 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         // 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
     // =========================================
@@ -1864,9 +2367,22 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     }
     /**
      * Prescribe observers and names for an epoch. Permissionless — call after
-     * weights are tallied. Gateway PDAs are appended as `remaining_accounts`,
-     * and the optional `nameRegistryAccount` (must be last) enables the name
+     * weights are tallied.
+     *
+     * `gatewayAccounts` MUST be the Gateway PDAs of the SELECTED observers only
+     * — at most `epoch_settings.prescribed_observer_count` (≤50), NOT the whole
+     * registry. The selection is computed on-chain; mirror it off-chain with
+     * {@link predictPrescribedObservers} / {@link getPredictedObserverPDAs} to
+     * learn the set. Passing every registry gateway (e.g. via
+     * {@link getAllRegistryGatewayPDAs}) hits Solana's `MAX_TX_ACCOUNT_LOCKS = 64`
+     * on large registries and the tx fails at pre-flight.
+     *
+     * The selected PDAs are appended as `remaining_accounts`, followed by the
+     * optional `nameRegistryAccount` (must be LAST) which enables the name
      * prescription leg.
+     *
+     * If a selected gateway leaves between prediction and tx landing, the tx
+     * fails with `InvalidGatewayAccount` — retry once with a fresh prediction.
      */
     async prescribeEpoch(params, _options) {
         const ix = await getPrescribeEpochInstructionAsync(await this.withGarDefaults({
@@ -1883,7 +2399,28 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 role: AccountRole.READONLY,
             });
         }
-        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        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 };
     }
     /**
@@ -1984,6 +2521,411 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         }
         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.
@@ -2011,10 +2953,13 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      *   [8 per_obs][8 reward_rate][8 weight_lo][8 weight_hi][32 hashchain]
      *   [4 active_gw_count][4 dist_idx][4 tally_idx]
      *   [1 observer_count][1 name_count][1 obs_submitted][1 rewards_dist]
-     *   [1 weights_tallied][1 prescriptions_done][1 bump][1 _pad1]
+     *   [1 weights_tallied][1 prescriptions_done][1 bump][1 obs_closed]
      *   [6000 failure_counts][1600 prescribed_observers]
      *   [1600 prescribed_observer_gateways][64 prescribed_names]
      *   [7 has_observed][5 _pad2]
+     *
+     * NOTE: byte +123 is `observations_closed` (NOT padding) — `close_epoch`
+     * reverts with EpochObservationsNotClosed until it equals obs_submitted.
      */
     fetchEpochRawFields(data) {
         const base = 8;
@@ -2022,15 +2967,19 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         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,
         };
@@ -2068,6 +3017,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      * (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({
@@ -2075,7 +3025,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             returnedName,
             payer: this.signer,
         }), { programAddress: this.arnsProgram });
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -2147,11 +3097,34 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     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 });
-        const sig = await this.sendTransaction([ix]);
+        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 };
     }
     /**
@@ -2170,6 +3143,29 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         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).