proof-of-take-sdk 1.0.0

package/README.md

@@ -0,0 +1,370 @@
+# Proof of Miztake SDK
+
+TypeScript/JavaScript SDK for interacting with the Proof of Miztake Solana program.
+
+## Installation
+
+```bash
+npm install @proof-of-miztake/sdk
+# or
+yarn add @proof-of-miztake/sdk
+```
+
+## Quick Start
+
+```typescript
+import { AnchorProvider, Program } from "@coral-xyz/anchor";
+import { Connection, Keypair } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import {
+  createMiztake,
+  claimReward,
+  depositTokens,
+  initializeStatistics,
+  PROGRAM_ID
+} from "@proof-of-miztake/sdk";
+
+// Setup
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const wallet = // your wallet
+const provider = new AnchorProvider(connection, wallet, {});
+const idl = // load your IDL
+const program = new Program(idl, provider);
+
+// Create a miztake
+const tx = await createMiztake(program, {
+  telegramId: new BN(12345678),
+  telegramUsername: "myusername",
+  perceptualHash: "hash1",
+  averageHash: "hash2",
+  differenceHash: "hash3",
+  waveletHash: "hash4",
+  shaHash: "sha256_hash_must_be_at_least_32_characters_long",
+  computedAt: new Date().toISOString()
+}, wallet.publicKey);
+
+console.log("Miztake created:", tx);
+```
+
+## API Reference
+
+### User Operations
+
+#### `createMiztake()`
+Create a new miztake with metadata and hashes.
+
+```typescript
+await createMiztake(program, {
+  telegramId: new BN(12345678),
+  telegramUsername: "username",
+  perceptualHash: "hash1",
+  averageHash: "hash2",
+  differenceHash: "hash3",
+  waveletHash: "hash4",
+  shaHash: "sha256_hash_32_chars_minimum...",
+  computedAt: "2025-10-26T12:00:00Z"
+}, userWallet.publicKey);
+```
+
+**Parameters**:
+- `telegramId`: User's Telegram ID
+- `telegramUsername`: Max 21 characters
+- `shaHash`: Min 32 characters (used for PDA)
+- Other hashes and metadata
+
+**Fee**: Dynamic (default 0.0001 SOL)
+
+---
+
+#### `claimReward()`
+Claim MIZD token rewards (requires user + admin signatures).
+
+```typescript
+await claimReward(program, {
+  miztakePda: miztakeAddress,
+  userTokenAccount: userMizdTokenAccount,
+  amount: new BN(100_000_000) // 10 tokens with 7 decimals
+}, userWallet, adminWallet);
+```
+
+**Requires**:
+- User signature (miztake owner)
+- Admin signature
+- Amount within max_claimable limit
+
+---
+
+#### `canClaim()`
+Check if a claim is possible before attempting.
+
+```typescript
+const result = await canClaim(program, miztakePda, new BN(100_000_000));
+if (result.canClaim) {
+  console.log("Can claim! Remaining:", result.remainingClaimable);
+} else {
+  console.log("Cannot claim:", result.reason);
+}
+```
+
+---
+
+### Token Operations
+
+#### `depositTokens()`
+Deposit MIZD tokens to the vault (anyone can deposit).
+
+```typescript
+await depositTokens(program, {
+  amount: new BN(1_000_000_000_000), // 100,000 tokens
+  depositorTokenAccount: depositorMizdAccount
+}, depositorWallet);
+```
+
+---
+
+#### `getVaultBalance()`
+Get current vault balance.
+
+```typescript
+const balance = await getVaultBalance(program);
+console.log("Vault balance:", balance.toString());
+```
+
+---
+
+### Admin Operations
+
+#### `initializeStatistics()`
+Initialize the program (admin only, one-time).
+
+```typescript
+await initializeStatistics(program, adminWallet);
+```
+
+---
+
+#### `updateConfig()`
+Update program configuration (admin only).
+
+```typescript
+// Update fee
+await updateConfig(program, {
+  newFee: new BN(150_000)  // 0.00015 SOL
+}, adminWallet);
+
+// Update max claimable
+await updateConfig(program, {
+  newDefaultMaxClaimable: new BN(20_000_000_000)  // 2000 tokens
+}, adminWallet);
+
+// Update multiple fields
+await updateConfig(program, {
+  newFee: new BN(200_000),
+  newFeeRecipient: new PublicKey("..."),
+  newDefaultMaxClaimable: new BN(50_000_000_000)
+}, adminWallet);
+```
+
+---
+
+#### `togglePause()`
+Emergency pause/unpause (admin only).
+
+```typescript
+await togglePause(program, adminWallet);
+
+// Check status
+const isPaused = await isProgramPaused(program);
+```
+
+---
+
+#### `withdrawTokens()`
+Withdraw from vault (admin only).
+
+```typescript
+await withdrawTokens(program, {
+  amount: new BN(500_000_000_000),
+  adminTokenAccount: adminMizdAccount
+}, adminWallet);
+```
+
+---
+
+### Utility Functions
+
+#### PDA Derivation
+
+```typescript
+import {
+  getMiztakeStatisticsPda,
+  getTokenVaultPda,
+  getUserStatsPda,
+  getMiztakePda
+} from "@proof-of-miztake/sdk";
+
+// Get statistics PDA
+const [statisticsPda, bump] = getMiztakeStatisticsPda();
+
+// Get user stats PDA
+const [userStatsPda] = getUserStatsPda(new BN(telegramId));
+
+// Get miztake PDA
+const [miztakePda] = getMiztakePda(shaHash);
+
+// Get vault PDA
+const [vaultPda] = getTokenVaultPda();
+```
+
+---
+
+#### Query Functions
+
+```typescript
+// Check if initialized
+const initialized = await isInitialized(program);
+
+// Get configuration
+const config = await getConfig(program);
+console.log("Current fee:", config.fee.toString());
+console.log("Fee recipient:", config.feeRecipient.toBase58());
+console.log("Default max claimable:", config.defaultMaxClaimable.toString());
+console.log("Is paused:", config.isPaused);
+
+// Check pause status
+const paused = await isProgramPaused(program);
+```
+
+---
+
+## Constants
+
+```typescript
+import {
+  PROGRAM_ID,
+  ADMIN_PUBLIC_KEY,
+  MIZD_TOKEN_MINT,
+  DEFAULT_FEE_RECIPIENT,
+  DEFAULT_MIZTAKE_FEE,
+  DEFAULT_MAX_CLAIMABLE,
+  MIN_FEE,
+  MAX_FEE,
+  MAX_USERNAME_LENGTH,
+  MIN_HASH_LENGTH
+} from "@proof-of-miztake/sdk";
+```
+
+---
+
+## Types
+
+All TypeScript types are exported:
+
+```typescript
+import {
+  CreateMiztakeParams,
+  ClaimRewardParams,
+  DepositTokensParams,
+  WithdrawTokensParams,
+  UpdateConfigParams,
+  MiztakeStatistics,
+  UserStats,
+  Miztake
+} from "@proof-of-miztake/sdk";
+```
+
+---
+
+## Error Handling
+
+```typescript
+try {
+  await createMiztake(program, params, wallet.publicKey);
+} catch (error) {
+  if (error.message.includes("UsernameTooLong")) {
+    console.error("Username exceeds 21 characters");
+  } else if (error.message.includes("ProgramPaused")) {
+    console.error("Program is currently paused");
+  } else if (error.message.includes("InvalidHashLength")) {
+    console.error("SHA hash must be at least 32 characters");
+  }
+  // Handle other errors...
+}
+```
+
+---
+
+## Examples
+
+### Complete Flow Example
+
+```typescript
+import { Program, BN } from "@coral-xyz/anchor";
+import {
+  createMiztake,
+  depositTokens,
+  claimReward,
+  getMiztakePda,
+  PROGRAM_ID
+} from "@proof-of-miztake/sdk";
+
+// 1. Deposit tokens to vault (admin)
+await depositTokens(program, {
+  amount: new BN(10_000_000_000_000), // 1M tokens
+  depositorTokenAccount: adminMizdAccount
+}, adminWallet);
+
+// 2. User creates miztake
+const miztakeParams = {
+  telegramId: new BN(12345678),
+  telegramUsername: "cryptouser",
+  perceptualHash: "abc123...",
+  averageHash: "def456...",
+  differenceHash: "ghi789...",
+  waveletHash: "jkl012...",
+  shaHash: "sha256_hash_exactly_32_chars_min",
+  computedAt: new Date().toISOString()
+};
+
+await createMiztake(program, miztakeParams, userWallet.publicKey);
+
+// 3. Admin + User claim reward
+const [miztakePda] = getMiztakePda(miztakeParams.shaHash);
+await claimReward(program, {
+  miztakePda,
+  userTokenAccount: userMizdAccount,
+  amount: new BN(100_000_000) // 10 tokens
+}, userWallet, adminWallet);
+```
+
+---
+
+## Building from Source
+
+```bash
+# Clone and install
+git clone ...
+cd proof_of_miztake_library
+npm install
+
+# Build
+npm run build
+
+# The dist/ folder contains the compiled JavaScript
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+## Support
+
+For issues and questions:
+- GitHub: [Your repo]
+- Documentation: See project README
+- Security: See SECURITY_AUDIT.md
+

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import { Program, AnchorProvider } from "@coral-xyz/anchor";
+import { Connection, PublicKey } from "@solana/web3.js";
+import { ProofOfTake } from "./types/proof_of_take";
+/**
+ * Create a Proof of Take program instance
+ *
+ * @param provider - Anchor provider with connection and wallet
+ * @returns Program instance
+ *
+ * @example
+ * ```typescript
+ * import { createProgram } from "@proof-of-take/sdk";
+ *
+ * const program = createProgram(provider);
+ * ```
+ */
+export declare function createProgram(provider: AnchorProvider): Program<ProofOfTake>;
+/**
+ * Create a Proof of Take program instance with custom program ID
+ *
+ * @param provider - Anchor provider
+ * @param programId - Custom program ID
+ * @returns Program instance
+ */
+export declare function createProgramWithId(provider: AnchorProvider, programId: PublicKey): Program<ProofOfTake>;
+/**
+ * Get the program instance with just a connection
+ *
+ * @param connection - Solana connection
+ * @returns Program instance (read-only, no wallet)
+ */
+export declare function getProgramReadOnly(connection: Connection): Program<ProofOfTake>;

package/dist/client.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProgram = createProgram;
+exports.createProgramWithId = createProgramWithId;
+exports.getProgramReadOnly = getProgramReadOnly;
+const anchor_1 = require("@coral-xyz/anchor");
+const idl_1 = require("./idl/idl");
+const anchorHelpers_1 = require("./utils/anchorHelpers");
+/**
+ * Create a Proof of Take program instance
+ *
+ * @param provider - Anchor provider with connection and wallet
+ * @returns Program instance
+ *
+ * @example
+ * ```typescript
+ * import { createProgram } from "@proof-of-take/sdk";
+ *
+ * const program = createProgram(provider);
+ * ```
+ */
+function createProgram(provider) {
+    return new anchor_1.Program(idl_1.IDL, provider);
+}
+/**
+ * Create a Proof of Take program instance with custom program ID
+ *
+ * @param provider - Anchor provider
+ * @param programId - Custom program ID
+ * @returns Program instance
+ */
+function createProgramWithId(provider, programId) {
+    // Anchor v0.32 Program ctor does not accept a programId param; it uses `idl.address`.
+    // So we clone the IDL and override its address to point at the provided programId.
+    const idlWithAddress = (0, anchorHelpers_1.withIdlAddress)(idl_1.IDL, programId);
+    return new anchor_1.Program(idlWithAddress, provider);
+}
+/**
+ * Get the program instance with just a connection
+ *
+ * @param connection - Solana connection
+ * @returns Program instance (read-only, no wallet)
+ */
+function getProgramReadOnly(connection) {
+    const provider = (0, anchorHelpers_1.createReadOnlyProvider)(connection, "confirmed");
+    return new anchor_1.Program(idl_1.IDL, provider);
+}

package/dist/constants/season.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Season system constants
+ * These values match the constants defined in the Rust program
+ */
+export declare const SEASON_CONSTANTS: {
+    /** Cost to join a season (100 MIZD with decimals) */
+    readonly MEMBERSHIP_COST: any;
+    /** Penalty per missed window (1.375 MIZD with decimals) */
+    readonly PENALTY_PER_WINDOW: any;
+    /** Duration of entire season in seconds (7 days) */
+    readonly SEASON_DURATION: 604800;
+    /** Duration of each window in seconds (8 hours) */
+    readonly WINDOW_DURATION: 28800;
+    /** Total number of windows per season */
+    readonly TOTAL_WINDOWS_PER_SEASON: 21;
+    /** Maximum members allowed per season (DOS protection) */
+    readonly MAX_MEMBERS_PER_SEASON: any;
+};

package/dist/constants/season.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEASON_CONSTANTS = void 0;
+const anchor_1 = require("@coral-xyz/anchor");
+/**
+ * Season system constants
+ * These values match the constants defined in the Rust program
+ */
+exports.SEASON_CONSTANTS = {
+    /** Cost to join a season (100 MIZD with decimals) */
+    MEMBERSHIP_COST: new anchor_1.BN(100000000000),
+    /** Penalty per missed window (1.375 MIZD with decimals) */
+    PENALTY_PER_WINDOW: new anchor_1.BN(1375000000),
+    /** Duration of entire season in seconds (7 days) */
+    SEASON_DURATION: 604800,
+    /** Duration of each window in seconds (8 hours) */
+    WINDOW_DURATION: 28800,
+    /** Total number of windows per season */
+    TOTAL_WINDOWS_PER_SEASON: 21,
+    /** Maximum members allowed per season (DOS protection) */
+    MAX_MEMBERS_PER_SEASON: new anchor_1.BN(10000),
+};

package/dist/getters/getMiztake.d.ts

@@ -0,0 +1,11 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { Miztake } from "../types";
+/**
+ * Get a miztake account by SHA hash
+ * @param connection - Solana connection
+ * @param shaHash - SHA hash of the miztake
+ * @returns Miztake account data
+ */
+export declare function getMiztake(connection: Connection, shaHash: string): Promise<Miztake & {
+    publicKey: PublicKey;
+}>;

package/dist/getters/getMiztake.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMiztake = getMiztake;
+const pdas_1 = require("../utils/pdas");
+const programHelpers_1 = require("../utils/programHelpers");
+/**
+ * Get a miztake account by SHA hash
+ * @param connection - Solana connection
+ * @param shaHash - SHA hash of the miztake
+ * @returns Miztake account data
+ */
+async function getMiztake(connection, shaHash) {
+    const program = (0, programHelpers_1.getProgram)(connection);
+    const [miztakePda] = (0, pdas_1.getMiztakePda)(shaHash);
+    const miztake = await program.account.miztake.fetch(miztakePda);
+    return {
+        publicKey: miztakePda,
+        id: miztake.id,
+        telegramId: miztake.telegramId,
+        telegramUsername: miztake.telegramUsername,
+        perceptualHash: miztake.perceptualHash,
+        averageHash: miztake.averageHash,
+        differenceHash: miztake.differenceHash,
+        waveletHash: miztake.waveletHash,
+        shaHash: miztake.shaHash,
+        computedAt: miztake.computedAt,
+        creator: miztake.creator,
+        userStats: miztake.userStats,
+        userKey: miztake.userKey,
+        onchainCreatedAt: miztake.onchainCreatedAt,
+        usedInSeason: miztake.usedInSeason,
+        usedInWindow: miztake.usedInWindow,
+    };
+}

package/dist/getters/getMiztakeStatistics.d.ts

@@ -0,0 +1,10 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { MiztakeStatistics } from "../types";
+/**
+ * Get miztake statistics account
+ * @param connection - Solana connection
+ * @returns MiztakeStatistics account data
+ */
+export declare function getMiztakeStatistics(connection: Connection): Promise<MiztakeStatistics & {
+    publicKey: PublicKey;
+}>;

package/dist/getters/getMiztakeStatistics.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMiztakeStatistics = getMiztakeStatistics;
+const pdas_1 = require("../utils/pdas");
+const programHelpers_1 = require("../utils/programHelpers");
+/**
+ * Get miztake statistics account
+ * @param connection - Solana connection
+ * @returns MiztakeStatistics account data
+ */
+async function getMiztakeStatistics(connection) {
+    const program = (0, programHelpers_1.getProgram)(connection);
+    const [statisticsPda] = (0, pdas_1.getMiztakeStatisticsPda)();
+    const statistics = await program.account.miztakeStatistics.fetch(statisticsPda);
+    return {
+        publicKey: statisticsPda,
+        totalMiztakes: statistics.totalMiztakes,
+        bump: statistics.bump,
+    };
+}

package/dist/getters/getTokenVault.d.ts

@@ -0,0 +1,30 @@
+import { Connection } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+/**
+ * Get the token vault account information
+ *
+ * @param connection - Solana connection
+ * @returns Token vault account data
+ */
+export declare function getTokenVault(connection: Connection): Promise<{
+    address: import("@solana/web3.js").PublicKey;
+    data: {
+        mint: import("@solana/web3.js").PublicKey;
+        owner: import("@solana/web3.js").PublicKey;
+        amount: any;
+        delegate: import("@solana/web3.js").PublicKey;
+        delegatedAmount: bigint;
+        isInitialized: boolean;
+        isFrozen: boolean;
+        isNative: boolean;
+        closeAuthority: import("@solana/web3.js").PublicKey;
+    };
+}>;
+/**
+ * Check if token vault is initialized
+ */
+export declare function isVaultInitialized(connection: Connection): Promise<boolean>;
+/**
+ * Get vault balance (amount of MIZD tokens in vault)
+ */
+export declare function getVaultTokenBalance(connection: Connection): Promise<BN>;

package/dist/getters/getTokenVault.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTokenVault = getTokenVault;
+exports.isVaultInitialized = isVaultInitialized;
+exports.getVaultTokenBalance = getVaultTokenBalance;
+const spl_token_1 = require("@solana/spl-token");
+const anchor_1 = require("@coral-xyz/anchor");
+const pdas_1 = require("../utils/pdas");
+/**
+ * Get the token vault account information
+ *
+ * @param connection - Solana connection
+ * @returns Token vault account data
+ */
+async function getTokenVault(connection) {
+    const [vaultPda] = (0, pdas_1.getTokenVaultPda)();
+    try {
+        const vaultAccount = await (0, spl_token_1.getAccount)(connection, vaultPda);
+        return {
+            address: vaultPda,
+            data: {
+                mint: vaultAccount.mint,
+                owner: vaultAccount.owner,
+                amount: new anchor_1.BN(vaultAccount.amount.toString()),
+                delegate: vaultAccount.delegate,
+                delegatedAmount: vaultAccount.delegatedAmount,
+                isInitialized: vaultAccount.isInitialized,
+                isFrozen: vaultAccount.isFrozen,
+                isNative: vaultAccount.isNative,
+                closeAuthority: vaultAccount.closeAuthority,
+            },
+        };
+    }
+    catch (error) {
+        throw new Error(`Token vault not found or not initialized: ${error}`);
+    }
+}
+/**
+ * Check if token vault is initialized
+ */
+async function isVaultInitialized(connection) {
+    try {
+        await getTokenVault(connection);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get vault balance (amount of MIZD tokens in vault)
+ */
+async function getVaultTokenBalance(connection) {
+    const vault = await getTokenVault(connection);
+    return vault.data.amount;
+}

package/dist/getters/getUserStats.d.ts

@@ -0,0 +1,21 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { UserStats } from "../types";
+/**
+ * Get user stats account by telegram ID
+ * @param connection - Solana connection
+ * @param telegramId - Telegram ID of the user
+ * @returns UserStats account data
+ */
+export declare function getUserStats(connection: Connection, telegramId: BN): Promise<UserStats & {
+    publicKey: PublicKey;
+}>;
+/**
+ * Get user stats by public key (if you already have the PDA)
+ * @param connection - Solana connection
+ * @param userStatsPda - User stats PDA
+ * @returns UserStats account data
+ */
+export declare function getUserStatsByPda(connection: Connection, userStatsPda: PublicKey): Promise<UserStats & {
+    publicKey: PublicKey;
+}>;