A Developer’s Guide to Token Extensions on Solana

24 January 2024, by Solana Foundation

A Developer’s Guide to Token Extensions on Solana

Token extensions on Solana are the next generation of the Solana Program Library standard. The original Token program brought the basic capabilities of transfer, freeze, and minting tokens. Comprising more than a dozen extensions, developers can now unlock advanced token functionality with remarkable efficiency, requiring only a fraction of the engineering time.

How do I create a token with token extensions?

To get started, use the Solana Tool Suite to create tokens with a CLI. Based on the extension you want to create, your command flags may be different. Below are the flags to add to create tokens with each type of extension.

Extension CLI Flag
Mint close authority --enable-close
Transfer fee --transfer-fee < basis points > < max fee >
Non-transferrable --enable-non-transferable
Interest-bearing --interest-rate < rate >
Permanent delegate --enable-permanent-delegate
Transfer hook --transfer-hook < programID >
Metadata --enable-metadata
Metadata pointer --metadata-address < accountId >
Confidential transfer --enable-confidential-transfers auto

You can enable some extensions on a token account instead of the mint. See the required flags for each below.

Extension Flag
Immutable owner Included by default
Required memo on transfer enable-required-transfer-memos
CPI guard enable-cpi-guard
Default account state --default-account-state < state >

Now that you know what extensions are available, you can create your new token with the following command:

spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb create-token <extension flags>

With token extensions, you can mix and match based on what you need for your project. For example, if you wanted a token with transfer fees and a custom metadata, you would just use the following command to combine the extensions:

spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb create-token --interest-rate 5 --enable-metadata 

Note: While you can mix and match extensions, extensions cannot be added after the token mint is created.

What extensions are compatible with each other?

You can combine multiple extensions together, but some extensions would either not work or not make sense to combine. (For example, you would not want to add token hooks alongside the non-transferable token extension because it would add anything to the token but still cost more to create.) 

The following extension combinations either do not work or will not make sense to combine:

  • Non-transferable + {transfer hooks, transfer fees, confidential transfer}
  • Confidential transfer + fees (available in 1.18)
  • Confidential transfer + transfer hooks (can only see source / destination, can't act on amount)

Other than these exceptions, you have the option to customize with any combination of token extensions that suit your project’s needs.

How do I add custom logic to my tokens with token extensions?

Token extensions enable you to create custom logic with your tokens while retaining full composability with dApps, wallets, programs. The two extensions that can enable this are the transfer hooks and metadata extensions.

Transfer Hooks

Transfer hooks are a powerful new extension that give token issuers greater ability to dictate how users and tokens interact. Now,any developer can insert custom logic into a program to be used with the transfer hook extension. With transfer hooks you can enable capabilities such as enforced on-chain royalties, enabling more elaborate token interactions.

It is important to note that while transfer hooks give the capability to insert custom logic within a transfer, all accounts from the initial transfer are converted to read-only accounts. This means that the signer privileges of the sender do not extend to the transfer hook program. This is to avoid potential unexpected logic executing on someone’s wallet who interacts with a token with transfer hooks, protecting the users.

Start building with transfer hooks today.

Metadata

The Metadata extension empowers token issuers by allowing them to seamlessly embed diverse key-value pairs on-chain, all within a single account. This functionality is particularly beneficial for projects like games, enabling them to incorporate custom metadata within each token. This opens up a myriad of possibilities for games to enhance the capabilities of their in-game tokens and items. Furthermore, the inclusion of custom on-chain metadata paves the way for the establishment of new standards. This presents a unique opportunity for the developer community to collaboratively explore innovative applications of on-chain metadata, all encapsulated under the umbrella of token extensions.

Start building with metadata today.

Do I need to migrate tokens from one standard to another?

Token extensions is a new standard for tokens, but it is not a requirement that anyone migrate from one standard to another. There are reasons why you may want to stick with the original Token standard. If you only need a transfer and freeze functionality and none of the additional features of token extensions, the Token program standard will suit your project just fine. However if you want the ability to add more advanced features, token extensions can help.

There is no way to automatically convert your tokens across standards today. A migration path does exist between the token standards, but it comes with some complications:

  • All tokens of the previous standard must be burned
  • The migration will be user opt-in only

The general recommendation is that if you want token extension capabilities for your token, start with creating your token with that standard.

DEVELOPER NEWSLETTER

For devs. By devs.

Hear about the latest news, commits, and more from the Solana Foundation Developer Relations team.