Cross Program Invocation (CPI)

Uma Cross Program Invocation (CPI) refere-se a quando um programa invoca as instruções de outro programa. Isso permite a composição de programas Solana.

Você pode pensar nas instruções como endpoints de API que um programa expõe para a rede e um CPI como uma API invocando internamente outra API.

Cross Program Invocation

Pontos-chave

Cross Program Invocations permitem que instruções de programas Solana invoquem diretamente instruções em outro programa.
Privilégios de signatário de um programa chamador se estendem ao programa chamado.
Ao fazer uma Cross Program Invocation, programas podem assinar em nome de PDAs derivados de seu próprio ID de programa.
O programa chamado pode fazer mais CPIs para outros programas, até uma profundidade de 4.

O que é um CPI?

Uma Cross Program Invocation (CPI) ocorre quando um programa invoca as instruções de outro programa.

Escrever uma instrução de programa com um CPI segue o mesmo padrão de construir uma instrução para adicionar a uma transação. Internamente, cada instrução CPI deve especificar:

Endereço do programa: Especifica o programa a ser invocado
Contas: Lista todas as contas que a instrução lê ou escreve, incluindo outros programas
Dados da instrução: Especifica qual instrução invocar no programa, além de quaisquer dados que a instrução precise (argumentos de função)

Quando um programa faz uma Cross Program Invocation (CPI) para outro programa:

Os privilégios do signatário da transação inicial se estendem ao programa chamado (ex. A->B)
O programa chamado pode fazer mais CPIs para outros programas, até uma profundidade de 4 (ex. B->C, C->D)
Os programas podem "assinar" em nome das PDAs derivadas de seu ID de programa

O runtime do programa Solana define uma max_instruction_stack_depth constante MAX_INSTRUCTION_STACK_DEPTH de 5. Isso representa a altura máxima da pilha de invocação de instruções do programa. A altura da pilha começa em 1 para a transação inicial e aumenta em 1 cada vez que um programa invoca outra instrução. Esta configuração limita a profundidade de invocação para CPIs a 4.

Quando uma transação é processada, os privilégios da conta se estendem de um programa para outro. Veja o que isso significa:

Digamos que o Programa A receba uma instrução com:

Uma conta que assinou a transação
Uma conta que pode ser escrita (mutável)

Quando o Programa A faz um CPI para o Programa B:

O Programa B pode usar essas mesmas contas com suas permissões originais
O Programa B pode assinar com a conta signatária
O Programa B pode escrever na conta gravável
O Programa B pode até passar essas mesmas permissões adiante se fizer seus próprios CPIs

Cross Program Invocation

A função invoke gerencia CPIs que não requerem signatários PDA. A função chama a função invoke_signed com um array signers_seeds vazio, indicando que não há PDAs necessárias para assinatura.

Invoke Function

pub fn invoke(instruction: &Instruction, account_infos: &[AccountInfo]) -> ProgramResult {
    invoke_signed(instruction, account_infos, &[])
}

Os exemplos a seguir mostram como fazer um CPI usando o Anchor Framework e Rust nativo. Os programas de exemplo incluem uma única instrução que transfere SOL de uma conta para outra usando um CPI.

Framework Anchor

Os exemplos a seguir apresentam três maneiras de criar Cross Program Invocations (CPIs) em um programa Anchor, cada uma em um nível diferente de abstração. Todos os exemplos funcionam da mesma maneira. O objetivo principal é mostrar os detalhes de implementação de um CPI.

Exemplo 1: Usa o CpiContext do Anchor e função auxiliar para construir a instrução CPI.
Exemplo 2: Usa a função system_instruction::transfer do crate solana_program para construir a instrução CPI. O exemplo 1 abstrai esta implementação.
Exemplo 3: Constrói a instrução CPI manualmente. Esta abordagem é útil quando não existe um crate para ajudar a construir a instrução.

use anchor_lang::prelude::*;
use anchor_lang::system_program::{transfer, Transfer};

