Plugins
Royalties Plugin
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 { addPlugin, ruleSet } from '@metaplex-foundation/mpl-core'
const creator1 = publicKey('11111111111111111111111111111111')
const creator2 = publicKey('2222222222222222222222222222222')
await addPlugin(umi, {
asset: asset.publicKey,
plugin: {
type: 'Royalties',
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 { addCollectionPlugin, ruleSet } from '@metaplex-foundation/mpl-core'
const creator1 = publicKey('11111111111111111111111111111111')
const creator2 = publicKey('2222222222222222222222222222222')
await addCollectionPlugin(umi, {
collection: collection.publicKey,
plugin: {
type: 'Royalties',
basisPoints: 500,
creators: [
{ address: creator1, percentage: 80 },
{ address: creator2, percentage: 20 },
],
ruleSet: ruleSet('ProgramDenyList', [
[
publicKey('44444444444444444444444444444444'),
publicKey('55555555555555555555555555555555'),
],
]),
},
}).sendAndConfirm(umi)