Anchor In Depth

Anchor is the dominant framework for writing Solana programs in Rust. It sits on the same Agave runtime as native programs (SBF bytecode, explicit account metas, compute units, CPI), but it generates the glue you would otherwise hand-write: instruction discriminators, entrypoint dispatch, declarative account checks, typed errors, events, and an IDL that clients consume.

This page is the umbrella for anchor-basics: what Anchor is, how the #[program] module and #[derive(Accounts)] structs form the instruction surface, how a workspace is laid out, how build/deploy and local testing fit together, and how Anchor compares to native programs.

Summary

• Anchor 0.32.1 turns Solana program development into a constrained, IDL-backed workflow: declare program ID and handlers in #[program], declare accounts and constraints in Accounts structs, then anchor build / anchor test / anchor deploy ship binary plus client schema.
• Insight: Most production bugs on Solana are account-validation and client-schema bugs, not clever business-logic bugs. Anchor fails closed on missing signers, wrong owners, and bad PDA seeds, and it keeps TypeScript (and other) clients honest via the IDL.
• Key Concepts: declare_id!, #[program], Context<T>, #[derive(Accounts)], constraints, #[account] state, IDL, Anchor.toml, SBF / .so, native vs Anchor.
• When to Use: Building application programs, admin surfaces, escrow and marketplace logic, SPL-adjacent apps, and anything that benefits from typed clients on @solana/kit 7.0.0 or Anchor's TS stack.
• Limitations/Trade-offs: Macro expansion adds binary size and some CU overhead; extreme hot paths may want Pinocchio or native; you still must design layouts, threats, and migrations yourself.
• Related Topics: Anchor basics examples, project structure, program module, accounts struct, workflow, build and deploy, Anchor vs native.

Foundations

What Anchor is

At the runtime level, a Solana program still implements roughly process_instruction(program_id, accounts, instruction_data). Anchor does not change that contract. It generates the entrypoint and unpacks instruction data into named handlers with typed args.

What you write is a workspace: Rust crates under programs/, TypeScript (or other) tests under tests/, and Anchor.toml for cluster, program IDs, and scripts. The framework crate is anchor-lang 0.32.1 (plus anchor-spl when you touch Token/Associated Token).

Anchor's product promise is three-fold:

1. Safety defaults - account validation runs before your handler body; missing constraints error instead of silently trusting client accounts.
2. Ergonomics - less boilerplate for discriminators, CPI helpers, and common account types (Signer, Account<T>, Program<T>).
3. Client contract - anchor build emits IDL JSON so off-chain code and CPI modules stay aligned with on-chain instructions.

The program module

use anchor_lang::prelude::*;
 
declare_id!("Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS");
 
#[program]
pub mod counter {
    use super::*;
 
    pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
        ctx.accounts.counter.count = 0;
        ctx.accounts.counter.authority = ctx.accounts.authority.key();
        Ok(())
    }
 
    pub fn increment(ctx: Context<Increment>) -> Result<()> {
        ctx.accounts.counter.count = ctx.accounts.counter.count.checked_add(1).unwrap();
        Ok(())
    }
}

• declare_id! hard-codes the program public key the binary expects; it must match deployment (use anchor keys sync after deploy keypair changes).
• #[program] marks the module whose public functions become instructions.
• Each handler takes Context<SomeAccounts> (and optional instruction args), returns Result<()>, and mutates only through validated account fields.

Instruction data is not free-form bytes you parse ad hoc: Anchor derives 8-byte discriminators and Borsh-serializes arguments. Clients that skip the IDL (or regenerate it late) break in confusing ways.

The Accounts struct

Every instruction names an accounts struct with #[derive(Accounts)]. Field types and attributes are the validation program.

#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(
        init,
        payer = authority,
        space = 8 + 8 + 32,
        seeds = [b"counter", authority.key().as_ref()],
        bump
    )]
    pub counter: Account<'info, Counter>,
    #[account(mut)]
    pub authority: Signer<'info>,
    pub system_program: Program<'info, System>,
}
 
#[account]
pub struct Counter {
    pub count: u64,
    pub authority: Pubkey,
}

Before initialize runs, Anchor checks signers, mutability, PDA seeds, system program id, and that init allocates and assigns ownership correctly. Account<'info, Counter> deserializes with the 8-byte account discriminator. Failures return Anchor errors instead of partial writes.

Project structure (minimal map)

