@ar.io/sdk 4.0.0-solana.39 → 4.0.0-solana.40

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

@@ -1212,6 +1212,36 @@ export class SolanaARIOReadable {
         }
         return { failureSummaries, reports };
     }
+    /**
+     * Observer pubkeys that have an OPEN Observation PDA for `epochIndex`. Lean —
+     * reads only the Observation accounts (no gateway-registry decode like
+     * {@link getObservations}). Used by the crank to close observations before
+     * `close_epoch`, whose `observations_closed == observations_submitted`
+     * precondition would otherwise wedge epoch progression.
+     */
+    async getEpochObservers(epochIndex) {
+        const epochIndexBuf = Buffer.alloc(8);
+        epochIndexBuf.writeBigUInt64LE(BigInt(epochIndex));
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, OBSERVATION_DISCRIMINATOR, [
+            {
+                memcmp: {
+                    offset: 8n,
+                    bytes: bs58.encode(epochIndexBuf),
+                    encoding: 'base58',
+                },
+            },
+        ]);
+        const observers = [];
+        for (const { data } of accounts) {
+            try {
+                observers.push(address(deserializeObservation(data).observer));
+            }
+            catch {
+                // skip malformed
+            }
+        }
+        return observers;
+    }
     async getDistributions(epoch) {
         const epochIndex = await this.resolveEpochIndex(epoch);
         const epochData = await this.fetchEpoch(epochIndex);

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

@@ -233,6 +233,9 @@ export function encodeReportTxId(reportTxId) {
  * the per-tx account/1232-byte budget even when none share a gateway.
  */
 const MAX_COMPOUND_BATCH = 12;
+/** Observation PDAs closed per tx before close_epoch (each ix carries Epoch +
+ *  Observation + payer + system accounts — keep well under the tx account cap). */
+const MAX_CLOSE_OBSERVATION_BATCH = 8;
 /** Demand-factor period length (seconds) — mirrors `PERIOD_LENGTH_SECONDS` in ario-arns. */
 const DEMAND_FACTOR_PERIOD_SECONDS = 86_400;
 /**
@@ -2758,12 +2761,47 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             };
         }
         // Close a fully-distributed epoch past retention (GAR-006).
+        //
+        // CRITICAL: this is cleanup of OLD epochs and must NEVER block creation of
+        // NEW ones. `close_epoch` reverts with EpochObservationsNotClosed until the
+        // epoch's Observation PDAs are closed (observations_closed ==
+        // observations_submitted), so we close those FIRST. The whole branch is
+        // wrapped so any failure falls through to create-next instead of throwing
+        // out of crankEpochStep — otherwise a single un-closeable epoch wedges epoch
+        // progression network-wide (every operator's crank hits the same wall).
         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 };
+            try {
+                const old = await this.getEpochRaw(closeTarget);
+                if (old && old.rewardsDistributed === 1) {
+                    if (old.observationsSubmitted > old.observationsClosed) {
+                        // Open observations remain — close a batch before close_epoch.
+                        const observers = await this.getEpochObservers(closeTarget);
+                        if (observers.length > 0) {
+                            const batch = observers.slice(0, MAX_CLOSE_OBSERVATION_BATCH);
+                            const { id } = await this.closeObservations({
+                                epochIndex: closeTarget,
+                                observers: batch,
+                            });
+                            return {
+                                action: 'close_observation',
+                                epochIndex: closeTarget,
+                                txId: id,
+                                progress: { index: batch.length, total: observers.length },
+                            };
+                        }
+                        // Counter says open but no Observation PDA exists (orphaned counter):
+                        // can't close it, so don't attempt close_epoch (it would revert) and
+                        // don't wedge — fall through to create-next.
+                    }
+                    else {
+                        const { id } = await this.closeEpoch({ epochIndex: closeTarget });
+                        return { action: 'close', epochIndex: closeTarget, txId: id };
+                    }
+                }
+            }
+            catch {
+                // Best-effort cleanup — never block epoch creation. Retried next tick.
             }
         }
         // Lazy-state maintenance — lower urgency than the lifecycle, reached only
@@ -2908,10 +2946,13 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      *   [8 per_obs][8 reward_rate][8 weight_lo][8 weight_hi][32 hashchain]
      *   [4 active_gw_count][4 dist_idx][4 tally_idx]
      *   [1 observer_count][1 name_count][1 obs_submitted][1 rewards_dist]
-     *   [1 weights_tallied][1 prescriptions_done][1 bump][1 _pad1]
+     *   [1 weights_tallied][1 prescriptions_done][1 bump][1 obs_closed]
      *   [6000 failure_counts][1600 prescribed_observers]
      *   [1600 prescribed_observer_gateways][64 prescribed_names]
      *   [7 has_observed][5 _pad2]
+     *
+     * NOTE: byte +123 is `observations_closed` (NOT padding) — `close_epoch`
+     * reverts with EpochObservationsNotClosed until it equals obs_submitted.
      */
     fetchEpochRawFields(data) {
         const base = 8;
@@ -2919,15 +2960,19 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         const activeGatewayCount = data.readUInt32LE(base + 104);
         const distributionIndex = data.readUInt32LE(base + 108);
         const tallyIndex = data.readUInt32LE(base + 112);
+        const observationsSubmitted = data.readUInt8(base + 118);
         const rewardsDistributed = data.readUInt8(base + 119);
         const weightsTallied = data.readUInt8(base + 120);
         const prescriptionsDone = data.readUInt8(base + 121);
+        const observationsClosed = data.readUInt8(base + 123);
         return {
             tallyIndex,
             distributionIndex,
             weightsTallied,
             prescriptionsDone,
             rewardsDistributed,
+            observationsSubmitted,
+            observationsClosed,
             activeGatewayCount,
             endTimestamp,
         };
@@ -3091,6 +3136,29 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         const sig = await this.sendTransaction([ix]);
         return { id: sig };
     }
+    /**
+     * Close multiple Observation PDAs for one epoch in a single tx (each
+     * `close_observation` increments the parent Epoch's `observations_closed`).
+     * Permissionless; rent is refunded to the payer. Used by the crank to satisfy
+     * `close_epoch`'s `observations_closed == observations_submitted` precondition
+     * before closing a retention-aged epoch. Keep the batch small — each ix carries
+     * the Epoch + Observation + payer + system accounts.
+     */
+    async closeObservations(params, _options) {
+        if (params.observers.length === 0) {
+            throw new Error('closeObservations: observers must be non-empty');
+        }
+        const ixs = await Promise.all(params.observers.map(async (obs) => {
+            const [observationPda] = await getObservationPDA(params.epochIndex, address(obs), this.garProgram);
+            return getCloseObservationInstructionAsync({
+                observation: observationPda,
+                payer: this.signer,
+                epochIndex: BigInt(params.epochIndex),
+            }, { programAddress: this.garProgram });
+        }));
+        const sig = await this.sendTransaction(ixs);
+        return { id: sig };
+    }
     /**
      * Close an empty Delegation PDA (`amount == 0`) and refund rent to the
      * original delegator (NOT the caller — see GAR-016, prevents griefing).

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

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

@@ -253,6 +253,14 @@ export declare class SolanaARIOReadable {
     getPrescribedObservers(epoch?: EpochInput): Promise<WeightedObserver[]>;
     getPrescribedNames(epoch?: EpochInput): Promise<string[]>;
     getObservations(epoch?: EpochInput): Promise<EpochObservationData>;
+    /**
+     * Observer pubkeys that have an OPEN Observation PDA for `epochIndex`. Lean —
+     * reads only the Observation accounts (no gateway-registry decode like
+     * {@link getObservations}). Used by the crank to close observations before
+     * `close_epoch`, whose `observations_closed == observations_submitted`
+     * precondition would otherwise wedge epoch progression.
+     */
+    getEpochObservers(epochIndex: number): Promise<Address[]>;
     getDistributions(epoch?: EpochInput): Promise<EpochDistributionData>;
     getEligibleEpochRewards(epoch?: EpochInput, params?: PaginationParams<EligibleDistribution>): Promise<PaginationResult<EligibleDistribution>>;
     /**

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' | 'prune_returned_names' | 'close' | 'idle';
+export type CrankAction = 'create' | 'tally' | 'prescribe' | 'distribute' | 'compound' | 'update_demand_factor' | 'prune_returned_names' | 'close_observation' | 'close' | 'idle';
 /** Options for {@link SolanaARIOWriteable.crankEpochStep}. */
 export interface CrankEpochStepOptions {
     /** Gateways per tally/distribute batch. Default 30. */
@@ -776,6 +776,8 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
         weightsTallied: number;
         prescriptionsDone: number;
         rewardsDistributed: number;
+        observationsSubmitted: number;
+        observationsClosed: number;
         activeGatewayCount: number;
         endTimestamp: number;
     } | null>;
@@ -788,10 +790,13 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      *   [8 per_obs][8 reward_rate][8 weight_lo][8 weight_hi][32 hashchain]
      *   [4 active_gw_count][4 dist_idx][4 tally_idx]
      *   [1 observer_count][1 name_count][1 obs_submitted][1 rewards_dist]
-     *   [1 weights_tallied][1 prescriptions_done][1 bump][1 _pad1]
+     *   [1 weights_tallied][1 prescriptions_done][1 bump][1 obs_closed]
      *   [6000 failure_counts][1600 prescribed_observers]
      *   [1600 prescribed_observer_gateways][64 prescribed_names]
      *   [7 has_observed][5 _pad2]
+     *
+     * NOTE: byte +123 is `observations_closed` (NOT padding) — `close_epoch`
+     * reverts with EpochObservationsNotClosed until it equals obs_submitted.
      */
     private fetchEpochRawFields;
     /**
@@ -856,6 +861,18 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
         epochIndex: number;
         observer: string;
     }, _options?: WriteOptions): Promise<MessageResult>;
+    /**
+     * Close multiple Observation PDAs for one epoch in a single tx (each
+     * `close_observation` increments the parent Epoch's `observations_closed`).
+     * Permissionless; rent is refunded to the payer. Used by the crank to satisfy
+     * `close_epoch`'s `observations_closed == observations_submitted` precondition
+     * before closing a retention-aged epoch. Keep the batch small — each ix carries
+     * the Epoch + Observation + payer + system accounts.
+     */
+    closeObservations(params: {
+        epochIndex: number;
+        observers: string[];
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Close an empty Delegation PDA (`amount == 0`) and refund rent to the
      * original delegator (NOT the caller — see GAR-016, prevents griefing).

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

package/package.json

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