IDL (Interface Definition Language)

IDL sta per 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, offrendo inoltre 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 per gli sviluppatori → Genera automaticamente 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 uno 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 degli eventi Anchor o 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)
  );
});

Puoi ad esempio emettere eventi Anchor nel tuo programma e poi registrarli, scriverli in un database o usarli per inviare un messaggio in una 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(),
});

Per farlo puoi usare gli helper JS di Solana per analizzare gli eventi. Ecco un' implementazione di esempio che utilizza gli eventi Anchor per pubblicare messaggi in una chat Telegram.

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. Basta trovare un programma con cui vuoi interagire, scaricare l'IDL e poi generare un client nel linguaggio che preferisci.

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 on-chain.
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 (pre-0.30) utilizzavano campi come name, version al livello superiore e isMut/isSigner negli account. Puoi convertire gli IDL legacy usando anchor idl convert o ricompilando con Anchor v0.30+. Se hai bisogno di convertire al volo un IDL legacy nella nuova specifica puoi anche usare questo codice di conversione. Ciò è 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 usare 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 saperne di più su come interagire con un client C# da Unity nel preset per i giochi Solana o nella documentazione Games.

Client Python

Per Python puoi usare la libreria AnchorPy.

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

IDL senza Anchor

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

Uno strumento chiamato Codama è attualmente in fase di 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 (oppure usa anchor idl convert per i progetti legacy).
Finché le macro di Codama non saranno completamente pronte, puoi anche usare 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 di intelligenza artificiale come Cursor possono aiutarti a scrivere l'IDL, ma dovresti sempre verificarlo rispetto al codice sorgente del programma; il metodo migliore rimane l'uso di Anchor, Codama o Metaplex Shank.

Archiviazione degli IDL on-chain

Esistono due modi per caricare gli IDL on-chain. Il più usato e standard è il Anchor IDL account. Il modo in cui Anchor ti consente di caricare i tuoi IDL on-chain è aggiungendo istruzioni aggiuntive al tuo programma che ti permettono di caricare e aggiornare i tuoi IDL on-chain. 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 nei PDA del program metadata program.

Anchor IDL Account

Anchor salva gli IDL on-chain in un PDA del tuo programma.

Gli IDL possono essere caricati on-chain sull'Anchor IDL account.
Questo consente a explorer, wallet e SDK di recuperare l'IDL direttamente da Solana.

Prima volta (inizializzazione dell'IDL account):

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>

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

Puoi saperne di più sull'Anchor IDL account nella documentazione di Anchor.

Program Metadata Program (PMP)

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

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

Puoi saperne di più sul program metadata program nella documentazione del program metadata program.

Nota: all'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, usare i workflow GitHub Actions di Solana.

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

Mantieni gli IDL aggiornati → Aggiorna sempre l'IDL quando apporti modifiche al tuo programma.
Carica gli IDL on-chain → 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.

Versionamento degli IDL

Attualmente con Anchor puoi avere solo una versione dell'IDL on-chain alla volta. Ciò significa che se vuoi apportare modifiche al tuo programma devi caricare una nuova versione dell'IDL, preferibilmente contemporaneamente all'aggiornamento del programma. Questo può causare problemi se i client non sono ancora stati aggiornati ed è uno dei motivi per cui è stato sviluppato il program metadata program. Con il PMP, sarà possibile avere diversi seed per il tuo programma e gestire il versionamento in questo modo. Il design per questa funzionalità non è ancora 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 on-chain.

Queste sono le basi degli IDL su Solana. Sono il ponte tra i programmi on-chain e i client off-chain, che abilitano il ricco ecosistema di strumenti e SDK che vediamo oggi.

IDL - un'interfaccia di programma facile da usare