Lib.rs

› 密码学 › 神奇豆子 › miraplex-candy-machine
#account #machine #collection #nft #mint #candy #metadata

miraplex-candy-machine-core

NFT Candy Machine Core：程序化和无需信任的 NFT 下发

所有者： miracle-land，miralandlabs。

2 个版本 (1 个稳定版)

1.0.4 2023 年 5 月 23 日
1.0.1 2023 年 5 月 24 日
0.1.3 2023 年 5 月 19 日

#11 in #candy


在 2 crates 中使用

自定义许可证

165KB
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 账户关联有两个权限：一个是 authority 权限，另一个是 mint_authority 权限。 authority 权限可以管理糖果机的配置，包括添加配置行（资产）、更新设置、更改权限/铸造权限以及关闭/提款账户。

mint_authority 是唯一可以从糖果机中铸造地址——唯一的要求是有可从中铸造的NFT。糖果机的 authority 权限可以将 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数量。
data 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) 数量；最终这将与 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，则有效索引从铸造编号 (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 ✅ 糖果机权限的公钥。
参数
参数 偏移量 大小 描述
index 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 账户。
参数
参数 偏移量 大小 描述
data 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 代币授权规则账户。
参数
参数 偏移量 大小 描述
data 0 ~ CandyMachineData 对象。
token_standard ~ 1 u8 表示代币标准（0 = NFT 和 4 = pNFT）。

📄 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）的Master Edition账户。
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系统变量集群数据。
参数

无。

📄 mint_v2

此指令从Candy Machine中铸造NFT或pNFT。只有铸造权限才能从Candy Machine中铸造。

账户
名称 可写 签名者 描述
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）的Master Edition账户。
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 (可选) 代币授权规则账户。
参数

无。

📄 set_authority

此指令更改Candy Machine的权限。请注意，此操作是不可逆的，一旦更改Candy Machine的权限，当前权限将失去操作它的权利。

账户
名称 可写 签名者 描述
candy_machine ✅ 的 CandyMachine 账户。
authority ✅ 糖果机权限的公钥。
参数
参数 偏移量 大小 描述
new_authority 0 32 新权限的公钥。

📄 set_collection（已弃用）

此指令设置Candy Machine使用的收藏。只有在没有铸造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 新收藏的Master Edition账户。
new_collection_authority_record ✅ 新收藏的权限记录PDA。
token_metadata_program Metaplex TokenMetadata 程序 ID。
system_program SystemProgram 账户。
参数

无。

📄 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 新收藏的Master Edition账户。
new_collection_delegate_record ✅ 新收藏的元数据委托记录。
token_metadata_program Metaplex TokenMetadata 程序 ID。
system_program SystemProgram 账户。
sysvar_instructions sysvar::instructions 账户。
authorization_rules_program (可选) 代币授权规则程序。
authorization_rules (可选) 代币授权规则账户。
参数

无。

📄 set_mint_authority

此指令更改Candy Machine的铸造权限。请注意，此操作是不可逆的，一旦更改Candy Machine的铸造权限，当前铸造权限将失去从Candy Machine中铸造的权利。

账户
名称 可写 签名者 描述
candy_machine ✅ 的 CandyMachine 账户。
authority ✅ 糖果机权限的公钥。
mint_authority ✅ 新铸造权限的公钥。
参数

无。

📄 set_token_standard

此指令设置Candy Machine使用的代币标准和（可选）规则集。它还将Candy Machine账户的版本更新到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 和 4 = pNFT）。

📄 update

此指令更新Candy Machine的配置。对哪些配置可以更新有限制

  • 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 ✅ 糖果机权限的公钥。
参数
参数 偏移量 大小 描述
data 0 ~ CandyMachineData 对象。

📄 withdraw

此指令会从账户中提取租金lamports并关闭它。执行此指令后，Candy Machine将不再运行。

账户
名称 可写 签名者 描述
candy_machine ✅ 的 CandyMachine 账户。
authority ✅ ✅ 糖果机权限的公钥。
参数

无。

功能

与之前Candy Machine程序相比的主要改进。

账户空间利用率

现在可以定义一个模式，以prefix_name + name和prefix_uri + uri的格式存储name和uri配置，其中prefix_name和prefix_uri在所有配置行中共享。这提供了账户空间节省，因为不需要在账户中存储重复的字节，从而有可能创建更大的Candy Machine并降低部署成本。

而不是为每个配置行存储完整的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为空，可以实现显著的空间节省。在这种情况下，所需的空间仅为存储表示随机铸造索引的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：My NFT #$ID+1$在铸造第一个NFT时展开为My NFT #1。

具有“自动”揭示的隐藏设置

隐藏设置是创建 Candy Machine 最节省空间的方法，因为不需要在账户上存储配置行。同时，在铸造后，运行一个更新元数据的过程——称为 揭示——是必要的，以设置铸造的每个NFT的元数据上的单个名称和URI。

当使用具有确定性URI生成的存储时，由于可以在隐藏设置的 名称 和 uri 字段中使用相同的 $ID$ 或 $ID+1$ 替换模式，因此不需要 揭示。

使用带有模式的配置行与使用带有模式的隐藏设置之间的区别在于，在前者中，铸造的索引生成是 随机的，而在后者中，索引生成是 顺序的。

注意 虽然使用确定性URI可以节省您在不需要为每个NFT运行更新元数据方面的工作，但在铸造之前可以确定NFT的URI。为了避免文件在提前公开访问，可以使用具有相同名称的占位符图像。因此，权衡是在每个NFT上运行更新元数据或更新图像之间。

随机索引生成

目前，随机索引生成使用顺序过程来查找下一个可用的铸造索引。虽然此过程适用于大多数情况，但它效率不高（从计算单元的角度来看），并且可以在大型Candy Machine部署中达到计算单元的限制。

新的Candy Machine使用改进的过程，该过程消耗固定数量的计算单元，无论项目数量多少，同时同时打乱值以提高其不可预测性。

依赖项

~28–38MB
~633K SLoC