@zemyth/raise-sdk 0.1.1 → 0.1.3

package/src/client.ts

@@ -12,7 +12,7 @@ import { Connection, PublicKey, Keypair } from '@solana/web3.js';
 import * as pdas from './pdas/index.js';
 import * as accounts from './accounts/index.js';
 import * as instructions from './instructions/index.js';
-import type { TierConfig } from './types/index.js';
+import type { TierConfig, SubAllocation } from './types/index.js';
 
 /**
  * Wallet interface required by the client
@@ -158,6 +158,31 @@ export class RaiseClient {
     return pdas.getAdminConfigPDA(this.programId);
   }
 
+  getAllocationProposalPDA(projectPda: PublicKey, proposalIndex: number): PublicKey {
+    return pdas.getAllocationProposalPDA(projectPda, proposalIndex, this.programId);
+  }
+
+  getAllocationVotePDA(proposalPda: PublicKey, nftMint: PublicKey): PublicKey {
+    return pdas.getAllocationVotePDA(proposalPda, nftMint, this.programId);
+  }
+
+  getSubAllocationVestingPDA(projectPda: PublicKey, subAllocationId: number): PublicKey {
+    return pdas.getSubAllocationVestingPDA(projectPda, subAllocationId, this.programId);
+  }
+
+  getTokenomicsPDA(projectPda: PublicKey): PublicKey {
+    return pdas.getTokenomicsPDA(projectPda, this.programId);
+  }
+
+  // Per-Milestone Vesting PDAs
+  getInvestorMilestoneVestingPDA(projectPda: PublicKey, milestoneIndex: number, investmentPda: PublicKey): PublicKey {
+    return pdas.getInvestorMilestoneVestingPDA(projectPda, milestoneIndex, investmentPda, this.programId);
+  }
+
+  getFounderMilestoneVestingPDA(projectPda: PublicKey, milestoneIndex: number): PublicKey {
+    return pdas.getFounderMilestoneVestingPDA(projectPda, milestoneIndex, this.programId);
+  }
+
   // ===========================================================================
   // Account Fetchers
   // ===========================================================================
@@ -202,6 +227,38 @@ export class RaiseClient {
     return accounts.fetchAdminConfig(this.program);
   }
 
+  async fetchTokenVault(projectId: BN) {
+    return accounts.fetchTokenVault(this.program, projectId);
+  }
+
+  async fetchTokenomics(projectId: BN) {
+    return accounts.fetchTokenomics(this.program, projectId);
+  }
+
+  async fetchAllocationProposal(projectId: BN, proposalIndex: number) {
+    return accounts.fetchAllocationProposal(this.program, projectId, proposalIndex);
+  }
+
+  async fetchAllAllocationProposals(projectId: BN) {
+    return accounts.fetchAllAllocationProposals(this.program, projectId);
+  }
+
+  async fetchAllocationVote(projectId: BN, proposalIndex: number, nftMint: PublicKey) {
+    return accounts.fetchAllocationVote(this.program, projectId, proposalIndex, nftMint);
+  }
+
+  async fetchSubAllocationVesting(projectId: BN, subAllocationId: number) {
+    return accounts.fetchSubAllocationVesting(this.program, projectId, subAllocationId);
+  }
+
+  async fetchInvestorMilestoneVesting(projectId: BN, milestoneIndex: number, nftMint: PublicKey) {
+    return accounts.fetchInvestorMilestoneVesting(this.program, projectId, milestoneIndex, nftMint);
+  }
+
+  async fetchFounderMilestoneVesting(projectId: BN, milestoneIndex: number) {
+    return accounts.fetchFounderMilestoneVesting(this.program, projectId, milestoneIndex);
+  }
+
   // ===========================================================================
   // Admin Instructions
   // ===========================================================================
@@ -242,6 +299,8 @@ export class RaiseClient {
     tokenomics: instructions.TokenomicsInput;
     /** Milestone 1 deadline - Unix timestamp (required) */
     milestone1Deadline: BN;
