Sign in

Cross-Program Invocation (CPI)

Suggest an edit

In 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.

CPI account flags: alice, vault, and mint keep the same signer and writable statusTwo account tables compare program A's frame with the called program B's frame for accounts alice, vault, and mint, and their signer and writable flags match exactly. A rules list below states that privileges never grow across a CPI, except a program can sign as a PDA it controls via invoke_signed. Privileges propagate, but never grow Your handler's frame (program A) account signer? writable? alice (Signer) yes yes vault (mut Account) no yes mint (Account) no no these are the flags your accounts carry in your handler CPI to Token Program The called program sees (program B) account signer? writable? alice yes yes vault no yes mint no no the same flags propagate through. nothing was upgraded. The rules → Signers from your frame stay signers in the called program's frame. → Writability is preserved, or you can drop it (pass writable as readonly). → A non-signer can never become a signer mid-call. Privileges never grow. → Exception: your program can sign as a PDA it controls, via invoke_signed. A program can only delegate authority it already has. This is the entire security model of CPI.

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.

invoke vs invoke_signed: forwarding signers vs signing as a PDATwo side-by-side panels compare the syscalls invoke and invoke_signed for calling another program. The invoke panel shows it forwarding existing signers, like Alice's signature used to move her tokens via a CPI to the Token Program; the invoke_signed panel shows it forwarding existing signers plus letting the program sign as a PDA, like a vault PDA authorizing a token transfer with seeds. Two ways to call another program invoke syscall: invoke(&ix, &accounts)?; what propagates: signers that signed your tx are still signers downstream use when: a human or wallet signed, and that signature is enough example: Alice signs your handler. You CPI to Token Program to move tokens from Alice's account. Alice is still the signer in the inner call. forwarding existing signatures invoke_signed syscall: invoke_signed(&ix, &accounts, signer_seeds)?; what propagates: existing signers, PLUS your program signs as a PDA use when: an account is owned by a PDA your program controls, and you need to authorize on its behalf example: a vault PDA owns a token account. you CPI to transfer from it. pass seeds; runtime re-derives, accepts as signer. programs signing on their own behalf Both syscalls forward signers. invoke_signed adds one capability: your program acting as a PDA.

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:

rust
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:

rust
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.