SPL Token em Programas

Programas on-chain interagem com o SPL Token por meio de invocações entre programas (CPIs). O anchor-spl da Anchor 0.32.1 envolve a validação de conta, desserialização e construtores de instruções para lógica de token de nível de produção.

Receita

use anchor_spl::token::{self, Mint, Token, TokenAccount, TransferChecked};
 
pub mint: Account<'info, Mint>,
#[account(mut, token::mint = mint, token::authority = authority)]
pub from: Account<'info, TokenAccount>,
pub token_program: Program<'info, Token>,
// ...
token::transfer_checked(cpi_ctx, amount, decimals)?;

Quando usar isso:

• Programas de escrow, cofre ou pagamento que movimentam tokens SPL
• Validando ATAs de usuários em instruções DeFi
• Cunhando tokens de recompensa de uma autoridade de cunhagem de PDA
• Aplicando regras de correspondência de cunhagem e de signatário em CPIs de token

Exemplo de trabalho

use anchor_lang::prelude::*;
use anchor_spl::associated_token::AssociatedToken;
use anchor_spl::token::{self, Mint, Token, TokenAccount, TransferChecked};
 
#[derive(Accounts)]
pub struct Deposit<'info> {
    pub mint: Account<'info, Mint>,
    #[account(
        mut,
        associated_token::mint = mint,
        associated_token::authority = user,
        associated_token::token_program = token_program,
    )]
    pub user_ata: Account<'info, TokenAccount>,
    #[account(
        mut,
        token::mint = mint,
        token::authority = vault_authority,
    )]
    pub vault_ata: Account<'info, TokenAccount>,
    pub user: Signer<'info>,
    /// CHECK: PDA authority over vault ATA
    pub vault_authority: UncheckedAccount<'info>,
    pub token_program: Program<'info, Token>,
    pub associated_token_program: Program<'info, AssociatedToken>,
    pub system_program: Program<'info, System>,
}
 
pub fn deposit(ctx: Context<Deposit>, amount: u64) -> Result<()> {
    require!(amount > 0, ErrorCode::ZeroAmount);
    let decimals = ctx.accounts.mint.decimals;
    let cpi = CpiContext::new(
        ctx.accounts.token_program.to_account_info(),
        TransferChecked {
            mint: ctx.accounts.mint.to_account_info(),
            from: ctx.accounts.user_ata.to_account_info(),
            to: ctx.accounts.vault_ata.to_account_info(),
            authority: ctx.accounts.user.to_account_info(),
        },
    );
    token::transfer_checked(cpi, amount, decimals)?;
    Ok(())
}
 
#[error_code]
pub enum ErrorCode {
    ZeroAmount,
}

O que isso demonstra:

• Account<'info, TokenAccount> valida que o proprietário é o programa Token clássico - ele rejeita contas Token-2022
• As restrições token::mint e associated_token reduzem as verificações manuais de pubkey
• transfer_checked inclui decimais para um manuseio de ativos mais seguro; o Transfer não verificado está obsoleto e o Token-2022 o rejeita em mints com taxa de transferência

Aprofundamento

Como funciona

• ID do programa SPL Token: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
• CPI passa a instrução serializada + metas de conta para o programa Token
• Requisitos de signatário: proprietário para débito, autoridade de cunhagem para mint_to, etc.
• anchor_spl::token_interface suporta Token-2022 com o tipo TokenInterface

Instruções comuns de CPI

Notas em Rust

use anchor_lang::prelude::*;
use anchor_spl::token_interface::{Mint, TokenAccount, TokenInterface};
 
// Nunca misture as duas árvores de módulos. `anchor_spl::token::{Mint, TokenAccount}` são
// apenas para Token clássico e sua verificação de proprietário rejeita contas Token-2022; os
// tipos `token_interface` despacham para ambos os programas.
#[derive(Accounts)]
pub struct EitherProgram<'info> {
    pub mint: InterfaceAccount<'info, Mint>,
    #[account(mut, token::mint = mint)]
    pub from: InterfaceAccount<'info, TokenAccount>,
    pub token_program: Interface<'info, TokenInterface>,
}

Armadilhas

• Falta de verificação de igualdade da cunhagem - ativo errado do ATA do cofre. Correção: restrição token::mint = mint em todas as contas de token.
• UncheckedAccount como autoridade do cofre - sem validação de sementes de PDA. Correção: restrições seeds + bump no PDA de autoridade.
• Conta token_program incorreta - Program<'info, Token> fixa Tokenkeg..., e Account<'info, TokenAccount> rejeita contas de propriedade do Token-2022, portanto, não há um caminho de "apenas passe a conta do programa Token-2022". Correção: altere toda a estrutura da conta para anchor_spl::token_interface (InterfaceAccount + Interface<TokenInterface>), ou em Rust nativo use spl_token_2022::instruction::* - spl_token::instruction::* chama check_program_account e retorna IncorrectProgramId para qualquer ID que não seja Tokenkeg....
• Mistura de tipos anchor_spl::token e anchor_spl::token_interface - a verificação de proprietário dos tipos clássicos rejeita cunhagens de extensão. Correção: escolha uma árvore de módulos por estrutura de conta.
• PDA não pode assinar transferência - sementes with_signer faltando. Correção: CpiContext::new_with_signer com sementes do cofre.
• Profundidade extra de CPI via hooks do Token-2022 - uma cunhagem com hook adiciona uma CPI aninhada a um programa de hook separado, custando profundidade e CU. Um hook nunca pode reentrar em um programa já na pilha (incluindo o seu ou o próprio Token-2022) - Solana rejeita isso com ReentrancyNotAllowed. Correção: orçamente CU e profundidade de CPI; consulte a documentação do hook de transferência.

cGJxcnRodnFyZi52YnxwdHZiMjgwfDIwMjYwNw==

Alternativas

Perguntas frequentes

Relacionado

• Contas de Token Associadas (ATAs) - Restrições de ATA
• Transferências e Delegados - Fluxos de delegação
• Invocações entre Programas (CPI) - Fundamentos de CPI

Versões da Stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.