Tokens and CPI

This section covers the common SPL token operations from an Anchor program. The examples focus on the legacy Token Program path because that surface is the most complete today. Token-2022 interface accounts and extension readers are covered separately.

A mint defines a token. A token account holds a balance for one mint and one authority. Minting creates new units of a token, and transferring moves existing units between token accounts. Anchor checks the mint, authority, and writable flags before your handler invokes the Token Program.

The SPL surface mirrors Anchor’s normal account model:

• Account<Mint> zero-copies SPL mint data
• Account<TokenAccount> zero-copies SPL token account data
• mint::* and token::* constraints are downstream AccountConstraint markers
• CPI helpers come from anchor_spl_v2::token::cpi
• CPI account structs are built from cpi_handle() and cpi_handle_mut()

Common workflow#

Most token programs follow this order:

1. Create a mint with mint::decimals and mint::authority.
2. Create token accounts with token::mint and token::authority.
3. Mint tokens by invoking token::cpi::mint_to or mint_to_checked.
4. Transfer tokens by invoking token::cpi::transfer_checked.

For program-controlled tokens, make the mint authority or token account authority a PDA and pass signer seeds through CpiContext::with_signer().

A mint account is the Token Program account that represents a token on Solana. The mint address is the token’s unique identifier, and the account stores global token state such as supply, decimals, mint authority, and optional freeze authority.

Anchor models the legacy SPL Token mint as Account<Mint> from anchor_spl_v2::mint. The wrapper is zero-copy over the SPL Token mint layout. It does not add an Anchor discriminator because the account is owned and initialized by the Token Program.

Mint account data#

The base mint layout is 82 bytes:

pub struct Mint {
    mint_authority_flag: [u8; 4],
    mint_authority: Address,
    supply: [u8; 8],
    decimals: u8,
    is_initialized: u8,
    freeze_authority_flag: [u8; 4],
    freeze_authority: Address,
}

The fields are private in anchor-spl-v2. Read them through accessors such as supply(), decimals(), is_initialized(), mint_authority(), and freeze_authority().

Usage#

The usual import shape is:

use {
    anchor_lang_v2::prelude::*,
    anchor_spl_v2::mint::{self, Mint},
};

The account constraints handle the full setup. They create the account, allocate the Token Program mint size, transfer ownership to the Token Program, and invoke InitializeMint2:

#[derive(Accounts)]
pub struct CreateMint {
    #[account(mut)]
    pub payer: Signer,
    pub authority: UncheckedAccount,
    #[account(
        init,
        payer = payer,
        mint::decimals = 6,
        mint::authority = authority,
    )]
    pub mint: Account<Mint>,
    pub token_program: Program<Token>,
    pub system_program: Program<System>,
}

The handler does not need to call the token program manually. Initialization happens in the generated account-validation path before the handler runs:

pub fn create_mint(_ctx: &mut Context<CreateMint>) -> Result<()> {
    Ok(())
}

Account constraints#

Use these constraints together for a new legacy SPL Token mint:

After initialization, the same namespaced constraints validate existing mints:

#[derive(Accounts)]
pub struct UseMint {
    pub expected_authority: UncheckedAccount,
    #[account(
        mint::decimals = 6,
        mint::authority = expected_authority,
    )]
    pub mint: Account<Mint>,
}

Address choices#

#[derive(Accounts)]
pub struct CreateMint {
    #[account(mut)]
    pub payer: Signer,
    pub authority: UncheckedAccount,
    #[account(
        init,
        payer = payer,
        mint::decimals = 6,
        mint::authority = authority,
        mint::freeze_authority = authority,
    )]
    pub mint: Account<Mint>,
    pub token_program: Program<Token>,
    pub system_program: Program<System>,
}

#[derive(Accounts)]
pub struct CreateMint {
    #[account(mut)]
    pub payer: Signer,
    #[account(seeds = [b"mint-authority"], bump)]
    pub mint_authority: UncheckedAccount,
    #[account(
        init,
        payer = payer,
        seeds = [b"mint"],
        bump,
        mint::decimals = 6,
        mint::authority = mint_authority,
        mint::freeze_authority = mint_authority,
    )]
    pub mint: Account<Mint>,
    pub token_program: Program<Token>,
    pub system_program: Program<System>,
}

