CPI desde un programa personalizado

Esta página fue traducida automáticamente por IA. La versión en inglés es la fuente autorizada.Ver versión en inglés →

sdk-api/rust-cpi cubre la mecánica de bajo nivel para invocar cada programa de Raydium. Esta página es la acompañante de nivel superior: por qué compondrías Raydium en tu propio programa, qué patrón se ajusta a tu caso de uso, y el código de integración completo que necesitas de principio a fin.

Cuándo CPI es la herramienta correcta

Un programa personalizado tiene sentido cuando el intercambio debe ocurrir de forma atómica con otros cambios de estado on-chain que solo tu programa puede hacer. Casos comunes:

Programas de depósito en garantía / órdenes limitadas — el usuario deposita un mint en tu depósito en garantía, tu programa observa una condición de precio, y cuando se activa, tu programa intercambia atómicamente a través de Raydium y acredita la cuenta del usuario.
Proxies agregadores — una única instrucción que enruta un intercambio a través de Raydium + uno o más DEXes adicionales, con todos los saltos bajo una única verificación de slippage propiedad de tu programa.
Bóvedas de auto-compounding — deposita LP o participación en granja en tu bóveda, la bóveda cosecha recompensas en un cronograma, re-suministra liquidez, emite tokens de participación.
Bóvedas de estrategia — posiciones LP apalancadas que se reequilibran intercambiando a través de CLMM; liquidadores que cierran posiciones e intercambian garantía en una transacción.
Plataformas de lanzamiento de tokens con vesting personalizado — tu programa mantiene tokens de vesting y los libera en un pool de Raydium en un cronograma.

Si solo quieres enviar un intercambio desde código off-chain, CPI es excesivo — usa el SDK. CPI justifica su complejidad solo cuando la atomicidad con tu propio estado es el requisito.

Patrones de composición

Patrón 1: Proxy delgado

Tu programa expone una única instrucción que valida alguna política (p. ej. pares de mint en lista blanca, descuento de tarifa para usuarios verificados) y luego reenvía a Raydium.

┌──────────────┐   user tx    ┌────────────────┐  CPI  ┌──────────┐
│ user         │─────────────▶│ your program   │──────▶│ Raydium  │
└──────────────┘              │  (validate)    │       │  (CPMM)  │
                              └────────────────┘       └──────────┘

El estado vive en los ATAs del usuario. Tu programa no posee tokens. Huella de confianza mínima.

Patrón 2: Depósito en garantía

Tu programa posee un PDA que mantiene el mint de entrada del usuario. Al activarse, el PDA firma un CPI a Raydium para intercambiar su propio saldo.

           deposit                   trigger
   user ───────────▶  PDA vault  ───────────────▶  Raydium swap
                     (your prog)                    (signed by PDA)
                                                            │
                                                            ▼
                                                    PDA vault (output mint)
                                                            │
                                                     withdraw ▼
                                                         user

Detalle crítico: el PDA firma a través de CpiContext::new_with_signer. Ver Semillas de firmante PDA.

Patrón 3: Multi-salto compuesto

Tu programa emite múltiples CPIs en una instrucción, aplicando un único límite de slippage en todos ellos. Las instrucciones de intercambio de Raydium tienen cada una su propio minimum_amount_out, pero estableces esos en 0 (o un piso muy flexible) y aplicas un mínimo final estricto después del último salto.

instruction:
  CPI swap: tokenA → tokenB   (raydium, loose min)
  CPI swap: tokenB → tokenC   (raydium / third-party, loose min)
  CPI swap: tokenC → tokenD   (raydium, loose min)
  require(user.tokenD_ata.amount - pre_balance >= user_min_out)

Esto te da una única puerta de reversión para toda la ruta. Solo usa este patrón cuando confíes en que cada salto sea seguro en slippage; de lo contrario, deja que cada salto aplique su propio mínimo.

Patrón 4: Bóveda / estrategia

Tu programa mantiene tokens LP o participación en granja en un PDA. Un guardián (o el usuario) llama a compound(), que:

