Metaplex

插件

Royalties Plugin

Last updated January 31, 2026

Royalties Plugin 在 Core Assets 的二次销售中强制执行创作者版税。它指定版税百分比、创作者分成，以及哪些程序（市场）被允许或禁止转移资产。

您将学到

如何：

  • 为 Assets 和 Collections 添加版税
  • 配置基点和创作者分成
  • 设置白名单和黑名单以控制市场访问
  • 创建后更新版税

概述

Royalties Plugin 是一个由 Authority 管理的 Plugin，用于在 Core Assets 上强制执行版税。设置百分比（基点），分配给多个创作者，并可选择限制哪些程序可以转移资产。

  • 将版税设置为基点（500 = 5%）
  • 在最多 5 个创作者之间分配版税
  • 使用白名单/黑名单控制市场访问
  • 应用于 Asset 级别（单个）或 Collection 级别（所有资产）

不在范围内

Token Metadata 版税（不同的系统）、版税收取/分配（由市场处理）以及版税的法律强制执行。

快速开始

跳转到： 添加到 Asset · 添加到 Collection · RuleSets · 更新

  1. 从 @metaplex-foundation/mpl-core 导入 addPlugin
  2. 使用 type: 'Royalties'、basisPoints、creators 和 ruleSet 调用
  3. 市场读取 Plugin 并在销售时强制执行版税

适用于

账户类型支持
MPL Core Asset是
MPL Core Collection是
当同时应用于 Asset 和其 Collection 时，Asset 级别的 Plugin 优先。

参数

参数类型描述
basisPointsnumber版税百分比（500 = 5%，1000 = 10%）
creatorsCreator[]创作者地址及其百分比份额的数组
ruleSetRuleSet程序白名单、黑名单或无

基点

版税百分比以百分之一的百分比表示。

基点百分比
1001%
2502.5%
5005%
100010%
示例：如果 basisPoints 为 500，Asset 以 1 SOL 出售，创作者总共获得 0.05 SOL。

Creators

creators 数组定义谁接收版税以及如何分配。最多支持 5 个创作者。百分比必须加起来等于 100。

Creators 数组

creators-array.ts
import { publicKey } from '@metaplex-foundation/umi'

const creators = [

  { address: publicKey('11111111111111111111111111111111'), percentage: 80 },

  { address: publicKey('22222222222222222222222222222222'), percentage: 20 },

]

RuleSets

RuleSets 控制哪些程序可以转移带有版税的 Assets。使用它们通过限制转移到合规市场来强制执行版税。

None（无限制）

任何程序都可以转移资产。版税仅为建议性质。

RuleSet None

ruleset-none.ts
import { ruleSet } from '@metaplex-foundation/mpl-core'

const rules = ruleSet('None')

Allowlist（推荐用于强制执行）

只有列表中的程序才能转移。使用此选项限制为符合版税的市场。

RuleSet Allowlist

ruleset-allowlist.ts
import { publicKey } from '@metaplex-foundation/umi'

import { ruleSet } from '@metaplex-foundation/mpl-core'

const rules = ruleSet('ProgramAllowList', [

  [

    publicKey('M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K'), // Magic Eden

    publicKey('TSWAPaqyCSx2KABk68Shruf4rp7CxcNi8hAsbdwmHbN'), // Tensor

  ],

])

Denylist

除列表中的程序外，所有程序都可以转移。用于阻止已知的不合规市场。

RuleSet DenyList

ruleset-denylist.ts
import { publicKey } from '@metaplex-foundation/umi'

import { ruleSet } from '@metaplex-foundation/mpl-core'

const rules = ruleSet('ProgramDenyList', [

  [

    publicKey('BadMarketplace111111111111111111111111111'),

  ],

])

将 Royalties Plugin 添加到 Asset（代码示例）

将 Royalties Plugin 添加到 Asset

add-royalties-to-asset.ts
import { publicKey } from '@metaplex-foundation/umi'

import { addPlugin, ruleSet } from '@metaplex-foundation/mpl-core'

const creator1 = publicKey('11111111111111111111111111111111')

const creator2 = publicKey('22222222222222222222222222222222')

await addPlugin(umi, {

  asset: assetAddress,

  plugin: {

    type: 'Royalties',

    basisPoints: 500, // 5%

    creators: [

      { address: creator1, percentage: 80 },

      { address: creator2, percentage: 20 },

    ],

    ruleSet: ruleSet('None'),

  },

}).sendAndConfirm(umi)

将 Royalties Plugin 添加到 Collection（代码示例）

Collection 级别的版税适用于 Collection 中的所有 Assets，除非在 Asset 级别被覆盖。

将 Royalties Plugin 添加到 Collection

