IDL (Ngôn ngữ Định nghĩa Giao diện)

IDL là viết tắt của Ngôn ngữ Định nghĩa Giao diện (Interface Definition Language).
Trên Solana, IDL là các tệp JSON mô tả giao diện của một chương trình. Chúng cho phép các trình khám phá và người dùng giải mã các lệnh của chương trình, dữ liệu tài khoản và lỗi chương trình, đồng thời cung cấp khả năng tạo client bằng nhiều ngôn ngữ lập trình khác nhau.

Tại sao IDL quan trọng

Chuẩn hóa → Một định dạng chung cho các giao diện chương trình.
Trải nghiệm nhà phát triển → Tự động tạo SDK client.
Khả năng kết hợp → Các nhà phát triển khác có thể tương tác với chương trình của bạn mà không cần đọc mã nguồn.
Dễ đọc → Mọi người đều có thể đọc các lệnh và dữ liệu tài khoản của chương trình trong các trình khám phá mà không cần đọc mã nguồn chương trình.

Những gì bạn có thể làm với IDL

Giải mã Lệnh và Dữ liệu Tài khoản

Tất cả các Trình khám phá đều sử dụng IDL của chương trình để giải mã các lệnh và dữ liệu tài khoản. Tại đây bạn có thể xem ví dụ về Anchor 0.30.1 và IDL Legacy trong giao diện Solana Explorer. Trong giao dịch này bạn có thể thấy lệnh đã được giải mã cho một trò chơi 2048, bao gồm pushInDirection và hướng của nó.

Bạn có thể giải mã các lệnh và dữ liệu tài khoản trong client TypeScript của mình bằng cách sử dụng Solana JS helpers.

Phân tích Sự kiện Anchor hoặc Thay đổi Tài khoản

Bạn có thể dễ dàng đăng ký theo dõi các thay đổi tài khoản trong chương trình của mình bằng cách sử dụng các kiểu TypeScript được tạo tự động.

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

Ví dụ, bạn có thể phát ra các sự kiện Anchor trong chương trình của mình và sau đó ghi lại các sự kiện này, lưu chúng vào cơ sở dữ liệu hoặc sử dụng chúng để gửi tin nhắn vào một nhóm 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(),
});

Để làm điều đó, bạn có thể sử dụng Solana JS helpers để phân tích các sự kiện. Đây là một ví dụ triển khai sử dụng sự kiện Anchor để đăng tin nhắn vào nhóm telegram.

Giải mã Giao dịch

Bạn cũng có thể giải mã các giao dịch trong client của mình bằng cách sử dụng Solana JS helpers. Điều này sẽ cung cấp cho bạn một đối tượng có kiểu của toàn bộ giao dịch.

Xây dựng client của riêng bạn

Sử dụng IDL, bạn có thể tạo client của riêng mình bằng nhiều ngôn ngữ. Bạn chỉ cần tìm một chương trình mà bạn muốn tương tác, tải xuống IDL và sau đó có thể tạo client bằng ngôn ngữ bạn ưa thích.

Đây là một ví dụ về cách tạo client bằng TypeScript.

IDL trong Anchor

Nếu bạn đang sử dụng framework Anchor:

IDL được tự động tạo khi bạn build chương trình.
Nó nằm ở target/idl/<program>.json.
Các kiểu TypeScript được tạo trong target/types/<program>.ts.
Địa chỉ chương trình được lưu trong IDL (idl.address).

anchor build
cat target/idl/counter.json

Cấu trúc của một IDL

