@ar.io/sdk 4.0.0-solana.37 → 4.0.0-solana.38

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

@@ -2661,6 +2661,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         const enableCompound = opts.enableCompound ?? true;
         const compoundMinPending = opts.compoundMinPendingRewards ?? 0;
         const enableDemandFactorRoll = opts.enableDemandFactorRoll ?? true;
+        const enablePrune = opts.enablePrune ?? true;
         const now = opts.now ?? Math.floor(Date.now() / 1000);
         const settings = await this.getEpochSettingsFull();
         if (!settings.enabled)
@@ -2714,9 +2715,19 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             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)
+        // Observations happen while the epoch is live. This is the dominant idle
+        // window — fold returned-name pruning in here so it isn't starved on
+        // clusters whose epochs park here (e.g. imported gateways that can't
+        // observe → distribution never advances → the post-distribution tail below
+        // is never reached).
+        if (now < epoch.endTimestamp) {
+            if (enablePrune) {
+                const pruned = await this.maybePruneReturnedNamesStep(opts, now);
+                if (pruned)
+                    return pruned;
+            }
             return { action: 'idle', reason: 'waiting_for_observations' };
+        }
         // Distribute (batched).
         if (epoch.rewardsDistributed === 0) {
             const gatewayAccounts = epoch.activeGatewayCount > 0
@@ -2761,6 +2772,11 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             if (rolled)
                 return rolled;
         }
+        if (enablePrune) {
+            const pruned = await this.maybePruneReturnedNamesStep(opts, now);
+            if (pruned)
+                return pruned;
+        }
         // Current epoch fully processed — create the next once its start arrives.
         if (now >= nextEpochStart) {
             const { id } = await this.createEpoch();
@@ -2805,6 +2821,38 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         const { id } = await this.updateDemandFactor();
         return { action: 'update_demand_factor', txId: id };
     }
+    /** Wall-clock (ms) of the last returned-name prune scan; throttles the
+     *  getProgramAccounts scan below the crank poll rate. */
+    lastReturnedNamePruneScanMs = 0;
+    /**
+     * One prune batch over ReturnedName PDAs whose 14-day auction window has
+     * elapsed (≤ {@link CrankEpochStepOptions.pruneBatchSize} per tx), or `null`
+     * when none are due / the scan is throttled. Scans the PDAs directly — it does
+     * NOT gate on `config.next_returned_names_prune_timestamp`, which is never set
+     * for imported returned names and would strand them. The contract re-checks
+     * each account's window, so a slightly-skewed client clock is safe.
+     */
+    async maybePruneReturnedNamesStep(opts, now) {
+        const scanInterval = opts.pruneScanIntervalMs ?? 60_000;
+        const wallNow = Date.now();
+        if (wallNow - this.lastReturnedNamePruneScanMs < scanInterval)
+            return null;
+        this.lastReturnedNamePruneScanMs = wallNow;
+        const expired = await this.getExpiredReturnedNames(now);
+        if (expired.length === 0)
+            return null;
+        const batchSize = opts.pruneBatchSize ?? 15;
+        const batch = expired.slice(0, batchSize).map((r) => r.pubkey);
+        const { id } = await this.pruneReturnedNames({
+            maxNames: batch.length,
+            returnedNames: batch,
+        });
+        return {
+            action: 'prune_returned_names',
+            txId: id,
+            progress: { index: batch.length, total: expired.length },
+        };
+    }
     /**
      * The DemandFactor account's stored period + period-zero start (seconds) —
      * the gate for {@link maybeRollDemandFactorStep}. `null` if the account

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

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' | 'compound' | 'update_demand_factor' | 'close' | 'idle';
+export type CrankAction = 'create' | 'tally' | 'prescribe' | 'distribute' | 'compound' | 'update_demand_factor' | 'prune_returned_names' | 'close' | 'idle';
 /** Options for {@link SolanaARIOWriteable.crankEpochStep}. */
 export interface CrankEpochStepOptions {
     /** Gateways per tally/distribute batch. Default 30. */
@@ -158,6 +158,24 @@ export interface CrankEpochStepOptions {
      * between buys) current. Default true. Runs only in the idle tail.
      */
     enableDemandFactorRoll?: boolean;
+    /**
+     * Prune expired ReturnedName PDAs (auction window elapsed) as part of the
+     * crank. Default true. Runs whenever the epoch lifecycle is otherwise idle
+     * (the live observation window AND the post-distribution tail), one batch per
+     * step. It scans the ReturnedName PDAs DIRECTLY (via getExpiredReturnedNames)
+     * and does NOT consult `config.next_returned_names_prune_timestamp` — that
+     * hint is only set for on-chain returns and is never updated for imported
+     * returned names, so trusting it strands imported auctions forever.
+     */
+    enablePrune?: boolean;
+    /** ReturnedName PDAs to prune per tx (u8, max 255). Default 15. */
+    pruneBatchSize?: number;
+    /**
+     * Minimum wall-clock gap between returned-name prune SCANS (ms). The scan is a
+     * `getProgramAccounts` over ReturnedName PDAs, so this throttles it below the
+     * crank poll rate. Default 60_000 (1 min). Set 0 to scan every step (tests).
+     */
+    pruneScanIntervalMs?: number;
     /** Unix seconds; defaults to the wall clock. Injectable for testing. */
     now?: number;
 }
@@ -727,6 +745,18 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      * itself is idempotent.
      */
     private maybeRollDemandFactorStep;
+    /** Wall-clock (ms) of the last returned-name prune scan; throttles the
+     *  getProgramAccounts scan below the crank poll rate. */
+    private lastReturnedNamePruneScanMs;
+    /**
+     * One prune batch over ReturnedName PDAs whose 14-day auction window has
+     * elapsed (≤ {@link CrankEpochStepOptions.pruneBatchSize} per tx), or `null`
+     * when none are due / the scan is throttled. Scans the PDAs directly — it does
+     * NOT gate on `config.next_returned_names_prune_timestamp`, which is never set
+     * for imported returned names and would strand them. The contract re-checks
+     * each account's window, so a slightly-skewed client clock is safe.
+     */
+    private maybePruneReturnedNamesStep;
     /**
      * The DemandFactor account's stored period + period-zero start (seconds) —
      * the gate for {@link maybeRollDemandFactorStep}. `null` if the account

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

package/package.json

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