継承ロイヤリティの読み取り

概要

Bubblegum V2は、リーフ上に販売者手数料を継承センチネル（65535）として保存し、MPL-CoreコレクションのRoyaltiesプラグインから実効料率を解決できます。DASはコレクションから解決された値を主フィールドに置き（表示用）、リーフ値は _raw フィールドに公開します（ハッシュ用）。

• 主フィールド（royalty.basis_points、creators）はロイヤリティUIと支払い表示に使用
• _raw フィールド（royalty.basis_points_raw、creators_raw）は証明、ハッシュ、書き込み命令に使用
• 非継承アセットは変更なし — _raw / inherited は省略されます

このページは、getAsset / DASレスポンスを読むすべてのクライアント（ウォレット、マーケットプレイス、インデクサー、分析、アプリ）向けです。継承ロイヤリティのcNFTのミントと更新については、ミントおよび更新を参照してください。

適用条件

次の条件を満たすとき、cNFTは継承ロイヤリティを使用しています。

• Royalties プラグインを持つMPL-Coreコレクション内のBubblegum V2アセットであり、かつ
• リーフの販売者手数料が継承センチネル 65535（0xffff）である

コレクションロイヤリティを主フィールドに解決できる場合、DASは royalty.inherited: true と royalty.basis_points_raw: 65535 でこれを示します。

フィールド対応表

表示用の値とリーフの値は別々のDASフィールドにあり、書き込みにはリーフの値を使う必要があります。

例: DASレスポンス（継承）

継承されたアセットでは、basis_pointsにコレクションの解決済み料率が、basis_points_rawに65535のセンチネルが返ります。

"royalty": {
  "royalty_model": "creators",
  "target": null,
  "percent": 0.075,
  "basis_points": 750,
  "basis_points_raw": 65535,
  "inherited": true,
  "primary_sale_happened": false,
  "locked": false
},
"creators": [
  {
    "address": "CJkzXwVwqiaSvMuRb3obrZHdrPFjCMBJBDrjspn72tDv",
    "share": 100,
    "verified": true
  }
],
"creators_raw": []

• basis_points: 750 はユーザーに見せるコレクション料率（7.5%）です。
• basis_points_raw: 65535 はリーフデータハッシュに使われるオンチェーンセンチネルであり — 655.35%のロイヤリティではありません。
• creators はコレクション Royalties プラグインの受取人、creators_raw: [] はハッシュ用のリーフ creators 配列です。

コレクションを解決できない場合、basis_points はフォールバックすることがあり、basis_points_raw は 65535 のままです。

検出と表示ヘルパー

以下の3つのヘルパーは、継承ロイヤリティで挙動が変わる操作をカバーします。継承の検出、書き込み用リーフ値の復元、正しいクリエイターリストの選択です。

const INHERIT = 0xffff // 65535

function isInheritedRoyalty(royalty: {
  basis_points: number
  basis_points_raw?: number | null
  inherited?: boolean | null
}): boolean {
  if (royalty.inherited === true) return true
  if (royalty.basis_points_raw != null) {
    return royalty.basis_points_raw === INHERIT
  }
  // Older DAS versions return neither field and surface the sentinel
  // directly in basis_points. Without this, 65535 reads as a 655.35% fee.
  return royalty.basis_points === INHERIT
}

function leafBasisPoints(royalty: {
  basis_points: number
  basis_points_raw?: number | null
  inherited?: boolean | null
}): number {
  if (royalty.basis_points_raw != null) return royalty.basis_points_raw
  if (royalty.inherited) return INHERIT
  return royalty.basis_points
}

function leafCreators(asset: {
  creators: Array<{ address: string; share: number; verified: boolean }>
  creators_raw?: Array<{
    address: string
    share: number
    verified: boolean
  }> | null
}) {
  return asset.creators_raw ?? asset.creators
}

@metaplex-foundation/digital-asset-standard-api を使う場合:

