@zemyth/raise-sdk 0.1.1 → 0.1.3

package/src/accounts/index.ts

@@ -14,8 +14,20 @@ import {
   getPivotProposalPDA,
   getTgeEscrowPDA,
   getAdminConfigPDA,
+  getTokenVaultPDA,
+  getTokenomicsPDA,
+  getAllocationProposalPDA,
+  getAllocationVotePDA,
+  getSubAllocationVestingPDA,
+  getInvestorMilestoneVestingPDA,
+  getFounderMilestoneVestingPDA,
+  getFundingRoundPDA,
+  getRoundMilestonePDA,
+  getRoundInvestmentPDA,
+  getRoundInvestorMilestoneVestingPDA,
+  getFutureRoundVaultPDA,
 } from '../pdas/index.js';
-import type { InvestmentWithKey, MilestoneWithKey, VoteWithKey } from '../types/index.js';
+import type { InvestmentWithKey, MilestoneWithKey, VoteWithKey, AllocationProposalWithKey, FundingRoundWithKey } from '../types/index.js';
 
 // Generic type for any Anchor program
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -306,6 +318,29 @@ export async function fetchAdminConfig(program: AnyProgram) {
   return await getAccountNamespace(program).adminConfig.fetch(adminConfigPda);
 }
 
+/**
+ * Fetch token vault account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @returns TokenVault account data or null if not found
+ */
+export async function fetchTokenVault(
+  program: AnyProgram,
+  projectId: BN
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const tokenVaultPda = getTokenVaultPDA(projectPda, program.programId);
+    return await getAccountNamespace(program).tokenVault.fetch(tokenVaultPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
 /**
  * Check if an account exists
  *
@@ -327,3 +362,819 @@ export async function accountExists(
     return false;
   }
 }
+
+// =============================================================================
+// Dynamic Tokenomics Account Fetchers
+// =============================================================================
+
+/**
+ * Fetch tokenomics account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @returns Tokenomics account data or null if not found
+ */
+export async function fetchTokenomics(
+  program: AnyProgram,
+  projectId: BN
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const tokenomicsPda = getTokenomicsPDA(projectPda, program.programId);
+    return await getAccountNamespace(program).tokenomics.fetch(tokenomicsPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Fetch allocation proposal account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param proposalIndex - Proposal index
+ * @returns AllocationProposal account data or null if not found
+ */
+export async function fetchAllocationProposal(
+  program: AnyProgram,
+  projectId: BN,
+  proposalIndex: number
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const proposalPda = getAllocationProposalPDA(projectPda, proposalIndex, program.programId);
+    return await getAccountNamespace(program).allocationProposal.fetch(proposalPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Fetch all allocation proposals for a project
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @returns Array of allocation proposal accounts with their public keys
+ */
+export async function fetchAllAllocationProposals(
+  program: AnyProgram,
+  projectId: BN
+): Promise<AllocationProposalWithKey[]> {
+  const projectPda = getProjectPDA(projectId, program.programId);
+
+  const proposals = await getAccountNamespace(program).allocationProposal.all([
+    {
+      memcmp: {
+        offset: 8, // Skip discriminator
+        bytes: projectPda.toBase58(),
+      },
+    },
+  ]);
+
+  return proposals.map((p: { publicKey: PublicKey; account: unknown }) => ({
+    publicKey: p.publicKey,
+    account: p.account,
+  })) as AllocationProposalWithKey[];
+}
+
+/**
+ * Fetch allocation vote account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param proposalIndex - Proposal index
+ * @param nftMint - NFT mint used for voting
+ * @returns AllocationVote account data or null if not found
+ */
+export async function fetchAllocationVote(
+  program: AnyProgram,
+  projectId: BN,
+  proposalIndex: number,
+  nftMint: PublicKey
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const proposalPda = getAllocationProposalPDA(projectPda, proposalIndex, program.programId);
+    const votePda = getAllocationVotePDA(proposalPda, nftMint, program.programId);
+    return await getAccountNamespace(program).allocationVote.fetch(votePda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Fetch sub-allocation vesting account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param subAllocationId - Sub-allocation ID (0-9)
+ * @returns SubAllocationVesting account data or null if not found
+ */
+export async function fetchSubAllocationVesting(
+  program: AnyProgram,
+  projectId: BN,
+  subAllocationId: number
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const vestingPda = getSubAllocationVestingPDA(projectPda, subAllocationId, program.programId);
+    return await getAccountNamespace(program).subAllocationVesting.fetch(vestingPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+// =============================================================================
+// Per-Milestone Vesting Account Fetchers
+// =============================================================================
+
+/**
+ * Fetch investor milestone vesting account data
+ *
+ * Per-milestone vesting: Each investor has a separate vesting PDA for each
+ * milestone they claim tokens from.
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param milestoneIndex - Milestone index
+ * @param nftMint - NFT mint that proves investment ownership
+ * @returns InvestorMilestoneVesting account data or null if not found
+ */
+export async function fetchInvestorMilestoneVesting(
+  program: AnyProgram,
+  projectId: BN,
+  milestoneIndex: number,
+  nftMint: PublicKey
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const investmentPda = getInvestmentPDA(projectPda, nftMint, program.programId);
+    const vestingPda = getInvestorMilestoneVestingPDA(projectPda, milestoneIndex, investmentPda, program.programId);
+    return await getAccountNamespace(program).investorMilestoneVesting.fetch(vestingPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Fetch founder milestone vesting account data
+ *
+ * Per-milestone vesting: Each milestone has a separate vesting PDA for the
+ * founder's milestone-based allocation.
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param milestoneIndex - Milestone index
+ * @returns FounderMilestoneVesting account data or null if not found
+ */
+export async function fetchFounderMilestoneVesting(
+  program: AnyProgram,
+  projectId: BN,
+  milestoneIndex: number
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const vestingPda = getFounderMilestoneVestingPDA(projectPda, milestoneIndex, program.programId);
+    return await getAccountNamespace(program).founderMilestoneVesting.fetch(vestingPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+// =============================================================================
+// Early Token Release Helpers
+// =============================================================================
+
+/** Early token cooling period in seconds (24 hours in production, 10s in dev) */
+export const EARLY_TOKEN_COOLING_PERIOD_SECONDS = 86_400; // 24 hours
+export const EARLY_TOKEN_COOLING_PERIOD_SECONDS_DEV = 10; // 10 seconds for dev
+
+/** Early token release percentage in basis points (500 = 5%) */
+export const EARLY_TOKEN_RELEASE_BPS = 500;
+
+/**
+ * Check if an investor can claim early tokens
+ *
+ * Early Token Release: Investors can claim 5% of their token allocation
+ * 24 hours after investing. This helper checks eligibility.
+ *
+ * @param investment - Investment account data
+ * @param currentTimestamp - Current Unix timestamp (optional, uses Date.now() if not provided)
+ * @param isDev - Use dev mode (10s) or production mode (24h) cooling period
+ * @returns Object with canClaim boolean, reason if ineligible, and time remaining if cooling period not expired
+ */
+export function canClaimEarlyTokens(
+  investment: {
+    earlyTokensClaimed: boolean;
+    investedAt: BN | number;
+    votingRightsActive?: boolean;
+    withdrawnFromPivot?: boolean;
+  },
+  currentTimestamp?: number,
+  isDev: boolean = false
+): { canClaim: boolean; reason?: string; timeRemainingSeconds?: number } {
+  const now = currentTimestamp ?? Math.floor(Date.now() / 1000);
+  const coolingPeriod = isDev ? EARLY_TOKEN_COOLING_PERIOD_SECONDS_DEV : EARLY_TOKEN_COOLING_PERIOD_SECONDS;
+
+  // Check if already claimed
+  if (investment.earlyTokensClaimed) {
+    return { canClaim: false, reason: 'Early tokens already claimed' };
+  }
+
+  // Check if voting rights are active
+  if (investment.votingRightsActive === false) {
+    return { canClaim: false, reason: 'Voting rights have been revoked' };
+  }
+
+  // Check if withdrawn from pivot
+  if (investment.withdrawnFromPivot === true) {
+    return { canClaim: false, reason: 'Investment has been withdrawn from pivot' };
+  }
+
+  // Check cooling period
+  const investedAt = typeof investment.investedAt === 'number'
+    ? investment.investedAt
+    : investment.investedAt.toNumber();
+
+  const coolingEndTime = investedAt + coolingPeriod;
+
+  if (now < coolingEndTime) {
+    const timeRemaining = coolingEndTime - now;
+    return {
+      canClaim: false,
+      reason: `Cooling period not expired. ${formatTimeRemaining(timeRemaining)} remaining.`,
+      timeRemainingSeconds: timeRemaining,
+    };
+  }
+
+  return { canClaim: true };
+}
+
+/**
+ * Check if a founder can claim early tokens
+ *
+ * Early Token Release: Founders can claim 5% of their token allocation
+ * when the project becomes Funded. This helper checks eligibility.
+ *
+ * @param project - Project account data
+ * @returns Object with canClaim boolean and reason if ineligible
+ */
+export function canClaimFounderEarlyTokens(
+  project: {
+    state: unknown;
+    founderEarlyTokensClaimed: boolean;
+  }
+): { canClaim: boolean; reason?: string } {
+  // Check if already claimed
+  if (project.founderEarlyTokensClaimed) {
+    return { canClaim: false, reason: 'Founder early tokens already claimed' };
+  }
+
+  // Check project state - must be Funded, InProgress, or Completed
+  // These states are represented as objects with a single key in Anchor
+  const stateStr = getProjectStateString(project.state);
+  const validStates = ['funded', 'inProgress', 'completed'];
+
+  if (!validStates.includes(stateStr)) {
+    return {
+      canClaim: false,
+      reason: `Project must be in Funded, InProgress, or Completed state. Current state: ${stateStr}`,
+    };
+  }
+
+  return { canClaim: true };
+}
+
+/**
+ * Check if a founder can claim milestone-based tokens
+ *
+ * Early Token Release: Founders can claim milestone-based tokens when
+ * milestones are unlocked. This helper checks eligibility.
+ *
+ * @param milestone - Milestone account data
+ * @returns Object with canClaim boolean and reason if ineligible
+ */
+export function canClaimFounderMilestoneTokens(
+  milestone: {
+    state: unknown;
+  }
+): { canClaim: boolean; reason?: string } {
+  // Check milestone state - must be Unlocked
+  const stateStr = getMilestoneStateString(milestone.state);
+  if (stateStr !== 'unlocked') {
+    return {
+      canClaim: false,
+      reason: `Milestone must be in Unlocked state. Current state: ${stateStr}`,
+    };
+  }
+
+  return { canClaim: true };
+}
+
+/**
+ * Check if an investor needs to burn tokens for a refund
+ *
+ * Early Token Release: If the project has no milestones claimed (cumulative_percentage == 0)
+ * AND the investor has claimed early tokens, they must burn those tokens to get a full refund.
+ *
+ * @param project - Project account data
+ * @param investment - Investment account data
+ * @returns Object indicating whether burn is required
+ */
+export function requiresBurnForRefund(
+  project: {
+    cumulativePercentage: number;
+  },
+  investment: {
+    earlyTokensClaimed: boolean;
+    earlyTokensAmount: BN | number;
+  }
+): { requiresBurn: boolean; burnAmount: number } {
+  const isFullRefund = project.cumulativePercentage === 0;
+  const requiresBurn = isFullRefund && investment.earlyTokensClaimed;
+
+  if (!requiresBurn) {
+    return { requiresBurn: false, burnAmount: 0 };
+  }
+
+  const burnAmount = typeof investment.earlyTokensAmount === 'number'
+    ? investment.earlyTokensAmount
+    : investment.earlyTokensAmount.toNumber();
+
+  return { requiresBurn: true, burnAmount };
+}
+
+/**
+ * Calculate early token amount for an investment
+ *
+ * @param tokensAllocated - Total tokens allocated to the investment
+ * @returns Early token amount (5% of allocation)
+ */
+export function calculateEarlyTokenAmount(tokensAllocated: BN | number): BN {
+  const allocated = typeof tokensAllocated === 'number'
+    ? new BN(tokensAllocated)
+    : tokensAllocated;
+
+  return allocated.muln(EARLY_TOKEN_RELEASE_BPS).divn(10000);
+}
+
+/**
+ * Calculate remaining token allocation after early tokens are claimed
+ *
+ * @param tokensAllocated - Total tokens allocated
+ * @returns Remaining allocation (95% of total)
+ */
+export function calculateRemainingAllocation(tokensAllocated: BN | number): BN {
+  const allocated = typeof tokensAllocated === 'number'
+    ? new BN(tokensAllocated)
+    : tokensAllocated;
+
+  const remainingBps = 10000 - EARLY_TOKEN_RELEASE_BPS; // 9500 = 95%
+  return allocated.muln(remainingBps).divn(10000);
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Format time remaining in human-readable format
+ */
+function formatTimeRemaining(seconds: number): string {
+  if (seconds <= 0) return '0 seconds';
+
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const secs = seconds % 60;
+
+  const parts: string[] = [];
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (secs > 0 && hours === 0) parts.push(`${secs}s`);
+
+  return parts.join(' ') || '0 seconds';
+}
+
+/**
+ * Convert Anchor project state object to string
+ */
+function getProjectStateString(state: unknown): string {
+  if (typeof state === 'object' && state !== null) {
+    const keys = Object.keys(state);
+    return keys[0]?.toLowerCase() ?? 'unknown';
+  }
+  return 'unknown';
+}
+
+/**
+ * Convert Anchor milestone state object to string
+ */
+function getMilestoneStateString(state: unknown): string {
+  if (typeof state === 'object' && state !== null) {
+    const keys = Object.keys(state);
+    return keys[0]?.toLowerCase() ?? 'unknown';
+  }
+  return 'unknown';
+}
+
+// =============================================================================
+// Multi-Round Fundraising Account Fetchers
+// =============================================================================
+
+/**
+ * Fetch FundingRound account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param roundNumber - Round number (2, 3, 4...)
+ * @returns FundingRound account data or null if not found
+ */
+export async function fetchFundingRound(
+  program: AnyProgram,
+  projectId: BN,
+  roundNumber: number
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const fundingRoundPda = getFundingRoundPDA(projectPda, roundNumber, program.programId);
+    return await getAccountNamespace(program).fundingRound.fetch(fundingRoundPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Fetch all FundingRounds for a project
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @returns Array of FundingRound accounts with their public keys
+ */
+export async function fetchAllFundingRounds(
+  program: AnyProgram,
+  projectId: BN
+): Promise<FundingRoundWithKey[]> {
+  const projectPda = getProjectPDA(projectId, program.programId);
+
+  const rounds = await getAccountNamespace(program).fundingRound.all([
+    {
+      memcmp: {
+        offset: 8, // Skip discriminator
+        bytes: projectPda.toBase58(),
+      },
+    },
+  ]);
+
+  return rounds.map((r: { publicKey: PublicKey; account: unknown }) => ({
+    publicKey: r.publicKey,
+    account: r.account,
+  })) as FundingRoundWithKey[];
+}
+
+/**
+ * Fetch round milestone account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param roundNumber - Round number
+ * @param milestoneIndex - Milestone index
+ * @returns Milestone account data or null if not found
+ */
+export async function fetchRoundMilestone(
+  program: AnyProgram,
+  projectId: BN,
+  roundNumber: number,
+  milestoneIndex: number
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const milestonePda = getRoundMilestonePDA(projectPda, roundNumber, milestoneIndex, program.programId);
+    return await getAccountNamespace(program).milestone.fetch(milestonePda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Fetch round investment account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param roundNumber - Round number
+ * @param nftMint - Investment NFT mint address
+ * @returns Investment account data or null if not found
+ */
+export async function fetchRoundInvestment(
+  program: AnyProgram,
+  projectId: BN,
+  roundNumber: number,
+  nftMint: PublicKey
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const investmentPda = getRoundInvestmentPDA(projectPda, roundNumber, nftMint, program.programId);
+    return await getAccountNamespace(program).investment.fetch(investmentPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Fetch round investor milestone vesting account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param roundNumber - Round number
+ * @param milestoneIndex - Milestone index
+ * @param nftMint - NFT mint that proves investment ownership
+ * @returns InvestorMilestoneVesting account data or null if not found
+ */
+export async function fetchRoundInvestorMilestoneVesting(
+  program: AnyProgram,
+  projectId: BN,
+  roundNumber: number,
+  milestoneIndex: number,
+  nftMint: PublicKey
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const investmentPda = getRoundInvestmentPDA(projectPda, roundNumber, nftMint, program.programId);
+    const vestingPda = getRoundInvestorMilestoneVestingPDA(
+      projectPda,
+      roundNumber,
+      milestoneIndex,
+      investmentPda,
+      program.programId
+    );
+    return await getAccountNamespace(program).investorMilestoneVesting.fetch(vestingPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Fetch FutureRoundVault account data
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @returns FutureRoundVault account data or null if not found
+ */
+export async function fetchFutureRoundVault(
+  program: AnyProgram,
+  projectId: BN
+) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const vaultPda = getFutureRoundVaultPDA(projectPda, program.programId);
+    return await getAccountNamespace(program).futureRoundVault.fetch(vaultPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes('Account does not exist')) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Check if an investor can claim R2+ early tokens
+ *
+ * @param investment - Investment account data (from R2+ round)
+ * @param currentTimestamp - Current Unix timestamp
+ * @param isDev - Use dev mode cooling period
+ * @returns Eligibility check result
+ */
+export function canClaimRoundEarlyTokens(
+  investment: {
+    earlyTokensClaimed: boolean;
+    investedAt: BN | number;
+    votingRightsActive?: boolean;
+    roundNumber: number;
+  },
+  currentTimestamp?: number,
+  isDev: boolean = false
+): { canClaim: boolean; reason?: string; timeRemainingSeconds?: number } {
+  // Must be R2+ investment
+  if (investment.roundNumber < 2) {
+    return { canClaim: false, reason: 'R1 investments use claim_investor_early_tokens instruction' };
+  }
+
+  // Delegate to the common early token check
+  return canClaimEarlyTokens(investment, currentTimestamp, isDev);
+}
+
+// =============================================================================
+// Multi-Round Funding Eligibility Helpers
+// =============================================================================
+
+/**
+ * Check if R1 (Project-based round) is fully funded
+ *
+ * @param project - Project account data
+ * @returns True if total_raised >= funding_goal
+ */
+export function isR1FullyFunded(
+  project: {
+    totalRaised: BN | number;
+    fundingGoal: BN | number;
+  }
+): boolean {
+  const raised = typeof project.totalRaised === 'number'
+    ? new BN(project.totalRaised)
+    : project.totalRaised;
+  const goal = typeof project.fundingGoal === 'number'
+    ? new BN(project.fundingGoal)
+    : project.fundingGoal;
+
+  return raised.gte(goal);
+}
+
+/**
+ * Check if a FundingRound (R2+) is fully funded
+ *
+ * A round is considered "fully funded" when it reaches the Funded, InProgress, or Completed state.
+ *
+ * @param fundingRound - FundingRound account data
+ * @returns True if round state is Funded, InProgress, or Completed
+ */
+export function isFundingRoundFullyFunded(
+  fundingRound: {
+    state: unknown;
+    totalRaised?: BN | number;
+    fundingGoal?: BN | number;
+  }
+): boolean {
+  const stateStr = getRoundStateString(fundingRound.state);
+  return ['funded', 'inProgress', 'inprogress', 'completed'].includes(stateStr);
+}
+
+/**
+ * Check if a round (R1 or R2+) is fully funded
+ *
+ * For R1: Checks project.totalRaised >= project.fundingGoal
+ * For R2+: Checks fundingRound.state is Funded or beyond
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @param roundNumber - Round number (1 for R1, 2+ for subsequent rounds)
+ * @returns True if the round is fully funded
+ */
+export async function isRoundFullyFunded(
+  program: AnyProgram,
+  projectId: BN,
+  roundNumber: number
+): Promise<boolean> {
+  if (roundNumber === 1) {
+    // R1 uses Project state
+    const project = await fetchProject(program, projectId);
+    if (!project) return false;
+    return isR1FullyFunded(project);
+  } else {
+    // R2+ uses FundingRound state
+    const fundingRound = await fetchFundingRound(program, projectId, roundNumber);
+    if (!fundingRound) return false;
+    return isFundingRoundFullyFunded(fundingRound);
+  }
+}
+
+/**
+ * Check if a project can open the next funding round
+ *
+ * Requirements:
+ * 1. Project must be InProgress or Completed
+ * 2. At least 1 milestone must have passed (for InProgress projects)
+ * 3. Current round must be fully funded
+ * 4. No other round is currently in Open state
+ * 5. Future round allocation must be available
+ *
+ * @param program - Anchor program instance
+ * @param projectId - Project identifier
+ * @returns Eligibility check result with reason if ineligible
+ */
+export async function canOpenNextRound(
+  program: AnyProgram,
+  projectId: BN
+): Promise<{ canOpen: boolean; reason?: string; nextRoundNumber?: number }> {
+  // Fetch project
+  const project = await fetchProject(program, projectId);
+  if (!project) {
+    return { canOpen: false, reason: 'Project not found' };
+  }
+
+  const projectState = getProjectStateString(project.state);
+
+  // 1. Project must be InProgress or Completed
+  if (!['inProgress', 'inprogress', 'completed'].includes(projectState)) {
+    return {
+      canOpen: false,
+      reason: `Project must be in InProgress or Completed state. Current: ${projectState}`,
+    };
+  }
+
+  // 2. At least 1 milestone must have passed (for InProgress)
+  if (projectState !== 'completed' && project.milestonesPassed === 0) {
+    return {
+      canOpen: false,
+      reason: 'At least one milestone must pass before opening next round',
+    };
+  }
+
+  // 3. No other round currently active
+  if (project.activeRound !== 0) {
+    return {
+      canOpen: false,
+      reason: `Round ${project.activeRound} is already active`,
+    };
+  }
+
+  // 4. Current round must be fully funded
+  const currentRound = project.roundCount;
+  const isCurrentFunded = await isRoundFullyFunded(program, projectId, currentRound);
+  if (!isCurrentFunded) {
+    return {
+      canOpen: false,
+      reason: `Current round ${currentRound} must be fully funded before opening next round`,
+    };
+  }
+
+  // 5. Future round allocation must be available
+  const tokenomics = await fetchTokenomics(program, projectId);
+  if (!tokenomics) {
+    return { canOpen: false, reason: 'Tokenomics not found' };
+  }
+
+  if (tokenomics.futureRoundAllocationBps === 0) {
+    return {
+      canOpen: false,
+      reason: 'No future round allocation configured',
+    };
+  }
+
+  const remainingAllocation = tokenomics.futureRoundAllocationBps - (tokenomics.usedFutureRoundBps || 0);
+  if (remainingAllocation <= 0) {
+    return {
+      canOpen: false,
+      reason: 'Future round allocation pool exhausted',
+    };
+  }
+
+  return {
+    canOpen: true,
+    nextRoundNumber: currentRound + 1,
+  };
+}
+
+/**
+ * Get remaining future round allocation in basis points
+ *
+ * @param tokenomics - Tokenomics account data
+ * @returns Remaining allocation in BPS
+ */
+export function getRemainingFutureRoundAllocation(
+  tokenomics: {
+    futureRoundAllocationBps: number;
+    usedFutureRoundBps?: number;
+  }
+): number {
+  return tokenomics.futureRoundAllocationBps - (tokenomics.usedFutureRoundBps || 0);
+}
+
+/**
+ * Convert Anchor round state object to string
+ */
+function getRoundStateString(state: unknown): string {
+  if (typeof state === 'object' && state !== null) {
+    const keys = Object.keys(state);
+    return keys[0]?.toLowerCase() ?? 'unknown';
+  }
+  return 'unknown';
+}