IDL (Interface Definition Language)

IDL adalah singkatan dari Interface Definition Language.
Di Solana, IDL adalah file JSON yang mendeskripsikan antarmuka sebuah program. IDL memungkinkan explorer dan pengguna untuk mendekode instruksi program, data akun, dan error program, serta menawarkan kemungkinan untuk menghasilkan klien dalam berbagai bahasa pemrograman.

Mengapa IDL Penting

Standardisasi → Format yang seragam untuk antarmuka program.
Pengalaman Developer → Menghasilkan SDK klien secara otomatis.
Komposabilitas → Developer lain dapat berinteraksi dengan program Anda tanpa harus membaca kode sumbernya.
Keterbacaan → Semua orang dapat membaca instruksi program dan data akun di explorer tanpa harus membaca kode sumber program.

Apa yang Dapat Anda Lakukan dengan IDL

Mendekode Data Instruksi dan Akun

Semua Explorer menggunakan IDL program untuk mendekode instruksi dan data akun. Di sini Anda dapat melihat contoh Anchor 0.30.1 dan Legacy IDL di UI Solana Explorer. Dalam transaksi ini Anda dapat melihat instruksi yang telah didekode untuk game 2048, termasuk pushInDirection beserta arahnya.

Anda dapat mendekode instruksi dan data akun di klien TypeScript Anda menggunakan Solana JS helpers.

Memantau Perubahan Akun

Anda dapat dengan mudah berlangganan perubahan akun dalam program Anda menggunakan tipe TypeScript yang telah dihasilkan.

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)
  );
});

Untuk definisi event, langganan, decoding log dan CPI, backfill, versioning skema, dan pengujian, lihat Anchor Events.

Mendekode Transaksi

Anda juga dapat mendekode transaksi di klien Anda menggunakan Solana JS helpers. Ini akan memberikan Anda objek bertipe dari keseluruhan transaksi.

Buat Klien Anda Sendiri

Menggunakan IDL, Anda dapat membuat klien sendiri dalam berbagai bahasa. Cukup temukan program yang ingin Anda gunakan, unduh IDL-nya, lalu Anda dapat menghasilkan klien dalam bahasa pilihan Anda.

Berikut adalah contoh cara menghasilkan klien dalam TypeScript.

IDL di Anchor

Jika Anda menggunakan framework Anchor:

IDL dibuat secara otomatis saat Anda membangun program Anda.
IDL tersimpan di target/idl/<program>.json.
Tipe TypeScript dihasilkan di target/types/<program>.ts.
Alamat program tersimpan dalam IDL (idl.address).

anchor build
cat target/idl/counter.json

Anatomi IDL

