proof-of-take-sdk 1.0.0

package/LIBRARY_GUIDE.md

@@ -0,0 +1,400 @@
+# Proof of Miztake SDK - Developer Guide
+
+## 🎯 Overview
+
+This TypeScript SDK provides a clean, typed interface for interacting with the Proof of Miztake Solana program.
+
+**Package**: `@proof-of-miztake/sdk`  
+**Version**: 1.0.0  
+**Program ID**: `takeA82AwosboZgG7HQx8D3dGLbbbPUyQCva9HpLJBr`
+
+---
+
+## 📦 Installation
+
+### Option 1: From npm (After Publishing)
+```bash
+npm install @proof-of-miztake/sdk
+```
+
+### Option 2: Local Development
+```bash
+cd proof_of_miztake_library
+npm install
+npm run build
+```
+
+Then in your project:
+```bash
+npm install /path/to/proof_of_miztake_library
+```
+
+---
+
+## 🏗️ Library Structure
+
+```
+proof_of_miztake_library/
+├── src/
+│   ├── index.ts                      # Main exports
+│   ├── types.ts                      # TypeScript type definitions
+│   ├── instructions/
+│   │   ├── createMiztake.ts         # Create miztake function
+│   │   ├── claimReward.ts           # Claim rewards function
+│   │   ├── depositTokens.ts         # Deposit tokens function
+│   │   ├── withdrawTokens.ts        # Withdraw tokens function
+│   │   ├── initializeStatistics.ts  # Initialize program function
+│   │   ├── updateConfig.ts          # Update config function
+│   │   └── togglePause.ts           # Pause/unpause function
+│   └── utils/
+│       ├── constants.ts              # Program constants
+│       └── pdas.ts                   # PDA derivation helpers
+├── package.json
+├── tsconfig.json
+├── README.md                         # User documentation
+├── LIBRARY_GUIDE.md                  # This file
+└── example.ts                        # Complete usage example
+```
+
+---
+
+## 🎯 Core Functions
+
+### All 7 Program Instructions Wrapped:
+
+1. **`initializeStatistics()`** - Initialize program (admin only)
+2. **`createMiztake()`** - Create new miztake (users)
+3. **`claimReward()`** - Claim rewards (dual-sig: user + admin)
+4. **`depositTokens()`** - Deposit to vault (anyone)
+5. **`withdrawTokens()`** - Withdraw from vault (admin only)
+6. **`updateConfig()`** - Update settings (admin only)
+7. **`togglePause()`** - Emergency pause (admin only)
+
+### Bonus Helper Functions:
+
+8. **`canClaim()`** - Check if claim is possible
+9. **`getConfig()`** - Get current configuration
+10. **`isProgramPaused()`** - Check pause status
+11. **`getVaultBalance()`** - Get vault balance
+12. **`isInitialized()`** - Check if initialized
+13. **PDA helpers** - All PDA derivation functions
+
+---
+
+## 💡 Usage Examples
+
+### Setup Your Project
+
+```typescript
+import { Program, AnchorProvider } from "@coral-xyz/anchor";
+import { Connection } from "@solana/web3.js";
+import {
+  createMiztake,
+  depositTokens,
+  PROGRAM_ID
+} from "@proof-of-miztake/sdk";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const provider = new AnchorProvider(connection, wallet, {});
+const idl = await Program.fetchIdl(PROGRAM_ID, provider);
+const program = new Program(idl, provider);
+```
+
+---
+
+### User: Create Miztake
+
+```typescript
+import { BN } from "@coral-xyz/anchor";
+import { createMiztake } from "@proof-of-miztake/sdk";
+
+const tx = await createMiztake(program, {
+  telegramId: new BN(12345678),
+  telegramUsername: "myusername",
+  perceptualHash: "hash1234567890ab",
+  averageHash: "hash1234567890cd",
+  differenceHash: "hash1234567890ef",
+  waveletHash: "hash1234567890gh",
+  shaHash: "sha256_full_hash_minimum_32_characters_required_here",
+  computedAt: "2025-10-26T12:00:00Z"
+}, userWallet.publicKey);
+
+console.log("Miztake created! TX:", tx);
+```
+
+---
+
+### User + Admin: Claim Reward
+
+```typescript
+import { claimReward, canClaim, getMiztakePda } from "@proof-of-miztake/sdk";
+
+const [miztakePda] = getMiztakePda(shaHash);
+const amount = new BN(100_000_000); // 10 tokens
+
+// Check if can claim first
+const checkResult = await canClaim(program, miztakePda, amount);
+
+if (!checkResult.canClaim) {
+  console.log("Cannot claim:", checkResult.reason);
+  return;
+}
+
+console.log("Remaining claimable:", checkResult.remainingClaimable?.toString());
+
+// Claim (both user and admin must sign)
+const tx = await claimReward(
+  program,
+  {
+    miztakePda,
+    userTokenAccount: userMizdTokenAccount,
+    amount
+  },
+  userWallet,
+  adminWallet
+);
+
+console.log("Reward claimed! TX:", tx);
+```
+
+---
+
+### Admin: Manage Vault
+
+```typescript
+import { depositTokens, withdrawTokens, getVaultBalance } from "@proof-of-miztake/sdk";
+
+// Deposit tokens
+await depositTokens(program, {
+  amount: new BN(1_000_000_000_000), // 100K tokens
+  depositorTokenAccount: adminMizdAccount
+}, adminWallet);
+
+// Check balance
+const balance = await getVaultBalance(program);
+console.log("Vault balance:", balance.toString());
+
+// Withdraw tokens
+await withdrawTokens(program, {
+  amount: new BN(500_000_000_000), // 50K tokens
+  adminTokenAccount: adminMizdAccount
+}, adminWallet);
+```
+
+---
+
+### Admin: Update Configuration
+
+```typescript
+import { updateConfig, getConfig } from "@proof-of-miztake/sdk";
+
+// Update fee
+await updateConfig(program, {
+  newFee: new BN(200_000)  // 0.0002 SOL
+}, adminWallet);
+
+// Update max claimable default
+await updateConfig(program, {
+  newDefaultMaxClaimable: new BN(50_000_000_000)  // 5000 tokens
+}, adminWallet);
+
+// Update multiple fields
+await updateConfig(program, {
+  newFee: new BN(150_000),
+  newFeeRecipient: new PublicKey("..."),
+  newDefaultMaxClaimable: new BN(30_000_000_000)
+}, adminWallet);
+
+// Check current config
+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());
+```
+
+---
+
+### Admin: Emergency Controls
+
+```typescript
+import { togglePause, isProgramPaused } from "@proof-of-miztake/sdk";
+
+// Pause the program
+await togglePause(program, adminWallet);
+console.log("Program paused");
+
+// Check status
+const paused = await isProgramPaused(program);
+console.log("Is paused:", paused);
+
+// Unpause
+await togglePause(program, adminWallet);
+console.log("Program unpaused");
+```
+
+---
+
+## 🔧 Building the Library
+
+```bash
+# Install dependencies
+cd proof_of_miztake_library
+npm install
+
+# Build
+npm run build
+
+# Output will be in dist/ folder
+# dist/index.js - Compiled JavaScript
+# dist/index.d.ts - TypeScript type definitions
+```
+
+---
+
+## 📝 Publishing (Optional)
+
+### To npm:
+
+```bash
+# Login to npm
+npm login
+
+# Update version in package.json
+npm version patch  # or minor, or major
+
+# Publish
+npm publish --access public
+```
+
+### To GitHub Packages:
+
+Update package.json name:
+```json
+{
+  "name": "@your-org/proof-of-miztake-sdk"
+}
+```
+
+Then publish:
+```bash
+npm publish
+```
+
+---
+
+## 🎯 Integration in Your App
+
+### React Example:
+
+```typescript
+import { useWallet } from "@solana/wallet-adapter-react";
+import { createMiztake } from "@proof-of-miztake/sdk";
+
+function CreateMiztakeButton() {
+  const wallet = useWallet();
+
+  const handleCreate = async () => {
+    if (!wallet.publicKey) return;
+
+    try {
+      const tx = await createMiztake(program, {
+        telegramId: new BN(user.telegramId),
+        telegramUsername: user.username,
+        // ... other params
+      }, wallet.publicKey);
+
+      toast.success(`Miztake created! TX: ${tx}`);
+    } catch (error) {
+      toast.error(`Failed: ${error.message}`);
+    }
+  };
+
+  return <button onClick={handleCreate}>Create Miztake</button>;
+}
+```
+
+---
+
+## 🔍 Advanced Usage
+
+### Event Listening:
+
+```typescript
+// Subscribe to events (requires program.addEventListener)
+program.addEventListener("MiztakeCreated", (event, slot) => {
+  console.log("New miztake:", event.miztakeId.toString());
+  console.log("Creator:", event.creator.toBase58());
+  console.log("Timestamp:", new Date(event.timestamp.toNumber() * 1000));
+});
+
+program.addEventListener("RewardClaimed", (event, slot) => {
+  console.log("Reward claimed:", event.amount.toString());
+  console.log("Miztake ID:", event.miztakeId.toString());
+  console.log("Total user claimed:", event.totalUserClaimed.toString());
+});
+```
+
+---
+
+### Query All User Miztakes:
+
+```typescript
+import { getUserStatsPda } from "@proof-of-miztake/sdk";
+
+const [userStatsPda] = getUserStatsPda(new BN(telegramId));
+const userStats = await program.account.userStats.fetch(userStatsPda);
+
+console.log("User has created", userStats.totalNumberOfMiztakes.toString(), "miztakes");
+console.log("User has claimed", userStats.claimedMizd.toString(), "tokens");
+
+// You would need to track miztake PDAs separately
+// or query all miztake accounts filtered by user_key
+```
+
+---
+
+## ✅ What's Included
+
+### ✅ All Instructions
+- Complete wrapper for all 7 program instructions
+- Proper parameter validation
+- Error handling
+- TypeScript types
+
+### ✅ PDA Helpers
+- Automatic PDA derivation
+- Correct seeds for all account types
+- No manual PDA calculation needed
+
+### ✅ Query Functions
+- Check claim eligibility
+- Get configuration
+- Get vault balance
+- Check pause status
+- Check initialization
+
+### ✅ Validation
+- Input validation before sending transactions
+- Clear error messages
+- Type safety
+
+### ✅ Documentation
+- JSDoc comments on all functions
+- Usage examples
+- Complete type definitions
+- Integration guides
+
+---
+
+## 🎉 You're Ready!
+
+The SDK provides everything needed to interact with Proof of Miztake:
+
+✅ **Clean API** - Simple function calls  
+✅ **Type Safe** - Full TypeScript support  
+✅ **Validated** - Input checking built-in  
+✅ **Documented** - Examples and guides  
+✅ **Production Ready** - Matches deployed program  
+
+**Start building your frontend with confidence!** 🚀
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Proof of Miztake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+