Cosecha recompensas de la granja.
Intercambia recompensas por tokens de pool (CPI en CPMM o CLMM).
Deposita los ingresos de vuelta en el LP (otro CPI).
Participa en el nuevo LP (otro CPI).

Todo en una transacción para que el NAV de la bóveda se mueva atómicamente. El presupuesto de cómputo es típicamente 600k–1M CU; las tablas de búsqueda de direcciones son obligatorias.

Construcción de lista de cuentas

La estructura Accounts del programa que llama refleja el orden de cuentas del programa de Raydium, pero la mayoría de las cuentas del lado de Raydium son UncheckedAccount porque Raydium las valida a sí mismo. Solo añades restricciones en cuentas que tú posees:

use anchor_lang::prelude::*;
use anchor_spl::token::{Token, TokenAccount};

#[derive(Accounts)]
pub struct EscrowSwap<'info> {
    /// El PDA de depósito en garantía; mantiene el mint de entrada y firma el CPI.
    #[account(
        mut,
        seeds = [b"escrow", user.key().as_ref()],
        bump = escrow.bump,
    )]
    pub escrow: Account<'info, Escrow>,

    #[account(mut)]
    pub user: Signer<'info>,

    // ----- Cuentas del lado de Raydium, mayormente sin verificar -----

    /// CHECK: validado por CPMM
    #[account(mut)] pub pool_state: UncheckedAccount<'info>,
    /// CHECK: validado por CPMM
    pub amm_config: UncheckedAccount<'info>,
    /// CHECK: validado por CPMM
    pub pool_authority: UncheckedAccount<'info>,
    #[account(mut)] pub input_vault:  Account<'info, TokenAccount>,
    #[account(mut)] pub output_vault: Account<'info, TokenAccount>,
    /// CHECK: validado por CPMM
    #[account(mut)] pub observation_state: UncheckedAccount<'info>,

    /// ATA de entrada del depósito en garantía — propiedad del PDA de depósito en garantía.
    #[account(
        mut,
        associated_token::mint = input_mint,
        associated_token::authority = escrow,
    )]
    pub escrow_input_ata: Account<'info, TokenAccount>,

    /// ATA de salida del depósito en garantía.
    #[account(
        mut,
        associated_token::mint = output_mint,
        associated_token::authority = escrow,
    )]
    pub escrow_output_ata: Account<'info, TokenAccount>,

    pub input_mint:  Account<'info, anchor_spl::token::Mint>,
    pub output_mint: Account<'info, anchor_spl::token::Mint>,

    pub cpmm_program:       Program<'info, raydium_cp_swap::program::RaydiumCpSwap>,
    pub token_program:      Program<'info, Token>,
    pub token_program_2022: Program<'info, anchor_spl::token_2022::Token2022>,
}

La asimetría — validación estricta en tus cuentas, UncheckedAccount en las de Raydium — no es pereza. El receptor valida las suyas; validar dos veces en el llamador solo quema CU y arriesga desincronización cuando Raydium envía un nuevo campo de diseño de struct.

La llamada CPI en sí

use raydium_cp_swap::cpi::{self, accounts::Swap as CpmmSwap};

