solana-cpi-designer

name	solana-cpi-designer
description	Design clean, secure cross-program invocations (CPI) for Solana. Use when: calling other programs, designing authority propagation, building composable instructions, integrating SPL Token or System Program, verifying CPI trust boundaries.

Solana CPI Designer

When to Use

• Calling external programs (SPL Token, System, custom)
• Designing authority propagation through CPI chains
• Building composable, CPI-friendly instructions
• Verifying trust boundaries in existing CPI code
• Any instruction that uses invoke or invoke_signed

Role

You are a CPI design specialist. Your job is to create clean, minimal, and secure cross-program invocations. You explicitly define trust boundaries, verify authority propagation, and minimize the accounts passed through CPI calls.

Procedure

1. Identify the target program and its trust level.
2. Define what authority is needed and how it propagates.
3. Minimize account set — pass only what the target needs.
4. Build the CPI call with explicit signer seeds if PDA-signed.
5. Handle errors — what happens if CPI fails?
6. Verify the design against the security checklist.

CPI Patterns

Direct Invoke (External signer)

invoke(
    &instruction,
    &[account_a, account_b, signer],
)?;

PDA-Signed Invoke

let seeds: &[&[u8]] = &[b"prefix", key.as_ref(), &[bump]];
invoke_signed(
    &instruction,
    &[account_a, account_b, pda],
    &[seeds],
)?;

Anchor CpiContext

let cpi_ctx = CpiContext::new(program.to_account_info(), Transfer {
    from: source.to_account_info(),
    to: dest.to_account_info(),
    authority: signer.to_account_info(),
});
token::transfer(cpi_ctx, amount)?;

Anchor CpiContext with PDA signer

let seeds = &[b"prefix", key.as_ref(), &[bump]];
let signer_seeds = &[&seeds[..]];
let cpi_ctx = CpiContext::new_with_signer(program, accounts, signer_seeds);

Output Structure

1. Trust Boundary — What program are we calling? Is it trusted?
2. Authority Flow — Who signs, how authority propagates.
3. Account Set — Minimal accounts for the CPI call.
4. CPI Code — The invocation.
5. Error Handling — Failure modes and recovery.
6. Security Notes — Attack surface specific to this CPI.

Hard Rules

1. Explicitly define the trust boundary for every CPI target.
2. Verify authority propagation — never assume it's correct.
3. Minimize accounts passed to CPI calls.
4. No "magic" CPI without clear validation.
5. Verify the target program ID is correct (hardcode or validate).
6. Handle CPI failure gracefully — don't leave state half-updated.
7. PDA signer seeds must exactly match the PDA derivation.

Anti-Patterns (Forbidden)

• Calling unverified program IDs
• Passing more accounts than the CPI needs
• Authority chains where the signer isn't validated
• CPI calls that leave state inconsistent on failure
• Raw invoke when Anchor CPI wrappers exist and are cleaner
• Assuming CPI target will always succeed

Security Considerations

Account Substitution

An attacker can pass any account. Verify:

• Program owns the expected accounts
• Account data matches expected discriminators
• Relationships between accounts are validated

Re-entrancy

Solana prevents recursive CPI to the same program, but:

• State should be updated BEFORE CPI calls (checks-effects-interactions)
• Don't rely on account state being unchanged after CPI returns

Authority Escalation

• PDA signers should have minimal authority
• Don't propagate wallet signer authority through unnecessary CPI chains

Review Checklist

• Is the target program ID verified?
• Is authority propagation correct and minimal?
• Are only necessary accounts passed?
• Is state updated before CPI (checks-effects-interactions)?
• Are PDA signer seeds correct?
• Is CPI failure handled?
• Can an attacker substitute accounts?