Attribute 插件

Attributes 插件在 Core Asset 或 Collection 中直接在链上存储键值对。非常适合游戏统计数据、特征以及链上程序需要读取的任何数据。

摘要

Attributes 插件是一个权限管理插件，在链上存储键值字符串对。与链下元数据不同，这些属性可被 Solana 程序读取并被 DAS 索引。

• 在链上存储任何字符串键值对
• 可通过 CPI 被链上程序读取
• 自动被 DAS 索引以便快速查询
• 可由更新权限者修改

范围外

链下元数据属性（存储在 URI 的 JSON 中）、复杂数据类型（仅支持字符串）以及不可变属性（所有属性都可修改）。

快速开始

跳转至： 添加到 Asset · 更新属性

1. 添加 Attributes 插件：addPlugin(umi, { asset, plugin: { type: 'Attributes', attributeList: [...] } })
2. 每个属性是一个 { key: string, value: string } 对
3. 随时使用 updatePlugin() 更新
4. 通过 DAS 查询或在链上获取

常见用例

• 游戏角色统计：生命值、经验值、等级、职业 - 游戏过程中变化的数据
• 访问控制：等级、角色、权限 - 程序用于授权检查的数据
• 动态特征：基于操作变化特征的进化 NFT
• 质押状态：跟踪质押状态、已赚取的奖励、质押时间
• 成就追踪：徽章、里程碑、完成状态
• 租赁/借贷：跟踪租赁期限、借用者信息、归还日期

适用于

参数

AttributeList

属性列表由 Array[] 组成，然后是键值对 {key: "value"} 字符串值对的对象。

const attributeList = [
  { key: 'key0', value: 'value0' },
  { key: 'key1', value: 'value1' },
]

向 Asset 添加 Attributes 插件

import { publicKey } from '@metaplex-foundation/umi'
import { addPlugin } from '@metaplex-foundation/mpl-core'
const asset = publicKey('11111111111111111111111111111111')
await addPlugin(umi, {
  asset: asset.publicKey,
  plugin: {
    type: 'Attributes',
    attributeList: [
      { key: 'key0', value: 'value0' },
      { key: 'key1', value: 'value1' },
    ],
  },
}).sendAndConfirm(umi)

更新 Asset 上的 Attributes 插件

import { publicKey } from '@metaplex-foundation/umi'
import { updatePlugin } from '@metaplex-foundation/mpl-core'
const assetAddress = publicKey('11111111111111111111111111111111')
await updatePlugin(umi, {
  asset: assetAddress,
  plugin: {
    type: 'Attributes',
    attributeList: [
      { key: 'key0', value: 'value0' },
      { key: 'key1', value: 'value1' },
    ],
  },
}).sendAndConfirm(umi)

常见错误

Authority mismatch

只有插件权限者（通常是更新权限者）可以添加或更新属性。验证您是否使用正确的密钥对签名。

String too long

属性键和值的大小有限制。请保持简洁。

注意事项

• 权限管理：更新权限者无需所有者签名即可添加/更新
• 所有值都是字符串 - 根据需要转换数字/布尔值
• 更新会替换整个属性列表（不支持部分更新）
• 属性会增加账户大小和租金成本
• DAS 索引属性以便快速查询

快速参考

最少代码

import { addPlugin } from '@metaplex-foundation/mpl-core'
await addPlugin(umi, {
  asset: assetAddress,
  plugin: {
    type: 'Attributes',
    attributeList: [
      { key: 'level', value: '5' },
      { key: 'class', value: 'warrior' },
    ],
  },
}).sendAndConfirm(umi)

常见属性模式

常见问题

链上属性和链下元数据属性有什么区别？

链上属性（此插件）存储在 Solana 上，可被程序读取。链下属性（URI 中的 JSON）存储在 Arweave/IPFS 上，只能被客户端读取。

链上程序能读取这些属性吗？

可以。使用 CPI 获取 Asset 账户并反序列化 Attributes 插件数据。

属性会被 DAS 索引吗？

是的。DAS 会自动索引属性键值对以便快速查询。

可以存储数字或布尔值吗？

值只能是字符串。根据需要进行转换：{ key: 'level', value: '5' }，{ key: 'active', value: 'true' }。

如何更新单个属性？

不能单独更新属性。需要获取当前列表，修改后用完整的新列表进行更新。

属性的大小限制是多少？

没有硬性限制，但较大的属性列表会增加租金成本。请保持数据简洁。

所有者可以更新属性吗？

不可以。Attributes 插件是权限管理的，所以只有更新权限者可以修改它（不是所有者）。

相关插件

• Update Delegate - 授予他人更新属性的权限
• ImmutableMetadata - 锁定名称/URI（属性仍可修改）
• AddBlocker - 防止添加新插件

术语表