import {
  SELLER_FEE_BASIS_POINTS_INHERIT,
  isInheritedSfbpRoyalty,
  getRawSellerFeeBasisPoints,
  getResolvedSellerFeeBasisPoints,
} from '@metaplex-foundation/digital-asset-standard-api'

const royalty = asset.royalty
if (isInheritedSfbpRoyalty(royalty)) {
  const rate = getResolvedSellerFeeBasisPoints(royalty) // e.g. 750 (display)
  const leaf = getRawSellerFeeBasisPoints(royalty) // 65535
  const payees = asset.creators // collection payees
  const leafCreators = asset.creators_raw ?? []
}

やってはいけないこと

統合時の不具合の多くは、リーフの値をユーザーに表示してしまうか、表示用の値を書き込みでハッシュしてしまうことが原因です。

• 65535 や 6.5535% をユーザー向けロイヤリティ料率として表示しないでください — その値は basis_points_raw にあります。
• 空の creators_raw がロイヤリティ受取人がいないことを意味すると仮定しないでください；表示用の受取人は creators にあります。
• リーフハッシュの再計算や Bubblegum 書き込み命令の構築時に、主フィールドの basis_points / creators を使わないでください — basis_points_raw と creators_raw を使ってください。

Bubblegum SDK の注意

getAssetWithProof は読み取り互換を維持します：metadata は DAS の主フィールドを反映します（継承時は解決済みコレクション料率）。currentMetadata は書き込み用のリーフ正規値です。任意の兄弟フィールド sellerFeeBasisPointsRaw / creatorsRaw と inherited は DAS の _raw / 継承検出をミラーします。書き込みでは ...assetWithProof を展開し、リーフ引数には currentMetadata を使い、表示用 metadata は渡さないでください。JavaScript SDKを参照してください。

注意事項

• DASのサポート状況はプロバイダーによって異なります。アップグレード済みのインデクサーはbasis_points_raw、creators_raw、inheritedを返しますが、古いものは3つとも返さず、65535のセンチネルをbasis_pointsに直接載せます。これらのフィールドは任意として扱い、センチネルにフォールバックしてください。
• 継承は読み取り時にMPL-CoreコレクションのRoyaltiesプラグインから解決されます。コレクションの料率を変更すると、リーフに一切触れずに、継承しているすべてのアセットについてDASの報告値が変わります。
• ロイヤリティの強制とロイヤリティの支払いは別物です。どのプログラムが転送できるかはコレクションのruleSet（ProgramAllowList / ProgramDenyList）が制御し、Bubblegumは転送時にロイヤリティ支払いをエスクローしません。
• 本ページはBubblegum V2（MPL-Bubblegum）に適用されます。V1ツリーにはコレクションレベルのロイヤリティ継承はありません。
• 本ページのDASフィールド（basis_points_raw、creators_raw、inherited）には@metaplex-foundation/digital-asset-standard-api 2.1.0以上が必要です。getAssetWithProofのcurrentMetadataは@metaplex-foundation/mpl-bubblegum 5.1.0で利用できますが、sellerFeeBasisPointsRaw、creatorsRaw、inheritedの各フィールドはまだ公開されていません。これらはmpl-bubblegum#173で追加されます。それまではrpcAssetから読み取ってください。

よくある質問

royalty.basis_points_rawが65535と表示されるのはなぜですか？

リーフハッシュに使われるオンチェーン継承センチネルです。royalty.basis_pointsにはすでに表示用のコレクション料率が入っています。

継承されたcNFTでcreators_rawが空なのはなぜですか？

SFBPが継承される場合、リーフのcreatorsは空でなければなりません。コレクションのロイヤリティ受取人にはcreatorsを使用してください。

継承していないcNFTについて変更は必要ですか？

いいえ。継承を使用しない場合、_rawフィールドとinheritedは省略され、主なroyaltyとcreatorsフィールドは従来どおり動作します。

関連

• 圧縮NFTの取得
• ミント — ロイヤリティの継承
• cNFTの更新 — 継承ロイヤリティ
• NFTデータのハッシュ
• DAS getAsset
• FAQ — 継承ロイヤリティ