Go to file
Armani Ferrante 09ed7f670d
Allow procedural macro coupling
2021-01-30 03:49:22 -08:00
attribute Remove stale comment 2021-01-23 22:11:16 -08:00
cli Rust client generation 2021-01-30 01:26:28 -08:00
client Rust client generation 2021-01-30 01:26:28 -08:00
derive/accounts Set versions on path dependencies 2021-01-15 01:11:03 -08:00
docs examples: Add basic-4 2021-01-22 05:19:43 -08:00
examples cli: Deploy with upgradeable loader 2021-01-29 06:20:30 -08:00
spl Lockup and staking examples (#28) 2021-01-20 17:13:29 -08:00
src Allow procedural macro coupling 2021-01-30 03:49:22 -08:00
syn Dedup private account module re-exports 2021-01-30 02:17:48 -08:00
ts ts: Bump version 2021-01-29 06:38:19 -08:00
.gitignore Set alpha and borsh versions 2021-01-15 00:39:46 -08:00
.travis.yml travis: Upgrade to solana cli 1.5.5 2021-01-29 06:25:12 -08:00
Cargo.lock Rust client generation 2021-01-30 01:26:28 -08:00
Cargo.toml Rust client generation 2021-01-30 01:26:28 -08:00
LICENSE Tutorial 2 init 2021-01-04 23:57:51 -08:00
README.md Remove unused types 2021-01-23 19:32:54 -08:00

README.md

Anchor

Build Status Docs.rs Docs Chat License

Anchor is a framework for Solana's Sealevel runtime providing several convenient developer tools.

  • Rust eDSL for writing Solana programs
  • IDL 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, Truffle, web3.js or Parity's Ink!, then the experience will be familiar. Although the DSL syntax and semantics are targeted at Solana, the high level flow of writing RPC request handlers, emitting an IDL, and generating clients from IDL is the same.

Getting Started

For a quickstart guide and in depth tutorials, see the guided documentation. To jump straight to examples, go here. For the latest Rust API documentation, see docs.rs.

Packages

Package Version Description
@project-serum/anchor npm TypeScript client generator for Anchor programs
anchor-lang Crates.io Rust primitives for writing programs on Solana
anchor-spl crates CPI clients for SPL programs on Solana

Note

  • Anchor is in active development, so all APIs are subject to change.
  • This code is unaudited. Use at your own risk.

Examples

Build stateful programs on Solana by defining a state struct with associated methods. Here's a classic counter example, where only the designated authority can increment the count.

#[program]
mod counter {

    #[state]
    pub struct Counter {
      authority: Pubkey,
      count: u64,
    }

    pub fn new(ctx: Context<Auth>) -> Result<Self> {
        Ok(Self {
            auth: *ctx.accounts.authority.key
        })
    }

    pub fn increment(&mut self, ctx: Context<Auth>) -> Result<()> {
        if &self.authority != ctx.accounts.authority.key {
            return Err(ErrorCode::Unauthorized.into());
        }

        self.count += 1;

        Ok(())
    }
}

#[derive(Accounts)]
pub struct Auth<'info> {
    #[account(signer)]
    authority: AccountInfo<'info>,
}

#[error]
pub enum ErrorCode {
    #[msg("You are not authorized to perform this action.")]
    Unauthorized,
}

Additionally, one can utilize the full power of Solana's parallel execution model by keeping the program stateless and working with accounts directly. The above example can be rewritten as follows.

use anchor::prelude::*;

#[program]
mod counter {
    use super::*;

    pub fn initialize(ctx: Context<Initialize>, authority: Pubkey) -> Result<()> {
        let counter = &mut ctx.accounts.counter;

        counter.authority = authority;
        counter.count = 0;

        Ok(())
    }

    pub fn increment(ctx: Context<Increment>) -> Result<()> {
        let counter = &mut ctx.accounts.counter;

        counter += 1;

        Ok(())
    }
}

#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(init)]
    pub counter: ProgramAccount<'info, Counter>,
    pub rent: Sysvar<'info, Rent>,
}

#[derive(Accounts)]
pub struct Increment<'info> {
    #[account(mut, has_one = authority)]
    pub counter: ProgramAccount<'info, Counter>,
    #[account(signer)]
    pub authority: AccountInfo<'info>,
}

#[account]
pub struct Counter {
    pub authority: Pubkey,
    pub count: u64,
}

#[error]
pub enum ErrorCode {
    #[msg("You are not authorized to perform this action.")]
    Unauthorized,
}

Due to the fact that account sizes on Solana are fixed, some combination of the above is often required. For example, one can store store global state associated with the entire program in the #[state] struct and local state assocated with each user in individual #[account] structs.

For more, see the examples directory.

Accounts attribute syntax.

There are several inert attributes that can be specified on a struct deriving Accounts.

Attribute Location Description
#[account(signer)] On raw AccountInfo structs. Checks the given account signed the transaction.
#[account(mut)] On AccountInfo, ProgramAccount or CpiAccount structs. Marks the account as mutable and persists the state transition.
#[account(init)] On ProgramAccount structs. Marks the account as being initialized, skipping the account discriminator check.
#[account(belongs_to = <target>)] On ProgramAccount or CpiAccount structs Checks the target field on the account matches the target field in the struct deriving Accounts.
#[account(has_one = <target>)] On ProgramAccount or CpiAccount structs Semantically different, but otherwise the same as belongs_to.
#[account(seeds = [<seeds>])] On AccountInfo structs Seeds for the program derived address an AccountInfo struct represents.
#[account(owner = program | skip)] On AccountInfo structs Checks the owner of the account is the current program or skips the check.
#[account("<literal>")] On any type deriving Accounts Executes the given code literal as a constraint. The literal should evaluate to a boolean.
#[account(rent_exempt = <skip>)] On AccountInfo or ProgramAccount structs Optional attribute to skip the rent exemption check. By default, all accounts marked with #[account(init)] will be rent exempt, and so this should rarely (if ever) be used. Similarly, omitting = skip will mark the account rent exempt.

License

Anchor is licensed under Apache 2.0.