Sign in

Token-2022 and token extensions

Suggest an edit

Token-2022 is a second token program, deployed alongside the original, in which a mint can switch on optional behaviors called extensions. For a program that accepts a token it did not issue, an extension can change what a transfer of that token does.

A token on Solana has no contract of its own

On Ethereum every token is its own contract, and the issuer writes what a transfer does. A token that inherits OpenZeppelin's ERC20 can override one internal function to add pausing, blacklisting, or a fee on every transfer (ERC-20 lesson).

On Solana a token is a Mint account owned by the Token Program, and the same program moves the balances of every token (SPL Token lesson). An issuer who wants a fee on every transfer has no code of their own in that path. The behavior has to be built into the shared program, as an option that each mint switches on or leaves off.

Token-2022 is built this way. For logic it does not have built in, one extension, the transfer hook, makes it call a program of the issuer's choice during every transfer.

Token-2022 is the same model with an extensions slot

Token-2022 is a separate program from classic SPL Token. It has its own program ID (TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb), its own on-chain accounts, and its own deployed bytecode. It does not supersede classic SPL Token. Both programs run side by side on mainnet. Each new mint is created under one program or the other, and the choice is permanent.

The Mint and TokenAccount struct shapes are the same, and the four core instructions and the three authorities from the SPL Token lesson work the same way.

The difference shows up in two places. Token-2022 mints and token accounts can carry a tail of extension data after the standard fields, in a format called TLV, short for type-length-value, that lets several extensions coexist on one account. And Token-2022 exposes extension-specific instructions on top of the standard ones, for things like setting transfer fee rates or withdrawing accumulated fees.

Classic SPL Token vs Token-2022: same fields plus TLV extensionsTwo side-by-side panels compare Classic SPL Token and Token-2022, each listing its program ID, Mint fields, TokenAccount fields, instructions, extensibility, and tool support. Token-2022 adds "+ extensions (TLV)" to the Mint and TokenAccount fields plus extension-specific instructions, and a caption notes both share the same Mint/TokenAccount shape, instructions, and authorities, with extensions simply appended. Classic SPL Token vs Token-2022: same model, extensions added Classic SPL Token program ID: TokenkegQfeZyiNw... Mint fields: mint_authority supply decimals freeze_authority TokenAccount fields: mint, owner, amount delegate, state, ... instructions: Transfer, MintTo, Burn, CloseAccount, FreezeAccount, ... extensibility: none. fields are fixed. universal support every wallet, DEX, indexer handles it correctly Token-2022 program ID: TokenzQdBNbLqP5VE... Mint fields: mint_authority supply decimals freeze_authority + extensions (TLV) TokenAccount fields: mint, owner, amount delegate, state, ... + extensions (TLV) instructions: all the classic ones, PLUS extension-specific calls extensibility: opt into extensions at mint creation time growing support most tools handle base case, extensions are spottier Same Mint/TokenAccount shape, same instructions, same authorities. Extensions are appended.

An extension is switched on when the mint is created, and it stays for the life of the mint. There's no upgrade path that adds extensions to an existing classic SPL mint. Extensions can stack, so a single mint can carry a transfer fee, an interest-bearing rate, and metadata, all at once. Most extensions are immutable once set. Others let the issuer change parameters later through a configured authority.

An extension can change what your program can assume about a transfer

Token-2022 has more than a dozen extensions, and new ones land in the program over time. The issuer picks them, and your program meets them when a user deposits the token. The diagram shows five of them the way the issuer sees them.

