Token Metadata

The NFT standard on Solana.

Create digital assets by adding Metadata to tokens.

Get startedView on GitHub
metadata.rs
offchain-metadata.json
pub struct Metadata {
    pub key: Key,
    pub update_authority: Pubkey,
    pub mint: Pubkey,
    pub data: Data,
    pub primary_sale_happened: bool,
    pub is_mutable: bool,
    // ...
  }

Introduction

Overview

The Token Metadata program is a fundamental program when dealing NFTs and Fungible assets on the Solana blockchain. In this overview, we explain what this program does and how we can leverage its various features at a high level.

Getting Started

Find the language or library of your choice and get started with digital assets on Solana.

API reference

Looking for something specific? Have a peak at our API References and find your answer.

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.

React Flow

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.

React Flow

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.

React Flow

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).

React Flow

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.

React Flow

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.

React Flow

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.

React Flow

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.

React Flow

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 this documentation aim to document it further and explain significant features in their own individual pages.

Next
Getting Started