Cross Program Invocation (CPI)

Cross Program Invocation (CPI) tarkoittaa tilannetta, jossa yksi ohjelma kutsuu toisen ohjelman käskyjä. Tämä mahdollistaa Solana-ohjelmien yhteensopivuuden.

Voit ajatella käskyjä API-päätepisteinä, joita ohjelma tarjoaa verkolle, ja CPI:tä yhtenä API:na, joka sisäisesti kutsuu toista API:a.

Cross Program Invocation

Keskeiset kohdat

Cross Program Invocation mahdollistaa Solana-ohjelmien käskyjen suoran kutsumisen toiseen ohjelmaan.
Allekirjoittajan oikeudet kutsuohjelmasta siirtyvät kutsuttavaan ohjelmaan.
Tehdessään Cross Program Invocation -kutsun, ohjelmat voivat allekirjoittaa PDA:iden puolesta, jotka on johdettu niiden omasta ohjelmatunnuksesta.
Kutsuttava ohjelma voi tehdä lisää CPI-kutsuja muihin ohjelmiin, enintään 4 tasoa syvyyteen.

Mikä on CPI?

Cross Program Invocation (CPI) on tilanne, jossa yksi ohjelma kutsuu toisen ohjelman käskyjä.

Ohjelmakäskyn kirjoittaminen CPI:llä noudattaa samaa kaavaa kuin käskyn rakentaminen transaktioon lisäämistä varten. Pohjimmiltaan jokaisen CPI-käskyn on määritettävä:

Ohjelman osoite: Määrittää kutsuttavan ohjelman
Tilit: Luettelee jokaisen tilin, josta käsky lukee tai johon se kirjoittaa, mukaan lukien muut ohjelmat
Instruction data: Määrittää, mikä käsky ohjelmassa kutsutaan, sekä kaikki käskyn tarvitsemat tiedot (funktioargumentit)

Kun ohjelma tekee Cross Program Invocation (CPI) -kutsun toiseen ohjelmaan:

Alkuperäisen tapahtuman allekirjoitusoikeudet ulottuvat kutsuttavaan ohjelmaan (esim. A->B)
Kutsuttava ohjelma voi tehdä lisää Cross Program Invocation -kutsuja muihin ohjelmiin, enintään 4 syvyyteen (esim. B->C, C->D)
Ohjelmat voivat "allekirjoittaa" PDA-tilien puolesta, jotka on johdettu sen ohjelmatunnuksesta

Solanan ohjelmaympäristö asettaa max_instruction_stack_depth vakion MAX_INSTRUCTION_STACK_DEPTH arvoksi 5. Tämä edustaa ohjelman käskyjen kutsupinon maksimisyvyyttä. Pinon korkeus alkaa arvosta 1 alkuperäiselle tapahtumalle ja kasvaa 1:llä aina kun ohjelma kutsuu toista käskyä. Tämä asetus rajoittaa CPI-kutsujen syvyyden 4:ään.

Kun tapahtumaa käsitellään, tilin käyttöoikeudet siirtyvät ohjelmasta toiseen. Tässä mitä se tarkoittaa:

Oletetaan, että ohjelma A vastaanottaa käskyn, jossa on:

Tili, joka on allekirjoittanut tapahtuman
Tili, johon voidaan kirjoittaa (muokattava)

Kun ohjelma A tekee CPI-kutsun ohjelmaan B:

Ohjelma B saa käyttää näitä samoja tilejä niiden alkuperäisillä käyttöoikeuksilla
Ohjelma B voi allekirjoittaa allekirjoittajatilin avulla
Ohjelma B voi kirjoittaa kirjoitettavaan tiliin
Ohjelma B voi jopa välittää nämä samat käyttöoikeudet eteenpäin, jos se tekee omia CPI-kutsujaan

Cross Program Invocations

invoke funktio käsittelee CPI-kutsuja, jotka eivät vaadi PDA-allekirjoittajia. Funktio kutsuu invoke_signed funktiota tyhjällä signers_seeds taulukolla, mikä osoittaa, ettei allekirjoittamiseen tarvita PDA-tilejä.

