proof-of-take-sdk 1.0.0

package/dist/utils/signerHelpers.d.ts

@@ -0,0 +1,17 @@
+import { PublicKey } from "@solana/web3.js";
+/**
+ * Signer information
+ */
+export interface SignerInfo {
+    publicKey: PublicKey;
+    role: string;
+}
+/**
+ * Build signers array with optional fee payer
+ * Automatically deduplicates if fee payer is already in required signers
+ *
+ * @param requiredSigners - Required signers for the instruction
+ * @param feePayer - Optional separate fee payer
+ * @returns Array of signers with deduplicated fee payer
+ */
+export declare function buildSigners(requiredSigners: SignerInfo[], feePayer?: PublicKey): SignerInfo[];

package/dist/utils/signerHelpers.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSigners = buildSigners;
+/**
+ * Build signers array with optional fee payer
+ * Automatically deduplicates if fee payer is already in required signers
+ *
+ * @param requiredSigners - Required signers for the instruction
+ * @param feePayer - Optional separate fee payer
+ * @returns Array of signers with deduplicated fee payer
+ */
+function buildSigners(requiredSigners, feePayer) {
+    const signers = [...requiredSigners];
+    if (feePayer) {
+        const alreadyIncluded = signers.some((s) => s.publicKey.equals(feePayer));
+        if (!alreadyIncluded) {
+            signers.push({ publicKey: feePayer, role: "feePayer" });
+        }
+    }
+    return signers;
+}

package/dist/utils/simulationHelpers.d.ts

@@ -0,0 +1,121 @@
+import { Connection, TransactionInstruction, PublicKey, SimulatedTransactionResponse } from "@solana/web3.js";
+import { SignerInfo } from "./signerHelpers";
+/**
+ * Simulation result with detailed information
+ */
+export interface DetailedSimulationResult {
+    success: boolean;
+    logs: string[];
+    unitsConsumed: number;
+    error?: string;
+    returnData?: {
+        programId: string;
+        data: [string, string];
+    };
+    accounts?: SimulatedTransactionResponse["accounts"];
+}
+/**
+ * Fee estimation result
+ */
+export interface FeeEstimate {
+    baseFee: number;
+    estimatedComputeUnits: number;
+    recommendedPriorityFee?: number;
+    totalEstimatedCost: number;
+}
+/**
+ * Simulate an instruction without sending it
+ *
+ * @param connection - Solana connection
+ * @param instructions - Instructions to simulate
+ * @param signers - Required signers (only public keys used for simulation)
+ * @param feePayer - Optional fee payer (defaults to first signer)
+ * @returns Detailed simulation result
+ *
+ * @example
+ * ```typescript
+ * const result = await simulateInstruction(
+ *   connection,
+ *   [createMiztakeIx],
+ *   signers
+ * );
+ *
+ * if (!result.success) {
+ *   console.error("Simulation failed:", result.error);
+ *   console.log("Logs:", result.logs);
+ * }
+ * ```
+ */
+export declare function simulateInstruction(connection: Connection, instructions: TransactionInstruction[], signers: SignerInfo[], feePayer?: PublicKey): Promise<DetailedSimulationResult>;
+/**
+ * Estimate fees for instructions
+ *
+ * @param connection - Solana connection
+ * @param instructions - Instructions to estimate fees for
+ * @param feePayer - Fee payer public key
+ * @returns Fee estimation with base fee and compute units
+ *
+ * @example
+ * ```typescript
+ * const estimate = await estimateFees(
+ *   connection,
+ *   instructions,
+ *   wallet.publicKey
+ * );
+ *
+ * console.log(`Estimated cost: ${estimate.totalEstimatedCost} lamports`);
+ * console.log(`Compute units: ${estimate.estimatedComputeUnits}`);
+ * ```
+ */
+export declare function estimateFees(connection: Connection, instructions: TransactionInstruction[], feePayer: PublicKey): Promise<FeeEstimate>;
+/**
+ * Dry run an instruction and check if it will succeed
+ *
+ * @param connection - Solana connection
+ * @param instructions - Instructions to check
+ * @param signers - Required signers
+ * @returns Whether the instruction will succeed and any error message
+ *
+ * @example
+ * ```typescript
+ * const { willSucceed, error, logs } = await dryRun(
+ *   connection,
+ *   instructions,
+ *   signers
+ * );
+ *
+ * if (!willSucceed) {
+ *   console.error("Transaction will fail:", error);
+ *   return;
+ * }
+ *
+ * // Proceed with actual transaction
+ * ```
+ */
+export declare function dryRun(connection: Connection, instructions: TransactionInstruction[], signers: SignerInfo[]): Promise<{
+    willSucceed: boolean;
+    error?: string;
+    logs: string[];
+    unitsConsumed: number;
+}>;
+/**
+ * Get compute unit usage for instructions
+ * Useful for optimizing compute budget
+ *
+ * @param connection - Solana connection
+ * @param instructions - Instructions to measure
+ * @param signers - Required signers
+ * @returns Compute units consumed
+ */
+export declare function getComputeUnits(connection: Connection, instructions: TransactionInstruction[], signers: SignerInfo[]): Promise<number>;
+/**
+ * Add optimal compute budget to instructions
+ * Simulates first to determine actual usage, then adds buffer
+ *
+ * @param connection - Solana connection
+ * @param instructions - Base instructions
+ * @param signers - Required signers
+ * @param buffer - Buffer multiplier (default 1.2 = 20% buffer)
+ * @returns Instructions with compute budget prepended
+ */
+export declare function addOptimalComputeBudget(connection: Connection, instructions: TransactionInstruction[], signers: SignerInfo[], buffer?: number): Promise<TransactionInstruction[]>;