add-royalties-to-collection.ts
import { publicKey } from '@metaplex-foundation/umi'

import { addCollectionPlugin, ruleSet } from '@metaplex-foundation/mpl-core'

const creator1 = publicKey('11111111111111111111111111111111')

const creator2 = publicKey('22222222222222222222222222222222')

await addCollectionPlugin(umi, {

  collection: collectionAddress,

  plugin: {

    type: 'Royalties',

    basisPoints: 500, // 5%

    creators: [

      { address: creator1, percentage: 80 },

      { address: creator2, percentage: 20 },

    ],

    ruleSet: ruleSet('None'),

  },

}).sendAndConfirm(umi)

更新 Asset 上的 Royalties Plugin

修改现有 Asset 上的版税百分比、创作者或规则集。

更新 Asset 上的 Royalties Plugin

update-royalties-asset.ts
import { publicKey } from '@metaplex-foundation/umi'

import { updatePlugin, ruleSet } from '@metaplex-foundation/mpl-core'

await updatePlugin(umi, {

  asset: assetAddress,

  plugin: {

    type: 'Royalties',

    basisPoints: 750, // Updated to 7.5%

    creators: [

      { address: creator1, percentage: 60 },

      { address: creator2, percentage: 40 },

    ],

    ruleSet: ruleSet('ProgramAllowList', [[marketplace1, marketplace2]]),

  },

}).sendAndConfirm(umi)

更新 Collection 上的 Royalties Plugin

更新 Collection 上的 Royalties Plugin

update-royalties-collection.ts
import { publicKey } from '@metaplex-foundation/umi'

import { updateCollectionPlugin, ruleSet } from '@metaplex-foundation/mpl-core'

await updateCollectionPlugin(umi, {

  collection: collectionAddress,

  plugin: {

    type: 'Royalties',

    basisPoints: 600, // Updated to 6%

    creators: [

      { address: creator1, percentage: 70 },

      { address: creator2, percentage: 30 },

    ],

    ruleSet: ruleSet('None'),

  },

}).sendAndConfirm(umi)

常见错误

Creator percentages must sum to 100

创作者百分比值加起来不等于 100。调整分配比例。

Authority mismatch

只有 Plugin Authority 可以更新版税。确保您使用正确的密钥对签名。

Program not in allowlist

转移被阻止，因为调用程序不在白名单中。添加该程序或切换到黑名单/无规则集。

注意事项

  • Asset 级别的版税覆盖 Collection 级别的版税
  • 创作者百分比必须正好加起来等于 100
  • 使用白名单进行严格执行，黑名单提供灵活性
  • 版税收取/分配由市场处理，而不是 Core 程序

快速参考

最小代码

minimal-royalties.ts
import { addPlugin, ruleSet } from '@metaplex-foundation/mpl-core'

await addPlugin(umi, {

  asset: assetAddress,

  plugin: {

    type: 'Royalties',

    basisPoints: 500,

    creators: [{ address: creatorAddress, percentage: 100 }],

    ruleSet: ruleSet('None'),

  },

}).sendAndConfirm(umi)

基点参考

期望百分比基点
2.5%250
5%500
7.5%750
10%1000

常见问题

Core 版税是强制执行的吗？

是的，当使用白名单规则集时。只有白名单中的程序才能转移资产，确保版税得到支付。

Core 版税和 Token Metadata 版税有什么区别？

Core 版税需要在 Asset 或 Collection 级别使用 Royalties Plugin，并可选择通过规则集强制执行。标准 Token Metadata NFT 版税仅为建议性质，依赖市场的配合。pNFTs（可编程 NFT）也支持类似于 Core 的基于规则集的强制执行。

我可以为 Collection 中的每个 Asset 设置不同的版税吗？

可以。将 Royalties Plugin 添加到单个 Asset 即可覆盖 Collection 级别的设置。

市场如何读取版税信息？

市场通过 DAS 或链上数据查询 Asset 的 Plugin。Royalties Plugin 数据包括基点、创作者和规则集。

如果我不设置规则集会怎样？

使用 ruleSet('None')。任何程序都可以转移资产，版税仅为建议性质。

铸造后可以更改版税吗？

可以。如果您有权限，可以使用 updatePlugin（用于 Assets）或 updateCollectionPlugin（用于 Collections）。

术语表

术语定义
Basis Points以百分之一表示的版税百分比（500 = 5%）
Creators接收版税付款的地址数组
RuleSet控制哪些程序可以转移的白名单/黑名单
Allowlist只有列出的程序可以转移（严格执行）
Denylist除列出的程序外所有程序都可以转移
Authority被允许更新 Plugin 的账户
Next
Update Delegate Plugin