IDL（インターフェース定義言語）

IDLは**インターフェース定義言語（Interface Definition Language）**の略です。 Solanaでは、IDLはプログラムのインターフェースを記述するJSONファイルです。エクスプローラーやユーザーがプログラムのinstructions、アカウントデータ、プログラムエラーをデコードできるようにし、さまざまなプログラミング言語でクライアントを生成する機能も提供します。

IDLが重要な理由

標準化 → プログラムインターフェースの共通フォーマット。
開発者体験 → クライアントSDKを自動生成。
コンポーザビリティ → 他の開発者がソースコードを読まずにあなたのプログラムと連携できます。
可読性 → プログラムのソースコードを読まなくても、エクスプローラー上でプログラムのinstructionsとアカウントデータを誰でも確認できます。

IDLでできること

instructionsとアカウントデータのデコード

すべてのエクスプローラーはプログラムIDLを使用してinstructionsとアカウントデータをデコードします。ここでは、Solana Explorer UIにおける Anchor 0.30.1 とレガシーIDL の例を確認できます。このトランザクションでは、2048ゲームのデコードされたinstructionを確認でき、pushInDirectionとその方向が含まれています。

TypeScriptクライアントでinstructionsとアカウントデータをデコードするには、 Solana JSヘルパーを使用します。

AnchorイベントまたはアカウントChangesのパース

生成された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でクライアントを生成する方法の例はこちらです。

AnchorにおけるIDL

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：オンチェーンのプログラムID。
metadata：プログラム／インターフェースに関する { name, version, spec, ... }。
instructions：accounts、args、discriminator を持つ呼び出し可能なメソッド。
accounts：プログラムが公開するアカウントの型（discriminatorを含む）。
types：instructions／accountsから参照されるstruct／enum／型エイリアス。
events / errors / constants：イベント、エラーコード、定数のオプション定義。

注意：Anchor v0.30では新しいIDL仕様が導入されました。レガシーIDL（0.30以前）はトップレベルに name、version フィールドを使用し、accountsには isMut／isSigner を使用していました。レガシーIDLは anchor idl convert を使用するか、Anchor v0.30+で再ビルドすることで変換できます。レガシーIDLをその場で新しい仕様に変換する必要がある場合は、この変換コードも利用できます。これは、たとえばSolanaエクスプローラーを管理していて後方互換性を維持したい場合に便利です。

TypeScriptクライアント

Anchorは自動的にTypeScriptクライアントも生成します。生成されたクライアントは target/types フォルダーに保存されます。

クライアント（TypeScript、v0.30+）では、プログラムのinstructionsを呼び出したり、アカウントを取得したりするのが簡単にできます：

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

UnityでC#クライアントを使用する方法の詳細については、 Solanaゲームプリセットまたはゲームドキュメントをご参照ください。

Pythonクライアント

PythonではAnchorPy ライブラリを使用できます。

今後、Codamaレンダラーを使用したクライアントジェネレーターがさらに追加される予定です。

Anchorを使わないIDL

すべてのプログラムがAnchorで構築されているわけではありません。ネイティブSolanaプログラムの場合：

Codama というツールが現在開発中で、マクロを使ってRustからIDLを生成したり、Anchor IDLを変換したりすることができます。Codamaマクロを使ってCodama IDLを生成する進行中の例もあります。CodamaはAnchor／Shank IDLをCodama IDLに変換します。Anchor IDLを取得するには、Anchorで生成するか（レガシープロジェクトの場合は anchor idl convert を使用）してください。
Codamaマクロが完全に完成するまでの間、Metaplex Shankを使用してShank IDLを生成し、それをCodama IDLに変換することもできます。
IDLを手書きすることもできます（AnchorまたはCodama形式）が、これはあまり信頼性が高くありません。CursorなどのAIツールがIDL作成を支援できますが、常にプログラムのソースコードと照合してIDLを検証する必要があります。より良い方法はAnchor、Codama、またはMetaplex Shankを使用することです。

IDLをオンチェーンにアップロードする方法は2つあります。最も広く使われている標準的な方法はAnchor IDLアカウントです。AnchorがIDLをオンチェーンにアップロードできる仕組みは、プログラムにIDLのアップロードと更新を可能にする追加のinstructionsを組み込むことです。これによりプログラムのサイズが若干増加するため、program metadata programが作られました。program metadata programでは、すべてのプログラムIDLとname、contact、iconなどのsecurity.txt情報が program metadata program のPDAに保存されます。

Anchor IDLアカウント

AnchorはIDLをプログラムのPDAにオンチェーン保存します。

IDLはAnchor IDLアカウントにオンチェーンでアップロードできます。
これにより、エクスプローラー、ウォレット、SDKがSolanaから直接IDLを取得できるようになります。

初回（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

Program Metadata Program（PMP）

program metadata programは、プログラムIDLとname、contact、iconなどのsecurity.txt情報をオンチェーンに保存できるプログラムです。将来的には、これがIDLをオンチェーンに保存する標準的な方法になると思われます。

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

program metadata programの詳細については program metadata programドキュメントをご参照ください。

注意：この記事の最終更新時点では、PMPはまだすべてのエクスプローラーでサポートされていません。

ベストプラクティス

プログラムデプロイのベストプラクティスは、Squadsのようなマルチシグを使用することです。このプロセスをできるだけ簡単にするために、 Solana GitHub Actionsワークフローを活用します。

これにより、プログラムが自動的にアップグレードされ、IDLがアップロードされ、ビルドが検証され、マルチシグが署名してプログラムをデプロイするためのトランザクションが提案されます。

IDLを常に最新の状態に保つ → プログラムを変更した際は必ずIDLも更新してください。
IDLをオンチェーンにアップロードする → 透明性とツールサポートのために。
カスタムエラーをドキュメント化する → クライアントのUXを向上させます。
ビルドを検証する → IDLがデプロイ済みプログラムと一致することを確認してください。

IDLのバージョン管理

現在、Anchorではオンチェーンに一度に1つのバージョンのIDLしか持つことができません。つまり、プログラムに変更を加える場合は、できればプログラムのアップグレードと同時に新しいバージョンのIDLをアップロードする必要があります。クライアントがまだ更新されていない場合に問題が生じる可能性があり、これがprogram metadata programが作られた理由の一つです。PMPでは、プログラムに異なるシードを持たせてバージョン管理を行えるようになります。その設計はまだ完全に確定しておらず、議論の余地があります。

参考資料

AnchorのIDLドキュメント → IDLとクライアントを自動生成します。（TypeScript、C#、Python）
Codama → IDLツール + クライアントジェネレーター（Rust、JS/TS、Umi/Kitなど）。
Program Metadata Program → IDLとsecurity.txt情報をオンチェーンに保存します。

以上がSolanaにおけるIDLの基本です。IDLはオンチェーンプログラムとオフチェーンクライアントをつなぐ橋であり、今日見られる豊富なツールとSDKのエコシステムを支えています。

IDL - 使いやすいプログラムインターフェース