IDL (Interface Definition Language)

IDL è l'acronimo di Interface Definition Language. Su Solana, gli IDL sono file JSON che descrivono l'interfaccia di un programma. Consentono a explorer e utenti di decodificare le istruzioni del programma, i dati degli account e gli errori del programma, e offrono la possibilità di generare client in diversi linguaggi di programmazione.

Perché gli IDL sono importanti

Standardizzazione → Un formato condiviso per le interfacce dei programmi.
Esperienza degli sviluppatori → Genera automaticamente gli SDK client.
Componibilità → Altri sviluppatori possono interagire con il tuo programma senza leggerne il codice sorgente.
Leggibilità → Chiunque può leggere le istruzioni del programma e i dati degli account negli explorer senza leggere il codice sorgente del programma.

Cosa puoi fare con gli IDL

Decodifica di istruzioni e dati degli account

Tutti gli Explorer utilizzano gli IDL dei programmi per decodificare istruzioni e dati degli account. Qui puoi vedere un esempio di Anchor 0.30.1 e di Legacy IDL nell'interfaccia utente di Solana Explorer. In questa transazione puoi vedere l'istruzione decodificata per un gioco 2048, inclusa pushInDirection e la sua direzione.

Puoi decodificare istruzioni e dati degli account nel tuo client TypeScript utilizzando gli helper JS di Solana.

Analisi delle modifiche agli account

Puoi facilmente sottoscrivere le modifiche agli account nel tuo programma utilizzando i tipi TypeScript generati.

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

Per le definizioni di eventi, sottoscrizioni, decodifica di log e CPI, backfill, versioning degli schemi e test, consulta Anchor Events.

Decodifica delle transazioni

Puoi anche decodificare le transazioni nel tuo client utilizzando gli helper JS di Solana. Questo ti fornirà un oggetto tipizzato dell'intera transazione.

Costruisci il tuo client

Utilizzando un IDL puoi creare il tuo client in molti linguaggi. Trova semplicemente un programma con cui vuoi interagire, scarica l'IDL e potrai generare un client nel tuo linguaggio preferito.

Ecco un esempio di come generare un client in TypeScript.

IDL in Anchor

Se stai utilizzando il framework Anchor:

L'IDL viene generato automaticamente quando compili il tuo programma.
Si trova in target/idl/<program>.json.
I tipi TypeScript vengono generati in target/types/<program>.ts.
L'indirizzo del programma è memorizzato nell'IDL (idl.address).

anchor build
cat target/idl/counter.json

Anatomia di un IDL

