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 στο Solana Explorer UI. Σε αυτήν την τρανζάκσιον μπορείτε να δείτε την αποκωδικοποιημένη οδηγία για ένα παιχνίδι 2048, συμπεριλαμβανομένου του pushInDirection και της κατεύθυνσής του.

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

Ανάλυση Anchor Events ή Αλλαγών Λογαριασμού

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

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

Για αυτό μπορείτε να χρησιμοποιήσετε τα Solana JS helpers για την ανάλυση των events. Εδώ είναι ένα παράδειγμα υλοποίησης που χρησιμοποιεί anchor events για να αναρτά μηνύματα σε μια ομάδα telegram.

Αποκωδικοποίηση Τρανζάκσιον

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

Δημιουργήστε τον δικό σας 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: κλήσιμες μέθοδοι με accounts, args και ένα discriminator.
accounts: τύποι λογαριασμών που εκθέτει το πρόγραμμα (με discriminators).
types: struct/enum/ψευδώνυμα τύπων που αναφέρονται από οδηγίες/λογαριασμούς.
events / errors / constants: προαιρετικοί ορισμοί για events, κωδικούς σφαλμάτων, σταθερές.

Σημείωση: Το Anchor v0.30 εισήγαγε νέα προδιαγραφή IDL. Τα Legacy IDL (προ-0.30) χρησιμοποιούσαν πεδία όπως name, version στο ανώτατο επίπεδο και isMut/isSigner στους λογαριασμούς. Μπορείτε να μετατρέψετε legacy IDL χρησιμοποιώντας anchor idl convert ή να ξαναχτίσετε με 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 έργα).
Μέχρι να είναι πλήρως έτοιμα τα codama macros μπορείτε επίσης να χρησιμοποιήσετε το Metaplex Shank για να δημιουργήσετε ένα Shank IDL και στη συνέχεια να το μετατρέψετε σε Codama IDL.
Μπορείτε επίσης να γράψετε το IDL με το χέρι (σε μορφή Anchor ή Codama), αλλά αυτό δεν είναι πολύ αξιόπιστο. Εργαλεία AI όπως το Cursor μπορούν να σας βοηθήσουν να γράψετε το IDL, αλλά θα πρέπει πάντα να επαληθεύετε το IDL με τον πηγαίο κώδικα του προγράμματος και ο καλύτερος τρόπος είναι να χρησιμοποιείτε Anchor, Codama ή Metaplex Shank.

Αποθήκευση IDL Onchain

Υπάρχουν δύο τρόποι για να ανεβάσετε IDL onchain. Ο πιο διαδεδομένος και τυπικός είναι το Anchor IDL account. Ο τρόπος που το Anchor σάς επιτρέπει να ανεβάζετε τα IDL σας onchain είναι προσθέτοντας επιπλέον οδηγίες στο πρόγραμμά σας που σας επιτρέπουν να ανεβάζετε και να ενημερώνετε τα IDL σας onchain. Αυτό προσθέτει κάποιο επιπλέον μέγεθος στο πρόγραμμα και γι' αυτό δημιουργήθηκε το program metadata program. Στο program metadata program όλα τα 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 είναι ένα πρόγραμμα που σάς επιτρέπει να αποθηκεύετε τα 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.

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

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

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

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

Έκδοση 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 - μια εύχρηστη διεπαφή προγράμματος