@zemyth/raise-sdk 0.1.0

package/src/constants/index.ts

@@ -0,0 +1,205 @@
+/**
+ * Raise Constants
+ *
+ * Mirrors the on-chain program constants for client-side validation
+ * and display purposes.
+ */
+
+// =============================================================================
+// PDA Seeds
+// =============================================================================
+
+export const SEEDS = {
+  PROJECT: 'project',
+  MILESTONE: 'milestone',
+  INVESTMENT: 'investment',
+  VOTE: 'vote',
+  ESCROW: 'escrow',
+  PIVOT: 'pivot',
+  PIVOT_PROPOSAL: 'pivot_proposal',
+  TGE_ESCROW: 'tge_escrow',
+  TGE_ESCROW_VAULT: 'tge_escrow_vault',
+  SCAM_REPORT: 'scam_report',
+  ADMIN_CONFIG: 'admin-config',
+  NFT_MINT: 'nft_mint',
+  AUTHORITY: 'authority',
+} as const;
+
+// =============================================================================
+// Validation Constants
+// =============================================================================
+
+export const VALIDATION = {
+  /** Minimum number of milestones per project */
+  MIN_MILESTONES: 2,
+  /** Maximum number of milestones per project */
+  MAX_MILESTONES: 10,
+  /** Milestone percentages must sum to this value */
+  MILESTONE_PERCENTAGE_SUM: 100,
+  /** Maximum funding buffer (110% of goal) */
+  MAX_FUNDING_BUFFER_PERCENT: 110,
+  /** Maximum metadata URI length */
+  MAX_METADATA_URI_LENGTH: 200,
+  /** Maximum pivot description length */
+  MAX_PIVOT_DESCRIPTION_LEN: 256,
+  /** Maximum pivot vision length */
+  MAX_PIVOT_VISION_LEN: 512,
+  /** Maximum pivot justification length */
+  MAX_PIVOT_JUSTIFICATION_LEN: 512,
+} as const;
+
+// =============================================================================
+// Timing Constants (in seconds)
+// =============================================================================
+
+export const TIMING = {
+  /** Production voting period (14 days) */
+  VOTING_PERIOD_SECONDS: 1_209_600,
+  /** Production hold period (7 days) */
+  HOLD_PERIOD_SECONDS: 604_800,
+  /** Inactivity timeout (90 days) */
+  INACTIVITY_TIMEOUT_SECONDS: 7_776_000,
+  /** Abandonment timeout (90 days) */
+  ABANDONMENT_TIMEOUT_SECONDS: 7_776_000,
+  /** Refund window (14 days) */
+  REFUND_WINDOW_SECONDS: 1_209_600,
+  /** Pivot withdrawal window (7 days) */
+  PIVOT_WITHDRAWAL_WINDOW_SECONDS: 604_800,
+  /** Minimum TGE date (15 days from now) */
+  TGE_MIN_DAYS: 1_296_000,
+  /** Maximum TGE date (90 days from now) */
+  TGE_MAX_DAYS: 7_776_000,
+  /** Post-TGE holdback period (30 days) */
+  POST_TGE_HOLDBACK_DAYS: 2_592_000,
+} as const;
+
+// =============================================================================
+// Tier Configuration Constraints
+// =============================================================================
+
+export const TIER_CONSTRAINTS = {
+  /** Minimum number of tiers */
+  MIN_TIERS: 1,
+  /** Maximum number of tiers */
+  MAX_TIERS: 10,
+  /** Minimum tier amount (10 USDC in lamports) */
+  MIN_TIER_AMOUNT: 10_000_000n,
+  /** Minimum max_lots per tier */
+  MIN_TIER_MAX_LOTS: 1,
+  /** Minimum token ratio */
+  MIN_TIER_TOKEN_RATIO: 1n,
+  /** Minimum vote multiplier (100 = 1.0x) */
+  MIN_TIER_VOTE_MULTIPLIER: 100,
+} as const;
+
+// =============================================================================
+// Investment Tiers (Legacy - kept for backwards compatibility)
+// =============================================================================
+
+export enum InvestmentTier {
+  Bronze = 'Bronze',
+  Silver = 'Silver',
+  Gold = 'Gold',
+  Platinum = 'Platinum',
+  Diamond = 'Diamond',
+}
+
+/** Investment tier minimum amounts in USDC lamports (6 decimals) - LEGACY */
+export const TIER_MINIMUMS = {
+  [InvestmentTier.Bronze]: 100_000_000n,    // 100 USDC
+  [InvestmentTier.Silver]: 500_000_000n,    // 500 USDC
+  [InvestmentTier.Gold]: 1_000_000_000n,    // 1,000 USDC
+  [InvestmentTier.Platinum]: 5_000_000_000n,  // 5,000 USDC
+  [InvestmentTier.Diamond]: 10_000_000_000n,  // 10,000 USDC
+} as const;
+
+/** Vote weight multipliers (scaled by 100) - LEGACY */
+export const TIER_VOTE_MULTIPLIERS = {
+  [InvestmentTier.Bronze]: 100,    // 1.0x
+  [InvestmentTier.Silver]: 120,    // 1.2x
+  [InvestmentTier.Gold]: 150,      // 1.5x
+  [InvestmentTier.Platinum]: 200,  // 2.0x
+  [InvestmentTier.Diamond]: 300,   // 3.0x
+} as const;
+
+/** Token allocation multipliers (same as vote multipliers) - LEGACY */
+export const TIER_TOKEN_MULTIPLIERS = {
+  [InvestmentTier.Bronze]: 100,
+  [InvestmentTier.Silver]: 120,
+  [InvestmentTier.Gold]: 150,
+  [InvestmentTier.Platinum]: 200,
+  [InvestmentTier.Diamond]: 300,
+} as const;
+
+/** Get tier from investment amount (in lamports) - LEGACY, use project.tiers instead */
+export function getTierFromAmount(amount: bigint): InvestmentTier {
+  if (amount >= TIER_MINIMUMS[InvestmentTier.Diamond]) return InvestmentTier.Diamond;
+  if (amount >= TIER_MINIMUMS[InvestmentTier.Platinum]) return InvestmentTier.Platinum;
+  if (amount >= TIER_MINIMUMS[InvestmentTier.Gold]) return InvestmentTier.Gold;
+  if (amount >= TIER_MINIMUMS[InvestmentTier.Silver]) return InvestmentTier.Silver;
+  return InvestmentTier.Bronze;
+}
+
+/** Get vote multiplier for an investment amount - LEGACY */
+export function getVoteMultiplier(amount: bigint): number {
+  const tier = getTierFromAmount(amount);
+  return TIER_VOTE_MULTIPLIERS[tier] / 100;
+}
+
+/** Get token multiplier for an investment amount - LEGACY */
+export function getTokenMultiplier(amount: bigint): number {
+  const tier = getTierFromAmount(amount);
+  return TIER_TOKEN_MULTIPLIERS[tier] / 100;
+}
+
+/**
+ * Find matching tier index for an investment amount (threshold-based)
+ * Returns the highest tier where amount >= tier.amount
+ */
+export function findTierIndex(tiers: Array<{ amount: bigint }>, amount: bigint): number | null {
+  for (let i = tiers.length - 1; i >= 0; i--) {
+    if (amount >= tiers[i].amount) {
+      return i;
+    }
+  }
+  return null;
+}
+
+// =============================================================================
+// Voting and Governance
+// =============================================================================
+
+export const GOVERNANCE = {
+  /** Scam report threshold (30%) */
+  SCAM_THRESHOLD_PERCENT: 30,
+  /** Consecutive milestone failures before exit window eligible */
+  CONSECUTIVE_FAILURES_THRESHOLD: 3,
+  /** Milestone approval threshold (>50% weighted approval per whitepaper voting.md:100-101) */
+  MILESTONE_APPROVAL_THRESHOLD_PERCENT: 50,
+} as const;
+
+// =============================================================================
+// NFT Constants
+// =============================================================================
+
+export const NFT = {
+  /** NFT symbol */
+  SYMBOL: 'SNI',
+  /** NFT name prefix */
+  NAME_PREFIX: 'Raise Investment #',
+  /** Royalty basis points (2%) */
+  ROYALTY_BASIS_POINTS: 200,
+} as const;
+
+// =============================================================================
+// USDC Constants
+// =============================================================================
+
+export const USDC = {
+  /** USDC decimals */
+  DECIMALS: 6,
+  /** Convert USDC to lamports */
+  toAmount: (usdc: number): bigint => BigInt(Math.floor(usdc * 10 ** 6)),
+  /** Convert lamports to USDC */
+  fromAmount: (lamports: bigint): number => Number(lamports) / 10 ** 6,
+} as const;

