IDL – prosty w użyciu interfejs programu

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ą eksploratorom i użytkownikom dekodowanie instrukcji programu, danych kont i 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 dla klientów.
• Kompozycyjność → Inni deweloperzy mogą wchodzić w interakcje z Twoim programem bez czytania jego kodu źródłowego.
• Czytelność → Każdy może odczytać instrukcje programu i dane kont w eksploratorach bez czytania kodu źródłowego programu.

Co można robić z IDL-ami

Dekodowanie instrukcji i danych kont

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

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

Parsowanie zdarzeń Anchor lub zmian kont

Możesz łatwo subskrybować zmiany kont w swoim programie, używając 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)
  );
});

Możesz na przykład emitować zdarzenia Anchor w swoim programie, a następnie je logować, zapisywać w bazie danych lub wykorzystywać do wysyłania wiadomości na czat 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(),
});

W tym celu możesz użyć pomocników Solana JS do parsowania zdarzeń. Oto przykładowa implementacja, która wykorzystuje zdarzenia Anchor do publikowania wiadomości na czacie Telegram.

Dekodowanie transakcji

Możesz również dekodować transakcje w swoim kliencie, używając pomocników Solana JS. Dzięki temu otrzymasz 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 interakcje, pobrać IDL, a następnie wygenerować klienta w preferowanym języku.

Oto przykład generowania 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-u (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 w łańcuchu (onchain program ID).
• metadata: { name, version, spec, ... } – informacje o programie/interfejsie.
• instructions: wywoływalne metody zawierające accounts, args oraz discriminator.
• accounts: typy kont eksponowane przez program (z dyskryminatorami).
• types: aliasy struct/enum/typów używane w instrukcjach i kontach.
• 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 (przed wersją 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 na nową specyfikację w locie, możesz również użyć tego kodu konwersji. Jest to przydatne na przykład, jeśli utrzymujesz eksplorator Solany i chcesz zachować wsteczną kompatybilność.

Klient TypeScript

Anchor automatycznie wygeneruje dla Ciebie również klienta TypeScript. Wygenerowanego klienta można znaleźć w folderze target/types.

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

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 interakcje z klientem C# z Unity, możesz przeczytać w presecie gier Solana lub w dokumentacji gier.

Klient Python

W przypadku Pythona możesz użyć biblioteki AnchorPy.

Więcej generatorów klientów będzie dostępnych w przyszłości za pomocą rendererów Codama.

IDL-e bez Anchor

Nie wszystkie programy są budowane z użyciem Anchor.
Dla natywnych programów Solany:

• Narzędzie o nazwie Codama jest obecnie w trakcie tworzenia, aby generować IDL-e z kodu Rust za pomocą makr lub poprzez konwersję IDL-i Anchor. Oto przykład w trakcie realizacji makr Codama do generowania IDL Codama. Codama konwertuje IDL-e Anchor/Shank na IDL Codama. Aby uzyskać IDL Anchor, wygeneruj go za pomocą Anchor (lub użyj anchor idl convert dla starszych projektów).
• Do momentu gdy makra Codama będą w pełni gotowe, możesz również użyć Metaplex Shank, aby wygenerować IDL Shank, a następnie skonwertować go na IDL Codama.
• Możesz również pisać IDL ręcznie (w formacie Anchor lub Codama), ale nie jest to zbyt wiarygodne. Narzędzia AI, takie jak Cursor, mogą Ci pomóc w pisaniu IDL-a, jednak zawsze powinieneś weryfikować IDL z kodem źródłowym programu – lepszym sposobem jest użycie Anchor, Codama lub Metaplex Shank.

Przechowywanie IDL-i w łańcuchu (On-Chain)

Istnieją dwa sposoby przesyłania IDL-i do łańcucha. Najczęściej używanym i standardowym jest konto IDL Anchor. Anchor umożliwia przesyłanie IDL-i do łańcucha poprzez dodanie dodatkowych instrukcji do programu, pozwalających na przesyłanie i aktualizowanie IDL-i w łańcuchu. Dodaje to nieco dodatkowego rozmiaru do programu i dlatego właśnie powstał program metadata program. W program metadata program wszystkie IDL-e programów oraz informacje security.txt, takie jak nazwa, kontakt i ikona, są przechowywane w PDA program metadata program.

Konto IDL Anchor

Anchor zapisuje IDL-e w łańcuchu w PDA Twojego programu.

• IDL-e mogą być przesyłane do łańcucha na konto IDL Anchor.
• Dzięki temu eksploratory, portfele i SDK mogą pobierać IDL bezpośrednio z Solany.

Pierwsze uruchomienie (inicjalizacja konta IDL):

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

Aktualizacje (kolejne aktualizacje 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>

Należy pamiętać, że 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 Metadata Program (PMP)

Program metadata program to program umożliwiający przechowywanie IDL-i programów oraz informacji security.txt, takich jak nazwa, kontakt i ikona, w łańcuchu. Prawdopodobnie stanie się to standardowym sposobem przechowywania IDL-i w łańcuchu w przyszłości.

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

Więcej o program metadata program możesz przeczytać w dokumentacji program metadata program.

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

Najlepsze praktyki

Najlepszą praktyką przy wdrożeniach programów jest użycie Multisig, takiego jak Squads, a aby ten proces uczynić jak najprostszym, należy użyć przepływów pracy GitHub Actions dla Solany.

W ten sposób program będzie automatycznie aktualizowany, IDL przesyłany, build weryfikowany, a następnie zostanie zaproponowana transakcja do podpisania przez Twój multisig i wdrożenia programu.

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

Wersjonowanie IDL-i

Obecnie w Anchor można mieć tylko jedną wersję IDL-a w łańcuchu naraz. Oznacza to, że jeśli chcesz wprowadzić zmiany do swojego programu, musisz przesłać nową wersję IDL-a, najlepiej jednocześnie z aktualizacją programu. Może to prowadzić do problemów, jeśli klienci nie zostali jeszcze zaktualizowani – i jest to jeden z powodów, dla których powstał program metadata program. Dzięki PMP będziesz mógł używać różnych seedów dla swojego programu i w ten sposób realizować wersjonowanie. Projekt w tym zakresie nie jest jeszcze ostatecznie ustalony i jest otwarty na dyskusję.

Dalsza lektura

• Dokumentacja Anchor dotycząca IDL-i → 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 Metadata Program → przechowywanie IDL-i oraz informacji security.txt w łańcuchu.

To są podstawy IDL-i na Solanie. Stanowią one pomost między programami w łańcuchu a klientami poza łańcuchem, umożliwiając bogaty ekosystem narzędzi i SDK, który widzimy dzisiaj.