SDK

JavaScript SDK

Last updated January 31, 2026

Genesis JavaScript SDK 的 API 参考。完整教程请参阅 Launch PoolPresale

NPM Package

@metaplex-foundation/genesis

TypeDoc

自动生成的 API 文档

安装

npm install @metaplex-foundation/genesis @metaplex-foundation/umi \
@metaplex-foundation/umi-bundle-defaults @metaplex-foundation/mpl-toolbox \
@metaplex-foundation/mpl-token-metadata

设置

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
import { genesis } from '@metaplex-foundation/genesis';
import { mplTokenMetadata } from '@metaplex-foundation/mpl-token-metadata';
const umi = createUmi('https://api.mainnet-beta.solana.com')
.use(genesis())
.use(mplTokenMetadata());

完整的实现示例请参阅 Launch PoolPresale


指令参考

核心

函数描述
initializeV2()创建 Genesis Account 并铸造代币
finalizeV2()锁定配置,激活发行

Buckets

函数描述
addLaunchPoolBucketV2()添加按比例分配的 bucket
addPresaleBucketV2()添加固定价格销售 bucket
addUnlockedBucketV2()添加资金库/接收者 bucket

Launch Pool 操作

函数描述
depositLaunchPoolV2()向 Launch Pool 存入 SOL
withdrawLaunchPoolV2()提取 SOL(存款期间)
claimLaunchPoolV2()领取代币(存款期结束后)

Presale 操作

函数描述
depositPresaleV2()向 Presale 存入 SOL
claimPresaleV2()领取代币(存款期结束后)

管理员

函数描述
transitionV2()执行结束行为
revokeMintAuthorityV2()永久撤销铸造权限
revokeFreezeAuthorityV2()永久撤销冻结权限

函数签名

initializeV2

await initializeV2(umi, {
baseMint, // Signer - new token keypair
quoteMint, // PublicKey - deposit token (wSOL)
fundingMode, // number - use 0
totalSupplyBaseToken, // bigint - supply with decimals
name, // string - token name
symbol, // string - token symbol
uri, // string - metadata URI
}).sendAndConfirm(umi);

finalizeV2

await finalizeV2(umi, {
baseMint, // PublicKey
genesisAccount, // PublicKey
}).sendAndConfirm(umi);

addLaunchPoolBucketV2

await addLaunchPoolBucketV2(umi, {
genesisAccount, // PublicKey
baseMint, // PublicKey
baseTokenAllocation, // bigint - tokens for this bucket
depositStartCondition, // TimeCondition
depositEndCondition, // TimeCondition
claimStartCondition, // TimeCondition
claimEndCondition, // TimeCondition
minimumDepositAmount, // bigint | null
endBehaviors, // EndBehavior[]
}).sendAndConfirm(umi);

addPresaleBucketV2

await addPresaleBucketV2(umi, {
genesisAccount, // PublicKey
baseMint, // PublicKey
baseTokenAllocation, // bigint
allocationQuoteTokenCap, // bigint - SOL cap (sets price)
depositStartCondition, // TimeCondition
depositEndCondition, // TimeCondition
claimStartCondition, // TimeCondition
claimEndCondition, // TimeCondition
minimumDepositAmount, // bigint | null
depositLimit, // bigint | null - max per user
endBehaviors, // EndBehavior[]
}).sendAndConfirm(umi);

addUnlockedBucketV2

await addUnlockedBucketV2(umi, {
genesisAccount, // PublicKey
baseMint, // PublicKey
baseTokenAllocation, // bigint - usually 0n
recipient, // PublicKey - who can claim
claimStartCondition, // TimeCondition
claimEndCondition, // TimeCondition
}).sendAndConfirm(umi);

depositLaunchPoolV2

await depositLaunchPoolV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
amountQuoteToken, // bigint - lamports
}).sendAndConfirm(umi);

depositPresaleV2

await depositPresaleV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
amountQuoteToken, // bigint - lamports
}).sendAndConfirm(umi);

withdrawLaunchPoolV2

await withdrawLaunchPoolV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
amountQuoteToken, // bigint - lamports
}).sendAndConfirm(umi);

