@star-factory/sdk-launchpad 0.1.0

package/README.md

@@ -0,0 +1,343 @@
+# @star-factory/sdk-launchpad
+
+TypeScript SDK for the Star Launchpad program. Covers the full lifecycle:
+
+1. **Launch Flow** — initialize, configure, create token, execute launch (pool + DAO + authority transfer)
+2. **Token Claims** — eligibility checks, vesting math, claim transaction building
+
+## Install
+
+```bash
+yarn add @star-factory/sdk-launchpad
+```
+
+Runtime dependencies (including `@solana/web3.js`, `@coral-xyz/anchor`, `bn.js`) are bundled via this package's `dependencies`.
+Peer dependency: `typescript@^5`.
+
+## Quick Start
+
+```typescript
+import { LaunchpadSDK } from '@star-factory/sdk-launchpad';
+
+const sdk = new LaunchpadSDK({
+  connection,
+  cluster: 'devnet',
+  zcApiKey: process.env.ZC_API_KEY!,
+});
+```
+
+---
+
+## Launch Flow
+
+### 1. Initialize Launch
+
+Creates a `LaunchConfig` PDA + underlying fundraise vault via CPI to `vault::make`.
+
+```typescript
+const tx = await sdk.buildInitializeLaunchTx(launchpadProgram, {
+  creator: wallet.publicKey,
+  seed: new BN(Date.now()),
+  vaultSeed: new BN(Date.now() + 1),
+  totalSupply: new BN('1000000000000000'),       // 1M tokens @ 9 decimals
+  tokensToParticipants: new BN('500000000000000'), // 500K to participants
+  quoteMint: NATIVE_MINT,
+  minRaise: new BN('100000000'),
+  targetRaise: new BN('100000000'),
+  startTime: new BN(now - 5),
+  endTime: new BN(now + 300),
+  vaultProgramId: VAULT_PROGRAM_ID,
+});
+await sendTx(tx, [creator]);
+```
+
+### 2. Configure Launch
+
+Sets vanity mint configuration and token metadata. Transitions `FundraiseActive → ReadyToLaunch`.
+
+```typescript
+const tx = await sdk.buildConfigureLaunchTx(launchpadProgram, {
+  admin: admin.publicKey,
+  launchConfig: launchConfigPda,
+  fundraiseState: vaultPda,
+  basePubkey: baseKeypair.publicKey,
+  vanitySeed: 'my-token-seed',
+  expectedMint: derivedMintAddress,
+  name: 'My Token',
+  symbol: 'MTK',
+  uri: 'https://arweave.net/metadata.json',
+});
+await sendTx(tx, [admin]);
+```
+
+### 3. Create Launch Token
+
+Creates the vanity mint, Metaplex metadata, and mints total supply. Transitions `ReadyToLaunch → TokenCreated`.
+
+```typescript
+const tx = await sdk.buildCreateLaunchTokenTx(launchpadProgram, {
+  admin: admin.publicKey,
+  baseKeypairPubkey: baseKeypair.publicKey,
+  launchConfig: launchConfigPda,
+  expectedMint: derivedMintAddress,
+});
+await sendTx(tx, [admin, baseKeypair]); // both must sign
+```
+
+### 4. Reserve Admin (off-chain)
+
+Calls the zCombinator API to allocate a managed admin wallet for the DAO.
+
+```typescript
+const poolAddress = sdk.derivePoolAddress(baseMint, quoteMint);
+
+const reservation = await sdk.reserveAdmin({
+  name: 'ProjectDAO',
+  tokenMint: baseMint,
+  poolAddress,
+  poolType: 'damm',
+  quoteMint,
+  treasuryCosigner: teamMultisig,
+  ownerWallet: projectOwner,
+});
+```
+
+Or use the one-call helper:
+
+```typescript
+const result = await sdk.prepareLaunchExecution({
+  daoName: 'ProjectDAO',
+  tokenMint: baseMint,
+  quoteMint,
+  treasuryCosigner: teamMultisig,
+  ownerWallet: projectOwner,
+});
+```
+
+### 5. Execute Launch
+
+Atomically finalizes the vault, creates DAMM pool, creates DAO, transfers authorities, and routes funds. Transitions `TokenCreated → Launched`.
+
+Returns both the TX and all resolved accounts (for ALT creation).
+
+```typescript
+const { tx, accounts } = await sdk.buildExecuteLaunchTx(launchpadProgram, {
+  admin: admin.publicKey,
+  launchConfig: launchConfigPda,
+  launchConfigData,
+  poolActivationTime: new BN(now + 120),
+  daoName: 'ProjectDAO',
+  treasuryCosigner: teamMultisig,
+  newDaoAdmin: reservation.adminWallet,
+  dammPool: poolAddress,
+  vaultProgramId: VAULT_PROGRAM_ID,
+  computeUnits: 1_400_000,
+});
+
+// Create ALT from `accounts`, compile to VersionedTransaction, send
+```
+
+### 6. Cancel Launch
+
+Cancels from any pre-Launched state. Burns tokens if minted, enables refunds.
+
+```typescript
+const tx = await sdk.buildCancelLaunchTx(launchpadProgram, {
+  admin: admin.publicKey,
+  launchConfig: launchConfigPda,
+  launchConfigData,
+  vaultProgramId: VAULT_PROGRAM_ID,
+});
+await sendTx(tx, [admin]);
+```
+
+---
+
+## Token Claims
+
+After a launch executes, depositors claim vested tokens through the `claim_tokens` instruction.
+
+### Check Eligibility
+
+```typescript
+const eligibility = await sdk.getClaimEligibility(
+  launchpadProgram,
+  vaultProgram,
+  launchConfigPda,
+  wallet.publicKey,
+);
+
+if (eligibility.canClaim) {
+  console.log(`Claimable: ${eligibility.claimableNow.toString()}`);
+} else {
+  console.log(`Reason: ${eligibility.reason}`);
+}
+```
+
+The `ClaimEligibility` result contains everything a UI needs:
+
+| Field             | Type              | Description                                    |
+|-------------------|-------------------|------------------------------------------------|
+| `canClaim`        | `boolean`         | Whether the user can claim right now            |
+| `reason`          | `string \| null`  | Why they can't (null when `canClaim` is true)   |
+| `claimableNow`    | `BN`              | Tokens claimable at this moment                 |
+| `totalTokens`     | `BN`              | User's total token entitlement                  |
+| `totalClaimed`    | `BN`              | Already claimed                                 |
+| `totalVested`     | `BN`              | Total vested as of now                          |
+| `tier`            | `number \| null`  | Vesting tier (0–6)                              |
+| `vestingSchedule` | `VestingSchedule`  | Start/end timestamps, percent vested, etc.     |
+
+### Build Claim Transaction
+
+**Client-side (wallet adapter):**
+
+```typescript
+const tx = await sdk.buildClaimTx(launchpadProgram, {
+  user: wallet.publicKey,
+  launchConfig: launchConfigPda,
+  launchConfigData,
+  vaultProgramId: VAULT_PROGRAM_ID,
+});
+const sig = await wallet.sendTransaction(tx, connection);
+```
+
+**Server-side (sponsored/relay):**
+
+```typescript
+const tx = await sdk.buildClaimTx(launchpadProgram, {
+  user: userPubkey,
+  launchConfig: launchConfigPda,
+  launchConfigData,
+  vaultProgramId: VAULT_PROGRAM_ID,
+  feePayer: relayPubkey,
+  priorityFee: 10_000,
+  computeUnits: 200_000,
+});
+```
+
+---
+
+## Vesting Model
+
+Tokens vest linearly from pool activation time based on the depositor's tier:
+
+| Tier | Vesting Duration | Unlock                       |
+|------|------------------|------------------------------|
+| 0    | Immediate        | 100% at pool activation      |
+| 1    | 2 weeks          | Linear over 1,209,600s       |
+| 2    | 4 weeks          | Linear over 2,419,200s       |
+| 3    | 6 weeks          | Linear over 3,628,800s       |
+| 4    | 8 weeks          | Linear over 4,838,400s       |
+| 5    | 10 weeks         | Linear over 6,048,000s       |
+| 6    | 12 weeks         | Linear over 7,257,600s       |
+
+Users can claim multiple times — each claim transfers `vested - already_claimed`.
+
+---
+
+## Low-Level Exports
+
+Every building block is exported individually:
+
+```typescript
+import {
+  // Instruction TX builders
+  buildInitializeLaunchTx,
+  buildConfigureLaunchTx,
+  buildCreateLaunchTokenTx,
+  buildExecuteLaunchTx,
+  buildCancelLaunchTx,
+
+  // Claim TX builders
+  buildClaimTransaction,
+  buildBatchClaimTransactions,
+
+  // Launchpad PDAs
+  deriveLaunchConfigPda,
+  deriveLaunchpadSignerPda,
+  deriveClaimRecordPda,
+  derivePositionNftMintPda,
+
+  // External program PDAs
+  deriveVaultPda,
+  deriveTgeConfigPda,
+  deriveDammPoolAuthority,
+  deriveDammTokenVault,
+  deriveDammPosition,
+  deriveDammPositionNftAccount,
+  deriveDammEventAuthority,
+  deriveSquadsMultisig,
+  deriveSquadsVault,
+  deriveSquadsProgramConfig,
+  deriveDaoPda,
+  deriveModeratorPda,
+  deriveMintCreateKeyPda,
+  deriveMetadataPda,
+
+  // Pool derivation
+  derivePoolAddress,
+  sortMints,
+
+  // Account fetching + resolution
+  fetchLaunchConfig,
+  fetchClaimRecord,
+  fetchDepositorRecord,
+  resolveClaimAccounts,
+  deriveDepositorRecordPda,
+
+  // Eligibility (pure computation)
+  computeAllocatedAmount,
+  computeClaimEligibility,
+  computeUserTokens,
+  computeVestedAmount,
+
+  // Constants
+  NUM_TIERS,
+  TIER_VESTING_SECONDS,
+  TIER_VESTING_WEEKS,
+  DAMM_PROGRAM_ID,
+  DAMM_CONFIG_PDA,
+  SQUADS_PROGRAM_ID,
+  METAPLEX_PROGRAM_ID,
+
+  // ZC client
+  ZCClient,
+} from '@star-factory/sdk-launchpad';
+```
+
+---
+
+## Architecture
+
+```
+sdk-launchpad/src/
+├── index.ts              Barrel exports
+├── sdk.ts                LaunchpadSDK class (high-level API)
+├── types.ts              All TypeScript interfaces and types
+├── pdas.ts               DAMM pool PDA derivation
+├── instructions/
+│   ├── pdas.ts           External program PDAs (DAMM, Squads, Futarchy, Metaplex, Vault)
+│   ├── constants.ts      External program IDs
+│   ├── initialize-launch.ts
+│   ├── configure-launch.ts
+│   ├── create-launch-token.ts
+│   ├── execute-launch.ts  Account resolution (~35 accounts) + TX builder
+│   └── cancel-launch.ts
+├── claims/
+│   ├── pdas.ts           Launchpad PDA derivation (launch config, signer, claim record)
+│   ├── accounts.ts       Account fetching + resolution
+│   ├── eligibility.ts    Pure vesting math + eligibility computation
+│   └── tx.ts             claim_tokens TX builder
+└── zc/
+    ├── client.ts         zCombinator REST API client
+    ├── constants.ts      Program IDs, API endpoints, rate limits
+    └── types.ts          ZC-specific types
+```
+
+**Design principles:**
+
+- **Pure math is separated from RPC** — `eligibility.ts` has zero network calls; it takes pre-fetched data and returns a deterministic result.
+- **All PDAs are deterministic** — every account for every instruction is derived from known inputs. No guessing, no fetching account lists.
+- **Transactions are unsigned** — the SDK never touches private keys. It returns `Transaction` objects for the caller to sign however they want.
+- **On-chain math parity** — `computeAllocatedAmount`, `computeUserTokens`, and `computeVestedAmount` mirror the Rust implementations exactly.
+- **Full lifecycle coverage** — every launchpad program instruction has a corresponding TX builder.

