IDLs (Interface Definition Language)

IDL staat voor Interface Definition Language.
Op Solana zijn IDLs JSON-bestanden die de interface van een programma beschrijven. Ze stellen explorers en gebruikers in staat om programma-instructies, accountgegevens en programmafouten te decoderen, en bieden de mogelijkheid om clients te genereren in verschillende programmeertalen.

Waarom IDLs belangrijk zijn

Standaardisatie → Een gedeeld formaat voor programma-interfaces.
Ontwikkelaarservaring → Genereer client-SDK's automatisch.
Composabiliteit → Andere ontwikkelaars kunnen met jouw programma communiceren zonder de broncode te lezen.
Leesbaarheid → Iedereen kan programma-instructies en accountgegevens lezen in explorers zonder de broncode van het programma te lezen.

Wat je kunt doen met IDLs

Instructie- en accountgegevens decoderen

Alle explorers gebruiken programma-IDLs om instructies en accountgegevens te decoderen. Hier kun je een Anchor 0.30.1 en een Legacy IDL voorbeeld zien in de Solana Explorer-interface. In deze transactie kun je de gedecodeerde instructie zien voor een 2048-spel, inclusief pushInDirection en de richting ervan.

Je kunt instructies en accountgegevens decoderen in je TypeScript-client door gebruik te maken van de Solana JS-hulpfuncties.

Anchor-events of accountwijzigingen verwerken

Je kunt eenvoudig abonneren op accountwijzigingen in je programma door gebruik te maken van de gegenereerde TypeScript-types.

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)
  );
});

Je kunt bijvoorbeeld Anchor-events uitzenden in je programma en deze events vervolgens loggen, opslaan in een database of gebruiken om bijvoorbeeld een bericht te sturen naar een Telegram-chat.

// 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(),
});

Daarvoor kun je de Solana JS-hulpfuncties gebruiken om de events te verwerken. Hier is een voorbeeldimplementatie die Anchor-events gebruikt om berichten te plaatsen in een Telegram-chat.

Transacties decoderen

Je kunt ook transacties decoderen in je client door gebruik te maken van de Solana JS-hulpfuncties. Dit geeft je een getypeerd object van de volledige transactie.

Bouw je eigen client

Met een IDL kun je je eigen client maken in veel talen. Je zoekt gewoon een programma waarmee je wilt communiceren, downloadt de IDL en vervolgens kun je een client genereren in je voorkeurstaal.

Hier is een voorbeeld van hoe je een client kunt genereren in TypeScript.

IDLs in Anchor

Als je het Anchor-framework gebruikt:

De IDL wordt automatisch gegenereerd wanneer je je programma bouwt.
Deze bevindt zich in target/idl/<program>.json.
TypeScript-types worden gegenereerd in target/types/<program>.ts.
Het programmaadres is opgeslagen in de IDL (idl.address).

anchor build
cat target/idl/counter.json

Anatomie van een IDL

Hier is een minimaal voorbeeld (Anchor v0.30+ spec):

