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.

Разбор событий Anchor или изменений аккаунтов

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

Декодирование транзакций

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

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

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

Аккаунт 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.

Program Metadata Program (PMP)

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

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

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

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

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

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

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

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

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

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