package/dist/claims/accounts.d.ts

@@ -0,0 +1,49 @@
+import type { Idl, Program } from '@coral-xyz/anchor';
+import { PublicKey } from '@solana/web3.js';
+import type { ClaimAccountsResolved, ClaimRecordAccount, DepositorRecordRaw, LaunchConfigAccount } from '../types';
+/**
+ * Fetch and decode a LaunchConfig account.
+ *
+ * @param connection  - Solana RPC connection
+ * @param program     - Anchor program instance (launchpad)
+ * @param launchConfig - The launch config PDA address
+ * @returns Typed LaunchConfig or `null` if account doesn't exist
+ */
+export declare function fetchLaunchConfig(program: Program<Idl>, launchConfig: PublicKey): Promise<LaunchConfigAccount | null>;
+/**
+ * Fetch and decode a ClaimRecord account.
+ *
+ * Returns `null` if the account doesn't exist yet (user hasn't claimed).
+ * This is the expected state for first-time claimants.
+ */
+export declare function fetchClaimRecord(program: Program<Idl>, claimRecord: PublicKey): Promise<ClaimRecordAccount | null>;
+/**
+ * Fetch a DepositorRecord from the vault program.
+ *
+ * The depositor record lives in the vault program, not the launchpad program.
+ * We use a generic `fetch` approach so the SDK doesn't need the vault IDL.
+ */
+export declare function fetchDepositorRecord(vaultProgram: Program<Idl>, depositorRecord: PublicKey): Promise<DepositorRecordRaw | null>;
+/**
+ * Derive the depositor record PDA from the vault program.
+ *
+ * Seeds: `["depositor", vault, user]`
+ */
+export declare function deriveDepositorRecordPda(vault: PublicKey, user: PublicKey, vaultProgramId: PublicKey): [PublicKey, number];
+/**
+ * Resolve all accounts needed for a `claim_tokens` instruction.
+ *
+ * Given a LaunchConfig account (already fetched) and user pubkey,
+ * deterministically derives every account the instruction needs.
+ *
+ * This is the core account resolution function — used by both the
+ * transaction builder (client-side) and eligibility checker (server-side).
+ *
+ * @param launchConfig      - The LaunchConfig PDA address
+ * @param launchConfigData  - The decoded LaunchConfig account data
+ * @param user              - The claiming user's wallet pubkey
+ * @param vaultProgramId    - The vault program ID (for depositor record PDA)
+ * @param launchpadProgramId - The launchpad program ID
+ */
+export declare function resolveClaimAccounts(launchConfig: PublicKey, launchConfigData: LaunchConfigAccount, user: PublicKey, vaultProgramId: PublicKey, launchpadProgramId: PublicKey): ClaimAccountsResolved;
+//# sourceMappingURL=accounts.d.ts.map

