Cross Program Invocation (CPI)

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

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

Cross Program InvocationCross 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(())
}
}
}

Is this page helpful?

Table of Contents

Edit Page