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.

Отслеживание изменений аккаунтов

Вы можете легко подписаться на изменения аккаунтов в своей программе, используя сгенерированные типы 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. Это вернёт типизированный объект всей транзакции.

Создание собственного клиента

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

Хранение IDL в сети

Существует два способа загрузки IDL в сеть. Наиболее распространённый и стандартный — это аккаунт IDL Anchor. Anchor позволяет загружать IDL в сеть, добавляя в программу дополнительные инструкции для загрузки и обновления IDL. Это увеличивает размер программы, именно поэтому была создана программа метаданных программы. В программе метаданных программы все IDL программ и информация security.txt — имя, контакт и иконка — хранятся в PDA программы метаданных программы.

Аккаунт IDL Anchor

Anchor сохраняет IDL в сети в PDA вашей программы.

IDL можно загрузить в сеть в аккаунт IDL Anchor.
Это позволяет обозревателям, кошелькам и 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>

Обратите внимание, что по умолчанию создание аккаунта IDL Anchor является беспрепятственным. Поэтому загрузите IDL как можно скорее, а затем установите авторизацию.

Подробнее об аккаунте IDL Anchor можно прочитать в документации Anchor.

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

Программа метаданных программы — это программа, которая позволяет хранить IDL программ и информацию security.txt — имя, контакт и иконку — в сети. Вероятно, в будущем это станет стандартным способом хранения IDL в сети.

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

Подробнее о программе метаданных программы можно прочитать в документации программы метаданных программы.

Примечание: на момент последнего обновления статьи PMP поддерживается не всеми обозревателями.

Версионирование IDL

В настоящее время с Anchor в сети одновременно может храниться только одна версия IDL. Это означает, что при внесении изменений в программу необходимо загружать новую версию IDL, желательно одновременно с обновлением программы. Это может привести к проблемам, если клиенты ещё не обновлены, и является одной из причин создания программы метаданных программы. С PMP у вас появится возможность использовать разные сиды для программы и реализовать версионирование таким образом. Дизайн этого решения ещё не окончательно определён и открыт для обсуждения.

Дополнительные материалы

Документация Anchor по IDL → автоматическая генерация IDL и клиентов. (TypeScript, C#, Python)
Codama → инструменты IDL и генераторы клиентов (Rust, JS/TS, Umi/Kit и др.).
Программа метаданных программы → хранение IDL и информации security.txt в сети.

Это основы IDL на Solana. Они служат мостом между программами в сети и офчейн-клиентами, обеспечивая богатую экосистему инструментов и SDK, которую вы видите сегодня.

IDL — удобный интерфейс программы