A token account stores one authority’s balance for one mint. Each token account records a mint, an authority, an amount, and optional delegate, wrapped-SOL, and close-authority state.

Anchor models the legacy SPL Token account as Account<TokenAccount> from anchor_spl_v2::token. Like Account<Mint>, it is zero-copy over the Token Program layout and starts at byte offset 0 instead of using an Anchor discriminator.

Token account data#

The base token account layout is 165 bytes:

pub struct TokenAccount {
    mint: Address,
    owner: Address,
    amount: [u8; 8],
    delegate_flag: [u8; 4],
    delegate: Address,
    state: u8,
    is_native_flag: [u8; 4],
    native_amount: [u8; 8],
    delegated_amount: [u8; 8],
    close_authority_flag: [u8; 4],
    close_authority: Address,
}

The fields are private. Read them with accessors such as mint(), owner(), amount(), delegate(), delegated_amount(), is_initialized(), is_frozen(), and close_authority().

Account kinds#

There are three common ways to choose the token-account address:

Anchor has high-level init support for keypair accounts and your program’s PDAs through token::* constraints. For associated token accounts, the current surface exposes address derivation and validation helpers. High-level associated_token::* init constraints are still in progress.

Imports#

Import the mint and token account wrappers together:

use {
    anchor_lang_v2::prelude::*,
    anchor_spl_v2::{
        mint::Mint,
        token::{self, TokenAccount},
    },
};

Account patterns#

#[derive(Accounts)]
pub struct CreateTokenAccount {
    #[account(mut)]
    pub payer: Signer,
    pub mint: Account<Mint>,
    pub authority: UncheckedAccount,
    #[account(
        init,
        payer = payer,
        token::mint = mint,
        token::authority = authority,
    )]
    pub token_account: Account<TokenAccount>,
    pub token_program: Program<Token>,
    pub system_program: Program<System>,
}

pub fn create_token_account(_ctx: &mut Context<CreateTokenAccount>) -> Result<()> {
    Ok(())
}

use anchor_spl_v2::associated_token::get_associated_token_address;

#[derive(Accounts)]
pub struct UseAssociatedTokenAccount {
    pub authority: Signer,
    pub mint: Account<Mint>,
    #[account(
        mut,
        token::mint = mint,
        token::authority = authority,
        address = get_associated_token_address(
            authority.address(),
            mint.account().address(),
            &Token::id(),
        ),
    )]
    pub token_account: Account<TokenAccount>,
}

#[derive(Accounts)]
pub struct CreateVaultTokenAccount {
    #[account(mut)]
    pub payer: Signer,
    pub mint: Account<Mint>,
    #[account(seeds = [b"vault-authority", mint.address().as_ref()], bump)]
    pub vault_authority: UncheckedAccount,
    #[account(
        init,
        payer = payer,
        seeds = [b"vault-token", mint.address().as_ref()],
        bump,
        token::mint = mint,
        token::authority = vault_authority,
    )]
    pub token_account: Account<TokenAccount>,
    pub token_program: Program<Token>,
    pub system_program: Program<System>,
}

Interface accounts#

Account<TokenAccount> accepts legacy Token Program accounts with the exact 165-byte base layout. Use InterfaceAccount<TokenAccount> when a read or validation path should accept Token-2022 accounts with TLV extension data after the base state:

use anchor_spl_v2::token_interface::InterfaceAccount;

#[derive(Accounts)]
pub struct UseEitherTokenProgram {
    pub mint: InterfaceAccount<Mint>,
    #[account(
        token::mint = mint,
        token::authority = authority,
    )]
    pub token_account: InterfaceAccount<TokenAccount>,
    pub authority: Signer,
}

For high-level initialization through an interface account, include token::token_program = token_program and use Program<Token> for the current legacy Token Program path. Token-2022 account creation and extension setup should use lower-level Token-2022 APIs, then validate the resulting account through InterfaceAccount<TokenAccount>.

Account constraints#

Use these constraints together for a new legacy SPL Token account:

After initialization, the same constraints validate existing accounts:

#[derive(Accounts)]
pub struct UseTokenAccount {
    pub mint: Account<Mint>,
    pub authority: Signer,
    #[account(
        mut,
        token::mint = mint,
        token::authority = authority,
    )]
    pub token_account: Account<TokenAccount>,
}