claimLaunchPoolV2

await claimLaunchPoolV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
recipient, // PublicKey
}).sendAndConfirm(umi);

claimPresaleV2

await claimPresaleV2(umi, {
genesisAccount, // PublicKey
bucket, // PublicKey
baseMint, // PublicKey
recipient, // PublicKey
}).sendAndConfirm(umi);

transitionV2

await transitionV2(umi, {
genesisAccount, // PublicKey
primaryBucket, // PublicKey
baseMint, // PublicKey
})
.addRemainingAccounts([/* destination accounts */])
.sendAndConfirm(umi);

revokeMintAuthorityV2

await revokeMintAuthorityV2(umi, {
baseMint, // PublicKey
}).sendAndConfirm(umi);

revokeFreezeAuthorityV2

await revokeFreezeAuthorityV2(umi, {
baseMint, // PublicKey
}).sendAndConfirm(umi);

PDA 辅助函数

函数种子
findGenesisAccountV2Pda()baseMint, genesisIndex
findLaunchPoolBucketV2Pda()genesisAccount, bucketIndex
findPresaleBucketV2Pda()genesisAccount, bucketIndex
findUnlockedBucketV2Pda()genesisAccount, bucketIndex
findLaunchPoolDepositV2Pda()bucket, recipient
findPresaleDepositV2Pda()bucket, recipient
const [genesisAccountPda] = findGenesisAccountV2Pda(umi, { baseMint: mint.publicKey, genesisIndex: 0 });
const [bucketPda] = findLaunchPoolBucketV2Pda(umi, { genesisAccount: genesisAccountPda, bucketIndex: 0 });
const [depositPda] = findLaunchPoolDepositV2Pda(umi, { bucket: bucketPda, recipient: wallet });

获取函数

函数返回值
fetchLaunchPoolBucketV2()Bucket 状态(不存在时抛出错误)
safeFetchLaunchPoolBucketV2()Bucket 状态或 null
fetchPresaleBucketV2()Bucket 状态(不存在时抛出错误)
safeFetchPresaleBucketV2()Bucket 状态或 null
fetchLaunchPoolDepositV2()存款状态(不存在时抛出错误)
safeFetchLaunchPoolDepositV2()存款状态或 null
fetchPresaleDepositV2()存款状态(不存在时抛出错误)
safeFetchPresaleDepositV2()存款状态或 null
const bucket = await fetchLaunchPoolBucketV2(umi, bucketPda);
const deposit = await safeFetchLaunchPoolDepositV2(umi, depositPda); // null if not found

Bucket 状态字段: quoteTokenDepositTotaldepositCountclaimCountbucket.baseTokenAllocation

存款状态字段: amountQuoteTokenclaimed


类型

TimeCondition

{
__kind: 'TimeAbsolute',
padding: Array(47).fill(0),
time: bigint, // Unix timestamp (seconds)
triggeredTimestamp: null,
}

EndBehavior

{
__kind: 'SendQuoteTokenPercentage',
padding: Array(4).fill(0),
destinationBucket: PublicKey,
percentageBps: number, // 10000 = 100%
processed: false,
}

常量

常量
WRAPPED_SOL_MINTSo11111111111111111111111111111111111111112

常见错误

错误原因
insufficient fundsSOL 不足以支付费用
already initializedGenesis Account 已存在
already finalized最终化后无法修改
deposit period not active不在存款窗口内
claim period not active不在领取窗口内

常见问题

什么是 Umi,为什么需要它?

Umi 是 Metaplex 的 Solana JavaScript 框架。它提供了统一的接口来构建交易、管理签名者以及与 Metaplex 程序交互。

我可以在浏览器中使用 Genesis SDK 吗?

可以。SDK 在 Node.js 和浏览器环境中都可以使用。在浏览器中,请使用钱包适配器进行签名,而不是密钥对文件。

fetch 和 safeFetch 有什么区别?

fetch 在账户不存在时会抛出错误。safeFetch 则返回 null,适用于检查账户是否存在。

如何处理交易错误?

sendAndConfirm 调用包装在 try/catch 块中。检查错误消息以了解具体的失败原因。


下一步

完整的实现教程: