On-Chain IDLs
Anchor can store IDL on-chain in a program-owned account so explorers and clients fetch canonical interfaces by program ID.
Recipe
anchor idl init -f target/idl/my_program.json <PROGRAM_ID>
anchor idl fetch <PROGRAM_ID> -o idl/my_program.jsonWhen to reach for this: You want discoverable interfaces without relying solely on GitHub.
Working Example
# After deploy and build
anchor idl init -f target/idl/my_program.json Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS --provider.cluster devnet
# Consumers fetch
anchor idl fetch Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS -o fetched.jsonWhat this demonstrates:
- idl init creates on-chain IDL account
- idl fetch retrieves JSON for clients
- Upgrade IDL with anchor idl upgrade when API changes
- Pair with verifiable builds for trust
Deep Dive
Trust Model
On-chain IDL is convenient, not a substitute for reproducible builds. Pair with verified program hashes.
Size Limits
Large IDLs may need chunking strategies; monitor account size and rent.
Gotchas
- IDL not updated after upgrade - Clients fetch stale API.. Fix: Run idl upgrade with program release.
- Trusting fetched IDL without hash check - Supply chain risk.. Fix: Compare to release artifact.
- Authority key compromise - Malicious IDL published.. Fix: Protect upgrade authority.
- Fetch from wrong cluster - Wrong program id mapping.. Fix: Pin cluster in tooling.
- Oversized IDL account - Init fails.. Fix: Trim docs metadata from IDL JSON.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| GitHub releases only | Full CI review | Wallet/explorer discoverability |
| npm IDL package | Versioned installs | On-chain discovery |
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 on-chain idl.
Related
- The Anchor IDL - contents
- IDL Versioning - releases
- Verifiable Builds - verify
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.