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.json

When 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.json

What 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

FAQs

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.