1---
2title: Programs with Anchor
3description: Write Solana programs using the Anchor framework for fast iteration, automatic account validation, and built-in TypeScript client generation.
4---
5 
6# Programs with Anchor (default choice)
7 
8## When to use Anchor
9Use Anchor by default when:
10- You want fast iteration with reduced boilerplate
11- You want an IDL and TypeScript client story out of the box
12- You want mature testing and workspace tooling
13- You need built-in security through automatic account validation
14 
15## Core Advantages
16- **Reduced Boilerplate**: Abstracts repetitive account management, instruction serialization, and error handling
17- **Built-in Security**: Automatic account-ownership verification and data validation
18- **IDL Generation**: Automatic interface definition for client generation
19 
20## Core Macros
21 
22### `declare_id!()`
23Declares the onchain address where the program resides—a unique public key derived from the project's keypair.
24 
25### `#[program]`
26Marks the module containing every instruction entrypoint and business-logic function.
27 
28### `#[derive(Accounts)]`
29Lists accounts an instruction requires and automatically enforces their constraints:
30- Declares all necessary accounts for specific instructions
31- Enforces constraint checks automatically to block bugs and exploits
32- Generates helper methods for safe account access and mutation
33 
34### `#[error_code]`
35Enables custom, human-readable error types with `#[msg(...)]` attributes for clearer debugging.
36 
37## Account Types
38 
39| Type | Purpose |
40|------|---------|
41| `Signer<'info>` | Verifies the account signed the transaction |
42| `SystemAccount<'info>` | Confirms System Program ownership |
43| `Program<'info, T>` | Validates executable program accounts |
44| `Account<'info, T>` | Typed program account with automatic validation |
45| `UncheckedAccount<'info>` | Raw account requiring manual validation |
46 
47## Account Constraints
48 
49### Initialization
50```rust
51#[account(
52    init,
53    payer = payer,
54    space = 8 + CustomAccount::INIT_SPACE
55)]
56pub account: Account<'info, CustomAccount>,
57```
58 
59### PDA Validation
60```rust
61#[account(
62    seeds = [b"vault", owner.key().as_ref()],
63    bump
64)]
65pub vault: SystemAccount<'info>,
66```
67 
68### Ownership and Relationships
69```rust
70#[account(
71    has_one = authority @ CustomError::InvalidAuthority,
72    constraint = account.is_active @ CustomError::AccountInactive
73)]
74pub account: Account<'info, CustomAccount>,
75```
76 
77### Reallocation
78```rust
79#[account(
80    mut,
81    realloc = new_space,
82    realloc::payer = payer,
83    realloc::zero = true  // Clear old data when shrinking
84)]
85pub account: Account<'info, CustomAccount>,
86```
87 
88### Closing Accounts
89```rust
90#[account(
91    mut,
92    close = destination
93)]
94pub account: Account<'info, CustomAccount>,
95```
96 
97## Account Discriminators
98 
99Default discriminators use `sha256("account:<StructName>")[0..8]`. Custom discriminators (Anchor 0.31+):
100 
101```rust
102#[account(discriminator = 1)]
103pub struct Escrow { ... }
104```
105 
106**Constraints:**
107- Discriminators must be unique across your program
108- Using `[1]` prevents using `[1, 2, ...]` which also start with `1`
109- `[0]` conflicts with uninitialized accounts
110 
111## Instruction Patterns
112 
113### Basic Structure
114```rust
115#[program]
116pub mod my_program {
117    use super::*;
118 
119    pub fn initialize(ctx: Context<Initialize>, data: u64) -> Result<()> {
120        ctx.accounts.account.data = data;
121        Ok(())
122    }
123}
124```
125 
126### Context Implementation Pattern
127Move logic to context struct implementations for organization and testability:
128 
129```rust
130impl<'info> Transfer<'info> {
131    pub fn transfer_tokens(&mut self, amount: u64) -> Result<()> {
132        // Implementation
133        Ok(())
134    }
135}
136```
137 
138## Cross-Program Invocations (CPIs)
139 
140### Basic CPI
141```rust
142let cpi_accounts = Transfer {
143    from: ctx.accounts.from.to_account_info(),
144    to: ctx.accounts.to.to_account_info(),
145};
146let cpi_ctx = CpiContext::new(System::id(), cpi_accounts);
147 
148transfer(cpi_ctx, amount)?;
149```
150 
151### PDA-Signed CPIs
152```rust
153let seeds = &[b"vault".as_ref(), &[ctx.bumps.vault]];
154let signer = &[&seeds[..]];
155let cpi_ctx = CpiContext::new_with_signer(System::id(), cpi_accounts, signer);
156```
157 
158## Error Handling
159 
160```rust
161#[error_code]
162pub enum MyError {
163    #[msg("Custom error message")]
164    CustomError,
165    #[msg("Value too large: {0}")]
166    ValueError(u64),
167}
168 
169// Usage
170require!(value > 0, MyError::CustomError);
171require!(value < 100, MyError::ValueError(value));
172```
173 
174## Token Accounts
175 
176### SPL Token
177```rust
178#[account(
179    mint::decimals = 9,
180    mint::authority = authority,
181)]
182pub mint: Account<'info, Mint>,
183 
184#[account(
185    mut,
186    associated_token::mint = mint,
187    associated_token::authority = owner,
188)]
189pub token_account: Account<'info, TokenAccount>,
190```
191 
192### Token2022 Compatibility
193Use `InterfaceAccount` for dual compatibility:
194 
195```rust
196use anchor_spl::token_interface::{Mint, TokenAccount};
197 
198pub mint: InterfaceAccount<'info, Mint>,
199pub token_account: InterfaceAccount<'info, TokenAccount>,
200pub token_program: Interface<'info, TokenInterface>,
201```
202 
203## LazyAccount (Anchor 0.31+)
204 
205Heap-allocated, read-only account access for efficient memory usage:
206 
207```rust
208// Cargo.toml
209anchor-lang = { version = "0.31.1", features = ["lazy-account"] }
210 
211// Usage
212pub account: LazyAccount<'info, CustomAccountType>,
213 
214pub fn handler(ctx: Context<MyInstruction>) -> Result<()> {
215    let value = ctx.accounts.account.get_value()?;
216    Ok(())
217}
218```
219 
220**Note:** LazyAccount is read-only. After CPIs, use `unload()` to refresh cached values.
221 
222## Zero-Copy Accounts
223 
224For accounts exceeding stack/heap limits:
225 
226```rust
227#[account(zero_copy)]
228pub struct LargeAccount {
229    pub data: [u8; 10000],
230}
231```
232 
233Accounts under 10,240 bytes use `init`; larger accounts require external creation then `zero` constraint initialization.
234 
235## Remaining Accounts
236 
237Pass dynamic accounts beyond fixed instruction structure:
238 
239```rust
240pub fn batch_operation(ctx: Context<BatchOp>, amounts: Vec<u64>) -> Result<()> {
241    let remaining = &ctx.remaining_accounts;
242    require!(remaining.len() % 2 == 0, BatchError::InvalidSchema);
243 
244    for (i, chunk) in remaining.chunks(2).enumerate() {
245        process_pair(&chunk[0], &chunk[1], amounts[i])?;
246    }
247    Ok(())
248}
249```
250 
251## Version Management
252 
253- Use AVM (Anchor Version Manager) for reproducible builds
254- Keep Solana CLI + Anchor versions aligned in CI and developer setup
255- Pin versions in `Anchor.toml`
256 
257## Compatibility Notes for Anchor 0.32.0
258 
259To resolve build conflicts with certain crates in Anchor 0.32.0, run these cargo update commands in your project root:
260 
261```bash
262cargo update base64ct --precise 1.6.0
263cargo update constant_time_eq --precise 0.4.1
264cargo update blake3 --precise 1.5.5
265```
266 
267Additionally, if you encounter warnings about `solana-program` conflicts, add `solana-program = "3"` to the `[dependencies]` section in your program's `Cargo.toml` file (e.g., `programs/your-program/Cargo.toml`).
268 
269 
270## Security Best Practices
271 
272### Account Validation
273- Use typed accounts (`Account<'info, T>`) over `UncheckedAccount` when possible
274- Always validate signer requirements explicitly
275- Use `has_one` for ownership relationships
276- Validate PDA seeds and bumps
277 
278### CPI Safety
279- Use `Program<'info, T>` to validate CPI targets (prevents arbitrary CPI attacks)
280- Never pass extra privileges to CPI callees
281- Prefer explicit program IDs for known CPIs
282 
283### Common Gotchas
284- **Avoid `init_if_needed`**: Permits reinitialization attacks
285- **Legacy IDL formats**: Ensure tooling agrees on format (pre-0.30 vs new spec)
286- **PDA seeds**: Ensure all seed material is stable and canonical
287 
288## Testing
289 
290- Use `NO_DNA=1 anchor test` for end-to-end tests (when run by an agent)
291- Use `NO_DNA=1 anchor build` for builds (when run by an agent)
292- Prefer Mollusk or LiteSVM for fast unit tests
293- Use Surfpool for integration tests with mainnet state
294 
295See [no-dna.org](https://no-dna.org) for the `NO_DNA` standard.
296 
297## IDL and Clients
298 
299- Treat the program's IDL as a product artifact
300- Prefer generating Kit-native clients via Codama
301- If using Anchor TS client in Kit-first app, put it behind web3-compat boundary
302 
303## Migrations
304 
305### Anchor v0.32 → v1
306 
307- **Dependencies** — bump `anchor-lang` and `anchor-spl` to `^1`, and all `solana-*` crates to `^3`.
308- **CPI context** — `CpiContext::new` now takes a program ID (`Pubkey`) instead of a program `AccountInfo`. Remove the program account from the accounts struct.
309- **TypeScript** — replace `@coral-xyz/anchor` with `@anchor-lang/core`.
310- **IDL** — IDL management is being moved off program, **mandatory** actions required.
311 
312See [anchor/migrating-v0.32-to-v1.md](./anchor/migrating-v0.32-to-v1.md) for the full checklist and before/after examples.
313