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

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

IDLが重要な理由

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

IDLでできること

InstructionおよびアカウントデータのデコードAnchor

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

TypeScriptクライアントでinstructionsとアカウントデータをデコードするには、 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でクライアントを生成する方法についてはこちらの例を参照してください。

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：プログラムが公開するアカウント型（ディスクリミネーター付き）。
types：instructions／アカウントから参照されるstruct／enum／型エイリアス。
events / errors / constants：イベント、エラーコード、定数のオプション定義。

注意：Anchor v0.30では新しいIDL仕様が導入されました。レガシーIDL（v0.30以前）はトップレベルにnameやversionフィールドを使用し、アカウントに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と、名前・連絡先・アイコンなどの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

便利な関連コマンド：

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アカウントの生成はパーミッションレスです。できるだけ早くIDLをアップロードし、その後に権限者を設定してください。

Anchor IDLアカウントについての詳細は 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はまだすべてのエクスプローラーでサポートされているわけではありません。

ベストプラクティス

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

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

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

IDLのバージョニング

現在、Anchorではオンチェーンに保持できるIDLのバージョンは同時に1つだけです。つまり、プログラムに変更を加えたい場合は新しいバージョンの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 - 使いやすいプログラムインターフェース