Визначення

IDL (Interface Definition Language) — це файл у форматі JSON, який описує зовнішній інтерфейс програми на Solana: її інструкції, структури акаунтів, типи даних, помилки та події. У екосистемі Solana IDL тісно повʼязаний із фреймворком Anchor і виконує роль, аналогічну ABI у Ethereum — дозволяє клієнтським додаткам взаємодіяти з програмою без необхідності читати її вихідний код на Rust.

Як працює

Під час компіляції програми Anchor автоматично генерує IDL на основі анотацій у Rust-коді. Цей файл містить усе необхідне для формування правильних транзакцій:

  • Program ID — адреса програми в мережі;
  • Accounts — перелік акаунтів, які вимагає кожна інструкція, із зазначенням того, чи є вони підписантами, чи записуваними;
  • Instructions — назви методів, їхні аргументи та типи;
  • Types — кастомні структури даних, які програма використовує;
  • Errors — коди та описи помилок, визначених розробником;
  • Events — події, які програма логує під час виконання.

На стороні клієнта (зазвичай TypeScript) бібліотека @coral-xyz/anchor завантажує IDL і автоматично створює типізовані методи для виклику інструкцій. Розробник фронтенду працює з IDL як із контрактом: знає, які акаунти передати, які аргументи очікує інструкція і яку структуру даних отримає у відповідь.

Приклад

Фрагмент IDL для простої програми-лічильника з однією інструкцією increment:

{
  "version": "0.1.0",
  "name": "counter",
  "instructions": [
    {
      "name": "increment",
      "accounts": [
        { "name": "counter", "isMut": true, "isSigner": false }
      ],
      "args": []
    }
  ],
  "accounts": [
    {
      "name": "Counter",
      "type": {
        "kind": "struct",
        "fields": [
          { "name": "count", "type": "u64" }
        ]
      }
    }
  ]
}

З цього опису клієнтський код одразу знає: інструкція increment потребує один записуваний акаунт типу Counter, не потребує аргументів і працює з полем count типу u64.

Типова помилка

Найчастіша помилка — використання застарілого IDL після оновлення та повторного розгортання програми. Якщо розробник додав новий аргумент до інструкції в Rust-коді, але забув оновити IDL на клієнтській стороні, транзакція буде сформована неправильно і відхилена з помилкою десеріалізації. IDL має завжди відповідати саме тій версії програми, яка розгорнута на ланцюжку. Перевіряйте відповідність IDL після кожного розгортання.

Пов'язані матеріали

Внутрішні переходи

  • CPI (Cross-Program Invocation) — як програми викликають одна одну, використовуючи знання про інтерфейси;
  • Compute units — обмеження обчислювальних ресурсів, які впливають на складність інструкцій, описаних у IDL.

Джерела