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 crate，可以使用以下方式序列化 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进行。

程序是如何工作的？

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数量中的价格

除了这些守卫之外，社区中的出色团队正在制作带有新酷检查的守卫程序。以下是一些创建守卫的团队

• Civic：Civic Pass Guard (集成文档)

账户

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

此指令从糖果机中移除糖果守卫，将糖果机的铸造权限设置为糖果机权限。为了使此指令成功，糖果守卫的公钥必须与糖果机 mint_authority 匹配。

📄 update

此指令更新糖果守卫配置。由于存在可灵活调整数量的守卫和组，此指令将相应地调整账户大小，要么增加要么减少账户大小。因此，将收取租金费用或退还租金兰波特。

📄 withdraw

此指令从账户中提取租金兰波特并关闭它。执行此指令后，糖果守卫账户将无法运行。

📄 wrap

此指令向糖果机添加糖果守卫。在守卫添加后，只有通过糖果守卫才能进行铸造。

守卫

AddressGate

pub struct AddressGate {
    address: Pubkey,
}

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

分配

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

Allocation 守卫指定组（守卫集）中允许的铸造最大数量。配置中的 id 代表分配的唯一标识符——更改 id 的效果是重新启动限制，因为将创建不同的跟踪账户。大小表示分配的最大铸造数量。

路由指令

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

AllowList

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

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

路由指令

在铸造交易之前需要完成默克尔证明的验证。这是通过具有以下账户和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解冻后启用。

冻结代币支付

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

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

铸造计数

NftBurn守卫限制铸造仅限于其他NFT（代币）的持有者，要求在允许铸造时烧毁NFT。

pub struct NftBurn {
    pub required_collection: Pubkey,
}

nft_account

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

《code>ProgramGate 保护器限制了可以在铸造交易中存在的程序。保护器允许铸造所需的程序以及配置中指定的任何其他程序。

RedeemedAmount

pub struct RedeemedAmount {
    pub maximum: u64,
}

《code>RedeemedAmount 保护器在Candy Machine的《code>items_redeemed数量达到配置的《code>maximum数量时停止铸造。

SolPayment

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

《code>SolPayment 保护器用于对铸造收取一定数量的SOL（lamports）。资金将转移到配置的《code>destination地址。

StartDate

pub struct StartDate {
    pub date: i64,
}

《code>StartDate 保护器确定铸造的开始日期。如果没有指定此保护器，则允许铸造——类似于说任何日期都有效。

ThirdPartySigner

pub struct ThirdPartySigner {
    pub signer_key: Pubkey,
}

《code>ThirdPartySigner 保护器需要在交易中添加额外的签名者。

TokenBurn

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

《code>TokenBurn 限制了铸造只能由指定的spl-token持有者进行，并要求烧毁这些令牌。《code>amount 决定了需要多少令牌。

TokenGate

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

《code>TokenGate 限制了铸造只能由指定的spl-token持有者进行。《code>amount 决定了需要多少令牌。

TokenPayment

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

《code>TokenPayment 限制了铸造只能由指定的spl-token持有者进行，并将所需数量转移到《code>destination_ata地址。《code>amount 决定了需要多少令牌。