@zemyth/raise-sdk 0.1.0

package/src/pdas/index.ts

@@ -0,0 +1,404 @@
+/**
+ * Raise PDA Derivation Helpers
+ *
+ * All PDA derivation functions for the Raise program.
+ * PDAs are deterministic addresses derived from seeds and program ID.
+ */
+
+import { PublicKey } from '@solana/web3.js';
+import { BN } from '@coral-xyz/anchor';
+import { SEEDS } from '../constants/index.js';
+
+/**
+ * Ensure value is a proper BN instance
+ * This handles cases where BN objects lose their prototype chain
+ * (e.g., when passing through React state or JSON serialization)
+ *
+ * Uses duck typing instead of instanceof to handle different BN module instances
+ */
+function ensureBN(value: BN | number | string | { toString(): string }): BN {
+  // Duck typing: if it has toArrayLike, it's BN-like and we can use it
+  if (value && typeof (value as BN).toArrayLike === 'function') {
+    return value as BN;
+  }
+  // Always create a fresh BN from the SDK's imported BN class
+  return new BN(String(value));
+}
+
+/**
+ * Derive Project PDA from project ID
+ *
+ * @param projectId - Unique project identifier
+ * @param programId - Raise program ID
+ * @returns Project account PDA
+ */
+export function getProjectPDA(projectId: BN | number | string, programId: PublicKey): PublicKey {
+  const projectIdBN = ensureBN(projectId);
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.PROJECT), projectIdBN.toArrayLike(Buffer, 'le', 8)],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Escrow PDA from project ID
+ *
+ * @param projectId - Project identifier
+ * @param programId - Raise program ID
+ * @returns Escrow account PDA
+ */
+export function getEscrowPDA(projectId: BN | number | string, programId: PublicKey): PublicKey {
+  const projectIdBN = ensureBN(projectId);
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.ESCROW), projectIdBN.toArrayLike(Buffer, 'le', 8)],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Milestone PDA from project PDA and milestone index
+ *
+ * @param projectPda - Project account PDA
+ * @param milestoneIndex - Milestone index (0-based)
+ * @param programId - Raise program ID
+ * @returns Milestone account PDA
+ */
+export function getMilestonePDA(
+  projectPda: PublicKey,
+  milestoneIndex: number,
+  programId: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(SEEDS.MILESTONE),
+      projectPda.toBuffer(),
+      Buffer.from([milestoneIndex]),
+    ],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Investment PDA from project PDA and NFT mint
+ *
+ * @param projectPda - Project account PDA
+ * @param nftMint - Investment NFT mint address
+ * @param programId - Raise program ID
+ * @returns Investment account PDA
+ */
+export function getInvestmentPDA(
+  projectPda: PublicKey,
+  nftMint: PublicKey,
+  programId: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(SEEDS.INVESTMENT),
+      projectPda.toBuffer(),
+      nftMint.toBuffer(),
+    ],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Vote PDA from milestone PDA, voter key, and voting round
+ *
+ * @param milestonePda - Milestone account PDA
+ * @param voterKey - Voter's public key
+ * @param votingRound - Current voting round (0 initially, incremented on resubmit)
+ * @param programId - Raise program ID
+ * @returns Vote account PDA
+ */
+export function getVotePDA(
+  milestonePda: PublicKey,
+  voterKey: PublicKey,
+  votingRound: number,
+  programId: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.VOTE), milestonePda.toBuffer(), voterKey.toBuffer(), Buffer.from([votingRound])],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive PivotProposal PDA from project PDA and pivot count
+ *
+ * @param projectPda - Project account PDA
+ * @param pivotCount - Current pivot count from project account
+ * @param programId - Raise program ID
+ * @returns PivotProposal account PDA
+ */
+export function getPivotProposalPDA(
+  projectPda: PublicKey,
+  pivotCount: number,
+  programId: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(SEEDS.PIVOT), // Use PIVOT seed, not PIVOT_PROPOSAL
+      projectPda.toBuffer(),
+      Buffer.from([pivotCount]), // pivot_count is u8 (1 byte) on-chain
+    ],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive TgeEscrow PDA from project PDA
+ *
+ * @param projectPda - Project account PDA
+ * @param programId - Raise program ID
+ * @returns TgeEscrow account PDA
+ */
+export function getTgeEscrowPDA(
+  projectPda: PublicKey,
+  programId: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.TGE_ESCROW), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive TgeEscrowVault PDA from project PDA
+ * Used for holding 10% USDC holdback from final milestone
+ *
+ * @param projectPda - Project account PDA
+ * @param programId - Raise program ID
+ * @returns TgeEscrowVault PDA
+ */
+export function getTgeEscrowVaultPDA(
+  projectPda: PublicKey,
+  programId: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.TGE_ESCROW_VAULT), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive TokenVault PDA from project PDA
+ * Used for holding project tokens for investor distribution
+ *
+ * @param projectPda - Project account PDA
+ * @param programId - Raise program ID
+ * @returns TokenVault PDA
+ */
+export function getTokenVaultPDA(
+  projectPda: PublicKey,
+  programId: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('token_vault'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive ScamReport PDA from project PDA and NFT mint
+ *
+ * @param projectPda - Project account PDA
+ * @param nftMint - Reporter's NFT mint address
+ * @param programId - Raise program ID
+ * @returns ScamReport account PDA
+ */
+export function getScamReportPDA(
+  projectPda: PublicKey,
+  nftMint: PublicKey,
+  programId: PublicKey
+): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(SEEDS.SCAM_REPORT),
+      projectPda.toBuffer(),
+      nftMint.toBuffer(),
+    ],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive AdminConfig PDA (global admin authority)
+ *
+ * @param programId - Raise program ID
+ * @returns AdminConfig account PDA
+ */
+export function getAdminConfigPDA(programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.ADMIN_CONFIG)],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive NFT Mint PDA
+ *
+ * @param projectId - Project identifier
+ * @param investor - Investor's public key
+ * @param investmentCount - Investment count (u64 in Rust, 8 bytes LE)
+ * @param programId - Raise program ID
+ * @returns NFT Mint PDA and bump
+ */
+export function getNftMintPDA(
+  projectId: BN | number | string,
+  investor: PublicKey,
+  investmentCount: BN | number,
+  programId: PublicKey
+): [PublicKey, number] {
+  // Ensure both values are proper BN instances (handles prototype chain issues)
+  const projectIdBN = ensureBN(projectId);
+  const countBN = ensureBN(investmentCount);
+  return PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(SEEDS.NFT_MINT),
+      projectIdBN.toArrayLike(Buffer, 'le', 8),
+      investor.toBuffer(),
+      countBN.toArrayLike(Buffer, 'le', 8), // u64 is 8 bytes LE
+    ],
+    programId
+  );
+}
+
+/**
+ * Derive Program Authority PDA
+ *
+ * @param programId - Raise program ID
+ * @returns Program authority PDA and bump
+ */
+export function getProgramAuthorityPDA(programId: PublicKey): [PublicKey, number] {
+  return PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.AUTHORITY)],
+    programId
+  );
+}
+
+/**
+ * Helper to derive all PDAs for a project
+ *
+ * @param projectId - Project identifier
+ * @param programId - Raise program ID
+ * @returns Object with project and escrow PDAs
+ */
+export function getProjectPDAs(projectId: BN, programId: PublicKey) {
+  const project = getProjectPDA(projectId, programId);
+  const escrow = getEscrowPDA(projectId, programId);
+  return { project, escrow };
+}
+
+// =============================================================================
+// ZTM v2.0 PDAs
+// =============================================================================
+
+/**
+ * Derive Tokenomics PDA from project PDA
+ */
+export function getTokenomicsPDA(projectPda: PublicKey, programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('tokenomics'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Token Mint PDA from project PDA
+ */
+export function getTokenMintPDA(projectPda: PublicKey, programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('token_mint'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Vault Authority PDA from project PDA
+ */
+export function getVaultAuthorityPDA(projectPda: PublicKey, programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('vault_authority'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Investor Vault PDA from project PDA
+ */
+export function getInvestorVaultPDA(projectPda: PublicKey, programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('investor_vault'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Founder Vault PDA from project PDA
+ */
+export function getFounderVaultPDA(projectPda: PublicKey, programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('founder_vault'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive LP Token Vault PDA from project PDA
+ */
+export function getLpTokenVaultPDA(projectPda: PublicKey, programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('lp_token_vault'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Treasury Vault PDA from project PDA
+ */
+export function getTreasuryVaultPDA(projectPda: PublicKey, programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('treasury_vault'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive LP USDC Vault PDA from project PDA
+ */
+export function getLpUsdcVaultPDA(projectPda: PublicKey, programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('lp_usdc_vault'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+
+/**
+ * Derive Founder Vesting PDA from project PDA
+ */
+export function getFounderVestingPDA(projectPda: PublicKey, programId: PublicKey): PublicKey {
+  const [pda] = PublicKey.findProgramAddressSync(
+    [Buffer.from('founder_vesting'), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}

package/src/types/index.ts

@@ -0,0 +1,267 @@
+/**
+ * Raise Type Definitions
+ *
+ * Re-exports types from the IDL and provides additional utility types.
+ */
+
+import { PublicKey } from '@solana/web3.js';
+import { BN } from '@coral-xyz/anchor';
+
+// =============================================================================
+// Project State Enums
+// =============================================================================
+
+export enum ProjectState {
+  Draft = 'draft',
+  PendingApproval = 'pendingApproval',
+  Open = 'open',
+  Funded = 'funded',
+  InProgress = 'inProgress',
+  Completed = 'completed',
+  Abandoned = 'abandoned',
+  Failed = 'failed',
+  TGEFailed = 'tgeFailed',
+  Cancelled = 'cancelled',
+}
+
+export enum MilestoneState {
+  Proposed = 'proposed',
+  Approved = 'approved',
+  InProgress = 'inProgress',
+  UnderReview = 'underReview',
+  Passed = 'passed',
+  Failed = 'failed',
+  Unlocked = 'unlocked',
+}
+
+export enum VoteChoice {
+  Good = 'good',
+  Bad = 'bad',
+}
+
+export enum PivotState {
+  PendingModeratorApproval = 'pendingModeratorApproval',
+  ApprovedAwaitingInvestorWindow = 'approvedAwaitingInvestorWindow',
+  Finalized = 'finalized',
+}
+
+// =============================================================================
+// Account Types
+// =============================================================================
+
+/**
+ * Tier configuration stored on-chain (includes filled_lots)
+ */
+export interface Tier {
+  /** USDC amount per lot */
+  amount: BN;
+  /** Maximum lots available */
+  maxLots: number;
+  /** Currently filled lots */
+  filledLots: number;
+  /** Token allocation per $1 invested */
+  tokenRatio: BN;
+  /** Vote weight multiplier (basis points, 100 = 1.0x) */
+  voteMultiplier: number;
+}
+
+/**
+ * Tier configuration input for project initialization
+ * Founders pass these when creating a project
+ */
+export interface TierConfig {
+  /** USDC amount per lot (must be >= 10 USDC = 10_000_000 lamports) */
+  amount: BN;
+  /** Maximum lots available (must be >= 1) */
+  maxLots: number;
+  /** Token allocation per $1 invested (must be >= 1) */
+  tokenRatio: BN;
+  /** Vote weight multiplier (basis points, must be >= 100 = 1.0x) */
+  voteMultiplier: number;
+}
+
+export interface ProjectAccount {
+  founder: PublicKey;
+  projectId: BN;
+  fundingGoal: BN;
+  amountRaised: BN;
+  state: ProjectState;
+  metadataUri: string;
+  escrow: PublicKey;
+  currentMilestone: number;
+  totalMilestones: number;
+  /** Number of active tiers (1-10) */
+  tierCount: number;
+  /** All tier slots (only first tierCount are active) */
+  tiers: Tier[];
+  tokenMint: PublicKey | null;
+  tgeDate: BN | null;
+  tokensDeposited: BN;
+  tokenAllocationBps: number;
+  totalTokenAllocation: BN;
+  consecutiveFailures: number;
+  investorCount: number;
+  bump: number;
+}
+
+export interface MilestoneAccount {
+  project: PublicKey;
+  milestoneIndex: number;
+  percentage: number;
+  description: string;
+  state: MilestoneState;
+  yesVotes: BN;
+  noVotes: BN;
+  totalWeight: BN;
+  voterCount: number;
+  votingEndsAt: BN | null;
+  bump: number;
+}
+
+export interface InvestmentAccount {
+  project: PublicKey;
+  investor: PublicKey;
+  nftMint: PublicKey;
+  amount: BN;
+  voteWeight: BN;
+  tokenAllocation: BN;
+  tier: number;
+  investedAt: BN;
+  tokensClaimed: boolean;
+  withdrawnFromPivot: boolean;
+  refundClaimed: boolean;
+  bump: number;
+}
+
+export interface VoteAccount {
+  milestone: PublicKey;
+  voter: PublicKey;
+  choice: VoteChoice;
+  weight: BN;
+  votedAt: BN;
+  bump: number;
+}
+
+export interface AdminConfigAccount {
+  admin: PublicKey;
+  pendingAdmin: PublicKey | null;
+  bump: number;
+}
+
+export interface PivotProposalAccount {
+  project: PublicKey;
+  newMetadataUri: string;
+  newMilestones: Array<{ percentage: number; description: string }>;
+  state: PivotState;
+  proposedAt: BN;
+  approvedAt: BN | null;
+  withdrawalWindowEndsAt: BN | null;
+  withdrawnAmount: BN;
+  withdrawnCount: number;
+  bump: number;
+}
+
+export interface TgeEscrowAccount {
+  project: PublicKey;
+  holdbackAmount: BN;
+  scamReports: BN;
+  scamWeight: BN;
+  scamConfirmed: boolean;
+  holdbackReleased: boolean;
+  bump: number;
+}
+
+// =============================================================================
+// Instruction Arguments
+// =============================================================================
+
+export interface InitializeProjectArgs {
+  projectId: BN;
+  fundingGoal: BN;
+  metadataUri: string;
+  /** Founder-configured tiers (1-10 tiers) */
+  tiers: TierConfig[];
+}
+
+export interface CreateMilestoneArgs {
+  milestoneIndex: number;
+  percentage: number;
+  description: string;
+}
+
+export interface InvestArgs {
+  amount: BN;
+}
+
+export interface VoteOnMilestoneArgs {
+  choice: VoteChoice;
+}
+
+export interface SetTgeDateArgs {
+  tgeDate: BN;
+  tokenMint: PublicKey;
+}
+
+export interface DepositTokensArgs {
+  amount: BN;
+}
+
+export interface ProposePivotArgs {
+  newMetadataUri: string;
+  newMilestones: Array<{ percentage: number; description: string }>;
+}
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+export interface ProjectCreatedEvent {
+  projectId: BN;
+  founder: PublicKey;
+  fundingGoal: BN;
+  metadataUri: string;
+}
+
+export interface InvestmentMadeEvent {
+  projectId: BN;
+  investor: PublicKey;
+  amount: BN;
+  nftMint: PublicKey;
+  tier: number;
+  voteWeight: BN;
+}
+
+export interface MilestoneVoteCastEvent {
+  projectId: BN;
+  milestoneIndex: number;
+  voter: PublicKey;
+  choice: VoteChoice;
+  weight: BN;
+}
+
+export interface MilestoneVoteFinalizedEvent {
+  projectId: BN;
+  milestoneIndex: number;
+  passed: boolean;
+  yesVotes: BN;
+  noVotes: BN;
+}
+
+// =============================================================================
+// Utility Types
+// =============================================================================
+
+export interface InvestmentWithKey {
+  publicKey: PublicKey;
+  account: InvestmentAccount;
+}
+
+export interface MilestoneWithKey {
+  publicKey: PublicKey;
+  account: MilestoneAccount;
+}
+
+export interface VoteWithKey {
+  publicKey: PublicKey;
+  account: VoteAccount;
+}