proof-of-take-sdk 2.0.0 → 2.1.0

package/dist/optimistic/index.d.ts

@@ -4,4 +4,4 @@
  * This module contains all optimistic update logic separated from instruction building.
  * Each function mirrors the on-chain logic to predict state changes before confirmation.
  */
-export { getCurrentTimestamp, createEmptyUserStats, initializeUserStats, updateUserStatsForMiztakeCreation, updateMiztakeStatisticsForCreation, initializeUserWindowParticipation, initializeRewardWindow, updateMiztakeForSeasonUse, initializeSeasonMembership, updateSeasonForJoin, updateWindowForConfirmation, updateParticipationForConfirmation, updateMembershipForConfirmation, updateSeasonForConfirmation, updateWindowForFinalization, updateParticipationForClaim, updateMembershipForClaim, initializeReferralPenaltyClaim, calculateWithdrawalAmount, updateSeasonSettingsForPauseToggle, updateSeasonSettingsForAdminUpdate, } from "../utils/accountUpdates";
+export { getCurrentTimestamp, expectedToBeLazyInitialized, createEmptyUserStats, initializeUserStats, updateUserStatsForMiztakeCreation, updateMiztakeStatisticsForCreation, initializeUserWindowParticipation, initializeRewardWindow, updateMiztakeForSeasonUse, initializeSeasonMembership, updateSeasonForJoin, updateWindowForConfirmation, updateParticipationForConfirmation, updateMembershipForConfirmation, updateSeasonForConfirmation, updateWindowForFinalization, updateParticipationForClaim, updateMembershipForClaim, initializeReferralPenaltyClaim, calculateWithdrawalAmount, updateSeasonSettingsForPauseToggle, updateSeasonSettingsForAdminUpdate, } from "../utils/accountUpdates";

package/dist/optimistic/index.js

@@ -6,11 +6,12 @@
  * Each function mirrors the on-chain logic to predict state changes before confirmation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.updateSeasonSettingsForAdminUpdate = exports.updateSeasonSettingsForPauseToggle = exports.calculateWithdrawalAmount = exports.initializeReferralPenaltyClaim = exports.updateMembershipForClaim = exports.updateParticipationForClaim = exports.updateWindowForFinalization = exports.updateSeasonForConfirmation = exports.updateMembershipForConfirmation = exports.updateParticipationForConfirmation = exports.updateWindowForConfirmation = exports.updateSeasonForJoin = exports.initializeSeasonMembership = exports.updateMiztakeForSeasonUse = exports.initializeRewardWindow = exports.initializeUserWindowParticipation = exports.updateMiztakeStatisticsForCreation = exports.updateUserStatsForMiztakeCreation = exports.initializeUserStats = exports.createEmptyUserStats = exports.getCurrentTimestamp = void 0;
+exports.updateSeasonSettingsForAdminUpdate = exports.updateSeasonSettingsForPauseToggle = exports.calculateWithdrawalAmount = exports.initializeReferralPenaltyClaim = exports.updateMembershipForClaim = exports.updateParticipationForClaim = exports.updateWindowForFinalization = exports.updateSeasonForConfirmation = exports.updateMembershipForConfirmation = exports.updateParticipationForConfirmation = exports.updateWindowForConfirmation = exports.updateSeasonForJoin = exports.initializeSeasonMembership = exports.updateMiztakeForSeasonUse = exports.initializeRewardWindow = exports.initializeUserWindowParticipation = exports.updateMiztakeStatisticsForCreation = exports.updateUserStatsForMiztakeCreation = exports.initializeUserStats = exports.createEmptyUserStats = exports.expectedToBeLazyInitialized = exports.getCurrentTimestamp = void 0;
 // Re-export all optimistic update functions from accountUpdates
 // This provides a cleaner separation of concerns
 var accountUpdates_1 = require("../utils/accountUpdates");
 Object.defineProperty(exports, "getCurrentTimestamp", { enumerable: true, get: function () { return accountUpdates_1.getCurrentTimestamp; } });
+Object.defineProperty(exports, "expectedToBeLazyInitialized", { enumerable: true, get: function () { return accountUpdates_1.expectedToBeLazyInitialized; } });
 Object.defineProperty(exports, "createEmptyUserStats", { enumerable: true, get: function () { return accountUpdates_1.createEmptyUserStats; } });
 Object.defineProperty(exports, "initializeUserStats", { enumerable: true, get: function () { return accountUpdates_1.initializeUserStats; } });
 Object.defineProperty(exports, "updateUserStatsForMiztakeCreation", { enumerable: true, get: function () { return accountUpdates_1.updateUserStatsForMiztakeCreation; } });

package/dist/utils/accountUpdates.d.ts

