IDL (мова визначення інтерфейсу)

IDL розшифровується як Interface Definition Language (мова визначення інтерфейсу).
На Solana IDL — це JSON-файли, що описують інтерфейс програми. Вони дозволяють оглядачам і користувачам декодувати інструкції програми, дані акаунтів і помилки програми, а також надають можливість генерувати клієнти різними мовами програмування.

Навіщо потрібні IDL

Стандартизація → Єдиний формат для інтерфейсів програм.
Зручність для розробників → Автоматична генерація клієнтських SDK.
Компонованість → Інші розробники можуть взаємодіяти з вашою програмою, не читаючи її вихідний код.
Читабельність → Кожен може переглядати інструкції програми та дані акаунтів в оглядачах, не читаючи вихідний код програми.

Що можна робити з IDL

Декодування інструкцій та даних акаунтів

Усі оглядачі використовують IDL програм для декодування інструкцій та даних акаунтів. Тут ви можете побачити приклади Anchor 0.30.1 та Legacy IDL у інтерфейсі Solana Explorer. У цій транзакції ви можете побачити декодовану інструкцію для гри 2048, включаючи pushInDirection та її напрямок.

Ви можете декодувати інструкції та дані акаунтів у своєму TypeScript-клієнті, використовуючи 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)
  );
});

Щодо визначення подій, підписок, декодування логів і CPI, бекфілів, версіонування схем та тестування, дивіться Anchor Events.

Декодування транзакцій

Ви також можете декодувати транзакції у своєму клієнті, використовуючи Solana JS helpers. Це надасть вам типізований об'єкт усієї транзакції.

Створення власного клієнта

Використовуючи IDL, ви можете створити власний клієнт багатьма мовами. Просто знайдіть програму, з якою хочете взаємодіяти, завантажте IDL, і тоді ви зможете згенерувати клієнт у своїй улюбленій мові програмування.

Ось приклад того, як згенерувати клієнт на TypeScript.

IDL в Anchor

Якщо ви використовуєте фреймворк Anchor:

IDL генерується автоматично під час збірки програми.
Він зберігається в 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: ідентифікатор програми в мережі.
metadata: { name, version, spec, ... } — інформація про програму/інтерфейс.
instructions: виклики методів з accounts, args та discriminator.
accounts: типи акаунтів, що надаються програмою (з дискримінаторами).
types: псевдоніми структур/перелічень/типів, що використовуються в інструкціях/акаунтах.
events / errors / constants: необов'язкові визначення для подій, кодів помилок, констант.

Примітка: Anchor v0.30 запровадив нову специфікацію IDL. У застарілих IDL (до версії 0.30) використовувались поля name, version на верхньому рівні та isMut/isSigner в акаунтах. Ви можете конвертувати застарілі IDL за допомогою anchor idl convert або перезібрати з Anchor v0.30+. Якщо вам потрібно конвертувати застарілий IDL до нової специфікації на льоту, ви також можете використати цей код конвертації. Це корисно, наприклад, якщо ви підтримуєте Solana-оглядач і хочете зберегти зворотну сумісність.

TypeScript-клієнт

Anchor також автоматично згенерує для вас TypeScript-клієнт. Ви можете знайти згенерований клієнт у папці target/types.