Invoke Function

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

Seuraavat esimerkit näyttävät, miten tehdä CPI-kutsu käyttäen Anchor Framework -kehystä ja natiivi-Rustia. Esimerkkiohjelmat sisältävät yhden käskyn, joka siirtää SOL:ia yhdeltä tililtä toiselle CPI-kutsun avulla.

Anchor Framework

Seuraavat esimerkit esittelevät kolme tapaa luoda Cross Program Invocations (CPIs) Anchor-ohjelmassa, kukin eri abstraktiotasolla. Kaikki esimerkit toimivat samalla tavalla. Päätarkoituksena on näyttää CPI:n toteutuksen yksityiskohdat.

Esimerkki 1: Käyttää Anchorin CpiContext ja apufunktiota CPI-ohjeen rakentamiseen.
Esimerkki 2: Käyttää system_instruction::transfer -funktiota solana_program -paketista CPI-ohjeen rakentamiseen. Esimerkki 1 abstrahoi tämän toteutuksen.
Esimerkki 3: Rakentaa CPI-ohjeen manuaalisesti. Tämä lähestymistapa on hyödyllinen kun ohjeen rakentamiseen ei ole olemassa pakettia.

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>,
}

Native Rust

Seuraava esimerkki näyttää, miten tehdään CPI ohjelmasta, joka on kirjoitettu Native Rustilla. Ohjelma sisältää yhden ohjeen, joka siirtää SOL:ia yhdeltä tililtä toiselle käyttäen CPI:tä. 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 Invocations PDA-allekirjoittajilla

invoke_signed -funktio käsittelee CPI:t, jotka vaativat PDA-allekirjoittajia. Funktio ottaa siemenet PDA-allekirjoittajien johtamiseen signer_seeds.

Voit tutustua Program Derived Address -sivuun saadaksesi lisätietoja siitä, miten PDA:t johdetaan.

Invoke Signed

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

Kun käsitellään ohjetta, joka sisältää CPI:n, Solana-ajoympäristö kutsuu sisäisesti create_program_address käyttäen signers_seeds ja kutsuvan ohjelman program_id. Kun kelvollinen PDA on vahvistettu, osoite lisätään kelvolliseksi allekirjoittajaksi.

Seuraavat esimerkit havainnollistavat, miten tehdään CPI PDA-allekirjoittajilla käyttäen Anchor Framework -kehystä ja Native Rustia. Esimerkkiohjelmat sisältävät yhden ohjeen, joka siirtää SOL:ia PDA:lta vastaanottajatilille käyttäen PDA:n allekirjoittamaa CPI:tä.

Anchor Framework

Seuraavat esimerkit sisältävät kolme lähestymistapaa Cross Program Invocation (CPI) -toimintojen toteuttamiseen Anchor-ohjelmassa, kukin eri abstraktiotasolla. Kaikki esimerkit ovat toiminnallisesti samanarvoisia. Päätarkoituksena on havainnollistaa CPI:n toteutuksen yksityiskohtia.

Esimerkki 1: Käyttää Anchorin CpiContext ja apufunktiota CPI-ohjeen rakentamiseen.
Esimerkki 2: Käyttää system_instruction::transfer -funktiota solana_program -paketista CPI-ohjeen rakentamiseen. Esimerkki 1 on abstraktio tästä toteutuksesta.
Esimerkki 3: Rakentaa CPI-ohjeen manuaalisesti. Tämä lähestymistapa on hyödyllinen kun saatavilla ei ole 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>,
}

Native Rust

Seuraava esimerkki näyttää, miten tehdään CPI PDA-allekirjoittajilla ohjelmasta, joka on kirjoitettu natiivilla Rustilla. Ohjelma sisältää yhden ohjeen, joka siirtää SOL:ia PDA:lta vastaanottajatilille käyttäen PDA:n allekirjoittamaa CPI:tä. 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(())
        }
    }
}

Sisällysluettelo