Sign in

The SPL Token program in practice

Suggest an edit

On Ethereum every ERC-20 token is its own contract with its own table of balances. On Solana one program, the SPL Token Program, manages every token, and each holder's balance of each token is a separate account. The first follows from programs holding no state, and the second from the limits on a single account.

One program serves every token, and a token is a Mint account

On Ethereum a new token means a new contract. Someone deploys code that implements the ERC-20 interface, and that contract keeps a mapping from address to balance in its own storage (What is ERC-20). A developer coming from there expects a Solana token to be a program too.

A Solana program holds no state, so nothing ties its code to one token. The SPL Token Program is a Solana program, deployed at a fixed and well-known address (TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA), with the same shape as any program you've written, and its code is the same for every token. What makes one token different from another is data. A Mint account stores the rules for one specific token: its total supply, its decimal precision, the authority allowed to mint more, and the authority allowed to freeze holdings. Issuing a new token means creating a new Mint account, and no new code is deployed. Every program that touches tokens does so by CPI-ing into this one well-tested codebase. A second token program, Token-2022, runs beside it with the same Mint and TokenAccount model plus extensions, and the Token-2022 lesson covers it.

Balances cannot live in the Mint, so each holder gets a token account

The next thing an ERC-20 developer would try is to keep all balances of a token in its Mint, the way the contract keeps them in one mapping. Two limits rule that out.

An account's data cannot exceed ten megabytes (accounts). A holder's address alone takes 32 bytes, so one account has room for about 300,000 holders at most.

Every transfer would also write the Mint. The runtime runs two transactions in parallel only if they write different accounts, so no two transfers of the same token could run at the same time (why Solana was built differently).

So each balance gets an account of its own. A TokenAccount references the mint, names an owner, and tracks a balance, and a holder needs one for each mint. Alice's USDC account holds 100 USDC, Bob's USDC account holds 50 USDC, and a protocol's vault PDA holds 1,000 USDC.

USDC mint with Alice, Bob, and Vault PDA token accountsOne USDC Mint holds the supply, decimals, and authorities for the currency. Three separate token accounts point to that same mint: Alice holds 100 USDC, Bob holds 50 USDC, and the Vault PDA holds 1,000 USDC, each stored as raw integer amounts. One Mint, many Token Accounts Mint (USDC) address: USDC mint pubkey supply: 1,150 USDC decimals: 6 mint_authority: Circle's wallet freeze_authority: Circle's wallet Alice's USDC account mint: USDC owner: Alice balance: 100 USDC stored as 100,000,000 raw Bob's USDC account mint: USDC owner: Bob balance: 50 USDC stored as 50,000,000 raw Vault PDA's account mint: USDC owner: Vault PDA balance: 1,000 USDC stored as 1,000,000,000 raw The mint is the currency itself: design, supply, decimals, authorities. A token account is one holder's balance of that currency. Multiple holders, each with their own account, all pointing at the same mint. Mint is the currency. Token account is the bank account holding it.

The mint is created once, by whoever issues the token. The token accounts are created on demand, as users come to hold the token for the first time.

The recipient's token account has to exist before the transfer

The price of this design is that a balance has nowhere to go until its account exists. An ERC-20 transfer to a fresh address needs no setup, because in a mapping every address already has a balance of zero (mappings). On Solana the recipient needs a token account for that mint before the first transfer, and somebody has to create it and pay its rent deposit, about 0.002 SOL. The sender also has to find the address of that account, which is not the recipient's wallet address. Associated Token Accounts, the next lesson, are the convention for both.

A transfer writes two token accounts and nothing else

Alice sends Bob 50 USDC. Her transaction carries one Transfer instruction with three accounts: Alice's USDC account as the source, Bob's USDC account as the destination, and Alice's wallet as the authority. The Token Program reads the owner field of the source account, confirms that it equals the authority, and confirms that the authority signed. Then it subtracts 50 USDC from Alice's account and adds 50 USDC to Bob's, which leaves Alice with 50 and Bob with 100. The mint and Alice's wallet are unchanged.

The amounts in these accounts are raw integers scaled by ten to the power of the mint's decimals. USDC has 6 decimals, so the instruction carries 50,000,000, and Alice's stored balance goes from 100,000,000 to 50,000,000. Every amount that touches the Token Program is a raw integer. Conversion to and from display values happens only at the edges, in your frontend or in your test setup, never inside program logic.

Four instructions cover everyday work

The Token Program has dozens of instructions, but for everyday work you'll reach for four of them constantly.

