From 37da65f5f148092458fedd9fad7df86b7db4beeb Mon Sep 17 00:00:00 2001 From: Tony Boyle Date: Fri, 18 Sep 2026 01:20:46 +0100 Subject: [PATCH] docs(genesis): add refundLaunchPoolV2 and soft cap to the JS SDK reference refundLaunchPoolV2 was missing from the SDK reference entirely, and the addLaunchPoolBucketV2 signature predated the softCap and minimumQuoteTokenThreshold extensions. - Document refundLaunchPoolV2 with its signature, permissionless crank behaviour, and the errors it can return - Add softCap and minimumQuoteTokenThreshold to the addLaunchPoolBucketV2 signature, flagging that softCap is required in 0.42.0 and has no serializer default - Add a LaunchPoolV2Extensions type block and note the add/removeLaunchPoolBucketV2Extensions instructions - Extend the bucket and deposit state field lists with refundCount, weightedQuoteTokenTotal, extensions, weightedQuoteToken and refunded - Add the soft cap and refund errors to Common Errors - Fix two pre-existing broken in-page anchors (#launchtype and #gpa-builder--query-by-launch-type) --- .../smart-contracts/genesis/sdk/javascript.md | 62 +++++++++++++++++-- 1 file changed, 56 insertions(+), 6 deletions(-) diff --git a/src/pages/en/smart-contracts/genesis/sdk/javascript.md b/src/pages/en/smart-contracts/genesis/sdk/javascript.md index f0bf32b78..9cf10a968 100644 --- a/src/pages/en/smart-contracts/genesis/sdk/javascript.md +++ b/src/pages/en/smart-contracts/genesis/sdk/javascript.md @@ -3,7 +3,7 @@ title: JavaScript SDK metaTitle: JavaScript SDK | Genesis | Metaplex description: API reference for the Genesis JavaScript SDK. Function signatures, parameters, and types for token launches on Solana. created: '01-15-2025' -updated: '03-10-2026' +updated: '09-18-2026' keywords: - Genesis SDK - JavaScript SDK @@ -11,6 +11,8 @@ keywords: - token launch SDK - Umi framework - Genesis API reference + - refundLaunchPoolV2 + - soft cap about: - SDK installation - API reference @@ -90,6 +92,7 @@ For complete implementation examples, see [Launch Pool](/smart-contracts/genesis | [depositLaunchPoolV2()](#deposit-launch-pool-v2) | Deposit SOL into Launch Pool | | [withdrawLaunchPoolV2()](#withdraw-launch-pool-v2) | Withdraw SOL (during deposit period) | | [claimLaunchPoolV2()](#claim-launch-pool-v2) | Claim tokens (after deposit period) | +| [refundLaunchPoolV2()](#refund-launch-pool-v2) | Refund a deposit (failed threshold or exceeded soft cap) | ### Presale Operations @@ -143,11 +146,17 @@ await addLaunchPoolBucketV2(umi, { depositEndCondition, // TimeCondition claimStartCondition, // TimeCondition claimEndCondition, // TimeCondition - minimumDepositAmount, // bigint | null + minimumDepositAmount, // { amount: bigint } | null + minimumQuoteTokenThreshold, // { amount: bigint } | null - floor, launch fails below it + softCap, // { amount: bigint } | null - REQUIRED, ceiling on quote kept endBehaviors, // EndBehavior[] }).sendAndConfirm(umi); ``` +{% callout type="warning" %} +`softCap` is a required argument as of `@metaplex-foundation/genesis` 0.42.0. Unlike the other Launch Pool extensions it has no default in the generated serializer, so pass `softCap: null` explicitly when the launch has no cap. See [Launch Pool Soft Cap](/smart-contracts/genesis/launch-pool#launch-pool-soft-cap) for behaviour. +{% /callout %} + ### addPresaleBucketV2 ```typescript @@ -223,6 +232,21 @@ await claimLaunchPoolV2(umi, { }).sendAndConfirm(umi); ``` +### refundLaunchPoolV2 + +Refunds a Launch Pool deposit after the deposit window closes. The program derives the amount, so there is no amount argument: a missed `minimumQuoteTokenThreshold` refunds the full deposit, and an exceeded `softCap` refunds only the excess while leaving the depositor's token allocation intact. + +```typescript +await refundLaunchPoolV2(umi, { + genesisAccount, // PublicKey + bucket, // PublicKey + baseMint, // PublicKey + recipient, // PublicKey | Signer - depositor; base token account closed if they sign +}).sendAndConfirm(umi); +``` + +Only `payer` must sign, so refunds can be cranked permissionlessly on a depositor's behalf. Calling before the deposit window closes returns `LaunchPoolNotEnded`; calling when the floor was met and the cap was not exceeded returns `LaunchPoolThresholdMet`; calling twice returns `DepositAlreadyRefunded`. + ### claimPresaleV2 ```typescript @@ -286,7 +310,7 @@ const [depositPda] = findLaunchPoolDepositV2Pda(umi, { bucket: bucketPda, recipi ### Genesis Account -The Genesis Account stores top-level launch state including the [launch type](#launchtype). A backend crank sets the `launchType` field on-chain after creation via the `setLaunchTypeV2` instruction, so the value may initially be `Uninitialized` (0) until the crank processes it. +The Genesis Account stores top-level launch state including the [launch type](#launch-type). A backend crank sets the `launchType` field on-chain after creation via the `setLaunchTypeV2` instruction, so the value may initially be `Uninitialized` (0) until the crank processes it. | Function | Returns | |----------|---------| @@ -374,14 +398,35 @@ const bucket = await fetchLaunchPoolBucketV2(umi, bucketPda); const deposit = await safeFetchLaunchPoolDepositV2(umi, depositPda); // null if not found ``` -**Bucket state fields:** `quoteTokenDepositTotal`, `depositCount`, `claimCount`, `bucket.baseTokenAllocation` +**Bucket state fields:** `quoteTokenDepositTotal`, `weightedQuoteTokenTotal`, `depositCount`, `claimCount`, `refundCount`, `bucket.baseTokenAllocation`, `extensions` -**Deposit state fields:** `amountQuoteToken`, `claimed` +**Deposit state fields:** `amountQuoteToken`, `weightedQuoteToken`, `claimed`, `refunded` --- ## Types +### LaunchPoolV2Extensions + +Optional guards on a Launch Pool bucket, read from `bucket.extensions`. Every field is a Umi `Option`, so use `unwrapOption()` or check `.__option` before reading a value. + +```typescript +{ + backendSigner: Option; + depositPenalty: Option; + withdrawPenalty: Option; + bonusSchedule: Option; + depositLimit: Option; // { limit: bigint } + allowlist: Option; + claimSchedule: Option; + minimumDepositAmount: Option; // { amount: bigint } + minimumQuoteTokenThreshold: Option; // { amount: bigint } - floor + softCap: Option; // { amount: bigint } - ceiling +} +``` + +Extensions can be added or removed individually with `addLaunchPoolBucketV2Extensions()` and `removeLaunchPoolBucketV2Extensions()`, selecting the field via `LaunchPoolV2ExtensionType`. Both are rejected once the Genesis Account is finalized. + ### LaunchType The on-chain launch type, set retroactively by a backend crank via the `setLaunchTypeV2` instruction. The launch type represents the underlying mechanism used for the launch. @@ -461,6 +506,11 @@ Account size: **136 bytes**. PDA seeds: `["genesis_v2", baseMint, genesisIndex]` | `already finalized` | Cannot modify after finalization | | `deposit period not active` | Outside deposit window | | `claim period not active` | Outside claim window | +| `InvalidSoftCap` (221) | `softCap.amount` is zero — pass `softCap: null` instead of `{ amount: 0n }` | +| `SoftCapBelowThreshold` (222) | `softCap.amount` is below `minimumQuoteTokenThreshold.amount` | +| `LaunchPoolNotEnded` | `refundLaunchPoolV2()` called before the deposit window closed | +| `LaunchPoolThresholdMet` (173) | Refund requested when the floor was met and the soft cap was not exceeded | +| `DepositAlreadyRefunded` | `refundLaunchPoolV2()` called twice for the same deposit | --- @@ -476,7 +526,7 @@ Yes. The SDK works in both Node.js and browser environments. For browsers, use a `fetch` throws an error if the account doesn't exist. `safeFetch` returns `null` instead, useful for checking if an account exists. ### How do I retrieve the launch type for a token? -Fetch the `GenesisAccountV2` account using `fetchGenesisAccountV2FromSeeds()` with the token's mint address. The `launchType` field returns `0` (Uninitialized) or `3` (LaunchPoolV1). To query all launches of a given type, use the [GPA builder](#gpa-builder--query-by-launch-type). Alternatively, the [Integration APIs](/smart-contracts/genesis/integration-apis) return the launch type as a string in REST responses. +Fetch the `GenesisAccountV2` account using `fetchGenesisAccountV2FromSeeds()` with the token's mint address. The `launchType` field returns `0` (Uninitialized) or `3` (LaunchPoolV1). To query all launches of a given type, use the [GPA builder](#gpa-builder-query-by-launch-type). Alternatively, the [Integration APIs](/smart-contracts/genesis/integration-apis) return the launch type as a string in REST responses. ### How do I handle transaction errors? Wrap `sendAndConfirm` calls in try/catch blocks. Check error messages for specific failure reasons.