declare_id!("9AvUNHjxscdkiKQ8tUn12QCMXtcnbR9BVGq3ULNzFMRi");

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

    pub fn sol_transfer(ctx: Context<SolTransfer>, amount: u64) -> Result<()> {
        let from_pubkey = ctx.accounts.sender.to_account_info();
        let to_pubkey = ctx.accounts.recipient.to_account_info();
        let program_id = ctx.accounts.system_program.to_account_info();

        let cpi_context = CpiContext::new(
            program_id,
            Transfer {
                from: from_pubkey,
                to: to_pubkey,
            },
        );

        transfer(cpi_context, amount)?;
        Ok(())
    }
}

#[derive(Accounts)]
pub struct SolTransfer<'info> {
    #[account(mut)]
    sender: Signer<'info>,
    #[account(mut)]
    recipient: SystemAccount<'info>,
    system_program: Program<'info, System>,
}

Rust Nativo

O exemplo a seguir mostra como fazer um CPI a partir de um programa escrito em Rust Nativo. O programa inclui uma única instrução que transfere SOL de uma conta para outra usando um CPI. O arquivo de teste usa o LiteSVM para testar o programa.

use borsh::BorshDeserialize;
use solana_program::{
    account_info::AccountInfo,
    entrypoint,
    entrypoint::ProgramResult,
    program::invoke,
    program_error::ProgramError,
    pubkey::Pubkey,
    system_instruction,
};

// Declare program entrypoint
entrypoint!(process_instruction);

// Define program instructions
#[derive(BorshDeserialize)]
enum ProgramInstruction {
    SolTransfer { amount: u64 },
}

impl ProgramInstruction {
    fn unpack(input: &[u8]) -> Result<Self, ProgramError> {
        Self::try_from_slice(input).map_err(|_| ProgramError::InvalidInstructionData)
    }
}

pub fn process_instruction(
    _program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    // Deserialize instruction data
    let instruction = ProgramInstruction::unpack(instruction_data)?;

    // Process instruction
    match instruction {
        ProgramInstruction::SolTransfer { amount } => {
            // Parse accounts
            let [sender_info, recipient_info, system_program_info] = accounts else {
                return Err(ProgramError::NotEnoughAccountKeys);
            };

            // Verify the sender is a signer
            if !sender_info.is_signer {
                return Err(ProgramError::MissingRequiredSignature);
            }

            // Create and invoke the transfer instruction
            let transfer_ix = system_instruction::transfer(
                sender_info.key,
                recipient_info.key,
                amount,
            );

            invoke(
                &transfer_ix,
                &[
                    sender_info.clone(),
                    recipient_info.clone(),
                    system_program_info.clone(),
                ],
            )?;

            Ok(())
        }
    }
}

Cross Program Invocations com assinantes PDA

A função invoke_signed gerencia CPIs que requerem assinantes PDA. A função recebe as seeds para derivar PDAs assinantes como signer_seeds.

Você pode consultar a página Program Derived Address para detalhes sobre como derivar PDAs.

Invoke Signed

pub fn invoke_signed(
    instruction: &Instruction,
    account_infos: &[AccountInfo],
    signers_seeds: &[&[&[u8]]],
) -> ProgramResult {
    // --snip--
    invoke_signed_unchecked(instruction, account_infos, signers_seeds)
}

Ao processar uma instrução que inclui um CPI, o runtime da Solana internamente chama create_program_address usando o signers_seeds e o program_id do programa chamador. Quando um PDA válido é verificado, o endereço é adicionado como um assinante válido.

Os exemplos a seguir demonstram como fazer um CPI com assinantes PDA usando o Framework Anchor e Rust Nativo. Os programas de exemplo incluem uma única instrução que transfere SOL de um PDA para a conta do destinatário usando um CPI assinado pelo PDA.

Framework Anchor

Os exemplos a seguir incluem três abordagens para implementar Invocações entre Programas (CPIs) em um programa Anchor, cada uma em um nível diferente de abstração. Todos os exemplos são funcionalmente equivalentes. O objetivo principal é ilustrar os detalhes de implementação de um CPI.

