@ar.io/sdk 3.24.0 → 4.0.0-solana.10

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

@@ -0,0 +1,2215 @@
+/**
+ * Solana implementation of AoARIOWrite interface.
+ *
+ * Extends SolanaARIOReadable with write operations that build and send
+ * Solana transactions via Codama-generated instruction builders.
+ *
+ * All instruction encoding (discriminators, account ordering, Borsh codecs,
+ * default value resolution for token/system programs) is delegated to the
+ * generated builders in `./generated/{core,gar,arns}/instructions/`. The
+ * builders are derived from the on-chain IDL and stay in sync via codegen.
+ *
+ * This file's job is just to:
+ *   1. Translate the AO-style SDK params into the builder's input shape.
+ *   2. Pre-derive the PDAs that the *Async builders can't infer (the ones
+ *      whose seeds depend on runtime state — e.g. the next withdrawal id
+ *      from the on-chain counter, or the buyer's ATA from a runtime mint).
+ *   3. Append remaining_accounts (gateway PDAs, name registry) for the
+ *      epoch crank instructions, since Codama doesn't generate a typed
+ *      surface for them.
+ */
+import { AccountRole, address, 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 { FundingSourceKind as GeneratedFundingSourceKindEnum } from '@ar.io/solana-contracts/gar';
+import { buildCreateAtaIdempotentIx, getAssociatedTokenAddressKit, } from './ata.js';
+import { deserializeArnsRecord, deserializeEpochSettingsFull, } from './deserialize.js';
+import { buildFundingPlan as buildFundingPlanCore, buildFundingPlanRemainingAccounts, computeResidueIndexes, predictResidueVaults, } from './funding-plan.js';
+/** Maps the SDK's user-facing FundingSourceKind string union to the
+ *  Codama-generated enum used by the on-chain ix payload. */
+function toGeneratedFundingSourceSpec(s) {
+    const kindMap = {
+        balance: GeneratedFundingSourceKindEnum.Balance,
+        delegation: GeneratedFundingSourceKindEnum.Delegation,
+        operatorStake: GeneratedFundingSourceKindEnum.OperatorStake,
+        withdrawal: GeneratedFundingSourceKindEnum.Withdrawal,
+    };
+    return { kind: kindMap[s.kind], amount: s.amount };
+}
+import { getSyncAttributesInstruction } from '@ar.io/solana-contracts/ant';
+import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, 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 { getTransferCheckedInstruction } from '@solana-program/token';
+import { 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';
+const addressDecoder = getAddressDecoder();
+/** Resolve mARIOToken | number to a plain number */
+function toAmount(qty) {
+    if (typeof qty === 'number')
+        return qty;
+    return qty.valueOf();
+}
+/**
+ * Append additional `AccountMeta`s to a Codama-generated instruction.
+ *
+ * The generated `getXInstruction[Async]` builders return frozen objects with
+ * a typed, fixed `accounts` tuple. The Solana program accepts extra
+ * `remaining_accounts` for epoch crank ops (gateway PDAs, name registry) and
+ * for primary-name authorization (arnsRecord, demandFactor, antRecord — see
+ * `_buildPrimaryNameValidationAccounts`), but
+ * Codama has no typed surface for them — so we splice them in here.
+ */
+function withRemainingAccounts(ix, remaining) {
+    const accounts = [
+        ...(ix.accounts ?? []),
+        ...remaining,
+    ];
+    return { ...ix, accounts };
+}
+/**
+ * Split a primary name into its undername + base parts using the same rule
+ * as the on-chain `splitn(2, '_')` in `programs/ario-core/src/instructions/primary_name.rs`:
+ * everything before the first '_' is the undername, the rest is the base.
+ *
+ * Exposed as a top-level helper so it can be unit-tested without spinning up
+ * an `SolanaARIOWriteable`. Lowercases the input to match contract behavior.
+ */
+export function splitPrimaryName(name) {
+    const lower = name.toLowerCase();
+    const ix = lower.indexOf('_');
+    if (ix === -1) {
+        return { isUndername: false, baseName: lower, undername: null };
+    }
+    return {
+        isUndername: true,
+        baseName: lower.slice(ix + 1),
+        undername: lower.slice(0, ix),
+    };
+}
+/**
+ * Solana-backed read-write client for the AR.IO protocol.
+ *
+ * Usage:
+ * ```ts
+ * import {
+ *   createSolanaRpc,
+ *   createSolanaRpcSubscriptions,
+ *   generateKeyPairSigner,
+ * } from '@solana/kit';
+ * import { SolanaARIOWriteable } from '@ar.io/sdk/solana';
+ *
+ * const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+ * const rpcSubscriptions = createSolanaRpcSubscriptions('wss://api.mainnet-beta.solana.com');
+ * const signer = await generateKeyPairSigner();
+ * const ario = new SolanaARIOWriteable({ rpc, rpcSubscriptions, signer });
+ *
+ * await ario.transfer({ target: 'RecipientPubkey...', qty: 100_000_000 });
+ * ```
+ */
+// =========================================================================
+// save_observations encoding helpers
+// =========================================================================
+// Extracted as pure functions so the bitmap-pack + base64url-decode logic
+// can be unit-tested without standing up the rpc/signer plumbing of the
+// SolanaARIOWriteable class. The on-chain ABI:
+//   - gateway_results: [u8; 375]   bit i = 1 (pass) / 0 (fail) for the
+//                                  gateway at registry index i.
+//   - gateway_count:   u16         must equal epoch.active_gateway_count.
+//   - report_tx_id:    [u8; 32]    raw 32-byte Arweave hash (base64url
+//                                  decoded from its 43-char string form).
+/** Build the gateway_results bitmap for save_observations.
+ *  All bits start as 1 (pass) for the first `registryAddresses.length`
+ *  positions; positions named in `failedGateways` get cleared to 0; all
+ *  positions beyond `registryAddresses.length` are 0. */
+export function buildObservationBitmap(registryAddresses, failedGateways) {
+    const buf = Buffer.alloc(375, 0xff);
+    const failedSet = new Set(failedGateways);
+    for (let i = 0; i < registryAddresses.length; i++) {
+        if (failedSet.has(registryAddresses[i])) {
+            buf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+        }
+    }
+    // Clear bits beyond the active gateway count so the bitmap is exactly
+    // the prescribed shape (1s only at indices < gatewayCount that passed).
+    for (let i = registryAddresses.length; i < 3000; i++) {
+        buf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+    }
+    return buf;
+}
+/** Encode an Arweave TX ID into the on-chain `[u8; 32]` slot.
+ *
+ *  An Arweave TX ID **is** a 32-byte SHA-256 hash; the 43-char base64url
+ *  string is just its presentation encoding. We decode here so the
+ *  on-chain bytes are the raw hash — lossless and trivially reversible
+ *  via base64url-encode on the consumer side. Without this, on-chain
+ *  bytes alone couldn't be used to look up the original report bundle
+ *  on permaweb (the whole point of recording the txid for auditability).
+ *
+ *  Empty / undefined input → 32 zero bytes ("no permaweb archive
+ *  configured for this submission" — the report still lives off-chain
+ *  in the observer's local sinks but isn't anchored on Arweave).
+ *
+ *  Throws on malformed input: the base64url string must be exactly 43
+ *  chars and decode to 32 bytes. Strict validation here is desirable —
+ *  silently truncating or accepting bad input would erode the
+ *  auditability that the field exists for.
+ */
+export function encodeReportTxId(reportTxId) {
+    const out = Buffer.alloc(32);
+    if (reportTxId === undefined || reportTxId === '') {
+        return out;
+    }
+    // base64url → base64. The 43-char Arweave form has no padding; add it
+    // back so Node's `Buffer.from(_, 'base64')` accepts the input.
+    const padded = reportTxId
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(reportTxId.length / 4) * 4, '=');
+    // Reject non-base64url chars up front — `Buffer.from` silently
+    // tolerates them, which would mask typos.
+    if (!/^[A-Za-z0-9+/=]+$/.test(padded)) {
+        throw new Error(`reportTxId contains non-base64url characters: "${reportTxId}". ` +
+            `Expected a 43-char Arweave TX ID using A-Z, a-z, 0-9, -, _.`);
+    }
+    const decoded = Buffer.from(padded, 'base64');
+    if (decoded.length !== 32) {
+        throw new Error(`reportTxId must be a 43-char base64url Arweave TX ID decoding to 32 bytes; ` +
+            `got ${reportTxId.length} chars decoding to ${decoded.length} bytes.`);
+    }
+    decoded.copy(out);
+    return out;
+}
+export class SolanaARIOWriteable extends SolanaARIOReadable {
+    signer;
+    rpcSubscriptions;
+    constructor(config) {
+        super(config);
+        this.signer = config.signer;
+        this.rpcSubscriptions = config.rpcSubscriptions;
+    }
+    /** The signer's on-chain address. */
+    get signerAddress() {
+        return this.signer.address;
+    }
+    async sendTransaction(instructions, computeUnitLimit = 400_000) {
+        return sendAndConfirm({
+            rpc: this.rpc,
+            rpcSubscriptions: this.rpcSubscriptions,
+            signer: this.signer,
+            instructions,
+            commitment: this.commitment,
+            computeUnitLimit,
+        });
+    }
+    /** Helper to get the ARIO mint and treasury from ArioConfig */
+    async getCoreConfig() {
+        const [configPda] = await getArioConfigPDA(this.coreProgram);
+        const account = await fetchEncodedAccount(this.rpc, configPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            throw new Error('ArioConfig not found');
+        const data = Buffer.from(account.data);
+        // ArioConfig: [8 disc][32 authority][32 mint][32 arns_program][32 treasury]
+        const mint = addressDecoder.decode(data.subarray(40, 72));
+        const treasury = addressDecoder.decode(data.subarray(104, 136));
+        return { mint, treasury };
+    }
+    async getMint() {
+        return (await this.getCoreConfig()).mint;
+    }
+    /** Helper to get ArNS config fields (mint and treasury) */
+    async getArnsConfig() {
+        const [settingsPda] = await getArnsSettingsPDA(this.arnsProgram);
+        const account = await fetchEncodedAccount(this.rpc, settingsPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            throw new Error('ArnsConfig not found');
+        const data = Buffer.from(account.data);
+        // ArnsConfig layout: [8 disc][32 authority][32 mint][32 treasury]...
+        const mint = addressDecoder.decode(data.subarray(40, 72));
+        const treasury = addressDecoder.decode(data.subarray(72, 104));
+        return { mint, treasury };
+    }
+    /** Helper to get GAR config fields (mint, stake pool, protocol pool) */
+    async getGarConfig() {
+        const [settingsPda] = await getGarSettingsPDA(this.garProgram);
+        const account = await fetchEncodedAccount(this.rpc, settingsPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            throw new Error('GarSettings not found');
+        const data = Buffer.from(account.data);
+        // GarSettings: [8 disc][32 authority][32 mint][8+8+8+8+8+8=48 u64s][4 u32][1 bool]
+        //   [32 migration_authority][32 stake_token_account][32 protocol_token_account][1 bump]
+        const mint = addressDecoder.decode(data.subarray(40, 72));
+        const stakeTokenAccount = addressDecoder.decode(data.subarray(157, 189));
+        const protocolTokenAccount = addressDecoder.decode(data.subarray(189, 221));
+        return { mint, stakeTokenAccount, protocolTokenAccount };
+    }
+    // =========================================
+    // Codama default-PDA injection helpers
+    // =========================================
+    //
+    // Codama's auto-generated `getXInstructionAsync` builders fall back to
+    // calling `find<Account>Pda()` (no args) when a "defaultable" account is
+    // omitted from the input. Those `find*Pda` helpers default to the
+    // **placeholder** program addresses baked into the generated client
+    // (`ARioArnsProgXXX...`, `ArioCoreProgXXX...`, etc.), *not* the env- or
+    // constructor-overridden program ID we actually deploy at. The result is a
+    // PDA derived against the wrong program id, which on-chain shows up as
+    // Anchor `AccountNotInitialized` (#3012) for `config` / `demand_factor` /
+    // `name_registry` / `settings` / etc.
+    //
+    // The wrappers below pre-derive each program's defaultable PDAs against
+    // the **real** program id and merge them into the input so codama never
+    // touches its placeholder defaults. Caller-provided values still win
+    // because spread order is `(...defaults, ...input)`.
+    /**
+     * Inject ARNS default PDAs (config, demandFactor, nameRegistry).
+     *
+     * Extra fields not consumed by a given builder are harmlessly ignored
+     * (codama only reads the named keys from `input`).
+     */
+    async withArnsDefaults(input) {
+        const [config] = await getArnsSettingsPDA(this.arnsProgram);
+        const [demandFactor] = await getDemandFactorPDA(this.arnsProgram);
+        const [nameRegistry] = await getArnsRegistryPDA(this.arnsProgram);
+        return { config, demandFactor, nameRegistry, ...input };
+    }
+    /** Inject ARIO core default PDAs (config). */
+    async withCoreDefaults(input) {
+        const [config] = await getArioConfigPDA(this.coreProgram);
+        return { config, ...input };
+    }
+    /** Inject GAR default PDAs (settings, epochSettings, registry). */
+    async withGarDefaults(input) {
+        const [settings] = await getGarSettingsPDA(this.garProgram);
+        const [epochSettings] = await getEpochSettingsPDA(this.garProgram);
+        const [registry] = await getGatewayRegistryPDA(this.garProgram);
+        return { settings, epochSettings, registry, ...input };
+    }
+    /** Read WithdrawalCounter's next_id (returns 0n if not yet created) */
+    async getNextWithdrawalId(owner) {
+        const [counterPda] = await getWithdrawalCounterPDA(owner, this.garProgram);
+        const account = await fetchEncodedAccount(this.rpc, counterPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return 0n;
+        // WithdrawalCounter: [8 disc][32 owner][8 next_id]
+        return Buffer.from(account.data).readBigUInt64LE(40);
+    }
+    // =========================================
+    // Token operations (ario-core)
+    // =========================================
+    async transfer(params, _options) {
+        const amount = toAmount(params.qty);
+        const recipient = address(params.target);
+        const mint = await this.getMint();
+        const fromATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const toATA = await getAssociatedTokenAddressKit(mint, recipient);
+        // SPL `transferChecked` requires the recipient ATA to exist; bundle
+        // an idempotent ATA-create so fresh recipients just work. Same
+        // pattern as `vaultedTransfer` below.
+        const createToAtaIx = buildCreateAtaIdempotentIx(this.signer.address, toATA, recipient, mint);
+        // Standard SPL Token `transferChecked`. The custom `ario-core::transfer`
+        // ix is deprecated — it added no protocol-level accounting, just wrapped
+        // this same CPI plus a `TransferEvent` emission that no major Solana
+        // indexer needs (Helius, Solscan, etc. all track SPL transfers natively).
+        // See `docs/REMOVE_CUSTOM_TRANSFER_PLAN.md` in `ar-io/solana-ar-io`.
+        // `transferChecked` (vs `transfer`) validates the mint + decimals
+        // on-chain, preventing cross-mint mistakes.
+        const ix = getTransferCheckedInstruction({
+            source: fromATA,
+            mint,
+            destination: toATA,
+            authority: this.signer,
+            amount,
+            decimals: TOKEN_DECIMALS,
+        });
+        const sig = await this.sendTransaction([createToAtaIx, ix]);
+        return { id: sig };
+    }
+    async vaultedTransfer(params, _options) {
+        const amount = toAmount(params.quantity);
+        const lockSeconds = Math.floor(params.lockLengthMs / 1000);
+        const recipient = address(params.recipient);
+        const mint = await this.getMint();
+        // Vault PDA depends on the recipient's *current* vault counter id, which
+        // the codegen builder can't infer — derive it manually.
+        const nextId = await this.getNextVaultId(recipient);
+        const [vaultPda] = await getVaultPDA(recipient, nextId, this.coreProgram);
+        const senderATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const ix = await getVaultedTransferInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            senderTokenAccount: senderATA,
+            vaultTokenAccount: vaultATA,
+            recipient,
+            sender: this.signer,
+            amount,
+            lockDurationSeconds: lockSeconds,
+            revocable: params.revokable ?? false,
+        }), { programAddress: this.coreProgram });
+        // The on-chain CreateVault / VaultedTransfer constraint is
+        // `Account<TokenAccount>` (NOT `init`) — Anchor expects the vault ATA to
+        // already exist. Bundle an idempotent CreateAssociatedTokenAccount in
+        // the same tx so the caller doesn't need a separate setup step.
+        const createVaultAtaIx = buildCreateAtaIdempotentIx(this.signer.address, vaultATA, vaultPda, mint);
+        const sig = await this.sendTransaction([createVaultAtaIx, ix]);
+        return { id: sig };
+    }
+    async createVault(params, _options) {
+        const amount = toAmount(params.quantity);
+        const lockSeconds = Math.floor(params.lockLengthMs / 1000);
+        const mint = await this.getMint();
+        const nextId = await this.getNextVaultId(this.signer.address);
+        const [vaultPda] = await getVaultPDA(this.signer.address, nextId, this.coreProgram);
+        const ownerATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const ix = await getCreateVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            ownerTokenAccount: ownerATA,
+            vaultTokenAccount: vaultATA,
+            owner: this.signer,
+            amount,
+            lockDurationSeconds: lockSeconds,
+        }), { programAddress: this.coreProgram });
+        // See note in vaultedTransfer above — vault ATA is not init'd by the
+        // on-chain handler; bundle the create.
+        const createVaultAtaIx = buildCreateAtaIdempotentIx(this.signer.address, vaultATA, vaultPda, mint);
+        const sig = await this.sendTransaction([createVaultAtaIx, ix]);
+        return { id: sig };
+    }
+    /** Read VaultCounter's next_id (returns 0n if not yet created). */
+    async getNextVaultId(owner) {
+        // VaultCounter PDA derivation lives in pda.ts as getVaultCounterPDA.
+        const { getVaultCounterPDA } = await import('./pda.js');
+        const [counterPda] = await getVaultCounterPDA(owner, this.coreProgram);
+        const account = await fetchEncodedAccount(this.rpc, counterPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return 0n;
+        return Buffer.from(account.data).readBigUInt64LE(40);
+    }
+    async extendVault(params, _options) {
+        const additionalSeconds = Math.floor(params.extendLengthMs / 1000);
+        const [vaultPda] = await getVaultPDA(this.signer.address, BigInt(params.vaultId), this.coreProgram);
+        const ix = await getExtendVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            owner: this.signer,
+            additionalSeconds,
+        }), { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async increaseVault(params, _options) {
+        const amount = toAmount(params.quantity);
+        const mint = await this.getMint();
+        const [vaultPda] = await getVaultPDA(this.signer.address, BigInt(params.vaultId), this.coreProgram);
+        const ownerATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const ix = await getIncreaseVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            ownerTokenAccount: ownerATA,
+            vaultTokenAccount: vaultATA,
+            owner: this.signer,
+            amount,
+        }), { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async revokeVault(params, _options) {
+        const recipient = address(params.recipient);
+        const mint = await this.getMint();
+        const [vaultPda] = await getVaultPDA(recipient, BigInt(params.vaultId), this.coreProgram);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const controllerATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const ix = await getRevokeVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            vaultTokenAccount: vaultATA,
+            controllerTokenAccount: controllerATA,
+            controller: this.signer,
+        }), { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Gateway operations (ario-gar)
+    // =========================================
+    async joinNetwork(params, _options) {
+        const garConfig = await this.getGarConfig();
+        const operatorATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const observerAddress = params.observerAddress
+            ? address(params.observerAddress)
+            : this.signer.address;
+        const [observerLookupPda] = await getObserverLookupPDA(observerAddress, this.garProgram);
+        const ix = await getJoinNetworkInstructionAsync(await this.withGarDefaults({
+            operatorTokenAccount: operatorATA,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            observerLookup: observerLookupPda,
+            operator: this.signer,
+            operatorStake: BigInt(params.operatorStake),
+            label: params.label ?? '',
+            fqdn: params.fqdn ?? '',
+            port: params.port ?? 443,
+            protocol: Protocol.Https,
+            properties: params.properties ?? null,
+            note: params.note ?? null,
+            allowDelegatedStaking: params.allowDelegatedStaking === true ||
+                params.allowDelegatedStaking === 'allowlist',
+            delegateRewardShareRatio: params.delegateRewardShareRatio ?? 0,
+            minDelegateStake: params.minDelegatedStake !== undefined
+                ? BigInt(params.minDelegatedStake)
+                : null,
+            observerAddress,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async leaveNetwork(_options) {
+        // BD-102: leave_network may produce 1 or 2 Withdrawal PDAs. The
+        // protected exit vault uses `next_id`; the optional excess vault
+        // uses `next_id + 1`. The SDK always derives both PDAs and passes
+        // them to the codama-emitted builder — the contract's
+        // `Option<UncheckedAccount>` excess slot is consumed only when the
+        // post-stake excess is positive. Passing it unconditionally keeps
+        // the SDK side stateless (no need to fetch gateway.operator_stake +
+        // settings.min_operator_stake to decide).
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [exitVaultPda] = await getWithdrawalPDA(this.signer.address, nextId, this.garProgram);
+        const [excessVaultPda] = await getWithdrawalPDA(this.signer.address, nextId + 1n, this.garProgram);
+        const ix = await getLeaveNetworkInstructionAsync(await this.withGarDefaults({
+            withdrawal: exitVaultPda,
+            excessWithdrawal: excessVaultPda,
+            operator: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async updateGatewaySettings(params, _options) {
+        const 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);
+        return { id: sig };
+    }
+    async increaseOperatorStake(params, _options) {
+        const amount = toAmount(params.increaseQty);
+        const garConfig = await this.getGarConfig();
+        const operatorATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getIncreaseOperatorStakeInstructionAsync(await this.withGarDefaults({
+            operatorTokenAccount: operatorATA,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            operator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async decreaseOperatorStake(params, _options) {
+        const amount = toAmount(params.decreaseQty);
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, nextId, this.garProgram);
+        const ix = await getDecreaseOperatorStakeInstructionAsync(await this.withGarDefaults({
+            withdrawal: withdrawalPda,
+            operator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async delegateStake(params, _options) {
+        const amount = toAmount(params.stakeQty);
+        const target = address(params.target);
+        const garConfig = await this.getGarConfig();
+        const [gatewayPda] = await getGatewayPDA(target, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(target, this.signer.address, this.garProgram);
+        const delegatorATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getDelegateStakeInstructionAsync(await this.withGarDefaults({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            delegatorTokenAccount: delegatorATA,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            delegator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async decreaseDelegateStake(params, _options) {
+        const amount = toAmount(params.decreaseQty);
+        const target = address(params.target);
+        const [gatewayPda] = await getGatewayPDA(target, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(target, this.signer.address, this.garProgram);
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, nextId, this.garProgram);
+        const ix = await getDecreaseDelegateStakeInstructionAsync(await this.withGarDefaults({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            withdrawal: withdrawalPda,
+            delegator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async instantWithdrawal(params, _options) {
+        const garConfig = await this.getGarConfig();
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, BigInt(params.vaultId), this.garProgram);
+        const ownerATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getInstantWithdrawalInstructionAsync(await this.withGarDefaults({
+            withdrawal: withdrawalPda,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            ownerTokenAccount: ownerATA,
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            owner: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async cancelWithdrawal(params, _options) {
+        const gateway = params.gatewayAddress
+            ? address(params.gatewayAddress)
+            : this.signer.address;
+        const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, BigInt(params.vaultId), this.garProgram);
+        const isDelegate = gateway !== this.signer.address;
+        const delegation = isDelegate
+            ? (await getDelegationPDA(gateway, this.signer.address, this.garProgram))[0]
+            : undefined;
+        const [settingsPda] = await getGarSettingsPDA(this.garProgram);
+        const ix = getCancelWithdrawalInstruction({
+            settings: settingsPda,
+            gateway: gatewayPda,
+            withdrawal: withdrawalPda,
+            delegation,
+            owner: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async saveObservations(params, _options) {
+        let epochIndex;
+        if (params.epochIndex !== undefined) {
+            epochIndex = params.epochIndex;
+        }
+        else {
+            const [settingsPda] = await getEpochSettingsPDA(this.garProgram);
+            const settingsAccount = await fetchEncodedAccount(this.rpc, settingsPda, {
+                commitment: this.commitment,
+            });
+            if (!settingsAccount.exists)
+                throw new Error('EpochSettings not found');
+            const settings = deserializeEpochSettingsFull(Buffer.from(settingsAccount.data));
+            epochIndex = settings.currentEpochIndex;
+        }
+        // Build the [u8; 375] gateway_results bitfield. On-chain convention:
+        //   bit set (1) = passed, bit clear (0) = failed.
+        let resultsBuf;
+        let gatewayCount;
+        if (params.gatewayResults) {
+            resultsBuf = Buffer.alloc(375);
+            resultsBuf.set(params.gatewayResults.subarray(0, 375));
+            gatewayCount = params.gatewayCount ?? 0;
+        }
+        else {
+            const registryAddresses = await this.getRegistryGatewayAddresses();
+            gatewayCount = registryAddresses.length;
+            resultsBuf = buildObservationBitmap(registryAddresses, params.failedGateways);
+        }
+        const reportTxId = encodeReportTxId(params.reportTxId);
+        const ix = await getSaveObservationsInstructionAsync({
+            observer: this.signer,
+            epochIndex: BigInt(epochIndex),
+            gatewayResults: new Uint8Array(resultsBuf),
+            gatewayCount,
+            reportTxId: new Uint8Array(reportTxId),
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    async redelegateStake(params, _options) {
+        const amount = toAmount(params.stakeQty);
+        const source = address(params.source);
+        const target = address(params.target);
+        const garConfig = await this.getGarConfig();
+        const [sourceGatewayPda] = await getGatewayPDA(source, this.garProgram);
+        const [targetGatewayPda] = await getGatewayPDA(target, this.garProgram);
+        const [sourceDelegationPda] = await getDelegationPDA(source, this.signer.address, this.garProgram);
+        const [targetDelegationPda] = await getDelegationPDA(target, this.signer.address, this.garProgram);
+        const delegatorATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getRedelegateStakeInstructionAsync(await this.withGarDefaults({
+            sourceGateway: sourceGatewayPda,
+            targetGateway: targetGatewayPda,
+            sourceDelegation: sourceDelegationPda,
+            targetDelegation: targetDelegationPda,
+            delegatorTokenAccount: delegatorATA,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            delegator: this.signer,
+            amount,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
+    // ArNS operations (ario-arns)
+    // =========================================
+    async buyRecord(params, _options) {
+        const arnsConfig = await this.getArnsConfig();
+        const buyerATA = await getAssociatedTokenAddressKit(arnsConfig.mint, this.signer.address);
+        const antPubkey = address(params.processId ?? '11111111111111111111111111111111');
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const [reservedNameCheck] = await getReservedNamePDA(params.name, this.arnsProgram);
+        const [returnedNameCheck] = await getReturnedNamePDA(params.name, this.arnsProgram);
+        const buyNameParams = {
+            name: params.name,
+            purchaseType: params.type === 'permabuy' ? PurchaseType.Permabuy : PurchaseType.Lease,
+            years: params.years ?? 1,
+            ant: antPubkey,
+        };
+        // Phase 4 of FUND_FROM_PLAN.md: dispatch on params.fundFrom. The pre-Phase-4
+        // path always fell through to the balance-funded `buyName` ix even when
+        // CLI-set `--fund-from stakes`; we now route to the corresponding on-chain
+        // wrapper for each mode.
+        let ix;
+        if (params.fundFrom === 'stakes' && params.gatewayAddress) {
+            const gatewayAddr = address(params.gatewayAddress);
+            const garConfig = await this.getGarConfig();
+            const [garSettings] = await getGarSettingsPDA(this.garProgram);
+            const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+            const baseShared = {
+                config: await this.arnsConfigPda(),
+                demandFactor: await this.demandFactorPda(),
+                arnsRecord,
+                nameRegistry: await this.nameRegistryPda(),
+                reservedNameCheck,
+                returnedNameCheck,
+                garSettings,
+                gateway: gatewayPda,
+                stakeTokenAccount: garConfig.stakeTokenAccount,
+                protocolTokenAccount: arnsConfig.treasury,
+                buyer: this.signer,
+                garProgram: this.garProgram,
+                params: buyNameParams,
+            };
+            if (params.fundAsOperator) {
+                ix = await getBuyNameFromOperatorStakeInstructionAsync(baseShared, {
+                    programAddress: this.arnsProgram,
+                });
+            }
+            else {
+                const [delegationPda] = await getDelegationPDA(gatewayAddr, this.signer.address, this.garProgram);
+                ix = await getBuyNameFromDelegationInstructionAsync({ ...baseShared, delegation: delegationPda }, { programAddress: this.arnsProgram });
+            }
+        }
+        else if (params.fundFrom === 'withdrawal' &&
+            params.withdrawalId !== undefined) {
+            const garConfig = await this.getGarConfig();
+            const [garSettings] = await getGarSettingsPDA(this.garProgram);
+            const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, params.withdrawalId, this.garProgram);
+            ix = await getBuyNameFromWithdrawalInstructionAsync({
+                config: await this.arnsConfigPda(),
+                demandFactor: await this.demandFactorPda(),
+                arnsRecord,
+                nameRegistry: await this.nameRegistryPda(),
+                reservedNameCheck,
+                returnedNameCheck,
+                garSettings,
+                withdrawal: withdrawalPda,
+                stakeTokenAccount: garConfig.stakeTokenAccount,
+                protocolTokenAccount: arnsConfig.treasury,
+                buyer: this.signer,
+                garProgram: this.garProgram,
+                params: buyNameParams,
+            }, { programAddress: this.arnsProgram });
+        }
+        else if (params.fundFrom === 'plan' || params.fundFrom === 'any') {
+            ix = await this._buildBuyNameFromFundingPlanIx({
+                params,
+                antPubkey,
+                arnsRecord,
+                reservedNameCheck,
+                returnedNameCheck,
+                buyNameParams,
+                arnsConfig,
+            });
+        }
+        else {
+            // 'balance' or undefined falls through to the original direct-buy path.
+            ix = await getBuyNameInstructionAsync(await this.withArnsDefaults({
+                arnsRecord,
+                buyerTokenAccount: buyerATA,
+                protocolTokenAccount: arnsConfig.treasury,
+                reservedNameCheck,
+                returnedNameCheck,
+                buyer: this.signer,
+                params: buyNameParams,
+            }), { programAddress: this.arnsProgram });
+        }
+        // Sprint 4 / ADR-016: bundle `ant.sync_attributes` IFF the buyer
+        // owns the ANT (preserves BD-096 — non-holder buys defer the trait
+        // sync to a later `syncAttributes()` call by the actual owner).
+        // Pass `antPubkey` as assetOverride: the ArnsRecord PDA is CREATED
+        // by the buy_name ix, so it doesn't exist on-chain at SDK build
+        // time — the helper would 404 if it tried to read it.
+        const syncIx = await this._buildSyncAttributesIxIfOwner(params.name, antPubkey);
+        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        return { id: sig };
+    }
+    /**
+     * Resolve a `FundingPlan` for a fee-paying ArNS ix. When `params.sources`
+     * is set, use it verbatim (caller-supplied plan); otherwise discover the
+     * user's sources and build a plan via the Lua-faithful planner.
+     *
+     * Throws `InsufficientFundingError` (as a thrown Error with the structured
+     * payload as `cause`) when no plan covers `amountNeeded`.
+     */
+    async _resolveFundingPlan(params, amountNeeded) {
+        // `'plan'` is the explicit "I'll supply my own sources, skip discovery"
+        // mode (per FUNDING_MODES.md). Fail loudly if a caller picks `'plan'`
+        // without sources — pre-2026-05 the SDK silently fell through to
+        // discovery, making `'plan'` a synonym for `'any'`. The new semantic
+        // matches the doc: `'any'` discovers, `'plan'` uses what you give it.
+        if (params.fundFrom === 'plan' && !params.sources?.length) {
+            throw new Error("fundFrom: 'plan' requires explicit `sources`. Pass them via " +
+                "params.sources, or use fundFrom: 'any' to let the SDK discover " +
+                'and plan automatically.');
+        }
+        if (params.sources?.length) {
+            // Caller supplied an explicit plan; build the FundingPlan envelope
+            // around it without source discovery. Each Delegation/OperatorStake
+            // source MUST carry an explicit `gateway` field so the executor knows
+            // which gateway PDA to slot in. Earlier single-gateway flows used
+            // `params.gatewayAddress` as a fallback for the first stake source —
+            // we preserve that for back-compat in the explicit-plan path.
+            const hasBalance = params.sources.some((s) => s.kind === 'balance');
+            const fallbackGateway = params.gatewayAddress
+                ? address(params.gatewayAddress)
+                : undefined;
+            const gatewayPerSource = params.sources.map((s) => {
+                if (s.kind !== 'delegation' && s.kind !== 'operatorStake')
+                    return undefined;
+                const explicit = s.gateway;
+                if (explicit)
+                    return address(explicit);
+                if (fallbackGateway)
+                    return fallbackGateway;
+                throw new Error('sources includes delegation/operatorStake but no gateway is set on that source and gatewayAddress is unset');
+            });
+            // Auto-detect residue: for each Delegation source, fetch the live
+            // Delegation + Gateway PDAs and compute the post-drain. If it lands
+            // in (0, min_delegation_amount), that source will trigger an on-
+            // chain residue auto-vault and we must reserve a residue PDA slot.
+            const residueDelegationIndexes = await this._detectResidueIndexes(params.sources, gatewayPerSource);
+            return {
+                sources: params.sources.map((s) => ({
+                    kind: s.kind,
+                    amount: s.amount,
+                    ...(s.withdrawalId !== undefined
+                        ? { withdrawalId: s.withdrawalId }
+                        : {}),
+                })),
+                gatewayPerSource,
+                residueDelegationIndexes,
+                hasBalanceSource: hasBalance,
+            };
+        }
+        // No explicit sources: discover + plan.
+        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,
+        });
+        const plan = buildFundingPlanCore(sources, amountNeeded, {
+            fundFrom: params.fundFrom,
+            preferGateway: params.gatewayAddress
+                ? address(params.gatewayAddress)
+                : undefined,
+            fundAsOperator: params.fundAsOperator,
+        });
+        if ('kind' in plan) {
+            const err = new Error(plan.message);
+            err.cause = plan;
+            throw err;
+        }
+        return plan;
+    }
+    /**
+     * Build a `buy_name_from_funding_plan` ix using the funding-plan module.
+     * Resolves per-source PDAs (Delegation, Withdrawal) and the residue-vault
+     * PDA prediction in one shot.
+     */
+    async _buildBuyNameFromFundingPlanIx(args) {
+        const garConfig = await this.getGarConfig();
+        const [garSettings] = await getGarSettingsPDA(this.garProgram);
+        const buyerATA = await getAssociatedTokenAddressKit(args.arnsConfig.mint, this.signer.address);
+        const cost = await this._estimateBuyNameCost(args.buyNameParams);
+        const plan = await this._resolveFundingPlan(args.params, cost);
+        const { remainingAccounts, withdrawalCounter, residueVaultCount } = await this._materializeFundingPlan(args.params, plan);
+        return await getBuyNameFromFundingPlanInstructionAsync({
+            config: await this.arnsConfigPda(),
+            demandFactor: await this.demandFactorPda(),
+            arnsRecord: args.arnsRecord,
+            nameRegistry: await this.nameRegistryPda(),
+            reservedNameCheck: args.reservedNameCheck,
+            returnedNameCheck: args.returnedNameCheck,
+            garSettings,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: args.arnsConfig.treasury,
+            payerTokenAccount: plan.hasBalanceSource ? buyerATA : undefined,
+            buyer: this.signer,
+            withdrawalCounter,
+            garProgram: this.garProgram,
+            params: args.buyNameParams,
+            sources: plan.sources.map(toGeneratedFundingSourceSpec),
+            discountAccountCount: 0,
+            residueVaultCount,
+        }, {
+            programAddress: this.arnsProgram,
+        }).then((ix) => remainingAccounts.length > 0
+            ? withRemainingAccounts(ix, remainingAccounts)
+            : ix);
+    }
+    /**
+     * For an explicit caller-supplied plan, detect which Delegation sources
+     * will trigger an on-chain residue auto-vault. Reads each (Delegation,
+     * Gateway) pair in parallel; computes post-drain; flags `(0, min)`.
+     *
+     * Hard-fails on RPC error or missing PDA — silently skipping would let
+     * the on-chain handler reject the tx with `MissingResidueVault` and
+     * burn fees. The error message points at remediation.
+     */
+    async _detectResidueIndexes(sources, gatewayPerSource) {
+        const delegationIndexes = sources
+            .map((s, i) => ({ s, i }))
+            .filter(({ s }) => s.kind === 'delegation');
+        if (delegationIndexes.length === 0)
+            return [];
+        const owner = this.signer.address;
+        const reads = await Promise.all(delegationIndexes.map(async ({ i }) => {
+            const gateway = gatewayPerSource[i];
+            if (!gateway) {
+                throw new Error(`funding plan source #${i} is a Delegation but gatewayPerSource[${i}] is undefined; set source.gateway or params.gatewayAddress`);
+            }
+            const [delegationPda] = await getDelegationPDA(gateway, owner, this.garProgram);
+            const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+            const [delAcct, gwAcct] = await Promise.all([
+                fetchEncodedAccount(this.rpc, delegationPda, {
+                    commitment: this.commitment,
+                }),
+                fetchEncodedAccount(this.rpc, gatewayPda, {
+                    commitment: this.commitment,
+                }),
+            ]);
+            if (!delAcct.exists) {
+                throw new Error(`residue auto-detect failed: Delegation PDA ${delegationPda} not found for source #${i} (gateway ${gateway}); ensure the delegation exists or pass an explicit funding plan with residue hints`);
+            }
+            if (!gwAcct.exists) {
+                throw new Error(`residue auto-detect failed: Gateway PDA ${gatewayPda} not found for source #${i}`);
+            }
+            return { i, delAcct, gwAcct };
+        }));
+        const delegationDecoder = getDelegationDecoder();
+        const gatewayDecoder = getGatewayDecoder();
+        const states = new Array(sources.length).fill(undefined);
+        for (const { i, delAcct, gwAcct } of reads) {
+            const delegation = delegationDecoder.decode(delAcct.data);
+            const gateway = gatewayDecoder.decode(gwAcct.data);
+            states[i] = {
+                delegationAmount: delegation.amount,
+                minDelegationAmount: gateway.settings.minDelegationAmount,
+            };
+        }
+        return computeResidueIndexes(sources, states);
+    }
+    /**
+     * Materialize a `FundingPlan` into the on-chain ix's per-source remaining
+     * accounts, residue-vault PDAs, and the withdrawal_counter slot. Shared
+     * across all 5 ArNS funding-plan ix dispatches and the 2 ario-core
+     * primary-name funding-plan dispatches.
+     *
+     * Throws when the plan has Withdrawal sources whose ids cannot be
+     * resolved from either `spec.withdrawalId` (preferred) or
+     * `params.withdrawalId` (single-withdrawal back-compat).
+     */
+    async _materializeFundingPlan(params, plan) {
+        // Resolve withdrawalIds: prefer per-source `spec.withdrawalId` (the
+        // multi-withdrawal canonical path — discoverFundingSources sets it
+        // and explicit caller plans can too); fall back to params.withdrawalId
+        // for single-withdrawal CLI back-compat.
+        const withdrawalSpecs = (params.sources ?? plan.sources).filter((s) => s.kind === 'withdrawal');
+        const withdrawalIds = withdrawalSpecs.map((s, idx) => {
+            const specId = s.withdrawalId;
+            if (specId !== undefined)
+                return BigInt(specId);
+            if (params.withdrawalId !== undefined && idx === 0) {
+                return BigInt(params.withdrawalId);
+            }
+            throw new Error(`funding plan Withdrawal source #${idx} has no withdrawalId; set it on the source spec or pass params.withdrawalId for single-withdrawal plans`);
+        });
+        const { residueVaults, withdrawalCounter } = await predictResidueVaults(this.rpc, this.signer.address, plan, { garProgram: this.garProgram });
+        const remainingAccounts = await buildFundingPlanRemainingAccounts(plan, this.signer.address, { withdrawalIds, residueVaults, garProgram: this.garProgram });
+        return {
+            remainingAccounts: remainingAccounts,
+            withdrawalCounter,
+            residueVaultCount: residueVaults.length,
+        };
+    }
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    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,
+        });
+        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;
+    }
+    async arnsConfigPda() {
+        // The ArNS config (`Settings`) PDA is seeded with `arns_config` — NOT
+        // the `ario_config` seed used by the ario-core `Config` PDA. Earlier
+        // revisions of this helper called `getArioConfigPDA(this.arnsProgram)`
+        // which composes the wrong seed against the right program; the
+        // resulting PDA points at an account that never exists, and every
+        // fund-from-stakes / withdrawal / funding-plan path simulated as
+        // AccountNotInitialized (#3012) on the `config` slot.
+        const [pda] = await getArnsSettingsPDA(this.arnsProgram);
+        return pda;
+    }
+    async demandFactorPda() {
+        const [pda] = await getDemandFactorPDA(this.arnsProgram);
+        return pda;
+    }
+    async nameRegistryPda() {
+        const [pda] = await getArnsRegistryPDA(this.arnsProgram);
+        return pda;
+    }
+    async upgradeRecord(params, _options) {
+        const ix = await this._buildManageStakeIx({
+            params,
+            operation: 'upgrade',
+        });
+        const syncIx = await this._buildSyncAttributesIxIfOwner(params.name);
+        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        return { id: sig };
+    }
+    async syncAttributes(params, _options) {
+        // Public method — caller is asking explicitly to sync. Build the ix
+        // unconditionally; if they don't actually own the ANT, the on-chain
+        // handler returns NotNftHolder. (The bundle path uses
+        // `_buildSyncAttributesIxIfOwner`, which skips when not the owner so
+        // the wrapping arns ix can still succeed for non-holder management
+        // — see BD-095.)
+        const ix = await this._buildSyncAttributesIxUnconditional(params.name);
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Build a `sync_attributes` instruction for `name` IFF the signer is
+     * the current MPL Core asset owner. Returns `null` otherwise.
+     *
+     * Sprint 4 / ADR-016: bundle helper for `buyRecord`, `upgradeRecord`,
+     * `increaseUndernameLimit`, `reassignName`, and `buyReturnedName`.
+     * Returning `null` lets the caller send the arns ix alone — preserves
+     * BD-095 (non-holder ArNS lease management) and BD-096 (deferred
+     * trait sync for non-holder buyers). The actual ANT owner reconciles
+     * state later via the public `syncAttributes()`.
+     *
+     * `extendLease` is NOT a caller of this helper — extend_lease changes
+     * only `end_timestamp`, which isn't mirrored in any Attributes-plugin
+     * trait (BD-095 last row). `releaseName` is also excluded — release_name
+     * closes the ArnsRecord PDA, so a follow-up `sync_attributes` would
+     * fail the PDA-existence check.
+     *
+     * `assetOverride` MUST be set when the bundling ix mutates
+     * `record.ant` mid-tx (i.e. `reassign_name`). The on-chain record
+     * still points at the OLD asset at SDK build time, so without the
+     * override the bundled sync would target the wrong asset and fail
+     * the post-reassign `record.ant == asset.key()` check. The owner
+     * check runs against the supplied asset (= new ANT for reassign),
+     * matching the pre-reshape "new owner reconciles later" semantic.
+     */
+    async _buildSyncAttributesIxIfOwner(name, assetOverride) {
+        let asset;
+        if (assetOverride !== undefined) {
+            asset = assetOverride;
+        }
+        else {
+            const record = await this.getArNSRecord({ name });
+            asset = address(record.processId);
+        }
+        const { fetchMplCoreOwner } = await import('./mpl-core.js');
+        const owner = await fetchMplCoreOwner(this.rpc, asset, {
+            commitment: this.commitment,
+        });
+        if (owner === null || owner !== this.signer.address) {
+            return null;
+        }
+        return this._buildSyncAttributesIxFor(name, asset);
+    }
+    /**
+     * Build a `sync_attributes` instruction unconditionally (no owner
+     * check). Used by the public `syncAttributes()` method, where the
+     * caller is asking explicitly — if they aren't the owner the chain
+     * returns NotNftHolder.
+     */
+    async _buildSyncAttributesIxUnconditional(name) {
+        const record = await this.getArNSRecord({ name });
+        return this._buildSyncAttributesIxFor(name, address(record.processId));
+    }
+    /** Pure builder; no RPC. Used by both gated + unconditional helpers. */
+    async _buildSyncAttributesIxFor(name, asset) {
+        const [arnsRecord] = await getArnsRecordPDA(name, this.arnsProgram);
+        return getSyncAttributesInstruction({
+            asset,
+            payer: this.signer,
+            authority: this.signer,
+            arnsRecord,
+            name,
+        }, { programAddress: this.antProgram });
+    }
+    async extendLease(params, _options) {
+        const ix = await this._buildManageStakeIx({
+            params,
+            operation: 'extend',
+            years: params.years,
+        });
+        // BD-095: extend_lease changes only `end_timestamp`, which isn't
+        // mirrored in any Metaplex Attributes plugin trait. No bundle.
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async increaseUndernameLimit(params, _options) {
+        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]);
+        return { id: sig };
+    }
+    /**
+     * Shared dispatch helper for the 3 manage variants (upgrade / extend /
+     * increaseUndername). They share the same account shape per the
+     * `manage_from_delegation_accounts!` / `manage_from_operator_stake_accounts!`
+     * macros in `programs/ario-arns/src/instructions/manage_from_stake.rs`.
+     * Only the operation-specific extra args differ (years for extend,
+     * quantity for increaseUndername).
+     */
+    async _buildManageStakeIx(args) {
+        const arnsConfig = await this.getArnsConfig();
+        const callerATA = await getAssociatedTokenAddressKit(arnsConfig.mint, this.signer.address);
+        const [arnsRecord] = await getArnsRecordPDA(args.params.name, this.arnsProgram);
+        // Balance / undefined → original direct-transfer ix (matches pre-Phase-4).
+        if (!args.params.fundFrom ||
+            args.params.fundFrom === 'balance' ||
+            args.params.fundFrom === 'turbo') {
+            const baseAccounts = await this.withArnsDefaults({
+                arnsRecord,
+                callerTokenAccount: callerATA,
+                protocolTokenAccount: arnsConfig.treasury,
+                caller: this.signer,
+            });
+            if (args.operation === 'upgrade') {
+                return getUpgradeNameInstructionAsync(baseAccounts, {
+                    programAddress: this.arnsProgram,
+                });
+            }
+            if (args.operation === 'extend') {
+                return getExtendLeaseInstructionAsync({ ...baseAccounts, years: args.years }, { programAddress: this.arnsProgram });
+            }
+            return getIncreaseUndernameLimitInstructionAsync({ ...baseAccounts, quantity: args.quantity }, { programAddress: this.arnsProgram });
+        }
+        // Stake / withdrawal / funding-plan paths share an account skeleton.
+        const garConfig = await this.getGarConfig();
+        const [garSettings] = await getGarSettingsPDA(this.garProgram);
+        const sharedManageBase = {
+            config: await this.arnsConfigPda(),
+            demandFactor: await this.demandFactorPda(),
+            arnsRecord,
+            garSettings,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: arnsConfig.treasury,
+            caller: this.signer,
+            garProgram: this.garProgram,
+        };
+        if (args.params.fundFrom === 'stakes' && args.params.gatewayAddress) {
+            const gatewayAddr = address(args.params.gatewayAddress);
+            const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+            const stakeBase = { ...sharedManageBase, gateway: gatewayPda };
+            if (args.params.fundAsOperator) {
+                if (args.operation === 'upgrade')
+                    return getUpgradeNameFromOperatorStakeInstructionAsync(stakeBase, {
+                        programAddress: this.arnsProgram,
+                    });
+                if (args.operation === 'extend')
+                    return getExtendLeaseFromOperatorStakeInstructionAsync({ ...stakeBase, years: args.years }, { programAddress: this.arnsProgram });
+                return getIncreaseUndernameLimitFromOperatorStakeInstructionAsync({ ...stakeBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+            }
+            const [delegationPda] = await getDelegationPDA(gatewayAddr, this.signer.address, this.garProgram);
+            const delBase = { ...stakeBase, delegation: delegationPda };
+            if (args.operation === 'upgrade')
+                return getUpgradeNameFromDelegationInstructionAsync(delBase, {
+                    programAddress: this.arnsProgram,
+                });
+            if (args.operation === 'extend')
+                return getExtendLeaseFromDelegationInstructionAsync({ ...delBase, years: args.years }, { programAddress: this.arnsProgram });
+            return getIncreaseUndernameLimitFromDelegationInstructionAsync({ ...delBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+        }
+        if (args.params.fundFrom === 'withdrawal' &&
+            args.params.withdrawalId !== undefined) {
+            const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, args.params.withdrawalId, this.garProgram);
+            const wBase = { ...sharedManageBase, withdrawal: withdrawalPda };
+            if (args.operation === 'upgrade')
+                return getUpgradeNameFromWithdrawalInstructionAsync(wBase, {
+                    programAddress: this.arnsProgram,
+                });
+            if (args.operation === 'extend')
+                return getExtendLeaseFromWithdrawalInstructionAsync({ ...wBase, years: args.years }, { programAddress: this.arnsProgram });
+            return getIncreaseUndernameLimitFromWithdrawalInstructionAsync({ ...wBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+        }
+        if (args.params.fundFrom === 'plan' || args.params.fundFrom === 'any') {
+            // 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,
+                name: args.params.name,
+                years: args.years,
+                quantity: args.quantity,
+            });
+            const plan = await this._resolveFundingPlan(args.params, cost);
+            const buyerATA = await getAssociatedTokenAddressKit(arnsConfig.mint, this.signer.address);
+            const { remainingAccounts, withdrawalCounter, residueVaultCount } = await this._materializeFundingPlan(args.params, plan);
+            const fpBase = {
+                config: await this.arnsConfigPda(),
+                demandFactor: await this.demandFactorPda(),
+                arnsRecord,
+                garSettings,
+                stakeTokenAccount: garConfig.stakeTokenAccount,
+                protocolTokenAccount: arnsConfig.treasury,
+                payerTokenAccount: plan.hasBalanceSource ? buyerATA : undefined,
+                caller: this.signer,
+                withdrawalCounter,
+                garProgram: this.garProgram,
+                sources: plan.sources.map(toGeneratedFundingSourceSpec),
+                discountAccountCount: 0,
+                residueVaultCount,
+            };
+            let ix;
+            if (args.operation === 'upgrade')
+                ix = await getUpgradeNameFromFundingPlanInstructionAsync(fpBase, {
+                    programAddress: this.arnsProgram,
+                });
+            else if (args.operation === 'extend')
+                ix = await getExtendLeaseFromFundingPlanInstructionAsync({ ...fpBase, years: args.years }, { programAddress: this.arnsProgram });
+            else
+                ix = await getIncreaseUndernameLimitFromFundingPlanInstructionAsync({ ...fpBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+            return remainingAccounts.length > 0
+                ? withRemainingAccounts(ix, remainingAccounts)
+                : ix;
+        }
+        throw new Error(`unsupported fundFrom mode '${args.params.fundFrom}' for ${args.operation}`);
+    }
+    /**
+     * Cost estimate for manage operations (upgrade / extend / increaseUndername).
+     * Reads the live DemandFactor account + applies the on-chain pricing math.
+     */
+    async _estimateManageStakeCost(args) {
+        const [demandFactorPda] = await getDemandFactorPDA(this.arnsProgram);
+        const dfAccount = await fetchEncodedAccount(this.rpc, demandFactorPda, {
+            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);
+    }
+    // =========================================
+    // 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.
+     *
+     * 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(@)]
+     *
+     * `antRecord` keys off the undername part for undernames (e.g.
+     * "blog_arweave" → AntRecord at "blog") or the canonical "@" sentinel
+     * for base names. `removeForBaseName` is special — it always uses "@"
+     * regardless of whether the primary name being removed is an undername,
+     * since the *base* name owner is the one revoking it.
+     *
+     * `antProgram` honors ADR-016 / BD-100 pluggability: the asset's
+     * `ANT Program` Attributes-plugin trait selects which program owns the
+     * AntRecord PDA. Absent / unparseable → canonical fallback. Both the
+     * PDA derivation here and the `ant_program_id` arg the caller passes
+     * to the on-chain ix MUST agree (the handler re-derives and rejects
+     * mismatches).
+     */
+    async _buildPrimaryNameValidationAccounts(name, variant) {
+        const { isUndername, baseName, undername } = splitPrimaryName(name);
+        const [arnsRecordPda] = await getArnsRecordPDA(baseName, this.arnsProgram);
+        const remaining = [
+            { address: arnsRecordPda, role: AccountRole.READONLY },
+        ];
+        // Fee-charging variants need the demand factor for fee scaling.
+        if (variant === 'request' || variant === 'requestAndSet') {
+            const [demandFactorPda] = await getDemandFactorPDA(this.arnsProgram);
+            remaining.push({ address: demandFactorPda, role: AccountRole.READONLY });
+        }
+        // ANT-auth variants need the AntRecord PDA. We have to read the
+        // ArnsRecord first to recover the ANT mint, then read the asset's
+        // `ANT Program` trait (ADR-016 / BD-100) to pick the right program
+        // for the AntRecord PDA derivation.
+        let antProgram = this.antProgram;
+        if (variant !== 'request') {
+            const arnsAccount = await fetchEncodedAccount(this.rpc, arnsRecordPda, {
+                commitment: this.commitment,
+            });
+            if (!arnsAccount.exists) {
+                throw new Error(`ArNS record not found for base name: ${baseName}`);
+            }
+            const arnsRecord = deserializeArnsRecord(Buffer.from(arnsAccount.data));
+            const antMint = address(arnsRecord.processId);
+            const { fetchAntProgramFromAsset } = await import('./mpl-core.js');
+            antProgram =
+                (await fetchAntProgramFromAsset(this.rpc, antMint, {
+                    commitment: this.commitment,
+                })) ?? this.antProgram;
+            // removeForBaseName always uses the "@" undername (the base-name
+            // owner's record). The other ANT-auth variants use the undername
+            // part if the primary name is an undername.
+            const antUndername = variant === 'removeForBaseName' || !isUndername || undername === null
+                ? '@'
+                : undername;
+            const [antRecordPda] = await getAntRecordPDA(antMint, antUndername, antProgram);
+            remaining.push({ address: antRecordPda, role: AccountRole.READONLY });
+        }
+        return { remaining, antProgram };
+    }
+    async requestPrimaryName(params, _options) {
+        const coreConfig = await this.getCoreConfig();
+        const signerATA = await getAssociatedTokenAddressKit(coreConfig.mint, this.signer.address);
+        const { remaining } = await this._buildPrimaryNameValidationAccounts(params.name, 'request');
+        // Phase 4 of FUND_FROM_PLAN.md: dispatch primary-name funding via the
+        // funding-plan ix when caller asks for stakes/withdrawal/plan/any. The
+        // direct-transfer ix stays the path for fundFrom='balance' / undefined.
+        let ix;
+        if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            ix = withRemainingAccounts(await getRequestPrimaryNameInstructionAsync(await this.withCoreDefaults({
+                initiatorTokenAccount: signerATA,
+                protocolTokenAccount: coreConfig.treasury,
+                initiator: this.signer,
+                name: params.name,
+            }), { programAddress: this.coreProgram }), remaining);
+        }
+        else {
+            ix = await this._buildPrimaryNameFromFundingPlanIx({
+                params,
+                coreConfig,
+                validationAccounts: remaining,
+                operation: 'request',
+            });
+        }
+        const sig = await this.sendTransaction([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).
+        const coreConfig = await this.getCoreConfig();
+        const signerATA = await getAssociatedTokenAddressKit(coreConfig.mint, this.signer.address);
+        const { remaining, antProgram } = await this._buildPrimaryNameValidationAccounts(params.name, 'requestAndSet');
+        let ix;
+        if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            ix = withRemainingAccounts(await getRequestAndSetPrimaryNameInstructionAsync(await this.withCoreDefaults({
+                initiatorTokenAccount: signerATA,
+                protocolTokenAccount: coreConfig.treasury,
+                initiator: this.signer,
+                name: params.name,
+                reverseLookupHash: hashName(params.name),
+                antProgramId: antProgram,
+            }), { programAddress: this.coreProgram }), remaining);
+        }
+        else {
+            ix = await this._buildPrimaryNameFromFundingPlanIx({
+                params,
+                coreConfig,
+                validationAccounts: remaining,
+                operation: 'requestAndSet',
+                antProgramId: antProgram,
+            });
+        }
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Build a `request_primary_name_from_funding_plan` or
+     * `request_and_set_primary_name_from_funding_plan` ix. Forwards both:
+     *   - validation accounts (ArnsRecord + DemandFactor [+ ant_asset
+     *     [+ AntRecord]]) — passed via remaining_accounts at indices
+     *     [0..validation_account_count)
+     *   - per-source PDAs from the funding plan — passed at indices
+     *     [validation_account_count..)
+     *
+     * The on-chain handler (programs/ario-core/src/instructions/primary_name.rs)
+     * splits remaining_accounts at `validation_account_count` and forwards the
+     * funding-source slice to ario-gar's pay_from_funding_plan via CPI.
+     */
+    async _buildPrimaryNameFromFundingPlanIx(args) {
+        // 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,
+        });
+        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);
+        const initiatorATA = await getAssociatedTokenAddressKit(args.coreConfig.mint, this.signer.address);
+        const { remainingAccounts: fundingRemaining, withdrawalCounter, residueVaultCount, } = await this._materializeFundingPlan(args.params, plan);
+        const allRemaining = [
+            ...args.validationAccounts,
+            ...fundingRemaining,
+        ];
+        const validationAccountCount = args.validationAccounts.length;
+        const baseFp = {
+            config: await this._coreConfigPda(),
+            garSettings,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: args.coreConfig.treasury,
+            payerTokenAccount: plan.hasBalanceSource ? initiatorATA : undefined,
+            initiator: this.signer,
+            withdrawalCounter,
+            garProgram: this.garProgram,
+            sources: plan.sources.map(toGeneratedFundingSourceSpec),
+            validationAccountCount,
+            residueVaultCount,
+        };
+        let ix;
+        if (args.operation === 'request') {
+            const [requestPda] = await getPrimaryNameRequestPDA(this.signer.address, this.coreProgram);
+            ix = await getRequestPrimaryNameFromFundingPlanInstructionAsync({ ...baseFp, request: requestPda, name: args.params.name }, { programAddress: this.coreProgram });
+        }
+        else {
+            const [primaryNamePda] = await getPrimaryNamePDA(this.signer.address, this.coreProgram);
+            const [primaryNameReversePda] = await getPrimaryNameReversePDA(args.params.name, this.coreProgram);
+            ix = await getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync({
+                ...baseFp,
+                primaryName: primaryNamePda,
+                primaryNameReverse: primaryNameReversePda,
+                name: args.params.name,
+                reverseLookupHash: hashName(args.params.name),
+                antProgramId: args.antProgramId ?? this.antProgram,
+            }, { programAddress: this.coreProgram });
+        }
+        return allRemaining.length > 0
+            ? withRemainingAccounts(ix, allRemaining)
+            : ix;
+    }
+    async _coreConfigPda() {
+        const [pda] = await getArioConfigPDA(this.coreProgram);
+        return pda;
+    }
+    /**
+     * Approve a previously-created primary name request. The signer must be
+     * the AntRecord.owner for the requested name (undername part for
+     * undernames, "@" for base names) — Sprint 2 / ADR-016 reshape.
+     *
+     * Mirrors the on-chain `approve_primary_name` instruction
+     * (`programs/ario-core/src/instructions/primary_name.rs`).
+     * remaining_accounts: [arns_record(base), ant_record(undername | @)].
+     */
+    async approvePrimaryName(params, _options) {
+        const [requestPda] = await getPrimaryNameRequestPDA(params.initiator, this.coreProgram);
+        const [primaryNamePda] = await getPrimaryNamePDA(params.initiator, this.coreProgram);
+        const [primaryNameReversePda] = await getPrimaryNameReversePDA(params.name, this.coreProgram);
+        const { remaining, antProgram } = await this._buildPrimaryNameValidationAccounts(params.name, 'approve');
+        // withCoreDefaults injects `config` as the ArioConfig PDA derived against
+        // *this.coreProgram*. Without it, Codama's `findConfigPda()` fallback
+        // resolves to the source-pinned `ARioCoreProgramXXXX...` placeholder
+        // program id (declare_id! literal pre-anchor-keys-sync), which on any
+        // non-mainnet deployment produces an unallocated PDA → Anchor #3012
+        // AccountNotInitialized on `config`. requestPrimaryName /
+        // requestAndSetPrimaryName already use withCoreDefaults; this was the
+        // last setPrimaryName-family entrypoint missing it.
+        const ix = withRemainingAccounts(await getApprovePrimaryNameInstructionAsync(await this.withCoreDefaults({
+            request: requestPda,
+            initiator: params.initiator,
+            primaryName: primaryNamePda,
+            primaryNameReverse: primaryNameReversePda,
+            nameOwner: this.signer,
+            reverseLookupHash: hashName(params.name),
+            antProgramId: antProgram,
+        }), { programAddress: this.coreProgram }), remaining);
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Vault release (ario-core)
+    // =========================================
+    /** Release tokens from an unlocked vault back to the owner. */
+    async releaseVault(params, _options) {
+        const mint = await this.getMint();
+        const [vaultPda] = await getVaultPDA(this.signer.address, BigInt(params.vaultId), this.coreProgram);
+        const vaultATA = await getAssociatedTokenAddressKit(mint, vaultPda, true);
+        const ownerATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
+        const ix = await getReleaseVaultInstructionAsync(await this.withCoreDefaults({
+            vault: vaultPda,
+            vaultTokenAccount: vaultATA,
+            ownerTokenAccount: ownerATA,
+            owner: this.signer,
+        }), { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Close expired primary name request (ario-core)
+    // =========================================
+    /** Close an expired primary name request (permissionless — anyone can call). */
+    async closeExpiredRequest(params, _options) {
+        const initiatorPubkey = address(params.initiator);
+        const [requestPda] = await getPrimaryNameRequestPDA(initiatorPubkey, this.coreProgram);
+        const ix = getCloseExpiredRequestInstruction({
+            request: requestPda,
+            initiator: initiatorPubkey,
+            payer: this.signer,
+        }, { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Withdrawal claim (ario-gar)
+    // =========================================
+    /** Claim tokens from a completed withdrawal (after lock period). */
+    async claimWithdrawal(params, _options) {
+        const garConfig = await this.getGarConfig();
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, BigInt(params.withdrawalId), this.garProgram);
+        const ownerATA = await getAssociatedTokenAddressKit(garConfig.mint, this.signer.address);
+        const ix = await getClaimWithdrawalInstructionAsync(await this.withGarDefaults({
+            withdrawal: withdrawalPda,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            ownerTokenAccount: ownerATA,
+            owner: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
+    // Claim delegation from leaving gateway (ario-gar)
+    // =========================================
+    /** Claim delegated stake from a gateway that is leaving the network. */
+    async claimDelegateFromLeavingGateway(params, _options) {
+        const gateway = address(params.gatewayAddress);
+        const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(gateway, this.signer.address, this.garProgram);
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, nextId, this.garProgram);
+        // The on-chain handler is permissionless since `af38a40` (delegator +
+        // payer split — anyone can crank). The IDL exposes both fields:
+        // `delegator: Address` (no signature, just the seeds-derivation key)
+        // and `payer: Signer` (covers rent on the init_if_needed withdrawal
+        // counter + the new withdrawal account). The SDK's primary self-
+        // claim path passes the signer for both roles; cranker callers can
+        // pass distinct addresses by adding a `payer?` param to this method
+        // (out of scope here — feature gap; tracked in
+        // docs/E2E_TEST_COVERAGE_PLAN.md Phase 3.3).
+        const ix = await getClaimDelegateFromLeavingGatewayInstructionAsync({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            withdrawal: withdrawalPda,
+            delegator: this.signer.address,
+            payer: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
+    // Delegation allowlist (ario-gar)
+    // =========================================
+    /** Add an address to the gateway's delegation allowlist. */
+    async allowDelegate(params, _options) {
+        const ix = await getAllowDelegateInstructionAsync({
+            delegate: address(params.delegate),
+            operator: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    /** Remove an address from the gateway's delegation allowlist. */
+    async disallowDelegate(params, _options) {
+        const ix = await getDisallowDelegateInstructionAsync({
+            delegate: address(params.delegate),
+            operator: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    /** Enable or disable the delegation allowlist for the gateway. */
+    async setAllowlistEnabled(params, _options) {
+        const ix = await getSetAllowlistEnabledInstructionAsync(await this.withGarDefaults({
+            operator: this.signer,
+            enabled: params.enabled,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
+    // Buy returned name (ario-arns)
+    // =========================================
+    /**
+     * Buy a name from the returned name auction (Dutch auction with premium).
+     *
+     * Phase 4: now dispatches on `params.fundFrom`. Note that for
+     * `buyReturnedName`, only the protocol share funds from the chosen source;
+     * the initiator share is always a direct buyer-ATA → initiator-ATA SPL
+     * transfer (matches the on-chain `_from_*` variant behavior).
+     */
+    async buyReturnedName(params, _options) {
+        const arnsConfig = await this.getArnsConfig();
+        const buyerATA = await getAssociatedTokenAddressKit(arnsConfig.mint, this.signer.address);
+        const antPubkey = address(params.processId);
+        // Read the ReturnedName to find the original initiator (gets the premium).
+        const [returnedNamePda] = await getReturnedNamePDA(params.name, this.arnsProgram);
+        const returnedNameAccount = await fetchEncodedAccount(this.rpc, returnedNamePda, { commitment: this.commitment });
+        if (!returnedNameAccount.exists) {
+            throw new Error(`Returned name not found: ${params.name}`);
+        }
+        const returnedNameData = Buffer.from(returnedNameAccount.data);
+        const nameLen = returnedNameData.readUInt32LE(8);
+        const initiatorOffset = 8 + 4 + nameLen + 32;
+        const initiator = addressDecoder.decode(returnedNameData.subarray(initiatorOffset, initiatorOffset + 32));
+        const initiatorATA = await getAssociatedTokenAddressKit(arnsConfig.mint, initiator);
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const buyParams = {
+            name: params.name,
+            purchaseType: params.type === 'permabuy' ? PurchaseType.Permabuy : PurchaseType.Lease,
+            years: params.years ?? 1,
+            ant: antPubkey,
+        };
+        let ix;
+        if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            ix = await getBuyReturnedNameInstructionAsync(await this.withArnsDefaults({
+                arnsRecord,
+                returnedName: returnedNamePda,
+                buyerTokenAccount: buyerATA,
+                protocolTokenAccount: arnsConfig.treasury,
+                initiatorTokenAccount: initiatorATA,
+                buyer: this.signer,
+                params: buyParams,
+            }), { programAddress: this.arnsProgram });
+        }
+        else {
+            const garConfig = await this.getGarConfig();
+            const [garSettings] = await getGarSettingsPDA(this.garProgram);
+            const sharedReturnedBase = {
+                config: await this.arnsConfigPda(),
+                demandFactor: await this.demandFactorPda(),
+                returnedName: returnedNamePda,
+                arnsRecord,
+                nameRegistry: await this.nameRegistryPda(),
+                buyerTokenAccount: buyerATA,
+                initiatorTokenAccount: initiatorATA,
+                garSettings,
+                stakeTokenAccount: garConfig.stakeTokenAccount,
+                protocolTokenAccount: arnsConfig.treasury,
+                buyer: this.signer,
+                garProgram: this.garProgram,
+                params: buyParams,
+            };
+            if (params.fundFrom === 'stakes' && params.gatewayAddress) {
+                const gatewayAddr = address(params.gatewayAddress);
+                const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+                if (params.fundAsOperator) {
+                    ix = await getBuyReturnedNameFromOperatorStakeInstructionAsync({ ...sharedReturnedBase, gateway: gatewayPda }, { programAddress: this.arnsProgram });
+                }
+                else {
+                    const [delegationPda] = await getDelegationPDA(gatewayAddr, this.signer.address, this.garProgram);
+                    ix = await getBuyReturnedNameFromDelegationInstructionAsync({
+                        ...sharedReturnedBase,
+                        gateway: gatewayPda,
+                        delegation: delegationPda,
+                    }, { programAddress: this.arnsProgram });
+                }
+            }
+            else if (params.fundFrom === 'withdrawal' &&
+                params.withdrawalId !== undefined) {
+                const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, params.withdrawalId, 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({
+                    name: params.name,
+                    purchaseType: buyParams.purchaseType,
+                    years: buyParams.years,
+                });
+                const plan = await this._resolveFundingPlan(params, cost);
+                const { remainingAccounts, withdrawalCounter, residueVaultCount } = await this._materializeFundingPlan(params, plan);
+                ix = await getBuyReturnedNameFromFundingPlanInstructionAsync({
+                    ...sharedReturnedBase,
+                    payerTokenAccount: plan.hasBalanceSource ? buyerATA : undefined,
+                    withdrawalCounter,
+                    sources: plan.sources.map(toGeneratedFundingSourceSpec),
+                    discountAccountCount: 0,
+                    residueVaultCount,
+                }, { programAddress: this.arnsProgram });
+                if (remainingAccounts.length > 0)
+                    ix = withRemainingAccounts(ix, remainingAccounts);
+            }
+            else {
+                throw new Error(`unsupported fundFrom mode '${params.fundFrom}' for buyReturnedName`);
+            }
+        }
+        // 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]);
+        return { id: sig };
+    }
+    // =========================================
+    // Name management (ario-arns)
+    // =========================================
+    /** Reassign an ArNS name to a different ANT. */
+    async reassignName(params, _options) {
+        const newAnt = address(params.processId);
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const ix = await getReassignNameInstructionAsync(await this.withArnsDefaults({
+            arnsRecord,
+            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).
+        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]);
+        return { id: sig };
+    }
+    /** Release a permabuy name back to the registry (creates a returned name auction). */
+    async releaseName(params, _options) {
+        const [returnedNamePda] = await getReturnedNamePDA(params.name, this.arnsProgram);
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const ix = await getReleaseNameInstructionAsync(await this.withArnsDefaults({
+            arnsRecord,
+            returnedName: returnedNamePda,
+            caller: this.signer,
+        }), { programAddress: this.arnsProgram });
+        // Note: no sync_attributes bundle here — release_name closes the
+        // ArnsRecord PDA, so a follow-up sync would fail PDA validation. The
+        // asset's stale traits remain pointing at the released name; off-chain
+        // resolvers should treat ArnsRecord as the source of truth and ignore
+        // a "ArNS Name" trait that no longer resolves.
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Epoch cranking (ario-gar) — permissionless
+    // =========================================
+    /**
+     * Create a new epoch. Permissionless — anyone can call when the next
+     * epoch's start time has arrived.
+     */
+    async createEpoch(_options) {
+        const garConfig = await this.getGarConfig();
+        const [epochSettingsPda] = await getEpochSettingsPDA(this.garProgram);
+        const settingsAccount = await fetchEncodedAccount(this.rpc, epochSettingsPda, { commitment: this.commitment });
+        if (!settingsAccount.exists)
+            throw new Error('EpochSettings not found');
+        const settings = deserializeEpochSettingsFull(Buffer.from(settingsAccount.data));
+        const epochIndex = settings.currentEpochIndex;
+        const [epochPda] = await getEpochPDA(epochIndex, this.garProgram);
+        const ix = await getCreateEpochInstructionAsync(await this.withGarDefaults({
+            epoch: epochPda,
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            payer: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Tally weights for a batch of gateways. Permissionless — call repeatedly
+     * until all gateways are processed. Pass gateway PDAs as
+     * `gatewayAccounts`; they're appended as `remaining_accounts`.
+     */
+    async tallyWeights(params, _options) {
+        const ix = await getTallyWeightsInstructionAsync(await this.withGarDefaults({
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const remaining = params.gatewayAccounts.map((address) => ({
+            address,
+            role: AccountRole.WRITABLE,
+        }));
+        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Prescribe observers and names for an epoch. Permissionless — call after
+     * weights are tallied. Gateway PDAs are appended as `remaining_accounts`,
+     * and the optional `nameRegistryAccount` (must be last) enables the name
+     * prescription leg.
+     */
+    async prescribeEpoch(params, _options) {
+        const ix = await getPrescribeEpochInstructionAsync(await this.withGarDefaults({
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const remaining = params.gatewayAccounts.map((address) => ({
+            address,
+            role: AccountRole.READONLY,
+        }));
+        if (params.nameRegistryAccount) {
+            remaining.push({
+                address: params.nameRegistryAccount,
+                role: AccountRole.READONLY,
+            });
+        }
+        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Distribute rewards for a completed epoch in batches. Permissionless —
+     * call after epoch ends. Gateway PDAs appended as `remaining_accounts`.
+     */
+    async distributeEpoch(params, _options) {
+        const garConfig = await this.getGarConfig();
+        // ario_gar::distribute_epoch CPIs into ario_core::release_treasury_to_recipient
+        // (signed by the ArioConfig PDA — the canonical treasury authority). The
+        // generated builder expects `arioConfig` + `arioCoreProgram` accounts at
+        // positions 6+7 (post-PR-19 in ar-io-solana-contracts). Pin both to the
+        // configured core program so devnet/testnet deployments don't fall back
+        // to the bundled mainnet default.
+        const [arioConfig] = await getArioConfigPDA(this.coreProgram);
+        const ix = await getDistributeEpochInstructionAsync(await this.withGarDefaults({
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            arioConfig,
+            arioCoreProgram: this.coreProgram,
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const remaining = params.gatewayAccounts.map((address) => ({
+            address,
+            role: AccountRole.WRITABLE,
+        }));
+        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Close an old epoch account and reclaim rent. Permissionless — call after
+     * the epoch is distributed and at least 7 epochs have passed.
+     */
+    async closeEpoch(params, _options) {
+        const ix = await getCloseEpochInstructionAsync(await this.withGarDefaults({
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Cranker helpers
+    // =========================================
+    /**
+     * Get gateway PDAs for a batch starting at registryIndex.
+     * Reads the GatewayRegistry and derives PDAs for the next `batchSize`
+     * active gateways.
+     */
+    async getRegistryGatewayPDAs(startIndex, batchSize) {
+        const [registryPda] = await getGatewayRegistryPDA(this.garProgram);
+        const registryAccount = await fetchEncodedAccount(this.rpc, registryPda, {
+            commitment: this.commitment,
+        });
+        if (!registryAccount.exists)
+            return [];
+        const registryData = Buffer.from(registryAccount.data);
+        const count = registryData.readUInt32LE(40); // 8 disc + 32 authority
+        const slotsOffset = 48; // 8 + 32 + 4 + 4
+        // GatewaySlot: address(32) + composite_weight(8) + start_timestamp(8)
+        //            + status(1) + _padding(7) = 56 bytes.
+        const SLOT_STRIDE = 56;
+        const pdas = [];
+        const end = Math.min(startIndex + batchSize, count);
+        const zero = '11111111111111111111111111111111';
+        for (let i = startIndex; i < end && i < 3000; i++) {
+            const slotOffset = slotsOffset + i * SLOT_STRIDE;
+            const addr = addressDecoder.decode(registryData.subarray(slotOffset, slotOffset + 32));
+            if (addr === zero)
+                continue;
+            const [gatewayPda] = await getGatewayPDA(addr, this.garProgram);
+            pdas.push(gatewayPda);
+        }
+        return pdas;
+    }
+    /** Get ALL active gateway PDAs from the registry. */
+    async getAllRegistryGatewayPDAs() {
+        const [registryPda] = await getGatewayRegistryPDA(this.garProgram);
+        const registryAccount = await fetchEncodedAccount(this.rpc, registryPda, {
+            commitment: this.commitment,
+        });
+        if (!registryAccount.exists)
+            return [];
+        const registryData = Buffer.from(registryAccount.data);
+        const count = registryData.readUInt32LE(40);
+        const slotsOffset = 48;
+        const SLOT_STRIDE = 56;
+        const pdas = [];
+        const zero = '11111111111111111111111111111111';
+        for (let i = 0; i < count && i < 3000; i++) {
+            const slotOffset = slotsOffset + i * SLOT_STRIDE;
+            const addr = addressDecoder.decode(registryData.subarray(slotOffset, slotOffset + 32));
+            if (addr === zero)
+                continue;
+            const [gatewayPda] = await getGatewayPDA(addr, this.garProgram);
+            pdas.push(gatewayPda);
+        }
+        return pdas;
+    }
+    /**
+     * Read the raw epoch account data for cranker state inspection.
+     * Returns null if the epoch account doesn't exist yet.
+     */
+    async getEpochRaw(epochIndex) {
+        const [epochPda] = await getEpochPDA(epochIndex, this.garProgram);
+        const account = await fetchEncodedAccount(this.rpc, epochPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return null;
+        try {
+            return this.fetchEpochRawFields(Buffer.from(account.data));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Parse raw epoch account data for cranker-relevant fields.
+     * Offsets match the Rust Epoch zero-copy struct (repr(C)).
+     *
+     * Layout after 8-byte discriminator:
+     *   [8 epoch_index][8 start_ts][8 end_ts][8 total_eligible][8 per_gw]
+     *   [8 per_obs][8 reward_rate][8 weight_lo][8 weight_hi][32 hashchain]
+     *   [4 active_gw_count][4 dist_idx][4 tally_idx]
+     *   [1 observer_count][1 name_count][1 obs_submitted][1 rewards_dist]
+     *   [1 weights_tallied][1 prescriptions_done][1 bump][1 _pad1]
+     *   [6000 failure_counts][1600 prescribed_observers]
+     *   [1600 prescribed_observer_gateways][64 prescribed_names]
+     *   [7 has_observed][5 _pad2]
+     */
+    fetchEpochRawFields(data) {
+        const base = 8;
+        const endTimestamp = Number(data.readBigInt64LE(base + 16));
+        const activeGatewayCount = data.readUInt32LE(base + 104);
+        const distributionIndex = data.readUInt32LE(base + 108);
+        const tallyIndex = data.readUInt32LE(base + 112);
+        const rewardsDistributed = data.readUInt8(base + 119);
+        const weightsTallied = data.readUInt8(base + 120);
+        const prescriptionsDone = data.readUInt8(base + 121);
+        return {
+            tallyIndex,
+            distributionIndex,
+            weightsTallied,
+            prescriptionsDone,
+            rewardsDistributed,
+            activeGatewayCount,
+            endTimestamp,
+        };
+    }
+    // =========================================
+    // Prune / cleanup (permissionless crank)
+    // =========================================
+    //
+    // These mirror `tick()`-driven lazy pruning in the Lua source — on Solana
+    // each is a discrete instruction someone has to call. All are
+    // permissionless except `releaseVault`, which the on-chain handler still
+    // gates on `owner: Signer` (ADR / vault.rs::ReleaseVault). See
+    // docs/CRANKER_PRUNING_PLAN.md for the full design.
+    /**
+     * Batch-prune expired ArnsRecord PDAs from the NameRegistry. The caller
+     * supplies the eligible records as `arnsRecords` — they're appended as
+     * `remaining_accounts` and the on-chain handler verifies each is past
+     * `end_timestamp + grace_period + return_auction_duration` before closing.
+     * `maxNames` caps the per-tx work (u8). Submit in batches of ~10-15.
+     */
+    async pruneExpiredNames(params, _options) {
+        const ix = await getPruneExpiredNamesInstructionAsync(await this.withArnsDefaults({
+            payer: this.signer,
+            maxNames: params.maxNames,
+        }), { programAddress: this.arnsProgram });
+        const remaining = params.arnsRecords.map((a) => ({
+            address: address(a),
+            role: AccountRole.WRITABLE,
+        }));
+        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Convert a single expired-but-not-yet-returned lease into a `ReturnedName`
+     * (kicks off the Dutch auction). Permissionless.
+     */
+    async pruneNameToReturned(params, _options) {
+        const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
+        const [returnedName] = await getReturnedNamePDA(params.name, this.arnsProgram);
+        const ix = await getPruneNameToReturnedInstructionAsync(await this.withArnsDefaults({
+            arnsRecord,
+            returnedName,
+            payer: this.signer,
+        }), { programAddress: this.arnsProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Batch-prune expired ReturnedName PDAs (auction window elapsed). Caller
+     * supplies the eligible PDAs as `returnedNames`; they're appended as
+     * `remaining_accounts`. `maxNames` caps per-tx work (u8).
+     */
+    async pruneReturnedNames(params, _options) {
+        const ix = await getPruneReturnedNamesInstructionAsync(await this.withArnsDefaults({
+            payer: this.signer,
+            maxNames: params.maxNames,
+        }), { programAddress: this.arnsProgram });
+        const remaining = params.returnedNames.map((a) => ({
+            address: address(a),
+            role: AccountRole.WRITABLE,
+        }));
+        // Match `pruneExpiredNames` (1M CU) — both dispatch the same batched
+        // shape over `remaining_accounts`, and the default 400K is too tight
+        // when the cranker batches near `maxNames` (≈15) on a busy registry.
+        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * Close a single expired ReservedName PDA. Permissionless after
+     * `expires_at`.
+     */
+    async pruneExpiredReservation(params, _options) {
+        const [reservedName] = await getReservedNamePDA(params.name, this.arnsProgram);
+        const ix = getPruneExpiredReservationInstruction({
+            reservedName,
+            payer: this.signer,
+        }, { programAddress: this.arnsProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Slash and remove a deficient gateway (`stats.failed_consecutive >=
+     * max_consecutive_failures`). Builds the protected exit vault for the
+     * post-slash min portion plus the optional excess vault for any surplus.
+     * The contract's `excess_withdrawal: Option<UncheckedAccount>` slot is
+     * always passed (PDA derived from `next_id + 1`); the handler consumes
+     * it only when the post-slash stake exceeds `min_operator_stake`.
+     * Permissionless.
+     */
+    async pruneGateway(params, _options) {
+        const gatewayAddr = address(params.gateway);
+        const garConfig = await this.getGarConfig();
+        const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+        const [withdrawalCounterPda] = await getWithdrawalCounterPDA(gatewayAddr, this.garProgram);
+        const nextId = await this.getNextWithdrawalId(gatewayAddr);
+        const [withdrawalPda] = await getWithdrawalPDA(gatewayAddr, nextId, this.garProgram);
+        const [excessWithdrawalPda] = await getWithdrawalPDA(gatewayAddr, nextId + 1n, this.garProgram);
+        const ix = await getPruneGatewayInstructionAsync(await this.withGarDefaults({
+            gateway: gatewayPda,
+            withdrawalCounter: withdrawalCounterPda,
+            withdrawal: withdrawalPda,
+            excessWithdrawal: excessWithdrawalPda,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            payer: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    /**
+     * GC a `Leaving`/`Gone` gateway whose leave window has fully elapsed.
+     * Closes the Gateway PDA and refunds rent to the caller. Permissionless.
+     */
+    async finalizeGone(params, _options) {
+        const gatewayAddr = address(params.gateway);
+        const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+        const ix = await getFinalizeGoneInstructionAsync(await this.withGarDefaults({
+            gateway: gatewayPda,
+            caller: this.signer,
+        }), { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Reclaim rent from an Observation PDA whose epoch has been distributed.
+     * Permissionless. Pass `epochIndex` and the `observer` address used as
+     * the Observation seed.
+     */
+    async closeObservation(params, _options) {
+        const observerAddr = address(params.observer);
+        const [observationPda] = await getObservationPDA(params.epochIndex, observerAddr, this.garProgram);
+        const ix = await getCloseObservationInstructionAsync({
+            observation: observationPda,
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Close an empty Delegation PDA (`amount == 0`) and refund rent to the
+     * original delegator (NOT the caller — see GAR-016, prevents griefing).
+     * Permissionless.
+     */
+    async closeEmptyDelegation(params, _options) {
+        const gatewayAddr = address(params.gateway);
+        const delegatorAddr = address(params.delegator);
+        const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(gatewayAddr, delegatorAddr, this.garProgram);
+        const ix = getCloseEmptyDelegationInstruction({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            delegator: delegatorAddr,
+            payer: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Close a drained Withdrawal PDA (`amount == 0`) and refund rent to the
+     * original owner (NOT the caller). Permissionless.
+     */
+    async closeDrainedWithdrawal(params, _options) {
+        const ownerAddr = address(params.owner);
+        const [withdrawalPda] = await getWithdrawalPDA(ownerAddr, BigInt(params.withdrawalId), this.garProgram);
+        const ix = getCloseDrainedWithdrawalInstruction({
+            withdrawal: withdrawalPda,
+            owner: ownerAddr,
+            closer: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+}