Use init_if_needed only when the instruction is designed to be idempotent. The existing-account branch still checks token::mint and token::authority, so a caller cannot pass a token account for a different mint or authority.

Client and test checks#

In Rust tests, derive the expected ATA or PDA explicitly and pass that address to the generated instruction helper. For PDA token accounts, keep the seed list in one place in the program and the test. Array-form seeds also help IDL clients understand the derivation.

Minting creates new units of a token by invoking the Token Program’s MintTo instruction. The mint authority stored on the mint account must authorize the CPI, and the destination must be a token account for that mint.

Minting uses typed CPI account structs. The account values passed into CPI structs are CpiHandle<'a> values from cpi_handle() or cpi_handle_mut(). The helpers come from anchor_spl_v2::token::cpi.

How minting works#

The token program checks three things before increasing supply:

amount is always in base units. For a mint with 6 decimals, 1_000_000 represents one whole token.

Imports#

Import the CPI module with the mint and token account wrappers:

use {
    anchor_lang_v2::prelude::*,
    anchor_spl_v2::{
        mint::Mint,
        token::{self, cpi as token_cpi, TokenAccount},
    },
};

CPI patterns#

#[derive(Accounts)]
pub struct MintTokens {
    #[account(mut, mint::authority = authority)]
    pub mint: Account<Mint>,
    #[account(mut, token::mint = mint)]
    pub token_account: Account<TokenAccount>,
    pub authority: Signer,
    pub token_program: Program<Token>,
}

pub fn mint_tokens(ctx: &mut Context<MintTokens>, amount: u64) -> Result<()> {
    let accounts = token_cpi::accounts::MintTo {
        mint: ctx.accounts.mint.cpi_handle_mut(),
        to: ctx.accounts.token_account.cpi_handle_mut(),
        authority: ctx.accounts.authority.cpi_handle(),
    };
    let cpi = CpiContext::new(ctx.accounts.token_program.address(), accounts);
    token_cpi::mint_to(cpi, amount)
}

#[derive(Accounts)]
pub struct MintTokens {
    #[account(mut, mint::authority = mint_authority)]
    pub mint: Account<Mint>,
    #[account(mut, token::mint = mint)]
    pub token_account: Account<TokenAccount>,
    #[account(seeds = [b"mint-authority"], bump)]
    pub mint_authority: UncheckedAccount,
    pub token_program: Program<Token>,
}

pub fn mint_tokens(ctx: &mut Context<MintTokens>, amount: u64) -> Result<()> {
    let signer_seeds: &[&[&[u8]]] = &[&[b"mint-authority", &[ctx.bumps.mint_authority]]];
    let accounts = token_cpi::accounts::MintTo {
        mint: ctx.accounts.mint.cpi_handle_mut(),
        to: ctx.accounts.token_account.cpi_handle_mut(),
        authority: ctx.accounts.mint_authority.cpi_handle(),
    };
    let cpi = CpiContext::new(ctx.accounts.token_program.address(), accounts)
        .with_signer(signer_seeds);
    token_cpi::mint_to(cpi, amount)
}

Checked minting#

Use mint_to_checked when the caller should also provide the expected decimals:

pub fn mint_tokens_checked(
    ctx: &mut Context<MintTokens>,
    amount: u64,
    decimals: u8,
) -> Result<()> {
    let accounts = token_cpi::accounts::MintToChecked {
        mint: ctx.accounts.mint.cpi_handle_mut(),
        to: ctx.accounts.token_account.cpi_handle_mut(),
        authority: ctx.accounts.authority.cpi_handle(),
    };
    let cpi = CpiContext::new(ctx.accounts.token_program.address(), accounts);
    token_cpi::mint_to_checked(cpi, amount, decimals)
}

This is a good public-instruction default because it forces the caller and program to agree on the mint’s decimal configuration.

Destination checks#

Validate the destination account before the CPI:

#[derive(Accounts)]
pub struct MintToVault {
    pub authority: Signer,
    #[account(mut, mint::authority = authority)]
    pub mint: Account<Mint>,
    #[account(
        mut,
        token::mint = mint,
        token::authority = vault_authority,
    )]
    pub vault: Account<TokenAccount>,
    pub vault_authority: UncheckedAccount,
    pub token_program: Program<Token>,
}

