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

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

@@ -0,0 +1,1994 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SolanaARIOWriteable = void 0;
+exports.splitPrimaryName = splitPrimaryName;
+/**
+ * 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.
+ */
+const kit_1 = require("@solana/kit");
+const ata_js_1 = require("./ata.js");
+const deserialize_js_1 = require("./deserialize.js");
+const funding_plan_js_1 = require("./funding-plan.js");
+const index_js_1 = require("./generated/arns/instructions/index.js");
+const index_js_2 = require("./generated/arns/types/index.js");
+const index_js_3 = require("./generated/gar/types/index.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: index_js_3.FundingSourceKind.Balance,
+        delegation: index_js_3.FundingSourceKind.Delegation,
+        operatorStake: index_js_3.FundingSourceKind.OperatorStake,
+        withdrawal: index_js_3.FundingSourceKind.Withdrawal,
+    };
+    return { kind: kindMap[s.kind], amount: s.amount };
+}
+const syncAttributes_js_1 = require("./generated/ant/instructions/syncAttributes.js");
+const index_js_4 = require("./generated/core/instructions/index.js");
+const delegation_js_1 = require("./generated/gar/accounts/delegation.js");
+const gateway_js_1 = require("./generated/gar/accounts/gateway.js");
+const index_js_5 = require("./generated/gar/instructions/index.js");
+const index_js_6 = require("./generated/gar/types/index.js");
+const io_readable_js_1 = require("./io-readable.js");
+const pda_js_1 = require("./pda.js");
+const send_js_1 = require("./send.js");
+const addressDecoder = (0, kit_1.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.
+ */
+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 });
+ * ```
+ */
+class SolanaARIOWriteable extends io_readable_js_1.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 (0, send_js_1.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 (0, pda_js_1.getArioConfigPDA)(this.coreProgram);
+        const account = await (0, kit_1.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 (0, pda_js_1.getArnsSettingsPDA)(this.arnsProgram);
+        const account = await (0, kit_1.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 (0, pda_js_1.getGarSettingsPDA)(this.garProgram);
+        const account = await (0, kit_1.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 (0, pda_js_1.getArnsSettingsPDA)(this.arnsProgram);
+        const [demandFactor] = await (0, pda_js_1.getDemandFactorPDA)(this.arnsProgram);
+        const [nameRegistry] = await (0, pda_js_1.getArnsRegistryPDA)(this.arnsProgram);
+        return { config, demandFactor, nameRegistry, ...input };
+    }
+    /** Inject ARIO core default PDAs (config). */
+    async withCoreDefaults(input) {
+        const [config] = await (0, pda_js_1.getArioConfigPDA)(this.coreProgram);
+        return { config, ...input };
+    }
+    /** Inject GAR default PDAs (settings, epochSettings, registry). */
+    async withGarDefaults(input) {
+        const [settings] = await (0, pda_js_1.getGarSettingsPDA)(this.garProgram);
+        const [epochSettings] = await (0, pda_js_1.getEpochSettingsPDA)(this.garProgram);
+        const [registry] = await (0, pda_js_1.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 (0, pda_js_1.getWithdrawalCounterPDA)(owner, this.garProgram);
+        const account = await (0, kit_1.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 = (0, kit_1.address)(params.target);
+        const mint = await this.getMint();
+        const fromATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, this.signer.address);
+        const toATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, recipient);
+        const ix = (0, index_js_4.getTransferInstruction)({
+            fromTokenAccount: fromATA,
+            toTokenAccount: toATA,
+            authority: this.signer,
+            amount,
+        }, { programAddress: this.coreProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async vaultedTransfer(params, _options) {
+        const amount = toAmount(params.quantity);
+        const lockSeconds = Math.floor(params.lockLengthMs / 1000);
+        const recipient = (0, kit_1.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 (0, pda_js_1.getVaultPDA)(recipient, nextId, this.coreProgram);
+        const senderATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, this.signer.address);
+        const vaultATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, vaultPda, true);
+        const ix = await (0, index_js_4.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 = (0, ata_js_1.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 (0, pda_js_1.getVaultPDA)(this.signer.address, nextId, this.coreProgram);
+        const ownerATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, this.signer.address);
+        const vaultATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, vaultPda, true);
+        const ix = await (0, index_js_4.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 = (0, ata_js_1.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 Promise.resolve().then(() => __importStar(require('./pda.js')));
+        const [counterPda] = await getVaultCounterPDA(owner, this.coreProgram);
+        const account = await (0, kit_1.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 (0, pda_js_1.getVaultPDA)(this.signer.address, BigInt(params.vaultId), this.coreProgram);
+        const ix = await (0, index_js_4.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 (0, pda_js_1.getVaultPDA)(this.signer.address, BigInt(params.vaultId), this.coreProgram);
+        const ownerATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, this.signer.address);
+        const vaultATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, vaultPda, true);
+        const ix = await (0, index_js_4.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 = (0, kit_1.address)(params.recipient);
+        const mint = await this.getMint();
+        const [vaultPda] = await (0, pda_js_1.getVaultPDA)(recipient, BigInt(params.vaultId), this.coreProgram);
+        const vaultATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, vaultPda, true);
+        const controllerATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, this.signer.address);
+        const ix = await (0, index_js_4.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 (0, ata_js_1.getAssociatedTokenAddressKit)(garConfig.mint, this.signer.address);
+        const observerAddress = params.observerAddress
+            ? (0, kit_1.address)(params.observerAddress)
+            : this.signer.address;
+        const [observerLookupPda] = await (0, pda_js_1.getObserverLookupPDA)(observerAddress, this.garProgram);
+        const ix = await (0, index_js_5.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: index_js_6.Protocol.Https,
+            properties: params.properties ?? null,
+            note: params.note ?? null,
+            autoStake: params.autoStake ?? false,
+            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 (0, pda_js_1.getWithdrawalPDA)(this.signer.address, nextId, this.garProgram);
+        const [excessVaultPda] = await (0, pda_js_1.getWithdrawalPDA)(this.signer.address, nextId + 1n, this.garProgram);
+        const ix = await (0, index_js_5.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 (0, index_js_5.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,
+            autoStake: params.autoStake ?? 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 (0, ata_js_1.getAssociatedTokenAddressKit)(garConfig.mint, this.signer.address);
+        const ix = await (0, index_js_5.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 (0, pda_js_1.getWithdrawalPDA)(this.signer.address, nextId, this.garProgram);
+        const ix = await (0, index_js_5.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 = (0, kit_1.address)(params.target);
+        const garConfig = await this.getGarConfig();
+        const [gatewayPda] = await (0, pda_js_1.getGatewayPDA)(target, this.garProgram);
+        const [delegationPda] = await (0, pda_js_1.getDelegationPDA)(target, this.signer.address, this.garProgram);
+        const delegatorATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(garConfig.mint, this.signer.address);
+        const ix = await (0, index_js_5.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 = (0, kit_1.address)(params.target);
+        const [gatewayPda] = await (0, pda_js_1.getGatewayPDA)(target, this.garProgram);
+        const [delegationPda] = await (0, pda_js_1.getDelegationPDA)(target, this.signer.address, this.garProgram);
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [withdrawalPda] = await (0, pda_js_1.getWithdrawalPDA)(this.signer.address, nextId, this.garProgram);
+        const ix = await (0, index_js_5.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 (0, pda_js_1.getWithdrawalPDA)(this.signer.address, BigInt(params.vaultId), this.garProgram);
+        const ownerATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(garConfig.mint, this.signer.address);
+        const ix = await (0, index_js_5.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
+            ? (0, kit_1.address)(params.gatewayAddress)
+            : this.signer.address;
+        const [gatewayPda] = await (0, pda_js_1.getGatewayPDA)(gateway, this.garProgram);
+        const [withdrawalPda] = await (0, pda_js_1.getWithdrawalPDA)(this.signer.address, BigInt(params.vaultId), this.garProgram);
+        const isDelegate = gateway !== this.signer.address;
+        const delegation = isDelegate
+            ? (await (0, pda_js_1.getDelegationPDA)(gateway, this.signer.address, this.garProgram))[0]
+            : undefined;
+        const [settingsPda] = await (0, pda_js_1.getGarSettingsPDA)(this.garProgram);
+        const ix = (0, index_js_5.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 (0, pda_js_1.getEpochSettingsPDA)(this.garProgram);
+            const settingsAccount = await (0, kit_1.fetchEncodedAccount)(this.rpc, settingsPda, {
+                commitment: this.commitment,
+            });
+            if (!settingsAccount.exists)
+                throw new Error('EpochSettings not found');
+            const settings = (0, deserialize_js_1.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 = Buffer.alloc(375, 0xff); // start all-passed
+            const failedSet = new Set(params.failedGateways);
+            for (let i = 0; i < gatewayCount; i++) {
+                if (failedSet.has(registryAddresses[i])) {
+                    resultsBuf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+                }
+            }
+            // Clear bits beyond the active gateway count.
+            for (let i = gatewayCount; i < 3000; i++) {
+                resultsBuf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+            }
+        }
+        // report_tx_id is a fixed [u8; 32] (Arweave TX ID). The legacy SDK
+        // truncates the raw string bytes; mirror that for compatibility.
+        const reportTxId = Buffer.alloc(32);
+        Buffer.from(params.reportTxId).copy(reportTxId, 0, 0, Math.min(32, params.reportTxId.length));
+        const ix = await (0, index_js_5.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 = (0, kit_1.address)(params.source);
+        const target = (0, kit_1.address)(params.target);
+        const garConfig = await this.getGarConfig();
+        const [sourceGatewayPda] = await (0, pda_js_1.getGatewayPDA)(source, this.garProgram);
+        const [targetGatewayPda] = await (0, pda_js_1.getGatewayPDA)(target, this.garProgram);
+        const [sourceDelegationPda] = await (0, pda_js_1.getDelegationPDA)(source, this.signer.address, this.garProgram);
+        const [targetDelegationPda] = await (0, pda_js_1.getDelegationPDA)(target, this.signer.address, this.garProgram);
+        const delegatorATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(garConfig.mint, this.signer.address);
+        const ix = await (0, index_js_5.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 (0, ata_js_1.getAssociatedTokenAddressKit)(arnsConfig.mint, this.signer.address);
+        const antPubkey = (0, kit_1.address)(params.processId ?? '11111111111111111111111111111111');
+        const [arnsRecord] = await (0, pda_js_1.getArnsRecordPDA)(params.name, this.arnsProgram);
+        const [reservedNameCheck] = await (0, pda_js_1.getReservedNamePDA)(params.name, this.arnsProgram);
+        const [returnedNameCheck] = await (0, pda_js_1.getReturnedNamePDA)(params.name, this.arnsProgram);
+        const buyNameParams = {
+            name: params.name,
+            purchaseType: params.type === 'permabuy' ? index_js_2.PurchaseType.Permabuy : index_js_2.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 = (0, kit_1.address)(params.gatewayAddress);
+            const garConfig = await this.getGarConfig();
+            const [garSettings] = await (0, pda_js_1.getGarSettingsPDA)(this.garProgram);
+            const [gatewayPda] = await (0, pda_js_1.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 (0, index_js_1.getBuyNameFromOperatorStakeInstructionAsync)(baseShared, {
+                    programAddress: this.arnsProgram,
+                });
+            }
+            else {
+                const [delegationPda] = await (0, pda_js_1.getDelegationPDA)(gatewayAddr, this.signer.address, this.garProgram);
+                ix = await (0, index_js_1.getBuyNameFromDelegationInstructionAsync)({ ...baseShared, delegation: delegationPda }, { programAddress: this.arnsProgram });
+            }
+        }
+        else if (params.fundFrom === 'withdrawal' &&
+            params.withdrawalId !== undefined) {
+            const garConfig = await this.getGarConfig();
+            const [garSettings] = await (0, pda_js_1.getGarSettingsPDA)(this.garProgram);
+            const [withdrawalPda] = await (0, pda_js_1.getWithdrawalPDA)(this.signer.address, params.withdrawalId, this.garProgram);
+            ix = await (0, index_js_1.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 (0, index_js_1.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
+                ? (0, kit_1.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 (0, kit_1.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 Promise.resolve().then(() => __importStar(require('./funding-plan.js')));
+        const sources = await discoverFundingSources(this.rpc, this.signer.address, {
+            arioMint: arnsConfig.mint,
+            garProgram: this.garProgram,
+        });
+        const plan = (0, funding_plan_js_1.buildFundingPlan)(sources, amountNeeded, {
+            fundFrom: params.fundFrom,
+            preferGateway: params.gatewayAddress
+                ? (0, kit_1.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 (0, pda_js_1.getGarSettingsPDA)(this.garProgram);
+        const buyerATA = await (0, ata_js_1.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 (0, index_js_1.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 (0, pda_js_1.getDelegationPDA)(gateway, owner, this.garProgram);
+            const [gatewayPda] = await (0, pda_js_1.getGatewayPDA)(gateway, this.garProgram);
+            const [delAcct, gwAcct] = await Promise.all([
+                (0, kit_1.fetchEncodedAccount)(this.rpc, delegationPda, {
+                    commitment: this.commitment,
+                }),
+                (0, kit_1.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 = (0, delegation_js_1.getDelegationDecoder)();
+        const gatewayDecoder = (0, gateway_js_1.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 (0, funding_plan_js_1.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 (0, funding_plan_js_1.predictResidueVaults)(this.rpc, this.signer.address, plan, { garProgram: this.garProgram });
+        const remainingAccounts = await (0, funding_plan_js_1.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 (0, pda_js_1.getDemandFactorPDA)(this.arnsProgram);
+        const dfAccount = await (0, kit_1.fetchEncodedAccount)(this.rpc, demandFactorPda, {
+            commitment: this.commitment,
+        });
+        if (!dfAccount.exists)
+            throw new Error('DemandFactor not found');
+        // Layout: disc(8) + current_demand_factor(8) + ... + fees[51](u64×51).
+        // Fees array starts at offset that depends on the struct layout — we
+        // safely read the first 8+51*8 bytes.
+        const data = Buffer.from(dfAccount.data);
+        const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+        const demandFactor = dv.getBigUint64(8, true);
+        // Fees layout is: disc(8) + current_demand_factor(8) +
+        //                 purchases_this_period(8) + revenue_this_period(8) +
+        //                 period_zero_start_timestamp(8) + ... + fees[51]
+        // To stay decoupled from non-fee fields, we read the whole array
+        // assuming fees starts at a known offset. See ArNS DemandFactor struct.
+        // Pragmatic fallback: use a fixed fees offset of 56 (post-disc + 6 u64s).
+        const FEES_OFFSET = 56;
+        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 === index_js_2.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 (0, pda_js_1.getArnsSettingsPDA)(this.arnsProgram);
+        return pda;
+    }
+    async demandFactorPda() {
+        const [pda] = await (0, pda_js_1.getDemandFactorPDA)(this.arnsProgram);
+        return pda;
+    }
+    async nameRegistryPda() {
+        const [pda] = await (0, pda_js_1.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 = (0, kit_1.address)(record.processId);
+        }
+        const { fetchMplCoreOwner } = await Promise.resolve().then(() => __importStar(require('./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, (0, kit_1.address)(record.processId));
+    }
+    /** Pure builder; no RPC. Used by both gated + unconditional helpers. */
+    async _buildSyncAttributesIxFor(name, asset) {
+        const [arnsRecord] = await (0, pda_js_1.getArnsRecordPDA)(name, this.arnsProgram);
+        return (0, syncAttributes_js_1.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 (0, ata_js_1.getAssociatedTokenAddressKit)(arnsConfig.mint, this.signer.address);
+        const [arnsRecord] = await (0, pda_js_1.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 (0, index_js_1.getUpgradeNameInstructionAsync)(baseAccounts, {
+                    programAddress: this.arnsProgram,
+                });
+            }
+            if (args.operation === 'extend') {
+                return (0, index_js_1.getExtendLeaseInstructionAsync)({ ...baseAccounts, years: args.years }, { programAddress: this.arnsProgram });
+            }
+            return (0, index_js_1.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 (0, pda_js_1.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 = (0, kit_1.address)(args.params.gatewayAddress);
+            const [gatewayPda] = await (0, pda_js_1.getGatewayPDA)(gatewayAddr, this.garProgram);
+            const stakeBase = { ...sharedManageBase, gateway: gatewayPda };
+            if (args.params.fundAsOperator) {
+                if (args.operation === 'upgrade')
+                    return (0, index_js_1.getUpgradeNameFromOperatorStakeInstructionAsync)(stakeBase, {
+                        programAddress: this.arnsProgram,
+                    });
+                if (args.operation === 'extend')
+                    return (0, index_js_1.getExtendLeaseFromOperatorStakeInstructionAsync)({ ...stakeBase, years: args.years }, { programAddress: this.arnsProgram });
+                return (0, index_js_1.getIncreaseUndernameLimitFromOperatorStakeInstructionAsync)({ ...stakeBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+            }
+            const [delegationPda] = await (0, pda_js_1.getDelegationPDA)(gatewayAddr, this.signer.address, this.garProgram);
+            const delBase = { ...stakeBase, delegation: delegationPda };
+            if (args.operation === 'upgrade')
+                return (0, index_js_1.getUpgradeNameFromDelegationInstructionAsync)(delBase, {
+                    programAddress: this.arnsProgram,
+                });
+            if (args.operation === 'extend')
+                return (0, index_js_1.getExtendLeaseFromDelegationInstructionAsync)({ ...delBase, years: args.years }, { programAddress: this.arnsProgram });
+            return (0, index_js_1.getIncreaseUndernameLimitFromDelegationInstructionAsync)({ ...delBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
+        }
+        if (args.params.fundFrom === 'withdrawal' &&
+            args.params.withdrawalId !== undefined) {
+            const [withdrawalPda] = await (0, pda_js_1.getWithdrawalPDA)(this.signer.address, args.params.withdrawalId, this.garProgram);
+            const wBase = { ...sharedManageBase, withdrawal: withdrawalPda };
+            if (args.operation === 'upgrade')
+                return (0, index_js_1.getUpgradeNameFromWithdrawalInstructionAsync)(wBase, {
+                    programAddress: this.arnsProgram,
+                });
+            if (args.operation === 'extend')
+                return (0, index_js_1.getExtendLeaseFromWithdrawalInstructionAsync)({ ...wBase, years: args.years }, { programAddress: this.arnsProgram });
+            return (0, index_js_1.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 (0, ata_js_1.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 (0, index_js_1.getUpgradeNameFromFundingPlanInstructionAsync)(fpBase, {
+                    programAddress: this.arnsProgram,
+                });
+            else if (args.operation === 'extend')
+                ix = await (0, index_js_1.getExtendLeaseFromFundingPlanInstructionAsync)({ ...fpBase, years: args.years }, { programAddress: this.arnsProgram });
+            else
+                ix = await (0, index_js_1.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 (0, pda_js_1.getDemandFactorPDA)(this.arnsProgram);
+        const dfAccount = await (0, kit_1.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 = 56;
+        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 (0, pda_js_1.getArnsRecordPDA)(baseName, this.arnsProgram);
+        const remaining = [
+            { address: arnsRecordPda, role: kit_1.AccountRole.READONLY },
+        ];
+        // Fee-charging variants need the demand factor for fee scaling.
+        if (variant === 'request' || variant === 'requestAndSet') {
+            const [demandFactorPda] = await (0, pda_js_1.getDemandFactorPDA)(this.arnsProgram);
+            remaining.push({ address: demandFactorPda, role: kit_1.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 (0, kit_1.fetchEncodedAccount)(this.rpc, arnsRecordPda, {
+                commitment: this.commitment,
+            });
+            if (!arnsAccount.exists) {
+                throw new Error(`ArNS record not found for base name: ${baseName}`);
+            }
+            const arnsRecord = (0, deserialize_js_1.deserializeArnsRecord)(Buffer.from(arnsAccount.data));
+            const antMint = (0, kit_1.address)(arnsRecord.processId);
+            const { fetchAntProgramFromAsset } = await Promise.resolve().then(() => __importStar(require('./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 (0, pda_js_1.getAntRecordPDA)(antMint, antUndername, antProgram);
+            remaining.push({ address: antRecordPda, role: kit_1.AccountRole.READONLY });
+        }
+        return { remaining, antProgram };
+    }
+    async requestPrimaryName(params, _options) {
+        const coreConfig = await this.getCoreConfig();
+        const signerATA = await (0, ata_js_1.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 (0, index_js_4.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 (0, ata_js_1.getAssociatedTokenAddressKit)(coreConfig.mint, this.signer.address);
+        const { remaining, antProgram } = await this._buildPrimaryNameValidationAccounts(params.name, 'requestAndSet');
+        if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            // Direct-transfer path: delegate to requestPrimaryName for now (this
+            // matches the pre-Phase-4 placeholder; the on-chain
+            // request_and_set_primary_name ix uses the same fee charge so the
+            // routing is functionally identical).
+            void signerATA;
+            return this.requestPrimaryName(params, _options);
+        }
+        const 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 (0, pda_js_1.getDemandFactorPDA)(this.arnsProgram);
+        const dfAccount = await (0, kit_1.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 (0, pda_js_1.getGarSettingsPDA)(this.garProgram);
+        const initiatorATA = await (0, ata_js_1.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 (0, pda_js_1.getPrimaryNameRequestPDA)(this.signer.address, this.coreProgram);
+            ix = await (0, index_js_4.getRequestPrimaryNameFromFundingPlanInstructionAsync)({ ...baseFp, request: requestPda, name: args.params.name }, { programAddress: this.coreProgram });
+        }
+        else {
+            const [primaryNamePda] = await (0, pda_js_1.getPrimaryNamePDA)(this.signer.address, this.coreProgram);
+            const [primaryNameReversePda] = await (0, pda_js_1.getPrimaryNameReversePDA)(args.params.name, this.coreProgram);
+            ix = await (0, index_js_4.getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync)({
+                ...baseFp,
+                primaryName: primaryNamePda,
+                primaryNameReverse: primaryNameReversePda,
+                name: args.params.name,
+                reverseLookupHash: (0, pda_js_1.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 (0, pda_js_1.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 (0, pda_js_1.getPrimaryNameRequestPDA)(params.initiator, this.coreProgram);
+        const [primaryNamePda] = await (0, pda_js_1.getPrimaryNamePDA)(params.initiator, this.coreProgram);
+        const [primaryNameReversePda] = await (0, pda_js_1.getPrimaryNameReversePDA)(params.name, this.coreProgram);
+        const { remaining, antProgram } = await this._buildPrimaryNameValidationAccounts(params.name, 'approve');
+        const ix = withRemainingAccounts(await (0, index_js_4.getApprovePrimaryNameInstructionAsync)({
+            request: requestPda,
+            initiator: params.initiator,
+            primaryName: primaryNamePda,
+            primaryNameReverse: primaryNameReversePda,
+            nameOwner: this.signer,
+            reverseLookupHash: (0, pda_js_1.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 (0, pda_js_1.getVaultPDA)(this.signer.address, BigInt(params.vaultId), this.coreProgram);
+        const vaultATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, vaultPda, true);
+        const ownerATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, this.signer.address);
+        const ix = await (0, index_js_4.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 = (0, kit_1.address)(params.initiator);
+        const [requestPda] = await (0, pda_js_1.getPrimaryNameRequestPDA)(initiatorPubkey, this.coreProgram);
+        const ix = (0, index_js_4.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 (0, pda_js_1.getWithdrawalPDA)(this.signer.address, BigInt(params.withdrawalId), this.garProgram);
+        const ownerATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(garConfig.mint, this.signer.address);
+        const ix = await (0, index_js_5.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 = (0, kit_1.address)(params.gatewayAddress);
+        const [gatewayPda] = await (0, pda_js_1.getGatewayPDA)(gateway, this.garProgram);
+        const [delegationPda] = await (0, pda_js_1.getDelegationPDA)(gateway, this.signer.address, this.garProgram);
+        const nextId = await this.getNextWithdrawalId(this.signer.address);
+        const [withdrawalPda] = await (0, pda_js_1.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 (0, index_js_5.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 (0, index_js_5.getAllowDelegateInstructionAsync)({
+            delegate: (0, kit_1.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 (0, index_js_5.getDisallowDelegateInstructionAsync)({
+            delegate: (0, kit_1.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 (0, index_js_5.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 (0, ata_js_1.getAssociatedTokenAddressKit)(arnsConfig.mint, this.signer.address);
+        const antPubkey = (0, kit_1.address)(params.processId);
+        // Read the ReturnedName to find the original initiator (gets the premium).
+        const [returnedNamePda] = await (0, pda_js_1.getReturnedNamePDA)(params.name, this.arnsProgram);
+        const returnedNameAccount = await (0, kit_1.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 (0, ata_js_1.getAssociatedTokenAddressKit)(arnsConfig.mint, initiator);
+        const [arnsRecord] = await (0, pda_js_1.getArnsRecordPDA)(params.name, this.arnsProgram);
+        const buyParams = {
+            name: params.name,
+            purchaseType: params.type === 'permabuy' ? index_js_2.PurchaseType.Permabuy : index_js_2.PurchaseType.Lease,
+            years: params.years ?? 1,
+            ant: antPubkey,
+        };
+        let ix;
+        if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            ix = await (0, index_js_1.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 (0, pda_js_1.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 = (0, kit_1.address)(params.gatewayAddress);
+                const [gatewayPda] = await (0, pda_js_1.getGatewayPDA)(gatewayAddr, this.garProgram);
+                if (params.fundAsOperator) {
+                    ix = await (0, index_js_1.getBuyReturnedNameFromOperatorStakeInstructionAsync)({ ...sharedReturnedBase, gateway: gatewayPda }, { programAddress: this.arnsProgram });
+                }
+                else {
+                    const [delegationPda] = await (0, pda_js_1.getDelegationPDA)(gatewayAddr, this.signer.address, this.garProgram);
+                    ix = await (0, index_js_1.getBuyReturnedNameFromDelegationInstructionAsync)({
+                        ...sharedReturnedBase,
+                        gateway: gatewayPda,
+                        delegation: delegationPda,
+                    }, { programAddress: this.arnsProgram });
+                }
+            }
+            else if (params.fundFrom === 'withdrawal' &&
+                params.withdrawalId !== undefined) {
+                const [withdrawalPda] = await (0, pda_js_1.getWithdrawalPDA)(this.signer.address, params.withdrawalId, this.garProgram);
+                ix = await (0, index_js_1.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 (0, index_js_1.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 = (0, kit_1.address)(params.processId);
+        const [arnsRecord] = await (0, pda_js_1.getArnsRecordPDA)(params.name, this.arnsProgram);
+        const ix = await (0, index_js_1.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: kit_1.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 (0, pda_js_1.getReturnedNamePDA)(params.name, this.arnsProgram);
+        const [arnsRecord] = await (0, pda_js_1.getArnsRecordPDA)(params.name, this.arnsProgram);
+        const ix = await (0, index_js_1.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 (0, pda_js_1.getEpochSettingsPDA)(this.garProgram);
+        const settingsAccount = await (0, kit_1.fetchEncodedAccount)(this.rpc, epochSettingsPda, { commitment: this.commitment });
+        if (!settingsAccount.exists)
+            throw new Error('EpochSettings not found');
+        const settings = (0, deserialize_js_1.deserializeEpochSettingsFull)(Buffer.from(settingsAccount.data));
+        const epochIndex = settings.currentEpochIndex;
+        const [epochPda] = await (0, pda_js_1.getEpochPDA)(epochIndex, this.garProgram);
+        const ix = await (0, index_js_5.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 (0, index_js_5.getTallyWeightsInstructionAsync)(await this.withGarDefaults({
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const remaining = params.gatewayAccounts.map((address) => ({
+            address,
+            role: kit_1.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 (0, index_js_5.getPrescribeEpochInstructionAsync)(await this.withGarDefaults({
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const remaining = params.gatewayAccounts.map((address) => ({
+            address,
+            role: kit_1.AccountRole.READONLY,
+        }));
+        if (params.nameRegistryAccount) {
+            remaining.push({
+                address: params.nameRegistryAccount,
+                role: kit_1.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();
+        const ix = await (0, index_js_5.getDistributeEpochInstructionAsync)(await this.withGarDefaults({
+            protocolTokenAccount: garConfig.protocolTokenAccount,
+            stakeTokenAccount: garConfig.stakeTokenAccount,
+            payer: this.signer,
+            epochIndex: BigInt(params.epochIndex),
+        }), { programAddress: this.garProgram });
+        const remaining = params.gatewayAccounts.map((address) => ({
+            address,
+            role: kit_1.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 (0, index_js_5.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 (0, pda_js_1.getGatewayRegistryPDA)(this.garProgram);
+        const registryAccount = await (0, kit_1.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 (0, pda_js_1.getGatewayPDA)(addr, this.garProgram);
+            pdas.push(gatewayPda);
+        }
+        return pdas;
+    }
+    /** Get ALL active gateway PDAs from the registry. */
+    async getAllRegistryGatewayPDAs() {
+        const [registryPda] = await (0, pda_js_1.getGatewayRegistryPDA)(this.garProgram);
+        const registryAccount = await (0, kit_1.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 (0, pda_js_1.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 (0, pda_js_1.getEpochPDA)(epochIndex, this.garProgram);
+        const account = await (0, kit_1.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,
+        };
+    }
+}
+exports.SolanaARIOWriteable = SolanaARIOWriteable;