Metaplex Candy Guard

💡 更新

从 Candy Guard v0.2.0 版本开始，initialize 和 update 指令的参数序列化逻辑期望一个表示自定义序列化结构的 [u8]。这是为了确保将来添加新的守卫时不会影响客户端。

如果您使用的是 mpl-candy-guard npm 包，可以使用以下方式序列化 CandyMachineData 对象：

import { serialize } from '@metaplex-foundation/mpl-candy-guard';

const data = { ... };
const serializedData = serialize(data);

如果您使用的是 mpl-candy-guard Rust 包，可以使用以下方式序列化 CandyMachineData 结构体：

let data = CandyGuardData { ... };
let mut serialized_data = vec![0; data.size()];
data.save(&mut serialized_data)?;

概述

新的 Candy Guard 程序旨在将 Candy Machine 的访问控制逻辑移除，以处理额外的铸造功能，而 Candy Machine 程序保留其核心铸造功能——NFT 的创建。这不仅提供了清晰的 访问控制 和 铸造逻辑 之间的分离，还提供了一个模块化和灵活的架构，无需修改 Candy Machine 程序即可添加或删除铸造功能。

Candy Guard 上的访问控制封装在代表需要满足的特定规则的个体守卫中，可以启用或禁用。例如，铸造的直播日期表示为 LiveDate 守卫。只有当交易时间在守卫配置的起始时间或之后时，该守卫才满足条件。其他守卫可以验证访问控制的各个方面——例如，确保用户持有特定令牌（令牌门控）。

注意 Candy Guard 程序只能与 Candy Machine Core (Candy Machine V3) 账户一起使用。当 Candy Guard 与 Candy Machine 一起使用时，它成为其铸造权限，铸造只能通过 Candy Guard 完成。

程序如何工作？

糖果守护者程序的主要目的是保存薄荷 守护者 的配置，并在用户从糖果机中铸造之前应用它们。如果所有启用的守护者条件都有效，铸造交易将被转发到糖果机。

当收到铸造交易时，程序执行以下步骤

1. 验证交易是否符合所有启用的守护者。
   • 如果在此点失败任何守护者，交易将受到 BotTax（当 BotTax 守护者启用时）的影响，并且交易将被终止。
2. 在评估所有守护者都有效后，它将在每个守护者上调用 pre_actions 函数。此函数负责执行任何在铸造 之前 的操作（例如，收取铸造费用）。
3. 然后，将交易转发到糖果机程序进行 NFT 铸造。
4. 最后，它将在每个启用的守护者上调用 post_actions 函数。此函数负责执行任何在铸造 之后 的操作（例如，冻结 NFT，更改更新权限）。

守护者 是一个模块化代码片段，可以轻松添加到糖果守护者程序中，为支持特定功能提供极大的灵活性和简单性，而无需直接修改糖果机程序。通过遵循特定的接口支持添加新的守护者，更改被隔离到单个守护者中——例如，每个守护者可以独立创建和修改。这种架构还提供了灵活性，可以在不要求代码更改的情况下启用/禁用守护者，因为每个守护者都有一个启用/禁用“开关”。

糖果守护者程序包含一组可启用/禁用的核心访问控制守护者

• AddressGate：将铸造限制为单个地址
• Allocation：指定一组（守护者集）中铸造的最大数量
• AllowList：使用钱包地址列表来决定谁可以铸造
• BotTax：对无效交易可配置的税费（金额）
• EndDate：确定结束铸造的日期
• FreezeSolPayment：以 SOL 的价格设置铸造，并带有冻结期
• FreezeTokenPayment：以 spl-token 的金额设置铸造，并带有冻结期
• Gatekeeper：验证码集成
• MintLimit：指定每个钱包的铸造数量限制
• NftBurn：将铸造限制为特定收藏的持有人，需要销毁 NFT
• NftGate：将铸造限制为特定收藏的持有人
• NftPayment：将铸造价格设置为指定收藏的 NFT
• ProgramGate：限制可以包含在铸造交易中的程序
• RedeemedAmount：根据已铸造的总金额确定铸造的结束
• SolPayment：以 SOL 的价格设置铸造
• StartDate：确定铸造的开始日期
• ThirdPartySigner：要求在交易上有一个额外的签署者
• TokenBurn：将铸造限制为特定 spl-token 的持有人，需要销毁代币
• TokenGate：将铸造限制为特定 spl-token 的持有人
• TokenPayment：以 spl-token 的金额设置铸造价格