token::mint = mint prevents minting into a token account for a different mint. token::authority = vault_authority is useful when the destination must be a specific vault or program-controlled token account.

Client and test checks#

Rust tests should verify both supply and destination balance after the instruction. The SPL wrappers expose accessors for this:

let mint = svm.get_account(&mint_address).expect("mint");
let mint_state: &anchor_spl_v2::mint::Mint = bytemuck::from_bytes(&mint.data);
assert_eq!(mint_state.supply(), amount);

For Token-2022 or interface-account flows, use InterfaceAccount<Mint> and InterfaceAccount<TokenAccount> in the program accounts, then choose the token program explicitly with mint::token_program or token::token_program. The legacy token_cpi::mint_to helper shown here targets the legacy Token Program surface.

Transferring tokens moves units between two token accounts for the same mint. The source token account’s authority must authorize the CPI, and both token accounts must be writable because their balances change.

Anchor exposes transfer helpers under anchor_spl_v2::token::cpi. Prefer transfer_checked for user-facing transfers because it includes the mint account and verifies the mint decimals.

Imports#

Import the token CPI module and account wrappers:

use {
    anchor_lang_v2::prelude::*,
    anchor_spl_v2::{
        mint::Mint,
        token::{self, cpi as token_cpi, TokenAccount},
    },
};

Transfer patterns#

#[derive(Accounts)]
pub struct TransferTokens {
    pub mint: Account<Mint>,
    #[account(
        mut,
        token::mint = mint,
        token::authority = authority,
    )]
    pub from: Account<TokenAccount>,
    #[account(mut, token::mint = mint)]
    pub to: Account<TokenAccount>,
    pub authority: Signer,
    pub token_program: Program<Token>,
}

pub fn transfer_tokens(
    ctx: &mut Context<TransferTokens>,
    amount: u64,
    decimals: u8,
) -> Result<()> {
    let accounts = token_cpi::accounts::TransferChecked {
        from: ctx.accounts.from.cpi_handle_mut(),
        mint: ctx.accounts.mint.cpi_handle(),
        to: ctx.accounts.to.cpi_handle_mut(),
        authority: ctx.accounts.authority.cpi_handle(),
    };
    let cpi = CpiContext::new(ctx.accounts.token_program.address(), accounts);
    token_cpi::transfer_checked(cpi, amount, decimals)
}

pub fn transfer(ctx: &mut Context<TransferTokens>, amount: u64) -> Result<()> {
    let accounts = token_cpi::accounts::Transfer {
        from: ctx.accounts.from.cpi_handle_mut(),
        to: ctx.accounts.to.cpi_handle_mut(),
        authority: ctx.accounts.authority.cpi_handle(),
    };
    let cpi = CpiContext::new(ctx.accounts.token_program.address(), accounts);
    token_cpi::transfer(cpi, amount)
}

PDA authority#

When a program controls the source token account, set the token account authority to a PDA and sign the CPI with that PDA’s seeds:

#[derive(Accounts)]
pub struct TransferFromVault {
    pub mint: Account<Mint>,
    #[account(seeds = [b"vault-authority", mint.address().as_ref()], bump)]
    pub vault_authority: UncheckedAccount,
    #[account(
        mut,
        token::mint = mint,
        token::authority = vault_authority,
    )]
    pub vault: Account<TokenAccount>,
    #[account(mut, token::mint = mint)]
    pub recipient: Account<TokenAccount>,
    pub token_program: Program<Token>,
}

pub fn transfer_from_vault(
    ctx: &mut Context<TransferFromVault>,
    amount: u64,
    decimals: u8,
) -> Result<()> {
    let signer_seeds: &[&[&[u8]]] = &[&[
        b"vault-authority",
        ctx.accounts.mint.address().as_ref(),
        &[ctx.bumps.vault_authority],
    ]];
    let accounts = token_cpi::accounts::TransferChecked {
        from: ctx.accounts.vault.cpi_handle_mut(),
        mint: ctx.accounts.mint.cpi_handle(),
        to: ctx.accounts.recipient.cpi_handle_mut(),
        authority: ctx.accounts.vault_authority.cpi_handle(),
    };
    let cpi = CpiContext::new(ctx.accounts.token_program.address(), accounts)
        .with_signer(signer_seeds);
    token_cpi::transfer_checked(cpi, amount, decimals)
}