Exemplo 1: Usa o CpiContext do Anchor e função auxiliar para construir a instrução CPI.
Exemplo 2: Usa a função system_instruction::transfer do crate solana_program para construir a instrução CPI. O Exemplo 1 é uma abstração desta implementação.
Exemplo 3: Constrói a instrução CPI manualmente. Esta abordagem é útil quando não há um crate disponível para ajudar a construir a instrução que você deseja invocar.

use anchor_lang::prelude::*;
use anchor_lang::system_program::{transfer, Transfer};

declare_id!("BrcdB9sV7z9DvF9rDHG263HUxXgJM3iCQdF36TcxbFEn");

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

    pub fn sol_transfer(ctx: Context<SolTransfer>, amount: u64) -> Result<()> {
        let from_pubkey = ctx.accounts.pda_account.to_account_info();
        let to_pubkey = ctx.accounts.recipient.to_account_info();
        let program_id = ctx.accounts.system_program.to_account_info();

        let seed = to_pubkey.key();
        let bump_seed = ctx.bumps.pda_account;
        let signer_seeds: &[&[&[u8]]] = &[&[b"pda", seed.as_ref(), &[bump_seed]]];

        let cpi_context = CpiContext::new(
            program_id,
            Transfer {
                from: from_pubkey,
                to: to_pubkey,
            },
        )
        .with_signer(signer_seeds);

        transfer(cpi_context, amount)?;
        Ok(())
    }
}

#[derive(Accounts)]
pub struct SolTransfer<'info> {
    #[account(
        mut,
        seeds = [b"pda", recipient.key().as_ref()],
        bump,
    )]
    pda_account: SystemAccount<'info>,
    #[account(mut)]
    recipient: SystemAccount<'info>,
    system_program: Program<'info, System>,
}

Rust Nativo

O exemplo a seguir mostra como fazer um CPI com assinantes PDA a partir de um programa escrito em Rust Nativo. O programa inclui uma única instrução que transfere SOL de um PDA para a conta do destinatário usando um CPI assinado pelo PDA. O arquivo de teste usa o LiteSVM para testar o programa.

use borsh::BorshDeserialize;
use solana_program::{
    account_info::AccountInfo,
    entrypoint,
    entrypoint::ProgramResult,
    program::invoke_signed,
    program_error::ProgramError,
    pubkey::Pubkey,
    system_instruction,
};

// Declare program entrypoint
entrypoint!(process_instruction);

// Define program instructions
#[derive(BorshDeserialize)]
enum ProgramInstruction {
    SolTransfer { amount: u64 },
}

impl ProgramInstruction {
    fn unpack(input: &[u8]) -> Result<Self, ProgramError> {
        Self::try_from_slice(input).map_err(|_| ProgramError::InvalidInstructionData)
    }
}

pub fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    // Deserialize instruction data
    let instruction = ProgramInstruction::unpack(instruction_data)?;

    // Process instruction
    match instruction {
        ProgramInstruction::SolTransfer { amount } => {
            // Parse accounts
            let [pda_account_info, recipient_info, system_program_info] = accounts else {
                return Err(ProgramError::NotEnoughAccountKeys);
            };

            // Derive PDA and verify it matches the account provided by client
            let recipient_pubkey = recipient_info.key;
            let seeds = &[b"pda", recipient_pubkey.as_ref()];
            let (expected_pda, bump_seed) = Pubkey::find_program_address(seeds, program_id);

            if expected_pda != *pda_account_info.key {
                return Err(ProgramError::InvalidArgument);
            }

            // Create the transfer instruction
            let transfer_ix = system_instruction::transfer(
                pda_account_info.key,
                recipient_info.key,
                amount,
            );

            // Create signer seeds for PDA
            let signer_seeds: &[&[&[u8]]] = &[&[b"pda", recipient_pubkey.as_ref(), &[bump_seed]]];

            // Invoke the transfer instruction with PDA as signer
            invoke_signed(
                &transfer_ix,
                &[
                    pda_account_info.clone(),
                    recipient_info.clone(),
                    system_program_info.clone(),
                ],
                signer_seeds,
            )?;

            Ok(())
        }
    }
}

Índice