workspace/
  Anchor.toml          # toolchain, programs.<cluster>, scripts
  Cargo.toml           # workspace members = ["programs/*"]
  programs/my_program/
    Cargo.toml         # anchor-lang = "0.32.1"
    src/lib.rs
  tests/*.ts
  target/deploy/*.so   # after build
  target/idl/*.json    # after build

Anchor.toml pins which program id maps to which cluster name. Root Cargo.toml is a Rust workspace; each program is its own crate. Tests typically call the program through a provider (local validator / Surfpool) using the generated IDL.

Build, deploy, and workflow in one sentence

anchor build compiles SBF and regenerates the IDL; anchor test deploys locally and runs tests; anchor deploy pushes the .so to a cluster; clients and CPI consumers must track the new IDL and program id.

Anchor vs native (orientation)

Native programs use entrypoint!, manual account walking, and hand-maintained client codecs. Anchor generates that surface. You pay some size/CU and gain constraints plus IDL. Hot settlement cores sometimes leave Anchor; most product programs should not start native "for purity."

Mechanics & Interactions

How the pieces interact end to end:

  Edit lib.rs (#[program] + Accounts + #[account] state)
           |
           v
  anchor build  -->  target/deploy/*.so + target/idl/*.json
           |
           v
  anchor test   -->  local validator/Surfpool + TS tests
           |
           v
  anchor deploy -->  upgradeable program on cluster
           |
           v
  keys sync / IDL publish  -->  clients & declare_program! consumers

Dispatch path on-chain

1. Transaction lists program id, accounts, and instruction data.
2. Runtime loads the program .so and invokes the generated entrypoint.
3. Anchor matches the 8-byte instruction discriminator to a handler.
4. Anchor deserializes args and builds Context<T> by validating the Accounts struct.
5. Your handler runs business logic and returns Ok(()) or an error.
6. On success, account data writes and lamport changes commit with the transaction; on error, the whole transaction fails.

Context is the handoff

Context<T> holds accounts: T, program_id, bumps (for PDA bumps discovered during validation), and remaining accounts when you use them. Handlers should not re-parse AccountInfo lists from scratch; they should trust (and only extend with require!) what constraints already enforced.

Constraints are the security boundary

Common attributes:

Order matters for init and CPI safety; treat validation order as part of design, not an accident of attribute listing. Custom business rules belong in constraints or early require!, not "we will check later if we remember."

Workspace config interactions

• Program id drift: binary declare_id!, Anchor.toml [programs.*], and on-chain deploy keypair must agree. After deploy, anchor keys sync rewrites sources/config when the keypair is the source of truth.
• IDL drift: public API changes (new ix, renamed fields, account layout) require rebuild and client regen. Shipping only a new .so without IDL is how dapps call wrong discriminators.
• Cluster isolation: localnet, devnet, and mainnet-beta are separate account universes; never reuse a devnet program id assumption on mainnet clients.

Client side

Tests and apps build instructions from the IDL. @solana/kit 7.0.0 does not require Anchor specifically, but it needs correct wire formats. Anchor's strength is producing that contract from the same macros that generate the program. Prefer regenerating typed clients in CI when IDL changes.

Advanced Considerations & Applications

Designing instructions as an API surface

Think of each #[program] function as a versioned public method. Stable discriminators and stable account orders matter more than clever Rust modules. Prefer additive instructions and versioned account layouts over silent field reorder.

When you change account space, plan realloc or migration instructions; clients holding old layouts will fail discriminator or deserialize checks for good reason.

Fail-closed defaults vs residual risk

Anchor removes entire classes of mistakes (unsigned authority, wrong program owner on Account<T>, wrong system program address). It does not invent your threat model:

• Who may call this instruction?
• Which accounts are still UncheckedAccount and why?
• Are token accounts the expected mint/authority?
• Is init_if_needed creating re-init attack surface?
• Do CPI targets and remaining accounts bounds hold under adversarial metas?

Security review still focuses on constraints, seeds, and CPI graphs - not only handler math.

Multi-program workspaces and CPI

A workspace can hold multiple crates under programs/. Cross-program calls need correct account metas and, in Anchor 0.32, often declare_program! or shared types for the callee. Framework boundaries still compose via CPI: an Anchor program can call native/Pinocchio if bytes and seeds match.

Release discipline that matches the framework

1. Pin Anchor CLI / anchor-lang 0.32.1, Rust 1.91.1, Solana CLI 3.0.10 in docs and CI.
2. anchor build and commit or publish IDL artifacts intentionally (policy varies; do not leave them accidental).
3. anchor test green on local stack before devnet.
4. Devnet deploy + integration tests against real RPC.
5. Mainnet only with verifiable builds, upgrade authority hygiene, and a rollback story.

When to stay on Anchor vs leave

Profile with fixed transactions and unitsConsumed; do not rewrite frameworks on vibes.

Common Misconceptions

• "Anchor is a different runtime or a separate chain." It compiles to ordinary SBF programs on Agave; validators do not special-case Anchor.
• "Constraints mean I can skip security design." Constraints enforce what you declare. Undeclared trust assumptions remain exploitable.
• "declare_id! is decorative." Mismatch with the deployed program causes runtime failures (DeclaredProgramIdMismatch). Sync after key changes.
• "Handlers run before account checks." Validation of the Accounts struct runs first; the handler assumes a valid Context.
• "IDL is optional documentation." For Anchor programs, the IDL is the client contract. Treat it as a release artifact.
• "Native is always faster, so always start native." Often false for team velocity and safety. Measure; default to Anchor for application programs.
• "anchor deploy alone updates all clients." Deploy updates on-chain bytecode; apps, indexers, and CPI modules need the matching IDL and program id.
• "Any AccountInfo in remaining accounts is safe if the main struct is strict." Remaining accounts are a common bypass surface; bound and validate them explicitly.

FAQs

Related

• Anchor Basics - scaffold, handlers, IDL, and first tests
• Project Structure - workspace layout, Anchor.toml, and crates
• The Accounts Struct - derive(Accounts), types, and constraints
• The Anchor Workflow - local build, test, promote to devnet/mainnet
• Building & Deploying - anchor build, deploy, keys sync, IDL
• Anchor vs Native - what macros generate and when native wins

Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1, and @solana/kit 7.0.0.