15个版本 (9个稳定版本)
| 3.0.1 | 2023年12月24日 |
|---|---|
| 2.0.2 |
|
| 2.0.1 | 2023年10月5日 |
| 1.0.4 | 2023年5月5日 |
| 0.1.3 | 2022年10月20日 |
10 在 #candy 中排名
每月76次下载
在 2 crates 中使用
160KB
2K SLoC
Metaplex Candy Machine Core（又名Candy Machine V3）
概述
Metaplex 协议的 Candy Machine 是在 Solana 上进行公平 NFT 集合发行的领先铸造和分发程序。它允许创作者将他们的资产元数据上链，并提供了从链上配置创建（铸造）NFT 的机制——无论是确定性还是非确定性（随机）方式，就像传统的糖果机。
Candy Machine 程序的最新版本保留了仅铸造 NFT 的核心功能，而任何访问控制配置现在都由新的 Candy Guard 程序来完成。
Candy Machine 程序负责：
- 配置行（资产）管理：配置有多少资产及其元数据信息；
- 索引生成和选择；
- NFT 铸造（创建代币）。
为什么将铸造逻辑和访问控制分离？
先前版本的 Candy Machine 将访问控制作为其铸造过程的一部分，以限制谁可以铸造、何时允许铸造以及其他与铸造相关的设置（例如，价格）。虽然将 铸造逻辑 与 访问控制 结合使用是可行的，但这种设计使得添加更多功能或移除不需要的功能变得复杂。
创建清晰的分离提供了模块化和灵活的架构，可以添加和移除访问控制设置，而无需承担破坏铸造逻辑的风险和复杂性。每个访问控制逻辑都可以独立实现，用户可以选择启用或禁用单个逻辑。
谁可以从Candy Machine中铸造？
每个糖果机账户关联两个权限：一个权限和一个mint_authority。该权限有权管理糖果机的配置。这包括添加配置行（资产）、更新其设置、更改权限/mint权限以及关闭/提款账户。
mint_authority是唯一能够从糖果机铸造的地址——唯一的要求是从中铸造NFT。糖果机的权限可以将mint_authority委托给另一个地址，无论是钱包还是PDA。这种分离提供了最大的灵活性，并使可组合性成为可能，因为其他程序可以设置为mint_authority，并在糖果机上提供额外的功能。例如，Candy Guard程序提供了对糖果机的访问控制保护。
账户
糖果机的配置存储在单个账户中，其中包含控制糖果机行为的设置以及通过它铸造的NFT的元数据信息。账户数据由CandyMachine结构体表示，其中包含对辅助结构体的引用Creator、ConfigLineSettings和HiddenSettings。
| 字段 | 偏移量 | 大小 | 描述 |
|---|---|---|---|
| — | 0 | 8 | 锚账户判别符。 |
account_version |
8 | 1 | AccountVersion |
token_standard |
9 | 1 | u8表示铸造NFT的代币标准（0 = NFT和4 = pNFT） |
features |
10 | 6 | [u8; 6]字段用作二进制标志，以支持未来功能的同时保持向后兼容。 |
authority |
16 | 32 | 控制糖果机的权限地址的PubKey。 |
mint_authority |
48 | 32 | 允许从糖果机铸造的地址的PubKey。 |
collection_mint |
80 | 32 | 收藏NFT的PubKey；从糖果机铸造的每个NFT都将属于这个收藏。 |
items_redeemed |
112 | 8 | 铸造的NFT数量。 |
数据 |
CandyMachineData |
||
- items_available |
120 | 8 | 可用的NFT总数。 |
- symbol |
128 | 14 | 表示代币符号的string：length（4字节）+ symbol（10字节）。 |
- seller_fee_basis_points |
142 | 2 | 授予创作者的版税百分比（0到1000之间的值）。 |
- max_supply |
144 | 8 | 表示在铸造后可以创建多少个NFT副本（版次）；这通常设置为0。 |
- is_mutable |
152 | 1 | 表示铸造的NFT是否可变。 |
- creators |
153 | ~ | 一个创建者数组及其版税份额；此数组限制为5个创建者。 注意：由于 creators 字段是一个可变长度的数组，我们无法保证任何后续字段的字节位置（注意下面字段中的波浪号 ~）。每个创建者包含以下字段 |
-- address |
~ | 32 | 创建者的公钥 |
-- verified |
~ | 1 | 创建者的公钥 |
-- share |
~ | 1 | 创建者的公钥 |
- config_line_settings |
~ | 1 | (可选) ConfigLineSettings |
-- prefix_name |
~ | 36 | string 表示 NFT 名称的共同部分。 |
-- name_length |
~ | 4 | u32 指定名称剩余部分的字节数。 |
-- prefix_uri |
~ | 204 | string 表示 NFT URI 的共同部分。 |
-- uri_length |
~ | 4 | u32 指定 URI 剩余部分的字节数。 |
-- is_sequential |
~ | 1 | 指示铸造索引生成是否连续。 |
- hidden_settings |
~ | 1 | (可选) HiddenSettings |
-- name |
~ | 36 | string 表示 NFT 的名称。 |
-- uri |
~ | 204 | uri 表示 NFT 元数据的 URI。 |
-- hash |
~ | 32 | string 表示包含（铸造索引，NFT 元数据）映射的文件哈希值。 |
| 隐藏部分 | 850 | ~ | (可选) 隐藏数据部分，用于避免不必要的反序列化。此账户部分不由结构体表示，数据通过字节偏移进行存储/检索。当使用 hiddenSettings 时，不存在隐藏数据部分，因为没有必要存储配置行设置。 |
| - items | 850 | 4 | 添加到糖果机的 NFT（项目）数量；最终这将与 items_available 相同。 |
| - config lines | 854 | ~ | 表示每个 NFT 的名称和 URI 对的序列；这些序列的长度由 name_length + uri_length 决定；总共有 items_available * (name + uri) 对。 |
| - byte mask | ~ | ~ | 长度等于 (items_available / 8) + 1 的字节部分，带有二进制标志以指示哪些配置行已被添加。 |
| - mint indices | ~ | ~ | 表示可用铸造索引的 u32 值序列；可用的索引由以下方式确定：如果 is_sequential 为 true，则有效索引从铸造号（《code>items_redeemed）开始；否则，有效铸造索引从偏移量 0 开始，直到由 items_available - items_redeemed 确定的偏移量。 |
| - rule set flag | ~ | 1 | (可选) 一个位，用于指示账户是否包含一组规则（仅适用于 pNFT）。 |
| - 规则集 | ~ | 32 | (可选) 规则集的公钥；此规则集将被添加到新铸造的 pNFT 中。 |
指令
注意 这些指令使用了 Anchor v0.26 对位置可选账户的支持。
📄 add_config_lines
此指令将配置行添加到账户的隐藏数据部分。只有当糖果机具有 config_line_settings 时才能使用。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority |
✅ | 糖果机权限公钥。 |
参数
| 参数 | 偏移量 | 大小 | 描述 |
|---|---|---|---|
索引 |
0 | 4 | 添加行的索引。 |
config_lines |
4 | ~ | 要添加的行的 ConfigLine 对象数组。 |
📄 initialize (已弃用)
此指令创建并初始化一个新的 CandyMachine 账户。在执行此指令之前，必须以预期大小创建 CandyMachine 账户。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority_pda |
✅ | 权限 PDA 密钥（种子 ["candy_machine", candy_machine pubkey]）。 |
|
authority |
糖果机权限公钥。 | ||
payer |
✅ | ✅ | 交易付款人。 |
collection_metadata |
收藏品的元数据账户。 | ||
collection_mint |
收藏品的铸造账户。 | ||
collection_master_edition |
收藏品的主版账户。 | ||
collection_update_authority |
✅ | ✅ | 收藏品的更新权限。 |
collection_authority_record |
✅ | 收藏品的权限记录 PDA。 | |
token_metadata_program |
Metaplex TokenMetadata 程序 ID。 |
||
system_program |
SystemProgram 账户。 |
参数
| 参数 | 偏移量 | 大小 | 描述 |
|---|---|---|---|
数据 |
0 | ~ | CandyMachineData 对象。 |
📄 initialize_v2
此指令创建并初始化一个新的支持多个代币标准的 CandyMachine 账户。在执行此指令之前，必须以预期大小创建 CandyMachine 账户。通过此指令创建的糖果机将设置其 AccountVersion 为 V2。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority_pda |
✅ | 权限 PDA 密钥（种子 ["candy_machine", candy_machine pubkey]）。 |
|
authority |
糖果机权限公钥。 | ||
payer |
✅ | ✅ | 交易付款人。 |
rule_set |
(可选) 要添加到新铸造 NFT 中的规则集。 | ||
collection_metadata |
收藏品的元数据账户。 | ||
collection_mint |
收藏品的铸造账户。 | ||
collection_master_edition |
收藏品的主版账户。 | ||
collection_update_authority |
✅ | ✅ | 收藏品的更新权限。 |
collection_delegate_record |
✅ | Token Metadata 收藏品委托记录 | |
token_metadata_program |
Metaplex TokenMetadata 程序 ID。 |
||
system_program |
SystemProgram 账户。 |
||
sysvar_instructions |
sysvar::instructions 账户。 |
||
authorization_rules_program |
代币授权规则程序。 | ||
authorization_rules |
代币授权规则账户。 |
参数
| 参数 | 偏移量 | 大小 | 描述 |
|---|---|---|---|
数据 |
0 | ~ | CandyMachineData 对象。 |
token_standard |
~ | 1 | u8 指示代币标准（0 = NFT 和 |
📄 mint (已弃用)
此指令从糖果机铸造 NFT。只有铸造权限才能从糖果机中铸造。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority_pda |
✅ | 权限 PDA 密钥（种子 ["candy_machine", candy_machine pubkey]）。 |
|
mint_authority |
✅ | 糖果机铸造权限公钥。 | |
payer |
✅ | ✅ | 交易付款人。 |
nft_mint |
✅ | NFT 的铸造账户。在执行指令之前，应创建此账户。 | |
nft_mint_authority |
✅ | NFT 的铸造权限。 | |
nft_metadata |
✅ | NFT 的元数据账户。 | |
nft_master_edition |
✅ | NFT 的主版账户。 | |
collection_authority_record |
收藏品的权限记录 PDA。 | ||
collection_mint |
收藏品的铸造账户。 | ||
collection_metadata |
✅ | 收藏品的元数据账户。 | |
collection_master_edition |
收藏品的主版账户。 | ||
collection_update_authority |
收藏品的更新权限。 | ||
token_metadata_program |
Metaplex TokenMetadata 程序 ID。 |
||
token_program |
spl-token 程序 ID。 |
||
system_program |
SystemProgram 账户。 |
||
recent_slothashes |
SlotHashes 系统变量集群数据。 |
参数
None。
📄 mint_v2
此指令从糖果机铸造NFT或pNFT。只有铸造权限才能从糖果机中铸造。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority_pda |
✅ | 权限 PDA 密钥（种子 ["candy_machine", candy_machine pubkey]）。 |
|
mint_authority |
✅ | 糖果机铸造权限公钥。 | |
payer |
✅ | ✅ | 交易付款人。 |
nft_owner |
NFT令牌账户所有者。 | ||
nft_mint |
✅ | NFT 的铸造账户。在执行指令之前，应创建此账户。 | |
nft_mint_authority |
✅ | NFT 的铸造权限。 | |
nft_metadata |
✅ | NFT 的元数据账户。 | |
nft_master_edition |
✅ | NFT 的主版账户。 | |
token |
✅ | (可选) NFT令牌账户。 | |
token_record |
✅ | (可选) 元数据TokenRecord账户（铸造pNFT时必需） |
|
collection_delegate_record |
收藏品权限记录PDA（适用于AccountVersion::V1）；元数据收藏品代理（适用于AccountVersion::V2）。 |
||
collection_mint |
收藏品的铸造账户。 | ||
collection_metadata |
✅ | 收藏品的元数据账户。 | |
collection_master_edition |
收藏品的主版账户。 | ||
collection_update_authority |
收藏品的更新权限。 | ||
token_metadata_program |
Metaplex TokenMetadata 程序 ID。 |
||
spl_token_program |
spl-token程序。 |
||
spl_ata_program |
(可选) spl关联令牌程序。 |
||
system_program |
SystemProgram 账户。 |
||
sysvar_instructions |
sysvar::instructions 账户。 |
||
recent_slothashes |
SlotHashes 系统变量集群数据。 | ||
authorization_rules_program |
(可选) 令牌授权规则程序。 | ||
authorization_rules |
(可选) 令牌授权规则账户。 |
参数
None。
📄 set_authority
此指令更改糖果机的权限。请注意，此操作不可逆，一旦更改糖果机的权限，当前权限将失去操作权。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority |
✅ | 糖果机权限公钥。 |
参数
| 参数 | 偏移量 | 大小 | 描述 |
|---|---|---|---|
new_authority |
0 | 32 | 新权限的公钥。 |
📄 set_collection (已弃用)
此指令设置糖果机使用的收藏品。只有在没有铸造NFT的情况下才能更改收藏品。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority |
✅ | 糖果机权限公钥。 | |
authority_pda |
✅ | 权限 PDA 密钥（种子 ["candy_machine", candy_machine pubkey]）。 |
|
payer |
✅ | ✅ | 交易付款人。 |
collection_mint |
当前收藏品的铸造账户。 | ||
collection_metadata |
当前收藏品的元数据账户。 | ||
collection_authority_record |
✅ | 当前收藏品的权限记录PDA。 | |
new_collection_update_authority |
✅ | ✅ | 新收藏品的权限记录PDA。 |
new_collection_metadata |
新收藏品的元数据账户。 | ||
new_collection_mint |
新收藏品的铸造账户。 | ||
new_collection_master_edition |
新收藏品的主版账户。 | ||
new_collection_authority_record |
✅ | 新收藏品的权限记录PDA。 | |
token_metadata_program |
Metaplex TokenMetadata 程序 ID。 |
||
system_program |
SystemProgram 账户。 |
参数
None。
📄 set_collection_v2
此指令设置Candy Machine的AccountVersion::V1或AccountVersion::V2使用的收藏品。只有在没有铸造(p)NFT的情况下才能更改收藏品。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority |
✅ | 糖果机权限公钥。 | |
authority_pda |
✅ | 权限 PDA 密钥（种子 ["candy_machine", candy_machine pubkey]）。 |
|
payer |
✅ | ✅ | 交易付款人。 |
collection_update_authority |
当前收藏品的更新权限账户。 | ||
collection_mint |
当前收藏品的铸造账户。 | ||
collection_metadata |
当前收藏品的元数据账户。 | ||
collection_delegate_record |
✅ | 当前收藏品的元数据代理记录。 | |
new_collection_update_authority |
✅ | ✅ | 新收藏品的权限记录PDA。 |
new_collection_mint |
新收藏品的铸造账户。 | ||
new_collection_metadata |
新收藏品的元数据账户。 | ||
new_collection_master_edition |
新收藏品的主版账户。 | ||
new_collection_delegate_record |
✅ | 新收藏品的元数据代理记录。 | |
token_metadata_program |
Metaplex TokenMetadata 程序 ID。 |
||
system_program |
SystemProgram 账户。 |
||
sysvar_instructions |
sysvar::instructions 账户。 |
||
authorization_rules_program |
(可选) 令牌授权规则程序。 | ||
authorization_rules |
(可选) 令牌授权规则账户。 |
参数
None。
📄 set_mint_authority
此指令更改糖果机的铸造权限。请注意，此操作不可逆，一旦更改糖果机的铸造权限，当前的铸造权限将失去从糖果机中铸造的权利。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority |
✅ | 糖果机权限公钥。 | |
mint_authority |
✅ | 新铸造权限的公钥。 |
参数
None。
📄 set_token_standard
此指令设置糖果机使用的令牌标准和（可选）规则集。它还将更新糖果机账户的版本到V2并设置元数据收藏品代理（而不是权限记录PDA）。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority |
✅ | 糖果机权限公钥。 | |
authority_pda |
✅ | 权限 PDA 密钥（种子 ["candy_machine", candy_machine pubkey]）。 |
|
payer |
✅ | ✅ | 交易付款人。 |
rule_set |
(可选) 要添加到新铸造 NFT 中的规则集。 | ||
collection_delegate_record |
✅ | 当前收藏品的元数据代理记录。 | |
collection_mint |
当前收藏品的铸造账户。 | ||
collection_metadata |
当前收藏品的元数据账户。 | ||
collection_authority_record |
✅ | (可选) 当前收藏品的权限记录PDA。 | |
collection_update_authority |
当前收藏品的更新权限账户。 | ||
token_metadata_program |
Metaplex TokenMetadata 程序 ID。 |
||
system_program |
SystemProgram 账户。 |
||
sysvar_instructions |
sysvar::instructions 账户。 |
||
authorization_rules_program |
(可选) 令牌授权规则程序。 | ||
authorization_rules |
(可选) 令牌授权规则账户。 |
参数
| 参数 | 偏移量 | 大小 | 描述 |
|---|---|---|---|
token_standard |
0 | 1 | u8 指示代币标准（0 = NFT 和 |
📄 update
此指令更新糖果机的配置。对哪些配置可以更新有限制
items_available：只能在使用hidden_settings时更新。hidden_settings：如果items_available的数量大于0，则无法切换到hidden_settings；无法从hidden_settings切换到config_line_settings。name_length和uri_length在config_line_settings中：只能使用小于当前使用值的值进行更新。is_sequential：只有当items_redemmed的数量等于0时，才能修改。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority |
✅ | 糖果机权限公钥。 |
参数
| 参数 | 偏移量 | 大小 | 描述 |
|---|---|---|---|
数据 |
0 | ~ | CandyMachineData 对象。 |
📄 withdraw
此指令将从账户中提取租金 lamports 并关闭它。执行此指令后，Candy Machine 将无法运行。
账户
| 名称 | 可写 | 签名者 | 描述 |
|---|---|---|---|
candy_machine |
✅ | 该 CandyMachine 账户。 |
|
authority |
✅ | ✅ | 糖果机权限公钥。 |
参数
None。
特性
相对于之前的 Candy Machine 程序的主要改进。
账户空间利用率
现在可以定义一个模式来存储 name 和 uri 配置，格式为 prefix_name + name 和 prefix_uri + uri，其中 prefix_name 和 prefix_uri 在所有配置行中共享。这提供了账户空间节省，因为不需要在账户中存储重复的字节，从而有可能创建更大的 Candy Machines 并降低部署成本。
不需要为每条配置行存储完整的 URI（例如，https://arweave.net/yFoNLhe6cBK-wj0n_Wu-XuX7DC75VbMsNKwVbRSz4iQ?ext=png），而是将 prefix_uri 设置为 https://arweave.net/，每条配置行仅存储 uri 空间中的不同值。这也适用于 prefix_name 和 name 对。
当使用具有确定性 URI 生成（例如，AWS S3 和 Shadow Drive）的存储时，通过在 prefix_name 和 prefix_uri 中使用替换模式，可以显著节省空间，从而每个单独的 name 和 uri 都为空。在这种情况下，所需的唯一空间是存储表示随机 mint 索引生成的索引的 id。
$ID$ 或 $ID+1$ 模式可以作为 mint index 或 mint index + 1 自动替换，以生成有效的 URI
https://shdw-drive.genesysgo.net/DCG6qThfZE8xbM72RoFRLwRSrhNVjeWE1gVPPCGvLYSS/$ID$.png在第一个 NFT 铸造时展开为https://shdw-drive.genesysgo.net/DCG6qThfZE8xbM72RoFRLwRSrhNVjeWE1gVPPCGvLYSS/0.png。
这也适用于 prefix_name：当第一个 NFT 铸造时，My NFT #$ID+1$ 展开为 My NFT #1。
带有“自动”揭示的隐藏设置
隐藏设置是创建 Candy Machine 的最有效空间方式，因为不需要在账户上存储配置行。同时，需要在铸造后运行更新元数据程序——称为 揭示 ——来设置铸造的每个 NFT 的元数据中的单独名称和 URI。
当使用具有确定性URI生成的存储时，不需要使用 揭示，因为可以在隐藏设置的 名称 和 uri 字段中使用相同的 $ID$ 或 $ID+1$ 替换模式。
使用具有模式配置行和使用具有模式隐藏设置的差异在于，在前者中，铸造的索引生成是 随机 的，而在后者中，索引生成是 顺序 的。
注意 虽然使用确定性URI可以在不需要为每个NFT运行更新元数据的情况下节省您的工作，但在NFT铸造之前可能确定NFT的URI。为了避免在文件提前公开可访问，可以使用具有相同名称的占位符图像。因此，权衡是在每个NFT上运行元数据更新或更新图像之间。
随机索引生成
目前，随机索引生成使用顺序过程来找到下一个可用的铸造索引。虽然这个过程在大多数情况下都有效，但它效率不高（从计算单元的角度来看），并且在大规模Candy Machine部署中可能会达到计算单元的限制。
新的Candy Machine使用了一种改进的过程，该过程消耗固定数量的计算单元，无论项目数量如何，同时通过洗牌值来提高其不可预测性。
依赖项
~40MB
~673K SLoC