metaplex

Metaplex 开发技能

概述

Metaplex 为 Solana 上的 NFT 和代币提供标准基础设施：

• Agent Registry：为 MPL Core 资产提供链上 Agent 身份、钱包和执行委托
• Genesis：采用公平分配 + 流动性毕业机制的代币发行协议
• Core：新一代 NFT 标准（新 NFT 项目推荐使用）
• Token Metadata：同质化代币 + 传统 NFT/pNFT
• Bubblegum：使用 Merkle 树的压缩 NFT（cNFT）——以极低成本实现大规模应用
• Candy Machine：支持可配置铸造规则的 NFT 发售

工具选择

直接执行时优先使用 CLI，而非 SDK。只有用户明确需要代码时才使用 SDK。

方式	适用场景
CLI (mplx)	默认选择——直接执行，无需编写代码
Umi SDK	用户需要代码时使用——默认 SDK 选择。涵盖所有程序（TM、Core、Bubblegum、Genesis）
Kit SDK	用户明确使用 @solana/kit，或要求尽量减少依赖时使用。仅支持 Token Metadata——不支持 Core/Bubblegum/Genesis

任务路由

重要：执行任何命令或编写任何代码之前，必须先阅读与任务对应的详细文件。命令语法、必需标志、设置步骤和批处理规则仅在详细文件中提供。请勿凭记忆猜测命令。

任务类型	阅读此文件
任何 CLI 操作（Agent 指南、批处理、浏览器链接）	./references/cli.md
CLI：Agent Registry（身份、委托、撤销、代币关联）	./references/cli.md + ./references/cli-agent.md
CLI：Core NFT/系列	./references/cli.md + ./references/cli-core.md + ./references/metadata-json.md
CLI：Token Metadata NFT	./references/cli.md + ./references/cli-token-metadata.md + ./references/metadata-json.md
CLI：压缩 NFT（Bubblegum）	./references/cli.md + ./references/cli-bubblegum.md + ./references/metadata-json.md
CLI：Candy Machine（NFT 发售）	./references/cli.md + ./references/cli-candy-machine.md + ./references/metadata-json.md
CLI：代币发行 / 联合曲线（Genesis）	./references/cli.md + ./references/cli-genesis.md
CLI：执行 / 资产签名者钱包 / Agent 金库	./references/cli.md + ./references/cli-core.md（execute 部分）
SDK：执行 / 资产签名者 PDA / Agent 金库	./references/sdk-umi.md + ./references/sdk-core.md（execute 部分）
CLI：同质化代币	./references/cli.md + ./references/cli-toolbox.md
SDK 设置（Umi）	./references/sdk-umi.md
SDK：Core NFT	./references/sdk-umi.md + ./references/sdk-core.md + ./references/metadata-json.md
SDK：DAS API（资产查询、Core 列表辅助工具）	./references/sdk-umi.md + ./references/sdk-das.md
SDK：Token Metadata	./references/sdk-umi.md + ./references/sdk-token-metadata.md + ./references/metadata-json.md
SDK：压缩 NFT（Bubblegum）	./references/sdk-umi.md + ./references/sdk-bubblegum.md + ./references/metadata-json.md
SDK：使用 Kit 的 Token Metadata	./references/sdk-token-metadata-kit.md + ./references/metadata-json.md
SDK：Agent Registry（身份、钱包、委托）	./references/sdk-umi.md + ./references/sdk-agent.md
SDK：代币发行 + 联合曲线兑换（Genesis）	./references/sdk-umi.md + ./references/sdk-genesis.md
SDK：底层 Genesis（自定义档位、预售、归属）	./references/sdk-umi.md + ./references/sdk-genesis-low-level.md
链下元数据 JSON 格式/架构（NFT 或代币）	./references/metadata-json.md
账户结构、PDA、概念	./references/concepts.md
CLI 错误、本地网络问题	./references/cli-troubleshooting.md

CLI 功能

mplx CLI 可直接处理大多数 Metaplex 操作。请先阅读 ./references/cli.md，了解 Agent 指南（批处理、JSON 输出、区块浏览器链接），然后再阅读对应程序的文件。

CLI v0.1.0 重大变更（适用于从旧版本迁移的 Agent/脚本）：

