在Anchor中使用Metaplex Core

使用Anchor构建与Core Asset交互的链上程序。本指南涵盖安装、账户反序列化、插件访问和CPI模式。

摘要

mpl-core Rust crate提供了从Anchor程序与Core交互所需的一切。启用anchor功能标志以进行原生Anchor账户反序列化。

• 添加default-features = false和适当的Anchor功能的mpl-core
• 与anchor-lang 0.32.x一起使用features = ["anchor", "anchor-0-32"]
• 与anchor-lang 0.31.x一起使用features = ["anchor"]
• 在Accounts结构体中反序列化Asset/Collection
• 使用fetch_plugin()读取插件数据
• CPI构建器简化指令调用

范围外

客户端JavaScript SDK（参见JavaScript SDK）、独立Rust客户端（参见Rust SDK）以及从客户端创建Core Asset。

快速入门

跳转到： 安装 · 账户反序列化 · 插件访问 · CPI示例

1. 在Cargo.toml中添加带有default-features = false和Anchor功能的mpl-core
2. 在rust-toolchain.toml中固定Rust 1.89.0或更高版本
3. 使用Account<'info, BaseAssetV1>反序列化Asset
4. 使用fetch_plugin::<BaseAssetV1, PluginType>()访问插件
5. 使用CreateV2CpiBuilder、TransferV1CpiBuilder等进行CPI调用

安装

将mpl-core添加到Anchor程序的Cargo.toml中。默认的borsh-v1功能与Anchor集成不兼容，因此启用anchor时必须禁用默认功能。

功能标志

Anchor 0.32.x（推荐）

当程序依赖anchor-lang 0.32.x时使用：

[dependencies]
anchor-lang = "0.32.1"
mpl-core = { version = "x.x.x", default-features = false, features = ["anchor", "anchor-0-32"] }

Anchor 0.31.x（旧版）

当程序依赖anchor-lang 0.31.x时使用：

[dependencies]
anchor-lang = "0.31.1"
mpl-core = { version = "x.x.x", default-features = false, features = ["anchor"] }

Rust工具链

mpl-core需要Rust 1.89.0或更高版本。在Anchor工作区中添加rust-toolchain.toml文件：

[toolchain]
channel = "1.89.0"

如果构建因base64ct等传递依赖出现edition2024错误，请升级到Rust 1.89.0或更高版本。

Core Rust SDK模块

Core Rust SDK组织成几个模块：

• accounts：表示程序的账户。
• errors：枚举程序的错误。
• instructions：促进指令、指令参数和CPI指令的创建。
• types：表示程序使用的类型。 有关如何调用和使用不同指令的更多详细信息，请参阅mpl-core docs.rs网站，或者您可以在指令上使用cmd + 左键点击（mac）或ctrl + 左键点击（windows）来展开它。

账户反序列化

可反序列化的账户

mpl-core crate中可用于反序列化的账户结构体如下：

- BaseAssetV1
- BaseCollectionV1
- HashedAssetV1
- PluginHeaderV1
- PluginRegistryV1

在Anchor中有两种反序列化Core账户的方法。

• 使用Anchor的Account列表结构体（大多数情况下推荐），
• 使用<Account>::from_bytes()直接在指令函数体中。

Anchor Accounts列表方法

通过激活anchor标志，您将能够直接在Anchor Accounts列表结构体中反序列化BaseAssetV1和BaseCollectionV1账户：

#[derive(Accounts)]
pub struct ExampleAccountStruct<'info> {
    ...
    pub asset: Account<'info, BaseAssetV1>,
}

Account from_bytes()方法

使用try_borrow_data()函数借用asset/collection账户内的数据，并从这些字节创建asset/collection结构体：

let data = ctx.accounts.asset.try_borrow_data()?;
let base_asset: BaseAssetV1 = BaseAssetV1::from_bytes(&data.as_ref())?;

插件反序列化

要访问Asset或Collection账户中的单个插件，请使用fetch_plugin()函数。此函数将返回插件数据或null响应而不抛出硬错误，允许您检查插件是否存在而无需访问其数据。 fetch_plugin()函数用于Asset和Collection账户，并且可以通过指定适当的类型来处理每种插件类型。如果要访问插件内的数据，请使用此函数返回的中间值。

let (_, attribute_list, _) = fetch_plugin::<BaseAssetV1, Attributes>(&ctx.accounts.asset.to_account_info(), mpl_core::types::PluginType::Attributes)?;

注意：fetch_plugin()函数仅用于非外部插件。要读取外部插件，请使用fetch_external_plugin()函数，其操作方式与fetch_plugin()相同。

CPI指令构建器

Core crate的每个指令都有一个CpiBuilder版本。CpiBuilder版本使用指令名称 + CpiBuilder创建，通过抽象大量样板代码来显著简化代码！ 如果您想了解更多关于Core中所有可用指令的信息，可以在mpl-core docs.rs网站上找到它们。

CPI示例

以CreateCollectionV2CpiBuilder指令为例。 通过在CpiBuilder上调用new并将core程序作为AccountInfo传入来初始化构建器：

CreateCollectionV2CpiBuilder::new(ctx.accounts.mpl_core_program.to_account_info);

然后使用Cmd + 左键点击（Windows用户使用Ctrl + 左键点击）查看此CPI调用所需的所有CPI参数：

CreateCollectionV2CpiBuilder::new(&ctx.accounts.core_program)
    .collection(&ctx.accounts.collection)
    .payer(&ctx.accounts.payer)
    .system_program(&ctx.accounts.system_program)
    .name("Test Collection".to_string())
    .uri("https://test.com".to_string())
    .invoke()?;

常见错误

AccountNotInitialized

Asset或Collection账户不存在或尚未创建。

PluginNotFound

您尝试获取的插件在Asset上不存在。使用安全返回None的fetch_plugin()检查。

InvalidAuthority

签名者没有此操作的权限。验证正确的authority正在签名。

注意事项

• 启用Anchor功能时始终设置default-features = false
• 与anchor-lang 0.32.x一起使用features = ["anchor", "anchor-0-32"]
• 与anchor-lang 0.31.x一起使用features = ["anchor"]
• 在rust-toolchain.toml中固定Rust 1.89.0或更高版本
• 对于内置插件使用fetch_plugin()，对于外部插件使用fetch_external_plugin()
• CPI构建器抽象了账户排序的复杂性
• 查看docs.rs/mpl-core获取完整的API参考

快速参考

常见CPI构建器

账户类型

常见问题

我需要anchor功能标志吗？

是的，对于Accounts结构体中的直接反序列化需要。没有它，请手动使用from_bytes()。启用anchor时始终设置default-features = false。

应该使用哪个Anchor版本？

对于anchor-lang 0.32.x，使用default-features = false和features = ["anchor", "anchor-0-32"]。对于anchor-lang 0.31.x，仅使用features = ["anchor"]。

需要什么Rust版本？

mpl-core需要Rust 1.89.0或更高版本。在Anchor项目中通过rust-toolchain.toml固定版本。

如何检查插件是否存在？

使用返回Option的fetch_plugin() - 如果插件不存在，它不会抛出错误。

我可以访问外部插件（Oracle、AppData）吗？

可以。使用fetch_external_plugin()而不是fetch_plugin()，并使用适当的key。

在哪里可以找到所有可用的指令？

请参阅mpl-core docs.rs指令模块。

术语表

相关页面

• Anchor质押示例 - 完整的质押程序
• 使用Anchor创建Asset - 分步指南
• Rust SDK - 独立Rust客户端使用
• mpl-core docs.rs - 完整API参考