CPI de um programa customizado

Esta página foi traduzida automaticamente por IA. A versão em inglês é a fonte oficial.Ver versão em inglês →

Quando CPI é a ferramenta certa

Um programa customizado faz sentido quando a troca precisa acontecer atomicamente com outras mudanças de estado on-chain que apenas seu programa pode fazer. Casos comuns:

Programas de escrow / ordem limitada — o usuário deposita um mint no seu escrow, seu programa monitora uma condição de preço, e quando dispara, seu programa atomicamente faz swap através do Raydium e credita a conta do usuário.
Proxies agregadores — uma única instrução que roteia um swap através do Raydium + um ou mais outros DEXes, com todos os hops sob uma única verificação de slippage de propriedade do seu programa.
Vaults com auto-compounding — deposite tokens LP ou stake de farm no seu vault, o vault colhe recompensas em um cronograma, re-fornece liquidez, emite tokens de participação.
Vaults de estratégia — posições LP alavancadas que rebalanceiam fazendo swap através de CLMM; liquidadores que fecham posições e fazem swap de colateral em uma transação.
Plataformas de lançamento de tokens com vesting customizado — seu programa mantém tokens em vesting e libera em um pool Raydium em um cronograma.

Se você apenas quer enviar um swap de código off-chain, CPI é excessivo — use o SDK. CPI justifica sua complexidade apenas quando atomicidade com seu próprio estado é o requisito.

Padrões de composição

Padrão 1: Proxy fino

Seu programa expõe uma única instrução que valida alguma política (ex: pares de mint na whitelist, desconto de taxa para usuários verificados) e depois encaminha para o Raydium.

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

O estado vive nas ATAs do usuário. Seu programa não possui tokens. Pegada de confiança mínima.

Padrão 2: Escrow

Seu programa possui um PDA que mantém o mint de entrada do usuário. No disparo, o PDA assina um CPI para o Raydium fazer swap de seu próprio saldo.

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

Detalhe crítico: o PDA assina via CpiContext::new_with_signer. Veja Sementes de signatário PDA.

Padrão 3: Multi-hop composto

Seu programa emite múltiplos CPIs em uma instrução, aplicando um único limite de slippage em todos eles. As instruções de swap do Raydium cada uma têm seu próprio minimum_amount_out, mas você define aqueles para 0 (ou um piso muito solto) e aplica um mínimo final rigoroso você mesmo após o último hop.

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)

Isso lhe dá um portão de reversão único para toda a rota. Use este padrão apenas quando você confia que cada hop é seguro em relação a slippage; caso contrário, deixe cada hop aplicar seu próprio mínimo.

Padrão 4: Vault / estratégia

Seu programa mantém tokens LP ou stake de farm em um PDA. Um keeper (ou o usuário) chama compound(), que:

Colhe recompensas do farm.
Faz swap de recompensas por tokens de pool (CPI em CPMM ou CLMM).
Deposita os rendimentos de volta no LP (outro CPI).
Faz stake do novo LP (outro CPI).

Tudo em uma transação para que o NAV do vault se mova atomicamente. O orçamento de compute é tipicamente 600k–1M CU; tabelas de lookup de endereço são obrigatórias.

Construção da lista de contas

A struct Accounts do programa chamador espelha a ordem de contas do programa Raydium, mas a maioria das contas do lado Raydium são UncheckedAccount porque o Raydium as valida por si mesmo. Você apenas adiciona restrições em contas que você possui:

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

#[derive(Accounts)]
pub struct EscrowSwap<'info> {
    /// O PDA de escrow; mantém o mint de entrada e assina o CPI.
    #[account(
        mut,
        seeds = [b"escrow", user.key().as_ref()],
        bump = escrow.bump,
    )]
    pub escrow: Account<'info, Escrow>,

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

    // ----- Contas do lado Raydium, principalmente não verificadas -----

    /// 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 do escrow — de propriedade do PDA de escrow.
    #[account(
        mut,
        associated_token::mint = input_mint,
        associated_token::authority = escrow,
    )]
    pub escrow_input_ata: Account<'info, TokenAccount>,

    /// ATA de saída do escrow.
    #[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>,
}

A assimetria — validação rigorosa em suas contas, UncheckedAccount nas do Raydium — não é preguiça. O receptor valida as suas; validar duas vezes no chamador apenas queima CU e corre o risco de ficar fora de sincronização quando o Raydium envia um novo campo de layout de struct.

