@ar.io/sdk 4.0.0-solana.32 → 4.0.0-solana.34

package/lib/esm/solana/delegation-math.js

@@ -76,3 +76,37 @@ export function computeLiveDelegationBalance({ delegatedStake, rewardDebt, cumul
     const capped = live > U64_MAX ? U64_MAX : live;
     return Number(capped);
 }
+/**
+ * Select the delegations worth compounding, from decoded delegations + a map
+ * of their gateways' reward accumulators. Pure (no I/O) so it's unit-testable
+ * independently of RPC; `SolanaARIOReadable.getDelegationsToCompound` is just
+ * fetch+decode wrapped around this.
+ *
+ * A delegation is included when its pending reward (live balance − settled
+ * principal) exceeds `minPendingRewards`, EXCEPT when its gateway is `leaving`
+ * (those settle via `claim_delegate_from_leaving_gateway`, not compounding) or
+ * its gateway is missing/unreadable. Compounding sub-threshold dust only
+ * advances `reward_debt` for no balance gain, so it's filtered out.
+ */
+export function selectCompoundableDelegations(delegations, gatewaysByOperator, minPendingRewards = 0) {
+    const out = [];
+    for (const del of delegations) {
+        const gw = gatewaysByOperator.get(del.gateway);
+        if (!gw || gw.status === 'leaving')
+            continue;
+        const live = computeLiveDelegationBalance({
+            delegatedStake: del.delegatedStake,
+            rewardDebt: del.rewardDebt,
+            cumulativeRewardPerToken: gw.cumulativeRewardPerToken,
+        });
+        const pendingRewards = live - del.delegatedStake;
+        if (pendingRewards <= minPendingRewards)
+            continue;
+        out.push({
+            gatewayAddress: del.gateway,
+            delegatorAddress: del.delegator,
+            pendingRewards,
+        });
+    }
+    return out;
+}

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

@@ -29,7 +29,7 @@ import { Logger } from '../common/logger.js';
 import { SolanaANTRegistryReadable } from './ant-registry-readable.js';
 import { getAssociatedTokenAddressKit } from './ata.js';
 import { ARIO_ANT_PROGRAM_ID, ARIO_ARNS_PROGRAM_ID, ARIO_CORE_PROGRAM_ID, ARIO_GAR_PROGRAM_ID, ARNS_RECORD_ANT_OFFSET, RATE_SCALE, } from './constants.js';
-import { computeLiveDelegationBalance } from './delegation-math.js';
+import { computeLiveDelegationBalance, selectCompoundableDelegations, } from './delegation-math.js';
 import { deserializeAllowlist, deserializeArioConfig, deserializeArnsRecord, deserializeDelegation, deserializeDemandFactor, deserializeEpoch, deserializeEpochSettings, deserializeEpochSettingsFull, deserializeGarSettings, deserializeGarSupplyCounters, deserializeGateway, deserializeGatewayWithAccumulator, deserializeObservation, deserializePrimaryName, deserializePrimaryNameRequest, deserializeRedelegationRecord, deserializeReservedName, deserializeReturnedName, deserializeVault, deserializeWithdrawal, } from './deserialize.js';
 import { TOKEN_PROGRAM_ADDRESS } from './instruction.js';
 import { getArioConfigPDA, getArnsRecordPDA, getArnsRecordPDAFromHash, getArnsSettingsPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getObserverLookupPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, } from './pda.js';
@@ -1639,6 +1639,56 @@ export class SolanaARIOReadable {
         }));
         return paginate(items, params);
     }