Đây là một ví dụ tối giản (đặc tả 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 chương trình trên chuỗi.
metadata: { name, version, spec, ... } về chương trình/giao diện.
instructions: các phương thức có thể gọi với accounts, args và discriminator.
accounts: các kiểu tài khoản được chương trình công khai (với các discriminator).
types: các bí danh struct/enum/kiểu được tham chiếu bởi instructions/accounts.
events / errors / constants: các định nghĩa tùy chọn cho sự kiện, mã lỗi và hằng số.

Lưu ý: Anchor v0.30 đã giới thiệu một đặc tả IDL mới. Các IDL Legacy (trước 0.30) sử dụng các trường như name, version ở cấp cao nhất và isMut/isSigner trong accounts. Bạn có thể chuyển đổi các IDL legacy bằng anchor idl convert hoặc build lại với Anchor v0.30+. Nếu bạn cần chuyển đổi IDL legacy sang đặc tả mới ngay lúc chạy, bạn cũng có thể sử dụng mã chuyển đổi này. Điều này hữu ích chẳng hạn nếu bạn duy trì một solana explorer và muốn duy trì khả năng tương thích ngược.

Client TypeScript

Anchor cũng sẽ tự động tạo một client TypeScript cho bạn. Bạn có thể tìm thấy client được tạo trong thư mục target/types.

Sau đó trong client của bạn (TypeScript, v0.30+), bạn có thể gọi các lệnh chương trình và lấy dữ liệu tài khoản dễ dàng như sau:

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

Client C#

Để tạo client C#, bạn có thể sử dụng lệnh sau:

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

Bạn có thể đọc thêm về cách tương tác với client C# từ Unity trong Solana games preset hoặc trong Tài liệu Games.

Client Python

Đối với Python, bạn có thể sử dụng thư viện AnchorPy.

Nhiều trình tạo client hơn sẽ có sẵn khi sử dụng Codama renderers trong tương lai.

IDL không dùng Anchor

Không phải tất cả các chương trình đều được xây dựng bằng Anchor.
Đối với các chương trình Solana gốc:

Một công cụ có tên Codama hiện đang được phát triển để tạo IDL từ Rust thông qua macro hoặc bằng cách chuyển đổi Anchor IDL. Đây là ví dụ đang trong quá trình phát triển về Codama Macros để tạo Codama IDL. Codama chuyển đổi Anchor/Shank IDL thành Codama IDL. Để có Anchor IDL, hãy tạo nó bằng Anchor (hoặc sử dụng anchor idl convert cho các dự án legacy).
Cho đến khi các codama macro hoàn toàn sẵn sàng, bạn cũng có thể sử dụng Metaplex Shank để tạo Shank IDL, sau đó chuyển đổi sang Codama IDL.
Bạn cũng có thể viết IDL thủ công (định dạng Anchor hoặc Codama) nhưng cách này không thực sự đáng tin cậy. Các công cụ AI như Cursor có thể giúp bạn viết IDL nhưng bạn luôn nên xác minh IDL với mã nguồn chương trình và cách tốt hơn là sử dụng Anchor, Codama hoặc Metaplex Shank.

Lưu trữ IDL On-Chain

Có hai cách để tải IDL lên onchain. Cách phổ biến và chuẩn nhất là Anchor IDL account. Cách Anchor cho phép bạn tải IDL lên onchain là bằng cách thêm các lệnh bổ sung vào chương trình của bạn, cho phép bạn tải lên và cập nhật IDL onchain. Điều này thêm một ít kích thước vào chương trình và đó là lý do tại sao program metadata program được tạo ra. Trong program metadata program, tất cả IDL của chương trình và thông tin security.txt như tên, liên hệ và icon đều được lưu trữ trong các PDA của program metadata program.

Anchor IDL Account

Anchor lưu IDL onchain trong một PDA của chương trình bạn.

IDL có thể được tải lên onchain vào Anchor IDL account.
Điều này cho phép các trình khám phá, ví và SDK lấy IDL trực tiếp từ Solana.

Lần đầu tiên (khởi tạo IDL account):

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

Nâng cấp (các cập nhật tiếp theo bởi authority):

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

Các lệnh liên quan hữu ích:

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>

Lưu ý rằng theo mặc định, việc tạo Anchor IDL account không cần cấp phép. Vì vậy hãy tải IDL của bạn lên càng sớm càng tốt và sau đó thiết lập một authority.

Bạn có thể đọc thêm về Anchor IDL account trong Tài liệu Anchor.

Program Metadata Program (PMP)

Program metadata program là một chương trình cho phép bạn lưu trữ IDL của chương trình và thông tin security.txt như tên, liên hệ và icon onchain. Đây có thể sẽ là cách chuẩn để lưu trữ IDL onchain trong tương lai.

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

Bạn có thể đọc thêm về program metadata program trong tài liệu program metadata program.

Lưu ý: Tính đến lần cập nhật cuối cùng của bài viết này, PMP chưa được hỗ trợ bởi tất cả các trình khám phá.

Các thực tiễn tốt nhất

Thực tiễn tốt nhất cho việc triển khai chương trình là sử dụng Multisig như Squads và để làm cho quá trình này dễ dàng nhất có thể, bạn sử dụng Solana GitHub Actions workflows.

Theo cách này, chương trình sẽ tự động được nâng cấp, IDL được tải lên, bản build được xác minh và sau đó sẽ có một giao dịch được đề xuất để multisig của bạn ký và triển khai chương trình.

Luôn cập nhật IDL → Luôn cập nhật IDL khi bạn thực hiện thay đổi đối với chương trình của mình.
Tải IDL lên onchain → để đảm bảo tính minh bạch và hỗ trợ công cụ.
Ghi lại các lỗi tùy chỉnh → cải thiện UX cho các client.
Xác minh các bản build → đảm bảo IDL khớp với chương trình đã được triển khai.

Quản lý phiên bản IDL

Hiện tại với Anchor, bạn chỉ có thể có một phiên bản IDL trên chuỗi tại một thời điểm. Điều này có nghĩa là nếu bạn muốn thực hiện thay đổi đối với chương trình của mình, bạn cần tải lên phiên bản IDL mới, tốt nhất là cùng lúc với khi bạn nâng cấp chương trình. Điều này có thể dẫn đến sự cố nếu các client chưa được cập nhật và đây là một lý do tại sao program metadata program được tạo ra. Với PMP, bạn sẽ có thể có các seed khác nhau cho chương trình của mình và thực hiện quản lý phiên bản theo cách đó. Thiết kế cho điều này vẫn chưa hoàn toàn được hoàn thiện và còn đang được thảo luận.

Đọc thêm

Tài liệu Anchor về IDL → tự động tạo IDL và client. (TypeScript, C#, Python)
Codama → Công cụ IDL + trình tạo client (Rust, JS/TS, Umi/Kit, v.v.).
Program Metadata Program → lưu trữ IDL và thông tin security.txt onchain.

Đó là những kiến thức cơ bản về IDL trên Solana. Chúng là cầu nối giữa các chương trình onchain và các client off-chain, tạo nên hệ sinh thái phong phú của các công cụ và SDK mà bạn thấy ngày nay.

IDL - Giao diện Chương trình dễ sử dụng