pub fn escrow_swap(
    ctx: Context<EscrowSwap>,
    amount_in: u64,
    minimum_amount_out: u64,
) -> Result<()> {
    let user_key = ctx.accounts.user.key();
    let bump     = ctx.accounts.escrow.bump;
    let seeds: &[&[u8]] = &[b"escrow", user_key.as_ref(), &[bump]];
    let signer: &[&[&[u8]]] = &[seeds];

    let cpi_accounts = CpmmSwap {
        // `payer` es la cuenta cuya firma debe cubrir el ATA de entrada. Ese ATA es
        // propiedad del PDA de depósito en garantía, así que el depósito en garantía —
        // firmando a través de new_with_signer abajo — va aquí, NO `user`.
        payer:                ctx.accounts.escrow.to_account_info(),
        // `authority` es el PDA de bóveda propio de CPMM en [b"vault_and_lp_mint_auth_seed"];
        // CPMM firma la parte de la bóveda con él mismo. Pasar tu depósito en garantía aquí
        // falla la restricción de semillas antes de que cualquier transferencia se ejecute.
        authority:            ctx.accounts.pool_authority.to_account_info(),
        amm_config:           ctx.accounts.amm_config.to_account_info(),
        pool_state:           ctx.accounts.pool_state.to_account_info(),
        input_token_account:  ctx.accounts.escrow_input_ata.to_account_info(),
        output_token_account: ctx.accounts.escrow_output_ata.to_account_info(),
        input_vault:          ctx.accounts.input_vault.to_account_info(),
        output_vault:         ctx.accounts.output_vault.to_account_info(),
        input_token_program:  ctx.accounts.token_program.to_account_info(),
        output_token_program: ctx.accounts.token_program.to_account_info(),
        input_token_mint:     ctx.accounts.input_mint.to_account_info(),
        output_token_mint:    ctx.accounts.output_mint.to_account_info(),
        observation_state:    ctx.accounts.observation_state.to_account_info(),
    };

    // Anchor 1.0 toma la Pubkey del programa aquí, no su AccountInfo.
    let cpi_ctx = CpiContext::new_with_signer(
        *ctx.accounts.cpmm_program.key,
        cpi_accounts,
        signer,
    );

    cpi::swap_base_input(cpi_ctx, amount_in, minimum_amount_out)?;
    Ok(())
}

Semillas de firmante PDA

El CPI solo tiene éxito si el PDA pasado como authority coincide con la derivación que el llamador afirma. Los dos deben estar de acuerdo en:

La secuencia de bytes de semilla (aquí [b"escrow", user.key().as_ref()]).
El bump.
El ID del programa que llama (tu programa, no el de Raydium).

Ten en cuenta qué debe coincidir el PDA. La ranura authority de CPMM es su propio PDA de bóveda — una cuenta fija de todo el programa que deriva y firma a sí mismo, y que tu programa ni controla ni sustituye. La cuenta con la que tus semillas PDA tienen que alinearse es payer: la verificación ocurre dentro del ayudante transfer_from_user_to_pool_vault propio de CPMM, que requiere que la cuenta pasada como payer sea la propietaria de input_token_account. Error común: pasar user como payer mientras escrow_input_ata es propiedad del PDA de depósito en garantía. El programa SPL Token rechaza con owner mismatch. Siempre haz que payer sea el propietario del ATA — y firma por él con new_with_signer cuando ese propietario es un PDA.

Cuentas restantes

Varias instrucciones de Raydium toman una lista de longitud variable de cuentas añadidas después de las fijas — cuentas restantes.

CLMM SwapV2: 1–8 cuentas TickArrayState para los arrays de tick que el intercambio puede atravesar, en dirección de intercambio.
Farm v6 Deposit / Harvest / Withdraw: pares (reward_vault, user_reward_ata), un par por ranura de recompensa activa.
Mints de transfer-hook de Token-2022: el programa de transfer-hook más cualquier cuenta que el hook necesite.

Los ayudantes CPI de Anchor no verifican tipos en cuentas restantes. Pásalas a través:

let cpi_ctx = CpiContext::new_with_signer(program_id, accounts, signer)
    .with_remaining_accounts(ctx.remaining_accounts.to_vec());

El orden importa. Para CLMM:

remaining = [
    tick_array_in_direction_0,    // el primero cruzado
    tick_array_in_direction_1,
    ...,
]

Para cosecha de farm v6:

remaining = [
    reward_vault_0, user_reward_ata_0,
    reward_vault_1, user_reward_ata_1,
    // omite cualquier ranura cuyo reward_state sea Uninitialized
]

Tu programa que llama debe pasar las cuentas restantes que recibe del cliente sin cambios. No intentes filtrarlas o reordenarlas.

Presupuesto de cómputo para llamadas compuestas

Un CPI cuesta ~1,500 CU por el marco de llamada en sí; el uso de CU propio del llamado se apila encima. Las figuras del llamado abajo se midieron de transacciones mainnet en vivo en pools de alto volumen el 2026-09-09, leídas de la línea de log Program <id> consumed N of M compute units para la propia invocación del programa de Raydium (así que incluyen sus CPIs internos de programa de token):

