@zemyth/raise-sdk 0.1.0

package/dist/instructions/index.d.cts

@@ -0,0 +1,452 @@
+import { BN, Program } from '@coral-xyz/anchor';
+import { PublicKey, Keypair } from '@solana/web3.js';
+
+/**
+ * Raise Instruction Builders
+ *
+ * All instruction builder functions for the Raise program.
+ * These return transaction signatures when called with RPC.
+ */
+
+type AnyProgram = Program<any>;
+/**
+ * Initialize admin config (deploy-time only)
+ */
+declare function initializeAdmin(program: AnyProgram, admin: PublicKey, payer: PublicKey): Promise<string>;
+/**
+ * Propose admin transfer to new admin
+ */
+declare function transferAdmin(program: AnyProgram, adminKeypair: Keypair, newAdmin: PublicKey): Promise<string>;
+/**
+ * Accept admin transfer
+ */
+declare function acceptAdmin(program: AnyProgram, newAuthority: PublicKey): Promise<string>;
+/**
+ * TierConfig input type for initializeProject
+ * Matches the on-chain TierConfig struct
+ */
+interface TierConfigInput {
+    /** USDC amount per lot */
+    amount: BN;
+    /** Maximum lots available */
+    maxLots: number;
+    /** Token allocation per $1 invested */
+    tokenRatio: BN;
+    /** Vote weight multiplier (basis points, 100 = 1.0x) */
+    voteMultiplier: number;
+}
+/**
+ * TokenomicsArgs input type for initializeProject (ZTM v2.0)
+ * Matches the on-chain TokenomicsArgs struct
+ */
+interface TokenomicsInput {
+    /** Token symbol as 8-byte array (2-8 chars uppercase, padded with 0s) */
+    tokenSymbol: number[];
+    /** Total token supply */
+    totalSupply: BN;
+    /** Investor allocation in basis points (e.g., 4000 = 40%) */
+    investorAllocationBps: number;
+    /** LP token allocation in basis points */
+    lpTokenAllocationBps: number;
+    /** LP USDC allocation in basis points (min 500 = 5% of raised USDC) */
+    lpUsdcAllocationBps: number;
+    /** Founder allocation in basis points (optional) */
+    founderAllocationBps?: number | null;
+    /** Treasury allocation in basis points (optional) */
+    treasuryAllocationBps?: number | null;
+    /** Founder wallet for vesting (required if founder_allocation_bps > 0) */
+    founderWallet?: PublicKey | null;
+    /** Vesting duration in months (required if founder_allocation_bps > 0) */
+    vestingDurationMonths?: number | null;
+    /** Cliff period in months (optional) */
+    cliffMonths?: number | null;
+}
+/**
+ * Helper to convert string symbol to 8-byte array
+ */
+declare function symbolToBytes(symbol: string): number[];
+/** Minimum deadline duration from current time (7 days in production, 60s in dev) */
+declare const MIN_DEADLINE_DURATION_SECONDS_PROD = 604800;
+declare const MIN_DEADLINE_DURATION_SECONDS_DEV = 60;
+/** Maximum deadline duration from current time (1 year) */
+declare const MAX_DEADLINE_DURATION_SECONDS = 31536000;
+/**
+ * Calculate a valid milestone deadline
+ *
+ * @param daysFromNow - Number of days from now to set deadline
+ * @param isDev - Use dev mode (60s min) or production mode (7 days min)
+ * @returns BN timestamp for the deadline
+ */
+declare function calculateDeadline(daysFromNow: number, isDev?: boolean): BN;
+/**
+ * Create a deadline that's the minimum allowed duration from now
+ *
+ * @param isDev - Use dev mode (60s min) or production mode (7 days min)
+ * @returns BN timestamp for the minimum valid deadline
+ */
+declare function minDeadline(isDev?: boolean): BN;
+/**
+ * Validate a deadline is within allowed bounds
+ *
+ * @param deadline - BN timestamp to validate
+ * @param isDev - Use dev mode (60s min) or production mode (7 days min)
+ * @returns { valid: boolean, error?: string }
+ */
+declare function validateDeadline(deadline: BN, isDev?: boolean): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Initialize a new project with founder-configured tiers and tokenomics (ZTM v2.0)
+ *
+ * @param milestone1Deadline - Unix timestamp for M1 deadline (required)
+ *   Must be >= current_time + MIN_DEADLINE_DURATION_SECONDS (7 days prod, 60s dev)
+ *   Must be <= current_time + MAX_DEADLINE_DURATION_SECONDS (1 year)
+ */
+declare function initializeProject(program: AnyProgram, args: {
+    projectId: BN;
+    fundingGoal: BN;
+    metadataUri: string;
+    /** Founder-configured tiers (1-10 tiers, sorted ascending by amount) */
+    tiers: TierConfigInput[];
+    /** ZTM v2.0: Tokenomics configuration */
+    tokenomics: TokenomicsInput;
+    /** Milestone 1 deadline - Unix timestamp (required) */
+    milestone1Deadline: BN;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Submit project for approval
+ */
+declare function submitForApproval(program: AnyProgram, projectId: BN, founder: PublicKey): Promise<string>;
+/**
+ * Approve project (admin only)
+ * ZTM v2.0: This now deploys the token and creates all vaults
+ */
+declare function approveProject(program: AnyProgram, args: {
+    projectId: BN;
+    /** USDC mint address (for creating lp_usdc_vault) */
+    usdcMint: PublicKey;
+}, adminKeypair: Keypair): Promise<string>;
+/**
+ * Create a milestone for a project
+ */
+declare function createMilestone(program: AnyProgram, args: {
+    projectId: BN;
+    milestoneIndex: number;
+    percentage: number;
+    description: string;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Submit milestone for review
+ */
+declare function submitMilestone(program: AnyProgram, projectId: BN, milestoneIndex: number, founder: PublicKey): Promise<string>;
+/**
+ * Vote on a milestone
+ *
+ * Automatically fetches the milestone to get the current voting_round
+ * for proper vote PDA derivation. This supports re-voting after milestone failure.
+ */
+declare function voteOnMilestone(program: AnyProgram, args: {
+    projectId: BN;
+    milestoneIndex: number;
+    nftMint: PublicKey | string;
+    choice: {
+        good: object;
+    } | {
+        bad: object;
+    };
+}, voter: PublicKey): Promise<string>;
+/**
+ * Finalize voting on a milestone
+ */
+declare function finalizeVoting(program: AnyProgram, projectId: BN, milestoneIndex: number): Promise<string>;
+/**
+ * Claim milestone funds (for founders)
+ *
+ * ZTM v2.0: Transfers USDC from escrow to founder's account.
+ * - Regular milestones: Full payout to founder (no LP deduction)
+ * - Final milestone: LP USDC reserved for PCL, triggers MAE
+ *
+ * @param nextMilestoneDeadline - Deadline for next milestone (required for non-final milestones)
+ *   Must be >= current_time + MIN_DEADLINE_DURATION_SECONDS (7 days prod, 60s dev)
+ *   Must be <= current_time + MAX_DEADLINE_DURATION_SECONDS (1 year)
+ *   Set to BN(0) for final milestone claims (no next milestone exists)
+ */
+declare function claimMilestoneFunds(program: AnyProgram, args: {
+    projectId: BN;
+    milestoneIndex: number;
+    founderUsdcAccount: PublicKey;
+    escrowTokenAccount: PublicKey;
+    /** Deadline for next milestone - required for non-final milestones, use BN(0) for final */
+    nextMilestoneDeadline: BN;
+    /** Next milestone PDA - required for non-final milestones */
+    nextMilestonePda?: PublicKey;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Resubmit a failed milestone for rework (Failed → InProgress)
+ *
+ * This allows founders to iterate on a failed milestone by transitioning it
+ * back to InProgress state with cleared voting state for a fresh voting cycle.
+ * The consecutive_failures counter is NOT reset (tracked at project level).
+ * Unlimited rework attempts are allowed.
+ */
+declare function resubmitMilestone(program: AnyProgram, args: {
+    projectId: BN;
+    milestoneIndex: number;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Set milestone deadline for founder to commit submission date
+ *
+ * Founders must set deadlines for milestones to provide visibility to investors.
+ * Deadline must be at least 7 days from now and at most 1 year from now.
+ * Can only be set on Proposed, Approved, or InProgress milestones.
+ */
+declare function setMilestoneDeadline(program: AnyProgram, args: {
+    projectId: BN;
+    milestoneIndex: number;
+    /** Unix timestamp for the deadline */
+    deadline: BN;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Extend milestone deadline (max 3 extensions per milestone)
+ *
+ * Founders can extend a deadline up to 3 times before it passes.
+ * Must be called BEFORE the current deadline passes.
+ * New deadline must be later than current deadline.
+ */
+declare function extendMilestoneDeadline(program: AnyProgram, args: {
+    projectId: BN;
+    milestoneIndex: number;
+    /** New deadline timestamp (must be > current deadline) */
+    newDeadline: BN;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Invest in a project
+ *
+ * This creates an investment NFT and transfers USDC to the project escrow.
+ * The investmentCount should be fetched from the project account before calling.
+ */
+declare function invest(program: AnyProgram, args: {
+    projectId: BN;
+    amount: BN;
+    investorTokenAccount: PublicKey;
+    escrowTokenAccount: PublicKey;
+    investmentCount: number;
+}, investor: PublicKey): Promise<string>;
+/**
+ * Cancel investment within 24-hour cooling-off period
+ */
+declare function cancelInvestment(program: AnyProgram, args: {
+    projectId: BN;
+    nftMint: PublicKey;
+    investorNftAccount: PublicKey;
+    investorUsdcAccount: PublicKey;
+    escrowTokenAccount: PublicKey;
+}, investor: PublicKey): Promise<string>;
+/**
+ * Propose a pivot
+ */
+declare function proposePivot(program: AnyProgram, args: {
+    projectId: BN;
+    newMetadataUri: string;
+    newMilestones: Array<{
+        percentage: number;
+        description: string;
+    }>;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Approve pivot proposal (admin only)
+ */
+declare function approvePivot(program: AnyProgram, projectId: BN, adminKeypair: Keypair): Promise<string>;
+/**
+ * Withdraw from pivot during 7-day window
+ */
+declare function withdrawFromPivot(program: AnyProgram, args: {
+    projectId: BN;
+    pivotCount: number;
+    nftMint: PublicKey;
+    investorTokenAccount: PublicKey;
+    escrowTokenAccount: PublicKey;
+    milestoneAccounts: PublicKey[];
+}, investor: PublicKey): Promise<string>;
+/**
+ * Finalize pivot after 7-day window
+ *
+ * IMPORTANT: When old_milestone_count == new_milestone_count, the milestone PDAs are
+ * the same and get reinitialized in-place. In this case, only pass the milestone
+ * accounts once (not twice as old+new).
+ */
+declare function finalizePivot(program: AnyProgram, args: {
+    projectId: BN;
+    pivotCount: number;
+    milestoneAccounts: PublicKey[];
+}, authority: PublicKey): Promise<string>;
+/**
+ * Set TGE date and token mint
+ */
+declare function setTgeDate(program: AnyProgram, args: {
+    projectId: BN;
+    tgeDate: BN;
+    tokenMint: PublicKey;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Deposit tokens for investor distribution
+ */
+declare function depositTokens(program: AnyProgram, args: {
+    projectId: BN;
+    amount: BN;
+    tokenMint: PublicKey;
+    founderTokenAccount: PublicKey;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Claim project tokens using Investment NFT
+ */
+declare function claimTokens(program: AnyProgram, args: {
+    projectId: BN;
+    nftMint: PublicKey;
+    investorNftAccount: PublicKey;
+    investorTokenAccount: PublicKey;
+    projectTokenVault: PublicKey;
+}, investor: PublicKey): Promise<string>;
+/**
+ * Report scam during 30-day post-TGE window
+ */
+declare function reportScam(program: AnyProgram, args: {
+    projectId: BN;
+    nftMint: PublicKey;
+}, reporter: PublicKey): Promise<string>;
+/**
+ * Release 10% holdback to founder after 30 days
+ */
+declare function releaseHoldback(program: AnyProgram, args: {
+    projectId: BN;
+    founderTokenAccount: PublicKey;
+}): Promise<string>;
+/**
+ * Check for abandonment (90 days inactivity)
+ */
+declare function checkAbandonment(program: AnyProgram, projectId: BN, milestoneIndex?: number): Promise<string>;
+/**
+ * Claim refund after abandonment
+ *
+ * @param milestoneCount - Number of milestones in the project (used to derive milestone PDAs for remainingAccounts)
+ *                         The program calculates unreleased funds by iterating through milestone accounts.
+ */
+declare function claimRefund(program: AnyProgram, args: {
+    projectId: BN;
+    nftMint: PublicKey;
+    investorNftAccount: PublicKey;
+    investorUsdcAccount: PublicKey;
+    escrowTokenAccount: PublicKey;
+    milestoneCount?: number;
+}, investor: PublicKey): Promise<string>;
+/**
+ * Claim investor tokens from a passed milestone (whitepaper: manual claim model)
+ *
+ * ZTM v2.0: Per whitepaper, investors manually claim their tokens after a milestone passes.
+ * This replaces the batch distribution model with investor-initiated per-NFT claims.
+ *
+ * @param milestoneIndex - The milestone index to claim tokens from
+ * @param nftMint - The NFT mint that proves investment ownership
+ * @param investorTokenAccount - Investor's token account to receive claimed tokens
+ */
+declare function claimInvestorTokens(program: AnyProgram, args: {
+    projectId: BN;
+    /** Milestone index to claim tokens from */
+    milestoneIndex: number;
+    /** NFT mint that proves investment ownership */
+    nftMint: PublicKey;
+    /** Investor's token account to receive claimed tokens */
+    investorTokenAccount: PublicKey;
+}, investor: PublicKey): Promise<string>;
+/**
+ * Distribute tokens to NFT holders for a milestone
+ *
+ * ZTM v2.0: Called by cranker after finalize_voting sets distribution_pending = true.
+ * Processes batch of investments, transferring unlocked tokens to NFT holders.
+ *
+ * @deprecated Use claimInvestorTokens instead (whitepaper manual claim model)
+ *
+ * @param investments - Array of { investmentPda, investorTokenAccount } pairs
+ *   Each pair represents an investor's investment and their token account to receive tokens.
+ *   Max batch size: 10 investments per call.
+ */
+declare function distributeTokens(program: AnyProgram, args: {
+    projectId: BN;
+    milestoneIndex: number;
+    /** Investment and token account pairs to process */
+    investments: Array<{
+        investmentPda: PublicKey;
+        investorTokenAccount: PublicKey;
+    }>;
+}, payer: PublicKey): Promise<string>;
+/**
+ * Complete token distribution for a milestone
+ *
+ * ZTM v2.0: Marks distribution as complete after all batches have been processed.
+ * Permissionless - anyone can call this to finalize a distribution.
+ */
+declare function completeDistribution(program: AnyProgram, args: {
+    projectId: BN;
+    milestoneIndex: number;
+}, payer: PublicKey): Promise<string>;
+/**
+ * Claim exit window refund during 3-failure voluntary exit window
+ * Per whitepaper: 3 consecutive failures trigger 7-day voluntary exit window
+ * Investors can claim proportional share of unreleased USDC escrow funds
+ */
+declare function claimExitWindowRefund(program: AnyProgram, args: {
+    projectId: BN;
+    nftMint: PublicKey;
+    investorNftAccount: PublicKey;
+    escrowTokenAccount: PublicKey;
+    investorTokenAccount: PublicKey;
+    milestoneAccounts?: PublicKey[];
+}, investor: PublicKey): Promise<string>;
+/**
+ * Initialize founder vesting after MAE (Market Access Event)
+ *
+ * ZTM v2.0: Creates FounderVesting PDA with vesting schedule from Tokenomics.
+ * Must be called after project reaches Completed state (all milestones done).
+ * Permissionless - anyone can pay to initialize.
+ */
+declare function initializeFounderVesting(program: AnyProgram, args: {
+    projectId: BN;
+}, payer: PublicKey): Promise<string>;
+/**
+ * Claim vested tokens from founder vault
+ *
+ * ZTM v2.0: Founder claims tokens based on linear vesting schedule.
+ * Requires cliff period to pass before any tokens can be claimed.
+ */
+declare function claimVestedTokens(program: AnyProgram, args: {
+    projectId: BN;
+    /** Founder's token account to receive vested tokens */
+    founderTokenAccount: PublicKey;
+}, founder: PublicKey): Promise<string>;
+/**
+ * Force complete a stuck distribution (admin only)
+ *
+ * ZTM v2.0: Circuit breaker for when token distribution is stuck for >7 days.
+ * Marks distribution as complete so project can continue.
+ * Affected investors can use claimMissedUnlock to get their tokens.
+ */
+declare function forceCompleteDistribution(program: AnyProgram, args: {
+    projectId: BN;
+}, adminKeypair: Keypair): Promise<string>;
+/**
+ * Claim missed token unlock after force-complete distribution
+ *
+ * ZTM v2.0: Allows investors to claim tokens they missed during a stuck
+ * distribution that was force-completed by admin.
+ */
+declare function claimMissedUnlock(program: AnyProgram, args: {
+    projectId: BN;
+    nftMint: PublicKey;
+    /** Milestone index to claim for */
+    milestoneIndex: number;
+    /** Claimer's token account to receive tokens */
+    claimerTokenAccount: PublicKey;
+}, claimer: PublicKey): Promise<string>;
+
+export { MAX_DEADLINE_DURATION_SECONDS, MIN_DEADLINE_DURATION_SECONDS_DEV, MIN_DEADLINE_DURATION_SECONDS_PROD, type TokenomicsInput, acceptAdmin, approvePivot, approveProject, calculateDeadline, cancelInvestment, checkAbandonment, claimExitWindowRefund, claimInvestorTokens, claimMilestoneFunds, claimMissedUnlock, claimRefund, claimTokens, claimVestedTokens, completeDistribution, createMilestone, depositTokens, distributeTokens, extendMilestoneDeadline, finalizePivot, finalizeVoting, forceCompleteDistribution, initializeAdmin, initializeFounderVesting, initializeProject, invest, minDeadline, proposePivot, releaseHoldback, reportScam, resubmitMilestone, setMilestoneDeadline, setTgeDate, submitForApproval, submitMilestone, symbolToBytes, transferAdmin, validateDeadline, voteOnMilestone, withdrawFromPivot };