Cross-Program Invocation (CPI)
Suggest an editIn a Cross-Program Invocation (CPI), a program calls another program in the middle of its own execution, passes it accounts, and observes the result before continuing. The accounts keep the signer and writable flags they had in the caller, and the called program never gets more than that.
Only the owner program can change an account, so you ask the owner
The programs you've written so far operate on accounts owned by your own program. What you can't do, alone, is move SPL tokens, mint NFTs, place an order on a DEX, or do anything else that requires touching state owned by a different program.
Each account has one owner program, and only that owner can mutate the account's data. So if you want to move tokens out of a vault, you can't write zeros over the source balance and write a higher number into the destination. The tokens live in accounts owned by the Token Program, and only the Token Program can mutate them.
The way you make changes to accounts you don't own is to ask the program that owns them to do it on your behalf. You construct a request, you hand it to the runtime, and the runtime hands it to the owning program. If your request is well-formed and you have the right authority, the owning program performs the mutation and returns success. That request is a CPI.
A CPI is an instruction built inside your program
A CPI happens in four phases. Your handler builds an Instruction describing what it wants the called program to do. It calls the invoke syscall, passing the instruction along with references to the accounts the called program will need. The runtime suspends your program, switches execution to the called program, and runs it with those accounts. When the called program returns, control comes back to your handler with the state changes already applied.
The Instruction struct is the same shape as the instructions a wallet builds and submits in a transaction. The CPI version is built inside another program and sent through the syscall instead of arriving from the network, but the runtime treats them the same way once they're being executed.
Privileges propagate, and they never grow
When your handler runs, each account in its frame carries flags: was this account a signer in the transaction, and is it marked writable. When you CPI to another program, those flags travel through.
Take the three accounts in the diagram. Alice signed the transaction, vault is marked writable, and mint is read-only. When your handler makes a CPI to the Token Program with these accounts, the Token Program sees Alice as a signer, can write to vault, and can only read mint.
What you cannot do is escalate authority. If your handler marked mint as writable or vault as a signer in the inner instruction, the runtime would reject the CPI. A program can only delegate authority it already has. If the runtime allowed a new signer, a program could mark any wallet passed to it as a signer and have the Token Program move that wallet's tokens. If it allowed a new writable account, a program could write to an account that the transaction declared read-only, and the runtime uses those declarations to decide which transactions run in parallel (instructions and transactions).
You can drop authority: if your handler can write to an account, you can pass it to a CPI as readonly, telling the called program it may read the account but not write to it. This lets you call programs that need to read state without granting them write access they don't need.
invoke forwards signers, invoke_signed adds a PDA your program controls
The runtime exposes two syscalls. invoke forwards existing signers downstream. invoke_signed does the same, plus it lets your program sign as one or more PDAs, which is the one exception to the rule that a CPI adds no signers. Your program passes the PDA's seeds, the runtime re-derives the PDA, confirms it belongs to your program, and treats it as a signer in the called program's frame. A vault PDA authorizes a token transfer out of its own token account this way.
The signer seeds passed to invoke_signed are an array of seed arrays. Each inner array re-derives one PDA, so you can sign on behalf of multiple PDAs in a single call. A concrete shape for the seeds, with the bump appended at the end:
let bump = ctx.accounts.vault.bump;
let mint_key = ctx.accounts.mint.key();
let seeds: &[&[u8]] = &[b"vault", mint_key.as_ref(), &[bump]];
let signer_seeds: &[&[&[u8]]] = &[seeds];
invoke_signed(&ix, &account_infos, signer_seeds)?;The PDAs as signers lesson explains why the runtime accepts seeds in place of a signature.
Anchor's CpiContext builds the instruction for you
Writing raw Instruction structs and calling invoke directly is verbose and easy to get wrong. Anchor provides a typed wrapper called CpiContext that builds the instruction and account structures for you when calling known programs, and the SPL Token bindings in anchor_spl give you typed structs for every Token Program instruction.
A token transfer through Anchor looks like this:
use anchor_spl::token::{self, Transfer};
let cpi_accounts = Transfer {
from: ctx.accounts.source.to_account_info(),
to: ctx.accounts.destination.to_account_info(),
authority: ctx.accounts.authority.to_account_info(),
};
let cpi_ctx = CpiContext::new(
ctx.accounts.token_program.to_account_info(),
cpi_accounts,
);
token::transfer(cpi_ctx, amount)?;The Transfer struct names every account the Token Program's transfer instruction expects, with the correct field names. CpiContext::new packages the program reference together with the accounts. token::transfer builds the right Instruction, calls invoke, and returns the result.
For invoke_signed, the equivalent constructor is CpiContext::new_with_signer, which takes the same arguments plus a signer seeds slice. The call to token::transfer is the same.
The raw syscall form exists so you can use it directly when no typed wrapper exists for the program you're calling. For the popular SPL programs, the typed wrappers cover the common operations.
The called program can do everything the forwarded signers can
Because authority never grows through a CPI, a program you call cannot do anything with the accounts you gave it that you couldn't have done yourself. The cost is that the called program gets all of that authority. It receives every signer and writable account you forward and can pass them on to any other program. With Alice's signature and her token account, it can ask the Token Program to move her tokens somewhere else.
On Ethereum, when contract A calls contract B, B sees A as msg.sender, not the wallet that started the transaction, and a contract that B calls sees B. On Solana, a wallet that signed the transaction is a signer in every program it is forwarded to.
Your program also has to be sure which program it is calling. The program to call is an account in a slot that the client fills. If your code does not check that slot, the client can pass their own program in place of the Token Program. That program can return success without moving any tokens, and your handler continues as if the transfer happened. Declaring the slot as Program<'info, Token> pins its address (account types), and the classic exploits lesson goes through this bug in code.
A transaction can invoke up to four levels deep: your handler is depth one, a CPI from it is depth two, a CPI from that is depth three, and one more layer is allowed. Beyond that, the runtime rejects the call. If an aggregator calls your program and your program calls the Token Program, your handler already runs at depth two and its transfer at depth three.
For each CPI in your program, name the signers and writable accounts it forwards, and name what in your Accounts struct fixes the address of the program that receives them.