proof-of-take-sdk 1.0.0

package/dist/types/proof_of_take.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types.d.ts

@@ -0,0 +1,232 @@
+import { PublicKey } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+/**
+ * Type definitions for Proof of Take SDK
+ */
+export type { ProofOfTake } from "./types/proof_of_take";
+export interface CreateMiztakeParams {
+    telegramId: BN;
+    telegramUsername: string;
+    perceptualHash: string;
+    averageHash: string;
+    differenceHash: string;
+    waveletHash: string;
+    shaHash: string;
+    computedAt: string;
+}
+export interface ClaimRewardParams {
+    miztakePda: PublicKey;
+    userTokenAccount: PublicKey;
+    amount: BN;
+}
+export interface DepositTokensParams {
+    amount: BN;
+    depositorTokenAccount: PublicKey;
+}
+export interface WithdrawTokensParams {
+    amount: BN;
+    adminTokenAccount: PublicKey;
+}
+export interface UpdateConfigParams {
+    newFee?: BN;
+    newFeeRecipient?: PublicKey;
+    newDefaultMaxClaimable?: BN;
+}
+export interface MiztakeStatistics {
+    totalMiztakes: BN;
+    bump: number;
+}
+export interface UserStats {
+    telegramId: BN;
+    totalNumberOfMiztakes: BN;
+    onchainFirstMiztakeAt: BN;
+    onchainLastMiztakeAt: BN;
+    bump: number;
+}
+export interface Miztake {
+    id: BN;
+    telegramId: BN;
+    telegramUsername: string;
+    perceptualHash: string;
+    averageHash: string;
+    differenceHash: string;
+    waveletHash: string;
+    shaHash: string;
+    computedAt: string;
+    creator: PublicKey;
+    userStats: PublicKey;
+    userKey: PublicKey;
+    onchainCreatedAt: BN;
+    usedInSeason: BN;
+    usedInWindow: BN;
+}
+export declare enum SeasonState {
+    Uninitialized = 0,
+    Active = 1,
+    Ended = 2
+}
+export declare enum WindowState {
+    Uninitialized = 0,
+    Active = 1,
+    Finalized = 2
+}
+/**
+ * Season deposit tier (Anchor enum representation)
+ *
+ * Note: Anchor represents enum values as an object with a single key.
+ * Example: `{ silver: {} }`
+ */
+export type SeasonDepositTier = {
+    copper: Record<string, never>;
+} | {
+    silver: Record<string, never>;
+} | {
+    gold: Record<string, never>;
+} | {
+    platinum: Record<string, never>;
+} | {
+    mithril: Record<string, never>;
+};
+export interface SeasonSettings {
+    completedSeasons: BN;
+    seasonDuration: BN;
+    windowDuration: BN;
+    totalWindowsPerSeason: number;
+    canInitializeNextSeason: boolean;
+    lastSeasonEndsAt: BN;
+    currentSeasonNumber: BN;
+    admin: PublicKey;
+    isPaused: boolean;
+    maxMembersPerSeason: BN;
+    bump: number;
+}
+export interface Season {
+    seasonNumber: BN;
+    seasonState: SeasonState;
+    startedAt: BN;
+    endsAt: BN;
+    totalWindows: number;
+    totalMembers: BN;
+    copperMembersCount: BN;
+    silverMembersCount: BN;
+    goldMembersCount: BN;
+    platinumMembersCount: BN;
+    mithrilMembersCount: BN;
+    eligibleStakePerWindow: BN[];
+    totalDepositsHeld: BN;
+    totalSuccessfulPosts: BN;
+    totalPenaltiesCollected: BN;
+    bump: number;
+}
+export interface SeasonMembership {
+    id: BN;
+    owner: PublicKey;
+    /** Optional referrer (PublicKey.default means no referrer). */
+    referrer: PublicKey;
+    seasonNumber: BN;
+    depositTier: SeasonDepositTier;
+    depositAmount: BN;
+    depositEscrowedAmount: BN;
+    joinedAt: BN;
+    joinedWindowNumber: BN;
+    successfulPostsCount: BN;
+    totalRewardsClaimed: BN;
+    totalPenaltiesPaid: BN;
+    /** Whether the user has already withdrawn their season deposit (prevents double-withdraw). */
+    depositWithdrawn: boolean;
+    isActive: boolean;
+    bump: number;
+}
+export interface RewardWindow {
+    seasonNumber: BN;
+    windowNumber: BN;
+    windowState: WindowState;
+    startedAt: BN;
+    endsAt: BN;
+    totalMembersInSeason: BN;
+    penaltyPool: BN;
+    successfulPostersCount: BN;
+    successfulStakeTotal: BN;
+    rewardPerPoster: BN;
+    isFinalized: boolean;
+    bump: number;
+}
+export interface UserWindowParticipation {
+    user: PublicKey;
+    seasonNumber: BN;
+    windowNumber: BN;
+    seasonMembershipId: BN;
+    postedSuccessfully: boolean;
+    claimedReward: boolean;
+    rewardAmount: BN;
+    miztakeId: BN;
+    bump: number;
+}
+/**
+ * Referral penalty claim record
+ *
+ * Mirrors on-chain `ReferralPenaltyClaim` account.
+ * NOTE: `claimedAt` is i64 on-chain; Anchor typically returns it as BN.
+ */
+export interface ReferralPenaltyClaim {
+    referredUser: PublicKey;
+    seasonNumber: BN;
+    windowNumber: BN;
+    seasonMembershipId: BN;
+    claimant: PublicKey;
+    amount: BN;
+    claimedAt: BN;
+    claimed: boolean;
+    bump: number;
+}
+/**
+ * View return types (Anchor `.view()` RPC return structs).
+ *
+ * These are not on-chain accounts; they are computed/returned by view instructions.
+ * All u64/i64 fields are returned as BN by Anchor.
+ */
+export interface CurrentSeasonView {
+    seasonNumber: BN;
+    startedAt: BN;
+    endsAt: BN;
+    totalWindows: number;
+    totalMembers: BN;
+    totalDepositsHeld: BN;
+    totalSuccessfulPosts: BN;
+    totalPenaltiesCollected: BN;
+    currentWindowNumber: BN;
+    windowsRemaining: BN;
+    timeRemaining: BN;
+    isActive: boolean;
+    isJoinable: boolean;
+}
+export interface SeasonMembershipStatusView {
+    owner: PublicKey;
+    seasonNumber: BN;
+    depositAmount: BN;
+    joinedAt: BN;
+    joinedWindowNumber: BN;
+    successfulPostsCount: BN;
+    totalRewardsClaimed: BN;
+    totalPenaltiesPaid: BN;
+    depositWithdrawn: boolean;
+    isActive: boolean;
+    seasonStartedAt: BN;
+    seasonEndsAt: BN;
+    seasonTotalMembers: BN;
+    currentWindowNumber: BN;
+    windowsRemaining: BN;
+}
+export interface WindowStatusView {
+    seasonNumber: BN;
+    windowNumber: BN;
+    startedAt: BN;
+    endsAt: BN;
+    totalMembersInSeason: BN;
+    successfulPostersCount: BN;
+    penaltyPool: BN;
+    rewardPerPoster: BN;
+    isFinalized: boolean;
+    isActive: boolean;
+    isEnded: boolean;
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WindowState = exports.SeasonState = void 0;
+// Season Membership State Types
+var SeasonState;
+(function (SeasonState) {
+    SeasonState[SeasonState["Uninitialized"] = 0] = "Uninitialized";
+    SeasonState[SeasonState["Active"] = 1] = "Active";
+    SeasonState[SeasonState["Ended"] = 2] = "Ended";
+})(SeasonState || (exports.SeasonState = SeasonState = {}));
+var WindowState;
+(function (WindowState) {
+    WindowState[WindowState["Uninitialized"] = 0] = "Uninitialized";
+    WindowState[WindowState["Active"] = 1] = "Active";
+    WindowState[WindowState["Finalized"] = 2] = "Finalized";
+})(WindowState || (exports.WindowState = WindowState = {}));

package/dist/utils/accountUpdates.d.ts

@@ -0,0 +1,245 @@
+import { BN } from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import { Miztake, UserStats, MiztakeStatistics, SeasonSettings, Season, SeasonMembership, RewardWindow, UserWindowParticipation, SeasonDepositTier, ReferralPenaltyClaim } from "../types";
+/**
+ * Get current Unix timestamp in SECONDS as BN
+ *
+ * Note:
+ * - Returns Unix timestamp in SECONDS (not milliseconds)
+ * - Matches Solana's Clock::unix_timestamp format
+ * - This is an approximate timestamp; the actual on-chain timestamp
+ *   will be set by the Solana runtime when the transaction is processed
+ *
+ * @returns Current Unix timestamp in seconds
+ */
+export declare function getCurrentTimestamp(now?: BN): BN;
+/**
+ * Create an empty/initialized UserStats object
+ * Used when initializing a new user stats account
+ */
+export declare function createEmptyUserStats(telegramId: BN): UserStats;
+/**
+ * Create a fully initialized UserStats account with PDA bump
+ * Mirrors the initialization logic from create_miztake.rs (lines 33-48)
+ *
+ * This function derives the PDA and returns a UserStats object exactly as it
+ * will appear on-chain after initialization.
+ *
+ * @param telegramId - Telegram ID of the user
+ * @returns Initialized UserStats object with proper bump seed
+ *
+ * @example
+ * ```typescript
+ * const userStats = initializeUserStats(new BN(123456789));
+ * // userStats is ready to be used for local state tracking
+ * // and matches exactly what will be created on-chain
+ * ```
+ */
+export declare function initializeUserStats(telegramId: BN): UserStats;
+/**
+ * Update UserStats after creating a miztake
+ * Mirrors the increment_miztakes logic from user_stats.rs
+ *
+ * @param userStats - Current user stats
+ * @param telegramId - Telegram ID for initialization check
+ * @param timestamp - Timestamp for the update in SECONDS (Unix timestamp)
+ * @returns Updated UserStats object
+ */
+export declare function updateUserStatsForMiztakeCreation(userStats: UserStats, telegramId: BN, timestamp?: BN): UserStats;
+/**
+ * Update MiztakeStatistics after creating a miztake
+ * Mirrors the increment_miztakes logic from miztake_statistics.rs
+ *
+ * @param statistics - Current miztake statistics
+ * @returns Updated MiztakeStatistics object and new miztake ID
+ *
+ * @throws Error if invalid statistics provided
+ */
+export declare function updateMiztakeStatisticsForCreation(statistics: MiztakeStatistics): {
+    statistics: MiztakeStatistics;
+    newMiztakeId: BN;
+};
+/**
+ * Initialize or update UserWindowParticipation
+ * Mirrors the logic from create_miztake.rs (lines 109-139)
+ *
+ * @param user - User's public key
+ * @param seasonNumber - Season number
+ * @param windowNumber - Window number
+ * @param seasonMembershipId - Season membership ID
+ * @param miztakeId - The miztake ID to associate
+ * @returns Initialized/Updated UserWindowParticipation object
+ */
+export declare function initializeUserWindowParticipation(user: PublicKey, seasonNumber: BN, windowNumber: BN, seasonMembershipId: BN, miztakeId: BN): UserWindowParticipation;
+/**
+ * Initialize RewardWindow
+ * Mirrors the logic from season_helpers::initialize_window
+ *
+ * @param seasonNumber - Season number
+ * @param windowNumber - Window number
+ * @param season - Current season state
+ * @param windowDuration - Duration of each window in seconds
+ * @returns Initialized RewardWindow object
+ */
+export declare function initializeRewardWindow(seasonNumber: BN, windowNumber: BN, season: Season, windowDuration: BN): RewardWindow;
+/**
+ * Update Miztake to mark it as used in a season/window
+ * Mirrors mark_as_used from miztake.rs
+ *
+ * @param miztake - Current miztake
+ * @param seasonNumber - Season number
+ * @param windowNumber - Window number
+ * @returns Updated Miztake object
+ */
+export declare function updateMiztakeForSeasonUse(miztake: Miztake, seasonNumber: BN, windowNumber: BN): Miztake;
+/**
+ * Update SeasonMembership after joining
+ * Mirrors the initialization from join_season.rs (lines 84-96)
+ *
+ * @param user - User's public key
+ * @param seasonMembershipId - Membership ID
+ * @param seasonNumber - Season number
+ * @param depositTier - Tier chosen at join time
+ * @param depositAmount - Active deposit amount (participates in rewards/penalties)
+ * @param depositEscrowedAmount - Escrowed deposit amount (always refundable)
+ * @param joinedAt - Timestamp when joined
+ * @param joinedWindowNumber - Window number when joined
+ * @returns Initialized SeasonMembership object
+ */
+export declare function initializeSeasonMembership(user: PublicKey, seasonMembershipId: BN, seasonNumber: BN, depositTier: SeasonDepositTier, referrer: PublicKey, depositAmount: BN, depositEscrowedAmount: BN, joinedAt: BN, joinedWindowNumber: BN, bump: number): SeasonMembership;
+/**
+ * Update Season after a user joins
+ * Mirrors the update from join_season.rs (lines 98-104)
+ *
+ * @param season - Current season
+ * @param depositActive - Active deposit amount added to season totals
+ * @returns Updated Season object
+ */
+export declare function updateSeasonForJoin(season: Season, depositActive: BN, depositTier: SeasonDepositTier, joinedWindowNumber: BN, totalWindowsPerSeason?: number): Season;
+/**
+ * Update RewardWindow after post confirmation
+ * Mirrors confirmed_post_on_x.rs logic
+ *
+ * @param window - Current window
+ * @param isOnTime - Whether the post was on time
+ * @param penaltyAmount - Penalty amount if late (REQUIRED when isOnTime=false)
+ * @returns Updated RewardWindow object
+ *
+ * @throws Error if penaltyAmount missing when isOnTime is false
+ */
+export declare function updateWindowForConfirmation(window: RewardWindow, isOnTime: boolean, stakeAmount?: BN): RewardWindow;
+/**
+ * Update UserWindowParticipation after post confirmation
+ * Mirrors confirmed_post_on_x.rs logic
+ *
+ * @param participation - Current participation
+ * @param isOnTime - Whether the post was on time
+ * @returns Updated UserWindowParticipation object
+ */
+export declare function updateParticipationForConfirmation(participation: UserWindowParticipation, isOnTime: boolean): UserWindowParticipation;
+/**
+ * Update SeasonMembership after post confirmation
+ * Mirrors confirmed_post_on_x.rs logic
+ *
+ * @param membership - Current membership
+ * @param isOnTime - Whether the post was on time
+ * @param penaltyAmount - Penalty amount if late (REQUIRED when isOnTime=false)
+ * @returns Updated SeasonMembership object
+ *
+ * @throws Error if penaltyAmount missing when isOnTime is false
+ */
+export declare function updateMembershipForConfirmation(membership: SeasonMembership, isOnTime: boolean, penaltyAmount?: BN): SeasonMembership;
+/**
+ * Update Season after post confirmation
+ * Mirrors confirmed_post_on_x.rs logic
+ *
+ * @param season - Current season
+ * @param isOnTime - Whether the post was on time
+ * @param penaltyAmount - Penalty amount if late (REQUIRED when isOnTime=false)
+ * @returns Updated Season object
+ *
+ * @throws Error if penaltyAmount missing when isOnTime is false
+ */
+export declare function updateSeasonForConfirmation(season: Season, isOnTime: boolean, _stakeAmount?: BN): Season;
+/**
+ * Finalize RewardWindow and calculate rewards
+ * Mirrors claim_window_rewards.rs finalization logic (lines 22-86)
+ *
+ * @param window - Current window
+ * @returns Updated finalized RewardWindow object
+ */
+export declare function updateWindowForFinalization(window: RewardWindow, eligibleStakeX: BN): RewardWindow;
+/**
+ * Update UserWindowParticipation after claiming window rewards
+ * Mirrors claim_window_rewards.rs logic
+ *
+ * @param participation - Current participation
+ * @param rewardAmount - Reward amount claimed
+ * @returns Updated UserWindowParticipation object
+ */
+export declare function updateParticipationForClaim(participation: UserWindowParticipation, rewardAmount: BN): UserWindowParticipation;
+/**
+ * Update SeasonMembership after claiming window rewards
+ * Mirrors claim_window_rewards.rs logic (lines 156-165)
+ *
+ * @param membership - Current membership
+ * @param rewardAmount - Total reward amount
+ * (Penalties are tier-derived on-chain; settings no longer carry penalty_per_window.)
+ * @returns Updated SeasonMembership object
+ *
+ * @throws Error if invalid inputs provided
+ */
+export declare function updateMembershipForClaim(membership: SeasonMembership, rewardAmount: BN): SeasonMembership;
+/**
+ * Initialize ReferralPenaltyClaim
+ * Mirrors claim_referral_penalty_for_window.rs (write fields + amount calc)
+ *
+ * @param referredUser - The user who missed the window
+ * @param seasonNumber - Season number
+ * @param windowNumber - Window number
+ * @param seasonMembershipId - Referred user's membership id
+ * @param claimant - Referrer (or root admin if no referrer)
+ * @param perWindowPenalty - Tier penalty per window (base units)
+ * @param claimedAt - Unix timestamp in seconds (i64 on-chain, represented as BN in SDK)
+ */
+export declare function initializeReferralPenaltyClaim(params: {
+    referredUser: PublicKey;
+    seasonNumber: BN;
+    windowNumber: BN;
+    seasonMembershipId: BN;
+    claimant: PublicKey;
+    perWindowPenalty: BN;
+    claimedAt?: BN;
+}): ReferralPenaltyClaim;
+/**
+ * Calculate withdrawal amount for season deposit
+ * Mirrors withdraw_season_deposit.rs logic (lines 55-87)
+ *
+ * @param membership - Current membership
+ * @param season - Current season
+ * @param settings - Season settings
+ * @returns Withdrawal amount and updated accounts
+ *
+ * @throws Error if invalid inputs provided
+ */
+export declare function calculateWithdrawalAmount(membership: SeasonMembership, season: Season, settings: SeasonSettings): {
+    withdrawalAmount: BN;
+    updatedMembership: SeasonMembership;
+    updatedSeason: Season;
+    updatedSettings: SeasonSettings;
+};
+/**
+ * Update SeasonSettings after toggling pause
+ *
+ * @param settings - Current settings
+ * @returns Updated SeasonSettings object
+ */
+export declare function updateSeasonSettingsForPauseToggle(settings: SeasonSettings): SeasonSettings;
+/**
+ * Update SeasonSettings after admin update
+ *
+ * @param settings - Current settings
+ * @param newAdmin - New admin public key
+ * @returns Updated SeasonSettings object
+ */
+export declare function updateSeasonSettingsForAdminUpdate(settings: SeasonSettings, newAdmin: PublicKey): SeasonSettings;