The authority PDA is separate from the token account in this example, which keeps the account list easy to reason about. A program can use the same PDA as both the token account address and authority when it has a specific reason to do so.

Common validation checks#

Use constraints to reject mismatched accounts before the CPI runs:

For associated token accounts, derive the expected address with get_associated_token_address and use address = ... or constraint = ....

Token-2022 uses the same base mint and token-account layouts as the legacy Token Program, then appends extension data in a TLV section. A mint or token account can opt into features like transfer fees, metadata pointers, permanent delegates, and transfer hooks.

Anchor handles Token-2022 in two layers:

• InterfaceAccount<T> accepts accounts owned by either the legacy Token Program or Token-2022.
• anchor_spl_v2::extensions parses supported fixed-size TLV extension structs from the account tail.

Interface accounts#

Use InterfaceAccount<Mint> or InterfaceAccount<TokenAccount> when an instruction should accept either Token or Token-2022-owned accounts:

use {
    anchor_lang_v2::prelude::*,
    anchor_spl_v2::{
        mint::Mint,
        token::TokenAccount,
        token_interface::InterfaceAccount,
    },
};

#[derive(Accounts)]
pub struct ReadAnyTokenAccount {
    pub mint: InterfaceAccount<Mint>,
    #[account(token::mint = mint)]
    pub token_account: InterfaceAccount<TokenAccount>,
}

InterfaceAccount<T> is a transparent wrapper over the same base SPL types. It relaxes ownership validation to accept both token program IDs, and it allows Token-2022 accounts to be larger than the base layout because extension data follows the base state.

Constraints#

The usual namespaced constraints work on interface accounts:

For a public instruction that accepts either token program, include the token program account in the account list and validate ownership with token::token_program or mint::token_program. If the token program field is unchecked, also constrain it to one of the two known token program IDs before using it for initialization or CPI:

#[derive(Accounts)]
pub struct ReadToken2022Account {
    #[account(
        constraint = *token_program.address() == Token::id()
            || *token_program.address() == Token2022::id()
    )]
    pub token_program: UncheckedAccount,
    pub mint: InterfaceAccount<Mint>,
    #[account(
        token::mint = mint,
        token::token_program = token_program,
    )]
    pub token_account: InterfaceAccount<TokenAccount>,
}

Use a concrete Program<Token> or Program<Token2022> field when an instruction should accept only one token program.

Interface init#

The current high-level interface init path is for the legacy Token Program. Useful when initializing a base SPL mint or token account while keeping the account type as InterfaceAccount<T> for later read and validation paths:

#[derive(Accounts)]
pub struct InitInterfaceMint {
    #[account(mut)]
    pub payer: Signer,
    pub authority: UncheckedAccount,
    pub token_program: Program<Token>,
    #[account(
        init,
        payer = payer,
        mint::decimals = 6,
        mint::authority = authority,
        mint::token_program = token_program,
    )]
    pub mint: InterfaceAccount<Mint>,
    pub system_program: Program<System>,
}

For Token-2022 account creation or extension selection, use lower-level Token-2022 APIs, then validate or read the resulting account with InterfaceAccount<T>. Most Token-2022 extensions must be selected before the base account is initialized.

Extension data#

Token-2022 stores extension data after the base mint or token-account layout. anchor_spl_v2::extensions reads supported TLV entries by type:

use anchor_spl_v2::extensions::{self, TransferFeeConfig};

pub fn read_fee_config(
    ctx: &mut Context<ReadFeeConfig>,
    expected_bps: u16,
) -> Result<()> {
    let ext: &TransferFeeConfig =
        extensions::get_mint_extension(ctx.accounts.mint.account())?;
    require_eq!(ext.newer_transfer_fee.basis_points(), expected_bps);
    Ok(())
}

#[derive(Accounts)]
pub struct ReadFeeConfig {
    pub mint: InterfaceAccount<Mint>,
}

Use get_mint_extension::<T>() for mint extensions and get_token_account_extension::<T>() for token-account extensions.

Supported extension structs#

The current helpers include fixed-size structs for common extensions:

Variable-length extension data and extension initialization flows are still settling. Keep Token-2022 programs close to the source APIs, and add focused tests for every extension path.