Solana Token Metadata Explained
Introduction
Token metadata on Solana provides crucial information about SPL tokens and NFTs. It defines how these digital assets appear in wallets, explorers, and marketplaces. Understanding metadata is essential for creators and users alike. This page explains what metadata is, how the Metaplex standard works, common JSON fields, hosting options, update authority, immutability, and best practices.
Token Metadata - Understanding Data Structure on Solana
What is Metadata? (Simple Definition)
Metadata for Solana tokens and NFTs follows a two-part model. There is an on-chain metadata account and off-chain JSON data. The on-chain part stores essential fields like name, symbol, URI pointer, royalties, and verification flags. The off-chain JSON contains rich details like full descriptions, images, and attributes. This separation allows for comprehensive metadata without excessive on-chain storage costs.
Metadata Structure Overview
| Component | Location | Contents | Control |
|---|---|---|---|
| On-chain metadata | Solana blockchain | Name, symbol, URI, royalties, verification flags | Update authority |
| Off-chain JSON | External storage (Arweave/IPFS) | Full descriptions, images, attributes, rich media | Host/pinner |
On-chain fields are stored directly on the Solana blockchain in the metadata account. These include the update authority, immutable flag, short name (32 chars), symbol (10 chars), URI pointer, seller fee basis points, creators array with verification flags, and collection verification. The off-chain JSON holds extended information like full descriptions, high-resolution images, detailed attributes, and multiple media formats.
The Metaplex Token Metadata Standard
The Metaplex Token Metadata standard is widely adopted on Solana. It defines a consistent way to structure and interpret token metadata. This standard ensures that wallets, marketplaces, and explorers can display token information correctly. It uses a metadata PDA (Program Derived Address) to store the on-chain metadata. This PDA is associated with the token’s mint address.
The standard also defines the update authority. This is the key that can modify the metadata. It also includes a creators array. This lists the original creators of the token or NFT. Collection verification signals are also part of this standard. They help confirm the authenticity of NFTs belonging to a specific collection.
Example JSON Metadata
{ "name": "My Awesome Token", "symbol": "MAT", "description": "This is a description of my awesome token.", "image": "https://arweave.net/my-image-hash", "seller_fee_basis_points": 500, "attributes": [ { "trait_type": "Color", "value": "Blue" }, { "trait_type": "Rarity", "value": "Rare" } ], "properties": { "creators": [ { "address": "CreatorPubkey1", "share": 100 } ] }}Core JSON Fields (Quick Reference Table)
This table outlines the core fields found in the off-chain JSON metadata:
| Field | What it means | Required? | Storage | Notes |
|---|---|---|---|---|
name | Display name | ✅ | On-chain + JSON | On-chain limited to 32 chars |
symbol | Short ticker | ❌ | On-chain + JSON | On-chain limited to 10 chars |
description | Human-readable summary | ❌ | JSON only | Markdown/plain text |
image | Primary media URL | ✅ | JSON only | Prefer content-addressed links |
animation_url | Optional rich media | ❌ | JSON only | Video/HTML if supported |
seller_fee_basis_points | Royalty percentage | ❌ | On-chain + JSON | Basis points (500 = 5%) |
attributes | Trait list | ❌ | JSON only | [{ trait_type, value }] |
external_url | Project/site link | ❌ | JSON only | Landing page |
properties.files | Media variants | ❌ | JSON only | MIME types and sizes |
properties.creators | Creator list with shares | ❌ | JSON only | [{ address, share }] |
collection | Collection linkage | ❌ | On-chain + JSON | Can be verified |
Update Authority & Immutability
The update authority is a key that controls changes to a token’s metadata. This authority can modify fields like the URI. It can also update the creators array. This flexibility allows for corrections or evolving project needs.
However, metadata can also be made immutable. This means the update authority is revoked. Once immutable, the metadata cannot be changed. This builds trust with users. It assures them that the token’s properties are permanent. For example, an NFT’s image or name will never change.
Trust & Verification Features
✅ Verified creators: Have confirmed their identity through cryptographic signatures stored in the metadata account
✅ Collection verification: Collections can be verified to group authentic NFTs
✅ Immutability: Once set, metadata cannot be changed, ensuring permanence
These signals help users distinguish legitimate projects from fakes.
Hosting Options & Reliability (Comparison Table)
Choosing where to host your metadata is crucial for its long-term availability. Here are common options:
| Hosting | Pros | Cons | Best for | Reliability |
|---|---|---|---|---|
| Arweave | Durable, content-addressed | Gateway reliance for access | Long-term assets | Very High |
| IPFS (pinned) | Decentralized, flexible | Requires reliable pinning/gateways | Medium/long-term | High |
| HTTPS (CDN) | Fast, familiar | Centralized, link rot risk | Prototypes/docs | Medium |
Images & Media (Best Practices)
Images and media are central to token and NFT metadata. Follow these best practices for optimal display and accessibility:
Media Format Guidelines
| Format | Use Case | Benefits | Considerations |
|---|---|---|---|
| PNG | Graphics, transparency | Lossless, transparent backgrounds | Larger file sizes |
| JPEG | Photographs | Good compression, widely supported | Lossy compression |
| WebP | Modern web | Excellent compression, quality | Limited legacy support |
| GIF/MP4 | Animations | Dynamic content | File size management |
Best Practices Checklist
✅ Recommended formats: Use widely supported image formats like PNG, JPEG, or WebP
✅ Size limits: Keep file sizes reasonable for faster loading
✅ Thumbnails: Provide smaller thumbnail versions for quick loading
✅ Aspect ratios: Maintain consistent aspect ratios to prevent distortion
✅ Animation support: Use animation_url field for videos or interactive HTML
✅ Accessibility: Provide descriptive description and name fields as alt-text equivalents
Versioning & Migrations
Managing metadata over time requires careful planning. If your metadata is mutable, you can rotate URIs safely. This means updating the on-chain pointer to a new off-chain JSON file. This is useful for content updates or bug fixes.
Migration Considerations
| Factor | Impact | Mitigation |
|---|---|---|
| Caching delays | Updates may not appear instantly | Communicate changes clearly to users |
| Gateway changes | IPFS gateways may change | Use multiple gateways, have fallbacks |
| Content updates | Need to maintain URI consistency | Plan migration strategy in advance |
Reference Tables
Table A: On-Chain vs Off-Chain
| Aspect | On-Chain (Metadata Account) | Off-Chain (JSON at URI) |
|---|---|---|
| Who controls | Update authority | Host/pinner |
| Mutability | Toggleable (immutable) | Mutable unless content-addressed |
| Typical contents | Short name, symbol, URI pointer, royalties, creators + verification flags, collection flag | Full description, image(s), attributes, external links, rich media |
Table B: Roles & Permissions
| Role | Can change what? | Scope | Risk if misused |
|---|---|---|---|
| Update authority | Metadata account fields (URI, creators, mutability flag) | Per mint metadata | Unexpected changes, brand confusion |
| Verified creator | Cryptographically signed verification | Stored in creators array | Spoofing if users don’t check verification flag |
| Collection authority | Verifies NFTs belong to a collection | Collection grouping | Fake or misleading collections |
History & Ecosystem Context
The Metaplex Token Metadata program has been the de facto standard on Solana since 2021. It’s required for almost all Solana NFTs to display rich information in wallets and marketplaces. Without metadata, SPL tokens still exist functionally, but they appear as raw token accounts with no visual representation or descriptive information.
Ecosystem Integration
✅ Candy Machine integration and NFT launches
✅ Marketplace compatibility across all major Solana NFT platforms
✅ Wallet display of token information and media
✅ Collection management and verification systems
📝 Conclusion
Metadata shapes how users perceive tokens and NFTs. It is a critical component of their identity. Choose durable hosting solutions. Set clear authorities. Lock metadata when it is final. These steps ensure a reliable and trustworthy experience for your users.
❓ FAQ
Q: What happens when metadata is immutable?
A: When metadata is immutable, its details cannot be changed after creation. This provides permanence and trust for the token or NFT.
Q: Where should I host NFT images and JSON?
A: NFT images and JSON metadata are best hosted on decentralized storage solutions like Arweave or IPFS for durability and censorship resistance.
Q: How do verified creators and collections work?
A: Verified creators and collections are signals of authenticity. Creators can verify their identity, and collections can be verified to group legitimate NFTs from a project.
Q: Can I change the image after minting?
A: Changing the image after minting depends on whether the metadata is mutable. If the metadata is immutable, the image cannot be changed. If it’s mutable, the update authority can change the URI pointing to the image.
📚 References and Further Reading
- Metaplex Documentation - Comprehensive guides for metadata development
- Solana Metadata Documentation - Official Solana resources
- Token Metadata Program Repository - Source code and specifications