IDL's (Interface Definition Language)

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

Waarom IDL's belangrijk zijn

Standaardisatie → Een gedeeld formaat voor programma-interfaces.
Ontwikkelaarservaring → Genereer client-SDK's automatisch.
Composabiliteit → Andere ontwikkelaars kunnen met jouw programma werken 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 IDL's

Instructie- en accountgegevens decoderen

Alle explorers gebruiken programma-IDL's om instructies en accountgegevens te decoderen. Hier zie je een Anchor 0.30.1 en een Legacy IDL voorbeeld in de Solana Explorer UI. In deze transactie zie je de gedecodeerde instructie voor een 2048-spel, inclusief pushInDirection en de bijbehorende richting.

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

Accountwijzigingen verwerken

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

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

Voor event-definities, subscriptions, log- en CPI-decodering, backfills, schema- versiebeheer en testen, zie Anchor Events.

Transacties decoderen

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

Bouw je eigen client

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

Hier is een voorbeeld van hoe je een client genereert in TypeScript.

IDL's 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-typen 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: accounttypen 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, constanten.

Opmerking: Anchor v0.30 introduceerde een nieuwe IDL-spec. Legacy IDL's (vóór 0.30) gebruikten velden zoals name, version op het hoogste niveau en isMut/isSigner in accounts. Je kunt legacy IDL's 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 beheert 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.

Vervolgens 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 werken met een C#-client vanuit Unity in de Solana games preset of in de Games docs.

Python-client

Voor Python kun je de AnchorPy-bibliotheek gebruiken.

In de toekomst zullen er meer client-generators beschikbaar zijn via Codama-renderers.

IDL's zonder Anchor

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

Een tool genaamd Codama is momenteel in ontwikkeling om IDL's te genereren vanuit Rust via macro's of door Anchor IDL's te converteren. Hier is een voorbeeld in uitvoering van Codama Macros om een Codama IDL te genereren. Codama converteert Anchor/Shank IDL's naar een Codama IDL. Om een Anchor IDL te verkrijgen, genereer je die met Anchor (of gebruik je 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 met de hand 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 programma- broncode. De betere manier is om Anchor, Codama of Metaplex Shank te gebruiken.

IDL's on-chain opslaan

Er zijn twee manieren om IDL's onchain te uploaden. De meest gebruikte en standaard manier is het Anchor IDL-account. De manier waarop Anchor je in staat stelt je IDL's onchain te uploaden is door aditionele instructies aan je programma toe te voegen, waarmee je je IDL's onchain kunt uploaden en bijwerken. Dit voegt wat extra grootte toe aan het programma en daarom werd het programma-metadataprogramma gecreëerd. In het programma-metadataprogramma worden alle IDL's en security.txt-info zoals naam, contactgegevens en icoon opgeslagen in PDA's van het programma-metadataprogramma.

Anchor IDL-account

Anchor slaat IDL's onchain op in een PDA van je programma.

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

Eerste keer (het IDL-account initialiseren):

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

Upgrades (daaropvolgende updates door de authority):

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

Nuttige 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 aanmaak van het Anchor IDL-account permissieloos is. Upload je IDL dus zo snel mogelijk en stel vervolgens een authority in.

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

Programma Metadata Programma (PMP)

Het programma-metadataprogramma is een programma waarmee je de programma-IDL's en security.txt-info zoals naam, contactgegevens en icoon onchain kunt opslaan. Dit zal waarschijnlijk in de toekomst de standaardmanier worden om IDL's onchain op te slaan.

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

Je kunt meer lezen over het programma-metadataprogramma in de programma-metadataprogramma docs.

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

Best practices

De beste werkwijze 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 vervolgens wordt er een transactie voorgesteld voor je multisig om te ondertekenen en het programma te deployen.

Houd IDL's up-to-date → Werk de IDL altijd bij wanneer je wijzigingen aanbrengt in je programma.
Upload IDL's onchain → voor transparantie en toolingondersteuning.
Documenteer aangepaste fouten → verbetert de UX voor clients.
Verifieer builds → zorg ervoor dat de IDL overeenkomt met het gedeployde programma.

IDL's 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 programma-metadataprogramma is geschreven. Met PMP kun je verschillende seeds voor je programma gebruiken en op die manier versiebeheer toepassen. Het ontwerp hiervoor is nog niet volledig definitief en staat open voor discussie.

Verder lezen

Anchor Docs over IDL's → genereert automatisch IDL's en clients. (TypeScript, C#, Python)
Codama → IDL-tooling + client- generators (Rust, JS/TS, Umi/Kit, enz.).
Programma Metadata Programma → sla IDL's en security.txt-informatie onchain op.

Dat zijn de basisprincipes van IDL's op Solana. Ze vormen de brug tussen onchain 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