Dokumentasi SolanaMengembangkan Program

IDL - Antarmuka Program yang Mudah Digunakan

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 kesalahan program, serta menawarkan kemungkinan untuk menghasilkan klien dalam berbagai bahasa pemrograman.

Mengapa IDL Penting

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

Apa yang Dapat Anda Lakukan dengan IDL

Mendekode Instruksi dan Data 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.

Mem-parsing Event Anchor atau Perubahan Akun

Anda dapat dengan mudah berlangganan perubahan akun di program Anda menggunakan tipe TypeScript yang 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)

  );

});

Misalnya, Anda dapat memancarkan event Anchor di program Anda dan kemudian mencatat event-event tersebut, menulisnya ke database, atau menggunakannya untuk mengirim pesan ke chat 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(),

});

Untuk itu, Anda dapat menggunakan Solana JS helpers untuk mem-parsing event. Berikut adalah contoh implementasi yang menggunakan event Anchor untuk memposting pesan ke chat Telegram.

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, dan 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 dihasilkan secara otomatis saat Anda membangun program Anda.
  • IDL tersimpan di target/idl/<program>.json.
  • Tipe TypeScript dihasilkan di target/types/<program>.ts.
  • Alamat program disimpan dalam IDL (idl.address).
anchor build

cat target/idl/counter.json

Anatomi sebuah 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. IDL lama (sebelum v0.30) menggunakan field seperti name, version di level teratas dan isMut/isSigner di akun. Anda dapat mengonversi IDL lama menggunakan anchor idl convert atau membangun ulang dengan Anchor v0.30+. Jika Anda perlu mengonversi IDL lama 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 renderers di masa mendatang.

IDL Tanpa Anchor

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

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

Menyimpan IDL di Onchain

Ada dua cara untuk mengunggah IDL ke onchain. Yang paling umum digunakan dan menjadi standar adalah Anchor IDL account. Cara Anchor mengizinkan Anda mengunggah IDL ke onchain adalah dengan menambahkan instruksi tambahan ke program Anda yang memungkinkan Anda mengunggah dan memperbarui IDL di onchain. Ini menambah ukuran ekstra pada program, dan inilah alasan mengapa program metadata program dibuat. Di dalam program metadata program, semua IDL program dan info security.txt seperti nama, kontak, dan ikon disimpan dalam PDA dari program metadata program.

Anchor IDL Account

Anchor menyimpan IDL di onchain dalam PDA dari program Anda.

  • IDL dapat diunggah secara onchain ke Anchor IDL account.
  • Ini memungkinkan explorer, wallet, dan SDK untuk mengambil IDL langsung dari Solana.

Pertama kali (inisialisasi IDL account):

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

Pembaruan (pembaruan selanjutnya oleh otoritas):

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 diketahui bahwa secara default pembuatan Anchor IDL account bersifat tanpa izin. Jadi unggah IDL Anda sesegera mungkin dan kemudian tetapkan otoritas.

Anda dapat membaca lebih lanjut tentang Anchor IDL account 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 di onchain. Ini kemungkinan akan menjadi cara standar untuk menyimpan IDL di 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: Pada saat pembaruan artikel terakhir, 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 Anda dapat menggunakan Solana GitHub Actions workflows.

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

  1. Perbarui IDL secara konsisten → Selalu perbarui IDL saat Anda melakukan perubahan pada program Anda.
  2. Unggah IDL ke onchain → untuk transparansi dan dukungan tooling.
  3. Dokumentasikan error kustom → meningkatkan UX untuk klien.
  4. Verifikasi build → pastikan IDL sesuai dengan program yang di-deploy.

Versioning IDL

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

Bacaan Lebih Lanjut

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.

Is this page helpful?

Sebelumnya

Menghasilkan Klien

Berikutnya

Memverifikasi Program

Daftar Isi

Edit Halaman
Gunakan Solana
Bangun
Perusahaan
Produk
Ekosistem
Agen AI
© 2026 Yayasan Solana. Semua hak dilindungi.