Plugins Overview

This page explains the Core Plugin system - modular extensions that add behaviors and data storage to Core Assets and Collections. Plugins hook into lifecycle events to enforce rules or store on-chain data.

Summary

Plugins are on-chain extensions that add functionality to Core Assets or Collections. They can store data (like attributes), enforce rules (like royalties), or delegate permissions (like freeze/transfer authority).

• Owner Managed: Require owner signature to add (Transfer, Freeze, Burn Delegate)
• Authority Managed: Can be added by update authority (Royalties, Attributes, Update Delegate)
• Permanent: Can only be added at creation time (Permanent Transfer/Freeze/Burn Delegate)

Out of Scope

Creating custom plugins (only built-in plugins are supported), Token Metadata plugins (different system), and off-chain plugin data storage.

Quick Start

Jump to: Plugin Types · Plugin Table · Lifecycle Events · Adding Plugins

1. Choose a plugin based on your use case (royalties, freezing, attributes, etc.)
2. Add the plugin using addPlugin() or at Asset/Collection creation
3. Plugins automatically hook into lifecycle events
4. Query plugin data via DAS or on-chain fetch

Lifecycles

During a Core Assets lifecycle, multiple events can be triggered such as:

• Creating
• Transferring
• Updating
• Burning
• Add Plugin
• Approve Authority Plugin
• Remove Authority Plugin Lifecycle events impact the Asset in various ways from creating, to transfers between wallets, all the way through to the Assets destruction. Plugins attached an Asset level or a Collection level will run through a validation process during these lifecycle events to either approve, reject, or force approve the event from execution.

What are Plugins?

A plugin is like an onchain app for your NFT that can either store data or provide additional functionality to the asset.

Types of Plugins

Owner Managed Plugins

Owner managed plugins are plugins that can only be added to an Core Asset if the Asset owner's signature is present in the transaction. Owner Managed Plugins include but are not limited to:

• Transfer Delegate (market places, games)
• Freeze Delegate (market places, staking, games)
• Burn Delegate (games) If an Owner Managed plugin is added to an Asset/Collection without an authority set it will default the authority type to the type of owner. The authority of owner managed plugins is automatically revoked when they are transferred.

Authority Managed Plugins

Authority managed plugins are plugins that the authority of the MPL Core Asset or Core Collection can add and update at any time. Authority manages plugins include but are not limited to:

• Royalties
• Update Delegate
• Attribute If an Authority Managed plugin is added to an Asset/Collection without an authority argument present then the plugin will default to the authority type of update authority.

Permanent Plugins

Permanent plugins are plugins that may only be added to a Core Asset at the time of creation. If an Asset already exists then Permanent Plugins cannot be added. Permanent Plugins include but are not limited to:

• Permanent Transfer Delegate
• Permanent Freeze Delegate
• Permanent Burn Delegate If an Permanent Plugin is added to an Asset/Collection without an authority set it will default the authority type to the type of update authority.

Collection Plugins

Collection Plugins are plugins that are added at the collection level can have a collection-wide effect. This is particularly useful for royalties because you can assign the royalties plugin to the Collection Asset and all Assets in that collection will now reference that plugin. Collections only have access to Permanent Plugins and Authority Managed Plugins.

Plugin Priority

If an MPL Core Asset and MPL Core Collection Asset both share the same plugin type then the Asset level plugin and its data will take precedence over the Collection level plugin. This can be used in creative ways like setting royalties at different levels for a collection of assets.

• Collection Asset has a Royalties Plugin assigned at 2%
• A Super Rare MPL Core Asset within the collection has a Royalty Plugin assigned at 5% In the above case, regular MPL Core Asset sales from the collection will retain a 2% royalty while the Super Rare MPL Core Asset will retain a 5% royalty at sale because it has it's own Royalties Plugin that takes precedence over the Collection Asset Royalties Plugin.

Plugin Table

Plugins and Lifecycle Events

Plugins in MPL Core have the ability to affect the outcome of certain lifecycle actions such as Create, Transfer, Burn, and Update. Each plugin has the ability to to reject, approve, or force approve an action to a desired outcome. During lifecycle events the action will work its way down a list of predefined plugins checking and validating against them. If the plugins conditions are validated the lifecycle passes and continues its action. If a plugin validation fails then the lifecycle will be halted and rejected. The rules for plugin validation are as follows in this hierarchy of conditions;

• If there is force approve, always approve
• Else if there is any reject, reject
• Else if there is any approve, approve
• Else reject The force approve validation is only available on 1st party plugins and on Permanent Delegate plugins.

Force Approve

Force approve is the first check made when checking a plugins validations. The plugins which will force approve validations currently are:

• Permanent Transfer
• Pernament Burn
• Permanent Freeze These plugins will take precedence with their actions over their non permanent counterparts and other plugins.

Example

If you have an Asset frozen at Asset level with a Freeze Plugin while simultaneously have a Permanent Burn plugin on the Asset, even if the Asset is frozen the burn procedure called via the Pernament Burn plugin with still execute due to the forceApprove nature of permanent plugins.

Create

Update

Transfer

Burn

Add Plugin

Remove Plugin

Approve Plugin Authority

Revoke Authority Plugin

Common Use Cases

FAQ

Can I add plugins after an Asset is created?

Yes, except for Permanent plugins. Owner Managed plugins require owner signature; Authority Managed plugins require update authority signature.

What happens to plugins when an Asset is transferred?

Owner Managed plugins (Transfer, Freeze, Burn Delegate) have their authority automatically revoked on transfer. Authority Managed and Permanent plugins persist.

Can an Asset have the same plugin as its Collection?

Yes. When both have the same plugin type, the Asset-level plugin takes precedence over the Collection-level plugin.

How do I remove a plugin?

Use the removePlugin instruction. Only the plugin authority can remove it. See Removing Plugins.

Can I create custom plugins?

No. Only built-in plugins are supported. The plugin system is not extensible by third parties.

Do plugins cost extra SOL?

Adding plugins increases account size, which increases rent. Most plugins cost ~0.001 SOL, but data-storage plugins (like AppData or Attributes) can cost more depending on how much data is stored.

Glossary