Solana ProgramExtension Guide
Explanation of all available extensions and how to use them.
The Token-2022 program provides additional functionality on mints and token accounts through an extension model.
Please see the Token-2022 Introduction for more general information about Token-2022 and the concept of extensions.
Setup
See the Token Setup Guide to install the client utilities. Token-2022 shares the same CLI and NPM packages for maximal compatibility.
All JS examples are adapted from the tests, and available in full at the Token JS examples.
Extensions
Mint Close Authority
The Token program allows owners to close token accounts, but it is impossible
to close mint accounts. In Token-2022, it is possible to close mints by initializing
the MintCloseAuthority extension before initializing the mint.
Example: Initializing a mint with mint close authority
Example: Closing a mint
With the MintCloseAuthority extension on the mint and a valid authority, it's
possible to close the mint account and reclaim the lamports on the mint account.
Note: The supply on the mint must be 0.
Transfer Fees
In the Token program, it is impossible to assess a fee on every transfer. The existing systems typically involve freezing user accounts, and forcing them to go through a third party to unfreeze, transfer, and refreeze the accounts.
With Token-2022, it's possible to configure a transfer fee on a mint so that fees are assessed at the protocol level. On every transfer, some amount is withheld on the recipient account, untouchable by the recipient. These tokens can be withheld by a separate authority on the mint.
Important note: Transferring tokens with a transfer fee requires using
transfer_checked or transfer_checked_with_fee instead of transfer.
Otherwise, the transfer will fail.
Example: Creating a mint with a transfer fee
Transfer fee configurations contain a few important fields:
- Fee in basis points: fee assessed on every transfer, as basis points of the transfer amount. For example, with 50 basis points, a transfer of 1,000 tokens yields 5 tokens
- Maximum fee: cap on transfer fees. With a maximum fee of 5,000 tokens, even a transfer of 10,000,000,000,000 tokens only yields 5,000 tokens
- Transfer fee authority: entity that can modify the fees
- Withdraw withheld authority: entity that can move tokens withheld on the mint or token accounts
Let's create a mint with 50 basis point transfer fee, and a maximum fee of 5,000 tokens.
Example: Transferring tokens with the fee checked
As part of the extension, there is a new transfer_checked_with_fee instruction,
which accepts the expected fee. The transfer only succeeds if the fee is correctly
calculated, in order to avoid any surprises during the transfer.
Example: Find accounts with withheld tokens
As users transfer their tokens, transfer fees accumulate in the various recipient
accounts. The withdraw withheld authority, configured at initialization, can move
these tokens wherever they wish using withdraw_withheld_tokens_from_accounts or
harvest_withheld_tokens_to_mint.
Before doing that, however, they must find which accounts have withheld tokens by iterating over all accounts for the mint.
CLI support coming soon!
Example: Withdraw withheld tokens from accounts
With the accounts found, the withheld withdraw authority may move the withheld tokens.
Note: The design of pooling transfer fees at the recipient account is meant to maximize parallelization of transactions. Otherwise, one configured fee recipient account would be write-locked between parallel transfers, decreasing throughput of the protocol.
Example: Harvest withheld tokens to mint
Users may want to close a token account with withheld transfer fees, but it is impossible to close an account that holds any tokens, including withheld ones.
To clear out their account of withheld tokens, they can use the permissionless
harvest_withheld_tokens_to_mint instruction.
The harvest instruction isn't explicitly exposed since it typically isn't needed. It is required before closing an account, however, so we can show the harvest behavior by closing the account:
Example: Withdraw withheld tokens from mint
As users move the withheld tokens to the mint, the withdraw authority may choose to move those tokens from the mint to any other account.
Default Account State
A mint creator may want to restrict who can use their token. There are many heavy-handed approaches to this problem, most of which include going through a centralized service at the beginning. Even through a centralized service, however, it's possible for anyone to create a new token account and transfer the tokens around.
To simplify the restriction, a mint creator may use the DefaultAccountState
extension, which can force all new token accounts to be frozen. This way, users
must eventually interact with some service to unfreeze their account and use
tokens.
Example: Creating a mint with default frozen accounts
Example: Updating default state
Over time, if the mint creator decides to relax this restriction, the freeze
authority may sign an update_default_account_state instruction to make all
accounts unfrozen by default.
Immutable Owner
Token account owners may reassign ownership to any other address. This is useful in many situations, but it can also create security vulnerabilities.
For example, the addresses for Associated Token Accounts are derived based on the owner and the mint, making it easy to find the "right" token account for an owner. If the account owner has reassigned ownership of their associated token account, then applications may derive the address for that account and use it, not knowing that it does not belong to the owner anymore.
To avoid this issue, Token-2022 includes the ImmutableOwner extension, which
makes it impossible to reassign ownership of an account. The Associated Token
Account program always uses this extension when creating accounts.
Example: Explicitly creating an account with immutable ownership
Example: Creating an associated token account with immutable ownership
All associated token accounts have the immutable owner extension included, so it's extremely easy to use the extension.
The CLI will tell us that it's unnecessary to specify the --immutable argument
if it's provided:
Non-Transferable Tokens
To accompany immutably owned token accounts, the NonTransferable mint extension
allows for "soul-bound" tokens that cannot be moved to any other entity. For
example, this extension is perfect for achievements that can only belong to one
person or account.
This extension is very similar to issuing a token and then freezing the account, but allows the owner to burn and close the account if they want.
Example: Creating a non-transferable mint
Required Memo on Transfer
Traditional banking systems typically require a memo to accompany all transfers. The Token-2022 program contains an extension to satisfy this requirement.
By enabling required memo transfers on your token account, the program enforces that all incoming transfers must have an accompanying memo instruction right before the transfer instruction.
Note: This also works in CPI contexts, as long as a CPI is performed to log the memo before invoking the transfer.
Example: Create account with required memo transfers
Example: Enabling or disabling required memo transfers
An account owner may always choose to flip required memo transfers on or off.
Example: Transferring with a memo
When transferring into an account with required transfer memos, you must include a memo instruction before the transfer.
Reallocate
In the previous example, astute readers of the JavaScript code may have noticed
that the EnableRequiredMemoTransfers instruction came after InitializeAccount,
which means that this extension can be enabled after the account is already
created.
In order to actually add this extension after the account is created, however, you may need to reallocate more space in the account for the additional extension bytes.
The Reallocate instruction allows an owner to reallocate their token account
to fit room for more extensions.
Example: Reallocating existing account to enable required memo transfers
The CLI reallocs automatically, so if you use enable-required-transfer-memos
with an account that does not have enough space, it will add the Reallocate
instruction.
Interest-Bearing Tokens
Tokens that constantly grow or decrease in value have many uses in the real world. The most well known example is a bond.
With Token, this has only been possible through proxy contracts that require regular rebase or update operations.
With the Token-2022 extension model, however, we have the possibility to change
how the UI amount of tokens are represented. Using the InterestBearingMint
extension and the amount_to_ui_amount instruction, you can set an interest
rate on your token and fetch its amount with interest at any time.
Interest is continuously compounded based on the timestamp in the network. Due to drift that may occur in the network timestamp, the accumulated interest could be lower than the expected value. Thankfully, this is rare.
Note: No new tokens are ever created, the UI amount returns the amount of tokens plus all interest the tokens have accumulated. The feature is entirely cosmetic.
Example: Create an interest-bearing mint
Example: Update the interest rate
The rate authority may update the interest rate on the mint at any time.
Permanent Delegate
With Token-2022, it's possible to specify a permanent account delegate for a mint. This authority has unlimited delegate privileges over any account for that mint, meaning that it can burn or transfer any amount of tokens.
While this feature certainly has room for abuse, it has many important real-world use cases.
In some jurisdictions, a stablecoin issuer must be able to seize assets from sanctioned entities. Through the permanent delegate, the stablecoin issuer can transfer or burn tokens from accounts owned by sanctioned entities.
It's also possible to implement a Harberger Tax on an NFT, whereby an auction program has permanent delegate authority for the token. After a sale, the permanent delegate can move the NFT from the owner to the buyer if the previous owner doesn't pay the tax.
Example: Create a mint with a permanent delegate
The CLI defaults the permanent delegate to the mint authority, but you can change
it using the authorize command.
CPI Guard
CPI Guard is an extension that prohibits certain actions inside cross-program invocations, to protect users from implicitly signing for actions they can't see, hidden in programs that aren't the System or Token programs.
Users may choose to enable or disable the CPI Guard extension on their token account at will. When enabled, it has the following effects during CPI:
- Transfer: the signing authority must be the account delegate
- Burn: the signing authority must be the account delegate
- Approve: prohibited
- Close Account: the lamport destination must be the account owner
- Set Close Authority: prohibited unless unsetting
- Set Owner: always prohibited, including outside CPI
Background
When interacting with a dapp, users sign transactions that are constructed by frontend code. Given a user's signature, there are three fundamental ways for a dapp to transfer funds from the user to the dapp (or, equivalently, burn them):
- Insert a transfer instruction in the transaction
- Insert an approve instruction in the transaction, and perform a CPI transfer under program authority
- Insert an opaque program instruction, and perform a CPI transfer with the user's authorization
The first two are safe, in that the user can see exactly what is being done, with zero ambiguity. The third is quite dangerous. A wallet signature allows the program to perform any action as the user, without any visibility into its actions. There have been some attempts at workarounds, for instance, simulating the transaction and warning about balance changes. But, fundamentally, this is intractable.
There are two ways to make this much safer:
- Wallets warn whenever a wallet signature is made available to an opaque (non-system, non-token) instruction. Users should be educated to treat the request for a signature on such an instruction as highly suspect
- The token program prohibits CPI calls with the user authority, forcing opaque programs to directly ask for the user's authority
The CPI Guard covers the second instance.
Example: Enable CPI Guard on a token account
Example: Disable CPI Guard on a token account
Transfer Hook
Motivation
Token creators may need more control over how their token is transferred. The most prominent use case revolves around NFT royalties. Whenever a token is moved, the creator should be entitled to royalties, but due to the design of the current token program, it's impossible to stop a transfer at the protocol level.
Current solutions typically resort to perpetually freezing tokens, which requires a whole proxy layer to interact with the token. Wallets and marketplaces need to be aware of the proxy layer in order to properly use the token.
Worse still, different royalty systems have different proxy layers for using their token. All in all, these systems harm composability and make development harder.
Solution
To improve the situation, Token-2022 introduces the concept of the transfer-hook interface and extension. A token creator must develop and deploy a program that implements the interface and then configure their token mint to use their program.
During transfer, Token-2022 calls into the program with the accounts specified at a well-defined program-derived address for that mint and program id. This call happens after all other transfer logic, so the accounts reflect the end state of the transfer.
When interacting with a transfer-hook program, it's possible to send an
instruction - such as Execute (transfer) - to the program with only the
accounts required for the Transfer instruction, and any extra accounts that
the program may require are automatically resolved on-chain! This process is
explained in detail in many of the linked README files below under
Resources.
Resources
The interface description and structs exist at spl-transfer-hook-interface, along with a sample minimal program implementation. You can find detailed instructions on how to implement this interface for an on-chain program or interact with a program that implements transfer-hook in the repository's README.
The spl-transfer-hook-interface library provides offchain and onchain helpers
for resolving the additional accounts required. See
onchain.rs
for usage on-chain, and
offchain.rs
for fetching the additional required account metas with any async off-chain client
like BanksClient or RpcClient.
A usable example program exists at spl-transfer-hook-example. Token-2022 uses this example program in tests to ensure that it properly uses the transfer hook interface.
The example program and the interface are powered by the spl-tlv-account-resolution library, which is explained in detail in the repository's README
Example: Create a mint with a transfer hook
Example: Update transfer-hook program in mint
Example: Manage a transfer-hook program
A sample CLI for managing a transfer-hook program exists at spl-transfer-hook-cli. A mint manager can fork the tool for their own program.
It only contains a command to create the required transfer-hook account for the mint.
First, you must build the transfer-hook program and deploy it:
After that, you can initialize the transfer-hook account:
Metadata Pointer
With the potential proliferation of multiple metadata programs, a mint can have multiple different accounts all claiming to describe the mint.
To make it easy for clients to distinguish, the metadata pointer extension allows a token creator to designate an address that describes the canonical metadata. As you'll see in the "Metadata" section, this address can be the mint itself!
To avoid phony mints claiming to be stablecoins, however, a client must check that the mint and the metadata both point to each other.
Example: Create a mint with a metadata pointer to an external account
Metadata
To facilitate token-metadata usage, Token-2022 allows a mint creator to include their token's metadata directly in the mint account.
Token-2022 implements all of the instructions from the spl-token-metadata-interface.
The metadata extension should work directly with the metadata-pointer extension. During mint creation, you should also add the metadata-pointer extension, pointed at the mint itself.
The tools do this for you automatically.
Example: Create a mint with metadata
Example: Update a field
Example: Add a custom field
Example: Remove a custom field
Group Pointer
Similar to the metadata pointer, the group pointer allows a token creator to designate a group account that describes the mint. However, rather than describing token metadata, the group account describes configurations for grouping tokens together.
When a Token-2022 mint possesses a group pointer, the mint is considered to be a group mint (for example a Collection NFT). Group mints have configurations that allow them to be used as a point of reference for a related set of tokens.
Similar to metadata, the group pointer can point to the mint itself, and a client must check that the mint and the group both point to each other.
Example: Create a mint with a group pointer to an external account
Group
Token-2022 supports grouping of tokens through the group extension. The configurations for a group, which describe things like the update authority and the group's maximum size, can be stored directly in the mint itself.
Token-2022 implements all of the instructions from the spl-token-group-interface.
The group extension works directly with the group-pointer extension. To initialize group configurations within a mint, you must add the group-pointer extension, pointed at the mint itself, during mint creation.
The tools do this for you automatically.
Example: Create a mint with group configurations
Member Pointer
Similar to the metadata pointer and group pointer, the member pointer allows a token creator to designate a member account that describes the mint. This pointer describes configurations for a mint's membership of a group.
When a Token-2022 mint possesses a member pointer, the mint is considered to be a member mint (for example an NFT that belongs to a collection).
Similar to metadata and group, the member pointer can point to the mint itself, and a client must check that the mint and the member both point to each other.
Example: Create a mint with a member pointer to an external account
Member
The member extension also plays a key role in managing groups of tokens with Token-2022. The configurations for a member, which describe things like the group address and the member's number, can be stored directly in the mint itself.
The member extension, like the group extension, works directly with the member-pointer extension. To initialize member configurations within a mint, you must add the member-pointer extension, pointed at the mint itself, during mint creation.
The tools do this for you automatically.
Example: Create a mint with member configurations
Scaled UI Amount
Tokens that can programmatically update amounts uniformly for all users simultaneously have many use cases in the real world. For example, a stock split doubles the number of shares for all holders. Due to the cost and additional complexity, it is currently impractical to mint new tokens to all holders during a split event.
With the Token-2022 extension model, however, we have the possibility to change
how the UI amount of tokens are represented. Using the ScaledUiAmount
extension and the amount_to_ui_amount instruction, you can set a UI multiplier
on your token and fetch its UI amount at any time.
This feature can also be used for dividends or distributing yield.
Note: No new tokens are ever created, the UI amount returns the raw amount of tokens multiplied by the current multiplier. The feature is entirely cosmetic.
Example: Create a mint with a UI amount multiplier
Example: Update the multiplier
The multiplier authority may update the multiplier on the mint at any time, and optionally set a timestamp at which the new multiplier will take effect.
Pausable
Token systems on many blockchains and even some traditional finance applications have the ability to "pause" all activity. During this time, it is not possible transfer, mint, or burn tokens. The Token-2022 program contains an extension to enable this behavior.
By enabling the pausable extension on your mint, the program aborts all tranfers,
mints, and burns when the paused flag is flipped.
Example: Create a pausable mint
Example: Pausing or resuming a mint
The pause authority may always choose to pause or unpause activity on the mint.