Solana NFT Metadata Deep Dive
9 min read
Even in the 2022 bear market, Solana NFTs are showing no signs of slowing down. If you are building with Solana NFTs, understanding your NFTs' metadata will make it easier for you to deploy and update NFTs, communicate with your users, and develop innovative applications for NFTs. Whether you're a collector, deciphering your NFTs' metadata will help you understand your NFT and how to find essential information on a Solana block explorer.
In this guide, you will learn:
- What is the Metaplex NFT Token Standard
- How to track and find information about your NFT(s) using Solana Explorer
- What are Certified Collections and Candy Machines, and how do they impact an NFT's metadata
- How to use QuickNode's qn_fetchNFTsByCreator method to find all NFTs of a Collection
What you Will Need
- Basic experience with Solana NFTs
- A CLI terminal for running curl scripts (we'll need this to execute QuickNode's qn_fetchNFTsByCreator method)
The Metaplex NFT Token Standard
Metadata is an essential tool in blockchain protocols to allow additional information to be assigned to a fungible or non-fungible token. This includes data such as the image or traits associated with an NFT, the acronym of a fungible token (e.g., $USDC or $mSOL), or a creator's royalty amount and wallet.
Because Solana's SPL token program only includes minimal metadata (e.g., Token Supply), Metaplex has created a widely adopted protocol for attaching additional metadata to tokens. The Metaplex protocol creates a Program Derived Address (PDA) (for more information on PDAs, check out our Solana Fundamentals Reference Guide) associated with a Mint Account (Mint Accounts are responsible for storing the global information of a Token and Token Accounts store the relationship between a wallet and a Mint Account. Source docs.metaplex.com). To put that differently, every token (fungible or not) has a mint account; and the token's authority can append additional metadata to it using the Metaplex Metadata program via a PDA:
Note: If you have experience building Solana programs, the PDA is seeded by: the public key of the token mint, the public key of the token metadata program, and the term 'metadata.'
The Metaplex Metadata program has standards defined for NFTs, Fungible Tokens, and Fungible Asset/Semi-fungible Tokens (SFTs). This guide will focus on NFTs--for more information on other standards, visit Metaplex Token Standards.
The metadata includes two main parts: data stored on-chain in the PDA and data stored off-chain (usually in some permanent decentralized storage, e.g., Arweave, IPFS, or Shadow Drive) linked in the PDA through a unique URI. The primary purpose for hosting some data off-chain is to limit the cost of rent for a metadata PDA and to allow the metadata program to more flexibly evolve as the needs of the industry change (more information available at Metaplex FAQs).
The following fields are data stored within the on-chain metadata PDA for a given NFT:
- Key - An account discriminator that identifies the type of metadata account
- Update Authority - The public key that is allowed to update this account
- Mint - The public key of the Mint Account it derives from
- Name - The on-chain name of the token (e.g., "Quick Pixel #1")
- Symbol - The on-chain symbol of the token (e.g., "FFF")
- Uri - The URI to the external metadata. This URI points to an off-chain JSON file that contains additional data following a certain standard
- Seller Fee Basis Points - The royalties shared by the creators in basis points — i.e., 550 means 5.5% royalties. Note: though this field is used by most NFT marketplaces, it is not enforced by the Token Metadata program itself
- Primary Sale Happened - A boolean indicating if the token has already been sold at least once. Once flipped to True, it cannot ever be False again. This field can affect the way royalties are distributed
- Is Mutable - A boolean indicating if the metadata account can be updated. Once flipped to False, it cannot ever be True again
- Creators - (optional) An array of creators and their share of the royalties. This array is limited to 5 creators. Each creator object contains the following fields: Address (string of creator's public key), Verified (boolean--true if the creator has signed the NFT), Share (a number [0-100] representing the proportional share of royalties in %. Sum of all creators' share should be 100)
- Additional optional fields include: Creators, Edition Nonce, Token Standard, Collection, Uses, Collection Details
Source: Metaplex Token Metadata Accounts
The following fields are data stored within the JSON that is linked to the PDA for a given NFT via the URI field:
- name - NFT name
- symbol - symbol of the NFT
- description - description of the NFT
- image - URI pointing to the asset's primary image (typically what is associated with an NFT)
- animation_url - URI pointing to the asset's animation if one exists
- external_url -URI pointing to an external URL defining the asset — e.g., the creator's website.
- attributes - an array of attributes defining the characteristics of the asset.
- properties - any files associated with the NFT and a primary file type, "category."
- category (deprecated) - you may see instances of this in older NFTs, however, this information has now been moved to the on-chain metadata.
That's a lot to digest--here's a quick visual showing how the on-chain and off-chain information are related:
Let's try to make sense of it by looking at an example.
Browsing Metadata Using Solana Explorer
Let's look at an NFT on the chain using Solana Explorer and browse the elements of its metadata. I found an Okay Bear that I'm interested in learning more about. Its mint address is H6wPjAGAU1mH83sQ8pJC98kYkGCju5Z5ZpJ4sWcLfn2a. Go to explorer.solana.com and enter the mint address in the search bar. It should redirect you to the NFT's mint page, here.
You should see the image of an NFT with some basic information about it:
If you scroll down, you should see a "Metadata" tab (note: this will only be found on mint pages with associated metadata discovered by the explorer). Click it. You should see our NFT's on-chain metadata outlined in JSON format:
This should look familiar to the "On-Chain Metadata" bullets we outlined above. Solana Explorer abstracts some of our off-chain data (e.g., Traits) in the "Attributes" tab, but where is the rest of our off-chain metadata? If you return to the metadata tab, find the field "uri." If you recall, this is where we link our external JSON. Copy the link and open it in a new tab.
You should see a JSON file in your browser:
Take a moment to browse the data. You should see all of the fields we defined above. Feel free to find the "image" URI and open it in a new tab. That IPFS URI will take you to the original image!
That's it! Between the on-chain data we looked at on Solana Explorer and its off-chain data found through the "URI" field, we have all the data about this NFT.
Before wrapping up, let's take a closer look at Metaplex Certified Collections and Candy Machines and dive into how they impact an NFT's metadata.
Tracking Collections and Creators
Metaplex Certified Collections
In 2022, Metaplex launched Certified Collections to enable on-chain verification and grouping of NFTs. Certifying collections makes it easier for users to query which collection an NFT is a part of, find all NFTs in a collection, and standardize details about the collection. Exchanges and wallets often use collection data to consolidate a folder-like view of sets of NFTs.
Certified Collections are created by assigning the on-chain metadata field "collection" a value of the mint address of a "Collection NFT." A Collection NFT exists to store information about the collection and be a common link between all collection elements. In addition to capturing the public key of the Collection NFT in the "collection" field of an NFT's metadata, you will also see a boolean field, "verified." In order to mark the "verified" field as true, the Authority of the Collection NFT must sign the NFT to prove that it is allowed to be part of the collection (Source: docs.metaplex.com/../certified-collections).
Source/For more information: docs.metaplex.com/../certified-collections
If we go back to our Okay Bear metadata and expand the collection field, we can see that our NFT has been verified that it is a part of collection 3saAedkM9o5g1u5DCqsuMZuC4GRqPB4TuMkvSsSVvGQ3:
Collections can be created while minting an NFT using Candy Machine, JS SDK, or through Metaplex's Certified Collection web tool.
If you looked closely at the on-chain metadata for our NFT, you probably noticed something a little odd in our metadata. We have a verified creator that has a 0% share of revenues. Why would they do that? It's actually quite common--we will discuss that in the next section.
Candy Machine Mints
In addition to automatically certifying collections, Candy Machine includes another handy feature for tracking NFTs associated with a common mint. On mint, they add and verify a new creator in the first position of the creator's list (often referred to as "Creator Zero" as it sits in the 0-index position). The new creator was historically the address of the candy machines, but newer versions use a candy machine mint authority PDA. Since this address isn't a creator, the royalties are automatically set to 0. Since the address is only associated with the mint of a given collection/Candy Machine and since the Candy Machine verifies (signs) the NFT, marketplaces and wallets often use this as an alternative approach to find or track collections of NFTs.
Note: several versions of Candy Machines use this approach, as do several alternative minting tools. Here are the Program IDs of a few:
- CandyMachine v1: cndyAnrLdpjq1Ssp1z8xxDsB8dxe7u4HL5Nxi2K5WXZ
- CandyMachine v2: cndy3Z4yapfJBmL3ShUp5exZKqR3z33thTzeNMm2gRZ
- CandyMachine v3: CndyV3LdqHUfDLmE5naZjVN8rBZz4tqhdefbAnjHG3JR
- MagicEden Forked CM: CMZYPASGWeTz7RNGHaRJfCq2XQ5pYK6nDvVQxzkH51zb
- LaunchMyNft: ArAA6CZC123yMJLUe4uisBEgvfuw2WEvex9iFmFCYiXv
Source: OpenSea Help Center
Let's look at our Bear again:
As you can see, 3xVDoLaecZwXXtN59o6T3Gfxwjcgf8Hc9RfoqBn995P9 is the first creator. It is marked as verified with a 0% royalty share. This usually indicates that our NFT was minted with a Candy Machine. If we search for that address in Solana Explorer, we can see that, in fact, that address is a Candy Machine fork used by Magic Eden (Assigned Program ID: CMZYPASGWeTz7RNGHaRJfCq2XQ5pYK6nDvVQxzkH51zb):
Pretty nifty, right? Now let's use that to find all of the NFTs that are associated with that creator address!
Fetch all NFTs by Creator
QuickNode has built a handy API for fetching all the NFTs by the creator address, qn_fetchNFTsByCreator. To use it, we will use a cURL script in our command line. If you don't already have one, make sure to create a QuickNode endpoint.
Set Up Your QuickNode Endpoint
To build on Solana, you'll need an API endpoint to connect with the network. You're welcome to use public nodes or deploy and manage your own infrastructure; however, if you'd like 8x faster response times, you can leave the heavy lifting to us. See why over 50% of projects on Solana choose QuickNode and sign up for a free account here. We will use a Solana Mainnet node to query the Okay Bears collection.
Copy the HTTP Provider link:
Open a new terminal and paste the following code (make sure to replace the QuickNode URL with your own):
curl https://example.solana-mainnet.quiknode.pro/0123465/ \
-X POST \
-H "Content-Type: application/json" \
Since we are just querying a single NFT, you should see something like this:
Nice job! Check out our Docs for information on paginating results and understanding the returned values.
As you explore NFTs on Solana, we hope you can use these tips to build more efficient and secure applications. Join our Discord if you have any questions, or reach out to us via Twitter.
Ready to dive further into Solana NFTs? Check out these guides to continue on your journey:
- How to Mint an NFT on Solana using Typescript
- How to Deploy an NFT Collection on Solana Using Sugar (Candy Machine)
- How to Update Solana NFT Metadata Using TypeScript
We <3 Feedback!
If you have any feedback or questions on this guide, let us know. We’d love to hear from you!