Metaplex

플러그인

Royalties Plugin

Last updated January 31, 2026

Royalties Plugin은 Core Asset의 2차 판매에 대한 크리에이터 로열티를 강제합니다. 로열티 비율, 크리에이터 분배, 그리고 어떤 프로그램(마켓플레이스)이 Asset을 전송할 수 있거나 거부되는지를 지정합니다.

학습 내용

다음 방법을 배웁니다:

  • Asset 및 Collection에 로열티 추가
  • Basis points 및 크리에이터 분배 구성
  • 마켓플레이스 제어를 위한 allowlist 및 denylist 설정
  • 생성 후 로열티 업데이트

요약

Royalties Plugin은 Core Asset에 로열티를 강제하는 authority 관리형 Plugin입니다. 비율(basis points)을 설정하고, 여러 크리에이터에게 분배하며, 선택적으로 어떤 프로그램이 Asset을 전송할 수 있는지 제한할 수 있습니다.

  • 로열티를 basis points로 설정 (500 = 5%)
  • 최대 5명의 크리에이터에게 로열티 분배
  • Allowlist/denylist를 사용하여 마켓플레이스 접근 제어
  • Asset 레벨(개별) 또는 Collection 레벨(모든 Asset)에 적용

범위 외

Token Metadata 로열티(다른 시스템), 로열티 수집/분배(마켓플레이스에서 처리), 로열티의 법적 강제.

빠른 시작

바로가기: Asset에 추가 · Collection에 추가 · RuleSet · 업데이트

  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, 또는 none

Basis Points

백분율의 백분의 1 단위로 표현된 로열티 비율입니다.

Basis Points비율
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 },

]

RuleSet

RuleSet은 로열티가 적용된 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 추가 (코드 예제)

Asset에 Royalties Plugin 추가

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 레벨 로열티는 Asset 레벨에서 재정의되지 않는 한 Collection의 모든 Asset에 적용됩니다.

Collection에 Royalties Plugin 추가

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을 수정합니다.

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

호출 프로그램이 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 points, creators, ruleset이 포함됩니다.

ruleset을 설정하지 않으면 어떻게 되나요?

ruleSet('None')을 사용하세요. 모든 프로그램이 Asset을 전송할 수 있으며 로열티는 권고 사항으로만 적용됩니다.

민팅 후 로열티를 변경할 수 있나요?

네. 권한이 있다면 updatePlugin(Asset용) 또는 updateCollectionPlugin(Collection용)을 사용하세요.

용어집

용어정의
Basis Points백분율의 백분의 1 단위 로열티 비율 (500 = 5%)
Creators로열티 지불을 받는 주소 배열
RuleSet어떤 프로그램이 전송할 수 있는지 제어하는 allowlist/denylist
Allowlist목록에 있는 프로그램만 전송 가능 (엄격한 강제)
Denylist목록에 있는 프로그램을 제외한 모든 프로그램 전송 가능
AuthorityPlugin을 업데이트할 수 있는 계정
Next
Update Delegate Plugin