Cross Program Invocation

当一个 Solana 程序直接调用另一个程序的指令时，就会发生跨程序调用 (CPI)。这使得程序具有可组合性。如果将 Solana 的指令视为程序向网络公开的 API 端点，那么 CPI 就像一个端点在内部调用另一个端点。

在进行 CPI 时，程序可以代表从其程序 ID 派生的 PDA 进行签名。这些签名者权限从调用程序扩展到被调用程序。

跨程序调用示例

在进行 CPI 时，账户权限从一个程序扩展到另一个程序。假设程序 A 接收到一个包含签名账户和可写账户的指令。程序 A 然后对程序 B 进行 CPI。此时，程序 B 可以使用与程序 A 相同的账户，并保留其原始权限。（这意味着程序 B 可以使用签名账户进行签名，并可以写入可写账户。）如果程序 B 自己进行 CPI，它可以将这些相同的权限继续传递下去，最多可以传递 4 层。

程序指令调用的最大堆栈高度称为 max_instruction_stack_depth ，并被设置为 MAX_INSTRUCTION_STACK_DEPTH 常量的值 5。

堆栈高度从初始交易的 1 开始，每当一个程序调用另一个指令时增加 1，从而将 CPI 的调用深度限制为 4。

带有 PDA 签名者的 CPI

当 CPI 需要 PDA 签名者时，会使用 invoke_signed 函数。它接收用于派生签名者 PDA 的签名者种子。Solana 运行时会内部调用 create_program_address，使用调用程序的 signers_seeds 和 program_id。当 PDA 被验证后，它会被添加为有效签名者。

Invoke signed

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

以下示例展示了如何使用 Anchor 和原生 Rust 进行带有 PDA 签名者的 CPI。每个示例都包含一个通过 PDA 签名的 CPI 指令，将 SOL 从 PDA 转移到接收账户。

Anchor

以下示例展示了在 Anchor 程序中实现 CPI 的三种方法。这些示例在功能上是等效的，但每个示例展示了不同的抽象级别。

示例 1：使用 Anchor 的 CpiContext 和辅助函数。
示例 2：使用 solana_program crate 中的 system_instruction::transfer 函数。（示例 1 是此实现的抽象。）
示例 3：手动构建 CPI 指令。当没有可用的 crate 来帮助构建您想调用的指令时，这种方法非常有用。

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

以下示例展示了如何从用原生 Rust 编写的程序中进行带有 PDA 签名者的 CPI。它包含一个通过 PDA 签名的 CPI 指令，将 SOL 从 PDA 账户转移到另一个账户。（测试文件使用 LiteSVM 测试该程序。）

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

无 PDA 签名者的 CPI

当 CPI 不需要 PDA 签名者时，会使用 invoke 函数。invoke 函数会调用 invoke_signed 函数，并传递一个空的 signers_seeds 数组。空的签名者数组表示不需要任何 PDA 进行签名。

Invoke function

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

以下示例展示了如何使用 Anchor 和原生 Rust 进行 CPI。示例包括一个指令，通过 CPI 将 SOL 从一个账户转移到另一个账户。

Anchor

以下示例展示了在 Anchor 程序中实现 CPI 的三种方法。这些示例在功能上是等效的，但每个示例展示了不同的抽象级别。

示例 1：使用 Anchor 的 CpiContext 和辅助函数。
示例 2：使用 solana_program crate 中的 system_instruction::transfer 函数。
示例 3：手动构建 CPI 指令。当没有可用的 crate 来帮助构建所需的指令时，这种方法非常有用。

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

以下示例展示了如何从一个用原生 Rust 编写的程序中创建 CPI。示例包括一个指令，通过 CPI 将 SOL 从一个账户转移到另一个账户。（测试文件使用 LiteSVM 测试程序。）

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

带有 PDA 签名者的 CPI

Anchor

Rust

无 PDA 签名者的 CPI

Anchor

Rust

Table of Contents