Skip to main content

Overview

info

A newer version of this page is available in the Developer Hub. Click here to read it.

Introduction​

The Token Metadata program is one of the most important programs when dealing with NFTs on the Solana blockchain. Its main goal is to attach additional data to Fungible or Non-Fungible Tokens on Solana.

It achieves this using Program Derived Addresses (PDAs) that are derived from the address of Mint Accounts. If you’re not familiar with Solana’s Token program, 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.

A simple diagram showing a user icon followed by three blue rectangles in a straight line. From left to right, the rectangles are labelled: “Wallet Account”, “Token Account” and “Mint Account”. The user icon points to the “Wallet Account”, the “Wallet Account” points to the “Token Account” and the “Mint Account” points to the “Token Account”. Above the “Wallet Account” reads “Someone’s wallet”. Above the “Token Account” reads “Stores the number of tokens owned by the wallet”. Above the “Mint Account” reads “Stores information about the token itself. E.g. its current supply and its authorities.”.

Whilst Mint Accounts contain a few data attributes such as its current supply, it doesn't offer the ability to inject standardized data that can be understood by apps and marketplaces.

This is why the Token Metadata program offers a Metadata Account that attaches itself to a Mint Account via a PDA.

Same diagram as the previous one but this time, the Mint Account points towards a brown pill labelled "PDA" which itself points toward a brown rectangle labelled "Metadata Account". Below the Metadata Account is displayed a list of its attributes.

That Metadata Account holds a lot of valuable information that can be used throughout the ecosystem. For instance, it maintains a list of creators for the token. Each creator has a Verified attribute that, when True, guarantees the token was signed by that creator. Each creator also has a Share attribute that can be used by marketplaces to distribute royalties.

By attaching more data to the Mint Account, the Token Metadata program is able to make Digital Assets of regular on-chain Tokens.

A JSON standard​

One important attribute of the Metadata Account is the URI attribute that points to a JSON file off-chain. This is used to safely provide additional data whilst not being constrained by the fees involved in storing on-chain data. That JSON file follows a certain standard that anyone can use to find useful information on tokens.

Same diagram as the previous one with an arrow pointing out of the "URI" attribute of the Metadata Account, towards a cloud labelled "Off-chain JSON Object". A list of example attributes is displayed below that cloud: "Name, Description, Image, Animation URL, Attributes, etc.".

Note that, this JSON file can be stored using a permanent storage solution such as Arweave to ensure it cannot be updated. Additionally, one can use the Is Mutable attribute of the Metadata Account to make it immutable and, therefore, forbid the URI attribute — and other attributes such as Name and Creators — to ever be changed. Using this combination, we can guarantee the immutability of the off-chain JSON file.

NFTs​

You might be wondering: what has this got to do with NFTs? Well, NFTs are special tokens that are Non-Fungible.

More precisely, NFTs in Solana are Mint Accounts with the following characteristics:

  • It has a supply of 1, meaning only one token is in circulation.
  • It has zero decimals, meaning there cannot be such a thing as 0.5 tokens.
  • It has no mint authority, meaning no one can ever mint additional tokens.

What we end up with is a token that cannot be traded with something of the same kind, which is the definition of a Non-Fungible Token (NFT).

A simplified version of the previous diagram: no data attributes on the Metadata Account nor JSON Object cloud displayed. Instead the Mint Account displays the following attributes: "Mint Authority = None", "Supply = 1" and "Decimals = 0". The Token Account displays only one attribute: "Amount = 1".

In this particular yet popular case, the goal of the Metadata Account is to provide the actual data of that NFT to make it a useful Digital Asset.

Additionally, the Token Metadata program offers another account specifically for NFTs called the Master Edition Account. This account is also a PDA derived from the Mint Account.

Before creating this account, the Token Metadata program will ensure the special characteristics of Non-Fungible Tokens listed above are met. However, it is worth noting that, instead of voiding the Mint Authority, it will transfer both the Mint Authority and the Freeze Authority to the Master Edition PDA to ensure no one can mint or freeze tokens without going through the Token Metadata program. You can read more about why this decision was made in the FAQ.

Thus, the existence of the Master Edition account acts as proof of Non-Fungibility for that Mint Account.

Same diagram as the previous one but the Mint Account points to an additional "PDA" pill which itself points to a new brown rectangle labelled "Master Edition Account". The Mint account also displays the following updated data attributes: "Mint Authority = Edition" and "Freeze Authority = Edition" where both of these attributes point to the new PDA.

Printing Editions​

In addition to being Non-Fungibility evidence, the Master Edition account also allows users to print one or multiple copies of an NFT.

