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

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

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

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

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

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

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

Ви можете декодувати інструкції та дані account у вашому TypeScript-клієнті за допомогою Solana JS helpers.

Парсинг подій Anchor або змін account

Ви можете легко підписатися на зміни account у вашій програмі, використовуючи згенеровані 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 у своїй програмі, а потім записувати їх у журнал, зберігати в базі даних або використовувати для надсилання повідомлень у 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 для парсингу подій. Ось приклад реалізації, яка використовує події Anchor для публікації повідомлень у Telegram-чат.

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

Ви також можете декодувати транзакції у вашому клієнті за допомогою 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: типи account, що надаються програмою (з дискримінаторами).
types: псевдоніми struct/enum/типів, на які посилаються інструкції та account.
events / errors / constants: необов'язкові визначення подій, кодів помилок і констант.

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

TypeScript-клієнт

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

Потім у вашому клієнті (TypeScript, v0.30+) ви можете так само просто викликати інструкції програми та отримувати account:

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 конвертує Anchor/Shank IDL у Codama IDL. Щоб отримати Anchor IDL, згенеруйте його за допомогою Anchor (або використайте anchor idl convert для legacy-проєктів).
Поки макроси Codama не готові повністю, ви також можете скористатися Metaplex Shank, щоб згенерувати Shank IDL, а потім конвертувати його в Codama IDL.
Ви також можете написати IDL вручну (у форматах Anchor або Codama), але це не дуже надійно. Інструменти ШІ, як-от Cursor, можуть допомогти написати IDL, але завжди перевіряйте IDL за вихідним кодом програми — надійніший спосіб — використовувати Anchor, Codama або Metaplex Shank.

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

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

Anchor IDL Account

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

IDL можна завантажити в мережу до Anchor IDL account.
Це дозволяє оглядачам, гаманцям і 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 якнайшвидше, а потім встановіть authority.

Детальніше про Anchor IDL account можна дізнатися з документації Anchor.

Program Metadata Program (PMP)

Program metadata program — це програма, що дозволяє зберігати IDL програм та інформацію security.txt (назву, контакт і іконку) в мережі. Імовірно, у майбутньому це стане стандартним способом зберігання IDL в мережі.

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

Детальніше про program metadata program можна дізнатися з документації program metadata program.

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

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

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

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

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

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

Наразі з Anchor ви можете мати лише одну версію IDL в мережі одночасно. Це означає, що якщо ви хочете внести зміни до програми, вам потрібно завантажити нову версію IDL — бажано одночасно з оновленням програми. Це може призводити до проблем, якщо клієнти ще не оновлені, і є однією з причин, чому було написано program metadata program. З 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 — зручний інтерфейс програми