IDL (Interface Definition Language)

IDL to skrót od Interface Definition Language (język definicji interfejsu).
Na Solanie IDL-e to pliki JSON opisujące interfejs programu. Umożliwiają eksplorerą i użytkownikom dekodowanie instrukcji programu, danych kont oraz błędów programu, a także oferują możliwość generowania klientów w różnych językach programowania.

Dlaczego IDL-e są ważne

Standaryzacja → Wspólny format dla interfejsów programów.
Doświadczenie dewelopera → Automatyczne generowanie SDK klienta.
Kompozycyjność → Inni deweloperzy mogą wchodzić w interakcję z Twoim programem bez konieczności czytania jego kodu źródłowego.
Czytelność → Każdy może odczytać instrukcje programu i dane kont w explorerach bez czytania kodu źródłowego programu.

Co możesz robić z IDL-ami

Dekodowanie instrukcji i danych kont

Wszystkie eksplorery używają IDL-i programów do dekodowania instrukcji i danych kont. Tutaj możesz zobaczyć przykład Anchor 0.30.1 oraz Legacy IDL w interfejsie Solana Explorer. W tej transakcji możesz zobaczyć zdekodowaną instrukcję dla gry 2048, w tym pushInDirection oraz jej kierunek.

Możesz dekodować instrukcje i dane kont w swoim kliencie TypeScript, używając pomocników Solana JS.

Parsowanie zmian konta

Możesz łatwo subskrybować zmiany konta w swoim programie, korzystając z wygenerowanych typów TypeScript.

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

Definicje zdarzeń, subskrypcje, dekodowanie logów i CPI, backfille, wersjonowanie schematów oraz testowanie znajdziesz w Anchor Events.

Dekodowanie transakcji

Możesz również dekodować transakcje w swoim kliencie, korzystając z pomocników Solana JS. Da Ci to typowany obiekt całej transakcji.

Zbuduj własnego klienta

Używając IDL-a możesz stworzyć własnego klienta w wielu językach. Wystarczy znaleźć program, z którym chcesz wchodzić w interakcję, pobrać IDL i wygenerować klienta w preferowanym języku.

Oto przykład tego, jak wygenerować klienta w TypeScript.

IDL-e w Anchor

Jeśli używasz frameworka Anchor:

IDL jest automatycznie generowany podczas budowania programu.
Znajduje się w target/idl/<program>.json.
Typy TypeScript są generowane w target/types/<program>.ts.
Adres programu jest przechowywany w IDL (idl.address).

anchor build
cat target/idl/counter.json

Anatomia IDL-a

