IDLs (Interface Definition Language)

IDL steht für Interface Definition Language. Auf Solana sind IDLs JSON-Dateien, die die Schnittstelle eines Programms beschreiben. Sie ermöglichen es Explorern und Nutzern, Programm-Anweisungen, Kontendaten und Programmfehler zu dekodieren, und bieten die Möglichkeit, Clients in verschiedenen Programmiersprachen zu generieren.

Warum IDLs wichtig sind

Standardisierung → Ein gemeinsames Format für Programmschnittstellen.
Entwicklererfahrung → Client-SDKs automatisch generieren.
Komposabilität → Andere Entwickler können mit Ihrem Programm interagieren, ohne den Quellcode lesen zu müssen.
Lesbarkeit → Jeder kann Programm-Anweisungen und Kontendaten in Explorern lesen, ohne den Quellcode des Programms zu kennen.

Was Sie mit IDLs tun können

Anweisungs- und Kontendaten dekodieren

Alle Explorer verwenden Programm-IDLs, um Anweisungen und Kontendaten zu dekodieren. Hier können Sie ein Anchor 0.30.1 und ein Legacy-IDL Beispiel in der Solana Explorer-Oberfläche sehen. In dieser Transaktion können Sie die dekodierte Anweisung für ein 2048-Spiel sehen, einschließlich pushInDirection und dessen Richtung.

Sie können Anweisungen und Kontendaten in Ihrem TypeScript-Client dekodieren, indem Sie die Solana JS-Hilfsfunktionen verwenden.

Kontenänderungen verfolgen

Sie können mit den generierten TypeScript-Typen ganz einfach Kontenänderungen in Ihrem Programm abonnieren.

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

Für Event-Definitionen, Abonnements, Log- und CPI-Dekodierung, Backfills, Schema-Versionierung und Tests siehe Anchor Events.

Transaktionen dekodieren

Sie können Transaktionen in Ihrem Client auch dekodieren, indem Sie die Solana JS-Hilfsfunktionen verwenden. Dadurch erhalten Sie ein typisiertes Objekt der gesamten Transaktion.

Eigenen Client erstellen

Mit einer IDL können Sie Ihren eigenen Client in vielen Sprachen erstellen. Sie suchen einfach ein Programm, mit dem Sie interagieren möchten, laden die IDL herunter und können dann einen Client in Ihrer bevorzugten Sprache generieren.

Hier ist ein Beispiel, wie man einen Client in TypeScript generiert.

IDLs in Anchor

Wenn Sie das Anchor-Framework verwenden:

Die IDL wird automatisch generiert, wenn Sie Ihr Programm bauen.
Sie befindet sich unter target/idl/<program>.json.
TypeScript-Typen werden in target/types/<program>.ts generiert.
Die Programm-Adresse ist in der IDL gespeichert (idl.address).

anchor build
cat target/idl/counter.json

Aufbau einer IDL

Hier ist ein minimales Beispiel (Anchor v0.30+ Spezifikation):