Five Token-2022 extensions: Transfer Fee, Transfer Hook, Interest-Bearing, Default Account State, MetadataFour boxes arranged in a 2x2 grid describe the Transfer Fee, Transfer Hook, Interest-Bearing, and Default Account State extensions, each with what it does, who controls it, and a use case. A fifth box below covers on-mint Metadata, and a footer note says extensions are chosen at mint creation and can be immutable or controlled by an authority. Five extensions worth knowing Transfer Fee a percentage of each transfer is automatically diverted to accumulated fees on the mint controlled by: withdraw_withheld_authority use case: royalties, protocol fees Transfer Hook every transfer triggers a CPI to a designated program before the transfer completes controlled by: hook program's own logic use case: compliance, custom rules Interest-Bearing displayed balance grows over time at a set rate. raw amount in the account doesn't change. controlled by: rate_authority on the mint use case: yield-bearing stablecoins Default Account State new token accounts start frozen. freeze authority must explicitly unfreeze them. controlled by: freeze_authority on the mint use case: KYC-gated tokens, RWAs Metadata (on-mint) name, symbol, URI live directly on the mint, with no separate metadata account. use case: simpler than Metaplex Token Metadata Extensions are chosen at mint creation. Some are immutable once set, others have a configured authority.

The transfer fee extension takes a percentage cut on every transfer, specified in basis points where one basis point equals 0.01%, and withholds it in a hidden balance on the destination token account. The mint's withdraw-withheld authority collects the withheld fees later. The fee applies to every transfer regardless of which dApp or wallet initiated it, with no way for senders or receivers to avoid it.

So less arrives than was sent. Take a mint with a 2% fee, which is 200 basis points. A user deposits 100 tokens into your vault. The vault's balance grows by 98, and the other 2 are withheld for the withdraw-withheld authority. If the handler credits the user with the 100 it passed to the transfer, the vault owes 100 and holds 98. After a second deposit of 100 it owes 200 and holds 196. The first user's withdrawal takes 100 out of the vault, and the second user, who is also owed 100, finds 96 left. A program that accepts such a mint has to credit what arrived, which is the change in the vault's balance, and not the amount it asked to transfer.

The transfer hook extension makes the Token-2022 program perform a CPI into a program of the mint creator's choice on every transfer, passing details about the transfer. The hook program can run arbitrary validation logic before the transfer is allowed to complete. An issuer can use it to allow transfers only between accounts on an approved list, to require a royalty payment alongside a transfer, or to keep its own records current, the way Fragmetric's hook updates the holder's reward balance at the moment of the transfer (lazy loading).

For your program a hook means two things. A program you did not write runs in the middle of every transfer your program makes, and it can reject the transfer. The hook program also needs accounts of its own. Every account a transaction touches has to be declared up front (instructions and transactions), so the client that calls your program has to bring the hook's extra accounts, and your program has to pass them on in the transfer CPI. Most existing infrastructure does not do this, and many production protocols refuse hooked tokens to keep their integration surface small.

The default account state extension makes new token accounts start in the frozen state automatically. Anyone can call InitializeAccount to create the token account, but the resulting account can't send or receive tokens until the freeze authority explicitly unfreezes it. Real-world-asset tokens often need to verify KYC before letting a wallet hold the asset, and with this extension the chain enforces that gate. The vault token account your program creates for such a mint starts frozen too, so deposits into it fail until the issuer's freeze authority unfreezes it.

The other two extensions in the diagram do not change how tokens move. The interest-bearing extension keeps the raw amount field in a token account static and changes only the display value: the program's amount_to_ui_amount instruction returns the amount with interest accrued at a configurable rate stored on the mint. A program that keeps all its accounting in raw amounts is unaffected, and code that compares raw amounts with display amounts gets wrong results. The metadata extension lets a mint carry name, symbol, and URI directly, removing the need for a separate account in the Metaplex Token Metadata program.

Extensions cost compatibility

Classic SPL Token has been the standard for years, and wallets, DEXes, aggregators, and indexers assume it. Token-2022 has been growing in support since 2023, but the picture is uneven. Most tools handle the base case: a Token-2022 mint with no extensions behaves like a classic SPL mint, and most software gets that right. Extensions are where the breakage happens, because each behavior in the previous section is a case that software written for classic SPL does not handle.