除了这些守护者之外，社区中的优秀团队正在制作具有新和酷检查的守护者程序。以下是一些已创建守护者的团队

• Civic：Civic Pass 守护者（《集成文档》）

账户

糖果守护者配置存储在一个单独的账户中。有关已启用守护者的信息存储在账户的“隐藏”部分，以避免不必要的反序列化。

由于启用的守护者和组数是可变的，所以账户大小在update指令期间动态调整，以适应更新的配置。

指令

📄 initialize

此指令创建并初始化一个新的CandyGuard账户。

📄 mint（已弃用）

此指令从由糖果守护者“包装”的糖果机中铸造NFT。只有当交易成功验证后，它才会转发到糖果机。

📄 mint_v2

此指令从由Candy Guard "包装"的Candy Machine中铸造NFT或pNFT。只有当交易成功验证时，它才会转发到Candy Machine。

📄 route

此指令将交易路由到守卫，允许执行自定义守卫指令。交易可以包括守卫指令所需的任何其他账户。将接收交易和任何其他参数的守卫指定在 RouteArgs 结构中。

📄 unwrap

此指令从Candy Machine中移除Candy Guard，将Candy Machine的铸造权限设置为Candy Machine权限。Candy Gard public key 必须与Candy Machine mint_authority 匹配，才能使此指令成功。

📄 update

此指令更新Candy Guard配置。由于存在灵活数量的守卫和组可以存在，此指令将相应地调整账户大小，要么增加要么减少账户大小。因此，将会有租金费用或租金lamports的提款。

📄 withdraw

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

📄 wrap

本指令为糖果机添加糖果守护者。添加守护者后，只有通过糖果守护者才能进行铸币。

守护者

地址门

pub struct AddressGate {
    address: Pubkey,
}

AddressGate 守护者将铸币限制为单个 address — 该地址必须与铸币事务的付款人地址匹配。

分配

pub struct Allocation {
    pub id: u8,
    pub size: u16,
}

Allocation 守护者指定一组（守护者集）中允许的最大铸币数量。 id 配置代表分配的唯一标识 — 更改 id 会重置限制，因为将创建不同的跟踪账户。 size 指示分配的最多铸币数量。

路由指令

在验证第一个铸币事务之前，需要创建分配 PDA。这通过具有以下账户和 RouteArgs 的 route 指令来完成。

允许列表

pub struct AllowList {
    pub merkle_root: [u8; 32],
}

AllowList 守护者通过基于 Merkle 树的地址允许列表验证付款人地址。它需要一个 Merkle 树的根作为配置，并且铸币事务必须包含 Merkle 证明的 PDA。如果没有指定证明，事务将失败。

路由指令

必须在铸币事务之前完成 Merkle 证明验证。这通过以下账户和 RouteArgs 的 route 指令来完成。

机器人税

pub struct BotTax {
    pub lamports: u64,
    pub last_instruction: bool,
}

BotTax 守护者用于

• 对无效交易征收罚款。罚款金额由 lamports 配置指定。
• 验证铸币事务是最后一个交易（last_instruction = true）。

当验证守护者时发生的任何错误都将应用 bot_tax。

结束日期

pub struct EndDate {
    pub date: i64,
}

EndDate 守护者用于指定铸币结束的日期。任何在结束日期之后接收到的交易都将失败。

FreezeSolPayment

pub struct FreezeSolPayment {
    pub lamports: u64,
    pub destination: Pubkey,
}

FreezeSolPayment 守卫用于在冻结期间对铸币收取一定数量的 SOL（lamports）。资金将被转入冻结托管账户，直到所有 NFT 解冻，此时可以（解锁）转移到目标账户。

注意：在开始铸币之前，必须使用 initialize 路由指令初始化冻结功能。

路由指令

initialize：初始化冻结托管 PDA。

thaw：解冻符合条件的 NFT。