Transfer, MintTo, Burn, and CloseAccount: the four SPL Token instructionsFour boxes show the SPL Token instructions Transfer, MintTo, Burn, and CloseAccount, each listing its accounts and which one must sign. A note below says every instruction needs one signer plus a few accounts, and Anchor's anchor_spl wraps each one. The four instructions you'll reach for Transfer moves tokens between accounts accounts: from (mut) to (mut) authority signer: authority must sign authority = owner of "from" MintTo creates new tokens, +supply accounts: mint (mut) to (mut) mint_authority signer: mint_authority must sign authority = mint's mint_authority Burn destroys tokens, -supply accounts: from (mut) mint (mut) authority signer: authority must sign authority = owner of "from" CloseAccount closes empty account, refunds rent accounts: account (mut) destination (mut) owner signer: owner must sign balance must be 0 first Every instruction is one signer plus a few accounts. Anchor's anchor_spl wraps each one.
  • Transfer moves tokens from a source token account to a destination. The owner of the source signs: the user's wallet, or a PDA that your program signs for using invoke_signed.
  • MintTo creates new tokens in a destination token account and increases the mint's supply field. The mint authority signs. A protocol that issues its own token uses MintTo, gated by a PDA mint authority, to distribute initial supply or ongoing rewards.
  • Burn decreases a token account's balance and the mint's supply by the same amount, permanently. The owner of the account signs.
  • CloseAccount closes a token account that has a zero balance and refunds the rent deposit to a destination. The owner of the account signs.

InitializeMint creates a new mint with chosen decimals and authorities, and InitializeAccount creates a new token account for a specific mint and owner. In Anchor programs, both are usually wrapped by the init constraint plus the right type, so you rarely call them directly.

Two authorities sit on the mint, and neither can move a holder's balance

Three authorities have power over a token. For each one, the question is what it can do to somebody else's balance.

Three SPL token authorities: mint, freeze, and account ownerThree columns compare mint authority, freeze authority, and token account owner, showing where each is stored, what it controls, and its scope. Two authorities live on the mint, one per currency, while the token account owner is set separately on each token account. Three authorities, three different jobs Mint authority stored on: the Mint controls: MintTo: who can create new tokens typically: - a wallet (USDC) - a PDA (protocol tokens) - None (fixed supply) setting to None: permanent. supply can never grow again. scope: the whole currency "who creates tokens" Freeze authority stored on: the Mint controls: FreezeAccount: lock a specific account typically: - an issuer's wallet (regulated tokens) - None (most tokens) when frozen: no transfers in or out of that account scope: one account at a time "who can freeze a holder" Token account owner stored on: the Token Account controls: Transfer, Burn, CloseAccount typically: - a user's wallet - a PDA (program- controlled vault) scope: one specific account, one specific balance most common: this is what your program touches daily "who controls this balance" Two authorities live on the mint (one per currency). One lives on each token account.

The mint authority lives on a Mint account and controls one thing: who can call MintTo against that mint. Set it to a wallet, that wallet can mint new tokens. Set it to a PDA your program controls, your program can mint via invoke_signed. Set it to None, and the supply is permanently fixed, because once mint authority is None, you cannot reinstate it.

The freeze authority also lives on a Mint and controls FreezeAccount, an instruction that locks a specific token account from doing transfers. Most tokens you'll work with have no freeze authority, since most token issuers don't want the ability to seize holdings. Regulated tokens like real-world-asset representations often do, and the USDC mint in the first diagram has one. If a mint has a freeze authority, every holder is taking on the risk that their balance could be frozen.

The token account owner lives on each individual TokenAccount and controls what can be done with that account's balance: Transfer, Burn, and CloseAccount all require the owner to sign. This is the authority your program will interact with most often, because every time you move tokens, somebody is signing as the source account's owner.

Of the three, only the freeze authority reaches into another holder's account. Holding the mint authority doesn't give you the ability to move other people's tokens, only to create new ones. Holding ownership of a token account doesn't give you the ability to mint new tokens, only to spend that one balance.

In Anchor, each token constraint rules out one substitution

The anchor_spl crate gives you the Mint and TokenAccount types and CPI helpers for each instruction, so you can declare token accounts in your Accounts struct alongside your own program's accounts.

rust
use anchor_spl::token::{Mint, Token, TokenAccount};

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

    pub mint: Account<'info, Mint>,

    #[account(mut, token::mint = mint, token::authority = depositor)]
    pub user_account: Account<'info, TokenAccount>,

    #[account(mut, token::mint = mint, token::authority = vault_pda)]
    pub vault_account: Account<'info, TokenAccount>,

    /// CHECK: this is a PDA, validated by seeds constraint
    #[account(seeds = [b"vault"], bump)]
    pub vault_pda: UncheckedAccount<'info>,

    pub token_program: Program<'info, Token>,
}

The token::mint = ... and token::authority = ... constraints are Anchor checks that the token account is for the right mint and owned by the right authority. Each one rules out a substitution that the Token Program itself would carry out without complaint.

token::authority = vault_pda on vault_account proves that the destination belongs to your vault PDA, and the seeds on vault_pda mean the caller could not choose that address. Without the constraint, a depositor can pass a second token account of their own as vault_account. The owner of the source signed, so the Token Program moves the tokens there, and your handler continues as if the vault had received them.

token::mint = mint proves that both token accounts hold the token whose Mint is in the mint slot. Without it, a depositor can pass accounts of a token they minted themselves, and the handler records a deposit of mint although a different token moved. The caller chose the mint account too, so a vault that accepts one specific token also has to pin that mint's address (root of trust).

For every token account your instruction receives, say which mint it must hold, who must own it, and which constraint stops the caller from passing a different one.