spl-token & spl-associated-token-account

El programa SPL Token define las "mints" (acuñaciones) y las cuentas de token; el programa Associated Token Account (ATA) deriva las direcciones canónicas de billetera por mint. Las crates de Rust spl-token y spl-associated-token-account (más los wrappers de anchor-spl) codifican los layouts y los helpers de CPI para los programas y clientes de Agave 4.1.1.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

[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);

Cuándo usar esto:

• Programas que transfieren, acuñan o queman tokens SPL a través de CPI.
• Clientes que resuelven direcciones ATA antes de construir instrucciones.
• Analizar decimales de mint y saldos de cuentas de token fuera de la cadena.
• Integración con extensiones de Token-2022 a través de crates hermanas.

Ejemplo de Trabajo

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("el monto debe ser positivo")]
    InvalidAmount,
}

Qué demuestra esto:

• Los tipos TokenAccount y Mint validan propietarios y layouts.
• Transferencia CPI al programa SPL Token con el firmante de autoridad correcto.
• El programa ATA está disponible cuando las instrucciones crean ATAs.
• Se verificó amount antes del movimiento del token.

Análisis Profundo

Cómo Funciona

• Las cuentas Mint almacenan el suministro, los decimales y las autoridades.
• Las Token accounts (cuentas de token) mantienen saldos por mint para un único propietario.
• El programa ATA deriva PDAs de forma determinista a partir de la billetera + mint + ID del programa de token.
• El ID del programa de token TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA en el SPL clásico.

Tabla de Crates de Rust

Tabla de TypeScript / NPM

Notas de Rust

// Siempre usa matemáticas verificadas para montos humanos
let raw = amount
    .checked_mul(10u64.pow(mint.decimals as u32))
    .ok_or(ProgramError::InvalidArgument)?;

Trampas Comunes

• ID de programa de token incorrecto para la derivación de ATA - Las mints de Token-2022 necesitan el ID del programa de Token-2022. Solución: pasar el ID de programa correcto a los helpers de ATA.
• Transferencia sin delegado cuando se usa autoridad delegada - falla con discrepancia de propietario. Solución: incluir el firmante delegado o usar el propietario.
• Decimales asumidos como 9 - USDC usa 6. Solución: leer mint.decimals en tiempo de ejecución.
• Cerrar ATA con polvo - reabrir cuesta alquiler. Solución: barrer a cero antes de cerrar o mantener la ATA.
• Autoridad de mint dejada en las mints de mainnet - riesgo de inflación ilimitada. Solución: revocar la autoridad de mint después del lanzamiento.

Alternativas

Preguntas Frecuentes

Relacionado

• anchor-lang & anchor-spl - Helpers SPL de Anchor
• Conceptos Básicos de SPL Token - conceptos
• Cuentas de Token Asociadas - guía de ATA
• Conceptos Básicos de Token-2022 - extensiones

Versiones de la Pila: Esta página fue 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, y LiteSVM 0.6.x.