@ar.io/sdk 4.0.0-solana.23 → 4.0.0-solana.25

package/lib/esm/solana/deserialize.js

@@ -108,6 +108,12 @@ class BorshReader {
             return undefined;
         return this.readU32();
     }
+    readOptionU16() {
+        const tag = this.readU8();
+        if (tag === 0)
+            return undefined;
+        return this.readU16();
+    }
     skip(bytes) {
         this.offset += bytes;
     }
@@ -332,6 +338,15 @@ export function deserializeGatewayWithAccumulator(data) {
     const delegateRewardShareRatio = r.readU16() / 100;
     const minDelegatedStake = r.readU64AsNumber();
     const allowlistEnabled = r.readBool();
+    // GATEWAY_VERSION 1.1.0 added two fields to GatewaySettings2 — MUST read them
+    // here to keep the byte stream aligned for every field after `settings`.
+    //   - pending_delegate_reward_share_ratio: Option<u16> (Fix #7) — basis points
+    //     of a deferred reward-share change applied at the next epoch's tally.
+    //   - delegation_disabled_at: Option<i64> (Fix #6) — unix seconds the operator
+    //     disabled delegation; starts the re-enable cooldown.
+    const pendingRatioRaw = r.readOptionU16();
+    const pendingDelegateRewardShareRatio = pendingRatioRaw === undefined ? undefined : pendingRatioRaw / 100;
+    const delegationDisabledAt = r.readOptionI64();
     // RegistryIndex (index: u32, _reserved: u8 — was is_registered:bool)
     r.readU32(); // registryIndex
     r.readU8(); // _reserved (layout-preserving placeholder for the legacy is_registered byte)
@@ -378,6 +393,8 @@ export function deserializeGatewayWithAccumulator(data) {
         fqdn,
         port,
         protocol: 'https', // protocolIdx: 0=Http, 1=Https — only HTTPS in practice
+        pendingDelegateRewardShareRatio, // Fix #7: undefined when no change is queued
+        delegationDisabledAt, // Fix #6: undefined when delegation is enabled
     };
     return {
         operator: operator,

package/lib/esm/solana/index.js

@@ -54,7 +54,7 @@ export { ARWEAVE_TX_REGEX, AR_IO_PROTOCOL, arweaveUri, FQDN_REGEX, MARIO_PER_ARI
 // Solana implementation classes (still exported for advanced/direct usage —
 // the `ARIO` / `ANT` factories above wrap these).
 export { SolanaARIOReadable } from './io-readable.js';
-export { SolanaARIOWriteable } from './io-writeable.js';
+export { isInvalidGatewayAccountError, SolanaARIOWriteable, } from './io-writeable.js';
 // ANT classes
 export { SolanaANTReadable } from './ant-readable.js';
 export { SolanaANTWriteable } from './ant-writeable.js';
@@ -88,6 +88,8 @@ export { hashName, getArioConfigPDA, getBalancePDA, getVaultPDA, getVaultCounter
 // `ANT_RECORD_DISCRIMINATOR`). Pull them from there instead of asking
 // this module — single source of truth, derived from the IDL.
 export { BorshReader, BorshWriter, deserializeGateway, deserializeArnsRecord, deserializeVault, deserializeDelegation, deserializeBalance, deserializeEpochSettings, deserializeArioConfig, deserializeDemandFactor, deserializeReservedName, deserializeReturnedName, deserializeWithdrawal, deserializeRedelegationRecord, deserializePrimaryNameRequest, deserializePrimaryName, deserializeAllowlist, deserializeGarSettings, deserializeEpochSettingsFull, deserializeEpoch, deserializeObservation, deserializeAntConfig, deserializeAntControllers, deserializeAntRecord, deserializeAclConfig, deserializeAclPage, } from './deserialize.js';
+// Off-chain prediction of prescribe_epoch's observer selection (cranker helper)
+export { predictPrescribedObservers, } from './predict-prescribed-observers.js';
 // Constants
 export * from './constants.js';
 // Cluster-specific deployment constants (devnet program IDs, RPC URL,

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

@@ -1743,6 +1743,39 @@ export class SolanaARIOReadable {
         }
         return out;
     }
+    /**
+     * Enumerate Joined Gateway PDAs whose delegation has been DISABLED
+     * (`allow_delegated_staking == false`) yet still hold delegated stake
+     * (`total_delegated_stake > 0`) — i.e. delegates that an operator's disable
+     * left stranded (WP §6.3 / Fix #6). Each such gateway's delegates must be
+     * cranked out via
+     * {@link SolanaARIOWriteable.claimDelegateFromDisabledGateway} (enumerate
+     * them with {@link getGatewayDelegates}) before the operator can re-enable
+     * delegation. This is the discovery primitive a cranker uses to sweep them.
+     */
+    async getDisabledGatewaysWithDelegatedStake() {
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, GATEWAY_DISCRIMINATOR);
+        const decoder = getGatewayDecoder();
+        const out = [];
+        for (const { pubkey, data } of accounts) {
+            try {
+                const g = decoder.decode(data);
+                if (g.status !== GatewayStatus.Joined)
+                    continue;
+                if (!g.settings.allowDelegatedStaking && g.totalDelegatedStake > 0n) {
+                    out.push({
+                        pubkey,
+                        operator: g.operator,
+                        totalDelegatedStake: g.totalDelegatedStake,
+                    });
+                }
+            }
+            catch {
+                // skip malformed
+            }
+        }
+        return out;
+    }
     /**
      * Enumerate Delegation PDAs with `amount == 0`. Eligible for
      * `closeEmptyDelegation` (rent refund to the original delegator).

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

@@ -38,12 +38,13 @@ function toGeneratedFundingSourceSpec(s) {
 import { getSyncAttributesInstruction } from '@ar.io/solana-contracts/ant';
 import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRemovePrimaryNameInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestAndSetPrimaryNameInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
 import { getDelegationDecoder, getGatewayDecoder, } from '@ar.io/solana-contracts/gar';
-import { Protocol, getAllowDelegateInstructionAsync, getCancelWithdrawalInstruction, getClaimDelegateFromLeavingGatewayInstructionAsync, getClaimWithdrawalInstructionAsync, getCloseDrainedWithdrawalInstruction, getCloseEmptyDelegationInstruction, getCloseEpochInstructionAsync, getCloseObservationInstructionAsync, getCreateEpochInstructionAsync, getDecreaseDelegateStakeInstructionAsync, getDecreaseOperatorStakeInstructionAsync, getDelegateStakeInstructionAsync, getDisallowDelegateInstructionAsync, getDistributeEpochInstructionAsync, getFinalizeGoneInstructionAsync, getIncreaseOperatorStakeInstructionAsync, getInstantWithdrawalInstructionAsync, getJoinNetworkInstructionAsync, getLeaveNetworkInstructionAsync, getPrescribeEpochInstructionAsync, getPruneGatewayInstructionAsync, getRedelegateStakeInstructionAsync, getSaveObservationsInstructionAsync, getSetAllowlistEnabledInstructionAsync, getTallyWeightsInstructionAsync, getUpdateGatewaySettingsInstructionAsync, } from '@ar.io/solana-contracts/gar';
+import { Protocol, getAllowDelegateInstructionAsync, getCancelWithdrawalInstruction, getClaimDelegateFromDisabledGatewayInstructionAsync, getClaimDelegateFromLeavingGatewayInstructionAsync, getClaimWithdrawalInstructionAsync, getCloseDrainedWithdrawalInstruction, getCloseEmptyDelegationInstruction, getCloseEpochInstructionAsync, getCloseObservationInstructionAsync, getCreateEpochInstructionAsync, getDecreaseDelegateStakeInstructionAsync, getDecreaseOperatorStakeInstructionAsync, getDelegateStakeInstructionAsync, getDisallowDelegateInstructionAsync, getDistributeEpochInstructionAsync, getFinalizeGoneInstructionAsync, getIncreaseOperatorStakeInstructionAsync, getInstantWithdrawalInstructionAsync, getJoinNetworkInstructionAsync, getLeaveNetworkInstructionAsync, getPrescribeEpochInstructionAsync, getPruneGatewayInstructionAsync, getRedelegateStakeInstructionAsync, getSaveObservationsInstructionAsync, getSetAllowlistEnabledInstructionAsync, getTallyWeightsInstructionAsync, getUpdateGatewaySettingsInstructionAsync, } from '@ar.io/solana-contracts/gar';
 import { getTransferCheckedInstruction } from '@solana-program/token';
 import { ARIO_ANT_PROGRAM_ID, TOKEN_DECIMALS } from './constants.js';
 import { SolanaARIOReadable } from './io-readable.js';
 import { getAntRecordPDA, getArioConfigPDA, getArnsRecordPDA, getArnsRegistryPDA, getArnsSettingsPDA, getDelegationPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getObservationPDA, getObserverLookupPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getPrimaryNameReversePDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, getWithdrawalCounterPDA, getWithdrawalPDA, hashName, } from './pda.js';
-import { sendAndConfirm } from './send.js';
+import { predictPrescribedObservers, } from './predict-prescribed-observers.js';
+import { reclaimLookupTablesForSigner, sendAndConfirm, sendWithEphemeralLookupTable, } from './send.js';
 const addressDecoder = getAddressDecoder();
 /** Resolve mARIOToken | number to a plain number */
 function toAmount(qty) {
@@ -181,6 +182,29 @@ export function encodeReportTxId(reportTxId) {
     decoded.copy(out);
     return out;
 }
+/**
+ * Detect the GAR `InvalidGatewayAccount` error by Anchor error name/message
+ * (walking the cause chain + `context.logs`), NOT by numeric code — codes are
+ * `6000 + enum-index` and shift across program versions, but the name and
+ * message are stable. `prescribe_epoch` raises this when a supplied observer
+ * Gateway PDA is missing/spoofed (e.g. a predicted observer left the registry
+ * between prediction and tx landing).
+ */
+export function isInvalidGatewayAccountError(error) {
+    const parts = [];
+    let cur = error;
+    for (let i = 0; cur != null && i < 8; i++) {
+        const e = cur;
+        if (e.message)
+            parts.push(e.message);
+        if (Array.isArray(e.context?.logs))
+            parts.push(e.context.logs.join('\n'));
+        cur = e.cause;
+    }
+    const text = parts.join('\n');
+    return (text.includes('InvalidGatewayAccount') ||
+        text.includes('Invalid gateway account'));
+}
 export class SolanaARIOWriteable extends SolanaARIOReadable {
     signer;
     rpcSubscriptions;
@@ -1747,6 +1771,47 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         return { id: sig };
     }
     // =========================================
+    // Claim delegation from gateway with delegation DISABLED (ario-gar, Fix #6)
+    // =========================================
+    /**
+     * Claim a delegate's stake out of a gateway that has DISABLED delegation
+     * (`allow_delegated_staking == false`), moving it into the delegate's own
+     * withdrawal vault (WP §6.3 / Fix #6). This is the disabled-gateway analog of
+     * {@link claimDelegateFromLeavingGateway}: the on-chain instruction is
+     * permissionless, so a cranker can sweep delegates out (the operator cannot
+     * re-enable delegation until `total_delegated_stake == 0` and the cooldown
+     * elapses). The withdrawal-counter and withdrawal PDAs are seeded by the
+     * DELEGATOR, so a cranker must pass that delegate's `delegatorAddress`.
+     *
+     * @param params.gatewayAddress  The gateway whose delegation was disabled.
+     * @param params.delegatorAddress  The delegate to claim for. Defaults to the
+     *   signer (self-claim). Pass another address to crank on a delegate's behalf;
+     *   the signer covers rent (`payer`) but stake still routes to the delegate's
+     *   own vault (the delegator key is bound by the delegation PDA seeds).
+     */
+    async claimDelegateFromDisabledGateway(params, _options) {
+        const gateway = address(params.gatewayAddress);
+        const delegator = params.delegatorAddress
+            ? address(params.delegatorAddress)
+            : this.signer.address;
+        const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(gateway, delegator, this.garProgram);
+        // Withdrawal counter + vault are PDA-seeded by the delegator, not the payer.
+        const nextId = await this.getNextWithdrawalId(delegator);
+        const [withdrawalPda] = await getWithdrawalPDA(delegator, nextId, this.garProgram);
+        const ix = await getClaimDelegateFromDisabledGatewayInstructionAsync({
+            gateway: gatewayPda,
+            delegation: delegationPda,
+            withdrawal: withdrawalPda,
+            // `delegator` is an unsigned seeds-derivation key; `payer` (the signer)
+            // covers rent on the init_if_needed counter + the new withdrawal.
+            delegator,
+            payer: this.signer,
+        }, { programAddress: this.garProgram });
+        const sig = await this.sendTransaction([ix], 1_000_000);
+        return { id: sig };
+    }
+    // =========================================
     // Delegation allowlist (ario-gar)
     // =========================================
     /** Add an address to the gateway's delegation allowlist. */
@@ -1995,9 +2060,22 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     }
     /**
      * Prescribe observers and names for an epoch. Permissionless — call after
-     * weights are tallied. Gateway PDAs are appended as `remaining_accounts`,
-     * and the optional `nameRegistryAccount` (must be last) enables the name
+     * weights are tallied.
+     *
+     * `gatewayAccounts` MUST be the Gateway PDAs of the SELECTED observers only
+     * — at most `epoch_settings.prescribed_observer_count` (≤50), NOT the whole
+     * registry. The selection is computed on-chain; mirror it off-chain with
+     * {@link predictPrescribedObservers} / {@link getPredictedObserverPDAs} to
+     * learn the set. Passing every registry gateway (e.g. via
+     * {@link getAllRegistryGatewayPDAs}) hits Solana's `MAX_TX_ACCOUNT_LOCKS = 64`
+     * on large registries and the tx fails at pre-flight.
+     *
+     * The selected PDAs are appended as `remaining_accounts`, followed by the
+     * optional `nameRegistryAccount` (must be LAST) which enables the name
      * prescription leg.
+     *
+     * If a selected gateway leaves between prediction and tx landing, the tx
+     * fails with `InvalidGatewayAccount` — retry once with a fresh prediction.
      */
     async prescribeEpoch(params, _options) {
         const ix = await getPrescribeEpochInstructionAsync(await this.withGarDefaults({
@@ -2014,7 +2092,28 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 role: AccountRole.READONLY,
             });
         }
-        const sig = await this.sendTransaction([withRemainingAccounts(ix, remaining)], 1_000_000);
+        const fullIx = withRemainingAccounts(ix, remaining);
+        // A prescribe tx with the selected observer set (~50 PDAs) exceeds Solana's
+        // 1232-byte limit once there are more than ~24 remaining accounts, so route
+        // those through an ephemeral Address Lookup Table (create → extend →
+        // compressed v0 tx). Small sets (sparse testnets) take the cheaper inline
+        // path. `prescribe_epoch` searches `remaining_accounts` by PDA, so serving
+        // them via the ALT (which preserves instruction account order) is
+        // transparent — incl. NameRegistry staying last. Validated on staging
+        // (667 gateways, 50 observers): 428k CU, name prescription intact.
+        if (remaining.length > 24) {
+            const id = await sendWithEphemeralLookupTable({
+                rpc: this.rpc,
+                rpcSubscriptions: this.rpcSubscriptions,
+                signer: this.signer,
+                instruction: fullIx,
+                lookupAddresses: remaining.map((a) => a.address),
+                commitment: this.commitment,
+                computeUnitLimit: 1_000_000,
+            });
+            return { id };
+        }
+        const sig = await this.sendTransaction([fullIx], 1_000_000);
         return { id: sig };
     }
     /**
@@ -2115,6 +2214,244 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         }
         return pdas;
     }
+    /**
+     * Predict the Gateway PDAs that `prescribe_epoch` will select as observers
+     * for `epochIndex`, mirroring the on-chain weighted-roulette selection.
+     *
+     * Returns at most `epoch_settings.prescribed_observer_count` (≤50) PDAs
+     * regardless of registry size — the set to pass as `gatewayAccounts` to
+     * {@link prescribeEpoch}. This is the size-safe replacement for
+     * {@link getAllRegistryGatewayPDAs} on the prescribe path (which oversupplies
+     * and trips `MAX_TX_ACCOUNT_LOCKS = 64` on large registries).
+     *
+     * Reads three accounts (epoch, registry, epoch settings) at the configured
+     * commitment so the prediction reflects live registry weights. If a selected
+     * gateway races out before the tx lands, `prescribeEpoch` throws
+     * `InvalidGatewayAccount` — re-call this and retry once.
+     */
+    async getPredictedObserverPDAs(epochIndex) {
+        // --- Epoch: hashchain (frozen entropy) + active_gateway_count (walk bound) ---
+        const [epochPda] = await getEpochPDA(epochIndex, this.garProgram);
+        const epochAccount = await fetchEncodedAccount(this.rpc, epochPda, {
+            commitment: this.commitment,
+        });
+        if (!epochAccount.exists)
+            throw new Error(`Epoch ${epochIndex} not found`);
+        const epochData = Buffer.from(epochAccount.data);
+        // After the 8-byte discriminator (see fetchEpochRawFields): 9×u64 = 72
+        // bytes, then hashchain[32], then active_gateway_count(u32).
+        const EPOCH_BASE = 8;
+        const hashchain = epochData.subarray(EPOCH_BASE + 72, EPOCH_BASE + 72 + 32);
+        const activeGatewayCount = epochData.readUInt32LE(EPOCH_BASE + 104);
+        // --- Registry: slots[0..activeGatewayCount] (address + composite_weight) ---
+        const [registryPda] = await getGatewayRegistryPDA(this.garProgram);
+        const registryAccount = await fetchEncodedAccount(this.rpc, registryPda, {
+            commitment: this.commitment,
+        });
+        if (!registryAccount.exists)
+            throw new Error('GatewayRegistry not found');
+        const registryData = Buffer.from(registryAccount.data);
+        const registryCount = registryData.readUInt32LE(40); // 8 disc + 32 authority
+        const SLOTS_OFFSET = 48; // 8 + 32 + 4 count + 4 pad
+        const SLOT_STRIDE = 56; // address(32)+weight(8)+start_ts(8)+status(1)+pad(7)
+        // Walk exactly the on-chain prefix. The roulette uses
+        // registry.gateways[0..epoch.active_gateway_count]; include zero-weight
+        // slots so the cumulative walk and weight sum match byte-for-byte.
+        const walkCount = Math.min(activeGatewayCount, registryCount, 3000);
+        const slots = [];
+        for (let i = 0; i < walkCount; i++) {
+            const slotOffset = SLOTS_OFFSET + i * SLOT_STRIDE;
+            slots.push({
+                address: addressDecoder.decode(registryData.subarray(slotOffset, slotOffset + 32)),
+                compositeWeight: registryData.readBigUInt64LE(slotOffset + 32),
+            });
+        }
+        // --- Epoch settings: prescribed_observer_count ---
+        const [epochSettingsPda] = await getEpochSettingsPDA(this.garProgram);
+        const settingsAccount = await fetchEncodedAccount(this.rpc, epochSettingsPda, {
+            commitment: this.commitment,
+        });
+        if (!settingsAccount.exists)
+            throw new Error('EpochSettings not found');
+        const settings = deserializeEpochSettingsFull(Buffer.from(settingsAccount.data));
+        // --- Predict selected operators, then derive their Gateway PDAs ---
+        const operators = predictPrescribedObservers(hashchain, slots, settings.prescribedObserverCount);
+        const pdas = [];
+        for (const operator of operators) {
+            const [gatewayPda] = await getGatewayPDA(operator, this.garProgram);
+            pdas.push(gatewayPda);
+        }
+        return pdas;
+    }
+    /**
+     * Reclaim rent from the ephemeral Address Lookup Tables this signer created
+     * for `prescribe_epoch` (see {@link sendWithEphemeralLookupTable}). Each
+     * prescribe leaves a single-use table allocated (~0.0126 SOL); reclaiming
+     * needs a deactivate → ~513-slot cooldown → close sequence, so it can't run
+     * inline. Call this from a throttled/permissionless cleanup pass (cranker /
+     * observer) to deactivate active tables and close cooled-down ones, refunding
+     * the rent to the signer.
+     *
+     * Discovery reads the signer's transaction history (RPC-portable; the ALT
+     * program can't be enumerated via `getProgramAccounts`). The GAR + ArNS
+     * program IDs are passed as the entry-ownership fingerprint so only genuine
+     * prescribe tables are touched. Best-effort: at most `maxTables` submissions
+     * per call, scanning at most `scanLimit` recent signatures.
+     */
+    async reclaimLookupTableRent(opts) {
+        return reclaimLookupTablesForSigner({
+            rpc: this.rpc,
+            rpcSubscriptions: this.rpcSubscriptions,
+            signer: this.signer,
+            allowedEntryOwners: [this.garProgram, this.arnsProgram],
+            commitment: this.commitment,
+            maxTables: opts?.maxTables,
+            scanLimit: opts?.scanLimit,
+        });
+    }
+    /** Read and deserialize the full EpochSettings account. */
+    async getEpochSettingsFull() {
+        const [esPda] = await getEpochSettingsPDA(this.garProgram);
+        const account = await fetchEncodedAccount(this.rpc, esPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            throw new Error('EpochSettings not found');
+        return deserializeEpochSettingsFull(Buffer.from(account.data));
+    }
+    /**
+     * Submit `prescribe_epoch` using the off-chain-predicted observer set, with a
+     * single re-predict-and-retry on `InvalidGatewayAccount` (covers a gateway
+     * leaving the registry between the prediction read and the tx landing).
+     */
+    async prescribeWithPrediction(epochIndex, nameRegistryAccount) {
+        const submit = async () => this.prescribeEpoch({
+            epochIndex,
+            gatewayAccounts: await this.getPredictedObserverPDAs(epochIndex),
+            nameRegistryAccount,
+        });
+        try {
+            return await submit();
+        }
+        catch (err) {
+            if (!isInvalidGatewayAccountError(err))
+                throw err;
+            return submit();
+        }
+    }
+    /**
+     * Advance the epoch lifecycle by ONE on-chain action and return what it did.
+     *
+     * Stateless and idempotent: it reads `EpochSettings` + the current `Epoch`,
+     * determines the single next required step
+     * (`create` → `tally` → `prescribe` → `distribute` → `close`), submits it,
+     * and returns a {@link CrankEpochStepResult}. Call it repeatedly on your own
+     * schedule — it owns *which* on-chain action is correct and *which accounts*
+     * it needs; you own scheduling, logging, error classification, and any
+     * permissionless cleanup.
+     *
+     * Crucially, the `prescribe` leg uses {@link getPredictedObserverPDAs} (only
+     * the ~`prescribed_observer_count` selected Gateway PDAs), so it never trips
+     * `MAX_TX_ACCOUNT_LOCKS = 64` on large registries — and it re-predicts and
+     * retries once on `InvalidGatewayAccount`.
+     *
+     * Errors propagate to the caller (classify/retry as you see fit); the only
+     * internally-handled error is the prescribe `InvalidGatewayAccount` retry.
+     */
+    async crankEpochStep(opts = {}) {
+        // tally_weights / distribute_epoch append the batch's Gateway PDAs as
+        // remaining_accounts. distribute also CPIs into ario-core (treasury
+        // release) so it carries 10 named accounts; with ~18+ gateway PDAs on top
+        // the tx exceeds Solana's 1232-byte limit. Cap the lifecycle batch at 18 so
+        // an oversized caller `batchSize` can't produce an unsendable tx (verified:
+        // 30 gateways → 1527B; 18 → ~1050B). prescribe is the exception — it needs
+        // ALL selected observers in one tx, so it uses an ALT instead (see
+        // prescribeEpoch).
+        const MAX_LIFECYCLE_BATCH = 18;
+        const batchSize = Math.min(opts.batchSize ?? MAX_LIFECYCLE_BATCH, MAX_LIFECYCLE_BATCH);
+        const enableClose = opts.enableClose ?? true;
+        const retention = opts.epochRetention ?? 7;
+        const now = opts.now ?? Math.floor(Date.now() / 1000);
+        const settings = await this.getEpochSettingsFull();
+        if (!settings.enabled)
+            return { action: 'idle', reason: 'epochs_disabled' };
+        const currentIndex = settings.currentEpochIndex;
+        // currentIndex is the NEXT epoch to create; the live one is currentIndex-1.
+        const targetEpochIndex = currentIndex > 0 ? currentIndex - 1 : 0;
+        const nextEpochStart = settings.genesisTimestamp + currentIndex * settings.epochDuration;
+        // Bootstrap: no epochs yet.
+        if (currentIndex === 0) {
+            if (now < nextEpochStart)
+                return { action: 'idle', reason: 'waiting_for_genesis' };
+            const { id } = await this.createEpoch();
+            return { action: 'create', epochIndex: 0, txId: id };
+        }
+        const epoch = await this.getEpochRaw(targetEpochIndex);
+        if (!epoch)
+            return { action: 'idle', reason: 'waiting_for_epoch' };
+        // Tally (batched). activeGatewayCount===0 still needs one tx to flip the flag.
+        if (epoch.weightsTallied === 0) {
+            const gatewayAccounts = epoch.activeGatewayCount > 0
+                ? await this.getRegistryGatewayPDAs(epoch.tallyIndex, batchSize)
+                : [];
+            const { id } = await this.tallyWeights({
+                epochIndex: targetEpochIndex,
+                gatewayAccounts,
+            });
+            return {
+                action: 'tally',
+                epochIndex: targetEpochIndex,
+                txId: id,
+                progress: { index: epoch.tallyIndex, total: epoch.activeGatewayCount },
+            };
+        }
+        // Prescribe (predicted observers only — the size-safe path).
+        if (epoch.prescriptionsDone === 0) {
+            const nameRegistryAccount = opts.nameRegistryAccount === null
+                ? undefined
+                : (opts.nameRegistryAccount ??
+                    (await getArnsRegistryPDA(this.arnsProgram))[0]);
+            const { id } = await this.prescribeWithPrediction(targetEpochIndex, nameRegistryAccount);
+            return { action: 'prescribe', epochIndex: targetEpochIndex, txId: id };
+        }
+        // Observations happen while the epoch is live.
+        if (now < epoch.endTimestamp)
+            return { action: 'idle', reason: 'waiting_for_observations' };
+        // Distribute (batched).
+        if (epoch.rewardsDistributed === 0) {
+            const gatewayAccounts = epoch.activeGatewayCount > 0
+                ? await this.getRegistryGatewayPDAs(epoch.distributionIndex, batchSize)
+                : [];
+            const { id } = await this.distributeEpoch({
+                epochIndex: targetEpochIndex,
+                gatewayAccounts,
+            });
+            return {
+                action: 'distribute',
+                epochIndex: targetEpochIndex,
+                txId: id,
+                progress: {
+                    index: epoch.distributionIndex,
+                    total: epoch.activeGatewayCount,
+                },
+            };
+        }
+        // Close a fully-distributed epoch past retention (GAR-006).
+        if (enableClose && targetEpochIndex >= retention) {
+            const closeTarget = targetEpochIndex - retention;
+            const old = await this.getEpochRaw(closeTarget);
+            if (old && old.rewardsDistributed === 1) {
+                const { id } = await this.closeEpoch({ epochIndex: closeTarget });
+                return { action: 'close', epochIndex: closeTarget, txId: id };
+            }
+        }
+        // Current epoch fully processed — create the next once its start arrives.
+        if (now >= nextEpochStart) {
+            const { id } = await this.createEpoch();
+            return { action: 'create', epochIndex: currentIndex, txId: id };
+        }
+        return { action: 'idle', reason: 'epoch_complete' };
+    }
     /**
      * Read the raw epoch account data for cranker state inspection.
      * Returns null if the epoch account doesn't exist yet.

package/lib/esm/solana/predict-prescribed-observers.js

@@ -0,0 +1,95 @@
+/**
+ * Off-chain prediction of `prescribe_epoch`'s observer selection.
+ *
+ * `ario_gar::prescribe_epoch` selects observers INTERNALLY via a weighted
+ * roulette over the `GatewayRegistry`, then uses `remaining_accounts` only as a
+ * lookup table for the ~50 selected Gateway PDAs (+ NameRegistry). A cranker
+ * that instead supplies every registry gateway hits Solana's
+ * `MAX_TX_ACCOUNT_LOCKS = 64` on large registries and the tx is rejected at
+ * pre-flight. This helper mirrors the on-chain selection so the caller can
+ * supply exactly the selected set.
+ *
+ * The selection is deterministic from on-chain state that is stable once
+ * `epoch.weights_tallied == 1`: the frozen `epoch.hashchain` entropy beacon and
+ * the live `registry.gateways[*].composite_weight`.
+ *
+ * Cross-language parity with the Rust handler
+ * (`ar-io-solana-contracts/programs/ario-gar/src/instructions/epoch.rs`, the
+ * `prescribe_epoch` observer-selection block) is asserted in
+ * `predict-prescribed-observers.test.ts` against vectors generated by the Rust
+ * reference example `programs/ario-gar/examples/predict_prescribed_observers.rs`.
+ * If you change this algorithm, update that example and the test together.
+ */
+import { createHash } from 'crypto';
+function sha256(data) {
+    return createHash('sha256').update(data).digest();
+}
+/** `u128::from_le_bytes(bytes[0..16])` — little-endian, first 16 bytes only. */
+function leU128(bytes) {
+    let v = 0n;
+    for (let i = 15; i >= 0; i--) {
+        v = (v << 8n) | BigInt(bytes[i]);
+    }
+    return v;
+}
+/**
+ * Predict the operator pubkeys `prescribe_epoch` will select as observers.
+ *
+ * Returns the selected `GatewaySlot.address` values (operator pubkeys) in
+ * selection order, at most `maxObservers`. These correspond 1:1 to the on-chain
+ * `epoch.prescribed_observer_gateways` array, and are what Gateway PDAs are
+ * derived from (`[GATEWAY_SEED, operator]`). NOTE this is NOT
+ * `epoch.prescribed_observers`, which `prescribe_epoch` later overwrites with
+ * each gateway's resolved `observer_address`.
+ *
+ * @param epochHashchain `epoch.hashchain` — exactly 32 bytes, frozen at
+ *   `create_epoch`.
+ * @param slots `registry.gateways[0 .. epoch.active_gateway_count]` in registry
+ *   (slot-index) order. Pass the whole prefix including any zero-weight slots —
+ *   order and the live weight sum must match the on-chain walk exactly. Empty /
+ *   zero-weight slots contribute nothing and can never be selected.
+ * @param maxObservers `epoch_settings.prescribed_observer_count`. Clamped to
+ *   `slots.length` (the on-chain `min(prescribed_observer_count, active_count)`).
+ */
+export function predictPrescribedObservers(epochHashchain, slots, maxObservers) {
+    if (epochHashchain.length !== 32) {
+        throw new Error(`epochHashchain must be 32 bytes, got ${epochHashchain.length}`);
+    }
+    const activeCount = slots.length;
+    const cap = Math.min(maxObservers, activeCount);
+    // Live total weight (epoch.rs: `for i in 0..active_count { total += w }`).
+    // u128 sum of u64 weights over <=3000 slots cannot overflow, so the Rust
+    // `saturating_add` never actually saturates; plain BigInt addition matches.
+    let totalWeight = 0n;
+    for (const slot of slots) {
+        totalWeight += slot.compositeWeight;
+    }
+    const selected = [];
+    if (totalWeight === 0n || activeCount === 0 || cap === 0) {
+        return selected;
+    }
+    // Initial entropy: sha256(hashchain).
+    let hashBytes = sha256(epochHashchain);
+    // GAR-019: bounded retries, up to cap * 10 rounds.
+    const maxRounds = cap * 10;
+    for (let round = 0; round < maxRounds; round++) {
+        if (selected.length >= cap)
+            break;
+        const randomValue = leU128(hashBytes.subarray(0, 16)) % totalWeight;
+        let cumulative = 0n;
+        for (const slot of slots) {
+            cumulative += slot.compositeWeight;
+            if (cumulative > randomValue && slot.compositeWeight > 0n) {
+                // Anti-duplicate: skip if already chosen, but the round still consumes
+                // the roulette hit — break the walk either way (epoch.rs).
+                if (!selected.includes(slot.address)) {
+                    selected.push(slot.address);
+                }
+                break;
+            }
+        }
+        // Re-hash for the next round: sha256(hash_bytes).
+        hashBytes = sha256(hashBytes);
+    }
+    return selected;
+}

package/lib/esm/solana/send.js

@@ -8,17 +8,18 @@
  * favor of the official package. See `sendAndConfirm` below for why we always
  * pin BOTH instructions (even with a 0 priority fee).
  */
+import { ADDRESS_LOOKUP_TABLE_PROGRAM_ADDRESS, getCloseLookupTableInstruction, getCreateLookupTableInstructionAsync, getDeactivateLookupTableInstruction, getExtendLookupTableInstruction, } from '@solana-program/address-lookup-table';
 import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from '@solana-program/compute-budget';
-import { appendTransactionMessageInstructions, compileTransaction, createTransactionMessage, getBase64EncodedWireTransaction, getSignatureFromTransaction, pipe, sendAndConfirmTransactionFactory, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, } from '@solana/kit';
+import { appendTransactionMessageInstructions, compileTransaction, compressTransactionMessageUsingAddressLookupTables, createTransactionMessage, getAddressDecoder, getBase64EncodedWireTransaction, getSignatureFromTransaction, pipe, sendAndConfirmTransactionFactory, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, } from '@solana/kit';
 /**
  * Build, sign, send, and confirm a transaction in one call.
  *
  * The caller supplies the core instructions; a compute-unit-limit instruction
  * is prepended automatically.
  */
-export async function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment = 'confirmed', computeUnitLimit = 400_000, }) {
+export async function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment = 'confirmed', computeUnitLimit = 400_000, addressLookupTables, }) {
     const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
-    const message = pipe(createTransactionMessage({ version: 0 }), (tx) => setTransactionMessageFeePayerSigner(signer, tx), (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx), (tx) => appendTransactionMessageInstructions([
+    const baseMessage = pipe(createTransactionMessage({ version: 0 }), (tx) => setTransactionMessageFeePayerSigner(signer, tx), (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx), (tx) => appendTransactionMessageInstructions([
         getSetComputeUnitLimitInstruction({ units: computeUnitLimit }),
         // Always pin the priority fee (even at 0) so wallets like Phantom
         // don't silently *append* their own compute-budget instructions
@@ -32,6 +33,10 @@ export async function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructio
         getSetComputeUnitPriceInstruction({ microLamports: 0n }),
         ...instructions,
     ], tx));
+    // Compress against any supplied lookup tables (v0). No-op when none given.
+    const message = addressLookupTables
+        ? compressTransactionMessageUsingAddressLookupTables(baseMessage, addressLookupTables)
+        : baseMessage;
     const signedTx = await signTransactionMessageWithSigners(message);
     const sendAndConfirmFactory = sendAndConfirmTransactionFactory({
         rpc,
@@ -115,3 +120,238 @@ async function logSimulationDiagnostics(rpc, message, originalError) {
         console.warn('[solana-send] failed to collect diagnostics', diagErr);
     }
 }
+/**
+ * Submit `instruction` in a v0 transaction whose `lookupAddresses` (read-only
+ * accounts) are served from a freshly-created, ephemeral Address Lookup Table,
+ * so an instruction touching far more accounts than fit inline (e.g.
+ * `prescribe_epoch` with ≤50 observer PDAs + NameRegistry, ~2 KB of keys) still
+ * fits Solana's 1232-byte transaction-size limit.
+ *
+ * Three confirmed steps: create the table, extend it with the addresses (in
+ * ≤20-address batches to stay within the extend tx size), then send
+ * `instruction` compressed against the table. The sequential confirmations
+ * satisfy the rule that appended addresses are only usable the slot AFTER they
+ * are added. `signer` is the table's authority + payer; the table's (tiny) rent
+ * is left allocated — a future cleanup pass can deactivate + close it.
+ */
+export async function sendWithEphemeralLookupTable({ rpc, rpcSubscriptions, signer, instruction, lookupAddresses, commitment = 'confirmed', computeUnitLimit = 1_000_000, }) {
+    const recentSlot = await rpc.getSlot({ commitment: 'finalized' }).send();
+    const createIx = await getCreateLookupTableInstructionAsync({
+        authority: signer.address,
+        payer: signer,
+        recentSlot,
+    });
+    const tableAddress = createIx.accounts[0].address;
+    // Create the (empty) table.
+    await sendAndConfirm({
+        rpc,
+        rpcSubscriptions,
+        signer,
+        instructions: [createIx],
+        commitment,
+        computeUnitLimit: 60_000,
+    });
+    // Fill it, ≤20 addresses per extend tx.
+    const BATCH = 20;
+    for (let i = 0; i < lookupAddresses.length; i += BATCH) {
+        const extendIx = getExtendLookupTableInstruction({
+            address: tableAddress,
+            authority: signer,
+            payer: signer,
+            addresses: lookupAddresses.slice(i, i + BATCH),
+        });
+        await sendAndConfirm({
+            rpc,
+            rpcSubscriptions,
+            signer,
+            instructions: [extendIx],
+            commitment,
+            computeUnitLimit: 60_000,
+        });
+    }
+    // Wait until the table holds every address AND one slot has elapsed since —
+    // addresses appended to a lookup table are only usable the slot AFTER they're
+    // added, and the validator that processes the prescribe must already see
+    // them. Skipping this yields "address table lookup uses an invalid index".
+    await waitForLookupTableActive(rpc, tableAddress, lookupAddresses.length);
+    // Send the real instruction, compressed against the now-active table.
+    return sendAndConfirm({
+        rpc,
+        rpcSubscriptions,
+        signer,
+        instructions: [instruction],
+        commitment,
+        computeUnitLimit,
+        addressLookupTables: { [tableAddress]: lookupAddresses },
+    });
+}
+/**
+ * Poll until an Address Lookup Table holds at least `expectedCount` addresses
+ * AND at least one slot has elapsed since they all landed. Lookup-table entries
+ * are only usable the slot AFTER they are appended, and the leader processing
+ * the consuming tx must already see them — otherwise the runtime rejects the tx
+ * with "address table lookup uses an invalid index". ALT account layout is a
+ * 56-byte metadata header followed by 32-byte addresses.
+ */
+async function waitForLookupTableActive(rpc, table, expectedCount, maxWaitMs = 30_000) {
+    const META = 56;
+    const start = Date.now();
+    let slotAllPresent = null;
+    while (Date.now() - start < maxWaitMs) {
+        const acc = await rpc.getAccountInfo(table, { encoding: 'base64' }).send();
+        const slot = acc.context.slot;
+        if (acc.value) {
+            const len = Buffer.from(acc.value.data[0], 'base64').length;
+            const count = len >= META ? Math.floor((len - META) / 32) : 0;
+            if (count >= expectedCount) {
+                if (slotAllPresent === null) {
+                    slotAllPresent = slot;
+                }
+                else if (slot > slotAllPresent) {
+                    return; // all addresses present + a slot has elapsed → warm
+                }
+            }
+        }
+        await new Promise((r) => setTimeout(r, 800));
+    }
+    throw new Error(`lookup table ${table} not active (≥${expectedCount} addresses + 1 slot) within ${maxWaitMs}ms`);
+}
+/**
+ * Reclaim rent from the ephemeral Address Lookup Tables `signer` created for
+ * prescribe (see {@link sendWithEphemeralLookupTable}). Each prescribe leaves a
+ * single-use table allocated (~0.0126 SOL of rent); reclaiming needs a
+ * deactivate → ~513-slot cooldown → close sequence, so it can't run inline — a
+ * throttled permissionless cleanup pass (cranker / observer) calls this.
+ *
+ * Discovery is RPC-portable. `getProgramAccounts` on the Address Lookup Table
+ * program is rejected by Agave RPCs (`Invalid param: WrongSize`, on public
+ * devnet/mainnet-beta and dedicated providers alike — the ALT program can't be
+ * enumerated), so instead we read the signer's own transaction history
+ * (`getSignaturesForAddress` + `getTransaction`) and collect the tables it
+ * referenced via `message.addressTableLookups` — a prescribe ALT is used in
+ * exactly one transaction.
+ *
+ * Safety fingerprint: a candidate is only touched when EVERY one of its entries
+ * is owned by a program in `allowedEntryOwners` (the GAR + ArNS programs — i.e.
+ * observer Gateway PDAs + the ArNS NameRegistry). That composition uniquely
+ * identifies a prescribe ephemeral, so the pass never deactivates/closes an
+ * unrelated table even if `signer` is also used to author Address Lookup Tables
+ * for other purposes.
+ *
+ * DEACTIVATES still-active matches (starts the cooldown) and CLOSES deactivated
+ * matches past the cooldown (refunding rent to `signer`). At most `maxTables`
+ * submissions per call; scans at most `scanLimit` recent signatures. Best-effort:
+ * per-table failures are skipped and retried on the next pass.
+ */
+export async function reclaimLookupTablesForSigner({ rpc, rpcSubscriptions, signer, allowedEntryOwners, commitment = 'confirmed', maxTables = 10, scanLimit = 500, }) {
+    const ALT_META = 56; // metadata header before the 32-byte address array
+    const ACTIVE = 0xffffffffffffffffn; // u64::MAX = not yet deactivated
+    const COOLDOWN_SLOTS = 513n; // deactivation_slot must age out of SlotHashes
+    const allowed = new Set(allowedEntryOwners);
+    const addressDecoder = getAddressDecoder();
+    // getTransaction only honours 'confirmed' | 'finalized'.
+    const historyCommitment = commitment === 'finalized' ? 'finalized' : 'confirmed';
+    // --- Discover candidate tables from the signer's transaction history -------
+    const sigs = await rpc
+        .getSignaturesForAddress(signer.address, { limit: scanLimit })
+        .send();
+    const candidates = new Set();
+    for (const { signature } of sigs) {
+        // A little headroom over maxTables so already-closed candidates don't
+        // starve the budget; the rest get picked up next pass.
+        if (candidates.size >= maxTables * 3)
+            break;
+        const tx = await rpc
+            .getTransaction(signature, {
+            encoding: 'json',
+            maxSupportedTransactionVersion: 0,
+            commitment: historyCommitment,
+        })
+            .send();
+        const lookups = tx?.transaction?.message?.addressTableLookups ?? [];
+        for (const l of lookups)
+            candidates.add(l.accountKey);
+    }
+    // --- Reclaim ----------------------------------------------------------------
+    const currentSlot = await rpc.getSlot().send();
+    let deactivated = 0;
+    let closed = 0;
+    for (const table of candidates) {
+        if (deactivated + closed >= maxTables)
+            break;
+        const address = table;
+        try {
+            const info = await rpc
+                .getAccountInfo(address, { encoding: 'base64' })
+                .send();
+            const value = info.value;
+            if (!value)
+                continue; // already closed
+            if (value.owner !==
+                ADDRESS_LOOKUP_TABLE_PROGRAM_ADDRESS) {
+                continue;
+            }
+            const data = Buffer.from(value.data[0], 'base64');
+            if (data.length < ALT_META)
+                continue;
+            const deactivationSlot = data.readBigUInt64LE(4);
+            // Fingerprint: every entry must be owned by an allowed program. A prescribe
+            // ALT is exclusively observer Gateway PDAs (GAR) + the NameRegistry (ArNS).
+            const entries = [];
+            for (let off = ALT_META; off + 32 <= data.length; off += 32) {
+                entries.push(addressDecoder.decode(data.subarray(off, off + 32)));
+            }
+            if (entries.length === 0)
+                continue;
+            const owners = await rpc
+                .getMultipleAccounts(entries, {
+                encoding: 'base64',
+                dataSlice: { offset: 0, length: 0 },
+            })
+                .send();
+            const allOwned = owners.value.every((a) => a != null && allowed.has(a.owner));
+            if (!allOwned)
+                continue; // not a prescribe ephemeral — leave it alone
+            if (deactivationSlot === ACTIVE) {
+                await sendAndConfirm({
+                    rpc,
+                    rpcSubscriptions,
+                    signer,
+                    commitment,
+                    computeUnitLimit: 30_000,
+                    instructions: [
+                        getDeactivateLookupTableInstruction({ address, authority: signer }),
+                    ],
+                });
+                deactivated += 1;
+            }
+            else if (currentSlot > deactivationSlot + COOLDOWN_SLOTS) {
+                await sendAndConfirm({
+                    rpc,
+                    rpcSubscriptions,
+                    signer,
+                    commitment,
+                    computeUnitLimit: 30_000,
+                    instructions: [
+                        getCloseLookupTableInstruction({
+                            address,
+                            authority: signer,
+                            recipient: signer.address,
+                        }),
+                    ],
+                });
+                closed += 1;
+            }
+        }
+        catch {
+            // best-effort: a racing close / not-yet-cooled table just gets retried
+            // on the next cleanup pass.
+        }
+    }
+    return {
+        deactivated,
+        closed,
+        candidates: candidates.size,
+        scannedSignatures: sigs.length,
+    };
+}

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '4.0.0-solana.23';
+export const version = '4.0.0-solana.25';

package/lib/types/solana/deserialize.d.ts

@@ -46,6 +46,7 @@ declare class BorshReader {
     readString(): string;
     readOptionI64(): number | undefined;
     readOptionU32(): number | undefined;
+    readOptionU16(): number | undefined;
     skip(bytes: number): void;
     getOffset(): number;
     remaining(): number;

package/lib/types/solana/index.d.ts

@@ -43,7 +43,7 @@ export * from '../types/index.js';
 export * from '../utils/index.js';
 export { ARWEAVE_TX_REGEX, AR_IO_PROTOCOL, arweaveUri, FQDN_REGEX, MARIO_PER_ARIO, } from '../constants.js';
 export { SolanaARIOReadable } from './io-readable.js';
-export { SolanaARIOWriteable } from './io-writeable.js';
+export { type CrankAction, type CrankEpochStepOptions, type CrankEpochStepResult, isInvalidGatewayAccountError, SolanaARIOWriteable, } from './io-writeable.js';
 export { SolanaANTReadable } from './ant-readable.js';
 export { SolanaANTWriteable } from './ant-writeable.js';
 export { SolanaANTRegistryReadable } from './ant-registry-readable.js';
@@ -60,6 +60,7 @@ export type { SpawnSolanaANTParams, SpawnSolanaANTResult, SpawnSolanaANTState, }
 export { hashName, getArioConfigPDA, getBalancePDA, getVaultPDA, getVaultCounterPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getGatewayRegistryPDA, getGarSettingsPDA, getGatewayPDA, getDelegationPDA, getWithdrawalPDA, getWithdrawalCounterPDA, getAllowlistPDA, getEpochPDA, getEpochSettingsPDA, getObservationPDA, getArnsRegistryPDA, getArnsSettingsPDA, getArnsRecordPDA, getArnsRecordPDAFromHash, getReservedNamePDA, getReturnedNamePDA, getDemandFactorPDA, getPrimaryNameReversePDA, getRedelegationRecordPDA, getAntConfigPDA, getAntControllersPDA, getAntRecordPDA, getAclConfigPDA, getAclPagePDA, getEscrowAntPDA, getEscrowTokenPDA, getEscrowVaultPDA, } from './pda.js';
 export { BorshReader, BorshWriter, deserializeGateway, deserializeArnsRecord, deserializeVault, deserializeDelegation, deserializeBalance, deserializeEpochSettings, deserializeArioConfig, deserializeDemandFactor, deserializeReservedName, deserializeReturnedName, deserializeWithdrawal, deserializeRedelegationRecord, deserializePrimaryNameRequest, deserializePrimaryName, deserializeAllowlist, deserializeGarSettings, deserializeEpochSettingsFull, deserializeEpoch, deserializeObservation, deserializeAntConfig, deserializeAntControllers, deserializeAntRecord, deserializeAclConfig, deserializeAclPage, } from './deserialize.js';
 export type { DeserializedAclEntry } from './deserialize.js';
+export { predictPrescribedObservers, type RegistrySlotWeight, } from './predict-prescribed-observers.js';
 export * from './constants.js';
 export * from './clusters.js';
 export { createCircuitBreakerRpc, defaultFallbackUrl, } from './rpc-circuit-breaker.js';

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

@@ -309,6 +309,21 @@ export declare class SolanaARIOReadable {
         pubkey: Address;
         operator: Address;
     }>>;
+    /**
+     * Enumerate Joined Gateway PDAs whose delegation has been DISABLED
+     * (`allow_delegated_staking == false`) yet still hold delegated stake
+     * (`total_delegated_stake > 0`) — i.e. delegates that an operator's disable
+     * left stranded (WP §6.3 / Fix #6). Each such gateway's delegates must be
+     * cranked out via
+     * {@link SolanaARIOWriteable.claimDelegateFromDisabledGateway} (enumerate
+     * them with {@link getGatewayDelegates}) before the operator can re-enable
+     * delegation. This is the discovery primitive a cranker uses to sweep them.
+     */
+    getDisabledGatewaysWithDelegatedStake(): Promise<Array<{
+        pubkey: Address;
+        operator: Address;
+        totalDelegatedStake: bigint;
+    }>>;
     /**
      * Enumerate Delegation PDAs with `amount == 0`. Eligible for
      * `closeEmptyDelegation` (rent refund to the original delegator).

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

@@ -23,6 +23,7 @@ import type { ILogger } from '../common/logger.js';
 import type { MessageResult, WriteOptions } from '../types/common.js';
 import type { ArNSPurchaseParams, BuyRecordParams, CreateVaultParams, DelegateStakeParams, ExtendLeaseParams, ExtendVaultParams, IncreaseUndernameLimitParams, IncreaseVaultParams, JoinNetworkParams, RedelegateStakeParams, RevokeVaultParams, UpdateGatewaySettingsParams, VaultedTransferParams } from '../types/io.js';
 import type { mARIOToken } from '../types/token.js';
+import { deserializeEpochSettingsFull } from './deserialize.js';
 import { SolanaARIOReadable } from './io-readable.js';
 import type { SolanaRpcSubscriptions, SolanaSigner, SolanaWriteConfig } from './types.js';
 /**
@@ -82,6 +83,50 @@ export declare function buildObservationBitmap(registryAddresses: string[], fail
  *  auditability that the field exists for.
  */
 export declare function encodeReportTxId(reportTxId: string | undefined): Buffer;
+/** The single on-chain action a {@link SolanaARIOWriteable.crankEpochStep} call performed. */
+export type CrankAction = 'create' | 'tally' | 'prescribe' | 'distribute' | 'close' | 'idle';
+/** Options for {@link SolanaARIOWriteable.crankEpochStep}. */
+export interface CrankEpochStepOptions {
+    /** Gateways per tally/distribute batch. Default 30. */
+    batchSize?: number;
+    /**
+     * NameRegistry account for the name-prescription leg. Defaults to the
+     * registry derived from the configured ArNS program. Pass `null` to disable
+     * name prescription entirely.
+     */
+    nameRegistryAccount?: Address | null;
+    /** Close fully-distributed epochs older than `epochRetention`. Default true. */
+    enableClose?: boolean;
+    /** Epochs of retention before an epoch may be closed (GAR-006). Default 7. */
+    epochRetention?: number;
+    /** Unix seconds; defaults to the wall clock. Injectable for testing. */
+    now?: number;
+}
+/** Result of a single {@link SolanaARIOWriteable.crankEpochStep} call. */
+export interface CrankEpochStepResult {
+    /** The action performed (or `'idle'` when nothing was due). */
+    action: CrankAction;
+    /** The epoch the action targeted (absent for `'idle'`). */
+    epochIndex?: number;
+    /** Confirmed transaction signature, when an action was submitted. */
+    txId?: string;
+    /** Batch progress for `'tally'` / `'distribute'`. */
+    progress?: {
+        index: number;
+        total: number;
+    };
+    /** For `action: 'idle'`, why nothing was done. */
+    reason?: 'epochs_disabled' | 'waiting_for_genesis' | 'waiting_for_epoch' | 'waiting_for_observations' | 'epoch_complete';
+}
+/**
+ * Detect the GAR `InvalidGatewayAccount` error by Anchor error name/message
+ * (walking the cause chain + `context.logs`), NOT by numeric code — codes are
+ * `6000 + enum-index` and shift across program versions, but the name and
+ * message are stable. `prescribe_epoch` raises this when a supplied observer
+ * Gateway PDA is missing/spoofed (e.g. a predicted observer left the registry
+ * between prediction and tx landing).
+ */
+export declare function isInvalidGatewayAccountError(error: unknown): boolean;
 export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     protected readonly signer: SolanaSigner;
     protected readonly rpcSubscriptions: SolanaRpcSubscriptions;
@@ -377,6 +422,26 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     claimDelegateFromLeavingGateway(params: {
         gatewayAddress: string;
     }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Claim a delegate's stake out of a gateway that has DISABLED delegation
+     * (`allow_delegated_staking == false`), moving it into the delegate's own
+     * withdrawal vault (WP §6.3 / Fix #6). This is the disabled-gateway analog of
+     * {@link claimDelegateFromLeavingGateway}: the on-chain instruction is
+     * permissionless, so a cranker can sweep delegates out (the operator cannot
+     * re-enable delegation until `total_delegated_stake == 0` and the cooldown
+     * elapses). The withdrawal-counter and withdrawal PDAs are seeded by the
+     * DELEGATOR, so a cranker must pass that delegate's `delegatorAddress`.
+     *
+     * @param params.gatewayAddress  The gateway whose delegation was disabled.
+     * @param params.delegatorAddress  The delegate to claim for. Defaults to the
+     *   signer (self-claim). Pass another address to crank on a delegate's behalf;
+     *   the signer covers rent (`payer`) but stake still routes to the delegate's
+     *   own vault (the delegator key is bound by the delegation PDA seeds).
+     */
+    claimDelegateFromDisabledGateway(params: {
+        gatewayAddress: string;
+        delegatorAddress?: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /** Add an address to the gateway's delegation allowlist. */
     allowDelegate(params: {
         delegate: string;
@@ -428,9 +493,22 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Prescribe observers and names for an epoch. Permissionless — call after
-     * weights are tallied. Gateway PDAs are appended as `remaining_accounts`,
-     * and the optional `nameRegistryAccount` (must be last) enables the name
+     * weights are tallied.
+     *
+     * `gatewayAccounts` MUST be the Gateway PDAs of the SELECTED observers only
+     * — at most `epoch_settings.prescribed_observer_count` (≤50), NOT the whole
+     * registry. The selection is computed on-chain; mirror it off-chain with
+     * {@link predictPrescribedObservers} / {@link getPredictedObserverPDAs} to
+     * learn the set. Passing every registry gateway (e.g. via
+     * {@link getAllRegistryGatewayPDAs}) hits Solana's `MAX_TX_ACCOUNT_LOCKS = 64`
+     * on large registries and the tx fails at pre-flight.
+     *
+     * The selected PDAs are appended as `remaining_accounts`, followed by the
+     * optional `nameRegistryAccount` (must be LAST) which enables the name
      * prescription leg.
+     *
+     * If a selected gateway leaves between prediction and tx landing, the tx
+     * fails with `InvalidGatewayAccount` — retry once with a fresh prediction.
      */
     prescribeEpoch(params: {
         epochIndex: number;
@@ -461,6 +539,74 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     getRegistryGatewayPDAs(startIndex: number, batchSize: number): Promise<Address[]>;
     /** Get ALL active gateway PDAs from the registry. */
     getAllRegistryGatewayPDAs(): Promise<Address[]>;
+    /**
+     * Predict the Gateway PDAs that `prescribe_epoch` will select as observers
+     * for `epochIndex`, mirroring the on-chain weighted-roulette selection.
+     *
+     * Returns at most `epoch_settings.prescribed_observer_count` (≤50) PDAs
+     * regardless of registry size — the set to pass as `gatewayAccounts` to
+     * {@link prescribeEpoch}. This is the size-safe replacement for
+     * {@link getAllRegistryGatewayPDAs} on the prescribe path (which oversupplies
+     * and trips `MAX_TX_ACCOUNT_LOCKS = 64` on large registries).
+     *
+     * Reads three accounts (epoch, registry, epoch settings) at the configured
+     * commitment so the prediction reflects live registry weights. If a selected
+     * gateway races out before the tx lands, `prescribeEpoch` throws
+     * `InvalidGatewayAccount` — re-call this and retry once.
+     */
+    getPredictedObserverPDAs(epochIndex: number): Promise<Address[]>;
+    /**
+     * Reclaim rent from the ephemeral Address Lookup Tables this signer created
+     * for `prescribe_epoch` (see {@link sendWithEphemeralLookupTable}). Each
+     * prescribe leaves a single-use table allocated (~0.0126 SOL); reclaiming
+     * needs a deactivate → ~513-slot cooldown → close sequence, so it can't run
+     * inline. Call this from a throttled/permissionless cleanup pass (cranker /
+     * observer) to deactivate active tables and close cooled-down ones, refunding
+     * the rent to the signer.
+     *
+     * Discovery reads the signer's transaction history (RPC-portable; the ALT
+     * program can't be enumerated via `getProgramAccounts`). The GAR + ArNS
+     * program IDs are passed as the entry-ownership fingerprint so only genuine
+     * prescribe tables are touched. Best-effort: at most `maxTables` submissions
+     * per call, scanning at most `scanLimit` recent signatures.
+     */
+    reclaimLookupTableRent(opts?: {
+        maxTables?: number;
+        scanLimit?: number;
+    }): Promise<{
+        deactivated: number;
+        closed: number;
+        candidates: number;
+        scannedSignatures: number;
+    }>;
+    /** Read and deserialize the full EpochSettings account. */
+    getEpochSettingsFull(): Promise<ReturnType<typeof deserializeEpochSettingsFull>>;
+    /**
+     * Submit `prescribe_epoch` using the off-chain-predicted observer set, with a
+     * single re-predict-and-retry on `InvalidGatewayAccount` (covers a gateway
+     * leaving the registry between the prediction read and the tx landing).
+     */
+    protected prescribeWithPrediction(epochIndex: number, nameRegistryAccount?: Address): Promise<MessageResult>;
+    /**
+     * Advance the epoch lifecycle by ONE on-chain action and return what it did.
+     *
+     * Stateless and idempotent: it reads `EpochSettings` + the current `Epoch`,
+     * determines the single next required step
+     * (`create` → `tally` → `prescribe` → `distribute` → `close`), submits it,
+     * and returns a {@link CrankEpochStepResult}. Call it repeatedly on your own
+     * schedule — it owns *which* on-chain action is correct and *which accounts*
+     * it needs; you own scheduling, logging, error classification, and any
+     * permissionless cleanup.
+     *
+     * Crucially, the `prescribe` leg uses {@link getPredictedObserverPDAs} (only
+     * the ~`prescribed_observer_count` selected Gateway PDAs), so it never trips
+     * `MAX_TX_ACCOUNT_LOCKS = 64` on large registries — and it re-predicts and
+     * retries once on `InvalidGatewayAccount`.
+     *
+     * Errors propagate to the caller (classify/retry as you see fit); the only
+     * internally-handled error is the prescribe `InvalidGatewayAccount` retry.
+     */
+    crankEpochStep(opts?: CrankEpochStepOptions): Promise<CrankEpochStepResult>;
     /**
      * Read the raw epoch account data for cranker state inspection.
      * Returns null if the epoch account doesn't exist yet.

package/lib/types/solana/predict-prescribed-observers.d.ts

@@ -0,0 +1,28 @@
+import { type Address } from '@solana/kit';
+/** One registry slot's selection-relevant fields (`GatewaySlot`). */
+export interface RegistrySlotWeight {
+    /** `GatewaySlot.address` — the operator pubkey. Gateway PDAs derive from this. */
+    address: Address;
+    /** `GatewaySlot.composite_weight` (u64, mARIO-scaled). */
+    compositeWeight: bigint;
+}
+/**
+ * Predict the operator pubkeys `prescribe_epoch` will select as observers.
+ *
+ * Returns the selected `GatewaySlot.address` values (operator pubkeys) in
+ * selection order, at most `maxObservers`. These correspond 1:1 to the on-chain
+ * `epoch.prescribed_observer_gateways` array, and are what Gateway PDAs are
+ * derived from (`[GATEWAY_SEED, operator]`). NOTE this is NOT
+ * `epoch.prescribed_observers`, which `prescribe_epoch` later overwrites with
+ * each gateway's resolved `observer_address`.
+ *
+ * @param epochHashchain `epoch.hashchain` — exactly 32 bytes, frozen at
+ *   `create_epoch`.
+ * @param slots `registry.gateways[0 .. epoch.active_gateway_count]` in registry
+ *   (slot-index) order. Pass the whole prefix including any zero-weight slots —
+ *   order and the live weight sum must match the on-chain walk exactly. Empty /
+ *   zero-weight slots contribute nothing and can never be selected.
+ * @param maxObservers `epoch_settings.prescribed_observer_count`. Clamped to
+ *   `slots.length` (the on-chain `min(prescribed_observer_count, active_count)`).
+ */
+export declare function predictPrescribedObservers(epochHashchain: Uint8Array, slots: RegistrySlotWeight[], maxObservers: number): Address[];

package/lib/types/solana/send.d.ts

@@ -1,4 +1,4 @@
-import { type Commitment, type Instruction, type TransactionSigner } from '@solana/kit';
+import { type Address, type Commitment, type Instruction, type TransactionSigner } from '@solana/kit';
 import type { SolanaRpc, SolanaRpcSubscriptions } from './types.js';
 /**
  * Build, sign, send, and confirm a transaction in one call.
@@ -6,11 +6,89 @@ import type { SolanaRpc, SolanaRpcSubscriptions } from './types.js';
  * The caller supplies the core instructions; a compute-unit-limit instruction
  * is prepended automatically.
  */
-export declare function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment, computeUnitLimit, }: {
+export declare function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment, computeUnitLimit, addressLookupTables, }: {
     rpc: SolanaRpc;
     rpcSubscriptions: SolanaRpcSubscriptions;
     signer: TransactionSigner;
     instructions: Instruction[];
     commitment?: Commitment;
     computeUnitLimit?: number;
+    /**
+     * Address Lookup Tables to compress the (v0) message against, as
+     * `{ [tableAddress]: addresses }`. Accounts present in a table are referenced
+     * by 1-byte index instead of their 32-byte key, shrinking the transaction —
+     * required when an instruction touches more accounts than fit inline (e.g.
+     * `prescribe_epoch` with ~50 observer PDAs). The tables MUST already be
+     * on-chain and active. See {@link sendWithEphemeralLookupTable}.
+     */
+    addressLookupTables?: Record<string, Address[]>;
 }): Promise<string>;
+/**
+ * Submit `instruction` in a v0 transaction whose `lookupAddresses` (read-only
+ * accounts) are served from a freshly-created, ephemeral Address Lookup Table,
+ * so an instruction touching far more accounts than fit inline (e.g.
+ * `prescribe_epoch` with ≤50 observer PDAs + NameRegistry, ~2 KB of keys) still
+ * fits Solana's 1232-byte transaction-size limit.
+ *
+ * Three confirmed steps: create the table, extend it with the addresses (in
+ * ≤20-address batches to stay within the extend tx size), then send
+ * `instruction` compressed against the table. The sequential confirmations
+ * satisfy the rule that appended addresses are only usable the slot AFTER they
+ * are added. `signer` is the table's authority + payer; the table's (tiny) rent
+ * is left allocated — a future cleanup pass can deactivate + close it.
+ */
+export declare function sendWithEphemeralLookupTable({ rpc, rpcSubscriptions, signer, instruction, lookupAddresses, commitment, computeUnitLimit, }: {
+    rpc: SolanaRpc;
+    rpcSubscriptions: SolanaRpcSubscriptions;
+    signer: TransactionSigner;
+    instruction: Instruction;
+    lookupAddresses: Address[];
+    commitment?: Commitment;
+    computeUnitLimit?: number;
+}): Promise<string>;
+/**
+ * Reclaim rent from the ephemeral Address Lookup Tables `signer` created for
+ * prescribe (see {@link sendWithEphemeralLookupTable}). Each prescribe leaves a
+ * single-use table allocated (~0.0126 SOL of rent); reclaiming needs a
+ * deactivate → ~513-slot cooldown → close sequence, so it can't run inline — a
+ * throttled permissionless cleanup pass (cranker / observer) calls this.
+ *
+ * Discovery is RPC-portable. `getProgramAccounts` on the Address Lookup Table
+ * program is rejected by Agave RPCs (`Invalid param: WrongSize`, on public
+ * devnet/mainnet-beta and dedicated providers alike — the ALT program can't be
+ * enumerated), so instead we read the signer's own transaction history
+ * (`getSignaturesForAddress` + `getTransaction`) and collect the tables it
+ * referenced via `message.addressTableLookups` — a prescribe ALT is used in
+ * exactly one transaction.
+ *
+ * Safety fingerprint: a candidate is only touched when EVERY one of its entries
+ * is owned by a program in `allowedEntryOwners` (the GAR + ArNS programs — i.e.
+ * observer Gateway PDAs + the ArNS NameRegistry). That composition uniquely
+ * identifies a prescribe ephemeral, so the pass never deactivates/closes an
+ * unrelated table even if `signer` is also used to author Address Lookup Tables
+ * for other purposes.
+ *
+ * DEACTIVATES still-active matches (starts the cooldown) and CLOSES deactivated
+ * matches past the cooldown (refunding rent to `signer`). At most `maxTables`
+ * submissions per call; scans at most `scanLimit` recent signatures. Best-effort:
+ * per-table failures are skipped and retried on the next pass.
+ */
+export declare function reclaimLookupTablesForSigner({ rpc, rpcSubscriptions, signer, allowedEntryOwners, commitment, maxTables, scanLimit, }: {
+    rpc: SolanaRpc;
+    rpcSubscriptions: SolanaRpcSubscriptions;
+    signer: TransactionSigner;
+    /**
+     * Program IDs that EVERY entry of a reclaimable prescribe ALT must be owned by
+     * — pass the GAR + ArNS program IDs. The fingerprint that keeps reclamation
+     * from touching unrelated lookup tables.
+     */
+    allowedEntryOwners: Address[];
+    commitment?: Commitment;
+    maxTables?: number;
+    scanLimit?: number;
+}): Promise<{
+    deactivated: number;
+    closed: number;
+    candidates: number;
+    scannedSignatures: number;
+}>;

package/lib/types/types/io.d.ts

@@ -232,6 +232,22 @@ export type GatewaySettings = {
     fqdn: string;
     port: number;
     protocol: 'https';
+    /**
+     * Solana only (GATEWAY_VERSION 1.1.0+). A `delegateRewardShareRatio` change
+     * requested mid-epoch is staged here and applied at the next epoch's
+     * `tally_weights` (WP §6.3 / Fix #7), so the active value stays epoch-stable.
+     * When set, render the active `delegateRewardShareRatio` as the current rate
+     * and this as "pending until next epoch". Percent (0-95), same scale as
+     * `delegateRewardShareRatio`. Undefined when no change is queued.
+     */
+    pendingDelegateRewardShareRatio?: number;
+    /**
+     * Solana only (GATEWAY_VERSION 1.1.0+). Unix seconds when the operator
+     * disabled delegation (WP §6.3 / Fix #6). Re-enabling is blocked until every
+     * delegate has been withdrawn AND the withdrawal-period cooldown has elapsed
+     * since this time. Undefined when delegation is enabled.
+     */
+    delegationDisabledAt?: number;
 };
 export type BalanceWithAddress = {
     address: WalletAddress;

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "4.0.0-solana.22";
+export declare const version = "4.0.0-solana.24";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.0.0-solana.23",
+  "version": "4.0.0-solana.25",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"
@@ -123,7 +123,8 @@
     "typescript": "^5.1.6"
   },
   "dependencies": {
-    "@ar.io/solana-contracts": "0.4.0",
+    "@ar.io/solana-contracts": "0.5.0-staging.15",
+    "@solana-program/address-lookup-table": "^0.11.0",
     "@solana-program/compute-budget": "^0.15.0",
     "@solana-program/token": "^0.13.0",
     "@solana/kit": "^6.8.0",