Cross Program Invocation

Cross-program invocation (CPI) tapahtuu, kun yksi Solana-ohjelma kutsuu suoraan toisen ohjelman käskyjä. Tämä mahdollistaa ohjelmien yhteensopivuuden. Jos ajattelet Solanan käskyä API-päätepisteenä, jonka ohjelma tarjoaa verkolle, CPI on kuin yksi päätepiste kutsuisi sisäisesti toista.

CPI-kutsua tehdessään ohjelma voi allekirjoittaa sellaisen PDA:n puolesta, joka on johdettu sen ohjelmatunnuksesta. Nämä allekirjoitusoikeudet siirtyvät kutsuvalta ohjelmalta kutsuttavalle ohjelmalle.

Cross-program invocation -esimerkki

CPI-kutsua tehtäessä tilin käyttöoikeudet siirtyvät ohjelmasta toiseen. Oletetaan, että ohjelma A vastaanottaa käskyn, jossa on allekirjoittajatili ja kirjoitettava tili. Ohjelma A tekee sitten CPI-kutsun ohjelmaan B. Nyt ohjelma B voi käyttää samoja tilejä kuin ohjelma A alkuperäisillä käyttöoikeuksilla. (Tämä tarkoittaa, että ohjelma B voi allekirjoittaa allekirjoittajatilin avulla ja kirjoittaa kirjoitettavaan tiliin.) Jos ohjelma B tekee omia CPI-kutsujaan, se voi välittää nämä samat oikeudet eteenpäin, enintään 4 tasoa syvyyteen.

Ohjelmakäskyjen kutsupinon enimmäiskorkeus on nimeltään max_instruction_stack_depth ja se on asetettu MAX_INSTRUCTION_STACK_DEPTH -vakioon, joka on 5.

Pinon korkeus alkaa arvosta 1 alkuperäiselle transaktiolle ja kasvaa yhdellä aina kun ohjelma kutsuu toista käskyä, rajoittaen CPI-kutsujen syvyyden enintään 4:ään.

CPI-kutsut PDA-allekirjoittajien kanssa

Kun CPI vaatii PDA-allekirjoittajan, invoke_signed -funktiota käytetään. Se ottaa allekirjoittajan siemenet, joita käytetään allekirjoittaja-PDA:iden johtamiseen. Solanan ajoympäristö kutsuu sisäisesti create_program_address käyttäen kutsuvan ohjelman signers_seeds ja program_id. Kun PDA on vahvistettu, se lisätään kelvolliseksi allekirjoittajaksi.

Invoke signed

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

Alla olevat esimerkit tekevät CPI:n PDA-allekirjoittajilla käyttäen Anchoria ja Native Rustia. Jokainen esimerkki sisältää yhden ohjeen, joka siirtää SOL-tokeneita PDA:lta vastaanottajatilille käyttäen PDA:n allekirjoittamaa CPI:tä.

Anchor

Seuraavat esimerkit näyttävät kolme lähestymistapaa CPI:n toteuttamiseen Anchor-ohjelmassa. Esimerkit ovat toiminnallisesti samanlaisia, mutta jokainen havainnollistaa eri abstraktiotasoa.

Esimerkki 1: Käyttää Anchorin CpiContext ja apufunktiota.
Esimerkki 2: Käyttää system_instruction::transfer -funktiota solana_program -paketista. (Esimerkki 1 on tämän toteutuksen abstraktio.)
Esimerkki 3: Rakentaa CPI-ohjeen manuaalisesti. Tämä lähestymistapa on hyödyllinen, kun ei ole saatavilla pakettia, joka auttaisi rakentamaan ohjeen, jonka haluat kutsua.

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

Alla oleva esimerkki tekee CPI:n PDA-allekirjoittajilla ohjelmasta, joka on kirjoitettu Native Rustilla. Se sisältää yhden ohjeen, joka siirtää SOL-tokeneita PDA-tililtä toiselle. CPI on allekirjoitettu PDA-tilillä. (Testitiedosto käyttää LiteSVM-kirjastoa ohjelman testaamiseen.)

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(())
        }
    }
}

CPI:t ilman PDA-allekirjoittajia

Kun CPI ei vaadi PDA-allekirjoittajia, invoke -funktiota käytetään. invoke -funktio kutsuu invoke_signed -funktiota tyhjällä signers_seeds -taulukolla. Tyhjä allekirjoittajataulukko osoittaa, että allekirjoittamiseen ei tarvita PDA:ita.

Invoke function

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

Alla olevat esimerkit tekevät CPI-kutsun käyttäen Anchoria ja natiivi-Rustia. Ne sisältävät yhden käskyn, joka siirtää SOL:ia yhdeltä tililtä toiselle.

Anchor

Seuraavat esimerkit näyttävät kolme lähestymistapaa CPI-kutsujen toteuttamiseen Anchor-ohjelmassa. Esimerkit ovat toiminnallisesti samanlaisia, mutta kukin esittelee eri abstraktiotason.

Esimerkki 1: Käyttää Anchorin CpiContext ja apufunktiota.
Esimerkki 2: Käyttää system_instruction::transfer -funktiota solana_program -paketista.
Esimerkki 3: Rakentaa CPI-käskyn manuaalisesti. Tämä lähestymistapa on hyödyllinen, kun ei ole olemassa pakettia, joka auttaisi rakentamaan käskyn, jonka haluat kutsua.

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

Seuraava esimerkki näyttää, miten tehdä CPI-kutsu natiivi-Rustilla kirjoitetusta ohjelmasta. Se sisältää yhden käskyn, joka siirtää SOL:ia yhdeltä tililtä toiselle. (Testitiedosto käyttää LiteSVM-kirjastoa ohjelman testaamiseen.)

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 Invocation

CPI-kutsut PDA-allekirjoittajien kanssa

Anchor

Rust

CPI:t ilman PDA-allekirjoittajia

Anchor

Rust

Sisällysluettelo