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, Konten-Daten und Programmfehler zu dekodieren, und bieten die Möglichkeit, Clients in verschiedenen Programmiersprachen zu generieren.

Warum IDLs wichtig sind

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

Was Sie mit IDLs tun können

Dekodierung von Anweisungen und Konten-Daten

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

Sie können Anweisungen und Konten-Daten in Ihrem TypeScript-Client dekodieren, indem Sie die Solana JS Helpers verwenden.

Anchor-Events oder Konten-Änderungen parsen

Sie können Konten-Änderungen in Ihrem Programm ganz einfach abonnieren, indem Sie die generierten TypeScript-Typen verwenden.

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

Sie können zum Beispiel Anchor-Events in Ihrem Programm ausgeben und diese Events dann protokollieren, in einer Datenbank speichern oder verwenden, um beispielsweise eine Nachricht in einen Telegram-Chat zu senden.

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

Dazu können Sie die Solana JS Helpers verwenden, um die Events zu parsen. Hier ist eine Beispielimplementierung, die Anchor-Events verwendet, um Nachrichten in einen Telegram-Chat zu posten.

Transaktionen dekodieren

Sie können Transaktionen auch in Ihrem Client dekodieren, indem Sie die Solana JS Helpers verwenden. Dies liefert Ihnen 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 in 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 onchain Programm-ID.
metadata: { name, version, spec, ... } über das Programm/die Schnittstelle.
Anweisungen: aufrufbare Methoden mit accounts, args und einem discriminator.
accounts: vom Programm bereitgestellte Konten-Typen (mit Discriminators).
types: Struct/Enum/Typ-Aliase, die von Anweisungen/Konten referenziert werden.
events / errors / constants: optionale Definitionen für Events, Fehlercodes und 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 bauen. Wenn Sie eine Legacy-IDL im Handumdrehen 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 pflegen und Abwärtskompatibilität gewährleisten möchten.

TypeScript-Client

Anchor generiert außerdem 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 man mit einem C#-Client aus Unity interagiert, 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 gebaut.
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 Macros zur Generierung einer Codama-IDL. Codama konvertiert Anchor/Shank-IDLs in eine Codama-IDL. Um eine Anchor-IDL zu erhalten, generieren Sie sie mit Anchor (oder verwenden Sie anchor idl convert für Legacy-Projekte).
Bis die Codama-Makros vollständig bereit 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 (Anchor- oder Codama-Format), aber das ist nicht sehr zuverlässig. KI-Tools wie Cursor können Ihnen beim Schreiben der IDL helfen, aber Sie sollten die IDL immer mit dem Programm-Quellcode überprüfen. Der bessere Weg ist die Verwendung von Anchor, Codama oder Metaplex Shank.

IDLs onchain speichern

Es gibt zwei Möglichkeiten, IDLs onchain hochzuladen. Die am häufigsten verwendete und standardisierte ist das Anchor IDL-Konto. Wie Anchor es Ihnen ermöglicht, Ihre IDLs onchain hochzuladen, ist durch das Hinzufügen zusätzlicher Anweisungen zu Ihrem Programm, die es Ihnen erlauben, Ihre IDLs onchain hochzuladen und zu aktualisieren. Dies fügt dem Programm etwas zusätzliche Größe hinzu, weshalb das program account-Metadaten-Programm erstellt wurde. Im program account-Metadaten-Programm werden alle Programm-IDLs und security.txt-Informationen wie Name, Kontakt und Symbol in PDAs des program account-Metadaten-Programms gespeichert.

Anchor IDL-Konto

Anchor speichert IDLs onchain in einer PDA Ihres Programms.

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

Erstmalige Nutzung (IDL-Konto initialisieren):

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

Aktualisierungen (nachfolgende Updates durch die Autorität):

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

Nützliche zugehörige 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 Generierung des Anchor IDL-Kontos standardmäßig ohne Genehmigung erfolgt. Laden Sie Ihre IDL daher 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 program account-Metadaten-Programm ist ein Programm, mit dem Sie die Programm-IDLs und security.txt-Informationen wie Name, Kontakt und Symbol onchain speichern können. Dies wird wahrscheinlich der Standardweg sein, IDLs onchain in der Zukunft zu speichern.

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

Mehr über das program account-Metadaten-Programm erfahren Sie in der Dokumentation des program account-Metadaten-Programms.

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

Best Practices

Die beste Praxis für Programm-Deployments ist die Verwendung eines Multisigs wie Squads. 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 onchain 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 deploymenten Programm übereinstimmt.

IDL-Versionierung

Derzeit können Sie mit Anchor jeweils nur eine Version der IDL onchain haben. Das bedeutet, dass Sie beim Vornehmen von Änderungen an Ihrem Programm eine neue Version der IDL hochladen müssen, vorzugsweise gleichzeitig mit dem Programm-Upgrade. Dies kann zu Problemen führen, wenn die Clients noch nicht aktualisiert wurden, und ist ein Grund, warum das program account-Metadaten-Programm entwickelt wurde. Mit PMP werden Sie verschiedene Seeds für Ihr Programm verwenden und so eine Versionierung vornehmen können. Das Design dafür ist noch nicht vollständig abgeschlossen und offen für Diskussionen.

Weiterführende Literatur

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

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

IDL – eine einfach zu verwendende Programmschnittstelle