IDLs (Interface Definition Language)

IDL signifie Interface Definition Language (langage de définition d'interface).
Sur Solana, les IDLs sont des fichiers JSON qui décrivent l'interface d'un programme. Ils permettent aux explorateurs et aux utilisateurs de décoder les instructions de programme, les données de compte et les erreurs de programme, et offrent la possibilité de générer des clients dans différents langages de programmation.

Pourquoi les IDLs sont importants

Standardisation → Un format commun pour les interfaces de programme.
Expérience développeur → Générez automatiquement des SDK clients.
Composabilité → D'autres développeurs peuvent interagir avec votre programme sans en lire le code source.
Lisibilité → Tout le monde peut lire les instructions du programme et les données de compte dans les explorateurs sans lire le code source du programme.

Ce que vous pouvez faire avec les IDLs

Décoder les instructions et les données de compte

Tous les explorateurs utilisent les IDLs de programme pour décoder les instructions et les données de compte. Vous pouvez voir ici un exemple Anchor 0.30.1 et un exemple Legacy IDL dans l'interface Solana Explorer. Dans cette transaction vous pouvez voir l'instruction décodée pour un jeu 2048, notamment pushInDirection et sa direction.

Vous pouvez décoder les instructions et les données de compte dans votre client TypeScript en utilisant les helpers Solana JS.

Écouter les changements de compte

Vous pouvez facilement vous abonner aux changements de compte dans votre programme en utilisant les types TypeScript générés.

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

Pour les définitions d'événements, les abonnements, le décodage des logs et des CPI, les backfills, la gestion des versions de schéma et les tests, consultez Anchor Events.

Décoder les transactions

Vous pouvez également décoder des transactions dans votre client en utilisant les helpers Solana JS. Cela vous fournira un objet typé de l'ensemble de la transaction.

Créer votre propre client

En utilisant un IDL, vous pouvez créer votre propre client dans de nombreux langages. Il vous suffit de trouver un programme avec lequel vous souhaitez interagir, de télécharger l'IDL, puis vous pouvez générer un client dans le langage de votre choix.

Voici un exemple illustrant comment générer un client en TypeScript.

Les IDLs dans Anchor

Si vous utilisez le framework Anchor :

L'IDL est auto-généré lors de la compilation de votre programme.
Il se trouve dans target/idl/<program>.json.
Les types TypeScript sont générés dans target/types/<program>.ts.
L'adresse du programme est stockée dans l'IDL (idl.address).

anchor build
cat target/idl/counter.json

Anatomie d'un IDL

Voici un exemple minimal (spécification Anchor v0.30+) :

{
  "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 : l'ID du programme onchain.
metadata : { name, version, spec, ... } concernant le programme/l'interface.
instructions : méthodes appelables avec accounts, args et un discriminator.
accounts : types de comptes exposés par le programme (avec discriminateurs).
types : alias de struct/enum/type référencés par les instructions/comptes.
events / errors / constants : définitions optionnelles pour les événements, les codes d'erreur et les constantes.

Remarque : Anchor v0.30 a introduit une nouvelle spécification IDL. Les IDLs legacy (antérieurs à la v0.30) utilisaient des champs comme name, version au niveau supérieur et isMut/isSigner dans les comptes. Vous pouvez convertir les IDLs legacy en utilisant anchor idl convert ou en recompilant avec Anchor v0.30+. Si vous devez convertir un IDL legacy vers la nouvelle spécification à la volée, vous pouvez également utiliser ce code de conversion. Cela est utile, par exemple, si vous maintenez un explorateur Solana et souhaitez rester rétrocompatible.

Client TypeScript

Anchor générera également automatiquement un client TypeScript pour vous. Vous pouvez trouver le client généré dans le dossier target/types.

Puis dans votre client (TypeScript, v0.30+) vous pouvez appeler les instructions du programme et récupérer les comptes aussi simplement que ceci :

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

Client C#

Pour générer un client C#, vous pouvez utiliser la commande suivante :

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

Vous pouvez en savoir plus sur la façon d'interagir avec un client C# depuis Unity dans le preset de jeux Solana ou dans la documentation Games.

Client Python

Pour Python, vous pouvez utiliser la bibliothèque AnchorPy.

D'autres générateurs de clients seront disponibles via les renderers Codama à l'avenir.

IDLs sans Anchor

Tous les programmes ne sont pas construits avec Anchor.
Pour les programmes Solana natifs :

Un outil appelé Codama est actuellement en cours de développement pour générer des IDLs depuis Rust via des macros ou en convertissant des IDLs Anchor. Voici un exemple en cours de Macros Codama pour générer un IDL Codama. Codama convertit les IDLs Anchor/Shank en IDL Codama. Pour obtenir un IDL Anchor, générez-le avec Anchor (ou utilisez anchor idl convert pour les projets legacy).
En attendant que les macros Codama soient entièrement prêtes, vous pouvez également utiliser Metaplex Shank pour générer un IDL Shank, puis le convertir en IDL Codama.
Vous pouvez également écrire l'IDL à la main (formats Anchor ou Codama), mais cette approche n'est pas très fiable. Des outils IA comme Cursor peuvent vous aider à rédiger l'IDL, mais vous devriez toujours vérifier l'IDL avec le code source du programme ; la meilleure approche reste d'utiliser Anchor, Codama ou Metaplex Shank.

Stocker les IDLs on-chain

Il existe deux façons de mettre des IDLs onchain. La plus utilisée et la plus standard est le compte IDL Anchor. La façon dont Anchor vous permet de mettre vos IDLs onchain consiste à ajouter des instructions supplémentaires à votre programme pour vous permettre de téléverser et de mettre à jour vos IDLs onchain. Cela augmente légèrement la taille du programme, c'est pourquoi le program metadata program a été créé. Dans le program metadata program, tous les IDLs de programme et les informations security.txt comme le nom, le contact et l'icône sont stockés dans des PDAs du program metadata program.

Compte IDL Anchor

Anchor sauvegarde les IDLs onchain dans un PDA de votre programme.

Les IDLs peuvent être téléversés onchain vers le compte IDL Anchor.
Cela permet aux explorateurs, aux wallets et aux SDK de récupérer l'IDL directement depuis Solana.

Première fois (initialisation du compte IDL) :

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

Mises à jour (mises à jour ultérieures par l'autorité) :

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

Commandes utiles associées :

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>

Notez que par défaut, la génération du compte IDL Anchor est sans permission. Téléversez donc votre IDL dès que possible, puis définissez une autorité.

Vous pouvez en savoir plus sur le compte IDL Anchor dans la documentation Anchor.

Program Metadata Program (PMP)

Le program metadata program est un programme qui vous permet de stocker les IDLs de programme et les informations security.txt comme le nom, le contact et l'icône onchain. Ce sera probablement la méthode standard pour stocker les IDLs onchain à l'avenir.

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

Vous pouvez en savoir plus sur le program metadata program dans la documentation du program metadata program.

Remarque : à la date de la dernière mise à jour de cet article, le PMP n'est pas encore pris en charge par tous les explorateurs.

Bonnes pratiques

La meilleure pratique pour le déploiement de programmes est d'utiliser un Multisig comme Squads et pour rendre ce processus aussi simple que possible, vous utilisez les workflows GitHub Actions de Solana.

Ainsi, le programme sera automatiquement mis à niveau, l'IDL téléversé, le build vérifié, puis une transaction sera proposée pour que votre multisig la signe et déploie le programme.

Maintenez les IDLs à jour → Mettez toujours à jour l'IDL lorsque vous apportez des modifications à votre programme.
Téléversez les IDLs onchain → pour la transparence et la prise en charge des outils.
Documentez les erreurs personnalisées → améliore l'UX pour les clients.
Vérifiez les builds → assurez-vous que l'IDL correspond au programme déployé.

Gestion des versions des IDLs

Actuellement avec Anchor, vous ne pouvez avoir qu'une seule version de l'IDL onchain à la fois. Cela signifie que si vous souhaitez apporter des modifications à votre programme, vous devez téléverser une nouvelle version de l'IDL, de préférence en même temps que vous mettez à niveau le programme. Cela peut entraîner des problèmes si les clients ne sont pas encore mis à jour, et c'est l'une des craisons pour lesquelles le program metadata program a été créé. Avec le PMP, vous pourrez disposer de différentes seeds pour votre programme et gérer les versions de cette façon. La conception de ce mécanisme n'est pas encore totalement finalisée et reste ouverte à la discussion.

Pour aller plus loin

Documentation Anchor sur les IDLs → génère automatiquement les IDLs et les clients. (TypeScript, C#, Python)
Codama → outillage IDL + générateurs de clients (Rust, JS/TS, Umi/Kit, etc.).
Program Metadata Program → stockez les IDLs et les informations security.txt onchain.

Voilà les bases des IDLs sur Solana. Ils constituent le pont entre les programmes onchain et les clients off-chain, permettant le riche écosystème d'outils et de SDK que vous connaissez aujourd'hui.

IDL - une interface de programme facile à utiliser