跳到主要內容

輔助方法

GraphQLClient 類別是與由 OCAP 驅動的區塊鏈互動的主要介面。它提供了一套全面的方法，用於查詢鏈上狀態、發送交易以及訂閱即時事件。此類別的設計旨在能於 Node.js 和瀏覽器環境中無縫運作。

客戶端初始化

javascript
const GraphQLClient = require('@ocap/client');

// 連線到 Beta 鏈
const client = new GraphQLClient('https://beta.abtnetwork.io/api');

(async () => {
  const res = await client.getChainInfo();
  console.log('Connected to chain:', res.info.network);
})();

本節為 GraphQLClient 類別的核心輔助方法提供了詳細的參考。

建構函式

new GraphQLClient(endpoint, autoInit)

建立一個新的 GraphQLClient 實例。

參數

  • endpoint string (required) — 區塊鏈節點的 GraphQL 端點絕對 URL（例如：https://beta.abtnetwork.io/api）。
  • autoInit boolean (default: true) — 若為 true，客戶端將在初始化時自動取得並快取必要的鏈上資訊（「上下文」）。建議在大多數使用案例中啟用此選項。

範例

建立客戶端實例

javascript
const client = new GraphQLClient('https://beta.abtnetwork.io/api', true);

核心方法

這些方法提供了與客戶端和鏈互動的基礎功能。

getContext()

取得並快取必要的鏈上資訊，例如鏈 ID、原生代幣詳情以及交易費用設定。如果在建構函式中啟用了 autoInit，此方法會自動被呼叫。後續的呼叫將回傳快取的上下文。

回傳值

  • Promise object — 一個解析為包含鏈元資料的上下文物件的 Promise。
    • chainId string — 區塊鏈網路的唯一識別碼。
    • consensus string — 共識引擎的版本。
    • token object — 關於原生代幣的資訊。
      • address string — 原生代幣合約的位址。
      • decimal number — 原生代幣的小數位數。
      • symbol string — 原生代幣的符號（例如：TBA）。
    • txConfig object — 交易費用與 Gas 設定。

範例

取得鏈的上下文

javascript
async function logChainToken() {
  const context = await client.getContext();
  console.log(`Native Token Symbol: ${context.token.symbol}`);
}

logChainToken();

setGasPayer(wallet)

設定一個錢包作為「Gas 支付者」。設定後，此錢包將為透過此客戶端實例發送的交易贊助交易費用，從而為使用者實現無 Gas 體驗。更多詳情，請參閱 Gas 支付 概念指南。

參數

  • wallet WalletObject (required) — 一個錢包物件，具備 address、publicKey 和 secretKey 屬性，並配有 sign 方法。

decodeTx(input)

將多種格式的交易反序列化為人類可讀的 JavaScript 物件。

參數

  • input Buffer | string (required) — 要解碼的交易資料。可以是 Buffer，或 hex、base58、base64 格式的字串。

回傳值

  • object object — 已解碼的交易物件。

getType(name)

根據給定的類型名稱，檢索其 Protobuf 訊息類別。這在需要手動建構或檢查 Protobuf 訊息的進階情境中非常有用。

參數

  • name string (required) — Protobuf 訊息類型的名稱（例如：'Transaction'、'TransferTx'）。

回傳值

  • class | null object — 訊息類別的建構函式，若找不到則為 null。

事件訂閱

客戶端支援透過 WebSocket 進行的即時事件訂閱，讓您的應用程式能即時對鏈上事件作出反應。

subscribe(topic, callback)

建立一個 WebSocket 連線並訂閱一個特定的事件主題。

參數

  • topic string (required) — 要訂閱的事件主題（例如：'newBlock'、'tx'）。
  • callback function (required) — 接收到事件時要執行的函式。它會接收事件負載作為其唯一的參數。

unsubscribe(topic, callback)

移除先前為特定主題註冊的回呼函式。

參數

  • topic string (required) — 要取消訂閱的事件主題。
  • callback function (required) — 要移除的特定回呼函式。

範例

訂閱新區塊

javascript
const handleNewBlock = (block) => {
  console.log(`New block received! Height: ${block.height}`);

  // 接收到一個區塊後取消訂閱
  client.unsubscribe('newBlock', handleNewBlock);
  console.log('Unsubscribed from newBlock events.');
};

client.subscribe('newBlock', handleNewBlock);
console.log('Subscribed to newBlock events...');

代幣工具方法

這些輔助方法簡化了人類可讀的代幣數量與鏈上基礎單位表示之間的轉換。

fromUnitToToken(value)

根據原生代幣的小數位數，將一個值從鏈上的基礎單位（一個大整數字串）轉換為標準的十進位字串。

參數

  • value string (required) — 鏈上基礎單位的金額。

回傳值

  • string string — 標準代幣單位的金額。

fromTokenToUnit(amount)

將一個標準的十進位金額轉換為鏈上的基礎單位表示（一個 BN.js 實例）。

參數

  • amount number | string (required) — 標準十進位格式的代幣金額。

回傳值

  • BN object — 一個代表鏈上基礎單位值的 BN.js 實例。

範例

代幣金額轉換

javascript
async function convertToken() {
  // 將 100 TBA 轉換為其基礎單位
  const unitAmount = await client.fromTokenToUnit(100);
  console.log(`100 TBA is ${unitAmount.toString()} in base units.`);

  // 將其轉換回來
  const tokenAmount = await client.fromUnitToToken(unitAmount.toString());
  console.log(`${unitAmount.toString()} base units is ${tokenAmount} TBA.`);
}

convertToken();

方法探索

客戶端會為所連線的 OCAP 節點支援的每種交易類型動態產生方法。這些探索方法讓您能以程式化的方式列出所有可用的交易相關函式。

getTxSendMethods()

回傳一個包含所有可用的 send...Tx 方法名稱的陣列。這些方法處理簽署和發送交易的完整生命週期。

getTxEncodeMethods()

回傳一個包含所有可用的 encode...Tx 方法名稱的陣列。這些方法準備交易並將其序列化為一個緩衝區，但不會簽署它。

getTxSignMethods()

回傳一個包含所有可用的 sign...Tx 方法名稱的陣列。這些方法會編碼並簽署一筆交易，然後回傳已簽署的交易物件。

getTxMultiSignMethods()

回傳一個包含所有可用的 multiSign...Tx 方法名稱的陣列，用於多重簽章工作流程。

範例

列出可用的交易方法

javascript
const sendMethods = client.getTxSendMethods();
console.log('Available send methods:', sendMethods);
// 範例輸出：[ 'sendPokeTx', 'sendTransferTx', ... ]