{
  "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: het onchain programma-ID.
metadata: { name, version, spec, ... } over het programma/de interface.
instructions: aanroepbare methoden met accounts, args en een discriminator.
accounts: accounttypes die door het programma worden blootgesteld (met discriminators).
types: struct/enum/type-aliassen waarnaar wordt verwezen door instructies/accounts.
events / errors / constants: optionele definities voor events, foutcodes en constanten.

Opmerking: Anchor v0.30 introduceerde een nieuwe IDL-spec. Legacy IDLs (vóór 0.30) gebruikten velden zoals name, version op het hoogste niveau en isMut/isSigner in accounts. Je kunt legacy IDLs converteren met anchor idl convert of opnieuw bouwen met Anchor v0.30+. Als je een legacy IDL on-the-fly naar de nieuwe spec wilt converteren, kun je ook deze conversiecode gebruiken. Dit is bijvoorbeeld handig als je een Solana-explorer onderhoudt en achterwaartse compatibiliteit wilt behouden.

TypeScript-client

Anchor genereert ook automatisch een TypeScript-client voor je. Je kunt de gegenereerde client vinden in de map target/types.

Dan kun je in je client (TypeScript, v0.30+) programma-instructies aanroepen en accounts ophalen zo eenvoudig als dit:

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

Om een C#-client te genereren kun je het volgende commando gebruiken:

cd program
dotnet tool install Solana.Unity.Anchor.Tool <- run once
dotnet anchorgen -i target/idl/counter.json -o target/idl/Counter.cs

Je kunt meer lezen over hoe je kunt communiceren met een C#-client vanuit Unity in de Solana games preset of in de Games-documentatie.

Python-client

Voor Python kun je de AnchorPy-bibliotheek gebruiken.

In de toekomst zullen meer clientgeneratoren beschikbaar zijn via Codama-renderers.

IDLs zonder Anchor

Niet alle programma's zijn gebouwd met Anchor.
Voor native Solana-programma's:

Een tool genaamd Codama is momenteel in ontwikkeling om IDLs te genereren vanuit Rust via macro's of door Anchor IDLs te converteren. Hier is een work-in-progress voorbeeld van Codama Macros om een Codama IDL te genereren. Codama converteert Anchor/Shank IDLs naar een Codama IDL. Om een Anchor IDL te verkrijgen, genereer je deze met Anchor (of gebruik anchor idl convert voor legacy-projecten).
Totdat de Codama-macro's volledig klaar zijn, kun je ook Metaplex Shank gebruiken om een Shank IDL te genereren en deze vervolgens te converteren naar een Codama IDL.
Je kunt ook de IDL handmatig schrijven (in Anchor- of Codama-formaat), maar dit is niet erg betrouwbaar. AI-tools zoals Cursor kunnen je helpen de IDL te schrijven, maar je moet de IDL altijd verifiëren aan de hand van de broncode van het programma. De betere aanpak is om Anchor, Codama of Metaplex Shank te gebruiken.

IDLs on-chain opslaan

Er zijn twee manieren om IDLs on-chain te uploaden. De meest gebruikte en standaard manier is het Anchor IDL-account. Hoe Anchor je in staat stelt je IDLs on-chain te uploaden, is door additionale instructies aan je programma toe te voegen waarmee je je IDLs on-chain kunt uploaden en bijwerken. Dit voegt enige extra omvang toe aan het programma, en dat is waarom het program metadata program werd gecreëerd. In het program metadata program worden alle programma-IDLs en security.txt-informatie zoals naam, contactgegevens en pictogram opgeslagen in PDA's van het program metadata program.

Anchor IDL-account

Anchor slaat IDLs on-chain op in een PDA van je programma.

IDLs kunnen on-chain worden geüpload naar het Anchor IDL-account.
Dit stelt explorers, wallets en SDK's in staat de IDL rechtstreeks van Solana op te halen.

Eerste keer (het IDL-account initialiseren):

anchor idl init <PROGRAM_ID> -f target/idl/counter.json --provider.cluster devnet

Upgrades (volgende updates door de beheerder):

anchor idl upgrade <PROGRAM_ID> -f target/idl/counter.json --provider.cluster devnet

Handige gerelateerde commando's:

anchor idl fetch -o idl.json <PROGRAM_ID>
anchor idl authority <PROGRAM_ID>
anchor idl set-authority -p <PROGRAM_ID> -n <NEW_AUTHORITY>
anchor idl erase-authority -p <PROGRAM_ID>

Merk op dat standaard de generatie van het Anchor IDL-account toestemmingsloos is. Upload de IDL dus zo snel mogelijk en stel daarna een beheerder in.

Je kunt meer lezen over het Anchor IDL-account in de Anchor-documentatie.

Program Metadata Program (PMP)

Het program metadata program is een programma waarmee je de programma-IDLs en security.txt-informatie zoals naam, contactgegevens en pictogram on-chain kunt opslaan. Dit wordt waarschijnlijk de standaard manier om IDLs on-chain op te slaan in de toekomst.

npx @solana-program/program-metadata write idl <program-id> ./idl.json

Je kunt meer lezen over het program metadata program in de program metadata program-documentatie.

Opmerking: Op het moment van de laatste update van dit artikel wordt de PMP nog niet door alle explorers ondersteund.

Best practices

De beste aanpak voor programma-deploys is om een Multisig te gebruiken zoals Squads, en om dit proces zo eenvoudig mogelijk te maken gebruik je de Solana GitHub Actions-workflows.

Op deze manier wordt het programma automatisch geüpgraded, de IDL geüpload, de build geverifieerd en wordt er vervolgens een transactie voorgesteld voor je multisig om te ondertekenen en het programma te deployen.

Houd IDLs bijgewerkt → Werk de IDL altijd bij wanneer je wijzigingen aanbrengt in je programma.
Upload IDLs on-chain → voor transparantie en ondersteuning van tooling.
Documenteer aangepaste fouten → verbetert de UX voor clients.
Verifieer builds → zorg ervoor dat de IDL overeenkomt met het gedeployde programma.

IDL-versiebeheer

Momenteel kun je met Anchor slechts één versie van de IDL tegelijk on-chain hebben. Dit betekent dat als je wijzigingen wilt aanbrengen in je programma, je een nieuwe versie van de IDL moet uploaden, bij voorkeur tegelijk met het upgraden van het programma. Dit kan tot problemen leiden als de clients nog niet zijn bijgewerkt, en is één van de redenen waarom het program metadata program is geschreven. Met PMP kun je verschillende seeds voor je programma hebben en op die manier versiebeheer toepassen. Het ontwerp daarvoor is nog niet volledig definitief en staat open voor discussie.

Verder lezen

Anchor-documentatie over IDLs → genereert automatisch IDLs en clients. (TypeScript, C#, Python)
Codama → IDL-tooling + clientgeneratoren (Rust, JS/TS, Umi/Kit, etc.).
Program Metadata Program → sla IDLs en security.txt-informatie on-chain op.

Dit zijn de basisprincipes van IDLs op Solana. Ze vormen de brug tussen on-chain programma's en off-chain clients, en maken het rijke ecosysteem van tools en SDK's mogelijk dat je vandaag de dag ziet.

IDL - een eenvoudig te gebruiken programma-interface