package/dist/claims/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../../src/claims/accounts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,EACR,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACtB,MAAM,UAAU,CAAC;AAoBlB;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EACrB,YAAY,EAAE,SAAS,GACtB,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAOrC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EACrB,WAAW,EAAE,SAAS,GACrB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAOpC;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,EAC1B,eAAe,EAAE,SAAS,GACzB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAOpC;AAMD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,SAAS,EACf,cAAc,EAAE,SAAS,GACxB,CAAC,SAAS,EAAE,MAAM,CAAC,CAKrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,SAAS,EACvB,gBAAgB,EAAE,mBAAmB,EACrC,IAAI,EAAE,SAAS,EACf,cAAc,EAAE,SAAS,EACzB,kBAAkB,EAAE,SAAS,GAC5B,qBAAqB,CA0BvB"}

package/dist/claims/accounts.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchLaunchConfig = fetchLaunchConfig;
+exports.fetchClaimRecord = fetchClaimRecord;
+exports.fetchDepositorRecord = fetchDepositorRecord;
+exports.deriveDepositorRecordPda = deriveDepositorRecordPda;
+exports.resolveClaimAccounts = resolveClaimAccounts;
+const spl_token_1 = require("@solana/spl-token");
+const web3_js_1 = require("@solana/web3.js");
+const pdas_1 = require("./pdas");
+function getAccountFetcher(program, accountName) {
+    const accounts = program.account;
+    const fetcher = accounts[accountName];
+    if (!fetcher) {
+        throw new Error(`Account namespace missing '${accountName}'`);
+    }
+    return fetcher;
+}
+// ============================================================================
+// Account Fetching
+// ============================================================================
+/**
+ * Fetch and decode a LaunchConfig account.
+ *
+ * @param connection  - Solana RPC connection
+ * @param program     - Anchor program instance (launchpad)
+ * @param launchConfig - The launch config PDA address
+ * @returns Typed LaunchConfig or `null` if account doesn't exist
+ */
+async function fetchLaunchConfig(program, launchConfig) {
+    try {
+        const raw = await getAccountFetcher(program, 'launchConfig').fetch(launchConfig);
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch and decode a ClaimRecord account.
+ *
+ * Returns `null` if the account doesn't exist yet (user hasn't claimed).
+ * This is the expected state for first-time claimants.
+ */
+async function fetchClaimRecord(program, claimRecord) {
+    try {
+        const raw = await getAccountFetcher(program, 'claimRecord').fetch(claimRecord);
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch a DepositorRecord from the vault program.
+ *
+ * The depositor record lives in the vault program, not the launchpad program.
+ * We use a generic `fetch` approach so the SDK doesn't need the vault IDL.
+ */
+async function fetchDepositorRecord(vaultProgram, depositorRecord) {
+    try {
+        const raw = await getAccountFetcher(vaultProgram, 'depositorRecord').fetch(depositorRecord);
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Account Resolution
+// ============================================================================
+/**
+ * Derive the depositor record PDA from the vault program.
+ *
+ * Seeds: `["depositor", vault, user]`
+ */
+function deriveDepositorRecordPda(vault, user, vaultProgramId) {
+    return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from('depositor'), vault.toBuffer(), user.toBuffer()], vaultProgramId);
+}
+/**
+ * Resolve all accounts needed for a `claim_tokens` instruction.
+ *
+ * Given a LaunchConfig account (already fetched) and user pubkey,
+ * deterministically derives every account the instruction needs.
+ *
+ * This is the core account resolution function — used by both the
+ * transaction builder (client-side) and eligibility checker (server-side).
+ *
+ * @param launchConfig      - The LaunchConfig PDA address
+ * @param launchConfigData  - The decoded LaunchConfig account data
+ * @param user              - The claiming user's wallet pubkey
+ * @param vaultProgramId    - The vault program ID (for depositor record PDA)
+ * @param launchpadProgramId - The launchpad program ID
+ */
+function resolveClaimAccounts(launchConfig, launchConfigData, user, vaultProgramId, launchpadProgramId) {
+    const fundraiseState = launchConfigData.fundraiseState;
+    const baseMint = launchConfigData.baseMint;
+    if (!baseMint) {
+        throw new Error('LaunchConfig.baseMint is not set — launch token not yet created');
+    }
+    const [launchpadSigner] = (0, pdas_1.deriveLaunchpadSignerPda)(launchConfig, launchpadProgramId);
+    const [claimRecord] = (0, pdas_1.deriveClaimRecordPda)(launchConfig, user, launchpadProgramId);
+    const [userRecord] = deriveDepositorRecordPda(fundraiseState, user, vaultProgramId);
+    const tokenVault = (0, spl_token_1.getAssociatedTokenAddressSync)(baseMint, launchpadSigner, true);
+    const userTokenAta = (0, spl_token_1.getAssociatedTokenAddressSync)(baseMint, user, false);
+    return {
+        user,
+        launchConfig,
+        fundraiseState,
+        userRecord,
+        claimRecord,
+        baseMint,
+        tokenVault,
+        userTokenAta,
+        launchpadSigner,
+    };
+}
+//# sourceMappingURL=accounts.js.map

package/dist/claims/accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.js","sourceRoot":"","sources":["../../src/claims/accounts.ts"],"names":[],"mappings":"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"}

package/dist/claims/eligibility.d.ts

@@ -0,0 +1,67 @@
+import BN from 'bn.js';
+import type { ClaimEligibility, ClaimRecordAccount, DepositorRecordRaw, LaunchConfigAccount, VaultAllocationData } from '../types';
+/** Number of vesting tiers (0–6 inclusive). */
+export declare const NUM_TIERS = 7;
+/** Maximum valid tier index. */
+export declare const MAX_TIER = 6;
+/**
+ * Tier vesting durations in seconds.
+ *
+ * - Tier 0: immediate at activation
+ * - Tier 1: 2 weeks  =  1,209,600s
+ * - Tier 2: 4 weeks  =  2,419,200s
+ * - Tier 3: 6 weeks  =  3,628,800s
+ * - Tier 4: 8 weeks  =  4,838,400s
+ * - Tier 5: 10 weeks =  6,048,000s
+ * - Tier 6: 12 weeks =  7,257,600s
+ */
+export declare const TIER_VESTING_SECONDS: readonly number[];
+/** Tier vesting durations in weeks (for display). */
+export declare const TIER_VESTING_WEEKS: readonly number[];
+/**
+ * Compute the user's total token entitlement from their vault allocation.
+ *
+ * Formula: `tokens_to_participants × user_allocated / total_allocated`
+ *
+ * Uses BN for precision. Returns `null` if `total_allocated == 0`.
+ */
+export declare function computeUserTokens(tokensToParticipants: BN, userAllocated: BN, totalAllocated: BN): BN | null;
+/**
+ * Compute the total vested amount at a given time.
+ *
+ * - Tier 0: 100% immediately at pool activation time
+ * - Tier 1–6: Linear vesting from pool_activation_time over tier duration
+ *
+ * Returns the total vested (caller subtracts `already_claimed`).
+ */
+export declare function computeVestedAmount(totalTokens: BN, tier: number, poolActivationTime: number, currentTime: number): BN;
+/**
+ * Compute the user's allocated amount from their depositor record and vault data.
+ *
+ * Mirrors `DepositorRecord::allocated_amount(&self, vault)` on-chain:
+ *   - If allocations not yet calculated → return raw `amount`
+ *   - If tier_totals_at_allocation[tier] == 0 → return 0
+ *   - Otherwise → `amount × tier_allocated[tier] / tier_totals_at_allocation[tier]`
+ *
+ * IMPORTANT: This uses vault tier-level allocation data for accuracy.
+ * The `finalAmount` field on `DepositorRecord` only reflects the correct
+ * allocation AFTER the user claims their excess refund. Before that,
+ * `finalAmount == amount` (the full deposit), which over-estimates
+ * allocation in oversubscribed tiers.
+ */
+export declare function computeAllocatedAmount(depositor: DepositorRecordRaw, vaultData: VaultAllocationData): BN;
+/**
+ * Compute full claim eligibility for a user.
+ *
+ * This is a **pure function** — no RPC calls. It takes pre-fetched account
+ * data and returns a comprehensive eligibility result. Works identically
+ * on client and server.
+ *
+ * @param launchConfigData  - Decoded LaunchConfig account
+ * @param depositorRecord   - Decoded DepositorRecord (from vault program), or `null` if not found
+ * @param claimRecord       - Decoded ClaimRecord, or `null` if user hasn't claimed yet
+ * @param currentTime       - Current unix timestamp in seconds (from `Date.now() / 1000` or RPC clock)
+ * @param vaultData         - Vault allocation data (tier arrays + total_allocated + flag)
+ */
+export declare function computeClaimEligibility(launchConfigData: LaunchConfigAccount, depositorRecord: DepositorRecordRaw | null, claimRecord: ClaimRecordAccount | null, currentTime: number, vaultData: VaultAllocationData): ClaimEligibility;
+//# sourceMappingURL=eligibility.d.ts.map

package/dist/claims/eligibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../src/claims/eligibility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,OAAO,CAAC;AAEvB,OAAO,KAAK,EACR,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EAEtB,MAAM,UAAU,CAAC;AAMlB,+CAA+C;AAC/C,eAAO,MAAM,SAAS,IAAI,CAAC;AAE3B,gCAAgC;AAChC,eAAO,MAAM,QAAQ,IAAI,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAQjD,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAA4B,CAAC;AAM7E;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,oBAAoB,EAAE,EAAE,EACxB,aAAa,EAAE,EAAE,EACjB,cAAc,EAAE,EAAE,GACjB,EAAE,GAAG,IAAI,CAKX;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,EAAE,EACf,IAAI,EAAE,MAAM,EACZ,kBAAkB,EAAE,MAAM,EAC1B,WAAW,EAAE,MAAM,GAClB,EAAE,CAwBJ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,kBAAkB,EAC7B,SAAS,EAAE,mBAAmB,GAC7B,EAAE,CAmBJ;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,mBAAmB,EACrC,eAAe,EAAE,kBAAkB,GAAG,IAAI,EAC1C,WAAW,EAAE,kBAAkB,GAAG,IAAI,EACtC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,mBAAmB,GAC7B,gBAAgB,CAgKlB"}