IDLs (Interface Definition Language)

IDL σημαίνει Interface Definition Language (Γλώσσα Ορισμού Διεπαφής).
Στο Solana, τα IDL είναι αρχεία JSON που περιγράφουν τη διεπαφή ενός προγράμματος. Επιτρέπουν σε explorers και χρήστες να αποκωδικοποιούν οδηγίες προγράμματος, δεδομένα λογαριασμών και σφάλματα προγράμματος, και προσφέρουν τη δυνατότητα δημιουργίας clients σε διαφορετικές γλώσσες προγραμματισμού.

Γιατί τα IDL έχουν σημασία

Τυποποίηση → Κοινή μορφή για διεπαφές προγραμμάτων.
Εμπειρία Προγραμματιστή → Αυτόματη δημιουργία client SDK.
Συνθεσιμότητα → Άλλοι προγραμματιστές μπορούν να αλληλεπιδράσουν με το πρόγραμμά σας χωρίς να διαβάσουν τον πηγαίο κώδικά του.
Αναγνωσιμότητα → Ο καθένας μπορεί να διαβάσει οδηγίες προγράμματος και δεδομένα λογαριασμών σε explorers χωρίς να διαβάζει τον πηγαίο κώδικα του προγράμματος.

Τι μπορείτε να κάνετε με τα IDL

Αποκωδικοποίηση Οδηγιών και Δεδομένων Λογαριασμών

Όλοι οι Explorers χρησιμοποιούν IDL προγραμμάτων για να αποκωδικοποιούν οδηγίες και δεδομένα λογαριασμών. Εδώ μπορείτε να δείτε ένα παράδειγμα Anchor 0.30.1 και ένα παράδειγμα Legacy IDL στο UI του Solana Explorer. Σε αυτή τη συναλλαγή μπορείτε να δείτε την αποκωδικοποιημένη οδηγία για ένα παιχνίδι 2048, συμπεριλαμβανομένου του pushInDirection και της κατεύθυνσής του.

Μπορείτε να αποκωδικοποιείτε οδηγίες και δεδομένα λογαριασμών στον TypeScript client σας χρησιμοποιώντας τα Solana JS helpers.

Παρακολούθηση αλλαγών λογαριασμού

Μπορείτε εύκολα να εγγραφείτε σε αλλαγές λογαριασμών στο πρόγραμμά σας χρησιμοποιώντας τους δημιουργημένους τύπους 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)
  );
});

Για ορισμούς συμβάντων, συνδρομές, αποκωδικοποίηση log και CPI, backfills, versioning σχήματος και δοκιμές, δείτε Anchor Events.

Αποκωδικοποίηση Συναλλαγών

Μπορείτε επίσης να αποκωδικοποιείτε συναλλαγές στον client σας χρησιμοποιώντας τα Solana JS helpers. Αυτό θα σας δώσει ένα typed αντικείμενο ολόκληρης της συναλλαγής.

Δημιουργήστε τον δικό σας client

Χρησιμοποιώντας ένα IDL μπορείτε να δημιουργήσετε τον δικό σας client σε πολλές γλώσσες. Απλώς βρίσκετε ένα πρόγραμμα με το οποίο θέλετε να αλληλεπιδράσετε, κατεβάζετε το IDL και στη συνέχεια μπορείτε να δημιουργήσετε έναν client στη γλώσσα της προτίμησής σας.

Εδώ υπάρχει ένα παράδειγμα για το πώς να δημιουργήσετε έναν client σε TypeScript.

IDL στο Anchor

Αν χρησιμοποιείτε το Anchor framework:

Το IDL δημιουργείται αυτόματα όταν κάνετε build το πρόγραμμά σας.
Βρίσκεται στο target/idl/<program>.json.
Οι τύποι TypeScript δημιουργούνται στο target/types/<program>.ts.
Η διεύθυνση του προγράμματος αποθηκεύεται στο IDL (idl.address).

anchor build
cat target/idl/counter.json

Ανατομία ενός IDL