Oto minimalny przykład (specyfikacja 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: identyfikator programu onchain.
metadata: { name, version, spec, ... } dotyczące programu/interfejsu.
instructions: wywoływalne metody z polami accounts, args i discriminator.
accounts: typy kont udostępniane przez program (z dyskryminatorami).
types: aliasy struct/enum/type przywoływane przez instrukcje/konta.
events / errors / constants: opcjonalne definicje zdarzeń, kodów błędów i stałych.

Uwaga: Anchor v0.30 wprowadził nową specyfikację IDL. Starsze IDL-e (pre-0.30) używały pól takich jak name, version na najwyższym poziomie oraz isMut/isSigner w kontach. Możesz konwertować starsze IDL-e za pomocą anchor idl convert lub przebudować je z Anchor v0.30+. Jeśli potrzebujesz skonwertować starszy IDL do nowej specyfikacji w locie, możesz również użyć tego kodu konwersji. Jest to przydatne na przykład, gdy utrzymujesz eksplorer Solany i chcesz zachować wsteczną kompatybilność.

Klient TypeScript

Anchor automatycznie wygeneruje dla Ciebie również klienta TypeScript. Możesz znaleźć wygenerowanego klienta w folderze target/types.

Następnie w swoim kliencie (TypeScript, v0.30+) możesz wywoływać instrukcje programu i pobierać konta tak łatwo jak poniżej:

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

Klient C#

Aby wygenerować klienta C#, możesz użyć następującego polecenia:

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

Więcej o tym, jak wchodzić w interakcję z klientem C# z poziomu Unity, możesz przeczytać w presecie gier Solana lub w dokumentacji gier.

Klient Python

Dla Pythona możesz użyć biblioteki AnchorPy.

W przyszłości dostępnych będzie więcej generatorów klientów opartych na rendererach Codama.

IDL-e bez Anchor

Nie wszystkie programy są zbudowane przy użyciu Anchor.
Dla natywnych programów Solany:

Narzędzie o nazwie Codama jest obecnie w fazie rozwoju – służy do generowania IDL-i z Rusta za pomocą makr lub przez konwersję IDL-i Anchor. Oto przykład w trakcie prac dotyczący makr Codama do generowania IDL Codama. Codama konwertuje IDL-e Anchor/Shank do formatu IDL Codama. Aby uzyskać IDL Anchor, wygeneruj go przy użyciu Anchor (lub użyj anchor idl convert dla starszych projektów).
Do czasu, gdy makra Codama będą w pełni gotowe, możesz również użyć Metaplex Shank, aby wygenerować IDL Shank, a następnie przekonwertować go na IDL Codama.
Możesz również napisać IDL ręcznie (w formacie Anchor lub Codama), jednak nie jest to zbyt niezawodne. Narzędzia AI, takie jak Cursor, mogą pomóc w napisaniu IDL-a, ale zawsze powinieneś weryfikować IDL z kodem źródłowym programu – lepszym podejściem jest użycie Anchor, Codama lub Metaplex Shank.

Przechowywanie IDL-i w łańcuchu

Istnieją dwa sposoby przesyłania IDL-i onchain. Najczęściej stosowanym i standardowym jest konto IDL Anchor. Anchor umożliwia przesyłanie IDL-i onchain poprzez dodanie dodatkowych instrukcji do programu, które pozwalają przesyłać i aktualizować IDL-e onchain. Powoduje to pewne zwiększenie rozmiaru programu, dlatego powstał program metadanych programu. W programie metadanych programu wszystkie IDL-e programów oraz informacje security.txt, takie jak nazwa, kontakt i ikona, są przechowywane w PDA-ch programu metadanych programu.

Konto IDL Anchor

Anchor zapisuje IDL-e onchain w PDA Twojego programu.

IDL-e mogą być przesyłane onchain do konta IDL Anchor.
Dzięki temu eksplorery, portfele i SDK mogą pobierać IDL bezpośrednio z Solany.

Pierwsze użycie (inicjalizacja konta IDL):

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

Aktualizacje (kolejne zmiany przez uprawniony podmiot):

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

Przydatne powiązane polecenia:

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>

Domyślnie generowanie konta IDL Anchor jest bezuprawnieniowe. Dlatego prześlij swój IDL jak najszybciej, a następnie ustaw uprawnienia.

Więcej o koncie IDL Anchor możesz przeczytać w dokumentacji Anchor.

Program Metadanych Programu (PMP)

Program metadanych programu to program umożliwiający przechowywanie IDL-i programów oraz informacji security.txt, takich jak nazwa, kontakt i ikona, onchain. Prawdopodobnie będzie to standardowy sposób przechowywania IDL-i onchain w przyszłości.

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

Więcej o programie metadanych programu możesz przeczytać w dokumentacji programu metadanych programu.

Uwaga: Na dzień ostatniej aktualizacji artykułu PMP nie jest jeszcze obsługiwany przez wszystkie eksplorery.

Najlepsze praktyki

Najlepszą praktyką przy wdrażaniu programów jest użycie Multisig, takiego jak Squads, a aby maksymalnie uprościć ten proces, należy wykorzystać workflow GitHub Actions dla Solany.

Dzięki temu program zostanie automatycznie zaktualizowany, IDL przesłany, build zweryfikowany, a następnie zostanie zaproponowana transakcja do podpisania i wdrożenia programu przez Twój multisig.

Aktualizuj IDL-e na bieżąco → Zawsze aktualizuj IDL przy wprowadzaniu zmian w programie.
Przesyłaj IDL-e onchain → dla przejrzystości i wsparcia narzędziowego.
Dokumentuj własne błędy → poprawia UX dla klientów.
Weryfikuj buildy → upewnij się, że IDL odpowiada wdrożonemu programowi.

Wersjonowanie IDL-i

Aktualnie w Anchor można mieć tylko jedną wersję IDL-a onchain w danym momencie. Oznacza to, że jeśli chcesz wprowadzić zmiany w programie, musisz przesłać nową wersję IDL-a, najlepiej jednoczenie z aktualizacją programu. Może to powodować problemy, gdy klienci nie zostali jeszcze zaktualizowani, i jest jednym z powodów, dla których powstał program metadanych programu. Dzięki PMP będzie można stosować różne ziarna (seeds) dla programu i w ten sposób prowadzić wersjonowanie. Projekt w tym zakresie nie jest jeszcze ostatecznie ustalony i pozostaje otwarty na dyskusję.

Dalsza lektura

Dokumentacja Anchor o IDL-ach → automatyczne generowanie IDL-i i klientów (TypeScript, C#, Python).
Codama → narzędzia IDL i generatory klientów (Rust, JS/TS, Umi/Kit, itp.).
Program Metadanych Programu → przechowywanie IDL-i oraz informacji security.txt onchain.

To są podstawy IDL-i na Solanie. Stanowią one most między programami onchain a klientami off-chain, umożliwiając bogaty ekosystem narzędzi i SDK, który widzimy dzisiaj.

IDL – łatwy w użyciu interfejs programu