package/src/errors/index.ts

@@ -0,0 +1,222 @@
+/**
+ * Raise Error Handling
+ *
+ * Maps program error codes to SDK errors with helpful messages.
+ */
+
+import { AnchorError } from '@coral-xyz/anchor';
+
+// =============================================================================
+// Error Codes (matching Rust program)
+// =============================================================================
+
+export const ERROR_CODES = {
+  // State Transition Errors (6000-6099)
+  InvalidStateTransition: 6000,
+  ProjectNotInOpenState: 6001,
+  ProjectNotInProgress: 6002,
+  MilestoneNotUnderReview: 6003,
+  VotingPeriodEnded: 6004,
+  VotingPeriodNotEnded: 6005,
+  MilestoneNotPassed: 6006,
+  MilestoneAlreadyUnlocked: 6007,
+  ProjectAlreadyFunded: 6008,
+  ProjectNotFunded: 6009,
+
+  // Authorization Errors (6100-6199)
+  UnauthorizedFounder: 6100,
+  UnauthorizedAdmin: 6101,
+  NotInvestor: 6102,
+  AlreadyVoted: 6103,
+
+  // Investment Errors (6200-6299)
+  InvestmentBelowMinimum: 6200,
+  FundingGoalExceeded: 6201,
+  InvalidTier: 6202,
+  CoolingOffPeriodActive: 6203,
+  CoolingOffPeriodExpired: 6204,
+
+  // Milestone Errors (6300-6399)
+  InvalidMilestoneIndex: 6300,
+  MilestonePercentageInvalid: 6301,
+  TotalPercentageExceeded: 6302,
+  MilestoneNotInProgress: 6303,
+  MilestoneNotApproved: 6304,
+
+  // TGE Errors (6400-6499)
+  TgeDateNotSet: 6400,
+  TgeDateAlreadySet: 6401,
+  TgeDateTooSoon: 6402,
+  TgeDateTooLate: 6403,
+  TgeNotReached: 6404,
+  TokensAlreadyClaimed: 6405,
+  InsufficientTokensDeposited: 6406,
+
+  // Pivot Errors (6500-6599)
+  PivotAlreadyProposed: 6500,
+  NoPivotProposed: 6501,
+  PivotNotApproved: 6502,
+  PivotWindowNotEnded: 6503,
+  PivotWindowEnded: 6504,
+  AlreadyWithdrawnFromPivot: 6505,
+
+  // Refund Errors (6800-6899)
+  RefundAlreadyClaimed: 6800,
+  RefundNotAvailable: 6801,
+  ProjectNotAbandoned: 6802,
+
+  // Scam Errors (6900-6999)
+  ScamReportPeriodEnded: 6900,
+  ScamAlreadyReported: 6901,
+  ScamNotConfirmed: 6902,
+  HoldbackAlreadyReleased: 6903,
+  HoldbackPeriodNotEnded: 6904,
+} as const;
+
+// =============================================================================
+// Error Messages
+// =============================================================================
+
+export const ERROR_MESSAGES: Record<number, string> = {
+  // State Transition Errors
+  [ERROR_CODES.InvalidStateTransition]: 'Invalid project state transition',
+  [ERROR_CODES.ProjectNotInOpenState]: 'Project must be in Open state to accept investments',
+  [ERROR_CODES.ProjectNotInProgress]: 'Project must be InProgress to perform this action',
+  [ERROR_CODES.MilestoneNotUnderReview]: 'Milestone must be under review to vote',
+  [ERROR_CODES.VotingPeriodEnded]: 'Voting period has ended',
+  [ERROR_CODES.VotingPeriodNotEnded]: 'Voting period has not ended yet',
+  [ERROR_CODES.MilestoneNotPassed]: 'Milestone did not pass voting',
+  [ERROR_CODES.MilestoneAlreadyUnlocked]: 'Milestone funds already unlocked',
+  [ERROR_CODES.ProjectAlreadyFunded]: 'Project has already reached funding goal',
+  [ERROR_CODES.ProjectNotFunded]: 'Project has not reached funding goal',
+
+  // Authorization Errors
+  [ERROR_CODES.UnauthorizedFounder]: 'Only the project founder can perform this action',
+  [ERROR_CODES.UnauthorizedAdmin]: 'Only the admin can perform this action',
+  [ERROR_CODES.NotInvestor]: 'You must be an investor to perform this action',
+  [ERROR_CODES.AlreadyVoted]: 'You have already voted on this',
+
+  // Investment Errors
+  [ERROR_CODES.InvestmentBelowMinimum]: 'Investment amount below minimum tier requirement',
+  [ERROR_CODES.FundingGoalExceeded]: 'Investment would exceed funding goal',
+  [ERROR_CODES.InvalidTier]: 'Invalid investment tier',
+  [ERROR_CODES.CoolingOffPeriodActive]: 'Investment is within 24-hour cooling-off period',
+  [ERROR_CODES.CoolingOffPeriodExpired]: 'Cooling-off period has expired, cannot cancel',
+
+  // Milestone Errors
+  [ERROR_CODES.InvalidMilestoneIndex]: 'Invalid milestone index',
+  [ERROR_CODES.MilestonePercentageInvalid]: 'Milestone percentage must be between 1-100',
+  [ERROR_CODES.TotalPercentageExceeded]: 'Total milestone percentages exceed 100%',
+  [ERROR_CODES.MilestoneNotInProgress]: 'Milestone must be in progress',
+  [ERROR_CODES.MilestoneNotApproved]: 'Milestone must be approved first',
+
+  // TGE Errors
+  [ERROR_CODES.TgeDateNotSet]: 'TGE date has not been set',
+  [ERROR_CODES.TgeDateAlreadySet]: 'TGE date has already been set',
+  [ERROR_CODES.TgeDateTooSoon]: 'TGE date must be at least 15 days in the future',
+  [ERROR_CODES.TgeDateTooLate]: 'TGE date must be within 90 days',
+  [ERROR_CODES.TgeNotReached]: 'TGE date has not been reached',
+  [ERROR_CODES.TokensAlreadyClaimed]: 'Tokens have already been claimed',
+  [ERROR_CODES.InsufficientTokensDeposited]: 'Insufficient tokens deposited by founder',
+
+  // Pivot Errors
+  [ERROR_CODES.PivotAlreadyProposed]: 'A pivot is already pending',
+  [ERROR_CODES.NoPivotProposed]: 'No pivot has been proposed',
+  [ERROR_CODES.PivotNotApproved]: 'Pivot has not been approved by admin',
+  [ERROR_CODES.PivotWindowNotEnded]: '7-day withdrawal window has not ended',
+  [ERROR_CODES.PivotWindowEnded]: '7-day withdrawal window has ended',
+  [ERROR_CODES.AlreadyWithdrawnFromPivot]: 'Already withdrawn from this pivot',
+
+  // Refund Errors
+  [ERROR_CODES.RefundAlreadyClaimed]: 'Refund has already been claimed',
+  [ERROR_CODES.RefundNotAvailable]: 'Refund is not available',
+  [ERROR_CODES.ProjectNotAbandoned]: 'Project has not been abandoned',
+
+  // Scam Errors
+  [ERROR_CODES.ScamReportPeriodEnded]: '30-day scam report period has ended',
+  [ERROR_CODES.ScamAlreadyReported]: 'Already reported this project for scam',
+  [ERROR_CODES.ScamNotConfirmed]: 'Scam has not been confirmed',
+  [ERROR_CODES.HoldbackAlreadyReleased]: 'Holdback has already been released',
+  [ERROR_CODES.HoldbackPeriodNotEnded]: '30-day holdback period has not ended',
+};
+
+// =============================================================================
+// SDK Error Class
+// =============================================================================
+
+export class RaiseError extends Error {
+  constructor(
+    public readonly code: number,
+    message: string,
+    public readonly logs?: string[]
+  ) {
+    super(message);
+    this.name = 'RaiseError';
+  }
+
+  /**
+   * Create from an Anchor error
+   */
+  static fromAnchorError(error: AnchorError): RaiseError {
+    const code = error.error.errorCode.number;
+    const message = ERROR_MESSAGES[code] || error.error.errorMessage;
+    return new RaiseError(code, message, error.logs);
+  }
+
+  /**
+   * Check if this is a specific error type
+   */
+  is(errorCode: number): boolean {
+    return this.code === errorCode;
+  }
+}
+
+// =============================================================================
+// Error Handling Utilities
+// =============================================================================
+
+/**
+ * Parse an error and return a RaiseError if it's a program error
+ */
+export function parseError(error: unknown): RaiseError | Error {
+  if (error instanceof AnchorError) {
+    return RaiseError.fromAnchorError(error);
+  }
+  if (error instanceof Error) {
+    return error;
+  }
+  return new Error(String(error));
+}
+
+/**
+ * Check if an error is a specific Raise error
+ */
+export function isRaiseError(
+  error: unknown,
+  code?: number
+): error is RaiseError {
+  if (!(error instanceof RaiseError)) {
+    return false;
+  }
+  if (code !== undefined) {
+    return error.code === code;
+  }
+  return true;
+}
+
+/**
+ * Get a user-friendly error message
+ */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof RaiseError) {
+    return error.message;
+  }
+  if (error instanceof AnchorError) {
+    const code = error.error.errorCode.number;
+    return ERROR_MESSAGES[code] || error.error.errorMessage;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return 'An unknown error occurred';
+}

