# 辅助方法

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

```javascript Client Initialization icon=logos: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` 的新实例。

**参数**

<x-field-group>
  <x-field data-name="endpoint" data-type="string" data-required="true">
    <x-field-desc markdown>区块链节点的 GraphQL 端点的绝对 URL（例如 `https://beta.abtnetwork.io/api`）。</x-field-desc>
  </x-field>
  <x-field data-name="autoInit" data-type="boolean" data-default="true" data-required="false">
    <x-field-desc markdown>如果为 `true`，客户端将在初始化时自动获取并缓存关键的链信息（“上下文”）。对于大多数用例，建议使用此设置。</x-field-desc>
  </x-field>
</x-field-group>

**示例**

```javascript Creating a Client Instance icon=logos:javascript
const client = new GraphQLClient('https://beta.abtnetwork.io/api', true);
```

---


## 核心方法

这些方法提供了与客户端和链进行交互的基本功能。

### getContext()

获取并缓存关键的链信息，例如链 ID、原生代币详情和交易费用配置。如果在构造函数中启用了 `autoInit`，此方法会自动调用。后续调用将返回缓存的上下文。

**返回**

<x-field data-name="Promise<object>" data-type="object" data-desc="一个解析为包含链元数据的上下文对象的 promise。">
  <x-field data-name="chainId" data-type="string" data-desc="区块链网络的唯一标识符。"></x-field>
  <x-field data-name="consensus" data-type="string" data-desc="共识引擎版本。"></x-field>
  <x-field data-name="token" data-type="object" data-desc="关于原生代币的信息。">
    <x-field data-name="address" data-type="string" data-desc="原生代币合约的地址。"></x-field>
    <x-field data-name="decimal" data-type="number" data-desc="原生代币的小数位数。"></x-field>
    <x-field data-name="symbol" data-type="string" data-desc="原生代币的符号（例如，TBA）。"></x-field>
  </x-field>
  <x-field data-name="txConfig" data-type="object" data-desc="交易费用和 gas 配置。"></x-field>
</x-field>

**示例**

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

logChainToken();
```

### setGasPayer(wallet)

配置一个钱包作为“gas 支付者”。设置后，该钱包将赞助通过此客户端实例发送的交易的交易费用，从而为用户提供无 gas 体验。更多详情，请参见 [Gas 支付](./core-concepts-gas-payment.md) 概念指南。

**参数**

<x-field data-name="wallet" data-type="WalletObject" data-required="true">
  <x-field-desc markdown>一个钱包对象，具有 `address`、`publicKey` 和 `secretKey` 属性，并配备一个 `sign` 方法。</x-field-desc>
</x-field>

### decodeTx(input)

将各种格式的交易反序列化为人类可读的 JavaScript 对象。

**参数**

<x-field data-name="input" data-type="Buffer | string" data-required="true">
  <x-field-desc markdown>要解码的交易数据。可以是 `Buffer`，也可以是 `hex`、`base58` 或 `base64` 格式的字符串。</x-field-desc>
</x-field>

**返回**

<x-field data-name="object" data-type="object" data-desc="解码后的交易对象。"></x-field>

### getType(name)

检索给定类型名称的 Protobuf 消息类。这在需要手动构建或检查 Protobuf 消息的高级场景中很有用。

**参数**

<x-field data-name="name" data-type="string" data-required="true" data-desc="Protobuf 消息类型的名称（例如，'Transaction', 'TransferTx'）。"></x-field>

**返回**

<x-field data-name="class | null" data-type="object" data-desc="消息类的构造函数，如果未找到则为 null。"></x-field>

---


## 事件订阅

客户端支持通过 WebSocket 进行实时事件订阅，使您的应用程序能够对链上事件做出即时反应。

### subscribe(topic, callback)

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

**参数**

<x-field-group>
  <x-field data-name="topic" data-type="string" data-required="true" data-desc="要订阅的事件主题（例如，'newBlock', 'tx:transfer'）。"></x-field>
  <x-field data-name="callback" data-type="function" data-required="true" data-desc="接收到事件时执行的函数。它接收事件的有效载荷作为其唯一参数。"></x-field>
</x-field-group>

### unsubscribe(topic, callback)

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

**参数**

<x-field-group>
  <x-field data-name="topic" data-type="string" data-required="true" data-desc="要取消订阅的事件主题。"></x-field>
  <x-field data-name="callback" data-type="function" data-required="true" data-desc="要移除的特定回调函数。"></x-field>
</x-field-group>

**示例**

```javascript Subscribing to New Blocks icon=logos: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...');
```

---


## Token 工具方法

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

### fromUnitToToken(value)

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

**参数**

<x-field data-name="value" data-type="string" data-required="true" data-desc="以链的基本单位表示的数量。"></x-field>

**返回**

<x-field data-name="string" data-type="string" data-desc="以标准 token 单位表示的数量。"></x-field>

### fromTokenToUnit(amount)

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

**参数**

<x-field data-name="amount" data-type="number | string" data-required="true" data-desc="以标准十进制形式表示的 token 数量。"></x-field>

**返回**

<x-field data-name="BN" data-type="object" data-desc="一个表示链基本单位值的 BN.js 实例。"></x-field>

**示例**

```javascript Token Amount Conversion icon=logos: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 Listing Available Transaction Methods icon=logos:javascript
const sendMethods = client.getTxSendMethods();
console.log('Available send methods:', sendMethods);
// 示例输出：[ 'sendPokeTx', 'sendTransferTx', ... ]
```
