@zemyth/raise-sdk 0.1.1 → 0.1.3

package/src/instructions/index.ts

@@ -29,6 +29,20 @@ import {
   getTreasuryVaultPDA,
   getLpUsdcVaultPDA,
   getFounderVestingPDA,
+  getSubAllocationVestingPDA,
+  // Per-Milestone Vesting PDAs
+  getInvestorMilestoneVestingPDA,
+  getFounderMilestoneVestingPDA,
+  // Future Round PDAs
+  getFutureRoundTokenVaultPDA,
+  getFutureRoundVaultPDA,
+  // Multi-Round Fundraising PDAs
+  getFundingRoundPDA,
+  getRoundEscrowPDA,
+  getRoundMilestonePDA,
+  getRoundNftMintPDA,
+  getRoundInvestmentPDA,
+  getRoundInvestorMilestoneVestingPDA,
 } from '../pdas/index.js';
 import { getAssociatedTokenAddressSync, TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID } from '@solana/spl-token';
 
@@ -79,7 +93,7 @@ export async function initializeAdmin(
 ): Promise<string> {
   return getMethods(program)
     .initializeAdmin()
-    .accounts({
+    .accountsPartial({
       admin,
       payer,
     })
@@ -96,7 +110,7 @@ export async function transferAdmin(
 ): Promise<string> {
   return getMethods(program)
     .transferAdmin()
-    .accounts({
+    .accountsPartial({
       authority: adminKeypair.publicKey,
       newAdmin,
     })
@@ -113,7 +127,7 @@ export async function acceptAdmin(
 ): Promise<string> {
   return getMethods(program)
     .acceptAdmin()
-    .accounts({
+    .accountsPartial({
       newAuthority,
     })
     .rpc();
@@ -126,6 +140,7 @@ export async function acceptAdmin(
 /**
  * TierConfig input type for initializeProject
  * Matches the on-chain TierConfig struct
+ * Note: voteMultiplier is auto-calculated on-chain using logarithmic formula
  */
 interface TierConfigInput {
   /** USDC amount per lot */
@@ -134,8 +149,6 @@ interface TierConfigInput {
   maxLots: number;
   /** Token allocation per $1 invested */
   tokenRatio: BN;
-  /** Vote weight multiplier (basis points, 100 = 1.0x) */
-  voteMultiplier: number;
 }
 
 /**
@@ -153,16 +166,22 @@ export interface TokenomicsInput {
   lpTokenAllocationBps: number;
   /** LP USDC allocation in basis points (min 500 = 5% of raised USDC) */
   lpUsdcAllocationBps: number;
-  /** Founder allocation in basis points (optional) */
+  /** Founder allocation in basis points (optional). Sub-allocations (treasury, advisors, marketing) draw from this pool. */
   founderAllocationBps?: number | null;
-  /** Treasury allocation in basis points (optional) */
-  treasuryAllocationBps?: number | null;
+  /** Zemyth platform fee in basis points (minimum 100 = 1%). Vests proportionally per milestone. */
+  zemythAllocationBps?: 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;
+  /** Early Token Release: Founder milestone-based vesting BPS (optional, default: 4750 = 47.5% of founder allocation) */
+  founderMilestoneVestingBps?: number | null;
+  /** Early Token Release: Founder time-based vesting BPS (optional, default: 4750 = 47.5% of founder allocation) */
+  founderTimeVestingBps?: number | null;
+  /** Future round allocation in basis points (optional, 0 = none, >= 1000 = 10% minimum if enabled) */
+  futureRoundAllocationBps?: number | null;
 }
 
 /**
@@ -262,6 +281,11 @@ export function validateDeadline(
  * @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)
+ * @param priceMultipliers - Optional price multipliers in BPS for each milestone
+ *   - If not provided (default): Uses DYNAMIC mode - multipliers calculated automatically
+ *     via ZEMYTH formula when founder claims milestone funds and sets next deadline
+ *   - If provided: Uses STATIC mode - pre-configured multipliers array (legacy behavior)
+ *     multipliers[i] = price after milestone i passes (10000 = 1.0x, 15000 = 1.5x)
  */
 export async function initializeProject(
   program: AnyProgram,
@@ -275,6 +299,8 @@ export async function initializeProject(
     tokenomics: TokenomicsInput;
     /** Milestone 1 deadline - Unix timestamp (required) */
     milestone1Deadline: BN;
+    /** Price multipliers: Optional pre-configured BPS array (defaults to dynamic ZEMYTH formula) */
+    priceMultipliers?: number[];
   },
   founder: PublicKey
 ): Promise<string> {
@@ -291,14 +317,18 @@ export async function initializeProject(
         lpTokenAllocationBps: args.tokenomics.lpTokenAllocationBps,
         lpUsdcAllocationBps: args.tokenomics.lpUsdcAllocationBps,
         founderAllocationBps: args.tokenomics.founderAllocationBps ?? null,
-        treasuryAllocationBps: args.tokenomics.treasuryAllocationBps ?? null,
+        zemythAllocationBps: args.tokenomics.zemythAllocationBps ?? null,
         founderWallet: args.tokenomics.founderWallet ?? null,
         vestingDurationMonths: args.tokenomics.vestingDurationMonths ?? null,
         cliffMonths: args.tokenomics.cliffMonths ?? null,
+        founderMilestoneVestingBps: args.tokenomics.founderMilestoneVestingBps ?? null,
+        founderTimeVestingBps: args.tokenomics.founderTimeVestingBps ?? null,
+        futureRoundAllocationBps: args.tokenomics.futureRoundAllocationBps ?? null,
       },
       milestone1Deadline: args.milestone1Deadline,
+      priceMultipliers: args.priceMultipliers ?? null,
     })
-    .accounts({
+    .accountsPartial({
       founder,
     })
     .rpc();
@@ -316,7 +346,7 @@ export async function submitForApproval(
 
   return getMethods(program)
     .submitForApproval()
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       founder,
     })
@@ -346,10 +376,17 @@ export async function approveProject(
   const lpTokenVaultPda = getLpTokenVaultPDA(projectPda, program.programId);
   const treasuryVaultPda = getTreasuryVaultPDA(projectPda, program.programId);
   const lpUsdcVaultPda = getLpUsdcVaultPDA(projectPda, program.programId);
+  const futureRoundTokenVaultPda = getFutureRoundTokenVaultPDA(projectPda, program.programId);
+  const futureRoundVaultPda = getFutureRoundVaultPDA(projectPda, program.programId);
+
+  // Request 400k CUs - this instruction creates 10 accounts + 7 CPIs + 5 events
+  const computeBudgetIx = ComputeBudgetProgram.setComputeUnitLimit({
+    units: 400_000,
+  });
 
   return getMethods(program)
     .approveProject()
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       tokenomics: tokenomicsPda,
       tokenVault: tokenVaultPda,
@@ -360,10 +397,13 @@ export async function approveProject(
       lpTokenVault: lpTokenVaultPda,
       treasuryVault: treasuryVaultPda,
       lpUsdcVault: lpUsdcVaultPda,
+      futureRoundTokenVault: futureRoundTokenVaultPda,
+      futureRoundVault: futureRoundVaultPda,
       usdcMint: args.usdcMint,
       authority: adminKeypair.publicKey,
       payer: adminKeypair.publicKey,
     })
+    .preInstructions([computeBudgetIx])
     .signers([adminKeypair])
     .rpc();
 }
@@ -374,6 +414,10 @@ export async function approveProject(
 
 /**
  * Create a milestone for a project
+ *
+ * @param vestingDurationMonths - Vesting duration in months (6-24), null for default (12)
+ * @param cliffMonths - Cliff duration in months (0-3), null for default (0)
+ * @param instantReleaseBps - Instant release basis points (500-5000), null for default (500 = 5%)
  */
 export async function createMilestone(
   program: AnyProgram,
@@ -382,6 +426,9 @@ export async function createMilestone(
     milestoneIndex: number;
     percentage: number;
     description: string;
+    vestingDurationMonths?: number | null;
+    cliffMonths?: number | null;
+    instantReleaseBps?: number | null;
   },
   founder: PublicKey
 ): Promise<string> {
@@ -393,8 +440,11 @@ export async function createMilestone(
       milestoneIndex: args.milestoneIndex,
       percentage: args.percentage,
       description: args.description,
+      vestingDurationMonths: args.vestingDurationMonths ?? null,
+      cliffMonths: args.cliffMonths ?? null,
+      instantReleaseBps: args.instantReleaseBps ?? null,
     })
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       milestone: milestonePda,
       founder,
@@ -416,7 +466,7 @@ export async function submitMilestone(
 
   return getMethods(program)
     .submitMilestone()
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       milestone: milestonePda,
       founder,
@@ -463,7 +513,7 @@ export async function voteOnMilestone(
 
   return getMethods(program)
     .voteOnMilestone({ choice: args.choice })
-    .accounts({
+    .accountsPartial({
       milestone: milestonePda,
       project: projectPda,
       investment: investmentPda,
@@ -488,7 +538,7 @@ export async function finalizeVoting(
 
   return getMethods(program)
     .finalizeVoting()
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       milestone: milestonePda,
     })
@@ -536,7 +586,7 @@ export async function claimMilestoneFunds(
 
   return getMethods(program)
     .claimMilestoneFunds({ nextMilestoneDeadline: args.nextMilestoneDeadline })
-    .accounts({
+    .accountsPartial({
       milestone: milestonePda,
       project: projectPda,
       founder,
@@ -574,7 +624,7 @@ export async function resubmitMilestone(
 
   return getMethods(program)
     .resubmitMilestone()
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       milestone: milestonePda,
       founder,
@@ -607,7 +657,7 @@ export async function setMilestoneDeadline(
       milestoneIndex: args.milestoneIndex,
       deadline: args.deadline,
     })
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       milestone: milestonePda,
       founder,
@@ -640,7 +690,7 @@ export async function extendMilestoneDeadline(
       milestoneIndex: args.milestoneIndex,
       newDeadline: args.newDeadline,
     })
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       milestone: milestonePda,
       founder,
@@ -725,7 +775,7 @@ export async function invest(
   // Metaplex NFT minting requires significantly more than the default 200k CU
   return getMethods(program)
     .invest({ amount: args.amount })
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       firstMilestone: firstMilestonePda,
       nftMint: nftMint,
@@ -771,7 +821,7 @@ export async function cancelInvestment(
 
   return getMethods(program)
     .cancelInvestment()
-    .accounts({
+    .accountsPartial({
       investor,
       project: projectPda,
       investment: investmentPda,
@@ -814,7 +864,7 @@ export async function proposePivot(
       newMetadataUri: args.newMetadataUri,
       newMilestones: args.newMilestones,
     })
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       founder,
       pivotProposal: pivotProposalPda,
@@ -850,7 +900,7 @@ export async function approvePivot(
 
   return getMethods(program)
     .approvePivot()
-    .accounts({
+    .accountsPartial({
       moderator: adminKeypair.publicKey,
       project: projectPda,
       pivotProposal: pivotProposalPda,
@@ -897,7 +947,7 @@ export async function withdrawFromPivot(
 
   return getMethods(program)
     .withdrawFromPivot()
-    .accounts({
+    .accountsPartial({
       investor,
       project: projectPda,
       pivotProposal: pivotProposalPda,
@@ -942,7 +992,7 @@ export async function finalizePivot(
 
   return getMethods(program)
     .finalizePivot()
-    .accounts({
+    .accountsPartial({
       authority,
       project: projectPda,
       pivotProposal: pivotProposalPda,
@@ -974,7 +1024,7 @@ export async function setTgeDate(
       tgeDate: args.tgeDate,
       tokenMint: args.tokenMint,
     })
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       founder,
     })
@@ -998,7 +1048,7 @@ export async function depositTokens(
 
   return getMethods(program)
     .depositTokens({ amount: args.amount })
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       tokenMint: args.tokenMint,
       founderTokenAccount: args.founderTokenAccount,
@@ -1027,7 +1077,7 @@ export async function claimTokens(
 
   return getMethods(program)
     .claimTokens()
-    .accounts({
+    .accountsPartial({
       investor,
       project: projectPda,
       investment: investmentPda,
@@ -1057,7 +1107,7 @@ export async function reportScam(
 
   return getMethods(program)
     .reportScam()
-    .accounts({
+    .accountsPartial({
       tgeEscrow: tgeEscrowPda,
       project: projectPda,
       investment: investmentPda,
@@ -1082,7 +1132,7 @@ export async function releaseHoldback(
 
   return getMethods(program)
     .releaseHoldback()
-    .accounts({
+    .accountsPartial({
       tgeEscrow: tgeEscrowPda,
       project: projectPda,
       founderTokenAccount: args.founderTokenAccount,
@@ -1107,7 +1157,7 @@ export async function checkAbandonment(
 
   return getMethods(program)
     .checkAbandonment()
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       milestone: milestonePda,
     })
@@ -1151,7 +1201,7 @@ export async function claimRefund(
 
   return getMethods(program)
     .claimRefund()
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       investment: investmentPda,
       nftMint: nftMintPubkey,
@@ -1208,7 +1258,7 @@ export async function claimInvestorTokens(
 
   return getMethods(program)
     .claimInvestorTokens({ milestoneIndex: args.milestoneIndex })
-    .accounts({
+    .accountsPartial({
       investor,
       project: projectPda,
       tokenVault: tokenVaultPda,
@@ -1261,7 +1311,7 @@ export async function distributeTokens(
 
   return getMethods(program)
     .distributeTokens({ milestoneIndex: args.milestoneIndex })
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       tokenVault: tokenVaultPda,
       investorVault: investorVaultPda,
@@ -1292,7 +1342,7 @@ export async function completeDistribution(
 
   return getMethods(program)
     .completeDistribution({ milestoneIndex: args.milestoneIndex })
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       tokenVault: tokenVaultPda,
       payer,
@@ -1372,7 +1422,7 @@ export async function initializeFounderVesting(
 
   return getMethods(program)
     .initializeFounderVesting()
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       tokenomics: tokenomicsPda,
       tokenVault: tokenVaultPda,
@@ -1406,7 +1456,7 @@ export async function claimVestedTokens(
 
   return getMethods(program)
     .claimVestedTokens()
-    .accounts({
+    .accountsPartial({
       project: projectPda,
       tokenVault: tokenVaultPda,
       founderVesting: founderVestingPda,
@@ -1443,7 +1493,7 @@ export async function forceCompleteDistribution(
 
   return getMethods(program)
     .forceCompleteDistribution()
-    .accounts({
+    .accountsPartial({
       admin: adminKeypair.publicKey,
       adminConfig: adminConfigPda,
       project: projectPda,
@@ -1488,7 +1538,7 @@ export async function claimMissedUnlock(
 
   return getMethods(program)
     .claimMissedUnlock({ milestoneIndex: args.milestoneIndex })
-    .accounts({
+    .accountsPartial({
       claimer,
       project: projectPda,
       tokenVault: tokenVaultPda,
@@ -1502,3 +1552,1296 @@ export async function claimMissedUnlock(
     })
     .rpc();
 }
+
+// =============================================================================
+// Dynamic Tokenomics Instructions
+// =============================================================================
+
+import {
+  getAllocationProposalPDA,
+  getAllocationVotePDA,
+} from '../pdas/index.js';
+
+/**
+ * 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.
+ *
+ * @param name - Sub-allocation name (1-32 ASCII chars)
+ * @param bps - Basis points from reserve pool
+ * @param recipient - Token destination wallet
+ * @param vestingMonths - Vesting duration (0 = immediate)
+ * @param cliffMonths - Cliff period before vesting starts
+ */
+export async function addSubAllocation(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    name: string;
+    bps: number;
+    recipient: PublicKey;
+    vestingMonths: number;
+    cliffMonths: number;
+  },
+  founder: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+
+  return getMethods(program)
+    .addSubAllocation({
+      name: args.name,
+      bps: args.bps,
+      recipient: args.recipient,
+      vestingMonths: args.vestingMonths,
+      cliffMonths: args.cliffMonths,
+    })
+    .accountsPartial({
+      project: projectPda,
+      tokenomics: tokenomicsPda,
+      founder,
+    })
+    .rpc();
+}
+
+/**
+ * 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.
+ */
+export async function proposeAllocationChange(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    name: string;
+    bps: number;
+    recipient: PublicKey;
+    vestingMonths: number;
+    cliffMonths: number;
+  },
+  founder: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+
+  // Fetch tokenomics to get current proposal_count
+  const tokenomics = await getAccountNamespace(program).tokenomics.fetch(tokenomicsPda);
+  const proposalIndex = tokenomics.proposalCount || 0;
+  const proposalPda = getAllocationProposalPDA(projectPda, proposalIndex, program.programId);
+
+  return getMethods(program)
+    .proposeAllocationChange({
+      name: args.name,
+      bps: args.bps,
+      recipient: args.recipient,
+      vestingMonths: args.vestingMonths,
+      cliffMonths: args.cliffMonths,
+    })
+    .accountsPartial({
+      project: projectPda,
+      tokenomics: tokenomicsPda,
+      proposal: proposalPda,
+      founder,
+      systemProgram: SystemProgram.programId,
+    })
+    .rpc();
+}
+
+/**
+ * Vote on an allocation change proposal
+ *
+ * Investors can vote for/against using their Investment NFT.
+ * Must meet 7-day hold period for voting eligibility.
+ * One vote per NFT (prevents double voting).
+ */
+export async function voteAllocationChange(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    proposalIndex: number;
+    nftMint: PublicKey;
+    voteFor: boolean;
+  },
+  voter: PublicKey
+): Promise<string> {
+  const nftMintPubkey = ensurePublicKey(args.nftMint);
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const proposalPda = getAllocationProposalPDA(projectPda, args.proposalIndex, program.programId);
+  const investmentPda = getInvestmentPDA(projectPda, nftMintPubkey, program.programId);
+  const votePda = getAllocationVotePDA(proposalPda, nftMintPubkey, program.programId);
+
+  // Get voter's NFT token account (ATA)
+  const investorNftAccount = getAssociatedTokenAddressSync(
+    nftMintPubkey,
+    voter,
+    false,
+    TOKEN_PROGRAM_ID
+  );
+
+  return getMethods(program)
+    .voteAllocationChange({ voteFor: args.voteFor })
+    .accountsPartial({
+      project: projectPda,
+      proposal: proposalPda,
+      investment: investmentPda,
+      nftMint: nftMintPubkey,
+      investorNftAccount,
+      voteRecord: votePda,
+      voter,
+      systemProgram: SystemProgram.programId,
+    })
+    .rpc();
+}
+
+/**
+ * Execute an approved allocation change proposal
+ *
+ * Permissionless - anyone can call after voting ends.
+ * Proposal must have passed (>51% approval).
+ * Adds the sub-allocation to tokenomics.
+ */
+export async function executeAllocationChange(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    proposalIndex: number;
+  },
+  executor: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+  const proposalPda = getAllocationProposalPDA(projectPda, args.proposalIndex, program.programId);
+
+  return getMethods(program)
+    .executeAllocationChange()
+    .accountsPartial({
+      project: projectPda,
+      tokenomics: tokenomicsPda,
+      proposal: proposalPda,
+      executor,
+    })
+    .rpc();
+}
+
+// =============================================================================
+// 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 (not withdrawn from pivot)
+ *
+ * @param nftMint - The NFT mint that proves investment ownership
+ * @param investorTokenAccount - Investor's token account to receive claimed tokens
+ */
+export async function claimEarlyTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** NFT mint that proves investment ownership */
+    nftMint: PublicKey;
+    /** Investor's token account to receive claimed tokens */
+    investorTokenAccount: PublicKey;
+  },
+  investor: PublicKey
+): Promise<string> {
+  const nftMintPubkey = ensurePublicKey(args.nftMint);
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const investmentPda = getInvestmentPDA(projectPda, nftMintPubkey, program.programId);
+  const investorVaultPda = getInvestorVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  // Get investor's NFT token account (ATA)
+  const investorNftAccount = getAssociatedTokenAddressSync(
+    nftMintPubkey,
+    investor,
+    false,
+    TOKEN_PROGRAM_ID
+  );
+
+  return getMethods(program)
+    .claimEarlyTokens()
+    .accountsPartial({
+      investor,
+      project: projectPda,
+      tokenVault: tokenVaultPda,
+      investment: investmentPda,
+      nftMint: nftMintPubkey,
+      investorNftAccount,
+      investorVault: investorVaultPda,
+      investorTokenAccount: args.investorTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}
+
+/**
+ * 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
+ * - Founder allocation must be configured in tokenomics
+ *
+ * @param founderTokenAccount - Founder's token account to receive claimed tokens
+ */
+export async function claimFounderEarlyTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Founder's token account to receive claimed tokens */
+    founderTokenAccount: PublicKey;
+  },
+  founder: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const founderVaultPda = getFounderVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  return getMethods(program)
+    .claimFounderEarlyTokens()
+    .accountsPartial({
+      founder,
+      project: projectPda,
+      tokenomics: tokenomicsPda,
+      tokenVault: tokenVaultPda,
+      founderVault: founderVaultPda,
+      founderTokenAccount: args.founderTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}
+
+/**
+ * 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.
+ * Amount per milestone = milestone_tokens * milestone_percentage / 100
+ *
+ * Prerequisites:
+ * - Milestone must be in Unlocked state
+ * - Founder must not have already claimed tokens for this milestone
+ * - Founder milestone vesting must be configured in tokenomics
+ *
+ * @param milestoneIndex - The milestone index to claim tokens from
+ * @param founderTokenAccount - Founder's token account to receive claimed tokens
+ */
+export async function claimFounderMilestoneTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Milestone index to claim tokens from */
+    milestoneIndex: number;
+    /** Founder's token account to receive claimed tokens */
+    founderTokenAccount: PublicKey;
+  },
+  founder: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const milestonePda = getMilestonePDA(projectPda, args.milestoneIndex, program.programId);
+  const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const founderVaultPda = getFounderVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  return getMethods(program)
+    .claimFounderMilestoneTokens({ milestoneIndex: args.milestoneIndex })
+    .accountsPartial({
+      founder,
+      project: projectPda,
+      milestone: milestonePda,
+      tokenomics: tokenomicsPda,
+      tokenVault: tokenVaultPda,
+      founderVault: founderVaultPda,
+      founderTokenAccount: args.founderTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}
+
+// =============================================================================
+// 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.
+ *
+ * @param subAllocationId - Sub-allocation ID to initialize vesting for (0-9)
+ */
+export async function initializeSubAllocationVesting(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Sub-allocation ID to initialize vesting for */
+    subAllocationId: number;
+  },
+  payer: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const subAllocationVestingPda = getSubAllocationVestingPDA(projectPda, args.subAllocationId, program.programId);
+
+  return getMethods(program)
+    .initializeSubAllocationVesting({ subAllocationId: args.subAllocationId })
+    .accountsPartial({
+      project: projectPda,
+      tokenomics: tokenomicsPda,
+      tokenVault: tokenVaultPda,
+      subAllocationVesting: subAllocationVestingPda,
+      payer,
+      systemProgram: SystemProgram.programId,
+    })
+    .rpc();
+}
+
+/**
+ * Claim vested tokens from a sub-allocation
+ *
+ * Only the designated recipient wallet can claim tokens.
+ * Project must be Completed and MAE must be completed.
+ * Calculates claimable amount based on cliff + linear vesting schedule.
+ *
+ * @param subAllocationId - Sub-allocation ID to claim from (0-9)
+ * @param recipientTokenAccount - Recipient's token account to receive claimed tokens
+ */
+export async function claimSubAllocationTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Sub-allocation ID to claim from */
+    subAllocationId: number;
+    /** Recipient's token account to receive claimed tokens */
+    recipientTokenAccount: PublicKey;
+  },
+  recipient: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const subAllocationVestingPda = getSubAllocationVestingPDA(projectPda, args.subAllocationId, program.programId);
+  const treasuryVaultPda = getTreasuryVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  return getMethods(program)
+    .claimSubAllocationTokens({ subAllocationId: args.subAllocationId })
+    .accountsPartial({
+      project: projectPda,
+      tokenomics: tokenomicsPda,
+      tokenVault: tokenVaultPda,
+      subAllocationVesting: subAllocationVestingPda,
+      reserveVault: treasuryVaultPda,
+      vaultAuthority: vaultAuthorityPda,
+      recipientTokenAccount: args.recipientTokenAccount,
+      recipient,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}
+
+// =============================================================================
+// 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.
+ *
+ * Prerequisites:
+ * - Milestone must be in Passed or Unlocked state
+ * - Milestone must use per-milestone vesting (instant_release_bps < 10000)
+ * - Investor must hold the NFT proving ownership
+ *
+ * @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
+ */
+export async function claimMilestoneInstantTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Milestone index to claim instant 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> {
+  const nftMintPubkey = ensurePublicKey(args.nftMint);
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const milestonePda = getMilestonePDA(projectPda, args.milestoneIndex, program.programId);
+  const investmentPda = getInvestmentPDA(projectPda, nftMintPubkey, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const vestingPda = getInvestorMilestoneVestingPDA(projectPda, args.milestoneIndex, investmentPda, program.programId);
+  const investorVaultPda = getInvestorVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  // Get investor's NFT token account (ATA)
+  const investorNftAccount = getAssociatedTokenAddressSync(
+    nftMintPubkey,
+    investor,
+    false,
+    TOKEN_PROGRAM_ID
+  );
+
+  return getMethods(program)
+    .claimMilestoneInstantTokens({ milestoneIndex: args.milestoneIndex })
+    .accountsPartial({
+      investor,
+      project: projectPda,
+      milestone: milestonePda,
+      investment: investmentPda,
+      tokenVault: tokenVaultPda,
+      vesting: vestingPda,
+      nftMint: nftMintPubkey,
+      investorNftAccount,
+      investorVault: investorVaultPda,
+      investorTokenAccount: args.investorTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+      systemProgram: SystemProgram.programId,
+    })
+    .rpc();
+}
+
+/**
+ * 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.
+ *
+ * Prerequisites:
+ * - Vesting PDA must exist (created by claimMilestoneInstantTokens)
+ * - Cliff period must have passed
+ * - Investor must hold the NFT proving ownership
+ *
+ * @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
+ */
+export async function claimMilestoneVestedTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Milestone index to claim vested 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> {
+  const nftMintPubkey = ensurePublicKey(args.nftMint);
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const milestonePda = getMilestonePDA(projectPda, args.milestoneIndex, program.programId);
+  const investmentPda = getInvestmentPDA(projectPda, nftMintPubkey, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const vestingPda = getInvestorMilestoneVestingPDA(projectPda, args.milestoneIndex, investmentPda, program.programId);
+  const investorVaultPda = getInvestorVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  // Get investor's NFT token account (ATA)
+  const investorNftAccount = getAssociatedTokenAddressSync(
+    nftMintPubkey,
+    investor,
+    false,
+    TOKEN_PROGRAM_ID
+  );
+
+  return getMethods(program)
+    .claimMilestoneVestedTokens({ milestoneIndex: args.milestoneIndex })
+    .accountsPartial({
+      investor,
+      project: projectPda,
+      milestone: milestonePda,
+      investment: investmentPda,
+      tokenVault: tokenVaultPda,
+      vesting: vestingPda,
+      nftMint: nftMintPubkey,
+      investorNftAccount,
+      investorVault: investorVaultPda,
+      investorTokenAccount: args.investorTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}
+
+/**
+ * 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.
+ * Creates vesting PDA on first claim.
+ *
+ * Prerequisites:
+ * - Milestone must be in Passed or Unlocked state
+ * - Milestone must use per-milestone vesting (instant_release_bps < 10000)
+ * - Founder must have milestone-based allocation configured
+ * - Caller must be the project founder
+ *
+ * @param milestoneIndex - The milestone index to claim tokens from
+ * @param founderTokenAccount - Founder's token account to receive claimed tokens
+ */
+export async function claimFounderMsInstantTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Milestone index to claim instant tokens from */
+    milestoneIndex: number;
+    /** Founder's token account to receive claimed tokens */
+    founderTokenAccount: PublicKey;
+  },
+  founder: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const milestonePda = getMilestonePDA(projectPda, args.milestoneIndex, program.programId);
+  const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const vestingPda = getFounderMilestoneVestingPDA(projectPda, args.milestoneIndex, program.programId);
+  const founderVaultPda = getFounderVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  return getMethods(program)
+    .claimFounderMsInstantTokens({ milestoneIndex: args.milestoneIndex })
+    .accountsPartial({
+      founder,
+      project: projectPda,
+      tokenomics: tokenomicsPda,
+      milestone: milestonePda,
+      tokenVault: tokenVaultPda,
+      vesting: vestingPda,
+      founderVault: founderVaultPda,
+      founderTokenAccount: args.founderTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+      systemProgram: SystemProgram.programId,
+    })
+    .rpc();
+}
+
+/**
+ * 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.
+ *
+ * Prerequisites:
+ * - Vesting PDA must exist (created by claimFounderMsInstantTokens)
+ * - Cliff period must have passed
+ * - Caller must be the project founder
+ *
+ * @param milestoneIndex - The milestone index to claim vested tokens from
+ * @param founderTokenAccount - Founder's token account to receive claimed tokens
+ */
+export async function claimFounderMsVestedTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Milestone index to claim vested tokens from */
+    milestoneIndex: number;
+    /** Founder's token account to receive claimed tokens */
+    founderTokenAccount: PublicKey;
+  },
+  founder: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const vestingPda = getFounderMilestoneVestingPDA(projectPda, args.milestoneIndex, program.programId);
+  const founderVaultPda = getFounderVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  return getMethods(program)
+    .claimFounderMsVestedTokens({ milestoneIndex: args.milestoneIndex })
+    .accountsPartial({
+      founder,
+      project: projectPda,
+      tokenVault: tokenVaultPda,
+      vesting: vestingPda,
+      founderVault: founderVaultPda,
+      founderTokenAccount: args.founderTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}
+
+// =============================================================================
+// Multi-Round Fundraising Instructions (add-second-round-fundraising)
+// =============================================================================
+
+/**
+ * TierConfig input type for openFundingRound
+ */
+interface RoundTierConfigInput {
+  /** USDC amount per lot */
+  amount: BN;
+  /** Maximum lots available */
+  maxLots: number;
+  /** Token allocation per $1 invested */
+  tokenRatio: BN;
+}
+
+/**
+ * Milestone configuration for new funding round
+ */
+interface RoundMilestoneConfigInput {
+  /** Percentage of funding_goal (1-100) */
+  percentage: number;
+  /** Milestone description (max 32 chars) */
+  description: string;
+  /** Vesting duration in months (6-24, 0 = instant unlock) */
+  vestingDurationMonths?: number | null;
+  /** Cliff duration in months (0-3) */
+  cliffMonths?: number | null;
+  /** Instant release basis points (500-5000) */
+  instantReleaseBps?: number | null;
+}
+
+/**
+ * Derive Round Escrow Authority PDA
+ */
+function getRoundEscrowAuthorityPDA(
+  projectPda: PublicKey,
+  roundNumber: number,
+  programId: PublicKey
+): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync(
+    [
+      Buffer.from('round_escrow'),
+      projectPda.toBuffer(),
+      Buffer.from([roundNumber]),
+      Buffer.from('authority'),
+    ],
+    programId
+  );
+}
+
+/**
+ * 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
+ *
+ * @param roundAllocationBps - BPS from future_round_allocation to use (e.g., 1000 = 10%)
+ * @param fundingGoal - USDC funding goal for this round
+ * @param tiers - Tier configuration (1-10 tiers)
+ * @param milestones - Milestone configuration (2-10 milestones, sum to 100%)
+ * @param previousFundingRoundPda - Previous round PDA (required for R3+)
+ */
+export async function openFundingRound(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** BPS from future_round_allocation to use (e.g., 1000 = 10%) */
+    roundAllocationBps: number;
+    /** USDC funding goal for this round */
+    fundingGoal: BN;
+    /** Tier configuration (1-10 tiers) */
+    tiers: RoundTierConfigInput[];
+    /** Milestone configuration (2-10 milestones) */
+    milestones: RoundMilestoneConfigInput[];
+    /** USDC mint address */
+    usdcMint: PublicKey;
+    /** Previous funding round PDA (required for R3+, optional for R2) */
+    previousFundingRoundPda?: PublicKey | null;
+  },
+  founder: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+
+  // Fetch project to get round_count
+  const project = await getAccountNamespace(program).project.fetch(projectPda);
+  const newRoundNumber = (project.roundCount || 1) + 1;
+
+  // Derive new round PDAs
+  const fundingRoundPda = getFundingRoundPDA(projectPda, newRoundNumber, program.programId);
+  const roundEscrowPda = getRoundEscrowPDA(projectPda, newRoundNumber, program.programId);
+  const [roundEscrowAuthorityPda] = getRoundEscrowAuthorityPDA(projectPda, newRoundNumber, program.programId);
+
+  // Build milestone PDAs as remaining accounts
+  const remainingAccounts = args.milestones.map((_, i) => {
+    const milestonePda = getRoundMilestonePDA(projectPda, newRoundNumber, i, program.programId);
+    return {
+      pubkey: milestonePda,
+      isSigner: false,
+      isWritable: true,
+    };
+  });
+
+  // Transform milestones for instruction
+  const milestonesParam = args.milestones.map((m) => ({
+    percentage: m.percentage,
+    description: m.description,
+    vestingDurationMonths: m.vestingDurationMonths ?? null,
+    cliffMonths: m.cliffMonths ?? null,
+    instantReleaseBps: m.instantReleaseBps ?? null,
+  }));
+
+  return getMethods(program)
+    .openFundingRound({
+      roundAllocationBps: args.roundAllocationBps,
+      fundingGoal: args.fundingGoal,
+      tiers: args.tiers,
+      milestones: milestonesParam,
+    })
+    .accountsPartial({
+      project: projectPda,
+      tokenomics: tokenomicsPda,
+      fundingRound: fundingRoundPda,
+      roundEscrow: roundEscrowPda,
+      roundEscrowAuthority: roundEscrowAuthorityPda,
+      usdcMint: args.usdcMint,
+      previousFundingRound: args.previousFundingRoundPda ?? null,
+      founder,
+      tokenProgram: TOKEN_PROGRAM_ID,
+      systemProgram: SystemProgram.programId,
+      rent: SYSVAR_RENT_PUBKEY,
+    })
+    .remainingAccounts(remainingAccounts)
+    .rpc();
+}
+
+/**
+ * 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.
+ *
+ * @param roundNumber - Round number to invest in (2, 3, 4...)
+ * @param amount - USDC amount to invest
+ * @param investorTokenAccount - Investor's USDC token account
+ * @param investmentCount - Current investment count from FundingRound
+ */
+export async function investInRound(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Round number to invest in */
+    roundNumber: number;
+    /** USDC amount to invest */
+    amount: BN;
+    /** Investor's USDC token account */
+    investorTokenAccount: PublicKey;
+    /** Current investment count from FundingRound */
+    investmentCount: number;
+  },
+  investor: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const fundingRoundPda = getFundingRoundPDA(projectPda, args.roundNumber, program.programId);
+  const roundEscrowPda = getRoundEscrowPDA(projectPda, args.roundNumber, program.programId);
+
+  // Derive first round milestone PDA (for state transition when funded)
+  const firstRoundMilestonePda = getRoundMilestonePDA(projectPda, args.roundNumber, 0, program.programId);
+
+  // Derive NFT mint PDA with round number
+  const [nftMint] = getRoundNftMintPDA(args.projectId, args.roundNumber, investor, args.investmentCount, program.programId);
+
+  // Derive investment PDA with round number
+  const investmentPda = getRoundInvestmentPDA(projectPda, args.roundNumber, nftMint, program.programId);
+
+  // Derive investor's NFT token account (ATA)
+  const investorNftAccount = getAssociatedTokenAddressSync(nftMint, investor);
+
+  // Derive Metaplex metadata and master edition PDAs
+  const metadataAccount = getMetadataPDA(nftMint);
+  const masterEdition = getMasterEditionPDA(nftMint);
+
+  // Derive program authority PDA
+  const [programAuthority] = getProgramAuthorityPDA(program.programId);
+
+  // Add compute budget for NFT minting
+  return getMethods(program)
+    .investInRound({ amount: args.amount })
+    .accountsPartial({
+      project: projectPda,
+      fundingRound: fundingRoundPda,
+      firstRoundMilestone: firstRoundMilestonePda,
+      nftMint: nftMint,
+      investment: investmentPda,
+      investorNftAccount: investorNftAccount,
+      metadataAccount: metadataAccount,
+      masterEdition: masterEdition,
+      roundEscrow: roundEscrowPda,
+      investorTokenAccount: args.investorTokenAccount,
+      programAuthority: programAuthority,
+      investor,
+      tokenProgram: TOKEN_PROGRAM_ID,
+      associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
+      systemProgram: SystemProgram.programId,
+      rent: SYSVAR_RENT_PUBKEY,
+      tokenMetadataProgram: TOKEN_METADATA_PROGRAM_ID,
+      sysvarInstructions: SYSVAR_INSTRUCTIONS_PUBKEY,
+    })
+    .preInstructions([
+      ComputeBudgetProgram.setComputeUnitLimit({ units: 400_000 }),
+    ])
+    .rpc();
+}
+
+/**
+ * Cancel round investment within 24-hour cooling-off period
+ *
+ * Multi-Round Fundraising: Returns USDC from round escrow,
+ * closes investment account.
+ */
+export async function cancelRoundInvestment(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Round number of the investment */
+    roundNumber: number;
+    /** NFT mint of the investment */
+    nftMint: PublicKey;
+    /** Investor's NFT token account */
+    investorNftAccount: PublicKey;
+    /** Investor's USDC token account for refund */
+    investorUsdcAccount: PublicKey;
+  },
+  investor: PublicKey
+): Promise<string> {
+  const nftMintPubkey = ensurePublicKey(args.nftMint);
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const fundingRoundPda = getFundingRoundPDA(projectPda, args.roundNumber, program.programId);
+  const investmentPda = getRoundInvestmentPDA(projectPda, args.roundNumber, nftMintPubkey, program.programId);
+  const roundEscrowPda = getRoundEscrowPDA(projectPda, args.roundNumber, program.programId);
+  const [roundEscrowAuthorityPda] = getRoundEscrowAuthorityPDA(projectPda, args.roundNumber, program.programId);
+
+  return getMethods(program)
+    .cancelRoundInvestment()
+    .accountsPartial({
+      investor,
+      project: projectPda,
+      fundingRound: fundingRoundPda,
+      investment: investmentPda,
+      nftMint: nftMintPubkey,
+      investorNftAccount: args.investorNftAccount,
+      roundEscrow: roundEscrowPda,
+      roundEscrowAuthority: roundEscrowAuthorityPda,
+      investorUsdcAccount: args.investorUsdcAccount,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}
+
+/**
+ * Submit round milestone for investor review
+ *
+ * Multi-Round Fundraising: Transitions milestone to UnderReview,
+ * sets voting deadline.
+ */
+export async function submitRoundMilestone(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Round number */
+    roundNumber: number;
+    /** Milestone index to submit */
+    milestoneIndex: number;
+  },
+  founder: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const fundingRoundPda = getFundingRoundPDA(projectPda, args.roundNumber, program.programId);
+  const milestonePda = getRoundMilestonePDA(projectPda, args.roundNumber, args.milestoneIndex, program.programId);
+
+  return getMethods(program)
+    .submitRoundMilestone()
+    .accountsPartial({
+      founder,
+      project: projectPda,
+      fundingRound: fundingRoundPda,
+      milestone: milestonePda,
+      clock: SYSVAR_CLOCK_PUBKEY,
+    })
+    .rpc();
+}
+
+/**
+ * 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.
+ *
+ * @param roundNumber - Round number of the milestone being voted on
+ * @param milestoneIndex - Milestone index to vote on
+ * @param nftMint - Voter's NFT mint (can be from any round)
+ * @param choice - Vote choice (good or bad)
+ * @param investmentRoundNumber - Round number of the voter's investment
+ */
+export async function voteOnRoundMilestone(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Round number of the milestone being voted on */
+    roundNumber: number;
+    /** Milestone index to vote on */
+    milestoneIndex: number;
+    /** Voter's NFT mint (can be from any round) */
+    nftMint: PublicKey | string;
+    /** Vote choice */
+    choice: { good: object } | { bad: object };
+    /** Round number of the voter's investment (for PDA derivation) */
+    investmentRoundNumber: number;
+  },
+  voter: PublicKey
+): Promise<string> {
+  const nftMintPubkey = ensurePublicKey(args.nftMint);
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const fundingRoundPda = getFundingRoundPDA(projectPda, args.roundNumber, program.programId);
+  const milestonePda = getRoundMilestonePDA(projectPda, args.roundNumber, args.milestoneIndex, program.programId);
+
+  // Investment can be from any round (unified voting)
+  let investmentPda: PublicKey;
+  if (args.investmentRoundNumber === 1) {
+    // R1 investments use standard PDA without round number
+    investmentPda = getInvestmentPDA(projectPda, nftMintPubkey, program.programId);
+  } else {
+    // R2+ investments include round number
+    investmentPda = getRoundInvestmentPDA(projectPda, args.investmentRoundNumber, nftMintPubkey, program.programId);
+  }
+
+  // Fetch milestone to get current voting_round for vote PDA derivation
+  const milestone = await getAccountNamespace(program).milestone.fetch(milestonePda);
+  const votingRound = milestone.votingRound ?? 0;
+  const votePda = getVotePDA(milestonePda, voter, votingRound, program.programId);
+
+  // Get voter's NFT token account (ATA)
+  const voterNftAccount = getAssociatedTokenAddressSync(
+    nftMintPubkey,
+    voter,
+    false,
+    TOKEN_PROGRAM_ID
+  );
+
+  return getMethods(program)
+    .voteOnRoundMilestone({ choice: args.choice })
+    .accountsPartial({
+      vote: votePda,
+      project: projectPda,
+      fundingRound: fundingRoundPda,
+      milestone: milestonePda,
+      investment: investmentPda,
+      nftMint: nftMintPubkey,
+      voterNftAccount,
+      voter,
+      systemProgram: SystemProgram.programId,
+    })
+    .rpc();
+}
+
+/**
+ * Finalize voting on a round milestone
+ *
+ * Multi-Round Fundraising: Processes vote results, transitions
+ * milestone to Passed or Failed state.
+ */
+export async function finalizeRoundVoting(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Round number */
+    roundNumber: number;
+    /** Milestone index to finalize */
+    milestoneIndex: number;
+  }
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const fundingRoundPda = getFundingRoundPDA(projectPda, args.roundNumber, program.programId);
+  const milestonePda = getRoundMilestonePDA(projectPda, args.roundNumber, args.milestoneIndex, program.programId);
+
+  return getMethods(program)
+    .finalizeRoundVoting()
+    .accountsPartial({
+      project: projectPda,
+      fundingRound: fundingRoundPda,
+      milestone: milestonePda,
+      clock: SYSVAR_CLOCK_PUBKEY,
+    })
+    .rpc();
+}
+
+/**
+ * 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
+ */
+export async function claimRoundMilestoneFunds(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Round number */
+    roundNumber: number;
+    /** Milestone index to claim */
+    milestoneIndex: number;
+    /** Founder's USDC token account */
+    founderUsdcAccount: PublicKey;
+    /** Deadline for next milestone - required for non-final milestones, use BN(0) for final */
+    nextMilestoneDeadline: BN;
+  },
+  founder: PublicKey
+): Promise<string> {
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const fundingRoundPda = getFundingRoundPDA(projectPda, args.roundNumber, program.programId);
+  const milestonePda = getRoundMilestonePDA(projectPda, args.roundNumber, args.milestoneIndex, program.programId);
+  const roundEscrowPda = getRoundEscrowPDA(projectPda, args.roundNumber, program.programId);
+  const [roundEscrowAuthorityPda] = getRoundEscrowAuthorityPDA(projectPda, args.roundNumber, program.programId);
+
+  // For non-final milestones, derive next milestone PDA
+  const nextMilestonePda = args.nextMilestoneDeadline.gt(new BN(0))
+    ? getRoundMilestonePDA(projectPda, args.roundNumber, args.milestoneIndex + 1, program.programId)
+    : null;
+
+  return getMethods(program)
+    .claimRoundMilestoneFunds({ nextMilestoneDeadline: args.nextMilestoneDeadline })
+    .accountsPartial({
+      project: projectPda,
+      fundingRound: fundingRoundPda,
+      milestone: milestonePda,
+      founder,
+      roundEscrow: roundEscrowPda,
+      roundEscrowAuthority: roundEscrowAuthorityPda,
+      founderUsdcAccount: args.founderUsdcAccount,
+      nextMilestone: nextMilestonePda,
+      systemProgram: SystemProgram.programId,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}
+
+/**
+ * Claim instant tokens for a round milestone (investor)
+ *
+ * Multi-Round Fundraising: R2+ investors claim instant portion
+ * when milestone passes. Tokens come from FutureRoundVault.
+ */
+export async function claimRoundInstantTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Round number of the investment */
+    roundNumber: number;
+    /** Milestone index to claim tokens from */
+    milestoneIndex: number;
+    /** NFT mint proving investment ownership */
+    nftMint: PublicKey;
+    /** Investor's token account to receive claimed tokens */
+    investorTokenAccount: PublicKey;
+  },
+  investor: PublicKey
+): Promise<string> {
+  const nftMintPubkey = ensurePublicKey(args.nftMint);
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const fundingRoundPda = getFundingRoundPDA(projectPda, args.roundNumber, program.programId);
+  const milestonePda = getRoundMilestonePDA(projectPda, args.roundNumber, args.milestoneIndex, program.programId);
+  const investmentPda = getRoundInvestmentPDA(projectPda, args.roundNumber, nftMintPubkey, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const futureRoundVaultPda = getFutureRoundVaultPDA(projectPda, program.programId);
+  const futureRoundTokenVaultPda = getFutureRoundTokenVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  // Vesting PDA with round number
+  const vestingPda = getRoundInvestorMilestoneVestingPDA(
+    projectPda,
+    args.roundNumber,
+    args.milestoneIndex,
+    investmentPda,
+    program.programId
+  );
+
+  // Get investor's NFT token account (ATA)
+  const investorNftAccount = getAssociatedTokenAddressSync(
+    nftMintPubkey,
+    investor,
+    false,
+    TOKEN_PROGRAM_ID
+  );
+
+  return getMethods(program)
+    .claimRoundInstantTokens({ milestoneIndex: args.milestoneIndex })
+    .accountsPartial({
+      investor,
+      project: projectPda,
+      fundingRound: fundingRoundPda,
+      milestone: milestonePda,
+      investment: investmentPda,
+      tokenVault: tokenVaultPda,
+      futureRoundVault: futureRoundVaultPda,
+      vesting: vestingPda,
+      nftMint: nftMintPubkey,
+      investorNftAccount,
+      futureRoundTokenVault: futureRoundTokenVaultPda,
+      investorTokenAccount: args.investorTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+      systemProgram: SystemProgram.programId,
+    })
+    .rpc();
+}
+
+/**
+ * Claim vested tokens for a round milestone (investor)
+ *
+ * Multi-Round Fundraising: R2+ investors claim vested portion
+ * after cliff period. Tokens come from FutureRoundVault.
+ */
+export async function claimRoundVestedTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Round number of the investment */
+    roundNumber: number;
+    /** Milestone index to claim tokens from */
+    milestoneIndex: number;
+    /** NFT mint proving investment ownership */
+    nftMint: PublicKey;
+    /** Investor's token account to receive claimed tokens */
+    investorTokenAccount: PublicKey;
+  },
+  investor: PublicKey
+): Promise<string> {
+  const nftMintPubkey = ensurePublicKey(args.nftMint);
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const fundingRoundPda = getFundingRoundPDA(projectPda, args.roundNumber, program.programId);
+  const milestonePda = getRoundMilestonePDA(projectPda, args.roundNumber, args.milestoneIndex, program.programId);
+  const investmentPda = getRoundInvestmentPDA(projectPda, args.roundNumber, nftMintPubkey, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const futureRoundVaultPda = getFutureRoundVaultPDA(projectPda, program.programId);
+  const futureRoundTokenVaultPda = getFutureRoundTokenVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  // Vesting PDA with round number
+  const vestingPda = getRoundInvestorMilestoneVestingPDA(
+    projectPda,
+    args.roundNumber,
+    args.milestoneIndex,
+    investmentPda,
+    program.programId
+  );
+
+  // Get investor's NFT token account (ATA)
+  const investorNftAccount = getAssociatedTokenAddressSync(
+    nftMintPubkey,
+    investor,
+    false,
+    TOKEN_PROGRAM_ID
+  );
+
+  return getMethods(program)
+    .claimRoundVestedTokens({ milestoneIndex: args.milestoneIndex })
+    .accountsPartial({
+      investor,
+      project: projectPda,
+      fundingRound: fundingRoundPda,
+      milestone: milestonePda,
+      investment: investmentPda,
+      tokenVault: tokenVaultPda,
+      futureRoundVault: futureRoundVaultPda,
+      vesting: vestingPda,
+      nftMint: nftMintPubkey,
+      investorNftAccount,
+      futureRoundTokenVault: futureRoundTokenVaultPda,
+      investorTokenAccount: args.investorTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}
+
+/**
+ * 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.
+ */
+export async function claimRoundEarlyTokens(
+  program: AnyProgram,
+  args: {
+    projectId: BN;
+    /** Round number of the investment */
+    roundNumber: number;
+    /** NFT mint proving investment ownership */
+    nftMint: PublicKey;
+    /** Investor's token account to receive claimed tokens */
+    investorTokenAccount: PublicKey;
+  },
+  investor: PublicKey
+): Promise<string> {
+  const nftMintPubkey = ensurePublicKey(args.nftMint);
+  const projectPda = getProjectPDA(args.projectId, program.programId);
+  const fundingRoundPda = getFundingRoundPDA(projectPda, args.roundNumber, program.programId);
+  const investmentPda = getRoundInvestmentPDA(projectPda, args.roundNumber, nftMintPubkey, program.programId);
+  const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+  const futureRoundVaultPda = getFutureRoundVaultPDA(projectPda, program.programId);
+  const futureRoundTokenVaultPda = getFutureRoundTokenVaultPDA(projectPda, program.programId);
+  const vaultAuthorityPda = getVaultAuthorityPDA(projectPda, program.programId);
+
+  // Get investor's NFT token account (ATA)
+  const investorNftAccount = getAssociatedTokenAddressSync(
+    nftMintPubkey,
+    investor,
+    false,
+    TOKEN_PROGRAM_ID
+  );
+
+  return getMethods(program)
+    .claimRoundEarlyTokens()
+    .accountsPartial({
+      investor,
+      project: projectPda,
+      fundingRound: fundingRoundPda,
+      investment: investmentPda,
+      tokenVault: tokenVaultPda,
+      futureRoundVault: futureRoundVaultPda,
+      nftMint: nftMintPubkey,
+      investorNftAccount,
+      futureRoundTokenVault: futureRoundTokenVaultPda,
+      investorTokenAccount: args.investorTokenAccount,
+      vaultAuthority: vaultAuthorityPda,
+      tokenProgram: TOKEN_PROGRAM_ID,
+    })
+    .rpc();
+}