This feature is particularly helpful to creators that want to offer multiple copies of their 1/1 NFTs to their audience.

The Master Edition account contains an optional Max Supply attribute that dictates the maximum amount of NFTs that can be printed that way. If set to 0, printing is disabled. If set to None an unlimited amount of copies can be printed.

The Master Edition NFT, a.k.a. Original NFT, acts as the master record that one can use to print copies, a.k.a. Print NFTs.

Each Print NFT is made of its own Mint Account and its own Metadata Account whose data is copied from the Original NFT. However, instead of having a Master Edition account attached to their Mint Account, Print NFTs use yet another PDA account called an Edition Account. This account keeps track of the edition number and the parent Master Edition it originated from.

Note that the Master Edition account and the Edition account share the same seeds for their PDA. That means an NFT can be one or the other but not both.

Same diagram as the previous one but with a new brown rectangle labelled "Edition Account". The "PDA" pill pointing to the Master Edition Account now also points to the new Edition Account with a big "OR" written on the arrow to show it points to one or the other.

Semi-Fungible Tokens​

Whilst NFTs are the biggest use case of the Token Metadata program, it’s important to notice that the program also works with Fungible Token and, what we call, Semi-Fungible Tokens or Fungible Assets.

At the end of the day, the Metadata account helps attach data to tokens regardless of their fungibility. However, the standard of the off-chain JSON file will vary slightly to accommodate their needs.

To safely identify the fungibility of a token — and, thus, the standard that we should use — the Metadata account keeps track of that information in its Token Standard attribute. This attribute is automatically computed by the program and cannot be manually updated. It can take the following values.

  • NonFungible: The Mint account is associated with a Master Edition account and, therefore, is Non-Fungible. This is your typical NFT standard.
  • NonFungibleEdition: This is the same as NonFungible but the NFT was printed from an Original NFT and, thus, is associated with an Edition account instead of a Master Edition account.
  • FungibleAsset: The Mint account is Fungible but has zero decimal places. Having zero decimals means we can treat the token as an asset whose supply is not limited to one. For instance, Fungible Assets can be used in the gaming industry to store resources such as “Wood” or “Iron”.
  • Fungible: The Mint account is Fungible and has more than one decimal place. This is more likely going to be a token used as a decentralised currency.
  • ProgrammableNonFungible: A special NonFungible token that is frozen at all times to enforce custom authorization rules. See the next section for more information.

You can read more about these standards here.

This image shows three diagrams representing all three fungibility standards. From top to bottom. "NonFungible": Shows a Mint Account with the following attributes "Mint Authority = Edition", "Supply = 1", "Decimals = 0" and "Freeze Authority = Edition". It points to two PDAs, one pointing to a Metadata Account and one pointing to both a Master Edition Account and an Edition Account with a big OR in the middle. "FungibleAsset": Shows a Mint Account with the following attribute: "Decimals = 0". It points to a single PDA which points to a Metadata Account. "Fungible": Shows the same diagram as the "FungibleAsset" diagram but instead of "Decimals = 0", it displays "Decimals > 0" under the Mint Account.

Programmable NFTs​

Because the Token Metadata program is building on top of the Solana Token program, anyone can transfer tokens (fungible or not) without going through the Token Metadata program. Whilst this is great for program composibility, it also means that the Token Metadata program cannot enforce any rules on the tokens it is attached to.

A good example of why this can be problematic is that Token Metadata cannot enforce secondary sales royalties. Whilst there is Seller Fee Basis Points attribute on the Metadata account, it is purely indicative and anyone could create a marketplace that does not honor royalties — which is exactly what happened.

Programmable NFTs were introduced to solve this problem. They are a new opt-in Token Standard that keeps the underlying token accounts frozen at all times. That way, nobody can transfer, lock or burn Programmable NFTs without going through the Token Metadata program.

It is then up to the creators to define custom operation-specific authorization rules that will be enforced by the Token Metadata program. These are defined in a special RuleSet account which is attached to the Metadata account. An example of such RuleSet could be an allowlist of program addresses that honor royalties. RuleSets are part of a new Metaplex program called Token Auth Rules.

You can read more about Programmable NFTs here.

Diagram of a Programmable NFT listing all the accounts they require.

And a lot more​

Whilst this provides a good overview of the Token Metadata program and what it has to offer, there’s still a lot more that can be done with it.

The other pages of the “Token Metadata” section aim to document it further and explain significant features in their own individual pages.

The next three pages focus on helping you get started with the Token Metadata program and provide detailed information on the accounts and instructions it provides, so you get the full picture and can refer back to them in the future.

The next pages act as in-depth guides on certain features offered by the program.

Finally, the last two pages answer frequently asked questions and document version updates.