IDLs (Interface Definition Language)

IDL signifie Interface Definition Language.
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 lire son code source.
Lisibilité → Tout le monde peut lire les instructions de 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écodage des instructions et des 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 de Solana Explorer. Dans cette transaction vous pouvez voir l'instruction décodée pour un jeu 2048, incluant 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.

Analyse des événements Anchor ou des 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)
  );
});

Vous pouvez par exemple émettre des événements Anchor dans votre programme, puis enregistrer ces événements, les écrire dans une base de données ou les utiliser pour, par exemple, envoyer un message dans un chat Telegram.

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

Pour cela, vous pouvez utiliser les helpers Solana JS pour analyser les événements. Voici un exemple d'implémentation qui utilise des événements Anchor pour publier des messages dans un chat Telegram.

Décoder les transactions

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

Construire 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 de générer un client dans le langage de votre choix.

Voici un exemple de génération d'un client en TypeScript.

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'identifiant 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 compte 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 tels que name et version au niveau supérieur, ainsi que isMut/isSigner dans les comptes. Vous pouvez convertir les IDLs legacy à l'aide de 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. Ceci 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.

Ensuite, dans votre client (TypeScript, v0.30+), vous pouvez appeler les instructions de programme et récupérer les comptes aussi facilement 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 manuellement (formats Anchor ou Codama), mais ce n'est pas très fiable. Les outils d'IA comme Cursor peuvent vous aider à écrire l'IDL, mais vous devez 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 téléverser des IDLs onchain. La plus utilisée et la plus standard est le Anchor IDL account. La façon dont Anchor vous permet de téléverser 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 ajoute une taille supplémentaire au 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 telles que le nom, le contact et l'icône sont stockés dans des PDAs du program metadata program.

Anchor IDL Account

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

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

Première fois (initialisation du Anchor IDL account) :

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 Anchor IDL account 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 Anchor IDL account 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 telles que 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 les déploiements de programmes est d'utiliser un Multisig comme Squads et, pour rendre ce processus aussi simple que possible, d'utiliser les workflows GitHub Actions Solana.

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

Maintenir les IDLs à jour → Mettez toujours à jour l'IDL lorsque vous apportez des modifications à votre programme.
Téléverser les IDLs onchain → pour la transparence et la prise en charge des outils.
Documenter les erreurs personnalisées → améliore l'UX pour les clients.
Vérifier 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, ce qui est l'une des raisons pour lesquelles le program metadata program a été développé. Avec le PMP, vous pourrez utiliser différentes seeds pour votre programme et gérer le versionnage de cette manière. La conception finale n'est pas encore complètement arrêtée et reste ouverte à la discussion.

Pour aller plus loin

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

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

IDL - une interface de programme facile à utiliser