辅助方法 | ArcBlock

GraphQLClient 类是与 OCAP 驱动的区块链进行交互的主要接口。它提供了一套全面的方法，用于查询链状态、发送交易以及订阅实时事件。它被设计为可以在 Node.js 和浏览器环境中无缝工作。

Client Initialization

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，客户端将在初始化时自动获取并缓存关键的链信息（“上下文”）。对于大多数用例，建议使用此设置。

示例

Creating a Client Instance

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 配置。

示例

Fetching Chain Context

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 进行实时事件订阅，使您的应用程序能够对链上事件做出即时反应。

建立 WebSocket 连接并订阅特定的事件主题。

参数

topic string (required) — 要订阅的事件主题（例如，'newBlock', 'tx'）。
callback function (required) — 接收到事件时执行的函数。它接收事件的有效载荷作为其唯一参数。

unsubscribe(topic, callback)

移除先前为特定主题注册的回调。

参数

topic string (required) — 要取消订阅的事件主题。
callback function (required) — 要移除的特定回调函数。

示例

Subscribing to New Blocks

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...');

Token 工具方法

这些辅助方法简化了人类可读的 token 数量与链上基本单位表示之间的转换。

fromUnitToToken(value)

根据原生代币的小数位数，将一个值从链的基本单位（一个大整数字符串）转换为标准的十进制字符串。

参数

value string (required) — 以链的基本单位表示的数量。

string string — 以标准 token 单位表示的数量。

fromTokenToUnit(amount)

将一个标准的十进制数量转换为链的基本单位表示（一个 BN.js 实例）。

参数

amount number | string (required) — 以标准十进制形式表示的 token 数量。

BN object — 一个表示链基本单位值的 BN.js 实例。

示例

Token Amount Conversion

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 方法名称的数组，用于多重签名工作流。

示例

Listing Available Transaction Methods

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