Lib.rs

› 密码学 › 神奇豆 › mpl-core
#账户 #机器 #NFT #糖果 #收藏 #铸造 #元数据

mpl-core-candy-machine-core

NFT 糖果机核心：程序化和无需信任的 NFT 释放

所有者 Nhan Phan.

1 个不稳定版本

0.2.1 2024 年 4 月 18 日

#6 in #糖果


用于 mpl-core-candy-guard

自定义许可证

115KB
1K SLoC

Metaplex 糖果机核心（又名 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数量。
数据 CandyMachineData
- items_available 120 8 可用的NFT总数。
- symbol 128 14 表示代币符号的《string》：长度（4字节）+ 符号（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，则有效索引从铸造编号 (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 ✅ The CandyMachine 账户。
authority ✅ 糖果机授权公钥。
参数
参数 偏移量 大小 描述
索引 0 4 添加行的起始索引。
config_lines 4 ~ 表示要添加的行的 ConfigLine 对象数组。

📄 initialize (已弃用)

此指令创建并初始化一个新的 CandyMachine 账户。执行此指令之前，必须使用预期大小创建 CandyMachine 账户。

账户
名称 可写 签名者 描述
candy_machine ✅ The 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 ✅ The 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 Token Authorization Rules 程序。
authorization_rules Token Authorization Rules 账户。
参数
参数 偏移量 大小 描述
数据 0 ~ CandyMachineData 对象。
token_standard ~ 1 u8 表示令牌标准（0 = NFT 和 4 = pNFT）。

📄 mint (已弃用)

此指令从糖果机铸造 NFT。只有铸币授权才能从糖果机铸造。

账户
名称 可写 签名者 描述
candy_machine ✅ The 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 sysvar 集群数据。
参数

None。

📄 mint_v2

此指令从糖果机铸造NFT或pNFT。只有铸造权限才能从糖果机进行铸造。

账户
名称 可写 签名者 描述
candy_machine ✅ The 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 sysvar 集群数据。
authorization_rules_program (可选) 令牌授权规则程序。
authorization_rules (可选) 令牌授权规则账户。
参数

None。

📄 set_authority

此指令更改糖果机的权限。请注意，此操作是不可逆的，一旦更改糖果机的权限，当前权限将失去操作权限。

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

📄 set_collection（已弃用）

此指令设置糖果机使用的集合。只有在没有铸造NFT的情况下，才能更改集合。

账户
名称 可写 签名者 描述
candy_machine ✅ The 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 ✅ The 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 ✅ The CandyMachine 账户。
authority ✅ 糖果机授权公钥。
mint_authority ✅ 新铸造权限的公钥。
参数

None。

📄 set_token_standard

此指令设置糖果机使用的令牌标准以及（可选）规则集。它还将更新糖果机账户的版本到V2，并设置元数据集合代理人（而不是权限记录PDA）。

账户
名称 可写 签名者 描述
candy_machine ✅ The 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

此指令更新糖果机的配置。对哪些配置可以更新有限制

  • 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 ✅ The CandyMachine 账户。
authority ✅ 糖果机授权公钥。
参数
参数 偏移量 大小 描述
数据 0 ~ CandyMachineData 对象。

📄 withdraw

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

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

None。

特性

相对于之前的 Candy Machine 程序的主要改进。

账户空间利用率

现在可以定义一个模式来存储配置中的 name 和 uri，格式为 prefix_name + name 和 prefix_uri + 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 为空，从而实现显著的空间节省。在这种情况下，所需的空间仅用于存储表示随机 mint 索引的索引。

前缀 prefix_uri 可以包含 $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生成的存储时，不需要使用 reveal，因为可以在隐藏设置的 name 和 uri 字段中使用相同的 $ID$ 或 $ID+1$ 替换模式。

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

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

随机索引生成

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

新的Candy Machine使用改进的程序，该程序消耗固定数量的计算单元，无论物品数量如何，同时通过打乱值来提高其不可预测性。

依赖项

~41MB
~699K SLoC