Anchor CPIs and Errors
Summary
- Anchor provides a simplified way to create CPIs using a
CpiContext - Anchor's
cpifeature generates CPI helper functions for invoking instructions on existing Anchor programs - If you do not have access to CPI helper functions, you can still use
invokeandinvoke_signeddirectly - The
error_codeattribute macro is used to create custom Anchor Errors
Lesson
Anchor makes invoking other Solana programs easier, especially if the program you're invoking is also an Anchor program whose crate you can access.
In this lesson, you'll learn how to construct an Anchor CPI. You'll also learn how to throw custom errors from an Anchor program so that you can start to write more sophisticated Anchor programs.
Cross Program Invocations (CPIs) with Anchor
CPIs allow programs to invoke instructions on other programs using the invoke
or invoke_signed functions. This allows new programs to build on top of
existing programs (we call that composability).
While making CPIs directly using invoke or invoke_signed is still an option,
Anchor also provides a simplified way to make CPIs by using a CpiContext.
In this lesson, you'll use the anchor_spl crate to make CPIs to the SPL Token
Program. You can
explore what's available in the anchor_spl crate.
CpiContext
The first step in making a CPI is to create an instance of CpiContext.
CpiContext is very similar to Context, the first argument type required by
Anchor instruction functions. They are both declared in the same module and
share similar functionality.
The CpiContext type specifies non-argument inputs for cross program
invocations:
accounts- the list of accounts required for the instruction being invokedremaining_accounts- any remaining accountsprogram- the program ID of the program being invokedsigner_seeds- if a PDA is signing, include the seeds required to derive the PDA
pub struct CpiContext<'a, 'b, 'c, 'info, T>
where
T: ToAccountMetas + ToAccountInfos<'info>,
{
pub accounts: T,
pub remaining_accounts: Vec<AccountInfo<'info>>,
pub program: AccountInfo<'info>,
pub signer_seeds: &'a [&'b [&'c [u8]]],
}
You use CpiContext::new to construct a new instance when passing along the
original transaction signature.
CpiContext::new(cpi_program, cpi_accounts)
pub fn new(
program: AccountInfo<'info>,
accounts: T
) -> Self {
Self {
accounts,
program,
remaining_accounts: Vec::new(),
signer_seeds: &[],
}
}
You use CpiContext::new_with_signer to construct a new instance when signing
on behalf of a PDA for the CPI.
CpiContext::new_with_signer(cpi_program, cpi_accounts, seeds)
pub fn new_with_signer(
program: AccountInfo<'info>,
accounts: T,
signer_seeds: &'a [&'b [&'c [u8]]],
) -> Self {
Self {
accounts,
program,
signer_seeds,
remaining_accounts: Vec::new(),
}
}
CPI accounts
One of the main things about CpiContext that simplifies cross-program
invocations is that the accounts argument is a generic type that lets you pass
in any object that adopts the ToAccountMetas and ToAccountInfos<'info>
traits.
These traits are added by the #[derive(Accounts)] attribute macro that you've
used before when creating structs to represent instruction accounts. That means
you can use similar structs with CpiContext.
This helps with code organization and type safety.
Invoke an instruction on another Anchor program
When the program you're calling is an Anchor program with a published crate, Anchor can generate instruction builders and CPI helper functions for you.
Simply declare your program's dependency on the program you're calling in your
program's Cargo.toml file as follows:
[dependencies]
callee = { path = "../callee", features = ["cpi"]}
By adding features = ["cpi"], you enable the cpi feature and your program
gains access to the callee::cpi module.
The cpi module exposes callee's instructions as a Rust function that takes
as arguments a CpiContext and any additional instruction data. These functions
use the same format as the instruction functions in your Anchor programs, only
with CpiContext instead of Context. The cpi module also exposes the
accounts structs required for calling the instructions.
For example, if callee has the instruction do_something that requires the
accounts defined in the DoSomething struct, you could invoke do_something as
follows:
use anchor_lang::prelude::*;
use callee;
...
#[program]
pub mod lootbox_program {
use super::*;
pub fn call_another_program(ctx: Context<CallAnotherProgram>, params: InitUserParams) -> Result<()> {
callee::cpi::do_something(
CpiContext::new(
ctx.accounts.callee.to_account_info(),
callee::DoSomething {
user: ctx.accounts.user.to_account_info()
}
)
)
Ok(())
}
}
...
Invoke an instruction on a non-Anchor program
When the program you're calling is not an Anchor program, there are two possible options:
- It's possible that the program maintainers have published a crate with their
own helper functions for calling into their program. For example, the
anchor_splcrate provides helper functions that are virtually identical from a call-site perspective to what you would get with thecpimodule of an Anchor program. E.g. you can mint using themint_tohelper function and use theMintToaccounts struct.token::mint_to(
CpiContext::new_with_signer(
ctx.accounts.token_program.to_account_info(),
token::MintTo {
mint: ctx.accounts.mint_account.to_account_info(),
to: ctx.accounts.token_account.to_account_info(),
authority: ctx.accounts.mint_authority.to_account_info(),
},
&[&[
"mint".as_bytes(),
&[*ctx.bumps.get("mint_authority").unwrap()],
]]
),
amount,
)?; - If there is no helper module for the program whose instruction(s) you need to
invoke, you can fall back to using
invokeandinvoke_signed. In fact, the source code of themint_tohelper function referenced above shows an example usinginvoke_signedwhen given aCpiContext. You can follow a similar pattern if you decide to use an accounts struct andCpiContextto organize and prepare your CPI.pub fn mint_to<'a, 'b, 'c, 'info>(
ctx: CpiContext<'a, 'b, 'c, 'info, MintTo<'info>>,
amount: u64,
) -> Result<()> {
let ix = spl_token::instruction::mint_to(
&spl_token::ID,
ctx.accounts.mint.key,
ctx.accounts.to.key,
ctx.accounts.authority.key,
&[],
amount,
)?;
solana_program::program::invoke_signed(
&ix,
&[
ctx.accounts.to.clone(),
ctx.accounts.mint.clone(),
ctx.accounts.authority.clone(),
],
ctx.signer_seeds,
)
.map_err(Into::into)
}
Throw errors in Anchor
We're deep enough into Anchor at this point that it's important to know how to create custom errors.
Ultimately, all programs return the same error
type: ProgramError.
However, when writing a program using Anchor you can use AnchorError as an
abstraction on top of ProgramError. This abstraction provides additional
information when a program fails, including:
- The error name and number
- Location in the code where the error was thrown
- The account that violated a constraint
pub struct AnchorError {
pub error_name: String,
pub error_code_number: u32,
pub error_msg: String,
pub error_origin: Option<ErrorOrigin>,
pub compared_values: Option<ComparedValues>,
}
Anchor Errors can be divided into:
- Anchor Internal Errors that the framework returns from inside its own code
- Custom errors that you the developer can create
You can add errors unique to your program by using the error_code attribute.
Simply add this attribute to a custom enum type. You can then use the variants
of the enum as errors in your program. Additionally, you can add an error
message to each variant using the msg attribute. Clients can then display this
error message if the error occurs.
#[error_code]
pub enum MyError {
#[msg("MyAccount may only hold data below 100")]
DataTooLarge
}
To return a custom error you can use the err or the error macro from an instruction function. These add file and line information to the error that is then logged by Anchor to help you with debugging.
#[program]
mod hello_anchor {
use super::*;
pub fn set_data(ctx: Context<SetData>, data: MyAccount) -> Result<()> {
if data.data >= 100 {
return err!(MyError::DataTooLarge);
}
ctx.accounts.my_account.set_inner(data);
Ok(())
}
}
#[error_code]
pub enum MyError {
#[msg("MyAccount may only hold data below 100")]
DataTooLarge
}
Alternatively, you can use the require macro to simplify returning errors. The code above can be refactored to the following:
#[program]
mod hello_anchor {
use super::*;
pub fn set_data(ctx: Context<SetData>, data: MyAccount) -> Result<()> {
require!(data.data < 100, MyError::DataTooLarge);
ctx.accounts.my_account.set_inner(data);
Ok(())
}
}
#[error_code]
pub enum MyError {
#[msg("MyAccount may only hold data below 100")]
DataTooLarge
}
Lab
Let’s practice the concepts we’ve gone over in this lesson by building on top of the Movie Review program from previous lessons.
In this lab we’ll update the program to mint tokens to users when they submit a new movie review.
Starter
To get started, we will be using the final state of the Anchor Movie Review
program from the previous lesson. So, if you just completed that lesson then
you’re all set and ready to go. If you are just jumping in here, no worries, you
can download the starter code.
We'll be using the solution-pdas branch as our starting point.
Add dependencies to Cargo.toml
Before we get started we need enable the init-if-needed feature and add the
anchor-spl crate to the dependencies in Cargo.toml. If you need to brush up
on the init-if-needed feature take a look at the
Anchor PDAs and Accounts lesson.
[dependencies]
anchor-lang = { version = "0.30.1", features = ["init-if-needed"] }
anchor-spl = "0.30.1"
Initialize reward token
Next, navigate to lib.rs and implement the InitializeMint context type and
list the accounts and constraints the instruction requires. Here we initialize a
new Mint account using a PDA with the string "mint" as a seed. Note that we
can use the same PDA for both the address of the Mint account and the mint
authority. Using a PDA as the mint authority enables our program to sign for the
minting of the tokens.
To initialize the Mint account, we'll need to include the token_program,
rent, and system_program in the list of accounts.
#[derive(Accounts)]
pub struct InitializeMint<'info> {
#[account(
init,
seeds = ["mint".as_bytes()],
bump,
payer = user,
mint::decimals = 6,
mint::authority = mint,
)]
pub mint: Account<'info, Mint>,
#[account(mut)]
pub user: Signer<'info>,
pub token_program: Program<'info, Token>,
pub rent: Sysvar<'info, Rent>,
pub system_program: Program<'info, System>
}
There may be some constraints above that you haven't seen yet. Adding
mint::decimals and mint::authority along with init ensures that the
account is initialized as a new token mint with the appropriate decimals and
mint authority set.
Now, create an instruction to initialize a new token mint. This will be the token that is minted each time a user leaves a review. Note that we don't need to include any custom instruction logic since the initialization can be handled entirely through Anchor constraints.
pub fn initialize_token_mint(_ctx: Context<InitializeMint>) -> Result<()> {
msg!("Token mint initialized");
Ok(())
}
Anchor Error
Next, let’s create an Anchor Error that we’ll use to validate the following:
- The
ratingpassed to either theadd_movie_revieworupdate_movie_reviewinstruction. - The
titlepassed to theadd_movie_reviewinstruction. - The
descriptionpassed to either theadd_movie_revieworupdate_movie_reviewinstruction.
#[error_code]
enum MovieReviewError {
#[msg("Rating must be between 1 and 5")]
InvalidRating,
#[msg("Movie Title too long")]
TitleTooLong,
#[msg("Movie Description too long")]
DescriptionTooLong,
}
Update add_movie_review instruction
Now that we've done some setup, let’s update the add_movie_review instruction
and AddMovieReview context type to mint tokens to the reviewer.
Next, update the AddMovieReview context type to add the following accounts:
token_program- we'll be using the Token Program to mint tokensmint- the mint account for the tokens that we'll mint to users when they add a movie reviewtoken_account- the associated token account for the afforementionedmintand reviewerassociated_token_program- required because we'll be using theassociated_tokenconstraint on thetoken_account
#[derive(Accounts)]
#[instruction(title: String, description: String)]
pub struct AddMovieReview<'info> {
#[account(
init,
seeds=[title.as_bytes(), initializer.key().as_ref()],
bump,
payer = initializer,
space = MovieAccountState::INIT_SPACE + title.len() + description.len()
)]
pub movie_review: Account<'info, MovieAccountState>,
#[account(mut)]
pub initializer: Signer<'info>,
pub system_program: Program<'info, System>,
pub token_program: Program<'info, Token>,
#[account(
seeds = ["mint".as_bytes()],
bump,
mut
)]
pub mint: Account<'info, Mint>,
#[account(
init_if_needed,
payer = initializer,
associated_token::mint = mint,
associated_token::authority = initializer
)]
pub token_account: Account<'info, TokenAccount>,
pub associated_token_program: Program<'info, AssociatedToken>,
}
Again, some of the above constraints may be unfamiliar to you. The
associated_token::mint and associated_token::authority constraints along
with the init_if_needed constraint ensures that if the account has not already
been initialized, it will be initialized as an associated token account for the
specified mint and authority. Also, the payer for the costs related with the
account initialization will be set under the constraint payer.
If you're unfamiliar with the INIT_SPACE constant used for the movie_review
account space allocation, please refer to the
solution-pdas
branch that is being used as our starting point. In there, we discuss the
implementation of the Space trait and the INIT_SPACE constant.
Next, let’s update the add_movie_review instruction to do the following:
- Check that
ratingis valid. If it is not a valid rating, return theInvalidRatingerror. - Check that
titlelength is valid. If it is not a valid length, return theTitleTooLongerror. - Check that
descriptionlength is valid. If it is not a valid length, return theDescriptionTooLongerror. - Make a CPI to the token program’s
mint_toinstruction using the mint authority PDA as a signer. Note that we'll mint 10 tokens to the user but need to adjust for the mint decimals by making it10*10^6.
Fortunately, we can use the anchor_spl crate to access helper functions and
types like mint_to and MintTo for constructing our CPI to the Token Program.
mint_to takes a CpiContext and integer as arguments, where the integer
represents the number of tokens to mint. MintTo can be used for the list of
accounts that the mint instruction needs.
Update your use statements to include:
use anchor_spl::token::{mint_to, MintTo, Mint, TokenAccount, Token};
use anchor_spl::associated_token::AssociatedToken;
Next, update the add_movie_review function to:
pub fn add_movie_review(ctx: Context<AddMovieReview>, title: String, description: String, rating: u8) -> Result<()> {
// We require that the rating is between 1 and 5
require!(rating >= MIN_RATING && rating <= MAX_RATING, MovieReviewError::InvalidRating);
// We require that the title is not longer than 20 characters
require!(title.len() <= MAX_TITLE_LENGTH, MovieReviewError::TitleTooLong);
// We require that the description is not longer than 50 characters
require!(description.len() <= MAX_DESCRIPTION_LENGTH, MovieReviewError::DescriptionTooLong);
msg!("Movie review account created");
msg!("Title: {}", title);
msg!("Description: {}", description);
msg!("Rating: {}", rating);
let movie_review = &mut ctx.accounts.movie_review;
movie_review.reviewer = ctx.accounts.initializer.key();
movie_review.title = title;
movie_review.description = description;
movie_review.rating = rating;
mint_to(
CpiContext::new_with_signer(
ctx.accounts.token_program.to_account_info(),
MintTo {
authority: ctx.accounts.mint.to_account_info(),
to: ctx.accounts.token_account.to_account_info(),
mint: ctx.accounts.mint.to_account_info()
},
&[&[
"mint".as_bytes(),
&[ctx.bumps.mint]
]]
),
10*10^6
)?;
msg!("Minted tokens");
Ok(())
}
Update update_movie_review instruction
Here we are only adding the check that rating and description are valid.
pub fn update_movie_review(ctx: Context<UpdateMovieReview>, title: String, description: String, rating: u8) -> Result<()> {
// We require that the rating is between 1 and 5
require!(rating >= MIN_RATING && rating <= MAX_RATING, MovieReviewError::InvalidRating);
// We require that the description is not longer than 50 characters
require!(description.len() <= MAX_DESCRIPTION_LENGTH, MovieReviewError::DescriptionTooLong);
msg!("Movie review account space reallocated");
msg!("Title: {}", title);
msg!("Description: {}", description);
msg!("Rating: {}", rating);
let movie_review = &mut ctx.accounts.movie_review;
movie_review.description = description;
movie_review.rating = rating;
Ok(())
}
Test
Those are all of the changes we need to make to the program! Now, let’s update our tests.
Start by making sure your imports and describe function look like this:
import * as anchor from "@coral-xyz/anchor"
import { Program } from "@coral-xyz/anchor"
import { expect } from "chai"
import { getAssociatedTokenAddress, getAccount } from "@solana/spl-token"
import { AnchorMovieReviewProgram } from "../target/types/anchor_movie_review_program"
describe("anchor-movie-review-program", () => {
// Configure the client to use the local cluster.
const provider = anchor.AnchorProvider.env()
anchor.setProvider(provider)
const program = anchor.workspace
.AnchorMovieReviewProgram as Program<AnchorMovieReviewProgram>
const movie = {
title: "Just a test movie",
description: "Wow what a good movie it was real great",
rating: 5,
}
const [movie_pda] = anchor.web3.PublicKey.findProgramAddressSync(
[Buffer.from(movie.title), provider.wallet.publicKey.toBuffer()],
program.programId
)
const [mint] = anchor.web3.PublicKey.findProgramAddressSync(
[Buffer.from("mint")],
program.programId
)
...
}
You can run npm install @solana/spl-token --save-dev if you don't have it
installed.
With that done, add a test for the initializeTokenMint instruction:
it("Initializes the reward token", async () => {
const tx = await program.methods.initializeTokenMint().rpc();
});
Notice that we didn't have to add .accounts because they call be inferred,
including the mint account (assuming you have seed inference enabled).
Next, update the test for the addMovieReview instruction. The primary
additions are:
- To get the associated token address that needs to be passed into the instruction as an account that cannot be inferred
- Check at the end of the test that the associated token account has 10 tokens
it("Movie review is added`", async () => {
const tokenAccount = await getAssociatedTokenAddress(
mint,
provider.wallet.publicKey,
);
const tx = await program.methods
.addMovieReview(movie.title, movie.description, movie.rating)
.accounts({
tokenAccount: tokenAccount,
})
.rpc();
const account = await program.account.movieAccountState.fetch(movie_pda);
expect(account.title).to.equal(movie.title);
expect(account.rating).to.equal(movie.rating);
expect(account.description).to.equal(movie.description);
expect(account.reviewer.toBase58()).to.equal(
provider.wallet.publicKey.toBase58(),
);
const userAta = await getAccount(provider.connection, tokenAccount);
expect(Number(userAta.amount)).to.equal((10 * 10) ^ 6);
});
After that, neither the test for updateMovieReview nor the test for
deleteMovieReview need any changes.
At this point, run anchor test and you should see the following output
anchor-movie-review-program
✔ Initializes the reward token (458ms)
✔ Movie review is added (410ms)
✔ Movie review is updated (402ms)
✔ Deletes a movie review (405ms)
5 passing (2s)
If you need more time with the concepts from this lesson or got stuck along the
way, feel free to take a look at the
solution code.
Note that the solution to this lab is on the solution-add-tokens branch.
Challenge
To apply what you've learned about CPIs in this lesson, think about how you could incorporate them into the Student Intro program. You could do something similar to what we did in the lab here and add some functionality to mint tokens to users when they introduce themselves.
Try to do this independently if you can! But if you get stuck, feel free to reference this solution code. Note that your code may look slightly different than the solution code depending on your implementation.