A chamada CPI em si

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` é a conta cuja assinatura deve cobrir a ATA de entrada. Essa ATA é
        // de propriedade do PDA de escrow, então o escrow — assinando via new_with_signer abaixo —
        // vai aqui, NÃO `user`.
        payer:                ctx.accounts.escrow.to_account_info(),
        // `authority` é o próprio PDA de vault do CPMM em [b"vault_and_lp_mint_auth_seed"];
        // CPMM assina a perna do vault com ele mesmo. Passar seu escrow aqui falha na
        // restrição de sementes antes de qualquer transferência ser executada.
        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 leva a Pubkey do programa aqui, não seu 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(())
}

Sementes de signatário PDA

O CPI só tem sucesso se o PDA passado como authority corresponder à derivação que o chamador afirma. Os dois devem concordar em:

A sequência de bytes de semente (aqui [b"escrow", user.key().as_ref()]).
O bump.
O ID do programa chamador (seu programa, não o do Raydium).

Note o que o PDA tem que corresponder. O slot authority do CPMM é seu próprio PDA de vault — uma conta fixa de todo o programa que ele deriva e assina com ele mesmo, e que seu programa nem controla nem substitui. A conta com a qual suas sementes PDA têm que se alinhar é payer: a verificação acontece dentro do helper transfer_from_user_to_pool_vault do próprio CPMM, que requer que a conta passada como payer seja a proprietária de input_token_account. Bug comum: passar user como payer enquanto escrow_input_ata é de propriedade do PDA de escrow. O programa SPL Token rejeita com owner mismatch. Sempre faça payer ser o proprietário da ATA — e assine por ela com new_with_signer quando esse proprietário é um PDA.

Contas restantes

Várias instruções do Raydium levam uma lista de comprimento variável de contas anexadas após as fixas — contas restantes.

CLMM SwapV2: 1–8 contas TickArrayState para os arrays de tick que o swap pode atravessar, na direção do swap.
Farm v6 Deposit / Harvest / Withdraw: pares (reward_vault, user_reward_ata), um par por slot de recompensa ativo.
Mints de transfer-hook Token-2022: o programa de transfer-hook mais quaisquer contas que o hook precise.

Os helpers CPI do Anchor não verificam tipos de contas restantes. Passe-as através:

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

A ordem importa. Para CLMM:

remaining = [
    tick_array_in_direction_0,    // primeira atravessada
    tick_array_in_direction_1,
    ...,
]

Para farm v6 harvest:

remaining = [
    reward_vault_0, user_reward_ata_0,
    reward_vault_1, user_reward_ata_1,
    // omita qualquer slot cujo reward_state seja Uninitialized
]

Seu programa chamador deve passar as contas restantes que recebe do cliente inalteradas. Não tente filtrá-las ou reordená-las.

Orçamento de compute para chamadas compostas

Um CPI custa ~1.500 CU para o frame de chamada em si; o uso de CU do chamado se acumula no topo. Os valores do chamado abaixo são medidos de transações mainnet ao vivo em pools de alto volume em 2026-09-09, lidos da linha de log Program <id> consumed N of M compute units para a própria invocação do programa Raydium (então incluem seus CPIs internos de programa de token):

Instrução do chamado	CU medido	Amostra
CPMM `swap_base_input`	~23.000	22.721–23.052 (n=8)
Swap 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

Adicione ~1.500 para cada frame CPI e a sobrecarga do seu próprio programa no topo. O custo de swap CLMM escala com travessias de tick, então trate seu valor como um piso. Mints Token-2022 adicionam o custo de manipulação de extensão da transferência em si; meça para seus próprios mints em vez de aplicar um multiplicador fixo.

Revisões anteriores desta página carregavam estimativas 5–7× maiores (um swap CPMM de ~150.000 CU, ~180.000 para CLMM). Aquelas nunca foram medidas. Orçamento a partir de sua própria leitura de computeUnitsConsumed, não de um número documentado — e note que uma transação completa custa mais que a instrução Raydium sozinha uma vez que criação de ATA, envolvimento de wSOL e instruções de orçamento de compute são contadas.

Sempre defina um 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,
);

O teto padrão de 200k CU se esgotará silenciosamente muito antes de uma chamada composta ser concluída.

Propagação de erro

Os programas do Raydium retornam erros Anchor com códigos estáveis. Seu programa chamador os vê como Err(ProgramError::Custom(code)). Propague por padrão:

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

Ou intercepte para 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) =>
    {
        // Seu programa pode querer tentar novamente com um slippage maior, ou desfazer estado.
        return err!(YourErr::PoolTooVolatile);
    }
    Err(err) => return Err(err),
}

Note o termo ERROR_CODE_OFFSET: variantes #[error_code] são emitidas começando em 6000, então comparar contra o discriminante de enum nu nunca corresponde. (Não há helper is_err em anchor-lang ou em raydium_cp_swap — revisões anteriores desta página usavam um que não existe.) O mapeamento de código de erro para significado é estável por política de IDL (sdk-api/anchor-idl); novos códigos se anexam ao final, códigos existentes nunca mudam de significado.

Exemplo completo trabalhado: escrow de ordem limitada

Fluxo:

open_order — usuário deposita amount_in de input_mint no PDA de escrow; registra min_amount_out alvo e expiração.
execute_order — qualquer um (keeper) chama com as contas de pool atuais. Programa verifica a cotação atual ≥ min_amount_out, depois CPI swap do Raydium e mantém a saída em escrow.
claim — usuário retira o mint de saída do escrow.

#[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 open, 1 filled, 2 cancelled, 3 expired
    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 {
            // A ATA de entrada do escrow é de propriedade do PDA `order`, então `order` deve ser
            // `payer` — assina via new_with_signer abaixo. O keeper apenas paga a
            // taxa de transação; não é o proprietário da ATA.
            payer:                ctx.accounts.order.to_account_info(),
            // PDA de vault próprio do CPMM em [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,
        );

        // Deixe o escrow aplicar o mínimo — confiamos no slippage do Raydium, mas também
        // re-verificamos nosso próprio delta pós-swap caso uma mudança futura o relaxe.
        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(())
    }
}

O keeper paga a taxa de transação (recebe uma taxa de keeper em outro lugar — não mostrado). O PDA order assina o CPI como payer, porque possui a ATA de entrada do escrow; ExecuteOrder portanto também precisa de um campo pool_authority: UncheckedAccount<'info> para o próprio PDA de vault do CPMM. Tanto a verificação de slippage do lado Raydium quanto a verificação de delta do próprio escrow aplicam o piso — segurança dupla.

Testes

Puxando programas Raydium para um validador local para testes de integração (de Anchor.toml):

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

Clone também as contas de estado do pool para que seus testes possam realmente executar swaps; anchor test as busca da mainnet na inicialização. Veja sdk-api/rust-cpi.

Armadilhas específicas de composição

Reentrância

Solana não tem verdadeira reentrância — um CPI não pode chamar de volta para o programa originador na mesma invocação. Mas você ainda pode se construir em uma reentrância lógica: um CPI que lê seu estado, depois seu código o lê novamente assumindo que o CPI não o mudou. Para Raydium, os CPIs não tocam seu estado, então isso é menos uma preocupação do que ex: contextos de flash-loan. Mas se você compor Raydium com um protocolo de empréstimo, esteja ciente.

Deriva de mutabilidade de conta

Se seu programa passa uma conta como mut mas Raydium espera apenas leitura (ou vice versa), o runtime rejeita a invocação com InvalidAccountData. Sempre verifique a mutabilidade esperada da instrução do Raydium no IDL; raydium_cp_swap::cpi::accounts::Swap define a mutabilidade de cada conta para você, a partir dos marcadores #[account(mut)] na própria struct Swap do CPMM — os campos derivados são todos AccountInfo<'info> simples, então é a impl ToAccountMetas derivada, não os tipos de campo, que carrega as flags.

Campo de programa Token-2022

Mints de entrada e saída podem estar sob diferentes programas de token — um SPL Token, um Token-2022. O CPI tem campos input_token_program e output_token_program separados por essa razão. Sempre verifique o campo owner de cada mint e roteia o programa correto em cada slot.

Transações versionadas

Uma tx composta que faz 2+ CPIs Raydium mais uma criação de ATA raramente cabe em uma transação legada (v0-sem-LUT). Use V0 com tabelas de lookup de endereço; puxe LUTs públicas do Raydium via raydium.getRaydiumLutAddresses().

Ponteiros

sdk-api/rust-cpi — mecânica CPI de baixo nível.
integration-guides/priority-fee-tuning — dimensionamento de orçamento de compute.
products/cpmm/code-demos, products/clmm/code-demos, products/farm-staking/code-demos — snippets CPI por produto.

Fontes:

Solana fundamentals

Quick start

SDK & API

Integration guides

CPI de um programa customizado

Quando CPI é a ferramenta certa

Padrões de composição

Padrão 1: Proxy fino

Padrão 2: Escrow

Padrão 3: Multi-hop composto

Padrão 4: Vault / estratégia

Construção da lista de contas

A chamada CPI em si

Sementes de signatário PDA

Contas restantes

Orçamento de compute para chamadas compostas

Propagação de erro

Exemplo completo trabalhado: escrow de ordem limitada

Testes

Armadilhas específicas de composição

Reentrância

Deriva de mutabilidade de conta

Campo de programa Token-2022

Transações versionadas

Ponteiros

​Quando CPI é a ferramenta certa

​Padrões de composição

​Padrão 1: Proxy fino

​Padrão 2: Escrow

​Padrão 3: Multi-hop composto

​Padrão 4: Vault / estratégia

​Construção da lista de contas

​A chamada CPI em si

​Sementes de signatário PDA

​Contas restantes

​Orçamento de compute para chamadas compostas

​Propagação de erro

​Exemplo completo trabalhado: escrow de ordem limitada

​Testes

​Armadilhas específicas de composição

​Reentrância

​Deriva de mutabilidade de conta

​Campo de programa Token-2022

​Transações versionadas

​Ponteiros

Quando CPI é a ferramenta certa

Padrões de composição

Padrão 1: Proxy fino

Padrão 2: Escrow

Padrão 3: Multi-hop composto

Padrão 4: Vault / estratégia

Construção da lista de contas

A chamada CPI em si

Sementes de signatário PDA

Contas restantes

Orçamento de compute para chamadas compostas

Propagação de erro

Exemplo completo trabalhado: escrow de ordem limitada

Testes

Armadilhas específicas de composição

Reentrância

Deriva de mutabilidade de conta

Campo de programa Token-2022

Transações versionadas

Ponteiros