@zemyth/raise-sdk 0.1.0

package/README.md

@@ -0,0 +1,416 @@
+# @raise/sdk
+
+TypeScript SDK for the Raise Solana program - a decentralized venture funding platform with milestone-based fund releases.
+
+## Features
+
+- **Full Program Coverage** - All 34 instructions wrapped with TypeScript types
+- **PDA Helpers** - Derive all program addresses deterministically
+- **Account Fetchers** - Fetch and decode all account types
+- **Error Handling** - Mapped error codes with helpful messages
+- **Constants** - Investment tiers, timing values, governance parameters
+- **Tree-shakable** - Modular exports for optimal bundle size
+- **Dual Format** - ESM and CJS builds included
+
+## Installation
+
+```bash
+npm install @raise/sdk
+# or
+yarn add @raise/sdk
+# or
+pnpm add @raise/sdk
+```
+
+### Peer Dependencies
+
+```bash
+npm install @coral-xyz/anchor @solana/web3.js
+```
+
+## Quick Start
+
+### Initialize Client
+
+```typescript
+import { Program, AnchorProvider } from '@coral-xyz/anchor';
+import { Connection } from '@solana/web3.js';
+import { RaiseClient, BN } from '@raise/sdk';
+import idl from './idl/raise.json';
+
+// Setup connection and provider
+const connection = new Connection('https://api.devnet.solana.com');
+const provider = new AnchorProvider(connection, wallet, {});
+
+// Create program instance
+const program = new Program(idl, provider);
+
+// Create SDK client
+const client = RaiseClient.fromProgram(program);
+```
+
+### Create a Project
+
+```typescript
+const projectId = new BN(1);
+
+// Initialize project
+const tx = await client.initializeProject({
+  projectId,
+  fundingGoal: new BN(100_000_000_000), // 100,000 USDC
+  metadataUri: 'https://example.com/project.json',
+});
+
+console.log('Project created:', tx);
+
+// Add milestones
+await client.createMilestone({
+  projectId,
+  milestoneIndex: 0,
+  percentage: 30,
+  description: 'MVP Development',
+});
+
+await client.createMilestone({
+  projectId,
+  milestoneIndex: 1,
+  percentage: 40,
+  description: 'Beta Launch',
+});
+
+await client.createMilestone({
+  projectId,
+  milestoneIndex: 2,
+  percentage: 30,
+  description: 'Production Release',
+});
+
+// Submit for approval
+await client.submitForApproval(projectId);
+```
+
+### Invest in a Project
+
+```typescript
+import { USDC, getTierFromAmount, InvestmentTier } from '@raise/sdk';
+
+const amount = USDC.toAmount(1000); // 1,000 USDC
+const tier = getTierFromAmount(amount);
+
+console.log(`Investing ${USDC.fromAmount(amount)} USDC (${tier} tier)`);
+
+const tx = await client.invest({
+  projectId,
+  amount: new BN(amount.toString()),
+  investorTokenAccount: myUsdcAccount,
+  escrowTokenAccount: projectEscrow,
+});
+```
+
+### Vote on Milestones
+
+```typescript
+// Vote "Good" on milestone
+await client.voteOnMilestone({
+  projectId,
+  milestoneIndex: 0,
+  nftMint: myInvestmentNft,
+  choice: { good: {} },
+});
+
+// Finalize voting after period ends
+await client.finalizeVoting(projectId, 0);
+```
+
+### Fetch Account Data
+
+```typescript
+// Fetch project
+const project = await client.fetchProject(projectId);
+console.log('Project state:', project?.state);
+console.log('Amount raised:', project?.amountRaised.toString());
+
+// Fetch all investments
+const investments = await client.fetchAllInvestments(projectId);
+console.log(`Total investors: ${investments.length}`);
+
+// Fetch top investors (for veto eligibility)
+const topInvestors = await client.fetchTopInvestors(projectId, 3);
+```
+
+## Modular Imports
+
+Import only what you need for smaller bundles:
+
+```typescript
+// PDAs only
+import { getProjectPDA, getInvestmentPDA } from '@raise/sdk/pdas';
+
+// Constants only
+import { TIMING, TIER_MINIMUMS, InvestmentTier } from '@raise/sdk/constants';
+
+// Account fetchers only
+import { fetchProject, fetchAllInvestments } from '@raise/sdk/accounts';
+
+// Instructions only
+import { invest, voteOnMilestone } from '@raise/sdk/instructions';
+
+// Error handling only
+import { parseError, ERROR_CODES } from '@raise/sdk/errors';
+
+// Types only
+import type { ProjectAccount, MilestoneAccount } from '@raise/sdk/types';
+```
+
+## Constants Reference
+
+### Investment Tiers
+
+```typescript
+import {
+  InvestmentTier,
+  TIER_MINIMUMS,
+  TIER_VOTE_MULTIPLIERS,
+  USDC
+} from '@raise/sdk';
+
+// Tier minimums (in lamports)
+console.log(TIER_MINIMUMS[InvestmentTier.Bronze]);   // 100_000_000n (100 USDC)
+console.log(TIER_MINIMUMS[InvestmentTier.Silver]);   // 500_000_000n (500 USDC)
+console.log(TIER_MINIMUMS[InvestmentTier.Gold]);     // 1_000_000_000n (1,000 USDC)
+console.log(TIER_MINIMUMS[InvestmentTier.Platinum]); // 5_000_000_000n (5,000 USDC)
+console.log(TIER_MINIMUMS[InvestmentTier.Diamond]);  // 10_000_000_000n (10,000 USDC)
+
+// Vote multipliers
+console.log(TIER_VOTE_MULTIPLIERS[InvestmentTier.Bronze]);   // 100 (1.0x)
+console.log(TIER_VOTE_MULTIPLIERS[InvestmentTier.Diamond]);  // 300 (3.0x)
+```
+
+### Timing Constants
+
+```typescript
+import { TIMING } from '@raise/sdk';
+
+console.log(TIMING.VOTING_PERIOD_SECONDS);      // 1,209,600 (14 days)
+console.log(TIMING.HOLD_PERIOD_SECONDS);        // 604,800 (7 days)
+console.log(TIMING.CHALLENGE_PERIOD_SECONDS);   // 172,800 (48 hours)
+console.log(TIMING.ABANDONMENT_TIMEOUT_SECONDS); // 7,776,000 (90 days)
+```
+
+### Governance Parameters
+
+```typescript
+import { GOVERNANCE } from '@raise/sdk';
+
+console.log(GOVERNANCE.MILESTONE_APPROVAL_THRESHOLD_PERCENT); // 50 (>50%)
+console.log(GOVERNANCE.SHUTDOWN_THRESHOLD_BPS);     // 6600 (66%)
+console.log(GOVERNANCE.SCAM_THRESHOLD_PERCENT);     // 30 (30%)
+console.log(GOVERNANCE.CONSECUTIVE_FAILURES_THRESHOLD); // 4
+```
+
+## Error Handling
+
+```typescript
+import {
+  parseError,
+  isRaiseError,
+  getErrorMessage,
+  ERROR_CODES
+} from '@raise/sdk';
+
+try {
+  await client.invest({ ... });
+} catch (error) {
+  const parsed = parseError(error);
+
+  if (isRaiseError(parsed, ERROR_CODES.InvestmentBelowMinimum)) {
+    console.error('Investment too small for minimum tier');
+  } else if (isRaiseError(parsed, ERROR_CODES.FundingGoalExceeded)) {
+    console.error('Project is fully funded');
+  } else {
+    console.error(getErrorMessage(parsed));
+  }
+}
+```
+
+## Utility Functions
+
+### Time Helpers
+
+```typescript
+import {
+  timeRemaining,
+  formatDuration,
+  hasTimestampPassed,
+  timestampToDate
+} from '@raise/sdk';
+
+// Check voting deadline
+const milestone = await client.fetchMilestone(projectId, 0);
+if (milestone?.votingEndsAt) {
+  const remaining = timeRemaining(milestone.votingEndsAt);
+  console.log(`Time remaining: ${formatDuration(remaining)}`);
+  // Output: "Time remaining: 2d 5h 30m"
+
+  if (hasTimestampPassed(milestone.votingEndsAt)) {
+    console.log('Voting period ended');
+  }
+}
+```
+
+### USDC Conversions
+
+```typescript
+import { USDC } from '@raise/sdk';
+
+// Convert USDC to lamports
+const lamports = USDC.toAmount(100); // 100_000_000n
+
+// Convert lamports to USDC
+const usdc = USDC.fromAmount(100_000_000n); // 100
+```
+
+### Validation
+
+```typescript
+import {
+  validateMilestonePercentages,
+  validateMetadataUri
+} from '@raise/sdk';
+
+// Validate milestone percentages sum to 100
+const isValid = validateMilestonePercentages([30, 40, 30]); // true
+
+// Validate metadata URI
+const isValidUri = validateMetadataUri('https://example.com/project.json');
+```
+
+## React Integration
+
+```typescript
+import { useMemo } from 'react';
+import { useConnection, useWallet } from '@solana/wallet-adapter-react';
+import { Program, AnchorProvider } from '@coral-xyz/anchor';
+import { RaiseClient } from '@raise/sdk';
+import idl from './idl/raise.json';
+
+export function useRaise(): RaiseClient | null {
+  const { connection } = useConnection();
+  const wallet = useWallet();
+
+  return useMemo(() => {
+    if (!wallet.publicKey || !wallet.signTransaction) {
+      return null;
+    }
+
+    const provider = new AnchorProvider(
+      connection,
+      wallet as any,
+      AnchorProvider.defaultOptions()
+    );
+
+    const program = new Program(idl as any, provider);
+    return RaiseClient.fromProgram(program);
+  }, [connection, wallet]);
+}
+
+// Usage in component
+function InvestButton({ projectId }) {
+  const client = useRaise();
+
+  const handleInvest = async () => {
+    if (!client) return;
+
+    const tx = await client.invest({
+      projectId: new BN(projectId),
+      amount: new BN(100_000_000),
+      investorTokenAccount: myUsdcAta,
+      escrowTokenAccount: projectEscrow,
+    });
+
+    console.log('Investment tx:', tx);
+  };
+
+  return (
+    <button onClick={handleInvest} disabled={!client}>
+      Invest
+    </button>
+  );
+}
+```
+
+## API Reference
+
+### RaiseClient Methods
+
+#### Admin Operations
+- `initializeAdmin(admin)` - Initialize admin config
+- `transferAdmin(newAdmin)` - Propose admin transfer
+- `acceptAdmin()` - Accept admin transfer
+
+#### Project Operations
+- `initializeProject(args)` - Create new project
+- `submitForApproval(projectId)` - Submit for admin approval
+- `approveProject(projectId, adminKeypair)` - Approve project
+
+#### Milestone Operations
+- `createMilestone(args)` - Add milestone to project
+- `submitMilestone(projectId, index)` - Submit for voting
+- `voteOnMilestone(args)` - Cast vote
+- `finalizeVoting(projectId, index)` - End voting period
+- `claimMilestoneFunds(args)` - Claim funds after passing
+
+#### Investment Operations
+- `invest(args)` - Invest USDC, receive NFT
+- `cancelInvestment(args)` - Cancel within 24h cooling-off
+
+#### TGE Operations
+- `setTgeDate(args)` - Set token generation date
+- `depositTokens(args)` - Deposit tokens for distribution
+- `claimTokens(args)` - Claim allocated tokens
+- `releaseHoldback(args)` - Release 10% founder holdback
+
+#### Governance Operations
+- `initiateShutdownVote(args)` - Start shutdown vote
+- `voteOnShutdown(args)` - Vote on shutdown
+- `finalizeShutdownVote(args)` - Finalize shutdown vote
+- `claimShutdownRefund(args)` - Claim refund after shutdown
+
+#### Pivot Operations
+- `proposePivot(args)` - Propose project pivot
+- `approvePivot(projectId, adminKeypair)` - Approve pivot
+- `withdrawFromPivot(args)` - Withdraw during window
+- `finalizePivot(args)` - Finalize after window
+
+#### Account Fetchers
+- `fetchProject(projectId)`
+- `fetchMilestone(projectId, index)`
+- `fetchAllMilestones(projectId)`
+- `fetchInvestment(projectId, nftMint)`
+- `fetchAllInvestments(projectId)`
+- `fetchTopInvestors(projectId, count)`
+- `fetchVote(projectId, milestoneIndex, voter)`
+- `fetchWithdrawal(projectId, milestoneIndex)`
+- `fetchPivotProposal(projectId)`
+- `fetchShutdownVote(projectId)`
+- `fetchAdminConfig()`
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Type check
+npm run typecheck
+
+# Watch mode
+npm run dev
+```
+
+## License
+
+MIT

package/dist/accounts/index.cjs

@@ -0,0 +1,258 @@
+'use strict';
+
+var web3_js = require('@solana/web3.js');
+var anchor = require('@coral-xyz/anchor');
+
+// src/pdas/index.ts
+
+// src/constants/index.ts
+var SEEDS = {
+  PROJECT: "project",
+  MILESTONE: "milestone",
+  INVESTMENT: "investment",
+  VOTE: "vote",
+  PIVOT: "pivot",
+  TGE_ESCROW: "tge_escrow",
+  ADMIN_CONFIG: "admin-config"};
+
+// src/pdas/index.ts
+function ensureBN(value) {
+  if (value && typeof value.toArrayLike === "function") {
+    return value;
+  }
+  return new anchor.BN(String(value));
+}
+function getProjectPDA(projectId, programId) {
+  const projectIdBN = ensureBN(projectId);
+  const [pda] = web3_js.PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.PROJECT), projectIdBN.toArrayLike(Buffer, "le", 8)],
+    programId
+  );
+  return pda;
+}
+function getMilestonePDA(projectPda, milestoneIndex, programId) {
+  const [pda] = web3_js.PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(SEEDS.MILESTONE),
+      projectPda.toBuffer(),
+      Buffer.from([milestoneIndex])
+    ],
+    programId
+  );
+  return pda;
+}
+function getInvestmentPDA(projectPda, nftMint, programId) {
+  const [pda] = web3_js.PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(SEEDS.INVESTMENT),
+      projectPda.toBuffer(),
+      nftMint.toBuffer()
+    ],
+    programId
+  );
+  return pda;
+}
+function getVotePDA(milestonePda, voterKey, votingRound, programId) {
+  const [pda] = web3_js.PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.VOTE), milestonePda.toBuffer(), voterKey.toBuffer(), Buffer.from([votingRound])],
+    programId
+  );
+  return pda;
+}
+function getPivotProposalPDA(projectPda, pivotCount, programId) {
+  const [pda] = web3_js.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;
+}
+function getTgeEscrowPDA(projectPda, programId) {
+  const [pda] = web3_js.PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.TGE_ESCROW), projectPda.toBuffer()],
+    programId
+  );
+  return pda;
+}
+function getAdminConfigPDA(programId) {
+  const [pda] = web3_js.PublicKey.findProgramAddressSync(
+    [Buffer.from(SEEDS.ADMIN_CONFIG)],
+    programId
+  );
+  return pda;
+}
+
+// src/accounts/index.ts
+function getAccountNamespace(program) {
+  return program.account;
+}
+async function fetchProject(program, projectId) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    return await getAccountNamespace(program).project.fetch(projectPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes("Account does not exist")) {
+      return null;
+    }
+    throw error;
+  }
+}
+async function fetchProjectByPda(program, projectPda) {
+  try {
+    return await getAccountNamespace(program).project.fetch(projectPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes("Account does not exist")) {
+      return null;
+    }
+    throw error;
+  }
+}
+async function fetchMilestone(program, projectId, milestoneIndex) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const milestonePda = getMilestonePDA(projectPda, 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;
+  }
+}
+async function fetchAllMilestones(program, projectId) {
+  const projectPda = getProjectPDA(projectId, program.programId);
+  const milestones = await getAccountNamespace(program).milestone.all([
+    {
+      memcmp: {
+        offset: 8,
+        // Skip discriminator
+        bytes: projectPda.toBase58()
+      }
+    }
+  ]);
+  return milestones.map((m) => ({
+    publicKey: m.publicKey,
+    account: m.account
+  }));
+}
+async function fetchInvestment(program, projectId, nftMint) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const investmentPda = getInvestmentPDA(projectPda, 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;
+  }
+}
+async function fetchAllInvestments(program, projectId) {
+  const projectPda = getProjectPDA(projectId, program.programId);
+  const investments = await getAccountNamespace(program).investment.all([
+    {
+      memcmp: {
+        offset: 8,
+        // Skip discriminator
+        bytes: projectPda.toBase58()
+      }
+    }
+  ]);
+  return investments.map((inv) => ({
+    publicKey: inv.publicKey,
+    account: inv.account
+  }));
+}
+async function fetchVote(program, projectId, milestoneIndex, voterKey, votingRound) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const milestonePda = getMilestonePDA(projectPda, milestoneIndex, program.programId);
+    const votePda = getVotePDA(milestonePda, voterKey, votingRound, program.programId);
+    return await getAccountNamespace(program).vote.fetch(votePda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes("Account does not exist")) {
+      return null;
+    }
+    throw error;
+  }
+}
+async function fetchAllVotes(program, projectId, milestoneIndex) {
+  const projectPda = getProjectPDA(projectId, program.programId);
+  const milestonePda = getMilestonePDA(projectPda, milestoneIndex, program.programId);
+  const votes = await getAccountNamespace(program).vote.all([
+    {
+      memcmp: {
+        offset: 8,
+        // Skip discriminator
+        bytes: milestonePda.toBase58()
+      }
+    }
+  ]);
+  return votes.map((v) => ({
+    publicKey: v.publicKey,
+    account: v.account
+  }));
+}
+async function fetchPivotProposal(program, projectId) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const projectAccount = await getAccountNamespace(program).project.fetch(projectPda);
+    let pivotPda;
+    if (projectAccount.activePivot) {
+      pivotPda = projectAccount.activePivot;
+    } else {
+      const pivotCount = projectAccount.pivotCount || 0;
+      pivotPda = getPivotProposalPDA(projectPda, pivotCount, program.programId);
+    }
+    return await getAccountNamespace(program).pivotProposal.fetch(pivotPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes("Account does not exist")) {
+      return null;
+    }
+    throw error;
+  }
+}
+async function fetchTgeEscrow(program, projectId) {
+  try {
+    const projectPda = getProjectPDA(projectId, program.programId);
+    const tgeEscrowPda = getTgeEscrowPDA(projectPda, program.programId);
+    return await getAccountNamespace(program).tgeEscrow.fetch(tgeEscrowPda);
+  } catch (error) {
+    if (error instanceof Error && error.message?.includes("Account does not exist")) {
+      return null;
+    }
+    throw error;
+  }
+}
+async function fetchAdminConfig(program) {
+  const adminConfigPda = getAdminConfigPDA(program.programId);
+  return await getAccountNamespace(program).adminConfig.fetch(adminConfigPda);
+}
+async function accountExists(program, accountType, pda) {
+  try {
+    await program.account[accountType].fetch(pda);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+exports.accountExists = accountExists;
+exports.fetchAdminConfig = fetchAdminConfig;
+exports.fetchAllInvestments = fetchAllInvestments;
+exports.fetchAllMilestones = fetchAllMilestones;
+exports.fetchAllVotes = fetchAllVotes;
+exports.fetchInvestment = fetchInvestment;
+exports.fetchMilestone = fetchMilestone;
+exports.fetchPivotProposal = fetchPivotProposal;
+exports.fetchProject = fetchProject;
+exports.fetchProjectByPda = fetchProjectByPda;
+exports.fetchTgeEscrow = fetchTgeEscrow;
+exports.fetchVote = fetchVote;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map