Metaplex

プラグイン

Royalties Plugin

Last updated January 31, 2026

Royalties Pluginは、Core Assetの二次販売においてクリエイターロイヤリティを強制します。ロイヤリティの割合、クリエイター分配、およびどのプログラム（マーケットプレイス）がAssetの転送を許可または拒否されるかを指定します。

学習内容

以下の方法を学びます：

  • AssetとCollectionにロイヤリティを追加する
  • Basis Pointとクリエイター分配を設定する
  • マーケットプレイス制御のためのAllowlistとDenylistを設定する
  • 作成後にロイヤリティを更新する

概要

Royalties Pluginは、Core Assetにロイヤリティを強制するAuthority管理のPluginです。割合（Basis Point）を設定し、複数のクリエイターに分配し、オプションでどのプログラムがAssetを転送できるかを制限できます。

  • Basis Pointでロイヤリティを設定（500 = 5%）
  • 最大5人のクリエイター間でロイヤリティを分配
  • Allowlist/Denylistを使用してマーケットプレイスアクセスを制御
  • Assetレベル（個別）またはCollectionレベル（全Asset）に適用

範囲外

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プログラムのAllowlist、Denylist、またはなし

Basis Points

ロイヤリティの割合を100分の1パーセントで表します。

Basis Pointsパーセンテージ
1001%
2502.5%
5005%
100010%
例：basisPointsが500で、Assetが1 SOLで売却された場合、クリエイターは合計0.05 SOLを受け取ります。

Creators

Creators配列は、誰がロイヤリティを受け取り、どのように分配されるかを定義します。最大5人のクリエイターがサポートされています。パーセンテージの合計は100である必要があります。

Creators Array

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

const creators = [

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

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

]

RuleSets

RuleSetsは、ロイヤリティ付きのAssetをどのプログラムが転送できるかを制御します。準拠したマーケットプレイスへの転送を制限することで、ロイヤリティを強制するために使用します。

None（制限なし）

任意のプログラムがAssetを転送できます。ロイヤリティは推奨事項のみです。

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'),

  ],

])

AssetへのRoyalties Pluginの追加（コード例）

Add Royalties Plugin to 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)

CollectionへのRoyalties Pluginの追加（コード例）

CollectionレベルのロイヤリティはCollection内のすべてのAssetに適用されますが、Assetレベルで上書きされない限りです。

Add Royalties Plugin to 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のロイヤリティ割合、クリエイター、またはRuleSetを変更します。

Update Royalties Plugin on Asset

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の更新

Update Royalties Plugin on Collection

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

呼び出しプログラムがAllowlistにないため、転送がブロックされました。プログラムを追加するか、Denylist/None RuleSetに切り替えてください。

注意事項

  • AssetレベルのロイヤリティはCollectionレベルのロイヤリティを上書きします
  • クリエイターのパーセンテージは正確に合計100である必要があります
  • 厳格な強制にはAllowlistを、柔軟性にはDenylistを使用
  • ロイヤリティの収集/分配は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)

Basis Pointsリファレンス

希望%Basis Points
2.5%250
5%500
7.5%750
10%1000

FAQ

Coreのロイヤリティは強制されますか？

はい、Allowlist RuleSetを使用する場合に強制されます。Allowlistに含まれるプログラムのみがAssetを転送でき、ロイヤリティの支払いが保証されます。

CoreのロイヤリティとToken Metadataのロイヤリティの違いは何ですか？

CoreのロイヤリティはAssetまたはCollectionレベルでRoyalties Pluginが必要で、RuleSetによるオプションの強制があります。標準のToken Metadata NFTロイヤリティは推奨事項であり、マーケットプレイスの協力に依存します。pNFT（プログラマブルNFT）もCoreと同様のRuleSetベースの強制をサポートしています。

Collection内のAssetごとに異なるロイヤリティを設定できますか？

はい。個別のAssetにRoyalties Pluginを追加することで、Collectionレベルの設定を上書きできます。

マーケットプレイスはどのようにロイヤリティを読み取りますか？

マーケットプレイスはDASまたはオンチェーンデータを通じてAssetのPluginを照会します。Royalties Pluginのデータには、Basis Point、クリエイター、RuleSetが含まれます。

RuleSetを設定しない場合はどうなりますか？

ruleSet('None')を使用してください。任意のプログラムがAssetを転送でき、ロイヤリティは推奨事項のみとなります。

ミント後にロイヤリティを変更できますか？

はい。Authorityがあれば、updatePlugin（Asset用）またはupdateCollectionPlugin（Collection用）を使用できます。

用語集

用語定義
Basis Pointsロイヤリティの割合を100分の1で表したもの（500 = 5%）
Creatorsロイヤリティの支払いを受け取るアドレスの配列
RuleSetどのプログラムが転送できるかを制御するAllowlist/Denylist
Allowlistリストにあるプログラムのみが転送可能（厳格な強制）
Denylistリストにあるプログラム以外のすべてが転送可能
AuthorityPluginを更新する権限を持つアカウント
Next
Update Delegate Plugin