Instrucción del llamado	CU medido	Muestra
CPMM `swap_base_input`	~23,000	22,721–23,052 (n=8)
Intercambio AMM v4	~26,000	25,215–26,002
CLMM `swap` (V1)	~41,000	37,148–44,721
CLMM `swap_v2`	~48,000	43,838–52,887 (n=6)
CLMM `increase_liquidity_v2`	~36,000	36,058

Añade ~1,500 por cada marco CPI y la sobrecarga de tu propio programa encima. El costo de intercambio CLMM se escala con cruces de tick, así que trata su figura como un piso. Los mints de Token-2022 añaden el costo de manejo de extensión de la transferencia en sí; mídelo para tus propios mints en lugar de aplicar un multiplicador plano.

Revisiones anteriores de esta página llevaban estimaciones 5–7× más altas (un intercambio CPMM de ~150,000 CU, ~180,000 para CLMM). Esos nunca fueron medidos. Presupuesta desde tu propia lectura de computeUnitsConsumed, no desde un número documentado — y ten en cuenta que una transacción completa cuesta más que la instrucción de Raydium sola una vez que se cuentan creación de ATA, envoltura de wSOL e instrucciones de presupuesto de cómputo.

Siempre establece un ComputeBudgetProgram::set_compute_unit_limit explícito:

import { ComputeBudgetProgram } from "@solana/web3.js";

const tx = new Transaction().add(
  ComputeBudgetProgram.setComputeUnitLimit({ units: 900_000 }),
  ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityFeeMicroLamports }),
  yourInstruction,
);

El techo de 200k CU predeterminado se agotará silenciosamente mucho antes de que una llamada compuesta se complete.

Propagación de errores

Los programas de Raydium devuelven errores de Anchor con códigos de error estables. Tu programa que llama los ve como Err(ProgramError::Custom(code)). Propágalos por defecto:

cpi::swap_base_input(cpi_ctx, amount_in, minimum_amount_out)?;

O intercepta códigos específicos:

use anchor_lang::error::{Error, ERROR_CODE_OFFSET};
use raydium_cp_swap::error::ErrorCode as CpmmErr;

match cpi::swap_base_input(cpi_ctx, amount_in, minimum_amount_out) {
    Ok(_) => {}
    Err(Error::ProgramError(pe))
        if pe.program_error
            == ProgramError::Custom(CpmmErr::ExceededSlippage as u32 + ERROR_CODE_OFFSET) =>
    {
        // Tu programa podría querer reintentar con un slippage más grande, o deshacer estado.
        return err!(YourErr::PoolTooVolatile);
    }
    Err(err) => return Err(err),
}

Ten en cuenta el término ERROR_CODE_OFFSET: las variantes #[error_code] se emiten comenzando en 6000, así que comparar contra el discriminante de enum desnudo nunca coincide. (No hay ayudante is_err en anchor-lang o en raydium_cp_swap — revisiones anteriores de esta página usaban uno que no existe.) La asignación de código de error a significado es estable según la política de IDL (sdk-api/anchor-idl); nuevos códigos se añaden al final, códigos existentes nunca cambian de significado.

Ejemplo completo trabajado: escrow de orden limitada

Flujo:

open_order — el usuario deposita amount_in de input_mint en el PDA de depósito en garantía; registra min_amount_out objetivo y vencimiento.
execute_order — cualquiera (guardián) llama con las cuentas de pool actuales. El programa verifica que la cotización actual ≥ min_amount_out, luego CPI intercambia Raydium y mantiene la salida en depósito en garantía.
claim — el usuario retira el mint de salida del depósito en garantía.

#[account]
pub struct LimitOrder {
    pub user:          Pubkey,
    pub input_mint:    Pubkey,
    pub output_mint:   Pubkey,
    pub amount_in:     u64,
    pub min_out:       u64,
    pub expiry_unix:   i64,
    pub state:         u8,    // 0 abierto, 1 completado, 2 cancelado, 3 expirado
    pub bump:          u8,
}