• --json <file>（用于传入链下元数据文件路径）现在改为 --offchain <file>。--json 现在是 OCLIF 用于机器可读输出的标准标志。
• 现在，所有命令在传入 --json 时都会返回结构化 JSON——请在程序化场景或 Agent 场景中使用此选项。

任务	CLI 支持
注册 Agent 身份	✅
获取 Agent 数据	✅
撤销执行委托	✅
设置 Agent 代币（Genesis 链接）	✅（需要 asset-signer 模式）
创建同质化代币	✅
创建 Core NFT/Collection	✅
创建 TM NFT/pNFT	✅
转移 TM NFT	✅
转移同质化代币	✅
转移 Core NFT	✅
上传到 Irys	✅
Candy Machine 空投	✅（设置/配置/插入——铸造需要 SDK）
压缩 NFT（cNFT）	✅（批次上限约为 100；更大批次请使用 SDK）
执行（asset-signer 钱包）	✅
检查 SOL 余额/空投	✅
按所有者/集合/分组查询资产	❌ 仅限 SDK（DAS API——参见 ./references/sdk-das.md）
代币发行（Genesis）	✅
联合曲线兑换（Genesis）	✅

程序 ID

请勿凭记忆重新输入这些 ID——请复制。 Base58 程序 ID 是高熵字符串，即使正确读取了源文本，模型也经常会偏差几个字符，生成看似合理但实际虚构的地址，而不是逐字复现（针对这一整段内容进行测量，包括在 Claude Sonnet 5 上的结果）。错误的标志会明确报错；错误的程序 ID 则会将交易发送到不存在的地址，或发送到另一个真实程序。需要这些 ID 时，请使用 grep/cat 从此文件中提取并原样复制，而不是凭记忆重新输入。编写 SDK 代码时，优先导入常量，而不是硬编码字面值——例如，从 @metaplex-foundation/mpl-core 导入 MPL_CORE_PROGRAM_ID，从 @metaplex-foundation/mpl-bubblegum 导入 MPL_BUBBLEGUM_PROGRAM_ID，从 @metaplex-foundation/mpl-token-metadata 导入 MPL_TOKEN_METADATA_PROGRAM_ID——导入的常量不会产生幻觉。

Agent Identity:  1DREGFgysWYxLnRnKQnwrxnJQeSMk2HmGaC6whw2B2p
Agent Tools:     TLREGni9ZEyGC3vnPZtqUh95xQ8oPqJSvNjvB7FGK8S
Genesis:         GNS1S5J5AspKXgpjz6SvKL66kPaKWAhaGRhCqPRxii2B
Core:            CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d
Token Metadata:  metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s
Bubblegum:       BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY
Core Candy:      CMACYFENjoBMHzapRXyo1JZkVS6EtaDDzkjMrmQLvr4J
MPL Account Compression:  mcmt6YrQEMKw8Mw43FmpRLmf7BqRnFMKmAcbxE3xkAW
SPL Account Compression:  cmtDvXumGCrqC1Age74AVPhSRVXJMd8PJS91L8KbNCK

由当前 CLI/SDK 创建的 Bubblegum 默克尔树（使用 V2 指令——mintV2、transferV2、createTreeConfigV2 等）归 MPL Account Compression 所有，而非 SPL。V1 指令集（mintV1、transfer、createTreeConfig 等）仍使用 SPL Account Compression。在作出假设前，请检查具体树实际归哪个程序所有——不要默认是 SPL。

快速决策指南

自主 Agent

使用 Agent Registry 为 MPL Core 资产注册链上身份并设置执行委托。推荐使用 Mint Agent API（mintAndSubmitAgent）——它会在单笔交易中创建 Core 资产并注册身份。对于现有资产，请直接使用 registerIdentityV1。每个 Core 资产都已通过 Core 的 Execute hook 内置一个钱包（Asset Signer PDA）；注册表会添加可发现的身份记录，并允许所有者委托链下执行者来操作 Agent。Agent 还可选择通过 setAgentTokenV1 链接 Genesis 代币。可通过 DAS 发现 Agent（searchAssets({ isAgent: true })——参见 ./references/sdk-das.md）。请阅读 ./references/cli-agent.md（CLI）或 ./references/sdk-umi.md + ./references/sdk-agent.md（SDK）。