unlock_funds：解锁冻结资金。

只有当所有冻结的 NFT 都解冻后，才能启用解锁资金。

FreezeTokenPayment

pub struct FreezeTokenPayment {
    pub amount: u64,
    pub mint: Pubkey,
    pub destination_ata: Pubkey,
}

FreezeTokenPayment 守卫用于使用指定 spl-token 收取铸币的金额，并带有冻结期。资金将被转入冻结托管账户，直到所有 NFT 解冻，此时可以（解锁）转移到目标账户。

注意：在开始铸币之前，必须使用 initialize 路由指令初始化冻结功能。

路由指令

initialize：初始化冻结托管 PDA。

thaw：解冻符合条件的 NFT。

unlock_funds：解锁冻结资金。

只有当所有冻结的 NFT 都解冻后，才能启用解锁资金。

门卫

pub struct Gatekeeper {
    pub gatekeeper_network: Pubkey,
    pub expire_on_use: bool,
}

门卫守卫验证交易付款人是否具有指定网关网络（通常是完成验证码挑战后的 令牌）。expire_on_use 配置用于指示令牌在铸造后是否应该过期。

MintLimit

pub struct MintLimit {
    pub id: u8,
    pub limit: u16,
}

MintLimit 守卫允许为每个地址指定铸造次数的限制。配置中的 id 表示限制的唯一标识符——更改 id 的效果是重新启动限制，因为将创建不同的跟踪账户。指示的 limit 表示允许的最大铸造次数。

NftBurn

pub struct NftBurn {
    pub required_collection: Pubkey,
}

NftBurn 守卫限制铸造仅限于持有另一个 NFT（令牌）的持有人，要求 NFT 在允许铸造时被烧毁。

NftGate

pub struct NftGate {
    pub required_collection: Pubkey,
}

NftGate 守卫限制铸造仅限于持有指定 required_collection NFT 收藏的持有人。付款人必须至少持有该收藏中的一个 NFT。

NftPayment

pub struct NftPayment {
    pub required_collection: Pubkey,
    pub destination: Pubkey,
}

NftPayment 守卫是一种支付守卫，它要求为铸造从特定收藏中收取另一个 NFT（令牌）。作为铸造的要求，指定的 NFT 被转移到配置的 destination 地址。

ProgramGate

pub struct ProgramGate {
    pub additional: Vec<Pubkey>,
}

ProgramGate 守卫限制可以出现在铸造交易中的程序。守卫允许铸造所需的程序以及配置中指定的任何其他程序。

RedeemedAmount

pub struct RedeemedAmount {
    pub maximum: u64,
}

RedeemedAmount 守卫在 Candy Machine 的 items_redeemed 数量达到配置的 maximum 数量时停止铸造。

SolPayment

pub struct SolPayment {
    pub lamports: u64,
    pub destination: Pubkey,
}

SolPayment 守卫用于对铸造收取 SOL（拉姆波特）金额。资金被转移到配置的 destination 地址。

StartDate

pub struct StartDate {
    pub date: i64,
}

StartDate 守卫确定铸造的开始日期。如果没有指定此守卫，则允许铸造——类似于说任何日期都是有效的。

ThirdPartySigner

pub struct ThirdPartySigner {
    pub signer_key: Pubkey,
}

ThirdPartySigner 守卫要求在交易中添加额外签名者。

TokenBurn

pub struct TokenBurn {
    pub amount: u64,
    pub mint: Pubkey,
}

TokenBurn 限制了代币铸造只能由持有特定 spl-token 的用户进行，并要求销毁这些代币。amount 决定了需要销毁多少代币。

TokenGate

pub struct TokenGate {
    pub amount: u64,
    pub mint: Pubkey,
}

TokenGate 限制了代币铸造只能由持有特定 spl-token 的用户进行。 amount 决定了需要多少代币。

TokenPayment

pub struct TokenPayment {
    pub amount: u64,
    pub token_mint: Pubkey,
    pub destination_ata: Pubkey,
}

TokenPayment 限制了代币铸造只能由持有特定 spl-token 的用户进行，并将所需数量的代币转移到 destination_ata 地址。 amount 决定了需要多少代币。