@@ -13,6 +13,34 @@ import { Miztake, UserStats, MiztakeStatistics, SeasonSettings, Season, SeasonMe
  * @returns Current Unix timestamp in seconds
  */
 export declare function getCurrentTimestamp(now?: BN): BN;
+/**
+ * Build the Season account object that is expected to be created by on-chain lazy initialization.
+ *
+ * This is a PURE helper (no RPC). It mirrors `season_helpers::initialize_season`:
+ * - `season_state = Active`
+ * - `started_at = current_time`
+ * - `ends_at = current_time + season_duration`
+ * - all counters and totals initialized to zero
+ * - schedule `eligible_stake_per_window` initialized to 21 zeros
+ * - PDA bump derived locally from seeds (no RPC)
+ *
+ * IMPORTANT:
+ * To match on-chain state exactly, you must supply the same `startedAt` that the transaction
+ * will observe on-chain (i.e. `Clock::get()?.unix_timestamp` at execution time) and the same
+ * season duration as stored in SeasonSettings at that moment. If you don't have settings locally,
+ * we fall back to the canonical defaults (7 days, 21 windows).
+ */
+export declare function expectedToBeLazyInitialized(params: {
+    /** Season number to initialize. */
+    seasonNumber: BN;
+    /** Unix timestamp in seconds used as `started_at` (i64 on-chain). */
+    startedAt: BN;
+    /**
+     * Optional settings snapshot (recommended) to compute `endsAt` and `totalWindows`.
+     * Providing this avoids drift if settings ever change.
+     */
+    seasonSettings?: Pick<SeasonSettings, "seasonDuration" | "totalWindowsPerSeason" | "lastSeasonEndsAt">;
+}): Season;
 /**
  * Create an empty/initialized UserStats object
  * Used when initializing a new user stats account

package/dist/utils/accountUpdates.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCurrentTimestamp = getCurrentTimestamp;
+exports.expectedToBeLazyInitialized = expectedToBeLazyInitialized;
 exports.createEmptyUserStats = createEmptyUserStats;
 exports.initializeUserStats = initializeUserStats;
 exports.updateUserStatsForMiztakeCreation = updateUserStatsForMiztakeCreation;
@@ -42,6 +43,55 @@ function getCurrentTimestamp(now) {
         return now;
     return new anchor_1.BN(Math.floor(Date.now() / 1000)); // Convert JS milliseconds → seconds
 }
+/**
+ * Build the Season account object that is expected to be created by on-chain lazy initialization.
+ *
+ * This is a PURE helper (no RPC). It mirrors `season_helpers::initialize_season`:
+ * - `season_state = Active`
+ * - `started_at = current_time`
+ * - `ends_at = current_time + season_duration`
+ * - all counters and totals initialized to zero
+ * - schedule `eligible_stake_per_window` initialized to 21 zeros
+ * - PDA bump derived locally from seeds (no RPC)
+ *
+ * IMPORTANT:
+ * To match on-chain state exactly, you must supply the same `startedAt` that the transaction
+ * will observe on-chain (i.e. `Clock::get()?.unix_timestamp` at execution time) and the same
+ * season duration as stored in SeasonSettings at that moment. If you don't have settings locally,
+ * we fall back to the canonical defaults (7 days, 21 windows).
+ */
+function expectedToBeLazyInitialized(params) {
+    const seasonDuration = params.seasonSettings?.seasonDuration ?? new anchor_1.BN(604800); // 7 days
+    const totalWindows = params.seasonSettings?.totalWindowsPerSeason ?? 21;
+    // Derive bump seed locally (mirrors Anchor ctx.bumps.season).
+    const [, bump] = (0, pdas_1.getSeasonPda)(params.seasonNumber);
+    const lastSeasonEndsAt = params.seasonSettings?.lastSeasonEndsAt ?? new anchor_1.BN(0);
+    // If lastSeasonEndsAt is 0 (first season), use params.startedAt.
+    // Otherwise, use lastSeasonEndsAt exactly (gapless).
+    // Note: We ignore params.startedAt in the gapless case to match on-chain logic,
+    // but in practice the caller should ideally pass the correct gapless time.
+    const effectiveStartedAt = lastSeasonEndsAt.isZero()
+        ? params.startedAt
+        : lastSeasonEndsAt;
+    return {
+        seasonNumber: params.seasonNumber,
+        seasonState: types_1.SeasonState.Active,
+        startedAt: effectiveStartedAt,
+        endsAt: effectiveStartedAt.add(seasonDuration),
+        totalWindows,
+        totalMembers: new anchor_1.BN(0),
+        copperMembersCount: new anchor_1.BN(0),
+        silverMembersCount: new anchor_1.BN(0),
+        goldMembersCount: new anchor_1.BN(0),
+        platinumMembersCount: new anchor_1.BN(0),
+        mithrilMembersCount: new anchor_1.BN(0),
+        eligibleStakePerWindow: Array.from({ length: 21 }, () => new anchor_1.BN(0)),
+        totalDepositsHeld: new anchor_1.BN(0),
+        totalSuccessfulPosts: new anchor_1.BN(0),
+        totalPenaltiesCollected: new anchor_1.BN(0),
+        bump,
+    };
+}
 /**
  * Create an empty/initialized UserStats object
  * Used when initializing a new user stats account

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proof-of-take-sdk",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "TypeScript SDK for Proof of Take Solana program",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",