Metaplex Token Metadata

SPL Token mint accounts store decimals, supply, authorities. They don't store names, images, descriptions. USDC's mint is EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v. Your wallet displays "USDC" with a logo. That information comes from metadata.

Metaplex Token Metadata is the standard that adds human-readable information to Solana tokens. A separate program creating metadata accounts linked to mint accounts. Every major NFT on Solana used this standard for years.

How Token Metadata Works

Token Metadata uses two accounts:

1. Mint account (SPL Token):

Standard SPL Token mint. For NFTs: supply=1, decimals=0, mint authority=None.

2. Metadata PDA (Metaplex program):

Program Derived Address owned by Metaplex Token Metadata program. Stores name, symbol, URI, creators, royalties, collection info.

Deterministically derived from mint address:

const metadataPDA = PublicKey.findProgramAddressSync(
    [
        Buffer.from("metadata"),
        METADATA_PROGRAM_ID.toBuffer(),
        mintAddress.toBuffer(),
    ],
    METADATA_PROGRAM_ID
)[0];

Given any mint address, anyone can calculate the metadata PDA address. No need to store or communicate it separately. Wallets and explorers derive it automatically.

Metadata Account Structure

The metadata account contains structured data:

pub struct Metadata {
    pub key: Key,                   // Account type discriminator
    pub update_authority: Pubkey,   // Who can update metadata
    pub mint: Pubkey,               // Associated token mint
    pub data: Data,                 // Name, symbol, URI, creators, royalty
    pub primary_sale_happened: bool,
    pub is_mutable: bool,           // Can metadata be changed?
    pub edition_nonce: Option<u8>,
    pub token_standard: Option<TokenStandard>,
    pub collection: Option<Collection>,
    pub uses: Option<Uses>,
    pub collection_details: Option<CollectionDetails>,
    pub programmable_config: Option<ProgrammableConfig>,
}

update_authority - Who can modify metadata:

• Typically the creator initially

• Can be changed or revoked (set to None for immutable)

• Independent from mint authority

mint - Which token this metadata describes:

• Links metadata to specific mint account

• One metadata account per mint

data - The actual metadata:

pub struct Data {
    pub name: String,              // "Okay Bear #1234"
    pub symbol: String,            // "OKAY"
    pub uri: String,               // Link to off-chain JSON
    pub seller_fee_basis_points: u16,  // Royalty %
    pub creators: Option<Vec<Creator>>,
}

primary_sale_happened - First sale tracking:

• False initially

• Set to true after first marketplace sale

• Used for royalty logic (some creators waive royalties on primary sales)

is_mutable - Can metadata change?:

• True: Update authority can modify metadata

• False: Metadata permanently frozen

• Common to set false after mint for immutability guarantee

collection - Collection membership:

• Reference to collection NFT

• Verified flag (collection authority signed)

• Enables collection filtering and verification

Off-Chain Metadata (JSON)

The uri field in on-chain metadata points to off-chain JSON file containing detailed information.

Typical JSON structure:

{
  "name": "Okay Bear #1234",
  "symbol": "OKAY",
  "description": "Okay Bear is a collection of 10,000 bears.",
  "image": "https://arweave.net/...",
  "attributes": [
    { "trait_type": "Background", "value": "Blue" },
    { "trait_type": "Fur", "value": "Brown" },
    { "trait_type": "Eyes", "value": "Happy" },
    { "trait_type": "Clothing", "value": "T-Shirt" }
  ],
  "properties": {
    "files": [
      { "uri": "https://arweave.net/...", "type": "image/png" }
    ],
    "category": "image"
  }
}

Why split on-chain/off-chain?

On-chain storage is expensive. Storing a 2KB JSON file on-chain costs ~0.01 SOL per NFT. For 10,000 NFTs: 100 SOL = $15,000+ in rent.

Off-chain storage (IPFS, Arweave, centralized) costs fraction of that. URI points to JSON. Wallets fetch and display.

Storage options:

Arweave: Permanent decentralized storage. Pay once, store forever. Most NFT projects use this. Cost: ~$0.01 per file.

IPFS: Decentralized but not guaranteed permanent. Files can disappear if no one pins them. Cheaper but less reliable.

Centralized (AWS, Cloudflare): Cheapest and fastest. Creator controls. Risk: Creator can change or delete. Not truly decentralized.

On-chain (rare): Maximum permanence and decentralization. Very expensive. Some high-value NFTs do this via inscriptions.

Creators and Royalties

Metadata includes creator list and royalty configuration:

pub struct Creator {
    pub address: Pubkey,
    pub verified: bool,    // Creator signed approval
    pub share: u8,         // Percentage of royalties (0-100)
}

Creator verification:

Anyone can mint an NFT claiming arbitrary creators. Verification proves creators approved.

Unverified: NFT lists creator, but creator didn't sign. Could be fake.