Εδώ είναι ένα ελάχιστο παράδειγμα (προδιαγραφή 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: το onchain program ID.
metadata: { name, version, spec, ... } σχετικά με το πρόγραμμα/τη διεπαφή.
instructions: callable μέθοδοι με accounts, args και ένα discriminator.
accounts: τύποι λογαριασμών που εκθέτει το πρόγραμμα (με discriminators).
types: struct/enum/type aliases που αναφέρονται από instructions/accounts.
events / errors / constants: προαιρετικοί ορισμοί για συμβάντα, κωδικούς σφαλμάτων και σταθερές.

Σημείωση: Το Anchor v0.30 εισήγαγε νέα προδιαγραφή IDL. Τα Legacy IDL (πριν το 0.30) χρησιμοποιούσαν πεδία όπως name, version στο ανώτατο επίπεδο και isMut/isSigner στους λογαριασμούς. Μπορείτε να μετατρέψετε legacy IDL χρησιμοποιώντας anchor idl convert ή να κάνετε rebuild με Anchor v0.30+. Αν χρειαστεί να μετατρέψετε ένα legacy IDL στη νέα προδιαγραφή εν κινήσει, μπορείτε επίσης να χρησιμοποιήσετε αυτόν τον κώδικα μετατροπής. Αυτό είναι χρήσιμο για παράδειγμα αν συντηρείτε έναν solana explorer και θέλετε να διατηρήσετε συμβατότητα με παλαιότερες εκδόσεις.

TypeScript Client

Το Anchor θα δημιουργήσει επίσης αυτόματα έναν TypeScript client για εσάς. Μπορείτε να βρείτε τον δημιουργημένο client στον φάκελο target/types.

Στη συνέχεια, στον client σας (TypeScript, v0.30+) μπορείτε να καλείτε οδηγίες προγράμματος και να ανακτάτε λογαριασμούς τόσο απλά:

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

Για να δημιουργήσετε έναν C# client μπορείτε να χρησιμοποιήσετε την ακόλουθη εντολή:

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

Μπορείτε να διαβάσετε περισσότερα για το πώς να αλληλεπιδράτε με έναν C# client από το Unity στο Solana games preset ή στα Games docs.

Python Client

Για Python μπορείτε να χρησιμοποιήσετε τη βιβλιοθήκη AnchorPy.

Περισσότερες γεννήτριες client θα είναι διαθέσιμες μέσω Codama renderers στο μέλλον.

IDL χωρίς Anchor

Δεν είναι όλα τα προγράμματα κατασκευασμένα με Anchor.
Για native προγράμματα Solana:

Ένα εργαλείο που ονομάζεται Codama βρίσκεται επί του παρόντος υπό ανάπτυξη για τη δημιουργία IDL από Rust μέσω macros ή με μετατροπή Anchor IDL. Εδώ υπάρχει ένα παράδειγμα σε εξέλιξη Codama Macros για τη δημιουργία ενός Codama IDL. Το Codama μετατρέπει Anchor/Shank IDL σε Codama IDL. Για να αποκτήσετε ένα Anchor IDL, δημιουργήστε το με Anchor (ή χρησιμοποιήστε anchor idl convert για legacy projects).
Μέχρι να είναι πλήρως έτοιμα τα codama macros, μπορείτε επίσης να χρησιμοποιήσετε Metaplex Shank για να δημιουργήσετε ένα Shank IDL και στη συνέχεια να το μετατρέψετε σε Codama IDL.
Μπορείτε επίσης να γράψετε το IDL με το χέρι (σε μορφή Anchor ή Codama), αλλά αυτό δεν είναι πολύ αξιόπιστο. Εργαλεία AI όπως το Cursor μπορούν να σας βοηθήσουν να γράψετε το IDL, αλλά θα πρέπει πάντα να επαληθεύετε το IDL με τον πηγαίο κώδικα του προγράμματος· ο καλύτερος τρόπος είναι να χρησιμοποιείτε Anchor, Codama ή Metaplex Shank.

Αποθήκευση IDL On-Chain

Υπάρχουν δύο τρόποι για να ανεβάσετε IDL onchain. Ο πιο διαδεδομένος και πρότυπος είναι ο λογαριασμός Anchor IDL. Ο τρόπος που το Anchor σας επιτρέπει να ανεβάζετε τα IDL σας onchain είναι προσθέτοντας επιπλέον οδηγίες στο πρόγραμμά σας που σας επιτρέπουν να ανεβάζετε και να ενημερώνετε τα IDL σας onchain. Αυτό προσθέτει κάποιο επιπλέον μέγεθος στο πρόγραμμα και γι' αυτό δημιουργήθηκε το program metadata program. Στο program metadata program αποθηκεύονται όλα τα IDL προγραμμάτων και πληροφορίες security.txt όπως όνομα, επικοινωνία και εικονίδιο σε PDA του program metadata program.

Anchor IDL Account

Το Anchor αποθηκεύει τα IDL onchain σε ένα PDA του προγράμματός σας.

Τα IDL μπορούν να ανεβαστούν onchain στον Anchor IDL account.
Αυτό επιτρέπει σε explorers, wallets και SDK να ανακτούν το IDL απευθείας από το Solana.

Πρώτη φορά (αρχικοποίηση του IDL account):

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

Αναβαθμίσεις (επόμενες ενημερώσεις από την αρχή εξουσιοδότησης):

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

Χρήσιμες σχετικές εντολές:

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>

Σημειώστε ότι από προεπιλογή η δημιουργία του Anchor IDL account είναι χωρίς άδεια. Γι' αυτό ανεβάστε το IDL σας όσο το δυνατόν νωρίτερα και στη συνέχεια ορίστε μια αρχή εξουσιοδότησης.

Μπορείτε να διαβάσετε περισσότερα για τον Anchor IDL account στα Anchor docs.

Program Metadata Program (PMP)

Το program metadata program είναι ένα πρόγραμμα που σας επιτρέπει να αποθηκεύετε τα IDL προγραμμάτων και πληροφορίες security.txt όπως όνομα, επικοινωνία και εικονίδιο onchain. Αυτό πιθανότατα θα αποτελέσει τον πρότυπο τρόπο αποθήκευσης IDL onchain στο μέλλον.

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

Μπορείτε να διαβάσετε περισσότερα για το program metadata program στα program metadata program docs.

Σημείωση: Από την τελευταία ενημέρωση του άρθρου, το PMP δεν υποστηρίζεται ακόμα από όλους τους explorers.

Βέλτιστες Πρακτικές

Η βέλτιστη πρακτική για deployments προγραμμάτων είναι να χρησιμοποιείτε ένα Multisig όπως το Squads και για να κάνετε αυτή τη διαδικασία όσο το δυνατόν πιο εύκολη χρησιμοποιείτε τα Solana GitHub Actions workflows.

Με αυτόν τον τρόπο το πρόγραμμα θα αναβαθμίζεται αυτόματα, το IDL θα ανεβαίνει, το build θα επαληθεύεται και στη συνέχεια θα προτείνεται μια συναλλαγή για υπογραφή και deploy του προγράμματος από το multisig σας.

Διατηρείτε τα IDL ενημερωμένα → Πάντα ενημερώνετε το IDL όταν κάνετε αλλαγές στο πρόγραμμά σας.
Ανεβάστε τα IDL onchain → για διαφάνεια και υποστήριξη εργαλείων.
Τεκμηριώστε προσαρμοσμένα σφάλματα → βελτιώνει την εμπειρία χρήστη για τους clients.
Επαληθεύστε τα builds → διασφαλίστε ότι το IDL αντιστοιχεί στο deployed πρόγραμμα.

Versioning IDL

Αυτή τη στιγμή με το Anchor μπορείτε να έχετε μόνο μία έκδοση του IDL onchain τη φορά. Αυτό σημαίνει ότι αν θέλετε να κάνετε αλλαγές στο πρόγραμμά σας πρέπει να ανεβάσετε μια νέα έκδοση του IDL, κατά προτίμηση ταυτόχρονα με την αναβάθμιση του προγράμματος. Αυτό μπορεί να δημιουργήσει προβλήματα αν οι clients δεν έχουν ενημερωθεί ακόμα και είναι ένας λόγος για τον οποίο γράφτηκε το program metadata program. Με το PMP, θα μπορείτε να έχετε διαφορετικά seeds για το πρόγραμμά σας και να κάνετε versioning με αυτόν τον τρόπο. Ο σχεδιασμός γι' αυτό δεν είναι ακόμα οριστικοποιημένος και είναι ανοιχτός σε συζήτηση.

Περαιτέρω Ανάγνωση

Anchor Docs για IDL → αυτόματη δημιουργία IDL και clients. (TypeScript, C#, Python)
Codama → εργαλεία IDL + γεννήτριες clients (Rust, JS/TS, Umi/Kit, κ.ά.).
Program Metadata Program → αποθήκευση IDL και πληροφοριών security.txt onchain.

Αυτά είναι τα βασικά των IDL στο Solana. Αποτελούν τη γέφυρα μεταξύ onchain προγραμμάτων και off-chain clients, επιτρέποντας το πλούσιο οικοσύστημα εργαλείων και SDK που βλέπετε σήμερα.

IDL - μια εύχρηστη διεπαφή προγράμματος