Sign in

A deployed Solana program is a binary on the chain. There is no way to look at the binary and discover what functions it exposes, what arguments they take, or what accounts they need. The IDL is the file that fills that gap. It's a JSON description of your program's public interface, generated by the Anchor compiler from your Rust source, and it's how every client that talks to your program knows how to call it.

Why the IDL exists

On most platforms you've worked with, the thing you deploy can describe itself, the way a Python or Node server exposes its routes through code that's still readable when the service is running.

What gets deployed on Solana is compiled BPF bytecode. The validators run it, the runtime calls into it, but the bytecode itself carries no information about what's inside. From the outside, your program is a black box with one entry point that takes a buffer of bytes.

The runtime only needs to execute the code, but anyone calling the program from a wallet, a frontend, a backend service, or another program has to build that buffer. The entry point decides which handler to run by the first bytes of the instruction data, called the discriminator, and reads the arguments from the bytes after it. So the caller needs to know which instructions exist, what arguments each one takes and in what order, and which accounts it expects. The IDL is the file that tells them.

Anchor build: source produces program binary for validators and IDL for clientsYour lib.rs source runs through anchor build to produce two outputs: the program binary and the IDL. Validators execute the binary, while clients use the IDL to build typed SDKs. Where the IDL comes from your source lib.rs #[program] pub fn deposit(...) pub fn withdraw(...) #[derive(Accounts)] struct Deposit { ... } anchor build the program binary target/deploy/ my_program.so → deployed to the chain the IDL target/idl/ my_program.json → bundled with your client validators execute the bytecode clients build typed SDKs from it Two outputs from one build The binary goes to the chain. The IDL stays in your repo and gets bundled with your client app. Validators do not need the IDL. Only humans and client code do. The IDL is a description of your program for everyone who isn't a validator.

When you run anchor build, the compiler does two jobs. The first is to compile the Rust source into BPF bytecode, producing the .so file that gets deployed to the chain. The second is to walk through your source and emit a JSON description of every public interface it found, producing the IDL file. The binary is uploaded to the chain, and the IDL stays in your repo and gets bundled with whatever client app talks to the program. You never write the IDL yourself. It is regenerated on every build, so if you change a handler's arguments in Rust, the IDL changes to match, and the Rust source stays the source of truth.

The closest analog from other ecosystems is OpenAPI. Your Solana program is like a backend service, the IDL is like the OpenAPI spec, and the TypeScript client is like the SDK generated from that spec. The difference is that on Solana, the spec is mandatory for any nontrivial client work, since there is no other way to introspect the program.

What's inside

The IDL is a single JSON file. The top carries the program's address, its name, and its version. The instructions array has one entry for each handler in your #[program] module. Each entry names the instruction, lists the accounts it expects in order, and describes the arguments it takes with their types. The accounts array lists every account type you defined with #[account], and the types array describes the field layout of each one, so a client can deserialize the raw bytes of an on-chain account back into a typed object. The errors array carries the custom errors you defined with #[error_code], and the client uses it to map the error number of a failed transaction back to a name and message.

IDL JSON structure: program address, instructions, accounts, types, errorsThe my_program.json sample shows a program address, an instructions array (each handler's name, accounts, and arguments), an accounts array of account structs, a types array with shared field layouts, and an errors array of error codes. A caption notes the IDL describes every public interface of the program and is generated by the compiler, never hand-written. What's inside an IDL JSON my_program.json { "address": "Fg6PaF...8nN", "metadata": { "name": "...", ... }, "instructions": [ { "name": "deposit", "accounts": [...], "args": [ { "name": "amount", "type": "u64" } ] } ], "accounts": [ { "name": "Vault", ... } ], "types": [ { "name": "Vault", "type": { "fields": [...] }} ], "errors": [...] } program address every instruction handler: its name, accounts, arguments account structs the data types shared types field layouts for each struct error codes Every public interface of your program, described in JSON. Generated by the compiler, never hand-written.

Clients build every call from the IDL

The Anchor TypeScript SDK, the most common way to talk to Solana programs from a web app, is built around the IDL. You hand the JSON file to a Program constructor along with a provider that holds the wallet and connection, and the result is a typed client object whose methods correspond one-to-one with the instructions in your program. When you call deposit, the SDK looks it up in the IDL's instructions array, serializes your arguments according to the types listed there, builds the instruction, signs the transaction with the provider's wallet, and sends it. The client side lesson shows the code.

Treating the IDL as a deliverable

Anyone integrating with your program will read your IDL, generate a client from it, and write code against the resulting types, so the IDL is the program's public API surface. Nothing on chain checks it against the deployed binary, because validators run the bytecode and do not need the IDL. A client that ships a stale IDL finds out only when its calls go wrong: arguments serialize to the wrong layout, account lists come out wrong, and error numbers map to names that moved.

Versioning the IDL the way you'd version a library helps. Many production programs keep a history of IDL versions in their repo so integrators can pin to a known shape. When you rename a field or add a new instruction, the IDL changes in ways that show up as a diff. Reviewing that diff during code review is one of the cheapest ways to catch accidental API breaks before they are released.