spl-token & spl-associated-token-account

O programa SPL Token define "mints" (cunhagens) e contas de token; o programa Associated Token Account (ATA) deriva endereços canônicos de carteira por "mint". Os crates Rust spl-token e spl-associated-token-account (mais os wrappers anchor-spl) codificam layouts e helpers de CPI para os programas e clientes do Agave 4.1.1.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

[dependencies]
spl-token = "7.0"
spl-associated-token-account = "6.0"

use spl_associated_token_account::get_associated_token_address;
use spl_token::state::Mint;
 
let ata = get_associated_token_address(&owner, &mint);

Quando usar isso:

• Programas que transferem, cunham ou queimam tokens SPL via CPI.
• Clientes que resolvem endereços ATA antes de construir instruções.
• Análise de decimais de "mint" e saldos de contas de token fora da cadeia.
• Integração com extensões Token-2022 via crates irmãos.

Exemplo de Trabalho

use anchor_lang::prelude::*;
use anchor_spl::{
    associated_token::AssociatedToken,
    token::{self, Mint, Token, TokenAccount, Transfer},
};
 
#[derive(Accounts)]
pub struct Pay<'info> {
    #[account(mut)]
    pub payer: Signer<'info>,
    #[account(mut)]
    pub payer_ata: Account<'info, TokenAccount>,
    #[account(mut)]
    pub merchant_ata: Account<'info, TokenAccount>,
    pub mint: Account<'info, Mint>,
    pub token_program: Program<'info, Token>,
    pub associated_token_program: Program<'info, AssociatedToken>,
}
 
pub fn pay(ctx: Context<Pay>, amount: u64) -> Result<()> {
    require!(amount > 0, ErrorCode::InvalidAmount);
    token::transfer(
        CpiContext::new(
            ctx.accounts.token_program.to_account_info(),
            Transfer {
                from: ctx.accounts.payer_ata.to_account_info(),
                to: ctx.accounts.merchant_ata.to_account_info(),
                authority: ctx.accounts.payer.to_account_info(),
            },
        ),
        amount,
    )?;
    Ok(())
}
 
#[error_code]
pub enum ErrorCode {
    #[msg("o valor deve ser positivo")]
    InvalidAmount,
}

O que isso demonstra:

• Os tipos TokenAccount e Mint validam proprietários e layouts.
• Transferências CPI para SPL Token com a autoridade assinante correta.
• O programa ATA está disponível quando as instruções criam ATAs.
• Verificou o amount antes do movimento do token.

Mergulho Profundo

Como Funciona

• Contas Mint armazenam o fornecimento, decimais e autoridades.
• Contas Token mantêm saldos por "mint" para um único proprietário.
• O programa ATA deriva PDAs deterministicamente do endereço da carteira + "mint" + ID do programa de token.
• O ID do programa Token TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA no SPL clássico.

Tabela de Crates Rust

Tabela TypeScript / NPM

Notas Rust

// Sempre use matemática verificada para valores humanos
let raw = amount
    .checked_mul(10u64.pow(mint.decimals as u32))
    .ok_or(ProgramError::InvalidArgument)?;

Armadilhas

• ID incorreto do programa de token para derivação ATA - "Mints" Token-2022 precisam do ID do programa Token-2022. Correção: passe o ID de programa correto para os helpers ATA.
• Transferência sem delegado ao usar autoridade delegada - falha com incompatibilidade de proprietário. Correção: inclua o "signer" delegado ou use o proprietário.
• Decimais assumidos como 9 - USDC usa 6. Correção: leia mint.decimals em tempo de execução.
• Fechar ATA com "dust" (resíduos) - reabrir custa aluguel (rent). Correção: varra para zero antes de fechar ou mantenha a ATA.
• Autoridade de "mint" deixada em "mints" da rede principal - risco de inflação ilimitada. Correção: revogue a autoridade de "mint" após o lançamento.

Alternativas

FAQs

Relacionados

• anchor-lang & anchor-spl - Helpers SPL do Anchor
• SPL Token Basics - conceitos
• Associated Token Accounts - guia ATA
• Token-2022 Basics - extensões

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.