So if you issue a mint yourself, classic SPL remains the right default. If you need a specific extension, Token-2022 is the only option, and you have to test against every system your token is going to touch: the major wallets, the DEXes you're targeting, and your own indexers.

token_interface: writing programs that handle both

When you're writing a program that needs to work with either classic SPL or Token-2022 mints, Anchor's anchor_spl::token_interface module provides a unified type that abstracts over the program ID. Instead of Account<'info, TokenAccount> from anchor_spl::token, you use InterfaceAccount<'info, TokenAccount> from anchor_spl::token_interface. The type accepts token accounts from either program.

rust
use anchor_spl::token_interface::{
    Mint, TokenAccount, TokenInterface, transfer_checked, TransferChecked,
};

#[derive(Accounts)]
pub struct Deposit<'info> {
    #[account(mut)]
    pub user: Signer<'info>,

    #[account(mint::token_program = token_program)]
    pub mint: InterfaceAccount<'info, Mint>,

    #[account(
        mut,
        token::mint = mint,
        token::authority = user,
        token::token_program = token_program,
    )]
    pub user_ata: InterfaceAccount<'info, TokenAccount>,

    pub token_program: Interface<'info, TokenInterface>,
}

The Interface<'info, TokenInterface> accepts either the classic SPL Token Program or the Token-2022 program, and the client decides which one goes in the slot. A transfer_checked CPI goes to whatever program is in token_program, and if that program does not own the mint, the CPI fails inside it. The constraints mint::token_program = token_program and token::token_program = token_program check during validation that the mint and the token account are owned by the program in the slot, so a client that pairs a classic mint with Token-2022 fails with ConstraintMintTokenProgram before the handler runs. With those checks in place, your handler doesn't need to branch on the token program.

In token_interface the plain transfer is deprecated in favor of transfer_checked. The "checked" version requires you to pass the mint and the expected decimals as part of the call, and the Token Program verifies the values match. This protects against bugs where the wrong mint or wrong decimals got plumbed through, and it's the recommended pattern for any new code regardless of which token program you're targeting. Classic SPL also has transfer_checked. The reason older code tends to use plain transfer is historical inertia.

Choosing between token and token_interface decides which mints can reach your handler. A program built on anchor_spl::token accepts only classic SPL mints, so it never meets an extension. A program built on token_interface accepts Token-2022 mints as well, and with them transfer fees, hooks, and accounts that start frozen. Pick token_interface for any new program that might encounter Token-2022 mints, which is most new programs. Pick token only if you're certain you'll never need to work with Token-2022, which usually means you're targeting a specific known mint that's classic SPL.

A program built on token_interface can still refuse the extensions it was not written for. The mint lists its extensions in its TLV tail, and the handler can read their types with the Token-2022 crate and fail on any type that is not on its own list. Here the list holds only the two metadata extensions:

rust
use anchor_spl::token_2022::spl_token_2022::{
    extension::{BaseStateWithExtensions, ExtensionType, StateWithExtensions},
    state::Mint as MintState,
};
const ALLOWED: [ExtensionType; 2] = [ExtensionType::MetadataPointer, ExtensionType::TokenMetadata];

let mint_info = ctx.accounts.mint.to_account_info();
let mint_data = mint_info.try_borrow_data()?;
let mint = StateWithExtensions::<MintState>::unpack(&mint_data)?;
for ext in mint.get_extension_types()? {
    require!(ALLOWED.contains(&ext), VaultError::UnsupportedMint);
}

A classic SPL mint has no TLV tail, so it passes with an empty list. A mint with a transfer fee, a transfer hook, or the default account state extension fails, and so does a mint with an extension added to Token-2022 after the program was written.

Three questions before your program accepts Token-2022 mints

What does the program record when 100 tokens are sent and 98 arrive? Who brings the hook program's accounts, and what happens to your users when the hook rejects a transfer? What happens when the token account your program creates starts frozen? Until the program has an answer to each of them, build it on anchor_spl::token, which accepts only classic SPL mints, or refuse those extensions with a check like the one above.