package/dist/utils/simulationHelpers.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulateInstruction = simulateInstruction;
+exports.estimateFees = estimateFees;
+exports.dryRun = dryRun;
+exports.getComputeUnits = getComputeUnits;
+exports.addOptimalComputeBudget = addOptimalComputeBudget;
+const web3_js_1 = require("@solana/web3.js");
+/**
+ * Simulate an instruction without sending it
+ *
+ * @param connection - Solana connection
+ * @param instructions - Instructions to simulate
+ * @param signers - Required signers (only public keys used for simulation)
+ * @param feePayer - Optional fee payer (defaults to first signer)
+ * @returns Detailed simulation result
+ *
+ * @example
+ * ```typescript
+ * const result = await simulateInstruction(
+ *   connection,
+ *   [createMiztakeIx],
+ *   signers
+ * );
+ *
+ * if (!result.success) {
+ *   console.error("Simulation failed:", result.error);
+ *   console.log("Logs:", result.logs);
+ * }
+ * ```
+ */
+async function simulateInstruction(connection, instructions, signers, feePayer) {
+    const payer = feePayer || signers[0]?.publicKey;
+    if (!payer) {
+        throw new Error("At least one signer required for simulation");
+    }
+    const transaction = new web3_js_1.Transaction();
+    for (const ix of instructions) {
+        transaction.add(ix);
+    }
+    transaction.feePayer = payer;
+    const { blockhash } = await connection.getLatestBlockhash();
+    transaction.recentBlockhash = blockhash;
+    try {
+        const simulation = await connection.simulateTransaction(transaction, undefined, [...signers.map((s) => s.publicKey)]);
+        return {
+            success: simulation.value.err === null,
+            logs: simulation.value.logs || [],
+            unitsConsumed: simulation.value.unitsConsumed || 0,
+            error: simulation.value.err
+                ? JSON.stringify(simulation.value.err)
+                : undefined,
+            returnData: simulation.value.returnData || undefined,
+            accounts: simulation.value.accounts || undefined,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            logs: [],
+            unitsConsumed: 0,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Estimate fees for instructions
+ *
+ * @param connection - Solana connection
+ * @param instructions - Instructions to estimate fees for
+ * @param feePayer - Fee payer public key
+ * @returns Fee estimation with base fee and compute units
+ *
+ * @example
+ * ```typescript
+ * const estimate = await estimateFees(
+ *   connection,
+ *   instructions,
+ *   wallet.publicKey
+ * );
+ *
+ * console.log(`Estimated cost: ${estimate.totalEstimatedCost} lamports`);
+ * console.log(`Compute units: ${estimate.estimatedComputeUnits}`);
+ * ```
+ */
+async function estimateFees(connection, instructions, feePayer) {
+    const transaction = new web3_js_1.Transaction();
+    for (const ix of instructions) {
+        transaction.add(ix);
+    }
+    transaction.feePayer = feePayer;
+    const { blockhash } = await connection.getLatestBlockhash();
+    transaction.recentBlockhash = blockhash;
+    // Get base fee
+    const message = transaction.compileMessage();
+    const feeResponse = await connection.getFeeForMessage(message);
+    const baseFee = feeResponse.value || 5000;
+    // Simulate to get compute units
+    let estimatedComputeUnits = 200000; // Default estimate
+    try {
+        const simulation = await connection.simulateTransaction(transaction);
+        if (simulation.value.unitsConsumed) {
+            estimatedComputeUnits = simulation.value.unitsConsumed;
+        }
+    }
+    catch (error) {
+        // Use default if simulation fails
+    }
+    // Calculate recommended priority fee (optional)
+    const recommendedPriorityFee = Math.ceil(estimatedComputeUnits * 0.000001); // 1 micro-lamport per CU
+    return {
+        baseFee,
+        estimatedComputeUnits,
+        recommendedPriorityFee,
+        totalEstimatedCost: baseFee + recommendedPriorityFee,
+    };
+}
+/**
+ * Dry run an instruction and check if it will succeed
+ *
+ * @param connection - Solana connection
+ * @param instructions - Instructions to check
+ * @param signers - Required signers
+ * @returns Whether the instruction will succeed and any error message
+ *
+ * @example
+ * ```typescript
+ * const { willSucceed, error, logs } = await dryRun(
+ *   connection,
+ *   instructions,
+ *   signers
+ * );
+ *
+ * if (!willSucceed) {
+ *   console.error("Transaction will fail:", error);
+ *   return;
+ * }
+ *
+ * // Proceed with actual transaction
+ * ```
+ */
+async function dryRun(connection, instructions, signers) {
+    const result = await simulateInstruction(connection, instructions, signers);
+    return {
+        willSucceed: result.success,
+        error: result.error,
+        logs: result.logs,
+        unitsConsumed: result.unitsConsumed,
+    };
+}
+/**
+ * Get compute unit usage for instructions
+ * Useful for optimizing compute budget
+ *
+ * @param connection - Solana connection
+ * @param instructions - Instructions to measure
+ * @param signers - Required signers
+ * @returns Compute units consumed
+ */
+async function getComputeUnits(connection, instructions, signers) {
+    const result = await simulateInstruction(connection, instructions, signers);
+    return result.unitsConsumed;
+}
+/**
+ * Add optimal compute budget to instructions
+ * Simulates first to determine actual usage, then adds buffer
+ *
+ * @param connection - Solana connection
+ * @param instructions - Base instructions
+ * @param signers - Required signers
+ * @param buffer - Buffer multiplier (default 1.2 = 20% buffer)
+ * @returns Instructions with compute budget prepended
+ */
+async function addOptimalComputeBudget(connection, instructions, signers, buffer = 1.2) {
+    const computeUnits = await getComputeUnits(connection, instructions, signers);
+    const optimalUnits = Math.ceil(computeUnits * buffer);
+    return [
+        web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({
+            units: optimalUnits,
+        }),
+        ...instructions,
+    ];
+}

package/dist/utils/tierPenalty.d.ts

@@ -0,0 +1,9 @@
+import { BN } from "@coral-xyz/anchor";
+import { SeasonDepositTier } from "../types";
+/**
+ * Tier-based per-window penalty amount (base units, 7 decimals).
+ *
+ * This is used both by optimistic updates and by instruction builders that need
+ * to mirror on-chain accounting (refund vs bonus portions).
+ */
+export declare function getTierPenaltyPerWindow(tier: SeasonDepositTier): BN;

package/dist/utils/tierPenalty.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTierPenaltyPerWindow = getTierPenaltyPerWindow;
+const anchor_1 = require("@coral-xyz/anchor");
+/**
+ * Tier-based per-window penalty amount (base units, 7 decimals).
+ *
+ * This is used both by optimistic updates and by instruction builders that need
+ * to mirror on-chain accounting (refund vs bonus portions).
+ */
+function getTierPenaltyPerWindow(tier) {
+    // Base units (7 decimals): 1 MIZD = 10_000_000
+    if ("copper" in tier)
+        return new anchor_1.BN(1000000); // 0.1 MIZD
+    if ("silver" in tier)
+        return new anchor_1.BN(10000000); // 1 MIZD
+    if ("gold" in tier)
+        return new anchor_1.BN(100000000); // 10 MIZD
+    if ("platinum" in tier)
+        return new anchor_1.BN(1000000000); // 100 MIZD
+    if ("mithril" in tier)
+        return new anchor_1.BN(10000000000); // 1,000 MIZD
+    throw new Error("Unknown depositTier");
+}

package/dist/utils/transactionBuilder.d.ts

@@ -0,0 +1,77 @@
+import { Connection, Transaction, TransactionInstruction, PublicKey, VersionedTransaction, SimulatedTransactionResponse, Commitment } from "@solana/web3.js";
+import { SignerInfo } from "./signerHelpers";
+/**
+ * Wallet interface for signing
+ */
+export interface WalletAdapter {
+    publicKey: PublicKey;
+    signTransaction<T extends Transaction | VersionedTransaction>(tx: T): Promise<T>;
+    signAllTransactions<T extends Transaction | VersionedTransaction>(txs: T[]): Promise<T[]>;
+}
+/**
+ * Transaction send options
+ */
+export interface SendOptions {
+    commitment?: Commitment;
+    skipPreflight?: boolean;
+    maxRetries?: number;
+    preflightCommitment?: Commitment;
+}
+/**
+ * Simulation result
+ */
+export interface SimulationResult {
+    success: boolean;
+    logs: string[];
+    unitsConsumed: number;
+    error?: string;
+    returnData?: SimulatedTransactionResponse["returnData"];
+}
+/**
+ * Transaction Builder for Proof of Miztake instructions
+ * Handles transaction construction, signing, and sending
+ */
+export declare class TransactionBuilder {
+    private connection;
+    private wallets;
+    constructor(connection: Connection, wallets: Map<string, WalletAdapter>);
+    /**
+     * Build a transaction from instructions
+     */
+    buildTransaction(instructions: TransactionInstruction[], feePayer: PublicKey, options?: {
+        addComputeBudget?: boolean;
+        computeUnits?: number;
+        priorityFee?: number;
+    }): Promise<Transaction>;
+    /**
+     * Sign a transaction with required signers
+     */
+    signTransaction(transaction: Transaction, signers: SignerInfo[]): Promise<Transaction>;
+    /**
+     * Build, sign, and send a transaction
+     */
+    buildSignAndSend(instructions: TransactionInstruction[], signers: SignerInfo[], options?: SendOptions & {
+        addComputeBudget?: boolean;
+        computeUnits?: number;
+        priorityFee?: number;
+    }): Promise<string>;
+    /**
+     * Simulate a transaction without sending
+     */
+    simulate(instructions: TransactionInstruction[], signers: SignerInfo[]): Promise<SimulationResult>;
+    /**
+     * Estimate fees for a transaction
+     */
+    estimateFees(instructions: TransactionInstruction[], feePayer: PublicKey): Promise<{
+        baseFee: number;
+        estimatedComputeUnits: number;
+    }>;
+    /**
+     * Build multiple transactions if instructions exceed size limits
+     */
+    buildBatchTransactions(instructions: TransactionInstruction[], feePayer: PublicKey, maxInstructionsPerTx?: number): Promise<Transaction[]>;
+}
+/**
+ * Quick helper to build and send without creating a TransactionBuilder instance
+ */
+export declare function quickSend(connection: Connection, instructions: TransactionInstruction[], signers: SignerInfo[], wallets: Map<string, WalletAdapter>, options?: SendOptions): Promise<string>;

package/dist/utils/transactionBuilder.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionBuilder = void 0;
+exports.quickSend = quickSend;
+const web3_js_1 = require("@solana/web3.js");
+/**
+ * Transaction Builder for Proof of Miztake instructions
+ * Handles transaction construction, signing, and sending
+ */
+class TransactionBuilder {
+    constructor(connection, wallets) {
+        this.connection = connection;
+        this.wallets = wallets;
+    }
+    /**
+     * Build a transaction from instructions
+     */
+    async buildTransaction(instructions, feePayer, options) {
+        const transaction = new web3_js_1.Transaction();
+        // Add compute budget if requested
+        if (options?.addComputeBudget) {
+            if (options.computeUnits) {
+                transaction.add(web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({
+                    units: options.computeUnits,
+                }));
+            }
+            if (options.priorityFee) {
+                transaction.add(web3_js_1.ComputeBudgetProgram.setComputeUnitPrice({
+                    microLamports: options.priorityFee,
+                }));
+            }
+        }
+        // Add instructions
+        for (const ix of instructions) {
+            transaction.add(ix);
+        }
+        // Set fee payer and recent blockhash
+        transaction.feePayer = feePayer;
+        const { blockhash, lastValidBlockHeight } = await this.connection.getLatestBlockhash();
+        transaction.recentBlockhash = blockhash;
+        return transaction;
+    }
+    /**
+     * Sign a transaction with required signers
+     */
+    async signTransaction(transaction, signers) {
+        for (const signerInfo of signers) {
+            const wallet = this.wallets.get(signerInfo.role);
+            if (!wallet) {
+                throw new Error(`No wallet provided for role: ${signerInfo.role}`);
+            }
+            if (!wallet.publicKey.equals(signerInfo.publicKey)) {
+                throw new Error(`Wallet mismatch for role ${signerInfo.role}: expected ${signerInfo.publicKey.toBase58()}, got ${wallet.publicKey.toBase58()}`);
+            }
+            transaction = await wallet.signTransaction(transaction);
+        }
+        return transaction;
+    }
+    /**
+     * Build, sign, and send a transaction
+     */
+    async buildSignAndSend(instructions, signers, options) {
+        // Determine fee payer (first signer by default)
+        const feePayer = signers[0]?.publicKey;
+        if (!feePayer) {
+            throw new Error("At least one signer required");
+        }
+        // Build transaction
+        const transaction = await this.buildTransaction(instructions, feePayer, options);
+        // Sign transaction
+        const signedTx = await this.signTransaction(transaction, signers);
+        // Send transaction
+        const signature = await this.connection.sendRawTransaction(signedTx.serialize(), {
+            skipPreflight: options?.skipPreflight ?? false,
+            preflightCommitment: options?.preflightCommitment ?? "confirmed",
+            maxRetries: options?.maxRetries,
+        });
+        // Confirm transaction
+        await this.connection.confirmTransaction(signature, options?.commitment ?? "confirmed");
+        return signature;
+    }
+    /**
+     * Simulate a transaction without sending
+     */
+    async simulate(instructions, signers) {
+        const feePayer = signers[0]?.publicKey;
+        if (!feePayer) {
+            throw new Error("At least one signer required for simulation");
+        }
+        const transaction = await this.buildTransaction(instructions, feePayer);
+        try {
+            const simulation = await this.connection.simulateTransaction(transaction);
+            return {
+                success: simulation.value.err === null,
+                logs: simulation.value.logs || [],
+                unitsConsumed: simulation.value.unitsConsumed || 0,
+                error: simulation.value.err
+                    ? JSON.stringify(simulation.value.err)
+                    : undefined,
+                returnData: simulation.value.returnData,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                logs: [],
+                unitsConsumed: 0,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Estimate fees for a transaction
+     */
+    async estimateFees(instructions, feePayer) {
+        const transaction = await this.buildTransaction(instructions, feePayer);
+        // Get fee for transaction
+        const message = transaction.compileMessage();
+        const baseFee = await this.connection.getFeeForMessage(message);
+        // Simulate to get compute units
+        const simulation = await this.connection.simulateTransaction(transaction);
+        return {
+            baseFee: baseFee.value || 5000,
+            estimatedComputeUnits: simulation.value.unitsConsumed || 200000,
+        };
+    }
+    /**
+     * Build multiple transactions if instructions exceed size limits
+     */
+    async buildBatchTransactions(instructions, feePayer, maxInstructionsPerTx = 10) {
+        const transactions = [];
+        for (let i = 0; i < instructions.length; i += maxInstructionsPerTx) {
+            const batch = instructions.slice(i, i + maxInstructionsPerTx);
+            const tx = await this.buildTransaction(batch, feePayer);
+            transactions.push(tx);
+        }
+        return transactions;
+    }
+}
+exports.TransactionBuilder = TransactionBuilder;
+/**
+ * Quick helper to build and send without creating a TransactionBuilder instance
+ */
+async function quickSend(connection, instructions, signers, wallets, options) {
+    const builder = new TransactionBuilder(connection, wallets);
+    return builder.buildSignAndSend(instructions, signers, options);
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "proof-of-take-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for Proof of Take Solana program",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "check:idl": "node scripts/check-idl-drift.js",
+    "build": "tsc && cp -r src/idl/*.json dist/idl/",
+    "watch": "tsc --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run check:idl && npm run clean && npm run build"
+  },
+  "keywords": [
+    "solana",
+    "anchor",
+    "proof-of-take",
+    "blockchain",
+    "web3",
+    "take",
+    "token"
+  ],
+  "author": "Proof of Take Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proof-of-take/proof-of-take.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@coral-xyz/anchor": "^0.32.1",
+    "@solana/web3.js": "^1.95.0",
+    "@solana/spl-token": "^0.4.0"
+  },
+  "devDependencies": {
+    "@coral-xyz/anchor": "^0.32.1",
+    "@solana/web3.js": "^1.95.8",
+    "@solana/spl-token": "^0.4.8",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LIBRARY_GUIDE.md",
+    "FINAL_USAGE.md"
+  ]
+}