eric.dev.blog

初探Solana程式接口描述 - Anchor IDL

eric's photo
eric

如果你看過我之前寫的兩篇介紹文章 ( Solana小技巧 - 解構PDA數據結構 及 [Example study] Solana program Instruction data encoding ), 大概會感到無論是Instruction Data也好, 或Data Account數據也好, 也像是空有一堆bytes的盲盒。彷彿如果不是預先知道source code的話, 就不懂如何解讀甚或封裝數據。

在這缺口上, Anchor framework做了一個很造福人群的解決方案, 就是自帶提供了程式接口描述檔。

Anchor 生成的接口描述檔(IDL)

假設你的Solana Program是用Anchor來寫的, 當你在anchor build 建構程式時, 你會發現在./target/idl/ 下會生成出一個json檔。

這檔案稱為IDL (Interface Description Language), 是一個描述著程式的instructions接口﹑account結構類型的定義描述檔。

像這樣:

{
  "version": "0.1.0",
  "name": "XXXXXX",
  "instructions": [
    {
      "name": "registerKey",
      "accounts": [
        {
          "name": "signer",
          "isMut": true,
          "isSigner": true
        },

        ......
      ],
      "args": [
        {
          "name": "data",
          "type": {
            "defined": "RegisterKeyData"
          }
        }
      ]
    },

    ......

  ],
  "accounts": [
    {
      "name": "RegisterKeyData",
      "type": {
        "kind": "struct",
        "fields": [
          {
            "name": "keyAddress",
            "type": "publicKey"
          },
          {
            "name": "exp",
            "type": "u64"
          },
          {
            "name": "name",
            "type": "string"
          }
        ]
      }
    },

    ......

  ],
  "errors": [
    {
      "code": 6000,
      "name": "KeyNameTooLong",
      "msg": "key name too long"
    },

    ......

  ]
}

例如上例中可看到:

  • 定義了個名為registerKey的Instruction。

  • 這instruction需要引用到一堆accounts。

  • 這instruction的instruction data內容的type是 RegisterKeyData。

在"accounts"底下也能找到RegisterKeyData這個type的結構:

  • 第一個field是keyAddress, type是publicKey。

  • 第二個field是exp, type是u64。

  • 第二個field是name, type是string。

在"errors"底下也能看到error code描述。

餘此類推......

這描述檔不一定有齊所有接口資訊, 但已足夠讓人們去了解大致的數據結構了。

但如果我們是寫Solana program的, 是如何把這些資訊給公眾共享呢?

答案是, 我們能把它上傳到鏈上！

上傳IDL到鏈上, 在區塊鏈瀏覽器查看

使用 Anchor CLI , 就能把IDL上傳到鏈上。

然後在區塊鏈瀏覽器上查看程式的地址內容, 例如這個:
https://solscan.io/account/2FxWeRCPnvaxQpB4mMFDgW2nbCJm74BVKnJ27ARcfSdt?cluster=devnet#anchorProgramIDL

我們就能看到有Anchor Program IDL 與Accounts Data 這兩個tab了。圍繞IDL及數據的資訊都在這些tab之下了。

Anchor Program IDL 底下, 能看到Instructions, Accounts等資訊, 都是從IDL檔提取的資訊, 像是前面提及過的 registerKey 這instruction。

看那個Accounts 底下的RegisterKeyData , 不就是和之前我們看到的IDL那樣一樣嗎?

然後我們再看看Accounts Data 這個tab:

在這裡我們能選擇account, 然後粗略的查看到各account底下的真實數據。
從圖中可以直接看到數據，所以其實solscan是已經盡量幫我們做了數據解析的動作了。

如果你是在寫Solana的web3 client去call你的鏈上程式, 那你可以配合使用Anchor的JS client library:

https://www.npmjs.com/package/@coral-xyz/anchor

用這個去做的話, Anchor會幫你做了好些編碼及解析的功夫了。有興趣可以網上找找教學，但這篇文章就此略過了。

SolanaWeb3