package/src/events/index.ts

@@ -0,0 +1,256 @@
+/**
+ * Raise Event Parsing
+ *
+ * Helpers for parsing program events from transaction logs.
+ */
+
+import { BN } from '@coral-xyz/anchor';
+import { PublicKey } from '@solana/web3.js';
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+export interface ProjectCreatedEvent {
+  name: 'ProjectCreated';
+  data: {
+    projectId: BN;
+    founder: PublicKey;
+    fundingGoal: BN;
+    metadataUri: string;
+  };
+}
+
+export interface ProjectApprovedEvent {
+  name: 'ProjectApproved';
+  data: {
+    projectId: BN;
+  };
+}
+
+export interface ProjectFundedEvent {
+  name: 'ProjectFunded';
+  data: {
+    projectId: BN;
+    amountRaised: BN;
+  };
+}
+
+export interface InvestmentMadeEvent {
+  name: 'InvestmentMade';
+  data: {
+    projectId: BN;
+    investor: PublicKey;
+    amount: BN;
+    nftMint: PublicKey;
+    tier: number;
+    voteWeight: BN;
+  };
+}
+
+export interface InvestmentCancelledEvent {
+  name: 'InvestmentCancelled';
+  data: {
+    projectId: BN;
+    investor: PublicKey;
+    amount: BN;
+    nftMint: PublicKey;
+  };
+}
+
+export interface MilestoneCreatedEvent {
+  name: 'MilestoneCreated';
+  data: {
+    projectId: BN;
+    milestoneIndex: number;
+    percentage: number;
+    description: string;
+  };
+}
+
+export interface MilestoneSubmittedEvent {
+  name: 'MilestoneSubmitted';
+  data: {
+    projectId: BN;
+    milestoneIndex: number;
+    votingEndsAt: BN;
+  };
+}
+
+export interface VoteCastEvent {
+  name: 'VoteCast';
+  data: {
+    projectId: BN;
+    milestoneIndex: number;
+    voter: PublicKey;
+    choice: { good: object } | { bad: object };
+    weight: BN;
+  };
+}
+
+export interface MilestoneVoteFinalizedEvent {
+  name: 'MilestoneVoteFinalized';
+  data: {
+    projectId: BN;
+    milestoneIndex: number;
+    passed: boolean;
+    yesVotes: BN;
+    noVotes: BN;
+  };
+}
+
+export interface FundsUnlockedEvent {
+  name: 'FundsUnlocked';
+  data: {
+    projectId: BN;
+    milestoneIndex: number;
+    amount: BN;
+  };
+}
+
+export interface TgeDateSetEvent {
+  name: 'TgeDateSet';
+  data: {
+    projectId: BN;
+    tgeDate: BN;
+    tokenMint: PublicKey;
+  };
+}
+
+export interface TokensDepositedEvent {
+  name: 'TokensDeposited';
+  data: {
+    projectId: BN;
+    amount: BN;
+  };
+}
+
+export interface TokensClaimedEvent {
+  name: 'TokensClaimed';
+  data: {
+    projectId: BN;
+    investor: PublicKey;
+    amount: BN;
+  };
+}
+
+export interface RefundClaimedEvent {
+  name: 'RefundClaimed';
+  data: {
+    projectId: BN;
+    investor: PublicKey;
+    amount: BN;
+  };
+}
+
+export interface PivotProposedEvent {
+  name: 'PivotProposed';
+  data: {
+    projectId: BN;
+    newMetadataUri: string;
+  };
+}
+
+export interface PivotApprovedEvent {
+  name: 'PivotApproved';
+  data: {
+    projectId: BN;
+    withdrawalWindowEndsAt: BN;
+  };
+}
+
+export interface PivotFinalizedEvent {
+  name: 'PivotFinalized';
+  data: {
+    projectId: BN;
+    withdrawnAmount: BN;
+    withdrawnCount: number;
+  };
+}
+
+export interface MilestoneReworkedEvent {
+  name: 'MilestoneReworked';
+  data: {
+    projectId: BN;
+    milestoneIndex: number;
+    milestoneKey: PublicKey;
+    consecutiveFailures: number;
+    reworkedAt: BN;
+  };
+}
+
+export type RaiseEvent =
+  | ProjectCreatedEvent
+  | ProjectApprovedEvent
+  | ProjectFundedEvent
+  | InvestmentMadeEvent
+  | InvestmentCancelledEvent
+  | MilestoneCreatedEvent
+  | MilestoneSubmittedEvent
+  | VoteCastEvent
+  | MilestoneVoteFinalizedEvent
+  | FundsUnlockedEvent
+  | TgeDateSetEvent
+  | TokensDepositedEvent
+  | TokensClaimedEvent
+  | RefundClaimedEvent
+  | PivotProposedEvent
+  | PivotApprovedEvent
+  | PivotFinalizedEvent
+  | MilestoneReworkedEvent;
+
+// =============================================================================
+// Event Parsing
+// =============================================================================
+
+/**
+ * Event name constants
+ */
+export const EVENT_NAMES = {
+  ProjectCreated: 'ProjectCreated',
+  ProjectApproved: 'ProjectApproved',
+  ProjectFunded: 'ProjectFunded',
+  InvestmentMade: 'InvestmentMade',
+  InvestmentCancelled: 'InvestmentCancelled',
+  MilestoneCreated: 'MilestoneCreated',
+  MilestoneSubmitted: 'MilestoneSubmitted',
+  VoteCast: 'VoteCast',
+  MilestoneVoteFinalized: 'MilestoneVoteFinalized',
+  FundsUnlocked: 'FundsUnlocked',
+  TgeDateSet: 'TgeDateSet',
+  TokensDeposited: 'TokensDeposited',
+  TokensClaimed: 'TokensClaimed',
+  RefundClaimed: 'RefundClaimed',
+  PivotProposed: 'PivotProposed',
+  PivotApproved: 'PivotApproved',
+  PivotFinalized: 'PivotFinalized',
+  MilestoneReworked: 'MilestoneReworked',
+} as const;
+
+/**
+ * Filter events by name
+ *
+ * @param events - Array of events
+ * @param name - Event name to filter
+ * @returns Filtered events
+ */
+export function filterEventsByName<T extends RaiseEvent>(
+  events: RaiseEvent[],
+  name: T['name']
+): T[] {
+  return events.filter((e) => e.name === name) as T[];
+}
+
+/**
+ * Get the first event of a specific type
+ *
+ * @param events - Array of events
+ * @param name - Event name to find
+ * @returns First matching event or undefined
+ */
+export function findEvent<T extends RaiseEvent>(
+  events: RaiseEvent[],
+  name: T['name']
+): T | undefined {
+  return events.find((e) => e.name === name) as T | undefined;
+}