Cross Program Invocation (CPI)

Cross Program Invocation (CPI) 指的是一个程序调用另一个程序的指令。这使得 Solana 程序具有可组合性。

您可以将指令视为程序向网络公开的 API 端点，而 CPI 则是一个 API 在内部调用另一个 API。

Cross Program Invocation

关键点

Cross Program Invocations 使 Solana 程序指令能够直接调用另一个程序的指令。
签名权限 从调用程序扩展到被调用程序。
在进行 Cross Program Invocation 时，程序可以代表从其自身程序 ID 派生的 PDA 进行签名。
被调用程序可以进一步对其他程序进行 CPI，深度最多为 4。

什么是 CPI？

Cross Program Invocation (CPI) 是指一个程序调用另一个程序的指令。

使用 CPI 编写程序指令的模式与构建一个添加到交易中的指令相同。在底层，每个 CPI 指令必须指定：

程序地址：指定要调用的程序
账户：列出指令读取或写入的每个账户，包括其他程序
指令数据：指定要在程序上调用的指令，以及指令所需的任何数据（函数参数）

当一个程序对另一个程序进行 Cross Program Invocation (CPI) 时：

初始交易中的签名者权限会扩展到被调用程序（例如 A->B）
被调用程序可以进一步对其他程序进行 CPI，最多可达 4 层深度（例如 B->C，C->D）
程序可以代表其程序 ID 派生的 PDA 进行“签名”

Solana 程序运行时设置了一个常量 max_instruction_stack_depth MAX_INSTRUCTION_STACK_DEPTH，其值为 5。这表示程序指令调用堆栈的最大高度。堆栈高度从初始交易开始为 1，每当一个程序调用另一个指令时，堆栈高度增加 1。此设置将 CPI 的调用深度限制为 4。

当处理交易时，账户权限会从一个程序扩展到另一个程序。这意味着：

假设程序 A 收到一个指令，其中包含：

一个签署了交易的账户
一个可以被写入（可变）的账户

当程序 A 对程序 B 进行 CPI 时：

程序 B 可以使用这些账户，并保留其原始权限
程序 B 可以使用签名者账户进行签名
程序 B 可以写入可写账户
如果程序 B 进行自己的 CPI，它甚至可以将这些权限进一步传递

跨程序调用

invoke 函数处理不需要 PDA 签名者的 CPI。该函数调用 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 程序中创建 Cross Program Invocations (CPI) 的三种方法，每种方法具有不同的抽象级别。所有示例的工作方式相同，主要目的是展示 CPI 的实现细节。

示例 1：使用 Anchor 的 CpiContext 和辅助函数构建 CPI 指令。
示例 2：使用 solana_program crate 中的 system_instruction::transfer 函数构建 CPI 指令。示例 1 是此实现的抽象。
示例 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(())
        }
    }
}

使用 PDA 签名者的 Cross Program Invocations

invoke_signed 函数处理需要 PDA 签名者的 CPI。该函数将用于派生签名者 PDA 的种子作为 signer_seeds。

您可以参考 Program Derived Address 页面了解如何派生 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)
}

在处理包含 CPI 的指令时，Solana 运行时会内部调用 create_program_address，使用 signers_seeds 和调用程序的 program_id。当验证了有效的 PDA 后，该地址会被添加为有效签名者。

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

Anchor 框架

以下示例展示了在 Anchor 程序中实现 Cross Program Invocations (CPI) 的三种方法，每种方法具有不同的抽象级别。所有示例在功能上是等效的，主要目的是说明 CPI 的实现细节。

示例 1：使用 Anchor 的 CpiContext 和辅助函数来构建 CPI 指令。
示例 2：使用 solana_program crate 中的 system_instruction::transfer 函数来构建 CPI 指令。示例 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(())
        }
    }
}

Table of Contents