Core - Enforcing Royalties

The Royalties Plugin is a Authority Managed plugin that allows the authority of the Asset to set and change the Royalties Plugin data.

This plugin can be used on both the MPL Core Asset and the MPL Core Collection.

When assigned to both MPL Core Asset and the MPL Core Collection the MPL Core Asset Royalties Plugin will take precedence over the MPL Core Collection Plugin.

Works With


MPL Core Asset	✅
MPL Core Collection	✅

Arguments

The Royalties Plugin requires the following arguments.

Arg	Value
basisPoints	number
creators	Array<CreatorArgs>
ruleset	RuleSet

basisPoints

This is the percentage in basispoints you wish creators from the creators array to receieve in royalties on secondary sales. If the Royalties Plugin is set to 500 this means 5%. So if you sell a MPL Core Asset for 1 SOL the Asset's designated creators will receive a total of 0.05 SOL to be distributed amongst them. Some of our SDKs provide helper methods like percentAmount in umi, so that you do not have to do the calculation yourself.

Creators

The creators list is a distribution list for where earned royalties are distributed. You can have up to 5 creators in your list that earn from royalties. The total share between all members must add up to 100%.

Creators Array

import { publicKey } from '@metaplex-foundation/umi'

const creators = [
    { address: publicKey("11111111111111111111111111111111"), percentage: 80 }
    { address: publicKey("22222222222222222222222222222222"), percentage: 20 }
]

RuleSets

RuleSets allow you to control what programs can or can not perform actions on the MPL Core Assets the Royalties plugin is assigned to.

Allowlist

An Allowlist is a list of programs that are allowed to interact with your MPL Core Asset/Collection. Any program not on this list will throw an error.

RuleSet Allowlist

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

const ruleSet = ruleSet('ProgramAllowList', [
    [
		publicKey("11111111111111111111111111111111")
		publicKey("22222222222222222222222222222222")
    ]
])

DenyList

A Denylist is a list of programs that are not allowed to interact with your MPL Core Asset/Collection. Any program on this list will throw an error.

RuleSet DenyList

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

const ruleSet = ruleSet('ProgramDenyList', [
    [
		publicKey("11111111111111111111111111111111")
		publicKey("22222222222222222222222222222222")
    ]
])

None

If you do not wish to set any ruleset rules then you can just pass the __kind as none.

RuleSet DenyList

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

const rule_set = ruleSet('None')

Adding the Royalties Plugin to an Asset code example

Adding a Royalties Plugin to an MPL Core Asset

import { publicKey } from '@metaplex-foundation/umi'
import {
  addPluginV1,
  createPlugin,
  ruleSet,
} from '@metaplex-foundation/mpl-core'

const creator1 = publicKey('11111111111111111111111111111111')
const creator2 = publicKey('2222222222222222222222222222222')

await addPluginV1(umi, {
  asset: asset.publicKey,
  plugin: createPlugin({
    type: 'Royalties',
    data: {
      basisPoints: 500,
      creators: [
        { address: creator1, percentage: 80 },
        { address: creator2, percentage: 20 },
      ],
      ruleSet: ruleSet('ProgramDenyList', [
        [
          publicKey('44444444444444444444444444444444'),
          publicKey('55555555555555555555555555555555'),
        ],
      ]),
    },
  }),
}).sendAndConfirm(umi)

Adding the Royalties Plugin to a Collection code example

Add Royalties Plugin to Collection

import { publicKey } from '@metaplex-foundation/umi'
import {
  addCollectionPluginV1,
  createPlugin,
  ruleSet,
} from '@metaplex-foundation/mpl-core'

const creator1 = publicKey('11111111111111111111111111111111')
const creator2 = publicKey('2222222222222222222222222222222')

await addCollectionPluginV1(umi, {
  collection: collection.publicKey,
  plugin: createPlugin({
    type: 'Royalties',
    data: {
      basisPoints: 500,
      creators: [
        { address: creator1, percentage: 80 },
        { address: creator2, percentage: 20 },
      ],
      ruleSet: ruleSet('ProgramDenyList', [
        [
          publicKey('44444444444444444444444444444444'),
          publicKey('55555555555555555555555555555555'),
        ],
      ]),
    },
  }),
}).sendAndConfirm(umi)