Cross Program Invocation (CPI)

Cross Program Invocation (CPI) относится к случаю, когда одна программа вызывает инструкции другой программы. Это позволяет создавать композиции программ Solana.

Вы можете представить инструкции как API-эндпоинты, которые программа предоставляет сети, а CPI — как внутренний вызов одного API другим API.

Cross Program InvocationCross Program Invocation

Основные моменты

  • Cross Program Invocation позволяет инструкциям программы Solana напрямую вызывать инструкции другой программы.
  • Привилегии подписанта от вызывающей программы распространяются на вызываемую программу.
  • При выполнении Cross Program Invocation программы могут подписывать от имени PDA, производных от их собственного ID программы.
  • Вызываемая программа может выполнять дальнейшие CPIs для других программ, до глубины 4.

Что такое CPI?

Cross Program Invocation (CPI) — это процесс, когда одна программа вызывает инструкции другой программы.

Написание инструкции программы с использованием CPI следует той же схеме, что и создание инструкции для добавления в транзакцию. На уровне реализации каждая инструкция CPI должна указывать:

  • Адрес программы: Указывает программу для вызова
  • Аккаунты: Перечисляет все аккаунты, из которых инструкция читает или в которые записывает, включая другие программы
  • Instruction Data: Указывает, какую инструкцию вызвать в программе, а также любые данные, необходимые для инструкции (аргументы функции)

Когда программа выполняет Cross Program Invocation (CPI) для другой программы:

  • Привилегии подписанта из исходной транзакции распространяются на вызываемую программу (например, A->B)
  • Вызываемая программа может выполнять дальнейшие CPI к другим программам, до глубины 4 (например, B->C, C->D)
  • Программы могут "подписывать" от имени PDA, производных от их идентификатора программы

Среда выполнения программ Solana устанавливает max_instruction_stack_depth константу MAX_INSTRUCTION_STACK_DEPTH равную 5. Это представляет максимальную высоту стека вызовов инструкций программы. Высота стека начинается с 1 для исходной транзакции и увеличивается на 1 каждый раз, когда программа вызывает другую инструкцию. Этот параметр ограничивает глубину вызовов для CPI до 4.

Когда транзакция обрабатывается, привилегии аккаунтов распространяются от одной программы к другой. Вот что это означает:

Предположим, Программа A получает инструкцию с:

  • Аккаунтом, который подписал транзакцию
  • Аккаунтом, который можно изменять (изменяемый)

Когда Программа A выполняет CPI к Программе B:

  • Программа B получает возможность использовать те же аккаунты с их исходными разрешениями
  • Программа B может подписывать с помощью аккаунта подписанта
  • Программа B может записывать в изменяемый аккаунт
  • Программа B может даже передать эти же разрешения дальше, если она выполняет свои собственные CPI

Cross Program Invocations

Функция invoke обрабатывает CPI, которые не требуют подписантов PDA. Функция вызывает invoke_signed с пустым массивом signers_seeds, указывая, что PDA не требуются для подписания.

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

Следующие примеры показывают, как выполнить CPI с использованием Anchor Framework и Native Rust. Примерные программы включают одну инструкцию, которая переводит SOL с одного аккаунта на другой с использованием CPI.

Фреймворк Anchor

Следующие примеры демонстрируют три способа создания Cross Program Invocations (CPI) в программе Anchor, каждый из которых находится на разном уровне абстракции. Все примеры работают одинаково. Основная цель — показать детали реализации CPI.

  • Пример 1: Использует CpiContext от Anchor и вспомогательную функцию для создания инструкции CPI.
  • Пример 2: Использует функцию system_instruction::transfer из крейта solana_program для создания инструкции CPI. Пример 1 абстрагирует эту реализацию.
  • Пример 3: Создает инструкцию CPI вручную. Этот подход полезен, когда нет доступного крейта для помощи в создании инструкции.
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

Следующий пример показывает, как сделать CPI из программы, написанной на нативном Rust. Программа включает одну инструкцию, которая переводит SOL с одного аккаунта на другой с использованием CPI. Тестовый файл использует 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 Invocations с PDA-подписантами

Функция invoke_signed обрабатывает CPI, которые требуют PDA-подписантов. Функция принимает seed для вывода 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 проверен, адрес добавляется как валидный подписант.

Следующие примеры демонстрируют, как сделать CPI с PDA-подписантами, используя Anchor Framework и нативный Rust. Примерные программы включают одну инструкцию, которая переводит SOL с PDA на аккаунт получателя с использованием CPI, подписанного PDA.

Фреймворк Anchor

Следующие примеры включают три подхода к реализации Cross Program Invocations (CPI) в программе Anchor, каждый из которых находится на разном уровне абстракции. Все примеры функционально эквивалентны. Основная цель — продемонстрировать детали реализации CPI.

  • Пример 1: Использует CpiContext Anchor и вспомогательную функцию для создания инструкции CPI.
  • Пример 2: Использует функцию system_instruction::transfer из крейта solana_program для создания инструкции CPI. Пример 1 является абстракцией этой реализации.
  • Пример 3: Создает инструкцию CPI вручную. Этот подход полезен, когда нет доступного крейта для помощи в создании инструкции, которую вы хотите вызвать.
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

Следующий пример показывает, как выполнить CPI с PDA-подписантами из программы, написанной на нативном Rust. Программа включает одну инструкцию, которая переводит SOL с PDA на учетную запись получателя, используя CPI, подписанный 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?

Содержание

Редактировать страницу