#[program]
pub mod limit_orders {
    use super::*;

    pub fn execute_order(
        ctx: Context<ExecuteOrder>,
    ) -> Result<()> {
        let order = &ctx.accounts.order;
        require!(order.state == 0, OrderErr::NotOpen);
        require!(Clock::get()?.unix_timestamp < order.expiry_unix, OrderErr::Expired);

        let user_key = order.user;
        let seeds: &[&[u8]] = &[b"order", user_key.as_ref(), &[order.bump]];
        let signer: &[&[&[u8]]] = &[seeds];

        let pre_out_balance = ctx.accounts.escrow_output_ata.amount;

        let cpi_accounts = CpmmSwap {
            // El ATA de entrada del depósito en garantía es propiedad del PDA `order`, así que `order`
            // debe ser `payer` — firma a través de new_with_signer abajo. El guardián solo paga la
            // tarifa de transacción; no es el propietario del ATA.
            payer:                ctx.accounts.order.to_account_info(),
            // PDA de bóveda propio de CPMM en [b"vault_and_lp_mint_auth_seed"].
            authority:            ctx.accounts.pool_authority.to_account_info(),
            amm_config:           ctx.accounts.amm_config.to_account_info(),
            pool_state:           ctx.accounts.pool_state.to_account_info(),
            input_token_account:  ctx.accounts.escrow_input_ata.to_account_info(),
            output_token_account: ctx.accounts.escrow_output_ata.to_account_info(),
            input_vault:          ctx.accounts.input_vault.to_account_info(),
            output_vault:         ctx.accounts.output_vault.to_account_info(),
            input_token_program:  ctx.accounts.token_program.to_account_info(),
            output_token_program: ctx.accounts.token_program.to_account_info(),
            input_token_mint:     ctx.accounts.input_mint.to_account_info(),
            output_token_mint:    ctx.accounts.output_mint.to_account_info(),
            observation_state:    ctx.accounts.observation_state.to_account_info(),
        };

        let cpi_ctx = CpiContext::new_with_signer(
            *ctx.accounts.cpmm_program.key,
            cpi_accounts,
            signer,
        );

        // Deja que el depósito en garantía aplique el mínimo — confiamos en el slippage de Raydium, pero
        // también re-verificamos nuestro propio delta post-intercambio en caso de que un cambio futuro
        // alguna vez lo relaje.
        cpi::swap_base_input(cpi_ctx, order.amount_in, order.min_out)?;

        ctx.accounts.escrow_output_ata.reload()?;
        let delta = ctx.accounts.escrow_output_ata.amount
            .checked_sub(pre_out_balance)
            .ok_or(error!(OrderErr::AccountingError))?;
        require!(delta >= order.min_out, OrderErr::InsufficientOutput);

        let order = &mut ctx.accounts.order;
        order.state = 1;
        Ok(())
    }
}

El guardián paga la tarifa de transacción (obtiene una tarifa de guardián en otro lugar — no se muestra). El PDA order firma el CPI como payer, porque posee el ATA de entrada del depósito en garantía; ExecuteOrder por lo tanto también necesita un campo pool_authority: UncheckedAccount<'info> para el PDA de bóveda propio de CPMM. Tanto la verificación de slippage del lado de Raydium como la verificación de delta del propio depósito en garantía aplican el piso — doble seguridad.

Pruebas

Extrayendo programas de Raydium en un validador local para pruebas de integración (desde Anchor.toml):

[test.validator]
clone = [
  { address = "CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C" }, # CPMM
  { address = "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK" }, # CLMM
  { address = "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8" }, # AMM v4
  { address = "FarmqiPv5eAj3j1GMdMCMUGXqPUvmquZtMy86QH6rzhG" }, # Farm v6
]

Clona también las cuentas de estado del pool para que tus pruebas puedan ejecutar realmente intercambios; anchor test las obtiene de mainnet al inicio. Ver sdk-api/rust-cpi.

Trampas específicas de composición

Reentrancia