Ecco un esempio minimale (specifiche 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 del programma onchain.
metadata: { name, version, spec, ... } informazioni sul programma/interfaccia.
instructions: metodi richiamabili con accounts, args e un discriminator.
accounts: tipi di account esposti dal programma (con discriminatori).
types: alias di struct/enum/tipo referenziati da istruzioni/account.
events / errors / constants: definizioni opzionali per eventi, codici di errore e costanti.

Nota: Anchor v0.30 ha introdotto una nuova specifica IDL. Gli IDL legacy (precedenti alla v0.30) utilizzavano campi come name, version al livello superiore e isMut/isSigner negli account. Puoi convertire gli IDL legacy utilizzando anchor idl convert o ricompilandoli con Anchor v0.30+. Se hai bisogno di convertire un IDL legacy nella nuova specifica al volo, puoi anche utilizzare questo codice di conversione. Questo è utile ad esempio se gestisci un explorer Solana e vuoi mantenere la compatibilità con le versioni precedenti.

Client TypeScript

Anchor genererà automaticamente anche un client TypeScript per te. Puoi trovare il client generato nella cartella target/types.

Poi nel tuo client (TypeScript, v0.30+) puoi chiamare le istruzioni del programma e recuperare gli account in modo semplice come questo:

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#

Per generare un client C# puoi utilizzare il seguente comando:

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

Puoi leggere ulteriori informazioni su come interagire con un client C# da Unity nel preset per giochi Solana o nella documentazione Games.

Client Python

Per Python puoi utilizzare la libreria AnchorPy.

Ulteriori generatori di client saranno disponibili tramite i renderer Codama in futuro.

IDL senza Anchor

Non tutti i programmi sono costruiti con Anchor. Per i programmi Solana nativi:

Uno strumento chiamato Codama è attualmente in sviluppo per generare IDL da Rust tramite macro o convertendo IDL Anchor. Ecco un esempio in corso di Codama Macros per generare un IDL Codama. Codama converte gli IDL Anchor/Shank in un IDL Codama. Per ottenere un IDL Anchor, generalo con Anchor (o usa anchor idl convert per i progetti legacy).
Fino a quando le macro Codama non saranno completamente pronte, puoi anche utilizzare Metaplex Shank per generare un IDL Shank, poi convertirlo in un IDL Codama.
Puoi anche scrivere l'IDL a mano (nei formati Anchor o Codama), ma questo non è molto affidabile. Strumenti AI come Cursor possono aiutarti a scrivere l'IDL, ma dovresti sempre verificarlo rispetto al codice sorgente del programma; il modo migliore è utilizzare Anchor, Codama o Metaplex Shank.

Archiviazione degli IDL on-chain

Ci sono due modi per caricare gli IDL onchain. Il più utilizzato e standard è l'account IDL di Anchor. Il modo in cui Anchor ti consente di caricare i tuoi IDL onchain è aggiungendo istruzioni aggiuntive al tuo programma che ti permettono di caricare e aggiornare i tuoi IDL onchain. Questo aggiunge una certa dimensione extra al programma ed è per questo che è stato creato il program metadata program. Nel program metadata program tutti gli IDL dei programmi e le informazioni security.txt come nome, contatto e icona sono memorizzati in PDA del program metadata program.

Account IDL di Anchor

Anchor salva gli IDL onchain in un PDA del tuo programma.

Gli IDL possono essere caricati onchain nell'account IDL di Anchor.
Questo consente a explorer, wallet e SDK di recuperare l'IDL direttamente da Solana.

Prima volta (inizializzazione dell'account IDL):

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

Aggiornamenti (aggiornamenti successivi da parte dell'autorità):

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

Comandi correlati utili:

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>

Tieni presente che per impostazione predefinita la generazione dell'account IDL di Anchor è senza permessi. Quindi carica il tuo IDL il prima possibile e poi imposta un'autorità.

Puoi leggere ulteriori informazioni sull'account IDL di Anchor nella documentazione di Anchor.

Program Metadata Program (PMP)

Il program metadata program è un programma che ti consente di memorizzare gli IDL dei programmi e le informazioni security.txt come nome, contatto e icona onchain. Questo diventerà probabilmente il modo standard per archiviare gli IDL onchain in futuro.

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

Puoi leggere ulteriori informazioni sul program metadata program nella documentazione del program metadata program.

Nota: al momento dell'ultimo aggiornamento dell'articolo, il PMP non è ancora supportato da tutti gli explorer.

Best practice

La best practice per i deploy dei programmi è utilizzare un Multisig come Squads e, per rendere questo processo il più semplice possibile, si utilizzano i workflow GitHub Actions di Solana.

In questo modo il programma verrà aggiornato automaticamente, l'IDL caricato, la build verificata e poi verrà proposta una transazione che il tuo multisig dovrà firmare e con cui distribuire il programma.

Mantieni gli IDL aggiornati → Aggiorna sempre l'IDL quando apporti modifiche al tuo programma.
Carica gli IDL onchain → per trasparenza e supporto agli strumenti.
Documenta gli errori personalizzati → migliora l'UX per i client.
Verifica le build → assicurati che l'IDL corrisponda al programma distribuito.

Versioning degli IDL

Attualmente con Anchor puoi avere solo una versione dell'IDL onchain alla volta. Ciò significa che se vuoi apportare modifiche al tuo programma devi caricare una nuova versione dell'IDL, preferibilmente nello stesso momento in cui aggiorni il programma. Questo può causare problemi se i client non sono ancora stati aggiornati ed è uno dei motivi per cui è stato creato il program metadata program. Con il PMP, potrai avere seed diversi per il tuo programma e gestire il versioning in questo modo. Il design per questo non è ancora completamente definitivo ed è aperto alla discussione.

Ulteriori letture

Documentazione Anchor sugli IDL → genera automaticamente IDL e client. (TypeScript, C#, Python)
Codama → strumenti IDL + generatori di client (Rust, JS/TS, Umi/Kit, ecc.).
Program Metadata Program → archivia IDL e informazioni security.txt onchain.

Questi sono i fondamenti degli IDL su Solana. Sono il ponte tra i programmi onchain e i client off-chain, abilitando il ricco ecosistema di strumenti e SDK che vediamo oggi.

IDL - un'interfaccia di programma semplice da usare