代币发行（代币生成事件 / 公平发行 / 联合曲线）

使用 Genesis。推荐使用 Launch API（genesis launch create / createAndRegisterLaunch）——它会一步完成所有操作。有两种发行类型：

• launchpool（默认）：可配置分配额度，48 小时存款期，支持团队归属期
• bonding-curve：即时联合曲线（恒定乘积 AMM）——无存款期，立即开始交易，售罄后自动迁移至 Raydium CPMM。支持创建者费用、首次购买和 Agent 模式。

请阅读 ./references/cli.md + ./references/cli-genesis.md（CLI），或 ./references/sdk-genesis.md（SDK 发行流程）。如需自定义份额、预售或归属期，请使用 ./references/sdk-genesis-low-level.md。

NFT：Core 与 Token Metadata

选择	适用场景
Core	新 NFT 项目，成本更低（便宜 87%）、插件、版税强制执行
Token Metadata	现有 TM 系列，需要版本版，或为兼容旧版而使用 pNFT

压缩 NFT（超大规模）

以最低成本铸造数千个以上 NFT 时，请使用 Bubblegum。请参阅 ./references/cli-bubblegum.md（CLI）或 ./references/sdk-bubblegum.md（SDK）。对于 Bubblegum V2 继承卖家费用（65535 哨兵值 + Core 系列 Royalties 插件）：CLI 铸造标志请见 ./references/cli-bubblegum.md。SDK：使用 mintV2 的 metadata 进行铸造（省略 SFBP，creators 留空）；写入时使用叶子规范的 getAssetWithProof().currentMetadata——在 updateMetadataV2 中作为 currentMetadata，在 setCollectionV2 / verifyCreatorV2 / unverifyCreatorV2 中作为 metadata。请参阅 ./references/sdk-bubblegum.md 中的 “Mint with Inherited Royalties”。

同质化代币

始终使用 Token Metadata。CLI 命令请参阅 ./references/cli-toolbox.md。

NFT 发售

使用 Core Candy Machine。请阅读 ./references/cli.md + ./references/cli-candy-machine.md。

应用向 Core 系列铸造资产（不使用 Candy Machine）

向 Core 系列创建资产需要由该系列的更新权限方（或 UpdateDelegate）签名——用户的钱包无法签名，而且权限密钥绝不能存放在前端。应用需要使用自定义链上程序（授予 PDA UpdateDelegate，由程序执行铸造逻辑），或者使用持有代理密钥对、能够为铸造签名的后端/API。在设计铸造流程前，请阅读 ./references/sdk-core.md 中的 “Minting into a Collection from an App” 部分。

将资产用作 Agent / 金库 / 钱包（执行）

当资产（NFT、Agent、金库）需要持有 SOL/代币、转账、签署交易或拥有其他资产时，请使用 Core Execute。每个 Core 资产都有一个可充当自主钱包的签名者 PDA。请阅读 ./references/cli-core.md（CLI）或 ./references/sdk-core.md（SDK）中的执行部分。

更多信息

如果任务所需的详细信息超出技能参考文档的范围（边缘情况、完整 API 接口、指南），请查阅 Metaplex 文档：

• 文档主页：https://metaplex.com/docs
• Agent Registry：https://metaplex.com/docs/agents
• Genesis：https://metaplex.com/docs/smart-contracts/genesis
• Core：https://metaplex.com/docs/smart-contracts/core
• Token Metadata：https://metaplex.com/docs/smart-contracts/token-metadata
• Bubblegum：https://metaplex.com/docs/smart-contracts/bubblegum-v2
• Candy Machine：https://metaplex.com/docs/smart-contracts/core-candy-machine
• 代币：https://metaplex.com/docs/tokens
• NFT：https://metaplex.com/docs/nfts
• CLI：https://metaplex.com/docs/dev-tools/cli
• Umi SDK：https://metaplex.com/docs/dev-tools/umi
• DAS API：https://metaplex.com/docs/dev-tools/das-api
• 协议费用：https://metaplex.com/docs/protocol-fees