The Anchor IDL
The Anchor IDL is a JSON description of your program's instructions, accounts, types, events, and errors. anchor build regenerates it from Rust macros.
Recipe
anchor build
ls target/idl/my_program.json{
"address": "Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS",
"instructions": [ { "name": "initialize", "accounts": [], "args": [] } ],
"errors": [],
"events": []
}When to reach for this: You integrate clients, CPI consumers, or publish on-chain metadata.
Working Example
// Rust macros drive IDL content
#[program]
pub mod my_program { /* ... */ }
#[account]
pub struct Config { pub admin: Pubkey }
#[event]
pub struct ConfigUpdated { pub admin: Pubkey }
#[error_code]
pub enum MyError { #[msg("Unauthorized")] Unauthorized }After build, IDL includes all public instructions, account types, events, and errors.
What this demonstrates:
- IDL address field matches declare_id!
- Instructions list account names and mutability
- Types section mirrors #[account] structs
- Errors include code and msg
Deep Dive
IDL Consumers
- TypeScript clients (@coral-xyz/anchor, Codama)
declare_program!CPI generation- Documentation and SDK publishing
Versioning
Tag IDL JSON with program release. Breaking account layout changes require client bumps.
Gotchas
- Hand-editing IDL - Drifts from on-chain truth.. Fix: Regenerate only via build.
- Not publishing IDL updates - Clients break silently.. Fix: CI check IDL diff on PR.
- Private instructions - Only pub handlers in IDL.. Fix: Keep helpers private.
- Renamed Rust fields without migration - Client account order breaks.. Fix: Version instructions.
- IDL missing from npm package - Integrators guess layouts.. Fix: Ship IDL artifact.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| On-chain IDL account | Discoverable on-chain | Repo-only IDL |
| Codama IDL transform | Kit-native output | Raw Anchor IDL only |
FAQs
Anchor version?
0.32.1 across advanced topics.
When to use zero_copy?
Large fixed layouts when Borsh CU too high.
Is realloc reversible?
Not easily; plan forward growth.
Are remaining accounts in IDL?
No; document separately.
declare_program! needs what?
Callee IDL JSON at compile time.
Can Anchor CPI to Pinocchio?
Yes with correct account metas.
Feature flags and IDL?
Avoid different IDL per feature on mainnet.
How to measure CU?
LiteSVM, Surfpool, devnet simulation.
Custom account types common?
No; last resort.
Next steps?
See Related links for idl.
Related
- declare_program! - consume IDL in Rust
- Generating TS Clients - TS
- On-Chain IDLs - publish
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.