Verified: Creator signed transaction proving they approve being listed. Authentic.

Marketplaces show verification status. Verified creators add legitimacy.

Royalty distribution:

seller_fee_basis_points: 500  // 5% royalty
creators: [
    { address: Artist, verified: true, share: 70 },   // Artist gets 3.5%
    { address: Platform, verified: true, share: 30 },  // Platform gets 1.5%
]

Secondary sales split: 95% to seller, 5% to creators (based on share percentages).

Marketplaces honor royalties voluntarily. Protocol doesn't enforce. Most major marketplaces respect creator royalties by default, but some offer zero-royalty trading.

Collections and Verification

Collections group related NFTs. Okay Bears is a collection. Mad Lads is a collection.

Collection structure:

Collection itself is an NFT (supply=1).

Individual NFTs reference the collection:

pub struct Collection {
    pub verified: bool,    // Collection authority signed
    pub key: Pubkey,       // Collection NFT address
}

Verification process:

1. Mint collection NFT (supply=1)

2. Mint individual NFTs with collection field pointing to collection NFT

3. Collection update authority signs verification for each NFT

4. verified flag set to true

Unverified collection membership means NFT claims to belong but collection didn't verify. Likely fake. Marketplaces filter unverified NFTs or show warnings.

Why verification matters:

Anyone can create NFT claiming "Okay Bear #10001." Without verification, marketplaces can't distinguish real from fake. Verification proves collection authority approved this NFT.

Fake NFTs can't get verified (they don't have collection authority signature). Real NFTs have verified flag. Simple fraud prevention.

Master Edition and Prints

Metaplex supports edition mechanism: one master NFT, multiple prints.

Master Edition:

Original NFT marked as master. Supply=1. Has master edition PDA tracking how many prints exist and maximum allowed.

Edition Prints:

Limited or unlimited copies of master. Each print is separate NFT (supply=1) but marked as edition of master.

Print #1, Print #2, etc. Numbered and traceable to master.

Use cases:

Digital art limited editions. Artist creates master, mints 100 prints. Print #37 of 100.

Event photos with signed originals. Photographer holds master, sells numbered prints.

Trade-offs:

Adds complexity. Each print is separate NFT with separate accounts. More expensive than single NFT.

Market value: Masters typically worth more than prints. Print numbers affect value (early prints more valuable).

Not widely used compared to unique 1/1 NFTs. Adds friction for most NFT projects.

Programmable NFTs

Recent addition to Token Metadata: Programmable NFTs (pNFTs).

What they enable:

Enforced royalties at protocol level (transfers require royalty payment).

Transfer rules (restrictions on who can transfer, when, under what conditions).

Delegate management (advanced permission systems).

How they work:

Mint includes programmable configuration. Transfers execute through rule validation. Programs can enforce logic Ethereum ERC-721 cannot.

Trade-offs:

More complexity than standard NFTs. Higher transaction costs. Additional accounts.

Benefit: True royalty enforcement (not marketplace-dependent). Transfer control for gaming, compliance, conditional ownership.

Adoption:

Growing but still minority. Most NFTs remain standard Token Metadata. Use pNFTs when enforcement is critical (high-value art with royalties, gaming items with trade restrictions).

Creating Token Metadata NFTs

Steps:

1. Create mint account (supply=1, decimals=0)

2. Mint 1 token to owner's token account

3. Set mint authority to None (prevent additional minting)

4. Create metadata PDA with name, symbol, URI, creators, royalties

5. If part of collection: Set collection field and verify

Tools:

Metaplex JS SDK provides helpers:

const { nft } = await metaplex.nfts().create({
    uri: "https://arweave.net/metadata.json",
    name: "My NFT",
    sellerFeeBasisPoints: 500,
    creators: [
        {
            address: creator.publicKey,
            share: 100,
        }
    ],
});

Handles mint creation, token minting, metadata PDA creation automatically.

Cost:

Mint account: 0.00144 SOL rent.

Metadata account: ~0.012-0.02 SOL (varies by data size).

Total: ~0.015-0.025 SOL per NFT ≈ $0.02-0.03.

When to Use Token Metadata

Use Token Metadata when:

Maximum compatibility desired. Every wallet, marketplace, tool supports it.

Your project needs battle-tested standard. Years of production use.

Collection already started with Token Metadata. Migration would be complex.

Programmable NFTs needed. pNFTs require Token Metadata.

Consider alternatives when:

Lower cost matters (Metaplex Core is cheaper).

Simpler structure preferred (Core uses single account).

Massive scale needed (compressed NFTs dramatically cheaper).

Starting fresh (Core is newer, cleaner standard for new projects).

Token Metadata remains the most widely supported standard. If compatibility is priority, use it. If optimizing costs and starting fresh, consider Core or compressed NFTs.

Next: Metaplex Core and compressed NFTs—the newer, more efficient approaches to Solana NFTs.