mpl-core & mpl-token-metadata
Metaplex libraries model NFTs and digital assets on Solana. mpl-token-metadata covers classic Metaplex Token Metadata accounts attached to SPL mints. mpl-core (Core digital assets) provides a streamlined asset model with plugins. Rust crates wrap instruction builders; TypeScript clients often use Umi or @solana/kit 7.0.0 integrations alongside DAS APIs.
Recipe
Quick-reference recipe card - copy-paste ready.
[dependencies]
mpl-token-metadata = "5.1"
mpl-core = "0.9"use mpl_token_metadata::accounts::Metadata;
// Layout parsing for legacy NFT metadata PDAWhen to reach for this:
- Minting NFTs with on-chain metadata and creators array.
- Building marketplaces that update metadata or verify collections.
- Adopting Metaplex Core for lower-cost asset issuance.
- Reading asset records via DAS instead of manual PDA walks.
Working Example
use anchor_lang::prelude::*;
use mpl_core::{
instructions::CreateV1CpiBuilder,
types::{Attribute, Attributes, DataState, PluginAuthorityPair},
};
pub fn create_core_asset<'info>(
asset: &AccountInfo<'info>,
payer: &Signer<'info>,
system_program: &AccountInfo<'info>,
mpl_core_program: &AccountInfo<'info>,
name: String,
uri: String,
) -> Result<()> {
CreateV1CpiBuilder::new(mpl_core_program)
.asset(asset)
.payer(payer)
.system_program(system_program)
.name(name)
.uri(uri)
.data_state(DataState::AccountState)
.invoke()?;
Ok(())
}What this demonstrates:
- MPL Core uses CPI builders to target the Core program.
- Name and URI point to off-chain JSON (IPFS/Arweave/https).
DataStatechooses account vs ledger state models.- Works inside Anchor 0.32.1 instructions with explicit accounts.
Deep Dive
How It Works
- Token Metadata attaches a PDA per mint with name, symbol, uri, creators, collection.
- Core assets unify ownership and plugins with a different program interface.
- DAS API indexes both legacy and compressed assets for client queries.
- Royalties enforced via program rules and marketplace integrations.
Rust Crate Table
| Crate | Asset model | Typical use |
|---|---|---|
mpl-token-metadata | Classic NFT PDAs on mint | Marketplaces, candy machines legacy |
mpl-core | Core digital assets | New collections with plugins |
mpl-candy-machine | Launch mechanics | Drops (see NFT section) |
mpl-bubblegum | Compression | cNFTs (see compression section) |
TypeScript / NPM Table
| Package | Role | Notes |
|---|---|---|
@metaplex-foundation/mpl-core | Core ix builders | Pair with Umi or kit |
@metaplex-foundation/mpl-token-metadata | Legacy metadata | Migration projects |
@metaplex-foundation/umi | Metaplex SDK shell | Bundles serializers |
DAS (getAsset) | Read layer | Provider-enabled RPC |
Rust Notes
// Prefer DAS for read-heavy dashboards; use crates for writes/CPIs
// Validate URI length and creator shares sum to 100 before CPIGotchas
- Mixing Core and Token Metadata models - incompatible account layouts. Fix: pick per collection; document in app.
- Oversized on-chain metadata - rent and CU spike. Fix: store JSON off-chain; on-chain uri only.
- Creator array mismatch - royalty enforcement fails. Fix: match seller fee basis points to business rules.
- Missing collection verification - fake collection membership. Fix: run verify collection instruction.
- Assuming DAS writes - DAS is read-only. Fix: build MPL instructions for mutations.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
mpl-bubblegum cNFTs | Mass mints | Need rich on-chain metadata |
| SPL token only | Fungible SFT | Full NFT metadata |
| Custom program metadata | Game items with logic | Standard marketplace interop |
| IPFS-only without MPL | Off-chain prototypes | OpenSea/Magic Eden compatibility |
FAQs
Core vs Token Metadata?
Core is the newer unified model; Token Metadata remains widespread on legacy NFTs.
Do I need Umi in Rust?
No - Rust uses MPL crates directly; Umi is TS-first.
Compressed NFTs?
Use Bubblegum + DAS - different crates and flows.
Royalties enforcement?
Marketplace-dependent; on-chain rules are necessary not sufficient.
Anchor integration?
CPI builders inside #[program] handlers with explicit remaining accounts.
Storage URIs?
Prefer immutable Arweave/IPFS CIDs; avoid mutable https for collectibles.
Edition accounts?
Token Metadata editions for print editions; Core uses plugins.
Indexing?
Helius/Triton DAS for reads; Geyser for custom pipelines.
Testing?
LiteSVM with MPL programs loaded or devnet integration tests.
Client reads in kit?
Combine @solana/kit 7.0.0 RPC with DAS HTTP for asset pages.
Related
- NFT Basics on Solana - concepts
- Metaplex Core - Core guide
- Token Metadata - legacy metadata
- Reading NFTs (DAS API) - read path
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.