@star-factory/sdk-launchpad 0.1.0

package/dist/sdk.d.ts

@@ -0,0 +1,274 @@
+import type { Idl, Program } from '@coral-xyz/anchor';
+import { Connection, PublicKey, Transaction } from '@solana/web3.js';
+import { type ExecuteLaunchAccountsResolved } from './instructions';
+import { BuildExecuteLaunchArgsInput, BuildReserveAdminParamsInput, BuildReserveAdminParamsResult, BuildTokenMetadataJsonInput, CancelLaunchOptions, ClaimEligibility, ClaimTransactionOptions, ConfigureLaunchMetadataArgs, ConfigureLaunchMetadataInput, ConfigureLaunchOptions, CreateLaunchTokenOptions, DerivePoolAddressRequest, DerivePoolAddressResult, ExecuteLaunchInstructionArgs, ExecuteLaunchOptions, HealthCheckResult, InitializeLaunchOptions, LaunchpadSDKFullConfig, PrepareLaunchExecutionRequest, PrepareLaunchExecutionResult, TokenMetadataJson, ValidationResult } from './types';
+import { ReserveAdminParams, ReserveAdminResponse, ZCClient } from './zc';
+/**
+ * Launchpad SDK
+ *
+ * Handles the off-chain prerequisites for token launches:
+ * 1. Derive DAMM pool address
+ * 2. Reserve admin with zCombinator API
+ *
+ * @example
+ * ```typescript
+ * const sdk = new LaunchpadSDK({
+ *   connection,
+ *   cluster: 'devnet',
+ *   zcApiKey: process.env.ZC_API_KEY!,
+ * });
+ *
+ * // Step 1: Derive pool address (pool doesn't exist yet!)
+ * const poolAddress = sdk.derivePoolAddress(baseMint, quoteMint);
+ *
+ * // Step 2: Reserve admin (off-chain API call to ZC)
+ * const reservation = await sdk.reserveAdmin({
+ *   name: 'SurfCash',
+ *   tokenMint: baseMint,
+ *   poolAddress,
+ *   poolType: 'damm',
+ *   quoteMint,
+ *   treasuryCosigner: teamMultisig,
+ *   ownerWallet: projectOwner,
+ * });
+ *
+ * // reservation.adminWallet is ZC's managed admin
+ * // Use this in transferAdmin IX after DAO creation
+ * ```
+ *
+ * @see https://docs.combinator.trade/llms.txt
+ */
+export declare class LaunchpadSDK {
+    readonly connection: Connection;
+    readonly cluster: 'devnet' | 'mainnet-beta' | 'testnet';
+    readonly dammProgramId: PublicKey;
+    readonly zcClient: ZCClient;
+    constructor(config: LaunchpadSDKFullConfig);
+    /**
+     * Derive the DAMM pool address for a token pair.
+     *
+     * IMPORTANT: The pool doesn't exist yet at this point!
+     * This computes the PREDICTED address that will be created during execute_launch.
+     *
+     * @param baseMint - Token being launched (vanity mint)
+     * @param quoteMint - SOL or USDC
+     * @param config - Optional DAMM config override (defaults to DAMM_CONFIG_PDA)
+     */
+    derivePoolAddress(baseMint: PublicKey, quoteMint: PublicKey, config?: PublicKey): PublicKey;
+    derivePoolAddress(input: DerivePoolAddressRequest): PublicKey;
+    /**
+     * Derive pool address with sorted mint context for downstream account building.
+     */
+    derivePoolAddressWithContext(input: DerivePoolAddressRequest): DerivePoolAddressResult;
+    /**
+     * Reserve an admin key with zCombinator.
+     *
+     * This is an OFF-CHAIN API call that must be made before building the
+     * execute_launch transaction.
+     *
+     * PREREQUISITES (derive these first):
+     * - tokenMint: the vanity mint address (from grinding)
+     * - poolAddress: use derivePoolAddress() above
+     *
+     * The reservation returns:
+     * - adminWallet: ZC's managed admin (use in transferAdmin IX)
+     * - adminKeyIdx: ZC internal key index
+     * - daoId: ZC database DAO ID
+     *
+     * After calling this, build your atomic transaction:
+     * 1. Token launch instructions
+     * 2. Pool launch instructions
+     * 3. DAO creation (with launchpad PDA as temp admin)
+     * 4. transferAdmin to adminWallet (from this response)
+     * 5. LP transfer to adminWallet
+     *
+     * @param params - Name, token mint, pool address, etc.
+     *
+     * @see https://github.com/zcombinatorio/combinator/blob/main/ui/routes/dao/creation.ts
+     */
+    reserveAdmin(params: ReserveAdminParams): Promise<ReserveAdminResponse>;
+    /**
+     * Validate launch pre-execution values that are known off-chain.
+     */
+    validateLaunchPreparation(request: {
+        daoName: string;
+    }): ValidationResult;
+    /**
+     * Validate configure_launch metadata constraints before submitting on-chain tx.
+     */
+    validateConfigureLaunchMetadata(input: ConfigureLaunchMetadataInput): ValidationResult;
+    /**
+     * Build canonical configure_launch metadata args with validation.
+     */
+    buildConfigureLaunchMetadataArgs(input: ConfigureLaunchMetadataInput): ConfigureLaunchMetadataArgs;
+    /**
+     * Build metadata JSON payload for off-chain hosting providers.
+     * Caller uploads resulting JSON and uses returned URL as configure_launch `uri`.
+     */
+    buildTokenMetadataJson(input: BuildTokenMetadataJsonInput): TokenMetadataJson;
+    /**
+     * Build reserve-admin params in a deterministic and typed way.
+     */
+    buildReserveAdminParams(input: BuildReserveAdminParamsInput): BuildReserveAdminParamsResult;
+    /**
+     * Build `execute_launch` args from reservation output.
+     */
+    buildExecuteLaunchArgs(input: BuildExecuteLaunchArgsInput): ExecuteLaunchInstructionArgs;
+    /**
+     * One-call helper for all pre-execution off-chain ops:
+     * 1) derive pool address
+     * 2) call ZC reserve-admin
+     * 3) construct execute_launch args
+     */
+    prepareLaunchExecution(input: PrepareLaunchExecutionRequest): Promise<PrepareLaunchExecutionResult>;
+    /**
+     * Build an unsigned `initialize_launch` transaction.
+     *
+     * Creates a LaunchConfig PDA + underlying 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'),
+     *   tokensToParticipants: new BN('500000000000000'),
+     *   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,
+     * });
+     * ```
+     */
+    buildInitializeLaunchTx(launchpadProgram: Program<Idl>, opts: InitializeLaunchOptions): Promise<Transaction>;
+    /**
+     * Build an unsigned `configure_launch` transaction.
+     *
+     * Sets vanity mint config + token metadata.
+     * Transitions FundraiseActive → ReadyToLaunch.
+     */
+    buildConfigureLaunchTx(launchpadProgram: Program<Idl>, opts: ConfigureLaunchOptions): Promise<Transaction>;
+    /**
+     * Build an unsigned `create_launch_token` transaction.
+     *
+     * Creates vanity mint, Metaplex metadata, mints total supply.
+     * Transitions ReadyToLaunch → TokenCreated.
+     *
+     * **Important**: The returned TX must be signed by both `admin` and `baseKeypair`.
+     */
+    buildCreateLaunchTokenTx(launchpadProgram: Program<Idl>, opts: CreateLaunchTokenOptions): Promise<Transaction>;
+    /**
+     * Build an unsigned `execute_launch` transaction.
+     *
+     * Atomically finalizes vault, creates DAMM pool, creates DAO,
+     * transfers authorities, and routes funds.
+     * Transitions TokenCreated → Launched.
+     *
+     * Returns both the transaction and all resolved accounts (for ALT creation).
+     *
+     * **Important**: This TX has ~35 accounts and requires an Address Lookup Table.
+     * Use the returned `accounts` to populate the ALT, then compile to a
+     * VersionedTransaction before sending.
+     *
+     * ```typescript
+     * const { tx, accounts } = await sdk.buildExecuteLaunchTx(launchpadProgram, {
+     *   admin: adminKeypair.publicKey,
+     *   launchConfig: launchConfigPda,
+     *   launchConfigData,
+     *   poolActivationTime: new BN(now + 120),
+     *   daoName: 'MyDAO',
+     *   treasuryCosigner: teamMultisig,
+     *   newDaoAdmin: reservation.adminWallet,
+     *   dammPool: poolAddress,
+     *   vaultProgramId: VAULT_PROGRAM_ID,
+     *   computeUnits: 1_400_000,
+     * });
+     * ```
+     */
+    buildExecuteLaunchTx(launchpadProgram: Program<Idl>, opts: ExecuteLaunchOptions): Promise<{
+        tx: Transaction;
+        accounts: ExecuteLaunchAccountsResolved;
+    }>;
+    /**
+     * Build an unsigned `cancel_launch` transaction.
+     *
+     * Cancels from any pre-Launched state. Burns tokens if minted.
+     */
+    buildCancelLaunchTx(launchpadProgram: Program<Idl>, opts: CancelLaunchOptions): Promise<Transaction>;
+    /**
+     * Check whether a user can claim tokens, and how much.
+     *
+     * This is the primary method for frontends to determine whether to show
+     * the claim button and what information to display.
+     *
+     * **Works on both client and server** — fetches on-chain state and
+     * runs a pure eligibility computation.
+     *
+     * @param launchpadProgram - Anchor program instance for the launchpad
+     * @param vaultProgram     - Anchor program instance for the vault
+     * @param launchConfig     - The launch config PDA address
+     * @param user             - The user's wallet pubkey
+     * @param currentTime      - Optional unix timestamp override (for testing).
+     *                           Defaults to `Date.now() / 1000`.
+     *
+     * @example
+     * ```typescript
+     * const eligibility = await sdk.getClaimEligibility(
+     *   launchpadProgram,
+     *   vaultProgram,
+     *   launchConfigPda,
+     *   wallet.publicKey,
+     * );
+     *
+     * if (eligibility.canClaim) {
+     *   console.log(`Claimable: ${eligibility.claimableNow.toString()} tokens`);
+     * } else {
+     *   console.log(`Cannot claim: ${eligibility.reason}`);
+     * }
+     * ```
+     */
+    getClaimEligibility(launchpadProgram: Program<Idl>, vaultProgram: Program<Idl>, launchConfig: PublicKey, user: PublicKey, currentTime?: number): Promise<ClaimEligibility>;
+    /**
+     * Build an unsigned `claim_tokens` transaction for a user.
+     *
+     * The transaction is ready for signing by the user's wallet (or relay).
+     * Includes compute budget and priority fee if specified.
+     *
+     * **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 (relay/sponsored):**
+     * ```typescript
+     * const tx = await sdk.buildClaimTx(launchpadProgram, {
+     *   user: userPubkey,
+     *   launchConfig: launchConfigPda,
+     *   launchConfigData,
+     *   vaultProgramId: VAULT_PROGRAM_ID,
+     *   feePayer: relayPubkey,        // sponsor pays gas
+     *   priorityFee: 10_000,          // 10k micro-lamports/CU
+     * });
+     * // Serialize and send to user for signing, then relay signs + submits
+     * ```
+     *
+     * @param launchpadProgram - Anchor program instance for the launchpad
+     * @param opts             - Claim transaction options
+     */
+    buildClaimTx(launchpadProgram: Program<Idl>, opts: ClaimTransactionOptions): Promise<Transaction>;
+    /**
+     * Check ZC API health status.
+     *
+     * @see https://docs.combinator.trade/api-reference/health
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+}
+//# sourceMappingURL=sdk.d.ts.map

package/dist/sdk.d.ts.map

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