Berikut adalah contoh minimal (spesifikasi 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 program onchain.
metadata: { name, version, spec, ... } tentang program/antarmuka.
instructions: metode yang dapat dipanggil dengan accounts, args, dan discriminator.
accounts: tipe akun yang diekspos oleh program (dengan discriminator).
types: alias struct/enum/tipe yang direferensikan oleh instruksi/akun.
events / errors / constants: definisi opsional untuk event, kode error, dan konstanta.

Catatan: Anchor v0.30 memperkenalkan spesifikasi IDL baru. Legacy IDL (sebelum v0.30) menggunakan field seperti name, version di level teratas dan isMut/isSigner di akun. Anda dapat mengonversi legacy IDL menggunakan anchor idl convert atau membangun ulang dengan Anchor v0.30+. Jika Anda perlu mengonversi legacy IDL ke spesifikasi baru secara langsung, Anda juga dapat menggunakan kode konversi ini. Ini berguna misalnya jika Anda mengelola solana explorer dan ingin tetap kompatibel ke belakang.

Klien TypeScript

Anchor juga akan secara otomatis menghasilkan klien TypeScript untuk Anda. Anda dapat menemukan klien yang dihasilkan di folder target/types.

Kemudian di klien Anda (TypeScript, v0.30+) Anda dapat memanggil instruksi program dan mengambil akun semudah ini:

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();

Klien C#

Untuk menghasilkan klien C#, Anda dapat menggunakan perintah berikut:

cd program
dotnet tool install Solana.Unity.Anchor.Tool <- run once
dotnet anchorgen -i target/idl/counter.json -o target/idl/Counter.cs

Anda dapat membaca lebih lanjut tentang cara berinteraksi dengan klien C# dari Unity di Solana games preset atau di dokumentasi Games.

Klien Python

Untuk Python, Anda dapat menggunakan library AnchorPy.

Generator klien lainnya akan tersedia menggunakan Codama renderer di masa mendatang.

IDL Tanpa Anchor

Tidak semua program dibangun dengan Anchor.
Untuk program Solana native:

Sebuah alat bernama Codama saat ini sedang dalam pengembangan untuk menghasilkan IDL dari Rust melalui makro atau dengan mengonversi IDL Anchor. Berikut adalah contoh yang sedang dalam pengerjaan dari Codama Macros untuk menghasilkan Codama IDL. Codama mengonversi IDL Anchor/Shank menjadi Codama IDL. Untuk mendapatkan Anchor IDL, hasilkan dengan Anchor (atau gunakan anchor idl convert untuk proyek lama).
Sampai makro Codama benar-benar siap, Anda juga dapat menggunakan Metaplex Shank untuk menghasilkan Shank IDL, lalu mengonversinya ke Codama IDL.
Anda juga dapat menulis IDL secara manual (format Anchor atau Codama), namun ini tidak terlalu andal. Alat AI seperti Cursor dapat membantu Anda menulis IDL, tetapi Anda harus selalu memverifikasi IDL dengan kode sumber program. Cara yang lebih baik adalah menggunakan Anchor, Codama, atau Metaplex Shank.

Menyimpan IDL Onchain

Ada dua cara untuk mengunggah IDL onchain. Yang paling banyak digunakan dan menjadi standar adalah akun IDL Anchor. Cara Anchor memungkinkan Anda mengunggah IDL onchain adalah dengan menambahkan instruksi tambahan ke program Anda yang memungkinkan Anda mengunggah dan memperbarui IDL onchain. Ini menambah ukuran program, dan itulah mengapa program metadata program dibuat. Dalam program metadata program, semua IDL program dan info security.txt seperti nama, kontak, dan ikon disimpan dalam PDA dari program metadata program.

Akun IDL Anchor

Anchor menyimpan IDL onchain dalam PDA program Anda.

IDL dapat diunggah onchain ke akun IDL Anchor.
Ini memungkinkan explorer, wallet, dan SDK mengambil IDL langsung dari Solana.

Pertama kali (inisialisasi akun IDL):

anchor idl init <PROGRAM_ID> -f target/idl/counter.json --provider.cluster devnet

Pembaruan (pembaruan berikutnya oleh authority):

anchor idl upgrade <PROGRAM_ID> -f target/idl/counter.json --provider.cluster devnet

Perintah terkait yang berguna:

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>

Perlu diperhatikan bahwa secara default pembuatan akun IDL Anchor bersifat permissionless. Oleh karena itu, unggah IDL Anda sesegera mungkin, lalu tetapkan authority.

Anda dapat membaca lebih lanjut tentang akun IDL Anchor di dokumentasi Anchor.

Program Metadata Program (PMP)

Program metadata program adalah program yang memungkinkan Anda menyimpan IDL program dan info security.txt seperti nama, kontak, dan ikon secara onchain. Ini kemungkinan akan menjadi cara standar untuk menyimpan IDL onchain di masa mendatang.

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

Anda dapat membaca lebih lanjut tentang program metadata program di dokumentasi program metadata program.

Catatan: Per pembaruan terakhir artikel ini, PMP belum didukung oleh semua explorer.

Praktik Terbaik

Praktik terbaik untuk deploy program adalah menggunakan Multisig seperti Squads dan untuk membuat proses ini semudah mungkin, gunakan workflow Solana GitHub Actions.

Dengan cara ini, program akan diperbarui secara otomatis, IDL diunggah, build diverifikasi, kemudian akan ada transaksi yang diusulkan untuk ditandatangani dan di-deploy oleh multisig Anda.

Selalu perbarui IDL → Selalu perbarui IDL setiap kali Anda membuat perubahan pada program Anda.
Unggah IDL onchain → untuk transparansi dan dukungan tooling.
Dokumentasikan error kustom → meningkatkan UX bagi klien.
Verifikasi build → pastikan IDL sesuai dengan program yang di-deploy.

Versioning IDL

Saat ini dengan Anchor, Anda hanya dapat memiliki satu versi IDL onchain pada satu waktu. Ini berarti jika Anda ingin membuat perubahan pada program Anda, Anda perlu mengunggah versi baru IDL, sebaiknya bersamaan dengan pembaruan program. Hal ini dapat menimbulkan masalah jika klien belum diperbarui, dan ini adalah salah satu alasan mengapa program metadata program dibuat. Dengan PMP, Anda akan dapat menggunakan seed yang berbeda untuk program Anda dan melakukan versioning dengan cara tersebut. Desain untuk itu belum sepenuhnya final dan masih terbuka untuk diskusi.

Bacaan Lebih Lanjut

Dokumentasi Anchor tentang IDL → menghasilkan IDL dan klien secara otomatis. (TypeScript, C#, Python)
Codama → tooling IDL + generator klien (Rust, JS/TS, Umi/Kit, dll.).
Program Metadata Program → menyimpan IDL dan informasi security.txt onchain.

Itulah dasar-dasar IDL di Solana. IDL adalah jembatan antara program onchain dan klien off-chain, yang memungkinkan ekosistem alat dan SDK yang kaya seperti yang Anda lihat saat ini.

IDL - Antarmuka Program yang Mudah Digunakan