Solana no tiene verdadera reentrancia — un CPI no puede llamar de vuelta al programa originador en la misma invocación. Pero aún puedes construirte en una reentrancia lógica: un CPI que lee tu estado, luego tu código lo lee de nuevo asumiendo que el CPI no lo cambió. Para Raydium, los CPIs no tocan tu estado, así que esto es menos una preocupación que p. ej. contextos de flash-loan. Pero si compones Raydium con un protocolo de préstamo, ten cuidado.

Deriva de mutabilidad de cuenta

Si tu programa pasa una cuenta como mut pero Raydium la espera de solo lectura (o viceversa), el tiempo de ejecución rechaza la invocación con InvalidAccountData. Siempre verifica la mutabilidad esperada de la instrucción de Raydium en el IDL; raydium_cp_swap::cpi::accounts::Swap establece la mutabilidad de cada cuenta para ti, desde los marcadores #[account(mut)] en la estructura Swap propia de CPMM — los campos derivados son todos AccountInfo<'info> simples, así que es la implementación ToAccountMetas derivada, no los tipos de campo, la que lleva las banderas.

Campo de programa Token-2022

Los mints de entrada y salida pueden estar bajo diferentes programas de token — uno SPL Token, uno Token-2022. El CPI tiene campos input_token_program y output_token_program separados por esta razón. Siempre verifica el campo owner de cada mint y enruta el programa correcto en cada ranura.

Transacciones versionadas

Una tx compuesta que hace 2+ CPIs de Raydium más una creación de ATA raramente cabe en una transacción heredada (v0-sin-LUT). Usa V0 con tablas de búsqueda de direcciones; extrae los LUTs públicos de Raydium a través de raydium.getRaydiumLutAddresses().

Punteros

sdk-api/rust-cpi — mecánica CPI de bajo nivel.
integration-guides/priority-fee-tuning — dimensionamiento de presupuesto de cómputo.
products/cpmm/code-demos, products/clmm/code-demos, products/farm-staking/code-demos — fragmentos CPI por producto.

Fuentes:

Fundamentos de Solana

Inicio rápido

SDK y API

Guías de integración

CPI desde un programa personalizado

Cuándo CPI es la herramienta correcta

Patrones de composición

Patrón 1: Proxy delgado

Patrón 2: Depósito en garantía

Patrón 3: Multi-salto compuesto

Patrón 4: Bóveda / estrategia

Construcción de lista de cuentas

La llamada CPI en sí

Semillas de firmante PDA

Cuentas restantes

Presupuesto de cómputo para llamadas compuestas

Propagación de errores

Ejemplo completo trabajado: escrow de orden limitada

Pruebas

Trampas específicas de composición

Reentrancia

Deriva de mutabilidad de cuenta

Campo de programa Token-2022

Transacciones versionadas

Punteros

​Cuándo CPI es la herramienta correcta

​Patrones de composición

​Patrón 1: Proxy delgado

​Patrón 2: Depósito en garantía

​Patrón 3: Multi-salto compuesto

​Patrón 4: Bóveda / estrategia

​Construcción de lista de cuentas

​La llamada CPI en sí

​Semillas de firmante PDA

​Cuentas restantes

​Presupuesto de cómputo para llamadas compuestas

​Propagación de errores

​Ejemplo completo trabajado: escrow de orden limitada

​Pruebas

​Trampas específicas de composición

​Reentrancia

​Deriva de mutabilidad de cuenta

​Campo de programa Token-2022

​Transacciones versionadas

​Punteros

Cuándo CPI es la herramienta correcta

Patrones de composición

Patrón 1: Proxy delgado

Patrón 2: Depósito en garantía

Patrón 3: Multi-salto compuesto

Patrón 4: Bóveda / estrategia

Construcción de lista de cuentas

La llamada CPI en sí

Semillas de firmante PDA

Cuentas restantes

Presupuesto de cómputo para llamadas compuestas

Propagación de errores

Ejemplo completo trabajado: escrow de orden limitada

Pruebas

Trampas específicas de composición

Reentrancia

Deriva de mutabilidad de cuenta

Campo de programa Token-2022

Transacciones versionadas

Punteros