--- title: IDL - an easy to use Program Interface seoTitle: "IDLs (Interface Definition Language)" description: "IDLs are a JSON representation of a program and let you decode the program's instructions and accounts, generate clients in different languages and lets people understand the program's interface without reading the source code." tags: - web3js - anchor keywords: - tutorial - anchor - idl - web3js - intro to solana development - blockchain developer - blockchain tutorial - web3 developer --- IDL stands for **Interface Definition Language**. On Solana, IDLs are JSON files that describe the interface of a program. They allow explorers and users to decode program instructions, account data and program errors and offer the possibility to generate clients in different program languages. --- ## Why IDLs Matter - **Standardization** → A shared format for program interfaces. - **Developer Experience** → Generate client SDKs automatically. - **Composability** → Other developers can interact with your program without reading its source code. - **Readability** → Everyone can read program instructions and account data in explorers without reading the program’s source code. --- ## What you can do with IDLs ### Decoding Instruction and Account Data All Explorers use program IDLs to decode instructions and account data. Here you can see a [Anchor 0.30.1](https://explorer.solana.com/address/MkabCfyUD6rBTaYHpgKBBpBo5qzWA2pK2hrGGKMurJt/idl) and a [Legacy IDL](https://explorer.solana.com/address/2o48ieM95rmHqMWC5B3tTX4DL7cLm4m1Kuwjay3keQSv/idl) example in the Solana Explorer UI. In [this transaction](https://explorer.solana.com/tx/3U81bTLnaJr3vZRx6LRovP8WJ2d4afiysFkjXijiPsZaHejFMuhHVXd8bPpAGckUwoqqq1te1LMvqQwCCjYobgm4) you can see the decoded instruction for a 2048 game, including `pushInDirection` and its direction. You can decode instructions and account data in your typescript client by using the [Solana JS helpers](https://github.com/solana-developers/helpers?tab=readme-ov-file#parse-account-data). ### Parsing Anchor Events or Account changes You can easily subscribe to account changes in your program by using the generated TypeScript types. ```ts import { Connection } from "@solana/web3.js"; const connection = new Connection("https://api.devnet.solana.com"); // Fetch account once const account = await program.account.counter.fetch(counterPda); // Subscribe via websocket to account changes program.account.counter.subscribe(counterPda).on("change", (account) => { console.log("Account changed:", account); }); // Or use decoder to decode any account or instruction data connection.onAccountChange(counterPda, (accInfo) => { console.log( "Account changed:", program.coder.accounts.decode("counterData", account.data) ); }); ``` You can for example emit Anchor events in your program and then log these events, write them in a database or use them to for example send a message into a telegram chat. ```Rust // Emit the purchase event emit!(PurchaseMade { buyer: *ctx.accounts.signer.key, product_name: name, price, timestamp: Clock::get()?.unix_timestamp, table_number, receipt_id, telegram_channel_id: ctx.accounts.receipts.telegram_channel_id.clone(), store_name: ctx.accounts.receipts.store_name.clone(), receipts_account: ctx.accounts.receipts.key(), }); ``` For that you can use the [Solana JS helpers](https://github.com/solana-developers/helpers?tab=readme-ov-file#parse-transaction-events) to parse the events. Here is an [example implementation](https://github.com/Woody4618/bar/blob/main/app/pages/api/webhooktg.ts#L61) that uses anchor events to post messages into a telegram chat. ### Decode Transactions You can also decode transactions in your client by using the [Solana JS helpers](https://github.com/solana-developers/helpers?tab=readme-ov-file#decode-anchor-transaction). This will give you a typed object of the whole transaction. ### Build your own client Using an IDL you can create your own client in many languages. You just find a program you want to interact with, download the IDL and then you can generate a client in your preferred language. Here is an [example](#typescript-client) of how to generate a client in TypeScript. ## IDLs in Anchor If you’re using the [Anchor framework](https://www.anchor-lang.com/): - The IDL is auto-generated when you build your program. - It lives in `target/idl/.json`. - TypeScript types are generated in `target/types/.ts`. - The program address is stored in the IDL (`idl.address`). ```bash anchor build cat target/idl/counter.json ``` ## Anatomy of an IDL Here’s a minimal example (Anchor v0.30+ spec): ```json { "address": "6khKp4BeJpCjBY1Eh39ybiqbfRnrn2UzWeUARjQLXYRC", "metadata": { "name": "counter", "version": "0.1.0", "spec": "0.1.0" }, "instructions": [ { "name": "increment", "discriminator": [11, 18, 104, 9, 104, 174, 59, 33], "accounts": [{ "name": "counter", "writable": true }], "args": [] } ], "accounts": [ { "name": "Counter", "discriminator": [255, 176, 4, 245, 188, 253, 124, 25] } ], "types": [ { "name": "Counter", "type": { "kind": "struct", "fields": [{ "name": "count", "type": "u64" }] } } ] } ``` - **address**: the onchain program ID. - **metadata**: `{ name, version, spec, ... }` about the program/interface. - **instructions**: callable methods with `accounts`, `args`, and a `discriminator`. - **accounts**: account types exposed by the program (with discriminators). - **types**: struct/enum/type aliases referenced by instructions/accounts. - **events / errors / constants**: optional definitions for events, error codes, constants. > Note: Anchor v0.30 introduced a new IDL spec. Legacy IDLs (pre-0.30) used > fields like `name`, `version` at top level and `isMut`/`isSigner` in accounts. > You can convert legacy IDLs using `anchor idl convert` or rebuild with Anchor > v0.30+. If you need to convert a legacy IDL to the new spec on the fly you can > also use this > [conversion code](https://github.com/solana-developers/helpers/blob/main/src/lib/convertLegacyIdl.ts). > This is useful for example if you maintain a solana explorer and want to stay > backwards compatible. --- ### TypeScript Client Anchor will also automatically generate a TypeScript client for you. You can find the generated client in the `target/types` folder. Then in your client (TypeScript, v0.30+) you can call program instructions and fetch accounts as easy as this: ```ts import { AnchorProvider, Program } from "@coral-xyz/anchor"; import idl from "./counter.json"; const provider = AnchorProvider.local(); const program = new Program(idl, provider); await program.methods.increment().rpc(); ``` ### C# Client To generate a C# client you can use the following command: ```bash cd program dotnet tool install Solana.Unity.Anchor.Tool <- run once dotnet anchorgen -i target/idl/counter.json -o target/idl/Counter.cs ``` You can read more about how to interact with a C# client from Unity in the [Solana games preset](https://github.com/solana-developers/solana-game-preset) or in the [Games docs](https://solana.com/de/developers/cookbook/games/porting-anchor-to-unity#generating-the-client). ### Python Client For Python you can use the [AnchorPy](https://github.com/kevinheavey/anchorpy) library. More client generators will be available using Codama renderers in the future. --- ## IDLs Without Anchor Not all programs are built with Anchor. For native Solana programs: - A tool called **[Codama](https://github.com/codama-idl/codama)** is currently in development to generate IDLs from Rust via macros or by converting Anchor IDLs. Here is an in progress example of [Codama Macros](https://github.com/lorisleiva/codama-demo-2025-08/tree/main/3-from-macros) to generate a Codama IDL. Codama converts Anchor/Shank IDLs into a Codama IDL. To get an Anchor IDL, generate it with Anchor (or use `anchor idl convert` for legacy projects). - Until the codama macros are completely ready you can also use [Metaplex Shank](https://github.com/metaplex-foundation/shank) to generate a Shank IDL, then convert it to a Codama IDL. - You can also **write the IDL by hand** (Anchor or Codama formats) but this is not very reliable. AI tools like [Cursor](https://www.cursor.com/) can help you to write the IDL but you should always verify the IDL with the program source code and the better way is to use Anchor, Codama or Metaplex Shank. --- ## Storing IDLs On-Chain There are two ways to upload IDLs onchain. The most used and standard one is the Anchor IDL account. How Anchor allows you to upload your IDLs onchain is by adding additional instructions to your program allow you to upload and update your IDLs onchain. This adds some extra size to the program and this is why the program metadata program was created. In the program metadata program all the program IDLs and security.txt info like name, contact and icon are stored in PDAs of the [program metadata program](https://github.com/solana-program/program-metadata). ### Anchor IDL Account Anchor saves IDLs onchain in a PDA of your program. - IDLs can be uploaded **onchain** to the Anchor IDL account. - This allows explorers, wallets, and SDKs to fetch the IDL directly from Solana. First time (initialize the IDL account): ```bash anchor idl init -f target/idl/counter.json --provider.cluster devnet ``` Upgrades (subsequent updates by the authority): ```bash anchor idl upgrade -f target/idl/counter.json --provider.cluster devnet ``` Useful related commands: ```bash anchor idl fetch -o idl.json anchor idl authority anchor idl set-authority -p -n anchor idl erase-authority -p ``` Note that by default the Anchor IDL account generation is permissionless. So upload your IDL as soon as possible and then set an authority. You can read more about the Anchor IDL account in the [Anchor docs](https://www.anchor-lang.com/docs/basics/idl). ### Program Metadata Program (PMP) The program metadata program is a program that allows you to store the program IDLs and security.txt info like name, contact and icon onchain. This will probably be the standard way to store IDLs onchain in the future. ```bash npx @solana-program/program-metadata write idl ./idl.json ``` You can read more about the program metadata program in the [program metadata program docs](https://github.com/solana-program/program-metadata). Note: As of the last update of the article the PMP is not supported by all explorers yet. --- ## Best Practices The best practise for program deploys is to use a Multisig like [Squads](https://squads.so/) and to make this process as easy as possible you use the [Solana GitHub Actions workflows](https://github.com/solana-foundation/github-workflows). Like this the program will automatically be upgraded, IDL uploaded, the build verified and then there will be a transaction proposed for your multisig to sign and deploy the program. 1. **Keep IDLs updated** → Always update the IDL when you make changes to your program. 2. **Upload IDLs onchain** → for transparency and tooling support. 3. **Document custom errors** → improves UX for clients. 4. **Verify builds** → ensure the IDL matches the deployed program. ## Versioning IDLs Currently with Anchor you can only have one version of the IDL on chain at a time. This means that if you want to make changes to your program you need to upload a new version of the IDL, preferably at the same time as you upgrade the program. This can lead to problems if the clients are not updated yet and is one reason why the program metadata program was written. With PMP, you will be able to have different seeds for your program and do versioning like that. The design for that is not completely final yet and open for discussion. --- ## Further Reading - [Anchor Docs on IDLs](https://www.anchor-lang.com/docs/basics/idl) → auto-generates IDLs and clients. (TypeScript, C#, Python) - [Codama](https://github.com/codama-idl/codama) → IDL tooling + client generators (Rust, JS/TS, Umi/Kit, etc.). - **[Program Metadata Program](https://github.com/solana-program/program-metadata)** → store IDLs and security.txt information onchain. --- That’s the basics of IDLs on Solana. They’re the **bridge between onchain programs and off-chain clients**, enabling the rich ecosystem of tools and SDKs you see today.