Codegen Best Practices
One source of truth: Rust program macros generate IDL; clients and CPI crates consume generated artifacts.
How to Use This List
- Treat IDL changes as API changes requiring changelog.
- Automate codegen in CI.
- Never hand-edit generated TS/Rust CPI output.
A - IDL source
- Commit IDL or publish on-chain with every release pick one canonical path per org.
- CI fails on uncommitted IDL diff after anchor build no silent API drift.
- Vendor callee IDLs for declare_program! pin version per deployment.
B - Client codegen
- Regenerate Codama/TS on IDL bump do not patch generated files.
- Pin @solana/kit and Codama CLI versions reproducible output.
- Ship error and event enums to UI layer for decoding.
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 codegen bp.
Related
- The Anchor IDL - IDL
- Codama from an Anchor IDL - kit
- Errors & Events Best Practices - observability
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.