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 完成。

程序如何工作？

Candy Guard 程序的主要目的是在用户从糖果机铸造之前，持有铸造 守卫 的配置并应用它们。如果所有启用的守卫条件都有效，则铸造事务将被转发到 Candy Machine。

收到铸造事务时，程序执行以下步骤

1. 对事务进行所有启用的守卫的验证。
   • 如果在此点守卫失败，则事务将受到 BotTax (当启用 BotTax 守卫时) 的影响，并将终止事务。
2. 在验证所有守卫都有效后，它将在每个守卫上调用 pre_actions 函数。此函数负责在铸造之前执行任何操作（例如，为铸造收取付款）。
3. 然后，事务被转发到 Candy Machine 程序以铸造 NFT。
4. 最后，它将在每个启用的守卫上调用 post_actions 函数。此函数负责在铸造之后执行任何操作（例如，冻结 NFT，更改更新权限）。

守卫 是一个模块化代码块，可以轻松添加到 Candy Guard 程序中，提供极大的灵活性和简单性，以支持特定功能而无需直接修改 Candy Machine 程序。通过遵循特定接口添加新守卫是支持的，更改仅限于单个守卫 - 例如，每个守卫可以单独创建和修改。此架构还提供了灵活性，可以在不要求代码更改的情况下启用/禁用守卫，因为每个守卫都有一个启用/禁用 "开关"。

Candy Guard 程序包含一组可启用/禁用的核心访问控制守卫

• 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 金额设置铸造价格

随着这些守卫程序的推出，社区中的优秀团队也在开发新的、酷炫的检查机制。以下是几个创建守卫程序的团队：

• 公民：公民通行证守卫程序（集成文档）

账户

Candy Guard的配置存储在单个账户中。启用的守卫相关信息存储在账户的“隐藏”部分，以避免不必要的反序列化。

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

指令

📄 initialize

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

📄 mint（已弃用）

此指令从由Candy Guard“包装”的Candy Machine中铸造NFT。只有在交易成功验证后，才会将其转发到Candy Machine。

📄 mint_v2

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

📄 route

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

📄 unwrap

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

📄 update

此指令更新Candy Guard配置。由于存在可变数量的守卫和组，此指令将相应地调整账户大小，无论是增加还是减少账户大小。因此，可能会有租金费用或租金lamports的提取。

📄 withdraw

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

📄 wrap

此指令向Candy Machine添加Candy Guard。添加守卫后，只能通过Candy Guard进行铸币。

守卫

AddressGate

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指令完成的：

BotTax

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

的BotTax守卫用于

• 对无效交易收取罚款。罚款的价值由的lamports配置指定。
• 验证铸造交易是否是最后一条交易（last_instruction = true）。

bot_tax应用于在验证守卫时发生的任何错误。

EndDate

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,
}

Gatekeeper 守卫验证交易付款人是否拥有指定网关网络的 代币 —— 在大多数情况下，完成验证码挑战后的 代币。使用 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 守卫限制 mint 交易中可以使用的程序。守卫允许 mint 所需的必要程序以及配置中指定的任何其他程序。

RedeemedAmount

pub struct RedeemedAmount {
    pub maximum: u64,
}

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

SolPayment

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

《SolPayment》守卫用于为铸造支付SOL（lamports）金额。资金将转移到配置的《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》确定需要多少代币。