Cross Program Invocation (CPI)

Cross Program Invocation (CPI)とは、あるプログラムが別のプログラムのinstructionsを呼び出すことを指します。これによりSolanaプログラムの組み合わせが可能になります。

instructionsはプログラムがネットワークに公開するAPIエンドポイントのようなもので、CPIは1つのAPIが内部で別のAPIを呼び出すようなものと考えることができます。

Cross Program Invocation

重要なポイント

Cross Program InvocationはSolanaプログラムのinstructionsが別のプログラムのinstructionsを直接呼び出すことを可能にします。
呼び出し元プログラムの署名者権限は呼び出し先プログラムにも拡張されます。
Cross Program Invocationを行う際、プログラムは自身のプログラムIDから派生したPDAの代わりに署名することができます。
呼び出し先プログラムは他のプログラムに対してさらにCPIを行うことができ、その深さは最大4レベルまでです。

CPIとは何か？

Cross Program Invocation (CPI)とは、あるプログラムが別のプログラムのinstructionsを呼び出すことです。

CPIを使用したプログラムinstructionの作成は、トランザクションに追加するinstructionの構築と同じパターンに従います。内部的には、各CPI instructionは以下を指定する必要があります：

プログラムアドレス：呼び出すプログラムを指定します
アカウント：instructionが読み取りまたは書き込みを行うすべてのアカウントを一覧表示します（他のプログラムを含む）
instruction data：プログラム上で呼び出すinstructionを指定し、さらにinstructionが必要とするデータ（関数の引数）を含みます

プログラムが別のプログラムにCross Program Invocation (CPI)を行う場合：

最初のトランザクションの署名者特権は呼び出し先プログラムに拡張されます（例：A->B）
呼び出し先プログラムは、最大深さ4まで他のプログラムに対してさらにCPIを行うことができます（例：B->C、C->D）
プログラムはそのプログラムIDから派生したPDAの「代わりに署名」することができます

Solanaプログラムランタイムは max_instruction_stack_depth 定数 MAX_INSTRUCTION_STACK_DEPTH を5に設定しています。これはプログラムinstructions呼び出しスタックの最大高さを表します。スタックの高さは最初のトランザクションで1から始まり、プログラムが別のinstructionsを呼び出すたびに1ずつ増加します。この設定により、CPIの呼び出し深度は4に制限されています。

トランザクションが処理されると、アカウント特権は一つのプログラムから別のプログラムへと拡張されます。これが意味することは：

プログラムAが以下を含むinstructionsを受け取ったとします：

トランザクションに署名したアカウント
書き込み可能なアカウント（可変）

プログラムAがプログラムBにCPIを行う場合：

プログラムBは元の権限を持つ同じアカウントを使用できます
プログラムBは署名者アカウントで署名できます
プログラムBは書き込み可能なアカウントに書き込むことができます
プログラムBが独自のCPIを行う場合、これらの同じ権限を転送することもできます

Cross Program Invocation

invoke関数は、PDA署名者を必要としないCPIを処理します。この関数は空のsigners_seeds配列を持つinvoke_signed関数を呼び出し、署名に必要なPDAがないことを示します。

Invoke Function

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

以下の例は、AnchorフレームワークとネイティブRustを使用してCPIを行う方法を示しています。サンプルプログラムには、CPIを使用して一つのアカウントから別のアカウントにSOLを転送する単一のinstructionsが含まれています。

Anchor フレームワーク

以下の例では、Anchorプログラムでクロスプログラム呼び出し（CPIs）を作成する3つの方法を紹介します。それぞれ異なる抽象化レベルで実装されていますが、すべての例は同じように機能します。主な目的はCPIの実装詳細を示すことです。

例1：Anchorの CpiContext とヘルパー関数を使用してCPI instructionsを構築します。
例2：solana_program クレートから system_instruction::transfer 関数を使用してCPI instructionsを構築します。例1はこの実装を抽象化したものです。
例3：CPI instructionsを手動で構築します。このアプローチは、instructionsを構築するためのクレートが存在しない場合に役立ちます。

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を転送する単一のinstructionsが含まれています。テストファイルでは、プログラムをテストするために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署名者によるクロスプログラム呼び出し

invoke_signed関数は、PDA署名者を必要とするCPIを処理します。この関数は、署名者PDAを導出するためのseedをsigner_seedsとして受け取ります。

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を含むinstructionsを処理する際、Solanaランタイムは内部的に呼び出し元プログラムのsigners_seedsとprogram_idを使用してcreate_program_addressを呼び出します。有効なPDAが検証されると、そのアドレスは有効な署名者として追加されます。

以下の例では、Anchor フレームワークとネイティブRustを使用してPDA署名者によるCPIを行う方法を示しています。これらのサンプルプログラムには、PDAによって署名されたCPIを使用してPDAから受信者アカウントにSOLを転送する単一のinstructionsが含まれています。

Anchor フレームワーク

以下の例では、Anchorプログラムでクロスプログラム呼び出し（CPIs）を実装するための3つのアプローチを紹介します。それぞれ異なるレベルの抽象化を示しています。すべての例は機能的に同等です。主な目的はCPIの実装詳細を説明することです。

例1：Anchorの CpiContext とヘルパー関数を使用してCPI instructionsを構築します。
例2：solana_program クレートから system_instruction::transfer 関数を使用してCPI instructionsを構築します。例1はこの実装の抽象化です。
例3：CPI instructionsを手動で構築します。この方法は、呼び出したいinstructionsの構築を支援するクレートが利用できない場合に役立ちます。

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を使用してPDAから受信者アカウントにSOLを転送する単一のinstructionsが含まれています。テストファイルでは、プログラムをテストするために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(())
        }
    }
}

目次