+    /** Milestone Price Increases: Price multipliers in BPS (optional, defaults to all 10000) */
+    priceMultipliers?: number[];
   }): Promise<string> {
     return instructions.initializeProject(
       this.program,
@@ -278,6 +337,9 @@ export class RaiseClient {
     milestoneIndex: number;
     percentage: number;
     description: string;
+    vestingDurationMonths?: number | null;
+    cliffMonths?: number | null;
+    instantReleaseBps?: number | null;
   }): Promise<string> {
     return instructions.createMilestone(
       this.program,
@@ -686,6 +748,170 @@ export class RaiseClient {
     );
   }
 
+  // ===========================================================================
+  // Early Token Release Instructions
+  // ===========================================================================
+
+  /**
+   * Claim early tokens as an investor (5% of token allocation)
+   *
+   * Early Token Release: Investors can claim 5% of their token allocation
+   * 24 hours after investing. These tokens are fully liquid immediately.
+   *
+   * Prerequisites:
+   * - 24h cooling period must have passed since investment
+   * - Investment must not have already claimed early tokens
+   * - Investment must have active voting rights
+   */
+  async claimEarlyTokens(args: {
+    projectId: BN;
+    nftMint: PublicKey;
+    investorTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimEarlyTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Claim early tokens as a founder (5% of founder allocation)
+   *
+   * Early Token Release: Founders can claim 5% of their token allocation
+   * when the project becomes Funded. These tokens are fully liquid immediately.
+   *
+   * Prerequisites:
+   * - Project must be in Funded, InProgress, or Completed state
+   * - Founder must not have already claimed early tokens
+   */
+  async claimFounderEarlyTokens(args: {
+    projectId: BN;
+    founderTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimFounderEarlyTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Claim founder milestone-based tokens for a specific milestone
+   *
+   * Early Token Release: Founders can claim their milestone-based portion
+   * (default 47.5% of founder allocation) when milestones are unlocked.
+   *
+   * Prerequisites:
+   * - Milestone must be in Unlocked state
+   * - Founder must not have already claimed tokens for this milestone
+   */
+  async claimFounderMilestoneTokens(args: {
+    projectId: BN;
+    milestoneIndex: number;
+    founderTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimFounderMilestoneTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  // ===========================================================================
+  // Per-Milestone Vesting Instructions (add-per-milestone-vesting)
+  // ===========================================================================
+
+  /**
+   * Claim instant tokens for a passed milestone (investor)
+   *
+   * Per-milestone vesting: Investors claim the instant portion (e.g., 5-50%)
+   * immediately when a milestone passes. Creates vesting PDA on first claim.
+   *
+   * @param milestoneIndex - The milestone index to claim tokens from
+   * @param nftMint - The NFT mint proving investment ownership
+   * @param investorTokenAccount - Investor's token account to receive claimed tokens
+   */
+  async claimMilestoneInstantTokens(args: {
+    projectId: BN;
+    milestoneIndex: number;
+    nftMint: PublicKey;
+    investorTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimMilestoneInstantTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Claim vested tokens for a milestone after cliff period (investor)
+   *
+   * Per-milestone vesting: Investors claim vested tokens linearly after
+   * the cliff period passes. Must have already claimed instant tokens
+   * to initialize the vesting PDA.
+   *
+   * @param milestoneIndex - The milestone index to claim vested tokens from
+   * @param nftMint - The NFT mint proving investment ownership
+   * @param investorTokenAccount - Investor's token account to receive claimed tokens
+   */
+  async claimMilestoneVestedTokens(args: {
+    projectId: BN;
+    milestoneIndex: number;
+    nftMint: PublicKey;
+    investorTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimMilestoneVestedTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Claim instant tokens for a passed milestone (founder)
+   *
+   * Per-milestone vesting: Founders claim the instant portion (e.g., 5-50%)
+   * of their milestone-based allocation when a milestone passes.
+   *
+   * @param milestoneIndex - The milestone index to claim tokens from
+   * @param founderTokenAccount - Founder's token account to receive claimed tokens
+   */
+  async claimFounderMsInstantTokens(args: {
+    projectId: BN;
+    milestoneIndex: number;
+    founderTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimFounderMsInstantTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Claim vested tokens for a milestone after cliff period (founder)
+   *
+   * Per-milestone vesting: Founders claim vested tokens linearly after
+   * the cliff period passes. Must have already claimed instant tokens
+   * to initialize the vesting PDA.
+   *
+   * @param milestoneIndex - The milestone index to claim vested tokens from
+   * @param founderTokenAccount - Founder's token account to receive claimed tokens
+   */
+  async claimFounderMsVestedTokens(args: {
+    projectId: BN;
+    milestoneIndex: number;
+    founderTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimFounderMsVestedTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
   // ===========================================================================
   // Abandonment Instructions
   // ===========================================================================
@@ -712,4 +938,907 @@ export class RaiseClient {
       this.walletPublicKey
     );
   }
+
+  // ===========================================================================
+  // Sub-Allocation Vesting Instructions
+  // ===========================================================================
+
+  /**
+   * Initialize sub-allocation vesting after MAE (Market Access Event)
+   *
+   * Creates SubAllocationVesting PDA for a specific sub-allocation ID.
+   * Project must be in Completed state with MAE completed.
+   * Permissionless - anyone can pay to initialize.
+   */
+  async initializeSubAllocationVesting(args: {
+    projectId: BN;
+    subAllocationId: number;
+  }): Promise<string> {
+    return instructions.initializeSubAllocationVesting(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Claim vested tokens from a sub-allocation
+   *
+   * Only the designated recipient wallet can claim tokens.
+   * Project must be Completed and MAE must be completed.
+   */
+  async claimSubAllocationTokens(args: {
+    projectId: BN;
+    subAllocationId: number;
+    recipientTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimSubAllocationTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  // ===========================================================================
+  // Dynamic Tokenomics Instructions
+  // ===========================================================================
+
+  /**
+   * Add a sub-allocation from the reserve pool (Draft state only)
+   *
+   * Allows founders to add named allocations (advisors, marketing, etc.)
+   * from their reserve pool before submitting for approval.
+   */
+  async addSubAllocation(args: {
+    projectId: BN;
+    name: string;
+    bps: number;
+    recipient: PublicKey;
+    vestingMonths: number;
+    cliffMonths: number;
+  }): Promise<string> {
+    return instructions.addSubAllocation(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Propose an allocation change via governance (post-Draft states)
+   *
+   * Creates a 7-day voting period for investors to approve/reject
+   * a new sub-allocation from the reserve pool.
+   */
+  async proposeAllocationChange(args: {
+    projectId: BN;
+    name: string;
+    bps: number;
+    recipient: PublicKey;
+    vestingMonths: number;
+    cliffMonths: number;
+  }): Promise<string> {
+    return instructions.proposeAllocationChange(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Vote on an allocation change proposal
+   *
+   * Investors can vote for/against using their Investment NFT.
+   * Must meet 7-day hold period for voting eligibility.
+   */
+  async voteAllocationChange(args: {
+    projectId: BN;
+    proposalIndex: number;
+    nftMint: PublicKey;
+    voteFor: boolean;
+  }): Promise<string> {
+    return instructions.voteAllocationChange(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Execute an approved allocation change proposal
+   *
+   * Permissionless - anyone can call after voting ends.
+   * Proposal must have passed (>51% approval).
+   */
+  async executeAllocationChange(args: {
+    projectId: BN;
+    proposalIndex: number;
+  }): Promise<string> {
+    return instructions.executeAllocationChange(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  // ===========================================================================
+  // Dynamic Tokenomics Helpers
+  // ===========================================================================
+
+  /**
+   * Get remaining founder pool capacity for sub-allocations in basis points
+   *
+   * Calculates: founder_allocation_bps - sum(sub_allocations.bps)
+   * Sub-allocations (treasury, advisors, marketing) draw from founder's allocation pool.
+   */
+  async getRemainingFounderPool(projectId: BN): Promise<number> {
+    const tokenomics = await this.fetchTokenomics(projectId);
+    if (!tokenomics) {
+      throw new Error('Tokenomics account not found');
+    }
+
+    const founderBps = tokenomics.founderAllocationBps || 0;
+    const usedBps = (tokenomics.subAllocations || [])
+      .filter((sa: SubAllocation) => sa.bps > 0)
+      .reduce((sum: number, sa: SubAllocation) => sum + sa.bps, 0);
+
+    return founderBps - usedBps;
+  }
+
+  /**
+   * Get all active (non-executed, non-expired) allocation proposals
+   */
+  async getActiveProposals(projectId: BN) {
+    const proposals = await this.fetchAllAllocationProposals(projectId);
+    const now = Math.floor(Date.now() / 1000);
+
+    return proposals.filter((p) => {
+      const account = p.account;
+      // Filter for non-executed proposals that haven't expired
+      return !account.executed && account.votingEndsAt.toNumber() > now;
+    });
+  }
+
+  /**
+   * Get vesting status for a sub-allocation
+   *
+   * Returns claimable amount, total vested, and remaining locked tokens.
+   */
+  async getSubAllocationVestingStatus(projectId: BN, subAllocationId: number) {
+    const vesting = await this.fetchSubAllocationVesting(projectId, subAllocationId);
+    if (!vesting) {
+      return null;
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+    // Use the pre-computed timestamps from the on-chain account
+    const cliffEnd = vesting.cliffEnd.toNumber();
+    const vestingEnd = vesting.vestingEnd.toNumber();
+    const totalAmount = vesting.totalAmount.toNumber();
+    const claimedAmount = vesting.claimedAmount.toNumber();
+
+    // Before cliff - nothing vested
+    if (now < cliffEnd) {
+      return {
+        totalAmount,
+        vestedAmount: 0,
+        claimedAmount,
+        claimableAmount: 0,
+        lockedAmount: totalAmount - claimedAmount,
+        vestingProgress: 0,
+        cliffPassed: false,
+      };
+    }
+
+    // After full vesting period - everything vested
+    if (now >= vestingEnd) {
+      return {
+        totalAmount,
+        vestedAmount: totalAmount,
+        claimedAmount,
+        claimableAmount: totalAmount - claimedAmount,
+        lockedAmount: 0,
+        vestingProgress: 100,
+        cliffPassed: true,
+      };
+    }
+
+    // Linear vesting calculation
+    const vestingDuration = vestingEnd - cliffEnd;
+    const elapsed = now - cliffEnd;
+    const vestedAmount = Math.floor((totalAmount * elapsed) / vestingDuration);
+
+    return {
+      totalAmount,
+      vestedAmount,
+      claimedAmount,
+      claimableAmount: vestedAmount - claimedAmount,
+      lockedAmount: totalAmount - vestedAmount,
+      vestingProgress: Math.floor((elapsed / vestingDuration) * 100),
+      cliffPassed: true,
+    };
+  }
+
+  // ===========================================================================
+  // Milestone Price Increase Helpers
+  // ===========================================================================
+
+  /** Base price multiplier constant (10000 BPS = 1.0x) */
+  static readonly PRICE_MULTIPLIER_BASE = 10000;
+
+  /**
+   * Get the current price multiplier for a project
+   *
+   * Returns the multiplier in BPS (10000 = 1.0x, 15000 = 1.5x)
+   *
+   * Supports two modes:
+   * - Dynamic mode (priceMultipliers[0] === 0): Uses currentPriceMultiplierBps
+   *   calculated dynamically via ZEMYTH formula at each milestone claim
+   * - Static mode (legacy): Uses pre-configured priceMultipliers array lookup
+   */
+  async getCurrentMultiplier(projectId: BN): Promise<number> {
+    const project = await this.fetchProject(projectId);
+    if (!project) {
+      throw new Error('Project account not found');
+    }
+
+    const { priceMultipliers, milestonesPassed, milestoneCount, currentPriceMultiplierBps } = project;
+
+    // Check for dynamic mode sentinel (priceMultipliers[0] === 0)
+    if (priceMultipliers[0] === 0) {
+      // Dynamic mode: return the dynamically calculated multiplier
+      return currentPriceMultiplierBps || RaiseClient.PRICE_MULTIPLIER_BASE;
+    }
+
+    // Static mode (legacy): use array lookup
+    // Clamp index to valid range (0 to milestoneCount - 1)
+    const index = milestoneCount === 0
+      ? 0
+      : Math.min(milestonesPassed, milestoneCount - 1);
+
+    return priceMultipliers[index] || RaiseClient.PRICE_MULTIPLIER_BASE;
+  }
+
+  /**
+   * Check if a project uses dynamic price multiplier mode
+   */
+  async isDynamicMultiplierMode(projectId: BN): Promise<boolean> {
+    const project = await this.fetchProject(projectId);
+    if (!project) {
+      throw new Error('Project account not found');
+    }
+
+    return project.priceMultipliers[0] === 0;
+  }
+
+  /**
+   * Calculate effective tier prices with current multiplier
+   *
+   * Returns array of tiers with their effective prices after applying
+   * the current milestone multiplier.
+   */
+  async getEffectiveTierPrices(projectId: BN): Promise<Array<{
+    tierIndex: number;
+    baseAmount: BN;
+    effectiveAmount: BN;
+    multiplierBps: number;
+  }>> {
+    const project = await this.fetchProject(projectId);
+    if (!project) {
+      throw new Error('Project account not found');
+    }
+
+    const multiplier = await this.getCurrentMultiplier(projectId);
+    const tiers = project.tiers.slice(0, project.tierCount);
+
+    return tiers.map((tier: { amount: BN }, index: number) => ({
+      tierIndex: index,
+      baseAmount: tier.amount,
+      effectiveAmount: tier.amount
+        .mul(new BN(multiplier))
+        .div(new BN(RaiseClient.PRICE_MULTIPLIER_BASE)),
+      multiplierBps: multiplier,
+    }));
+  }
+
+  /**
+   * Get price schedule showing multipliers after each milestone
+   *
+   * Returns array showing what the price multiplier will be
+   * after each milestone passes.
+   *
+   * For dynamic mode projects (priceMultipliers[0] === 0), returns null
+   * as multipliers are calculated dynamically based on deadline timing.
+   */
+  async getPriceSchedule(projectId: BN): Promise<Array<{
+    afterMilestone: number;
+    multiplierBps: number;
+    multiplierPercent: number;
+  }> | null> {
+    const project = await this.fetchProject(projectId);
+    if (!project) {
+      throw new Error('Project account not found');
+    }
+
+    const { priceMultipliers, milestoneCount } = project;
+
+    // Dynamic mode: no pre-set schedule
+    if (priceMultipliers[0] === 0) {
+      return null;
+    }
+
+    // Static mode: return pre-configured schedule
+    return priceMultipliers
+      .slice(0, milestoneCount)
+      .map((multiplier: number, index: number) => ({
+        afterMilestone: index,
+        multiplierBps: multiplier,
+        multiplierPercent: multiplier / 100, // 10000 -> 100%
+      }));
+  }
+
+  /**
+   * Preview multiplier calculation for dynamic mode projects
+   *
+   * Uses the ZEMYTH formula to calculate what the multiplier would be
+   * given a specific number of remaining milestones and days to deadline.
+   *
+   * Formula: totalMultiplier = 1 + (sqrt(n) / sqrt(15)) × (1 / ln(d/7 + e))
+   *
+   * @param remainingMilestones Number of milestones left (1-10)
+   * @param daysToDeadline Days until next milestone deadline (1-365)
+   * @returns Preview of the multiplier in BPS (10000 = 1.0x, max 20000 = 2.0x)
+   */
+  previewDynamicMultiplier(remainingMilestones: number, daysToDeadline: number): number {
+    // Edge case: 0 remaining milestones = base multiplier
+    if (remainingMilestones === 0) {
+      return RaiseClient.PRICE_MULTIPLIER_BASE;
+    }
+
+    // Clamp days to reasonable range
+    const days = Math.max(1, Math.min(365, daysToDeadline));
+
+    // Integer approximation of ZEMYTH formula
+    // sqrt(n) / sqrt(15) ≈ (sqrt(n) * 1000) / 3873
+    const sqrtN = Math.sqrt(remainingMilestones) * 1000;
+    const milestoneFactor = sqrtN / 3.873;
+
+    // 1/ln(d/7 + e) approximation
+    const timeFactor = this.timeFactorLookup(days);
+
+    // Combined factor
+    const combined = (milestoneFactor * timeFactor) / 1000;
+    const bonusBps = Math.min(combined, 10000);
+
+    // Base + bonus, clamped to [10000, 20000]
+    return Math.min(20000, Math.max(10000, Math.round(10000 + bonusBps)));
+  }
+
+  /** Time factor lookup for dynamic multiplier preview (approximates 1/ln(d/7 + e) × 1000) */
+  private timeFactorLookup(days: number): number {
+    if (days <= 7) return 950 - (days * 25);
+    if (days <= 14) return 775 - ((days - 7) * 20);
+    if (days <= 30) return 635 - ((days - 14) * 8);
+    if (days <= 60) return 507 - ((days - 30) * 4);
+    if (days <= 90) return 387 - ((days - 60) * 3);
+    if (days <= 180) return 297 - ((days - 90) * 1);
+    return 250;
+  }
+
+  // ===========================================================================
+  // Linear Progressive Pricing Helpers (add-linear-progressive-pricing)
+  // ===========================================================================
+
+  /** Constants for progressive pricing */
+  static readonly TIME_ALLOCATION_PERCENT = 50;
+  static readonly MILESTONE_ALLOCATION_PERCENT = 50;
+  /** DEV MODE: Time acceleration multiplier (10 real seconds = 1 simulated day) */
+  static readonly PROGRESSIVE_TIME_MULTIPLIER = 8640;
+
+  /**
+   * Check if progressive pricing is active for a project
+   *
+   * Progressive pricing is active when milestonePeriodStartedAt > 0,
+   * meaning the first milestone period has been initialized.
+   */
+  isProgressivePricingActive(project: { milestonePeriodStartedAt: BN }): boolean {
+    return project.milestonePeriodStartedAt.gt(new BN(0));
+  }
+
+  /**
+   * Calculate time progress for a milestone period
+   *
+   * @param project Project account with progressive pricing fields
+   * @param currentTime Current unix timestamp (seconds)
+   * @returns Progress as ratio 0-1 (capped at 1.0)
+   */
+  getTimeProgress(
+    project: {
+      milestonePeriodStartedAt: BN;
+      expectedMilestoneDeadlineTs: BN;
+    },
+    currentTime: number
+  ): number {
+    const startedAt = project.milestonePeriodStartedAt.toNumber();
+    const deadline = project.expectedMilestoneDeadlineTs.toNumber();
+
+    if (startedAt === 0 || deadline <= startedAt) {
+      return 0;
+    }
+
+    // DEV MODE: Apply time acceleration (10 real seconds = 1 simulated day)
+    const rawElapsed = Math.max(0, currentTime - startedAt);
+    const elapsed = rawElapsed * RaiseClient.PROGRESSIVE_TIME_MULTIPLIER;
+    const expectedDuration = Math.max(1, deadline - startedAt);
+
+    return Math.min(1, elapsed / expectedDuration);
+  }
+
+  /**
+   * Calculate the effective multiplier including time-based component
+   *
+   * @param project Project account with progressive pricing fields
+   * @param currentTime Current unix timestamp (seconds)
+   * @returns Effective multiplier in BPS (10000 = 1.0x)
+   */
+  calculateEffectiveMultiplier(
+    project: {
+      milestonePeriodStartedAt: BN;
+      expectedMilestoneDeadlineTs: BN;
+      milestoneBaseMultiplierBps: number;
+      timeAllocationBps: number;
+      currentPriceMultiplierBps: number;
+      priceMultipliers: number[];
+    },
+    currentTime: number
+  ): number {
+    // If progressive pricing not active, use legacy behavior
+    if (!this.isProgressivePricingActive(project)) {
+      // Legacy: use currentPriceMultiplierBps or static array
+      if (project.priceMultipliers[0] === 0) {
+        return project.currentPriceMultiplierBps || RaiseClient.PRICE_MULTIPLIER_BASE;
+      }
+      return project.currentPriceMultiplierBps || RaiseClient.PRICE_MULTIPLIER_BASE;
+    }
+
+    // Progressive pricing active: base + time increment
+    const timeProgress = this.getTimeProgress(project, currentTime);
+    const timeIncrement = Math.floor(project.timeAllocationBps * timeProgress);
+
+    return project.milestoneBaseMultiplierBps + timeIncrement;
+  }
+
+  /**
+   * Preview what the milestone spike will be at a given claim time
+   *
+   * If founder claims early, unused time allocation accumulates to spike.
+   *
+   * @param project Project account with progressive pricing fields
+   * @param claimTime Unix timestamp when claim will happen
+   * @returns Object with spike details
+   */
+  previewMilestoneSpike(
+    project: {
+      milestonePeriodStartedAt: BN;
+      expectedMilestoneDeadlineTs: BN;
+      milestoneBaseMultiplierBps: number;
+      timeAllocationBps: number;
+      milestoneAllocationBps: number;
+    },
+    claimTime: number
+  ): {
+    timeProgress: number;
+    consumedTimeBps: number;
+    unusedTimeBps: number;
+    milestoneSpikeBps: number;
+    effectiveMultiplierBps: number;
+    newBaseBps: number;
+  } {
+    const timeProgress = this.getTimeProgress(project, claimTime);
+
+    const consumedTimeBps = Math.floor(project.timeAllocationBps * timeProgress);
+    const unusedTimeBps = project.timeAllocationBps - consumedTimeBps;
+    const milestoneSpikeBps = project.milestoneAllocationBps + unusedTimeBps;
+
+    const effectiveMultiplierBps = project.milestoneBaseMultiplierBps + consumedTimeBps;
+    const newBaseBps = effectiveMultiplierBps + milestoneSpikeBps;
+
+    return {
+      timeProgress,
+      consumedTimeBps,
+      unusedTimeBps,
+      milestoneSpikeBps,
+      effectiveMultiplierBps,
+      newBaseBps,
+    };
+  }
+
+  /**
+   * Get effective tier prices with time-based progressive pricing
+   *
+   * Unlike getEffectiveTierPrices which fetches the project, this takes
+   * the project and current time to calculate prices including time component.
+   */
+  getProgressiveTierPrices(
+    project: {
+      tiers: Array<{ amount: BN }>;
+      tierCount: number;
+      milestonePeriodStartedAt: BN;
+      expectedMilestoneDeadlineTs: BN;
+      milestoneBaseMultiplierBps: number;
+      timeAllocationBps: number;
+      currentPriceMultiplierBps: number;
+      priceMultipliers: number[];
+    },
+    currentTime: number
+  ): Array<{
+    tierIndex: number;
+    baseAmount: BN;
+    effectiveAmount: BN;
+    multiplierBps: number;
+    timeProgressPercent: number;
+  }> {
+    const multiplier = this.calculateEffectiveMultiplier(project, currentTime);
+    const timeProgress = this.getTimeProgress(project, currentTime);
+    const tiers = project.tiers.slice(0, project.tierCount);
+
+    return tiers.map((tier, index) => ({
+      tierIndex: index,
+      baseAmount: tier.amount,
+      effectiveAmount: tier.amount
+        .mul(new BN(multiplier))
+        .div(new BN(RaiseClient.PRICE_MULTIPLIER_BASE)),
+      multiplierBps: multiplier,
+      timeProgressPercent: Math.round(timeProgress * 100),
+    }));
+  }
+
+  // ===========================================================================
+  // Multi-Round Fundraising PDAs
+  // ===========================================================================
+
+  getFundingRoundPDA(projectPda: PublicKey, roundNumber: number): PublicKey {
+    return pdas.getFundingRoundPDA(projectPda, roundNumber, this.programId);
+  }
+
+  getRoundEscrowPDA(projectPda: PublicKey, roundNumber: number): PublicKey {
+    return pdas.getRoundEscrowPDA(projectPda, roundNumber, this.programId);
+  }
+
+  getRoundMilestonePDA(projectPda: PublicKey, roundNumber: number, milestoneIndex: number): PublicKey {
+    return pdas.getRoundMilestonePDA(projectPda, roundNumber, milestoneIndex, this.programId);
+  }
+
+  getRoundInvestmentPDA(projectPda: PublicKey, roundNumber: number, nftMint: PublicKey): PublicKey {
+    return pdas.getRoundInvestmentPDA(projectPda, roundNumber, nftMint, this.programId);
+  }
+
+  getRoundInvestorMilestoneVestingPDA(
+    projectPda: PublicKey,
+    roundNumber: number,
+    milestoneIndex: number,
+    investmentPda: PublicKey
+  ): PublicKey {
+    return pdas.getRoundInvestorMilestoneVestingPDA(
+      projectPda,
+      roundNumber,
+      milestoneIndex,
+      investmentPda,
+      this.programId
+    );
+  }
+
+  getFutureRoundVaultPDA(projectPda: PublicKey): PublicKey {
+    return pdas.getFutureRoundVaultPDA(projectPda, this.programId);
+  }
+
+  getFutureRoundTokenVaultPDA(projectPda: PublicKey): PublicKey {
+    return pdas.getFutureRoundTokenVaultPDA(projectPda, this.programId);
+  }
+
+  // ===========================================================================
+  // Multi-Round Fundraising Account Fetchers
+  // ===========================================================================
+
+  async fetchFundingRound(projectId: BN, roundNumber: number) {
+    return accounts.fetchFundingRound(this.program, projectId, roundNumber);
+  }
+
+  async fetchAllFundingRounds(projectId: BN) {
+    return accounts.fetchAllFundingRounds(this.program, projectId);
+  }
+
+  async fetchRoundMilestone(projectId: BN, roundNumber: number, milestoneIndex: number) {
+    return accounts.fetchRoundMilestone(this.program, projectId, roundNumber, milestoneIndex);
+  }
+
+  async fetchRoundInvestment(projectId: BN, roundNumber: number, nftMint: PublicKey) {
+    return accounts.fetchRoundInvestment(this.program, projectId, roundNumber, nftMint);
+  }
+
+  async fetchFutureRoundVault(projectId: BN) {
+    return accounts.fetchFutureRoundVault(this.program, projectId);
+  }
+
+  // ===========================================================================
+  // Multi-Round Fundraising Instructions
+  // ===========================================================================
+
+  /**
+   * Open a new funding round (R2, R3, R4...)
+   *
+   * Multi-Round Fundraising: Creates FundingRound PDA, round escrow,
+   * and milestone PDAs for the new round. Tokens come from FutureRoundVault.
+   *
+   * Prerequisites:
+   * - Project must be InProgress or Completed state
+   * - At least 1 milestone must have passed (for InProgress projects)
+   * - No other round currently Open
+   * - Current round must be fully funded before opening next
+   * - Must have future_round_allocation configured in tokenomics
+   */
+  async openFundingRound(args: {
+    projectId: BN;
+    roundAllocationBps: number;
+    fundingGoal: BN;
+    tiers: Array<{ amount: BN; maxLots: number; tokenRatio: BN }>;
+    milestones: Array<{
+      percentage: number;
+      description: string;
+      vestingDurationMonths?: number | null;
+      cliffMonths?: number | null;
+      instantReleaseBps?: number | null;
+    }>;
+    usdcMint: PublicKey;
+    previousFundingRoundPda?: PublicKey | null;
+  }): Promise<string> {
+    return instructions.openFundingRound(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Invest in a funding round (R2, R3, R4...)
+   *
+   * Multi-Round Fundraising: Creates investment NFT and deposits USDC
+   * to the round-specific escrow. Tokens come from FutureRoundVault.
+   */
+  async investInRound(args: {
+    projectId: BN;
+    roundNumber: number;
+    amount: BN;
+    investorTokenAccount: PublicKey;
+    investmentCount: number;
+  }): Promise<string> {
+    return instructions.investInRound(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Cancel round investment within 24-hour cooling-off period
+   *
+   * Multi-Round Fundraising: Returns USDC from round escrow,
+   * closes investment account.
+   */
+  async cancelRoundInvestment(args: {
+    projectId: BN;
+    roundNumber: number;
+    nftMint: PublicKey;
+    investorNftAccount: PublicKey;
+    investorUsdcAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.cancelRoundInvestment(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Submit round milestone for investor review
+   *
+   * Multi-Round Fundraising: Transitions milestone to UnderReview,
+   * sets voting deadline.
+   */
+  async submitRoundMilestone(args: {
+    projectId: BN;
+    roundNumber: number;
+    milestoneIndex: number;
+  }): Promise<string> {
+    return instructions.submitRoundMilestone(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Vote on a round milestone (unified voting - ANY investor can vote)
+   *
+   * Multi-Round Fundraising: R1, R2, R3... investors can all vote
+   * on any round's milestones. Investment can be from any round.
+   */
+  async voteOnRoundMilestone(args: {
+    projectId: BN;
+    roundNumber: number;
+    milestoneIndex: number;
+    nftMint: PublicKey | string;
+    choice: { good: object } | { bad: object };
+    investmentRoundNumber: number;
+  }): Promise<string> {
+    return instructions.voteOnRoundMilestone(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Finalize voting on a round milestone
+   *
+   * Multi-Round Fundraising: Processes vote results, transitions
+   * milestone to Passed or Failed state.
+   */
+  async finalizeRoundVoting(args: {
+    projectId: BN;
+    roundNumber: number;
+    milestoneIndex: number;
+  }): Promise<string> {
+    return instructions.finalizeRoundVoting(
+      this.program,
+      args
+    );
+  }
+
+  /**
+   * Claim milestone funds from a round (founder)
+   *
+   * Multi-Round Fundraising: Transfers USDC from round escrow
+   * to founder's account.
+   *
+   * @param nextMilestoneDeadline - Deadline for next milestone (required for non-final)
+   *   Set to BN(0) for final milestone claims
+   */
+  async claimRoundMilestoneFunds(args: {
+    projectId: BN;
+    roundNumber: number;
+    milestoneIndex: number;
+    founderUsdcAccount: PublicKey;
+    nextMilestoneDeadline: BN;
+  }): Promise<string> {
+    return instructions.claimRoundMilestoneFunds(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Claim instant tokens for a round milestone (investor)
+   *
+   * Multi-Round Fundraising: R2+ investors claim instant portion
+   * when milestone passes. Tokens come from FutureRoundVault.
+   */
+  async claimRoundInstantTokens(args: {
+    projectId: BN;
+    roundNumber: number;
+    milestoneIndex: number;
+    nftMint: PublicKey;
+    investorTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimRoundInstantTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Claim vested tokens for a round milestone (investor)
+   *
+   * Multi-Round Fundraising: R2+ investors claim vested portion
+   * after cliff period. Tokens come from FutureRoundVault.
+   */
+  async claimRoundVestedTokens(args: {
+    projectId: BN;
+    roundNumber: number;
+    milestoneIndex: number;
+    nftMint: PublicKey;
+    investorTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimRoundVestedTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  /**
+   * Claim early tokens for a round investment (5% after 24h)
+   *
+   * Multi-Round Fundraising: R2+ investors claim 5% of token allocation
+   * 24 hours after investing. Tokens come from FutureRoundVault.
+   */
+  async claimRoundEarlyTokens(args: {
+    projectId: BN;
+    roundNumber: number;
+    nftMint: PublicKey;
+    investorTokenAccount: PublicKey;
+  }): Promise<string> {
+    return instructions.claimRoundEarlyTokens(
+      this.program,
+      args,
+      this.walletPublicKey
+    );
+  }
+
+  // ===========================================================================
+  // Multi-Round Fundraising Helpers
+  // ===========================================================================
+
+  /**
+   * Check if the next funding round can be opened
+   *
+   * Returns eligibility status with reason and next round number.
+   */
+  async canOpenNextRound(projectId: BN): Promise<{
+    canOpen: boolean;
+    reason?: string;
+    nextRoundNumber?: number;
+  }> {
+    return accounts.canOpenNextRound(this.program, projectId);
+  }
+
+  /**
+   * Get remaining future round allocation in BPS
+   */
+  getRemainingFutureRoundAllocation(tokenomics: {
+    futureRoundAllocationBps: number;
+    usedFutureRoundBps?: number;
+  }): number {
+    return accounts.getRemainingFutureRoundAllocation(tokenomics);
+  }
+
+  /**
+   * Check if a specific round is fully funded
+   */
+  async isRoundFullyFunded(projectId: BN, roundNumber: number): Promise<boolean> {
+    return accounts.isRoundFullyFunded(this.program, projectId, roundNumber);
+  }
+
+  /**
+   * Get round details with computed state
+   *
+   * Returns funding round data with additional computed fields.
+   */
+  async getRoundDetails(projectId: BN, roundNumber: number) {
+    const fundingRound = await this.fetchFundingRound(projectId, roundNumber);
+    if (!fundingRound) {
+      return null;
+    }
+
+    const milestones = [];
+    for (let i = 0; i < fundingRound.milestoneCount; i++) {
+      const milestone = await this.fetchRoundMilestone(projectId, roundNumber, i);
+      if (milestone) {
+        milestones.push(milestone);
+      }
+    }
+
+    const totalRaised = fundingRound.totalRaised.toNumber();
+    const fundingGoal = fundingRound.fundingGoal.toNumber();
+    const fundingProgress = fundingGoal > 0 ? (totalRaised / fundingGoal) * 100 : 0;
+
+    return {
+      ...fundingRound,
+      milestones,
+      fundingProgress,
+      isFullyFunded: totalRaised >= fundingGoal,
+    };
+  }
 }