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

IDL là viết tắt của Interface Definition Language (Ngôn ngữ Định nghĩa Giao diện).
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 ở nhiều ngôn ngữ lập trình khác nhau.

Tại sao IDL lại quan trọng

Tiêu chuẩn hóa → Đị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 của nó.
Khả năng đọc → Mọi người đều có thể đọc các lệnh chương trình và dữ liệu tài khoản trong các trình khám phá mà không cần đọc mã nguồn của chương trình.

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

Giải mã dữ liệu lệnh và tài khoản

Tất cả các trình khám phá đều sử dụng IDL chương trình để giải mã các lệnh và dữ liệu tài khoản. Ở đây bạn có thể xem ví dụ về Anchor 0.30.1 và Legacy IDL 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 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 các thay đổi tài khoản

Bạn có thể dễ dàng 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)
  );
});

Để biết về định nghĩa sự kiện, đăng ký, giải mã log và CPI, backfill, phiên bản schema và kiểm thử, hãy xem Anchor Events.

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 muốn tương tác, tải IDL xuống và sau đó có thể tạo client bằng ngôn ngữ ưa thích của bạn.

Đây là ví dụ về cách tạo client trong TypeScript.

IDL trong Anchor

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

IDL được tạo tự động khi bạn build chương trình.
Nó được lưu tại target/idl/<program>.json.
Các kiểu TypeScript được tạo tại 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à ví dụ tối giản (theo spec 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, ... } thông tin 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 (kèm discriminator).
types: các struct/enum/type alias đượ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, hằng số.

Lưu ý: Anchor v0.30 đã giới thiệu spec IDL mới. Các Legacy IDL (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 legacy IDL bằng anchor idl convert hoặc build lại với Anchor v0.30+. Nếu bạn cần chuyển đổi legacy IDL sang spec mới ngay lập tức, bạn cũng có thể sử dụng mã chuyển đổi này. Điều này hữu ích ví dụ nếu bạn duy trì một solana explorer và muốn giữ khả năng tương thích ngược.

Client TypeScript

Anchor cũng sẽ tự động tạo 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ư thế này:

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 bộ tạo client hơn sẽ có sẵn thông qua 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 với Anchor.
Đối với các chương trình Solana native:

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ó với Anchor (hoặc dùng anchor idl convert cho các dự án cũ).
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 nó sang Codama IDL.
Bạn cũng có thể viết IDL bằng tay (định dạng Anchor hoặc Codama) nhưng đây là cách không đáng tin cậy lắm. Các công cụ AI như Cursor có thể giúp bạn viết IDL nhưng bạn nên luô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 trên chuỗi

Có hai cách để tải IDL lên chuỗi. Cách được sử dụng phổ biến và tiêu chuẩn nhất là Anchor IDL account. Cách Anchor cho phép bạn tải IDL lên chuỗi 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 trên chuỗi. Điều này làm tăng thêm kích thước cho 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ả các IDL chương trình và thông tin security.txt như tên, liên hệ và biểu tượng được lưu trữ trong PDA của program metadata program.

Anchor IDL Account

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

IDL có thể được tải lên trên chuỗi 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 quyền hạn. 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 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ữ các IDL chương trình và thông tin security.txt như tên, liên hệ và biểu tượng trên chuỗi. Đây có thể sẽ là cách tiêu chuẩn để lưu trữ IDL trên chuỗi 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, PMP chưa được hỗ trợ bởi tất cả các trình khám phá.

Các thực hành tốt nhất

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

Như vậ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 cho multisig của bạn để ký và deploy 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 chuỗi → để đảm bảo tính minh bạch và hỗ trợ công cụ.
Ghi chép các lỗi tùy chỉnh → cải thiện trải nghiệm người dùng cho client.
Xác minh bản build → đảm bảo IDL khớp với chương trình đã deploy.

Versioning 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 mới của IDL, tốt nhất là cùng lúc với việc 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 trong những lý do tại sao program metadata program được tạo ra. Với PMP, bạn sẽ có thể sử dụng các seed khác nhau cho chương trình của mình và thực hiện versioning theo cách đó. Thiết kế cho điều đó vẫn chưa hoàn toàn được quyết định 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 + bộ tạo client (Rust, JS/TS, Umi/Kit, v.v.).
Program Metadata Program → lưu trữ IDL và thông tin security.txt trên chuỗi.

Đó 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 trên chuỗi và các client ngoài chuỗi, 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