+    /**
+     * Enumerate every delegation that has pending (unsettled) rewards — the work
+     * list for the permissionless `compound_delegation_rewards` crank. Pending is
+     * computed from the gateway's reward-per-share accumulator (mirrors
+     * {@link computeLiveDelegationBalance}); the crank only changes balances, so
+     * rewards already accrue correctly without it.
+     *
+     * Skips delegations whose gateway is `Leaving` (those settle through
+     * `claim_delegate_from_leaving_gateway`, not compounding) and any below
+     * `minPendingRewards` — compounding sub-threshold dust just advances
+     * `reward_debt` for no balance gain. Feed the result, chunked, to
+     * `SolanaARIOWriteable.compoundDelegationRewardsBatch`.
+     */
+    async getDelegationsToCompound(params) {
+        const minPending = params?.minPendingRewards ?? 0;
+        // One scan for gateways → accumulator + status.
+        const gatewayAccounts = await this.getAccountsByDiscriminator(this.garProgram, GATEWAY_DISCRIMINATOR);
+        const gateways = new Map();
+        for (const { data } of gatewayAccounts) {
+            try {
+                const gw = deserializeGatewayWithAccumulator(data);
+                gateways.set(gw.operator, {
+                    cumulativeRewardPerToken: gw.cumulativeRewardPerToken,
+                    status: gw.status,
+                });
+            }
+            catch {
+                // Skip malformed.
+            }
+        }
+        // One scan for delegations; decode then delegate the selection logic to the
+        // pure `selectCompoundableDelegations` (unit-tested in delegation-math).
+        const delegationAccounts = await this.getAccountsByDiscriminator(this.garProgram, DELEGATION_DISCRIMINATOR);
+        const delegations = [];
+        for (const { data } of delegationAccounts) {
+            try {
+                const del = deserializeDelegation(data);
+                delegations.push({
+                    gateway: del.gateway,
+                    delegator: del.delegator,
+                    delegatedStake: del.delegatedStake,
+                    rewardDebt: del.rewardDebt,
+                });
+            }
+            catch {
+                // Skip malformed.
+            }
+        }
+        return selectCompoundableDelegations(delegations, gateways, minPending);
+    }
     async getAllGatewayVaults(params) {
         const accounts = await this.getAccountsByDiscriminator(this.garProgram, WITHDRAWAL_DISCRIMINATOR);
         const items = [];

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

@@ -34,10 +34,10 @@
  *      surface for them.
  */
 import { AccountRole, address, appendTransactionMessageInstructions, compileTransaction, createTransactionMessage, fetchEncodedAccount, getAddressDecoder, getBase64EncodedWireTransaction, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, } from '@solana/kit';
-import { CostIntent, PurchaseType, getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getGetTokenCostInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getMigrateArnsRecordInstruction, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from '@ar.io/solana-contracts/arns';
+import { CostIntent, PurchaseType, getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getGetTokenCostInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getMigrateArnsRecordInstruction, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpdateDemandFactorInstruction, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from '@ar.io/solana-contracts/arns';
 import { FundingSourceKind as GeneratedFundingSourceKindEnum } from '@ar.io/solana-contracts/gar';
 import { buildCreateAtaIdempotentIx, getAssociatedTokenAddressKit, } from './ata.js';
-import { deserializeArnsRecord, deserializeEpochSettingsFull, deserializePrimaryName, } from './deserialize.js';
+import { deserializeArnsRecord, deserializeDemandFactor, deserializeEpochSettingsFull, deserializePrimaryName, } from './deserialize.js';
 import { buildFundingPlan as buildFundingPlanCore, buildFundingPlanRemainingAccounts, computeResidueIndexes, predictResidueVaults, } from './funding-plan.js';
 /** Maps the SDK's user-facing FundingSourceKind string union to the
  *  Codama-generated enum used by the on-chain ix payload. */
@@ -53,7 +53,7 @@ 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, 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, getUpdateObserverAddressInstructionAsync, } from '@ar.io/solana-contracts/gar';
+import { Protocol, getAllowDelegateInstructionAsync, getCancelWithdrawalInstruction, getClaimDelegateFromDisabledGatewayInstructionAsync, getClaimDelegateFromLeavingGatewayInstructionAsync, getClaimWithdrawalInstructionAsync, getCloseDrainedWithdrawalInstruction, getCloseEmptyDelegationInstruction, getCloseEpochInstructionAsync, getCloseObservationInstructionAsync, getCompoundDelegationRewardsInstruction, getCreateEpochInstructionAsync, getDecreaseDelegateStakeInstructionAsync, getDecreaseOperatorStakeInstructionAsync, getDelegateStakeInstructionAsync, getDisallowDelegateInstructionAsync, getDistributeEpochInstructionAsync, getFinalizeGoneInstructionAsync, getIncreaseOperatorStakeInstructionAsync, getInstantWithdrawalInstructionAsync, getJoinNetworkInstructionAsync, getLeaveNetworkInstructionAsync, getPrescribeEpochInstructionAsync, getPruneGatewayInstructionAsync, getRedelegateStakeInstructionAsync, getSaveObservationsInstructionAsync, getSetAllowlistEnabledInstructionAsync, getTallyWeightsInstructionAsync, getUpdateGatewaySettingsInstructionAsync, getUpdateObserverAddressInstructionAsync, } from '@ar.io/solana-contracts/gar';
 import { getTransferCheckedInstruction } from '@solana-program/token';
 import { ARIO_ANT_PROGRAM_ID, TOKEN_DECIMALS } from './constants.js';
 import { SolanaARIOReadable } from './io-readable.js';
@@ -227,6 +227,14 @@ export function encodeReportTxId(reportTxId) {
     decoded.copy(out);
     return out;
 }
+/**
+ * Max `compound_delegation_rewards` instructions packed into one batched tx.
+ * Each carries a gateway + delegation + delegator account; 12 stays well within
+ * the per-tx account/1232-byte budget even when none share a gateway.
+ */
+const MAX_COMPOUND_BATCH = 12;
+/** Demand-factor period length (seconds) — mirrors `PERIOD_LENGTH_SECONDS` in ario-arns. */
+const DEMAND_FACTOR_PERIOD_SECONDS = 86_400;
 /**
  * Detect the GAR `InvalidGatewayAccount` error by Anchor error name/message
  * (walking the cause chain + `context.logs`), NOT by numeric code — codes are
@@ -873,7 +881,16 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 params: buyNameParams,
             }, { programAddress: this.arnsProgram });
         }
-        else if (params.fundFrom === 'plan' || params.fundFrom === 'any') {
+        else if (params.fundFrom === 'plan' ||
+            params.fundFrom === 'any' ||
+            params.fundFrom === 'stakes' ||
+            params.fundFrom === 'withdrawal') {
+            // 'stakes'/'withdrawal' WITHOUT an explicit gatewayAddress/withdrawalId
+            // land here (the single-source branches above handle the explicit case).
+            // Route through the funding planner, which constrains sources to the
+            // chosen mode — it never silently spends liquid balance and auto-splits
+            // across the caller's delegations/vaults. (Previously these fell through
+            // to the balance path below, silently draining liquid ARIO.)
             ix = await this._buildBuyNameFromFundingPlanIx({
                 params,
                 antPubkey,
@@ -884,8 +901,10 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 arnsConfig,
             });
         }
-        else {
-            // 'balance' or undefined falls through to the original direct-buy path.
+        else if (!params.fundFrom ||
+            params.fundFrom === 'balance' ||
+            params.fundFrom === 'turbo') {
+            // Direct balance-funded buy.
             ix = await getBuyNameInstructionAsync(await this.withArnsDefaults({
                 arnsRecord,
                 buyerTokenAccount: buyerATA,
@@ -896,6 +915,9 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 params: buyNameParams,
             }), { programAddress: this.arnsProgram });
         }
+        else {
+            throw new Error(`unsupported fundFrom mode '${params.fundFrom}' for buyRecord`);
+        }
         // Sprint 4 / ADR-016: bundle `ant.sync_attributes` IFF the buyer
         // owns the ANT (preserves BD-096 — non-holder buys defer the trait
         // sync to a later `syncAttributes()` call by the actual owner).
@@ -1420,7 +1442,14 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 return getExtendLeaseFromWithdrawalInstructionAsync({ ...wBase, years: args.years }, { programAddress: this.arnsProgram });
             return getIncreaseUndernameLimitFromWithdrawalInstructionAsync({ ...wBase, quantity: args.quantity }, { programAddress: this.arnsProgram });
         }
-        if (args.params.fundFrom === 'plan' || args.params.fundFrom === 'any') {
+        if (args.params.fundFrom === 'plan' ||
+            args.params.fundFrom === 'any' ||
+            args.params.fundFrom === 'stakes' ||
+            args.params.fundFrom === 'withdrawal') {
+            // 'stakes'/'withdrawal' without an explicit gatewayAddress/withdrawalId
+            // route here (the single-source branches above handle the explicit
+            // case). The planner constrains sources to the chosen mode and never
+            // spends liquid balance.
             // Cost estimation for manage variants: each operation has its own
             // pricing path. Keep it pragmatic — let the planner build the plan
             // around the user's desired total (caller can pass explicit sources
@@ -1979,10 +2008,54 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             years: params.years ?? 1,
             ant: antPubkey,
         };
+        // Returned-name price is a per-slot-decaying Dutch auction, so the
+        // multi-source funding plan (which pre-commits exact source amounts) can't
+        // match the execution-time cost → FundingPlanAmountMismatch (#6066). Prefer
+        // a single-source stake path: it carries no amount, so the program computes
+        // and draws the live cost itself. When the caller asked to fund from
+        // stakes/withdrawal/any without naming a specific gateway/vault,
+        // auto-resolve a single source with enough stake to cover the
+        // (premium-inclusive) cost.
+        let resolvedGateway = params.gatewayAddress;
+        let resolvedFundAsOperator = params.fundAsOperator ?? false;
+        let resolvedWithdrawalId = params.withdrawalId;
+        const wantsStake = params.fundFrom === 'stakes' ||
+            params.fundFrom === 'withdrawal' ||
+            params.fundFrom === 'any';
+        if (wantsStake &&
+            resolvedGateway === undefined &&
+            resolvedWithdrawalId === undefined &&
+            !params.sources?.length) {
+            const picked = await this._autoPickReturnedNameStakeSource(params);
+            if (picked?.kind === 'delegation') {
+                resolvedGateway = picked.gateway;
+                resolvedFundAsOperator = false;
+            }
+            else if (picked?.kind === 'operatorStake') {
+                resolvedGateway = picked.gateway;
+                resolvedFundAsOperator = true;
+            }
+            else if (picked?.kind === 'withdrawal') {
+                resolvedWithdrawalId = picked.withdrawalId;
+            }
+            else if (params.fundFrom !== 'any') {
+                // 'stakes'/'withdrawal' explicitly requested but nothing covers it.
+                throw new Error(`buyReturnedName: no ${params.fundFrom === 'withdrawal'
+                    ? 'matured withdrawal vault'
+                    : 'delegation/operator stake'} large enough to fund '${params.name}' was found for ` +
+                    `${this.signer.address}. Fund from balance, or add stake first.`);
+            }
+            // 'any' with nothing found → falls through to the balance path.
+        }
         let ix;
-        if (!params.fundFrom ||
+        const useBalance = !params.fundFrom ||
             params.fundFrom === 'balance' ||
-            params.fundFrom === 'turbo') {
+            params.fundFrom === 'turbo' ||
+            (params.fundFrom === 'any' &&
+                resolvedGateway === undefined &&
+                resolvedWithdrawalId === undefined &&
+                !params.sources?.length);
+        if (useBalance) {
             ix = await getBuyReturnedNameInstructionAsync(await this.withArnsDefaults({
                 arnsRecord,
                 returnedName: returnedNamePda,
@@ -2011,10 +2084,10 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 garProgram: this.garProgram,
                 params: buyParams,
             };
-            if (params.fundFrom === 'stakes' && params.gatewayAddress) {
-                const gatewayAddr = address(params.gatewayAddress);
+            if (resolvedGateway !== undefined) {
+                const gatewayAddr = address(resolvedGateway);
                 const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
-                if (params.fundAsOperator) {
+                if (resolvedFundAsOperator) {
                     ix = await getBuyReturnedNameFromOperatorStakeInstructionAsync({ ...sharedReturnedBase, gateway: gatewayPda }, { programAddress: this.arnsProgram });
                 }
                 else {
@@ -2026,17 +2099,16 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                     }, { programAddress: this.arnsProgram });
                 }
             }
-            else if (params.fundFrom === 'withdrawal' &&
-                params.withdrawalId !== undefined) {
-                const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, params.withdrawalId, this.garProgram);
+            else if (resolvedWithdrawalId !== undefined) {
+                const [withdrawalPda] = await getWithdrawalPDA(this.signer.address, resolvedWithdrawalId, this.garProgram);
                 ix = await getBuyReturnedNameFromWithdrawalInstructionAsync({ ...sharedReturnedBase, withdrawal: withdrawalPda }, { programAddress: this.arnsProgram });
             }
-            else if (params.fundFrom === 'plan' || params.fundFrom === 'any') {
-                // Returned-name pricing is dynamic (Dutch auction premium); we trust
-                // explicit caller-supplied sources here and skip auto-discovery if
-                // sources is provided. For 'any' without sources, we fall back to a
-                // best-effort estimate using the plain registration fee — caller can
-                // always retry with explicit sources on FundingPlanAmountMismatch.
+            else if (params.fundFrom === 'plan' && params.sources?.length) {
+                // Explicit caller-supplied plan only: the caller owns the source
+                // amounts and accepts the decay risk (the price moves per slot, so a
+                // stale plan trips FundingPlanAmountMismatch). We do NOT auto-discover
+                // a multi-source plan for returned names — see the single-source note
+                // above.
                 const cost = await this._simulateTokenCost({
                     intent: CostIntent.BuyName,
                     name: params.name,
@@ -2060,14 +2132,63 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 throw new Error(`unsupported fundFrom mode '${params.fundFrom}' for buyReturnedName`);
             }
         }
+        // The on-chain `buy_returned_name*` handlers take `initiator_token_account`
+        // and `buyer_token_account` as `Account<TokenAccount>` (NOT `init`), so
+        // Anchor requires both ATAs to already exist or fails with
+        // AccountNotInitialized (#3012). The original initiator may never have held
+        // ARIO, and the premium always settles from the buyer's liquid ATA — bundle
+        // idempotent ATA creates so the buy succeeds without a separate setup step
+        // (mirrors the vault-ATA handling above). Idempotent: ~1500 CU each, no-op
+        // when the account already exists.
+        const createInitiatorAtaIx = buildCreateAtaIdempotentIx(this.signer.address, initiatorATA, initiator, arnsConfig.mint);
+        const createBuyerAtaIx = buildCreateAtaIdempotentIx(this.signer.address, buyerATA, this.signer.address, arnsConfig.mint);
         // Sprint 4 / ADR-016: bundle ant.sync_attributes after the buy so the
         // Attributes plugin reflects the new record holder. assetOverride =
         // antPubkey because the ArnsRecord PDA is created by buy_returned_name
         // and doesn't exist on-chain at SDK build time.
         const syncIx = await this._buildSyncAttributesIxIfOwner(params.name, antPubkey);
-        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        const sig = await this.sendTransaction([
+            createBuyerAtaIx,
+            createInitiatorAtaIx,
+            ix,
+            ...(syncIx ? [syncIx] : []),
+        ]);
         return { id: sig };
     }
+    /**
+     * Pick a single stake-derived funding source that can cover a returned-name
+     * purchase, for the single-source `buy_returned_name_from_*` paths.
+     *
+     * Returned-name prices decay per slot, so the multi-source funding plan
+     * (which pre-commits exact amounts) can't match the execution-time cost. The
+     * single-source paths carry no amount — the program draws the live cost — so
+     * we only need to pick ONE source with enough stake. We size the pick against
+     * the premium-inclusive estimate (an upper bound, since the price only falls
+     * from now) and choose the largest matching source. Returns `null` when no
+     * single source covers the estimate.
+     */
+    async _autoPickReturnedNameStakeSource(params) {
+        const estimate = BigInt(Math.ceil(await this.getTokenCost({
+            intent: 'Buy-Name',
+            name: params.name,
+            type: params.type,
+            years: params.years ?? 1,
+        })));
+        const arnsConfig = await this.getArnsConfig();
+        const { discoverFundingSources } = await import('./funding-plan.js');
+        const sources = await discoverFundingSources(this.rpc, this.signer.address, { arioMint: arnsConfig.mint, garProgram: this.garProgram });
+        // 'withdrawal' mode → matured withdrawal vaults only; otherwise prefer
+        // operator stake when the caller asked, else a delegation.
+        const wantKind = params.fundFrom === 'withdrawal'
+            ? 'withdrawal'
+            : params.fundAsOperator === true
+                ? 'operatorStake'
+                : 'delegation';
+        const candidates = sources
+            .filter((s) => s.kind === wantKind && s.available >= estimate)
+            .sort((a, b) => b.available > a.available ? 1 : b.available < a.available ? -1 : 0);
+        return candidates[0] ?? null;
+    }
     // =========================================
     // Name management (ario-arns)
     // =========================================
@@ -2124,6 +2245,66 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         return { id: sig };
     }
     // =========================================
+    // Lazy-state crank steps — materialize accumulator/period state.
+    // Both are permissionless + idempotent (safe to crank on a schedule).
+    // =========================================
+    /**
+     * Roll the demand factor forward to the current period. Permissionless and
+     * idempotent — a no-op within the same period. Pricing already rolls the
+     * factor inline on every buy/extend, so this only refreshes the STORED
+     * factor that `getDemandFactor` and between-buy price previews read; a
+     * periodic crank (~once per 24h `PERIOD_LENGTH_SECONDS`) keeps it current.
+     */
+    async updateDemandFactor(_options) {
+        const [demandFactorPda] = await getDemandFactorPDA(this.arnsProgram);
+        const ix = getUpdateDemandFactorInstruction({ demandFactor: demandFactorPda, payer: this.signer }, { programAddress: this.arnsProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Materialize a single delegate's pending rewards into their delegated
+     * stake by settling the gateway's reward-per-share accumulator.
+     * Permissionless — there is no signer beyond the fee payer; `delegator` is
+     * only a PDA-derivation seed. Rewards always accrue correctly in the
+     * accumulator regardless of this call; compounding makes the on-chain
+     * `delegatedStake` reflect them (and earn compound interest in the next
+     * epoch's weighting). Idempotent — a no-op once already settled.
+     */
+    async compoundDelegationRewards(params, _options) {
+        const ix = await this.buildCompoundDelegationRewardsInstruction(params);
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    /**
+     * Compound many delegates' rewards in a SINGLE transaction — one
+     * `compound_delegation_rewards` instruction per entry. Idempotent and
+     * permissionless, so partial batches are safe to retry. Keep each batch
+     * within the per-tx account/CU budget; grouping entries that share a gateway
+     * lowers the unique-account count (the gateway account is reused across
+     * instructions). Typical cranker usage: enumerate with
+     * `SolanaARIOReadable.getDelegationsToCompound`, chunk, then call this.
+     */
+    async compoundDelegationRewardsBatch(delegations, _options) {
+        if (delegations.length === 0) {
+            throw new Error('compoundDelegationRewardsBatch: delegations list is empty');
+        }
+        const ixs = await Promise.all(delegations.map((d) => this.buildCompoundDelegationRewardsInstruction(d)));
+        const sig = await this.sendTransaction(ixs, 1_400_000);
+        return { id: sig };
+    }
+    /**
+     * Build a single `compound_delegation_rewards` instruction (shared by the
+     * single + batch methods). PDAs are derived under the configured gar program
+     * so the program-id override always targets the right cluster.
+     */
+    async buildCompoundDelegationRewardsInstruction(params) {
+        const gateway = address(params.gateway);
+        const delegator = address(params.delegator);
+        const [gatewayPda] = await getGatewayPDA(gateway, this.garProgram);
+        const [delegationPda] = await getDelegationPDA(gateway, delegator, this.garProgram);
+        return getCompoundDelegationRewardsInstruction({ gateway: gatewayPda, delegation: delegationPda, delegator }, { programAddress: this.garProgram });
+    }
+    // =========================================
     // Epoch cranking (ario-gar) — permissionless
     // =========================================
     /**
@@ -2477,6 +2658,9 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         const batchSize = Math.min(opts.batchSize ?? MAX_LIFECYCLE_BATCH, MAX_LIFECYCLE_BATCH);
         const enableClose = opts.enableClose ?? true;
         const retention = opts.epochRetention ?? 7;
+        const enableCompound = opts.enableCompound ?? true;
+        const compoundMinPending = opts.compoundMinPendingRewards ?? 0;
+        const enableDemandFactorRoll = opts.enableDemandFactorRoll ?? true;
         const now = opts.now ?? Math.floor(Date.now() / 1000);
         const settings = await this.getEpochSettingsFull();
         if (!settings.enabled)
@@ -2561,6 +2745,22 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 return { action: 'close', epochIndex: closeTarget, txId: id };
             }
         }
+        // Lazy-state maintenance — lower urgency than the lifecycle, reached only
+        // once the live epoch is fully distributed (rewardsDistributed === 1 here).
+        // Compound FIRST so delegated stake reflects the just-distributed rewards
+        // before the next epoch's tally weights it; then roll the demand factor if
+        // its period elapsed. Both are permissionless + idempotent, and run BEFORE
+        // creating the next epoch so the compounded stake is in place for its tally.
+        if (enableCompound) {
+            const compounded = await this.maybeCompoundStep(compoundMinPending);
+            if (compounded)
+                return compounded;
+        }
+        if (enableDemandFactorRoll) {
+            const rolled = await this.maybeRollDemandFactorStep(now);
+            if (rolled)
+                return rolled;
+        }
         // Current epoch fully processed — create the next once its start arrives.
         if (now >= nextEpochStart) {
             const { id } = await this.createEpoch();
@@ -2568,6 +2768,61 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         }
         return { action: 'idle', reason: 'epoch_complete' };
     }
+    /**
+     * One compound batch over delegations with pending rewards (≤
+     * {@link MAX_COMPOUND_BATCH} per tx), or `null` when none are due. Settling
+     * is idempotent, so this converges over a few crank steps then no-ops until
+     * the next epoch's distribution advances the accumulator again.
+     */
+    async maybeCompoundStep(minPendingRewards) {
+        const pending = await this.getDelegationsToCompound({ minPendingRewards });
+        if (pending.length === 0)
+            return null;
+        const batch = pending.slice(0, MAX_COMPOUND_BATCH).map((p) => ({
+            gateway: p.gatewayAddress,
+            delegator: p.delegatorAddress,
+        }));
+        const { id } = await this.compoundDelegationRewardsBatch(batch);
+        return {
+            action: 'compound',
+            txId: id,
+            progress: { index: batch.length, total: pending.length },
+        };
+    }
+    /**
+     * Roll the demand factor forward if its (wall-clock) period elapsed since the
+     * last stored roll, else `null`. Mirrors the on-chain period math; the roll
+     * itself is idempotent.
+     */
+    async maybeRollDemandFactorStep(now) {
+        const state = await this.getDemandFactorPeriodState();
+        if (!state)
+            return null;
+        const elapsed = now - state.periodZeroStartTimestamp;
+        const periodForNow = elapsed < 0 ? 1 : Math.floor(elapsed / DEMAND_FACTOR_PERIOD_SECONDS) + 1;
+        if (periodForNow <= state.currentPeriod)
+            return null; // same period — no-op
+        const { id } = await this.updateDemandFactor();
+        return { action: 'update_demand_factor', txId: id };
+    }
+    /**
+     * The DemandFactor account's stored period + period-zero start (seconds) —
+     * the gate for {@link maybeRollDemandFactorStep}. `null` if the account
+     * doesn't exist (pre-genesis).
+     */
+    async getDemandFactorPeriodState() {
+        const [pda] = await getDemandFactorPDA(this.arnsProgram);
+        const account = await fetchEncodedAccount(this.rpc, pda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return null;
+        const df = deserializeDemandFactor(Buffer.from(account.data));
+        return {
+            currentPeriod: df.currentPeriod,
+            periodZeroStartTimestamp: df.periodZeroStartTimestamp,
+        };
+    }
     /**
      * Read the raw epoch account data for cranker state inspection.
      * Returns null if the epoch account doesn't exist yet.

package/lib/esm/solana/rpc-circuit-breaker.js

@@ -47,6 +47,121 @@ const logger = new Logger({ level: 'error' });
 const DEFAULT_MAINNET_RPC = 'https://api.mainnet-beta.solana.com';
 const DEFAULT_DEVNET_RPC = 'https://api.devnet.solana.com';
 // ---------------------------------------------------------------------------
+// Adaptive rate gate (token bucket + cooldown)
+// ---------------------------------------------------------------------------
+/** Default ceiling when `maxRequestsPerSecond` is not provided. */
+const DEFAULT_MAX_RPS = 10;
+/** Multiply the current rate by this on a 429 with no usable header. */
+const AIMD_DECREASE = 0.5;
+/** Never throttle below this many requests/second. */
+const MIN_RATE = 1;
+/** Consecutive successes before nudging the rate up by 1 (additive recovery). */
+const RECOVERY_SUCCESSES = 20;
+/** Fraction of a provider-advertised limit to actually use (safety margin). */
+const RATE_SAFETY_FACTOR = 0.9;
+/** Cooldown applied on a 429 that carries no `Retry-After`. */
+const DEFAULT_COOLDOWN_MS = 1_000;
+/**
+ * Token-bucket throttle whose rate can be retuned at runtime and which can be
+ * paused on demand. Tokens refill continuously at the current rate, capped at
+ * one second's worth (the burst allowance); waiters are released FIFO.
+ */
+function createRateGate(initialRate) {
+    let rate = Math.max(MIN_RATE, initialRate);
+    let capacity = Math.max(1, rate);
+    let tokens = capacity;
+    let lastRefill = Date.now();
+    let pausedUntil = 0;
+    const queue = [];
+    let timer = null;
+    const schedule = (ms) => {
+        if (timer !== null)
+            return;
+        timer = setTimeout(() => {
+            timer = null;
+            pump();
+        }, Math.max(ms, 1));
+    };
+    const refill = () => {
+        const now = Date.now();
+        const elapsed = (now - lastRefill) / 1000;
+        if (elapsed > 0) {
+            tokens = Math.min(capacity, tokens + elapsed * rate);
+            lastRefill = now;
+        }
+    };
+    const pump = () => {
+        const now = Date.now();
+        if (pausedUntil > now) {
+            schedule(pausedUntil - now);
+            return;
+        }
+        refill();
+        while (tokens >= 1) {
+            const release = queue.shift();
+            if (!release)
+                break;
+            tokens -= 1;
+            release();
+        }
+        if (queue.length > 0) {
+            // Wake when the next whole token will have accrued.
+            schedule(Math.ceil(((1 - tokens) / rate) * 1000));
+        }
+    };
+    return {
+        acquire: () => new Promise((resolve) => {
+            queue.push(resolve);
+            pump();
+        }),
+        setRate: (ratePerSecond) => {
+            rate = Math.max(MIN_RATE, ratePerSecond);
+            capacity = Math.max(1, rate);
+            tokens = Math.min(tokens, capacity);
+            lastRefill = Date.now();
+            pump();
+        },
+        pauseFor: (ms) => {
+            const until = Date.now() + Math.max(0, ms);
+            if (until > pausedUntil)
+                pausedUntil = until;
+            schedule(ms);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// 429 / rate-limit header parsing
+// ---------------------------------------------------------------------------
+/**
+ * If `err` is a transport HTTP 429, return its response `Headers`; else null.
+ * Duck-typed against the `@solana/errors` HTTP-error context
+ * (`{ statusCode, headers }`) so we avoid a hard dependency on the error code.
+ */
+function http429Headers(err) {
+    const ctx = err
+        ?.context;
+    if (ctx?.statusCode === 429 && ctx.headers instanceof Headers) {
+        return ctx.headers;
+    }
+    return null;
+}
+/** Parse `Retry-After` (delta-seconds or HTTP-date) into ms, or null. */
+function parseRetryAfterMs(headers) {
+    const v = headers.get('retry-after');
+    if (v === null || v === '')
+        return null;
+    const secs = Number(v);
+    if (Number.isFinite(secs))
+        return Math.max(0, secs * 1000);
+    const when = Date.parse(v);
+    return Number.isNaN(when) ? null : Math.max(0, when - Date.now());
+}
+/** Provider-advertised requests/second limit (`x-ratelimit-rps-limit`), or null. */
+function parseRpsLimit(headers) {
+    const v = Number(headers.get('x-ratelimit-rps-limit'));
+    return Number.isFinite(v) && v > 0 ? v : null;
+}
+// ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
 /**
@@ -58,11 +173,51 @@ const DEFAULT_DEVNET_RPC = 'https://api.devnet.solana.com';
 export function createCircuitBreakerRpc({ primaryUrl, fallbackUrl, circuitBreakerOptions: opts = {}, }) {
     const primaryTransport = createDefaultRpcTransport({ url: primaryUrl });
     const fallbackTransport = createDefaultRpcTransport({ url: fallbackUrl });
+    // Throttling is always on. `maxRequestsPerSecond` is the *ceiling*: every
+    // request flows through an adaptive token bucket that backs off on HTTP 429
+    // (honoring `Retry-After` and `x-ratelimit-rps-limit` when present, AIMD
+    // otherwise) and recovers back toward the ceiling on sustained success.
+    const ceilingRate = opts.maxRequestsPerSecond !== undefined && opts.maxRequestsPerSecond > 0
+        ? opts.maxRequestsPerSecond
+        : DEFAULT_MAX_RPS;
+    const gate = createRateGate(ceilingRate);
+    let currentRate = ceilingRate;
+    let successStreak = 0;
+    const onError = (err) => {
+        const headers = http429Headers(err);
+        if (!headers)
+            return; // only adapt to rate-limit (429) failures
+        successStreak = 0;
+        const advertised = parseRpsLimit(headers);
+        const next = advertised !== null
+            ? Math.min(ceilingRate, Math.max(MIN_RATE, advertised * RATE_SAFETY_FACTOR))
+            : Math.max(MIN_RATE, currentRate * AIMD_DECREASE);
+        if (next !== currentRate) {
+            currentRate = next;
+            gate.setRate(currentRate);
+        }
+        const retryAfter = parseRetryAfterMs(headers);
+        gate.pauseFor(retryAfter ?? DEFAULT_COOLDOWN_MS);
+        logger.warn(`[rpc-circuit-breaker] 429 — throttling to ${currentRate.toFixed(1)} req/s` +
+            `, cooling down ${retryAfter ?? DEFAULT_COOLDOWN_MS}ms`);
+    };
+    const onSuccess = () => {
+        if (currentRate >= ceilingRate)
+            return;
+        if (++successStreak >= RECOVERY_SUCCESSES) {
+            successStreak = 0;
+            currentRate = Math.min(ceilingRate, currentRate + 1);
+            gate.setRate(currentRate);
+        }
+    };
     const breaker = new CircuitBreaker((request) => primaryTransport(request), {
         timeout: opts.timeout ?? 10_000,
         errorThresholdPercentage: opts.errorThresholdPercentage ?? 25,
         resetTimeout: opts.resetTimeout ?? 60_000,
         volumeThreshold: opts.volumeThreshold ?? 3,
+        ...(opts.maxConcurrent !== undefined && opts.maxConcurrent > 0
+            ? { capacity: opts.maxConcurrent }
+            : {}),
     });
     breaker.fallback((request) => fallbackTransport(request));
     breaker.on('open', () => {
@@ -74,7 +229,20 @@ export function createCircuitBreakerRpc({ primaryUrl, fallbackUrl, circuitBreake
     breaker.on('close', () => {
         logger.info('[rpc-circuit-breaker] circuit CLOSED — primary RPC recovered');
     });
-    const transport = ((request) => breaker.fire(request));
+    // Adapt the rate to the *primary's* health via opossum's events: `failure`
+    // fires whenever the primary call rejects (a 429 included) even when the
+    // fallback then masks it by resolving `fire()`, and `success` fires on a
+    // healthy primary call. A plain try/catch around `fire()` would miss the
+    // fallback-masked 429s entirely.
+    breaker.on('failure', (err) => onError(err));
+    breaker.on('success', () => onSuccess());
+    const transport = (async (request) => {
+        // Throttle entry to the breaker so we stay under the provider's rate
+        // limit; the queue wait sits outside `fire`, so opossum's per-request
+        // timeout only measures the actual transport call.
+        await gate.acquire();
+        return breaker.fire(request);
+    });
     return createSolanaRpcFromTransport(transport);
 }
 /**

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.32';
+export const version = '4.0.0-solana.34';

package/lib/types/solana/delegation-math.d.ts

@@ -18,3 +18,28 @@ export declare function computeLiveDelegationBalance({ delegatedStake, rewardDeb
     rewardDebt: bigint;
     cumulativeRewardPerToken: bigint;
 }): number;
+/**
+ * Select the delegations worth compounding, from decoded delegations + a map
+ * of their gateways' reward accumulators. Pure (no I/O) so it's unit-testable
+ * independently of RPC; `SolanaARIOReadable.getDelegationsToCompound` is just
+ * fetch+decode wrapped around this.
+ *
+ * A delegation is included when its pending reward (live balance − settled
+ * principal) exceeds `minPendingRewards`, EXCEPT when its gateway is `leaving`
+ * (those settle via `claim_delegate_from_leaving_gateway`, not compounding) or
+ * its gateway is missing/unreadable. Compounding sub-threshold dust only
+ * advances `reward_debt` for no balance gain, so it's filtered out.
+ */
+export declare function selectCompoundableDelegations(delegations: Array<{
+    gateway: string;
+    delegator: string;
+    delegatedStake: number;
+    rewardDebt: bigint;
+}>, gatewaysByOperator: Map<string, {
+    cumulativeRewardPerToken: bigint;
+    status: string;
+}>, minPendingRewards?: number): Array<{
+    gatewayAddress: string;
+    delegatorAddress: string;
+    pendingRewards: number;
+}>;

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

@@ -287,6 +287,26 @@ export declare class SolanaARIOReadable {
     }): Promise<RedelegationFeeInfo>;
     getGatewayRegistrySettings(): Promise<GatewayRegistrySettings>;
     getAllDelegates(params?: PaginationParams<AllDelegates>): Promise<PaginationResult<AllDelegates>>;
+    /**
+     * Enumerate every delegation that has pending (unsettled) rewards — the work
+     * list for the permissionless `compound_delegation_rewards` crank. Pending is
+     * computed from the gateway's reward-per-share accumulator (mirrors
+     * {@link computeLiveDelegationBalance}); the crank only changes balances, so
+     * rewards already accrue correctly without it.
+     *
+     * Skips delegations whose gateway is `Leaving` (those settle through
+     * `claim_delegate_from_leaving_gateway`, not compounding) and any below
+     * `minPendingRewards` — compounding sub-threshold dust just advances
+     * `reward_debt` for no balance gain. Feed the result, chunked, to
+     * `SolanaARIOWriteable.compoundDelegationRewardsBatch`.
+     */
+    getDelegationsToCompound(params?: {
+        minPendingRewards?: number;
+    }): Promise<Array<{
+        gatewayAddress: string;
+        delegatorAddress: string;
+        pendingRewards: number;
+    }>>;
     getAllGatewayVaults(params?: PaginationParams<AllGatewayVaults>): Promise<PaginationResult<AllGatewayVaults>>;
     /**
      * Enumerate ArnsRecord PDAs whose lease has fully expired

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

@@ -122,7 +122,7 @@ export declare function buildObservationBitmap(registryAddresses: string[], fail
  */
 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';
+export type CrankAction = 'create' | 'tally' | 'prescribe' | 'distribute' | 'compound' | 'update_demand_factor' | 'close' | 'idle';
 /** Options for {@link SolanaARIOWriteable.crankEpochStep}. */
 export interface CrankEpochStepOptions {
     /** Gateways per tally/distribute batch. Default 30. */
@@ -137,6 +137,27 @@ export interface CrankEpochStepOptions {
     enableClose?: boolean;
     /** Epochs of retention before an epoch may be closed (GAR-006). Default 7. */
     epochRetention?: number;
+    /**
+     * Compound pending delegate rewards (settle the reward-per-share accumulator
+     * into delegated stake) once the live epoch is fully distributed, so the next
+     * epoch's tally weights the compounded stake. Default true. The delegate
+     * rewards are correct in the accumulator regardless — this only materializes
+     * them on-chain. Each step compounds one batch; runs only in the otherwise-
+     * idle tail (never during tally/distribute).
+     */
+    enableCompound?: boolean;
+    /**
+     * Skip compounding delegations whose pending reward is at/below this (mARIO).
+     * Avoids dust compounds that only advance `reward_debt`. Default 0.
+     */
+    compoundMinPendingRewards?: number;
+    /**
+     * Roll the demand factor forward when its (wall-clock) period has elapsed.
+     * Idempotent — only sends a tx when the stored period is behind. Pricing is
+     * always lazily correct without this; it keeps the STORED factor (and reads
+     * between buys) current. Default true. Runs only in the idle tail.
+     */
+    enableDemandFactorRoll?: boolean;
     /** Unix seconds; defaults to the wall clock. Injectable for testing. */
     now?: number;
 }
@@ -501,6 +522,19 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
         years?: number;
         processId: string;
     } & Partial<ArNSPurchaseParams>, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Pick a single stake-derived funding source that can cover a returned-name
+     * purchase, for the single-source `buy_returned_name_from_*` paths.
+     *
+     * Returned-name prices decay per slot, so the multi-source funding plan
+     * (which pre-commits exact amounts) can't match the execution-time cost. The
+     * single-source paths carry no amount — the program draws the live cost — so
+     * we only need to pick ONE source with enough stake. We size the pick against
+     * the premium-inclusive estimate (an upper bound, since the price only falls
+     * from now) and choose the largest matching source. Returns `null` when no
+     * single source covers the estimate.
+     */
+    private _autoPickReturnedNameStakeSource;
     /** Reassign an ArNS name to a different ANT. */
     reassignName(params: {
         name: string;
@@ -510,6 +544,46 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     releaseName(params: {
         name: string;
     }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Roll the demand factor forward to the current period. Permissionless and
+     * idempotent — a no-op within the same period. Pricing already rolls the
+     * factor inline on every buy/extend, so this only refreshes the STORED
+     * factor that `getDemandFactor` and between-buy price previews read; a
+     * periodic crank (~once per 24h `PERIOD_LENGTH_SECONDS`) keeps it current.
+     */
+    updateDemandFactor(_options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Materialize a single delegate's pending rewards into their delegated
+     * stake by settling the gateway's reward-per-share accumulator.
+     * Permissionless — there is no signer beyond the fee payer; `delegator` is
+     * only a PDA-derivation seed. Rewards always accrue correctly in the
+     * accumulator regardless of this call; compounding makes the on-chain
+     * `delegatedStake` reflect them (and earn compound interest in the next
+     * epoch's weighting). Idempotent — a no-op once already settled.
+     */
+    compoundDelegationRewards(params: {
+        gateway: string;
+        delegator: string;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Compound many delegates' rewards in a SINGLE transaction — one
+     * `compound_delegation_rewards` instruction per entry. Idempotent and
+     * permissionless, so partial batches are safe to retry. Keep each batch
+     * within the per-tx account/CU budget; grouping entries that share a gateway
+     * lowers the unique-account count (the gateway account is reused across
+     * instructions). Typical cranker usage: enumerate with
+     * `SolanaARIOReadable.getDelegationsToCompound`, chunk, then call this.
+     */
+    compoundDelegationRewardsBatch(delegations: Array<{
+        gateway: string;
+        delegator: string;
+    }>, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Build a single `compound_delegation_rewards` instruction (shared by the
+     * single + batch methods). PDAs are derived under the configured gar program
+     * so the program-id override always targets the right cluster.
+     */
+    private buildCompoundDelegationRewardsInstruction;
     /**
      * Create a new epoch. Permissionless — anyone can call when the next
      * epoch's start time has arrived.
@@ -640,6 +714,28 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      * internally-handled error is the prescribe `InvalidGatewayAccount` retry.
      */
     crankEpochStep(opts?: CrankEpochStepOptions): Promise<CrankEpochStepResult>;
+    /**
+     * One compound batch over delegations with pending rewards (≤
+     * {@link MAX_COMPOUND_BATCH} per tx), or `null` when none are due. Settling
+     * is idempotent, so this converges over a few crank steps then no-ops until
+     * the next epoch's distribution advances the accumulator again.
+     */
+    private maybeCompoundStep;
+    /**
+     * Roll the demand factor forward if its (wall-clock) period elapsed since the
+     * last stored roll, else `null`. Mirrors the on-chain period math; the roll
+     * itself is idempotent.
+     */
+    private maybeRollDemandFactorStep;
+    /**
+     * The DemandFactor account's stored period + period-zero start (seconds) —
+     * the gate for {@link maybeRollDemandFactorStep}. `null` if the account
+     * doesn't exist (pre-genesis).
+     */
+    getDemandFactorPeriodState(): Promise<{
+        currentPeriod: number;
+        periodZeroStartTimestamp: number;
+    } | null>;
     /**
      * Read the raw epoch account data for cranker state inspection.
      * Returns null if the epoch account doesn't exist yet.

package/lib/types/solana/rpc-circuit-breaker.d.ts

@@ -24,6 +24,35 @@ export interface CircuitBreakerRpcOptions {
      * @default 3
      */
     volumeThreshold?: number;
+    /**
+     * Ceiling for requests allowed through per second. Implemented as an
+     * adaptive token bucket *in front of* the breaker: excess requests are
+     * queued (FIFO) until a token frees, smoothing bursts so you stay under a
+     * provider's rate limit (avoids HTTP 429 / Solana error #8100002).
+     *
+     * The bucket auto-tunes on 429s: it honors `Retry-After`, drops to
+     * `x-ratelimit-rps-limit` when the provider advertises one (public Solana
+     * RPC does; QuickNode generally does not), otherwise halves the rate
+     * (AIMD). It recovers back up toward this ceiling on sustained success.
+     *
+     * The queue wait happens *before* `breaker.fire`, so it does NOT count
+     * against {@link CircuitBreakerRpcOptions.timeout}.
+     *
+     * Throttling is always on; omitting this (or passing `<= 0`) uses the
+     * {@link DEFAULT_MAX_RPS} default. To effectively remove the limit, pass a
+     * very large number.
+     * @default 10
+     */
+    maxRequestsPerSecond?: number;
+    /**
+     * Maximum number of concurrent in-flight requests (opossum `capacity`
+     * semaphore). Unlike {@link CircuitBreakerRpcOptions.maxRequestsPerSecond},
+     * excess requests are **rejected immediately** rather than queued — this is
+     * concurrency control, not a rate limit. For avoiding 429s you usually want
+     * `maxRequestsPerSecond` instead.
+     * @default undefined (unlimited)
+     */
+    maxConcurrent?: number;
 }
 export interface CircuitBreakerRpcConfig {
     /** URL for the primary (preferred) RPC endpoint. */

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.31";
+export declare const version = "4.0.0-solana.33";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.0.0-solana.32",
+  "version": "4.0.0-solana.34",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"