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 签名。
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 entrypointentrypoint!(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 datalet instruction = ProgramInstruction::unpack(instruction_data)?;// Process instructionmatch instruction {ProgramInstruction::SolTransfer { amount } => {// Parse accountslet [sender_info, recipient_info, system_program_info] = accounts else {return Err(ProgramError::NotEnoughAccountKeys);};// Verify the sender is a signerif !sender_info.is_signer {return Err(ProgramError::MissingRequiredSignature);}// Create and invoke the transfer instructionlet 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 的详细信息。
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 entrypointentrypoint!(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 datalet instruction = ProgramInstruction::unpack(instruction_data)?;// Process instructionmatch instruction {ProgramInstruction::SolTransfer { amount } => {// Parse accountslet [pda_account_info, recipient_info, system_program_info] = accounts else {return Err(ProgramError::NotEnoughAccountKeys);};// Derive PDA and verify it matches the account provided by clientlet 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 instructionlet transfer_ix = system_instruction::transfer(pda_account_info.key,recipient_info.key,amount,);// Create signer seeds for PDAlet signer_seeds: &[&[&[u8]]] = &[&[b"pda", recipient_pubkey.as_ref(), &[bump_seed]]];// Invoke the transfer instruction with PDA as signerinvoke_signed(&transfer_ix,&[pda_account_info.clone(),recipient_info.clone(),system_program_info.clone(),],signer_seeds,)?;Ok(())}}}
Is this page helpful?