2021-01-14 22:35:50 -08:00
|
|
|
//! Anchor ⚓ is a framework for Solana's Sealevel runtime providing several
|
|
|
|
//! convenient developer tools.
|
|
|
|
//!
|
|
|
|
//! - Rust eDSL for writing safe, secure, and high level Solana programs
|
|
|
|
//! - [IDL](https://en.wikipedia.org/wiki/Interface_description_language) specification
|
|
|
|
//! - TypeScript package for generating clients from IDL
|
|
|
|
//! - CLI and workspace management for developing complete applications
|
|
|
|
//!
|
|
|
|
//! If you're familiar with developing in Ethereum's
|
|
|
|
//! [Solidity](https://docs.soliditylang.org/en/v0.7.4/),
|
|
|
|
//! [Truffle](https://www.trufflesuite.com/),
|
|
|
|
//! [web3.js](https://github.com/ethereum/web3.js) or Parity's
|
|
|
|
//! [Ink!](https://github.com/paritytech/ink), then the experience will be
|
|
|
|
//! familiar. Although the syntax and semantics are targeted at Solana, the high
|
|
|
|
//! level workflow of writing RPC request handlers, emitting an IDL, and
|
|
|
|
//! generating clients from IDL is the same.
|
|
|
|
//!
|
|
|
|
//! For detailed tutorials and examples on how to use Anchor, see the guided
|
|
|
|
//! [tutorials](https://project-serum.github.io/anchor) or examples in the GitHub
|
|
|
|
//! [repository](https://github.com/project-serum/anchor).
|
|
|
|
//!
|
|
|
|
//! Presented here are the Rust primitives for building on Solana.
|
|
|
|
|
2021-01-30 03:49:22 -08:00
|
|
|
extern crate self as anchor_lang;
|
|
|
|
|
2021-04-17 12:07:48 -07:00
|
|
|
use bytemuck::{Pod, Zeroable};
|
2021-01-15 20:10:24 -08:00
|
|
|
use solana_program::account_info::AccountInfo;
|
2021-06-09 15:40:43 -07:00
|
|
|
use solana_program::entrypoint::ProgramResult;
|
2021-01-15 20:10:24 -08:00
|
|
|
use solana_program::instruction::AccountMeta;
|
|
|
|
use solana_program::program_error::ProgramError;
|
|
|
|
use solana_program::pubkey::Pubkey;
|
2021-01-09 22:03:14 -08:00
|
|
|
use std::io::Write;
|
2020-12-31 15:48:06 -08:00
|
|
|
|
2021-01-14 22:35:50 -08:00
|
|
|
mod account_info;
|
2021-06-18 15:50:58 -07:00
|
|
|
mod account_meta;
|
2021-01-20 17:13:02 -08:00
|
|
|
mod boxed;
|
2021-06-09 15:40:43 -07:00
|
|
|
mod common;
|
2021-01-14 22:35:50 -08:00
|
|
|
mod context;
|
|
|
|
mod cpi_account;
|
2021-04-11 17:23:43 -07:00
|
|
|
mod cpi_state;
|
2021-01-22 03:35:57 -08:00
|
|
|
mod ctor;
|
2021-01-15 23:05:26 -08:00
|
|
|
mod error;
|
2021-04-10 17:47:14 -07:00
|
|
|
#[doc(hidden)]
|
2021-01-29 06:19:00 -08:00
|
|
|
pub mod idl;
|
2021-04-17 12:07:48 -07:00
|
|
|
mod loader;
|
2021-01-14 22:35:50 -08:00
|
|
|
mod program_account;
|
2021-06-18 15:50:58 -07:00
|
|
|
pub mod state;
|
2021-01-14 22:35:50 -08:00
|
|
|
mod sysvar;
|
2021-02-07 07:45:10 -08:00
|
|
|
mod vec;
|
2021-01-14 22:35:50 -08:00
|
|
|
|
2021-04-11 22:37:58 -07:00
|
|
|
pub use crate::context::{Context, CpiContext, CpiStateContext};
|
2021-01-14 22:35:50 -08:00
|
|
|
pub use crate::cpi_account::CpiAccount;
|
2021-04-11 17:23:43 -07:00
|
|
|
pub use crate::cpi_state::CpiState;
|
2021-04-17 12:07:48 -07:00
|
|
|
pub use crate::loader::Loader;
|
2021-01-14 22:35:50 -08:00
|
|
|
pub use crate::program_account::ProgramAccount;
|
2021-01-23 19:31:44 -08:00
|
|
|
pub use crate::state::ProgramState;
|
2021-01-14 22:35:50 -08:00
|
|
|
pub use crate::sysvar::Sysvar;
|
2021-01-09 22:03:14 -08:00
|
|
|
pub use anchor_attribute_access_control::access_control;
|
2021-08-15 16:35:53 -07:00
|
|
|
pub use anchor_attribute_account::{account, zero_copy};
|
2021-01-15 23:05:26 -08:00
|
|
|
pub use anchor_attribute_error::error;
|
2021-04-10 17:47:14 -07:00
|
|
|
pub use anchor_attribute_event::{emit, event};
|
2021-02-07 07:45:10 -08:00
|
|
|
pub use anchor_attribute_interface::interface;
|
2021-01-09 22:03:14 -08:00
|
|
|
pub use anchor_attribute_program::program;
|
2021-01-22 03:35:57 -08:00
|
|
|
pub use anchor_attribute_state::state;
|
2021-01-09 22:03:14 -08:00
|
|
|
pub use anchor_derive_accounts::Accounts;
|
2021-02-07 22:22:50 -08:00
|
|
|
/// Borsh is the default serialization format for instructions and accounts.
|
2020-12-31 15:48:06 -08:00
|
|
|
pub use borsh::{BorshDeserialize as AnchorDeserialize, BorshSerialize as AnchorSerialize};
|
2021-01-15 20:10:24 -08:00
|
|
|
pub use solana_program;
|
2020-12-31 15:48:06 -08:00
|
|
|
|
2021-02-04 06:01:48 -08:00
|
|
|
/// A data structure of validated accounts that can be deserialized from the
|
|
|
|
/// input to a Solana program. Implementations of this trait should perform any
|
|
|
|
/// and all requisite constraint checks on accounts to ensure the accounts
|
|
|
|
/// maintain any invariants required for the program to run securely. In most
|
|
|
|
/// cases, it's recommended to use the [`Accounts`](./derive.Accounts.html)
|
|
|
|
/// derive macro to implement this trait.
|
2021-01-14 15:16:27 -08:00
|
|
|
pub trait Accounts<'info>: ToAccountMetas + ToAccountInfos<'info> + Sized {
|
2021-02-04 06:01:48 -08:00
|
|
|
/// Returns the validated accounts struct. What constitutes "valid" is
|
|
|
|
/// program dependent. However, users of these types should never have to
|
|
|
|
/// worry about account substitution attacks. For example, if a program
|
|
|
|
/// expects a `Mint` account from the SPL token program in a particular
|
2021-02-07 07:45:10 -08:00
|
|
|
/// field, then it should be impossible for this method to return `Ok` if
|
|
|
|
/// any other account type is given--from the SPL token program or elsewhere.
|
2021-02-04 06:01:48 -08:00
|
|
|
///
|
|
|
|
/// `program_id` is the currently executing program. `accounts` is the
|
|
|
|
/// set of accounts to construct the type from. For every account used,
|
|
|
|
/// the implementation should mutate the slice, consuming the used entry
|
|
|
|
/// so that it cannot be used again.
|
2021-01-14 15:16:27 -08:00
|
|
|
fn try_accounts(
|
|
|
|
program_id: &Pubkey,
|
2021-01-14 22:35:50 -08:00
|
|
|
accounts: &mut &[AccountInfo<'info>],
|
2021-06-15 17:15:51 -07:00
|
|
|
ix_data: &[u8],
|
2021-01-14 22:35:50 -08:00
|
|
|
) -> Result<Self, ProgramError>;
|
|
|
|
}
|
|
|
|
|
2021-04-29 10:24:43 -07:00
|
|
|
/// The exit procedure for an account. Any cleanup or persistence to storage
|
2021-02-04 06:01:48 -08:00
|
|
|
/// should be done here.
|
2021-01-20 17:13:02 -08:00
|
|
|
pub trait AccountsExit<'info>: ToAccountMetas + ToAccountInfos<'info> {
|
2021-02-04 06:01:48 -08:00
|
|
|
/// `program_id` is the currently executing program.
|
2021-06-09 15:40:43 -07:00
|
|
|
fn exit(&self, program_id: &Pubkey) -> ProgramResult;
|
|
|
|
}
|
|
|
|
|
|
|
|
/// The close procedure to initiate garabage collection of an account, allowing
|
|
|
|
/// one to retrieve the rent exemption.
|
|
|
|
pub trait AccountsClose<'info>: ToAccountInfos<'info> {
|
|
|
|
fn close(&self, sol_destination: AccountInfo<'info>) -> ProgramResult;
|
2021-01-20 17:13:02 -08:00
|
|
|
}
|
|
|
|
|
2021-02-04 06:01:48 -08:00
|
|
|
/// Transformation to
|
|
|
|
/// [`AccountMeta`](../solana_program/instruction/struct.AccountMeta.html)
|
|
|
|
/// structs.
|
2021-01-14 15:16:27 -08:00
|
|
|
pub trait ToAccountMetas {
|
2021-01-20 17:13:02 -08:00
|
|
|
/// `is_signer` is given as an optional override for the signer meta field.
|
|
|
|
/// This covers the edge case when a program-derived-address needs to relay
|
|
|
|
/// a transaction from a client to another program but sign the transaction
|
|
|
|
/// before the relay. The client cannot mark the field as a signer, and so
|
|
|
|
/// we have to override the is_signer meta field given by the client.
|
|
|
|
fn to_account_metas(&self, is_signer: Option<bool>) -> Vec<AccountMeta>;
|
2021-01-14 15:16:27 -08:00
|
|
|
}
|
|
|
|
|
2021-02-04 06:01:48 -08:00
|
|
|
/// Transformation to
|
|
|
|
/// [`AccountInfo`](../solana_program/account_info/struct.AccountInfo.html)
|
|
|
|
/// structs.
|
2021-01-14 15:16:27 -08:00
|
|
|
pub trait ToAccountInfos<'info> {
|
|
|
|
fn to_account_infos(&self) -> Vec<AccountInfo<'info>>;
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Transformation to an `AccountInfo` struct.
|
|
|
|
pub trait ToAccountInfo<'info> {
|
|
|
|
fn to_account_info(&self) -> AccountInfo<'info>;
|
2021-01-09 22:03:14 -08:00
|
|
|
}
|
|
|
|
|
2021-02-04 06:01:48 -08:00
|
|
|
/// A data structure that can be serialized and stored into account storage,
|
|
|
|
/// i.e. an
|
|
|
|
/// [`AccountInfo`](../solana_program/account_info/struct.AccountInfo.html#structfield.data)'s
|
|
|
|
/// mutable data slice.
|
2021-01-09 22:03:14 -08:00
|
|
|
///
|
2021-02-04 06:01:48 -08:00
|
|
|
/// Implementors of this trait should ensure that any subsequent usage of the
|
2021-01-09 22:03:14 -08:00
|
|
|
/// `AccountDeserialize` trait succeeds if and only if the account is of the
|
2021-02-04 06:01:48 -08:00
|
|
|
/// correct type.
|
|
|
|
///
|
|
|
|
/// In most cases, one can use the default implementation provided by the
|
|
|
|
/// [`#[account]`](./attr.account.html) attribute.
|
2021-01-09 22:03:14 -08:00
|
|
|
pub trait AccountSerialize {
|
2021-02-04 06:01:48 -08:00
|
|
|
/// Serializes the account data into `writer`.
|
2021-01-09 22:03:14 -08:00
|
|
|
fn try_serialize<W: Write>(&self, writer: &mut W) -> Result<(), ProgramError>;
|
|
|
|
}
|
|
|
|
|
2021-02-04 06:01:48 -08:00
|
|
|
/// A data structure that can be deserialized and stored into account storage,
|
|
|
|
/// i.e. an
|
|
|
|
/// [`AccountInfo`](../solana_program/account_info/struct.AccountInfo.html#structfield.data)'s
|
|
|
|
/// mutable data slice.
|
2021-01-09 22:03:14 -08:00
|
|
|
pub trait AccountDeserialize: Sized {
|
2021-02-04 06:01:48 -08:00
|
|
|
/// Deserializes previously initialized account data. Should fail for all
|
|
|
|
/// uninitialized accounts, where the bytes are zeroed. Implementations
|
|
|
|
/// should be unique to a particular account type so that one can never
|
|
|
|
/// successfully deserialize the data of one account type into another.
|
|
|
|
/// For example, if the SPL token program where to implement this trait,
|
|
|
|
/// it should impossible to deserialize a `Mint` account into a token
|
|
|
|
/// `Account`.
|
2021-01-09 22:03:14 -08:00
|
|
|
fn try_deserialize(buf: &mut &[u8]) -> Result<Self, ProgramError>;
|
|
|
|
|
|
|
|
/// Deserializes account data without checking the account discriminator.
|
2021-02-04 06:01:48 -08:00
|
|
|
/// This should only be used on account initialization, when the bytes of
|
|
|
|
/// the account are zeroed.
|
2021-01-09 22:03:14 -08:00
|
|
|
fn try_deserialize_unchecked(buf: &mut &[u8]) -> Result<Self, ProgramError>;
|
|
|
|
}
|
|
|
|
|
2021-04-17 12:07:48 -07:00
|
|
|
/// An account data structure capable of zero copy deserialization.
|
|
|
|
pub trait ZeroCopy: Discriminator + Copy + Clone + Zeroable + Pod {}
|
|
|
|
|
2021-02-06 00:28:33 -08:00
|
|
|
/// Calculates the data for an instruction invocation, where the data is
|
|
|
|
/// `Sha256(<namespace>::<method_name>)[..8] || BorshSerialize(args)`.
|
|
|
|
/// `args` is a borsh serialized struct of named fields for each argument given
|
|
|
|
/// to an instruction.
|
|
|
|
pub trait InstructionData: AnchorSerialize {
|
|
|
|
fn data(&self) -> Vec<u8>;
|
|
|
|
}
|
|
|
|
|
2021-04-10 17:47:14 -07:00
|
|
|
/// An event that can be emitted via a Solana log.
|
|
|
|
pub trait Event: AnchorSerialize + AnchorDeserialize + Discriminator {
|
|
|
|
fn data(&self) -> Vec<u8>;
|
|
|
|
}
|
|
|
|
|
|
|
|
// The serialized event data to be emitted via a Solana log.
|
|
|
|
// TODO: remove this on the next major version upgrade.
|
|
|
|
#[doc(hidden)]
|
|
|
|
#[deprecated(since = "0.4.2", note = "Please use Event instead")]
|
2021-03-24 20:19:29 -07:00
|
|
|
pub trait EventData: AnchorSerialize + Discriminator {
|
|
|
|
fn data(&self) -> Vec<u8>;
|
|
|
|
}
|
|
|
|
|
2021-04-10 17:47:14 -07:00
|
|
|
/// 8 byte unique identifier for a type.
|
2021-03-24 20:19:29 -07:00
|
|
|
pub trait Discriminator {
|
|
|
|
fn discriminator() -> [u8; 8];
|
|
|
|
}
|
|
|
|
|
2021-04-13 11:47:54 -07:00
|
|
|
/// Bump seed for program derived addresses.
|
|
|
|
pub trait Bump {
|
|
|
|
fn seed(&self) -> u8;
|
|
|
|
}
|
|
|
|
|
2021-06-27 13:17:05 -07:00
|
|
|
pub trait Key {
|
|
|
|
fn key(&self) -> Pubkey;
|
|
|
|
}
|
|
|
|
|
|
|
|
impl Key for Pubkey {
|
|
|
|
fn key(&self) -> Pubkey {
|
|
|
|
*self
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2021-01-14 22:35:50 -08:00
|
|
|
/// The prelude contains all commonly used components of the crate.
|
|
|
|
/// All programs should include it via `anchor_lang::prelude::*;`.
|
2020-12-31 15:48:06 -08:00
|
|
|
pub mod prelude {
|
|
|
|
pub use super::{
|
2021-08-15 16:35:53 -07:00
|
|
|
access_control, account, emit, error, event, interface, program, require, state, zero_copy,
|
2021-08-29 14:25:38 -07:00
|
|
|
AccountDeserialize, AccountSerialize, Accounts, AccountsExit, AnchorDeserialize,
|
|
|
|
AnchorSerialize, Context, CpiAccount, CpiContext, CpiState, CpiStateContext, Key, Loader,
|
|
|
|
ProgramAccount, ProgramState, Sysvar, ToAccountInfo, ToAccountInfos, ToAccountMetas,
|
2020-12-31 15:48:06 -08:00
|
|
|
};
|
|
|
|
|
2021-01-15 19:58:01 -08:00
|
|
|
pub use borsh;
|
2021-01-15 20:10:24 -08:00
|
|
|
pub use solana_program::account_info::{next_account_info, AccountInfo};
|
|
|
|
pub use solana_program::entrypoint::ProgramResult;
|
|
|
|
pub use solana_program::instruction::AccountMeta;
|
2021-01-01 23:01:31 -08:00
|
|
|
pub use solana_program::msg;
|
2021-01-15 20:10:24 -08:00
|
|
|
pub use solana_program::program_error::ProgramError;
|
|
|
|
pub use solana_program::pubkey::Pubkey;
|
|
|
|
pub use solana_program::sysvar::clock::Clock;
|
|
|
|
pub use solana_program::sysvar::epoch_schedule::EpochSchedule;
|
|
|
|
pub use solana_program::sysvar::fees::Fees;
|
|
|
|
pub use solana_program::sysvar::instructions::Instructions;
|
|
|
|
pub use solana_program::sysvar::recent_blockhashes::RecentBlockhashes;
|
|
|
|
pub use solana_program::sysvar::rent::Rent;
|
|
|
|
pub use solana_program::sysvar::rewards::Rewards;
|
|
|
|
pub use solana_program::sysvar::slot_hashes::SlotHashes;
|
|
|
|
pub use solana_program::sysvar::slot_history::SlotHistory;
|
|
|
|
pub use solana_program::sysvar::stake_history::StakeHistory;
|
|
|
|
pub use solana_program::sysvar::Sysvar as SolanaSysvar;
|
2021-01-15 23:05:26 -08:00
|
|
|
pub use thiserror;
|
2020-12-31 15:48:06 -08:00
|
|
|
}
|
2021-04-17 12:07:48 -07:00
|
|
|
|
2021-05-06 14:48:22 -07:00
|
|
|
// Internal module used by macros and unstable apis.
|
2021-04-17 12:07:48 -07:00
|
|
|
#[doc(hidden)]
|
|
|
|
pub mod __private {
|
2021-04-18 09:54:18 -07:00
|
|
|
use solana_program::program_error::ProgramError;
|
2021-04-17 12:07:48 -07:00
|
|
|
use solana_program::pubkey::Pubkey;
|
|
|
|
|
|
|
|
pub use crate::ctor::Ctor;
|
2021-06-09 13:02:50 -07:00
|
|
|
pub use crate::error::{Error, ErrorCode};
|
2021-04-17 12:07:48 -07:00
|
|
|
pub use anchor_attribute_account::ZeroCopyAccessor;
|
|
|
|
pub use anchor_attribute_event::EventIndex;
|
|
|
|
pub use base64;
|
|
|
|
pub use bytemuck;
|
|
|
|
|
2021-05-06 14:48:22 -07:00
|
|
|
pub mod state {
|
|
|
|
pub use crate::state::*;
|
|
|
|
}
|
|
|
|
|
2021-06-09 13:02:50 -07:00
|
|
|
// The starting point for user defined error codes.
|
|
|
|
pub const ERROR_CODE_OFFSET: u32 = 300;
|
|
|
|
|
2021-04-18 09:54:18 -07:00
|
|
|
// Calculates the size of an account, which may be larger than the deserialized
|
|
|
|
// data in it. This trait is currently only used for `#[state]` accounts.
|
|
|
|
#[doc(hidden)]
|
|
|
|
pub trait AccountSize {
|
|
|
|
fn size(&self) -> Result<u64, ProgramError>;
|
|
|
|
}
|
|
|
|
|
2021-04-17 12:07:48 -07:00
|
|
|
// Very experimental trait.
|
|
|
|
pub trait ZeroCopyAccessor<Ty> {
|
|
|
|
fn get(&self) -> Ty;
|
|
|
|
fn set(input: &Ty) -> Self;
|
|
|
|
}
|
|
|
|
|
|
|
|
impl ZeroCopyAccessor<Pubkey> for [u8; 32] {
|
|
|
|
fn get(&self) -> Pubkey {
|
|
|
|
Pubkey::new(self)
|
|
|
|
}
|
|
|
|
fn set(input: &Pubkey) -> [u8; 32] {
|
|
|
|
input.to_bytes()
|
|
|
|
}
|
|
|
|
}
|
2021-04-18 09:54:18 -07:00
|
|
|
|
|
|
|
pub use crate::state::PROGRAM_STATE_SEED;
|
2021-06-09 15:40:43 -07:00
|
|
|
pub const CLOSED_ACCOUNT_DISCRIMINATOR: [u8; 8] = [255, 255, 255, 255, 255, 255, 255, 255];
|
2021-04-17 12:07:48 -07:00
|
|
|
}
|
2021-06-27 13:17:05 -07:00
|
|
|
|
2021-07-09 18:42:05 -07:00
|
|
|
/// Ensures a condition is true, otherwise returns the given error.
|
|
|
|
/// Use this with a custom error type.
|
|
|
|
///
|
|
|
|
/// # Example
|
|
|
|
///
|
|
|
|
/// After defining an `ErrorCode`
|
|
|
|
///
|
|
|
|
/// ```ignore
|
|
|
|
/// #[error]
|
|
|
|
/// pub struct ErrorCode {
|
|
|
|
/// InvalidArgument,
|
|
|
|
/// }
|
|
|
|
/// ```
|
|
|
|
///
|
|
|
|
/// One can write a `require` assertion as
|
|
|
|
///
|
|
|
|
/// ```ignore
|
|
|
|
/// require!(condition, InvalidArgument);
|
|
|
|
/// ```
|
|
|
|
///
|
|
|
|
/// which would exit the program with the `InvalidArgument` error code if
|
|
|
|
/// `condition` is false.
|
|
|
|
#[macro_export]
|
|
|
|
macro_rules! require {
|
|
|
|
($invariant:expr, $error:tt $(,)?) => {
|
|
|
|
if !($invariant) {
|
|
|
|
return Err(crate::ErrorCode::$error.into());
|
|
|
|
}
|
|
|
|
};
|
2021-07-18 11:39:56 -07:00
|
|
|
($invariant:expr, $error:expr $(,)?) => {
|
|
|
|
if !($invariant) {
|
|
|
|
return Err($error.into());
|
|
|
|
}
|
|
|
|
};
|
2021-07-09 18:42:05 -07:00
|
|
|
}
|