Metaplex
Metaplex Core keeps ownership, a metadata URI, and attached plugin records in one Asset account
Metaplex Core places an NFT’s owner, name, metadata URI, update authority, and attached plugin records in one Solana Asset account. This model gives applications one base record to create, transfer, update, or burn. Plugins add permissions, stored data, or lifecycle rules without rebuilding the asset around separate token and metadata accounts. Some dependencies remain outside that account: a Collection account or an external Oracle may participate in a transaction, while images and descriptive JSON usually remain off-chain behind the URI. Choosing among a base Asset, a built-in plugin, and an external adapter determines who must sign, which state an application must read, and how much account storage the asset requires.
The short version: A Core Asset combines ownership, its metadata pointer, and attached plugins, while collections and external adapters can supply additional state.
Choose the smallest state model that fits the behavior
The first decision is whether the base Asset fields already describe the required state. Add a plugin only when the asset needs an extra authority, rule, or on-chain data area. Use an external adapter when the application requires separately controlled data or validation beyond the built-in behaviors.
- Use the base Asset when its owner, name, URI, and update authority are sufficient.
- Add a built-in plugin for supported behavior such as attributes, royalties, freezing, or delegation.
- Include a creation-only plugin when creating the Asset if that plugin must remain permanently attached.
- Place a shared plugin on a Collection when member Assets should inherit the same setting.
- Choose an external adapter when custom validation or separately controlled application data is necessary.
These choices make the required signer clear. It also avoids allocating storage for behavior that the asset never uses.
Some Core dependencies remain in separate accounts
A Core digital asset uses one on-chain Asset account for its base data and attached built-in plugin records. Ownership does not require an Associated Token Account. A Collection remains a separate account, however, and an external Oracle can add another account dependency. Media and extended descriptive metadata also remain outside the Asset account when the URI points to an off-chain JSON file.
What does the Asset account actually store?
The base record stores the owner, name, metadata URI, and update authority relationship. That authority value can identify an address, indicate that no update authority remains, or point to the Collection that governs a member Asset. The URI is a pointer rather than the image or descriptive JSON itself.
Attached plugins occupy additional space in the same account. Their records identify the plugin type, its authority, and any data needed by that plugin. Attributes can therefore remain on-chain, while a Royalties plugin can hold creator shares and transfer rules. External plugin adapters add a connection point or partitioned data area, depending on the adapter type. An Oracle adapter may also consult an account outside the Asset.
Stored bytes set the rent requirement
Solana rent follows the serialized size of the Asset account. Longer names and URIs require more space, and adding plugins expands the account further. Data-heavy plugins vary with their payload, so there is no durable flat plugin cost that covers every Asset. The payer must fund the added storage when an instruction grows the account. A transaction fee and the account’s rent balance are separate cost inputs.
Plugin families assign control in different ways
Each built-in plugin belongs to an authority family that determines who may add it and where control returns after revocation. Use the default only when it matches the application’s control model; otherwise, assign the intended authority explicitly.
Owner-managed plugins follow the current owner
Transfer Delegate, Freeze Delegate, and Burn Delegate are owner-managed examples. The owner must authorize their addition, and the default plugin authority is the current owner. A specific address can receive delegated control. When ownership transfers, delegated authorities for owner-managed plugins are revoked and the authority type returns to Owner.
Authority-managed plugins follow update control
Royalties, Attributes, and Update Delegate are authority-managed examples. The update authority authorizes their addition, and Update Authority is their default control type. A plugin can instead assign control to a specific address. Setting its authority to None makes that plugin immutable and prevents later updates or removal. It does not, by itself, make every other Asset field immutable.
Permanent plugins fix their presence at creation
Permanent Transfer Delegate, Permanent Freeze Delegate, and Permanent Burn Delegate must be included when the Asset is created. They cannot be attached later or removed from an existing Asset. Their presence is permanent, while configuration and authority behavior remain specific to the selected plugin. Plan this choice when creating the Asset, before users or integrations depend on its address.
Collections support authority-managed and permanent plugins, not owner-managed plugins. A Collection has an update authority but no changing holder whose signature could supply owner-managed control.
Lifecycle checks decide whether an instruction proceeds
Plugins can participate in lifecycle events such as creation, transfer, burn, update, and plugin management. A relevant check may approve an instruction, reject it, or force approval where that result is available. These checks operate alongside the instruction’s base signer and account requirements; attaching a plugin does not erase ordinary authority validation.
The Core program resolves eligible plugin results in a defined order. A force approval takes precedence. Without one, a rejection defeats an ordinary approval, while an approval can allow the action when no rejection remains. The program rejects an instruction when neither its base authority check nor an eligible plugin approves it. Collection-level checks can join Asset-level checks, so an application may need both accounts to predict whether the action is valid.
Check compatibility before the first state-changing instruction
Check whether the plugin can be added to an existing Asset before signing. An existing Asset can receive an Attributes plugin, but a Permanent Freeze Delegate must be included in its creation instruction.
Adding mutable attributes to an existing Asset
Fetch the existing Asset and identify its update authority before adding an Attributes plugin. The authorized signer submits the add-plugin instruction, while the payer covers any added storage. After confirmation, fetch the Asset again and inspect the Attributes record, its stored values, and its plugin authority. A missing record or authority mismatch invalidates the original assumption, so dependent application writes should stop until the authority or target Asset is corrected.
Reaching a creation-only boundary
An existing Asset cannot accept a Permanent Freeze Delegate. The program rejects that addition because permanent plugins belong in the creation instruction. Repeating the same request does not change compatibility. Use the non-permanent Freeze Delegate when its authority model fits, or create a different Asset with the permanent plugin included from the outset. A failed instruction leaves the existing Asset without that permanent plugin.
Transfers rewrite ownership and clear temporary delegates
A transfer changes the owner field inside the same Asset account rather than moving a token balance between holder accounts. The Asset address remains stable. Owner-managed delegate authorities reset to Owner after a successful transfer, which prevents a previous holder’s delegate from retaining that temporary control. Authority-managed and permanent plugins remain attached.
Plugin state can still block or shape the instruction. A frozen Asset cannot follow the ordinary transfer path until the appropriate freeze authority changes its state. A member Asset also requires its Collection account during the transfer so collection-level rules can be evaluated. Applications should read the resulting owner and effective plugin state instead of treating a submitted signature as the final ownership record.
Collection plugins can affect members, while Asset plugins can override the same type
A Collection is a separate Core account that can hold shared metadata and eligible plugins. Member Assets refer to that Collection through their update authority relationship, allowing one setting to affect many Assets without copying the plugin into every Asset account.
Collection-level plugins can apply to member Assets
An authority-managed plugin on a Collection can provide inherited behavior to its members. Royalties are a common example: Assets without their own Royalties plugin use the Collection setting. Because the plugin data remains on the Collection account, direct validation must include that account. A client that reads only the member Asset may miss part of the effective rule set.
An Asset-level plugin overrides the same Collection plugin type
When the Asset and its Collection carry the same plugin type, the Asset-level plugin takes precedence. This allows a specific member to use different plugin data without changing the Collection default. The override applies by plugin type rather than replacing unrelated Collection plugins. Applications therefore need to merge the two scopes carefully: read the Collection setting, check for an Asset-level instance, and use the Asset value only for that matching type.
Removing or changing a Collection plugin can affect members that depend on it, while Assets with their own override retain that separate record. The shared rule and the exception have distinct authorities and storage.
How should an application read effective plugin state?
An application should deserialize the Asset and any relevant Collection directly, or request indexed Core data through a DAS-enabled RPC. Direct account reads expose the committed base fields and attached records. The Core DAS extension can return parsed plugin data and derive plugins inherited from a Collection, which is convenient for discovery and display.
The read method must match the decision being made. A visible owner field alone does not prove that transfer, burn, or update will succeed. Freeze state, delegated authority, Collection rules, and external checks may also matter. SDK helpers such as canTransfer, canBurn, and canUpdate can evaluate fetched Asset and Collection data before an application builds a state-changing instruction.
Core’s single-account model and Token Metadata’s linked records
Core concentrates ownership, the metadata pointer, authority state, and attached plugin records in one per-Asset account. Token Metadata uses a linked structure built around an SPL Mint, a Metadata account, and a holder token account, with further records for some asset standards. That difference changes what software creates, funds, fetches, and validates.
The Core model fits an NFT that benefits from direct ownership state and composable built-in or external behavior. Existing systems may still require Token Metadata’s mint and token-account conventions. Compatibility with wallets, marketplaces, programs, and indexing infrastructure should decide between them. Core reduces the per-Asset account graph, while Token Metadata preserves the established SPL token account model.
Worth knowing
May one transaction add several plugins to an existing Core Asset?
Yes. Each plugin added to an existing Asset uses its own add-plugin instruction, and several instructions may be combined in one Solana transaction when transaction limits permit. Every instruction still needs the authority required by that plugin family, and the payer must cover any added account storage. Combining instructions does not allow a Permanent plugin onto an existing Asset, because that category must be included when the Asset is created.
Which account receives rent back after a removable plugin is deleted?
The payer associated with the plugin storage receives the recovered rent when a removable plugin is deleted. Removal also erases the plugin data and behavior, so the refund is not a reversible archive. The signer must have removal authority for that plugin. Permanent plugins cannot be removed, and a Collection plugin must be managed separately from any Asset-level plugin of the same type.
Does the Royalties plugin distribute creator payments by itself?
No. The Royalties plugin records basis points, creator shares, and a rule set that can restrict which programs may transfer the Asset. Marketplaces handle payment collection and distribution. With a None rule set, the plugin does not restrict transfers, and royalties remain advisory. An Asset-level Royalties plugin takes precedence over the same plugin on its Collection, so applications must read the effective setting rather than only the Collection record.
Where should application-specific writable data live in Core?
Use the Attributes plugin for structured on-chain traits controlled through its plugin authority. AppData fits an application that needs a partitioned writable area with a separate Data Authority. AppData supports JSON, MsgPack, or binary payloads. The choice changes who may write, how clients decode the payload, and whether application data remains distinct from the Asset’s general attributes. Neither option should hold media that clients expect to retrieve as an ordinary metadata file.
Are an AppData Data Authority and its plugin authority the same role?
No. The AppData Data Authority controls writes to the stored payload, while the plugin authority controls management of the adapter. An Asset’s update authority does not automatically gain AppData write permission unless that address is also assigned as Data Authority. Separating these roles lets an application update its own partition without receiving broader control over the Asset or Collection. Clients should verify both authorities before deciding which operation a signer may perform.
Can an application define a new built-in Core plugin type?
No. Applications cannot register a new type inside the standard built-in plugin registry. Built-in plugins provide predefined behavior such as attributes, royalties, freezing, and delegation. Custom validation can use an Oracle external plugin adapter, while isolated application data can use AppData. Those routes introduce their own authorities and possible account dependencies, so clients must read them explicitly. They do not become new native plugin types merely because an application depends on them.
Which state remains if the off-chain metadata file becomes unavailable?
The on-chain Asset remains and still exposes its owner, name, metadata URI, update authority or Collection relationship, and attached on-chain plugin state. Content stored only at the URI, such as an image, description, or additional attributes, becomes unavailable when that file cannot be fetched. An Attributes plugin remains readable from the account because its data is on-chain, but it does not restore missing media or JSON fields from the unreachable file.