Потім у своєму клієнті (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#-клієнт

Щоб згенерувати C#-клієнт, виконайте таку команду:

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

Докладніше про взаємодію з C#-клієнтом з Unity можна прочитати в пресеті для Solana-ігор або в документації для ігор.

Python-клієнт

Для Python ви можете використовувати бібліотеку AnchorPy.

У майбутньому буде доступно більше генераторів клієнтів за допомогою рендерерів Codama.

IDL без Anchor

Не всі програми створені з використанням Anchor.
Для нативних програм Solana:

Інструмент під назвою Codama наразі розробляється для генерації IDL з Rust за допомогою макросів або шляхом конвертації Anchor IDL. Ось приклад у процесі розробки — Codama Macros для генерації Codama IDL. Codama конвертує IDL формату Anchor/Shank у Codama IDL. Щоб отримати Anchor IDL, згенеруйте його за допомогою Anchor (або використовуйте anchor idl convert для застарілих проєктів).
Поки макроси Codama не готові повністю, ви також можете використовувати Metaplex Shank для генерації Shank IDL, а потім конвертувати його в Codama IDL.
Ви також можете написати IDL вручну (у форматі Anchor або Codama), але це не дуже надійно. Інструменти штучного інтелекту, як-от Cursor, можуть допомогти вам у написанні IDL, але завжди перевіряйте IDL за вихідним кодом програми — кращим підходом є використання Anchor, Codama або Metaplex Shank.

Зберігання IDL в мережі

Існує два способи завантаження IDL в мережу. Найпоширенішим і стандартним є акаунт Anchor IDL. Anchor дозволяє завантажувати IDL в мережу, додаючи до вашої програми додаткові інструкції для завантаження та оновлення IDL в мережі. Це збільшує розмір програми, саме тому була створена програма метаданих програми. У програмі метаданих програми всі IDL програм та інформація security.txt, як-от ім'я, контакт та іконка, зберігаються в PDA програми метаданих програми.

Акаунт Anchor IDL

Anchor зберігає IDL в мережі в PDA вашої програми.

IDL можна завантажити в мережу до акаунту Anchor IDL.
Це дозволяє оглядачам, гаманцям та SDK отримувати IDL безпосередньо з Solana.

Перший раз (ініціалізація акаунту IDL):

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 є безпозиційним. Тому завантажте свій IDL якомога швидше, а потім встановіть авторизацію.

Докладніше про акаунт Anchor IDL можна прочитати в документації Anchor.

Програма метаданих програми (PMP)

Програма метаданих програми — це програма, яка дозволяє зберігати IDL програм та інформацію security.txt, як-от ім'я, контакт та іконка, в мережі. Це, мабуть, стане стандартним способом зберігання IDL в мережі у майбутньому.

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

Докладніше про програму метаданих програми можна прочитати в документації програми метаданих програми.

Примітка: Станом на момент останнього оновлення статті PMP ще підтримується не всіма оглядачами.

Найкращі практики

Найкраща практика для деплою програм — використовувати Multisig, наприклад Squads, а щоб зробити цей процес якомога простішим, використовуйте робочі процеси Solana GitHub Actions.

Таким чином програма буде автоматично оновлена, IDL завантажено, збірку верифіковано, а потім буде запропоновано транзакцію для підписання та деплою програми вашим мультисигом.

Оновлюйте IDL → Завжди оновлюйте IDL при внесенні змін до вашої програми.
Завантажуйте IDL в мережу → для прозорості та підтримки інструментів.
Документуйте власні помилки → покращує UX для клієнтів.
Верифікуйте збірки → переконайтеся, що IDL відповідає задеплоєній програмі.

Версіонування IDL

Наразі з Anchor ви можете мати лише одну версію IDL в мережі одночасно. Це означає, що якщо ви хочете внести зміни до своєї програми, вам потрібно завантажити нову версію IDL, бажано одночасно з оновленням програми. Це може призводити до проблем, якщо клієнти ще не оновлені, і є однією з причин, чому була написана програма метаданих програми. З PMP ви зможете використовувати різні seed-и для своєї програми та здійснювати версіонування таким чином. Дизайн для цього ще не є остаточним і відкритий для обговорення.

Додаткові матеріали

Документація Anchor щодо IDL → автоматична генерація IDL та клієнтів. (TypeScript, C#, Python)
Codama → інструментарій IDL + генератори клієнтів (Rust, JS/TS, Umi/Kit тощо).
Program Metadata Program → зберігання IDL та інформації security.txt в мережі.

Це основи IDL на Solana. Вони є мостом між програмами в мережі та офлайн-клієнтами, забезпечуючи роботу багатого екосистему інструментів та SDK, який ви бачите сьогодні.

IDL — зручний інтерфейс програми