{
  "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: die Programm-ID on-chain.
metadata: { name, version, spec, ... } über das Programm/die Schnittstelle.
instructions: aufrufbare Methoden mit accounts, args und einem discriminator.
accounts: vom Programm bereitgestellte Kontentypen (mit Diskriminatoren).
types: Struct-/Enum-/Typ-Aliase, auf die in Anweisungen/Konten verwiesen wird.
events / errors / constants: optionale Definitionen für Events, Fehlercodes, Konstanten.

Hinweis: Anchor v0.30 hat eine neue IDL-Spezifikation eingeführt. Legacy-IDLs (vor 0.30) verwendeten Felder wie name, version auf oberster Ebene und isMut/isSigner in Konten. Sie können Legacy-IDLs mit anchor idl convert konvertieren oder mit Anchor v0.30+ neu erstellen. Wenn Sie eine Legacy-IDL spontan in die neue Spezifikation konvertieren müssen, können Sie auch diesen Konvertierungscode verwenden. Dies ist zum Beispiel nützlich, wenn Sie einen Solana Explorer betreiben und Rückwärtskompatibilität gewährleisten möchten.

TypeScript-Client

Anchor generiert auch automatisch einen TypeScript-Client für Sie. Den generierten Client finden Sie im Ordner target/types.

Dann können Sie in Ihrem Client (TypeScript, v0.30+) Programm-Anweisungen aufrufen und Konten so einfach wie folgt abrufen:

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

Um einen C#-Client zu generieren, können Sie folgenden Befehl verwenden:

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

Mehr darüber, wie Sie mit einem C#-Client in Unity interagieren, erfahren Sie im Solana Games Preset oder in der Games-Dokumentation.

Python-Client

Für Python können Sie die AnchorPy Bibliothek verwenden.

Weitere Client-Generatoren werden in Zukunft über Codama-Renderer verfügbar sein.

IDLs ohne Anchor

Nicht alle Programme werden mit Anchor erstellt. Für native Solana-Programme:

Ein Tool namens Codama befindet sich derzeit in der Entwicklung, um IDLs aus Rust über Makros zu generieren oder Anchor-IDLs zu konvertieren. Hier ist ein laufendes Beispiel für Codama-Makros zur Generierung einer Codama-IDL. Codama konvertiert Anchor/Shank-IDLs in eine Codama-IDL. Um eine Anchor-IDL zu erhalten, generieren Sie diese mit Anchor (oder verwenden Sie anchor idl convert für Legacy-Projekte).
Bis die Codama-Makros vollständig einsatzbereit sind, können Sie auch Metaplex Shank verwenden, um eine Shank-IDL zu generieren und diese dann in eine Codama-IDL zu konvertieren.
Sie können die IDL auch von Hand schreiben (im Anchor- oder Codama-Format), was jedoch nicht sehr zuverlässig ist. KI-Tools wie Cursor können Ihnen beim Schreiben der IDL helfen, aber Sie sollten die IDL immer anhand des Programm-Quellcodes überprüfen – die bessere Methode ist die Verwendung von Anchor, Codama oder Metaplex Shank.

IDLs On-Chain speichern

Es gibt zwei Möglichkeiten, IDLs on-chain hochzuladen. Die am häufigsten verwendete und standardmäßige ist das Anchor-IDL-Konto. Anchor ermöglicht das Hochladen Ihrer IDLs on-chain, indem zusätzliche Anweisungen zu Ihrem Programm hinzugefügt werden, die es Ihnen erlauben, Ihre IDLs on-chain hochzuladen und zu aktualisieren. Dies fügt dem Programm etwas zusätzliche Größe hinzu, weshalb das Programm-Metadaten-Programm entwickelt wurde. Im Programm-Metadaten-Programm werden alle Programm-IDLs und security.txt-Informationen wie Name, Kontakt und Icon in PDAs des Programm-Metadaten-Programms gespeichert.

Anchor-IDL-Konto

Anchor speichert IDLs on-chain in einer PDA Ihres Programms.

IDLs können on-chain in das Anchor-IDL-Konto hochgeladen werden.
Dies ermöglicht es Explorern, Wallets und SDKs, die IDL direkt von Solana abzurufen.

Erstmalig (IDL-Konto initialisieren):

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

Upgrades (nachfolgende Aktualisierungen durch die Autorität):

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

Nützliche verwandte Befehle:

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>

Beachten Sie, dass die Erstellung des Anchor-IDL-Kontos standardmäßig ohne Genehmigung erfolgt. Laden Sie daher Ihre IDL so schnell wie möglich hoch und legen Sie dann eine Autorität fest.

Mehr über das Anchor-IDL-Konto erfahren Sie in der Anchor-Dokumentation.

Program Metadata Program (PMP)

Das Programm-Metadaten-Programm ist ein Programm, das es Ihnen ermöglicht, Programm-IDLs und security.txt-Informationen wie Name, Kontakt und Icon on-chain zu speichern. Dies wird wahrscheinlich in Zukunft die Standardmethode zur On-Chain-Speicherung von IDLs sein.

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

Mehr über das Programm-Metadaten-Programm erfahren Sie in der Dokumentation zum Programm-Metadaten-Programm.

Hinweis: Zum Zeitpunkt der letzten Aktualisierung dieses Artikels wird das PMP noch nicht von allen Explorern unterstützt.

Best Practices

Die beste Vorgehensweise für Programm-Deployments ist die Verwendung eines Multisig wie Squads, und um diesen Prozess so einfach wie möglich zu gestalten, verwenden Sie die Solana GitHub Actions Workflows.

So wird das Programm automatisch aktualisiert, die IDL hochgeladen, der Build verifiziert und anschließend eine Transaktion für Ihr Multisig zum Unterzeichnen und Deployment des Programms vorgeschlagen.

IDLs aktuell halten → Aktualisieren Sie die IDL immer, wenn Sie Änderungen an Ihrem Programm vornehmen.
IDLs on-chain hochladen → für Transparenz und Tool-Unterstützung.
Benutzerdefinierte Fehler dokumentieren → verbessert die UX für Clients.
Builds verifizieren → sicherstellen, dass die IDL mit dem bereitgestellten Programm übereinstimmt.

IDL-Versionierung

Derzeit können Sie mit Anchor nur eine Version der IDL gleichzeitig on-chain haben. Das bedeutet, dass Sie bei Änderungen an Ihrem Programm eine neue Version der IDL hochladen müssen, vorzugsweise zeitgleich mit dem Upgrade des Programms. Dies kann zu Problemen führen, wenn die Clients noch nicht aktualisiert wurden, und ist ein Grund, warum das Programm-Metadaten-Programm entwickelt wurde. Mit PMP werden Sie verschiedene Seeds für Ihr Programm verwenden und auf diese Weise eine Versionierung durchführen können. Das Design dafür ist noch nicht vollständig abgeschlossen und steht zur Diskussion.

Weiterführende Literatur

Anchor-Dokumentation zu IDLs → generiert IDLs und Clients automatisch. (TypeScript, C#, Python)
Codama → IDL-Tooling + Client- Generatoren (Rust, JS/TS, Umi/Kit, etc.).
Program Metadata Program → IDLs und security.txt-Informationen on-chain speichern.

Das sind die Grundlagen von IDLs auf Solana. Sie sind die Brücke zwischen On-Chain-Programmen und Off-Chain-Clients und ermöglichen das reiche Ökosystem an Tools und SDKs, das wir heute kennen.

IDL – eine einfach zu verwendende Programmschnittstelle