npm package: @nexaid/network-js-sdk
Description: Network js sdk
Author: nexaid
Latest version: 1.0.1

# NexaID Network JS SDK

[English](./README.md)

用于 NexaID 网络证明流程的 TypeScript SDK，覆盖任务提交、证明执行、结果轮询与可退款余额提取。

## 概览

`@nexaid/network-js-sdk` 提供高层客户端 `NexaIDNetwork`，封装了以下能力：

- 任务合约操作（提交/查询/提取）
- Attestor 节点信息查询
- ZK-TLS 证明流程编排
- 链上结果轮询

## 安装

```bash
npm install @nexaid/network-js-sdk
# 或
yarn add @nexaid/network-js-sdk
# 或
pnpm add @nexaid/network-js-sdk
```

## 前置条件

### 1. 支持链

当前内置支持：

- `133`（HashKey Chain Testnet）

可在运行时查看：

```ts
import { NexaIDNetwork } from '@nexaid/network-js-sdk';

const sdk = new NexaIDNetwork();
console.log(sdk.supportedChainIds); // [133]
```

### 2. Provider 形态

`init(provider, chainId)` 支持：

- EIP-1193 provider（例如 `window.ethereum`）
- 可用于读链（以及写链）的 viem client

如需调用写链方法（`submitTask`、`withdrawBalance`），钱包账户必须已连接并授权签名。

### 3. 浏览器扩展桥接（attestation 必需）

证明流程依赖浏览器环境中的 NexaID 扩展桥接能力。
若扩展桥接不可用，attestation 初始化会失败。

### 4. 运行时说明

SDK 主要面向浏览器 dApp（内部使用了 `window`、`navigator`、`WebSocket` 等浏览器 API）。

## 快速开始

```ts
import { NexaIDNetwork } from '@nexaid/network-js-sdk';

async function main() {
  const provider = window.ethereum;
  if (!provider) throw new Error('未检测到 EIP-1193 钱包 Provider');

  const sdk = new NexaIDNetwork();

  // 1) 初始化 SDK，并连接到支持链
  await sdk.init(provider, 133); // HashKey Chain Testnet

  const templateId = 'YOUR_TEMPLATE_ID';
  const userAddress = 'YOUR_WALLET_ADDRESS';

  // 2) 提交任务
  const submitRes = await sdk.submitTask({
    templateId,
    address: userAddress
  });

  // 3) 发起 attestation
  const attestRes = await sdk.attest({
    templateId,
    address: userAddress,
    ...submitRes
    // 可选高级参数：
    // extendedParams: JSON.stringify({ scene: 'demo' }),
    // allJsonResponseFlag: 'true',
  });

  // 4) 轮询链上最终结果
  const taskResults = await sdk.verifyAndPollTaskResult({
    taskId: submitRes.taskId,
    reportTxHash: attestRes[0]?.reportTxHash
  });

  console.log('Task results:', taskResults);

  // 5) 可选：提取可退款余额
  // const settledTaskIds = await sdk.withdrawBalance();
  // console.log('Withdraw settled task IDs:', settledTaskIds);
}

main().catch(console.error);
```

## API 参考

### `init(provider, chainId)`

初始化 SDK 内部状态与对应链的合约实例。

- 参数：
  - `provider: any`
  - `chainId: number`
- 返回：
  - `Promise<true>`
- 常见失败：
  - `chainId` 不受支持
  - provider 实际连接链与目标链不一致
  - provider 形态不受支持

### `submitTask({ templateId, address })`

在链上提交 attestation 任务。

- 参数：
  - `templateId: string`
  - `address: string`
- 返回：
  - `Promise<{ taskId; taskTxHash; taskAttestors; submittedAt }>`

### `attest(params)`

对选定 attestor 节点执行证明，并返回原始证明结果。

- 必填参数：
  - `templateId: string`
  - `address: string`
  - `taskId: string`
  - `taskTxHash: string`
  - `taskAttestors: string[]`
- 可选高级参数：
  - `additionParams`、`attMode`、`attConditions`、`backUrl`、`computeMode`、`extendedParams`、`allJsonResponseFlag`
- 返回：
  - `Promise<RawAttestationResult[]>`

### `verifyAndPollTaskResult({ taskId, reportTxHash?, intervalMs?, timeoutMs? })`

轮询任务状态，在结果可用或超时/失败条件触发时返回。

- 必填参数：
  - `taskId: string`
- 可选参数：
  - `reportTxHash?: string`
  - `intervalMs?: number`（默认 `2000`）
  - `timeoutMs?: number`（默认 `60000`）
- 返回：
  - `Promise<TaskResult[]>`

### `withdrawBalance(tokenSymbol = TokenSymbol.ETH, limit = 100)`

提取可退款任务费用。

- 参数：
  - `tokenSymbol?: TokenSymbol`
  - `limit?: number`
- 返回：
  - `Promise<settledTaskIds>`

### `queryRefundableTasks(address, tokenSymbol = TokenSymbol.ETH, offset = 0, limit = 100)`

查询未结算任务，并返回当前按超时规则可退款的任务数量。

- 返回：
  - `Promise<number>`

### `queryTaskDetail(taskId)`

查询任务原始详情。

- 返回：
  - `Promise<TaskInfo-like object>`

### `queryTaskTimeout()`

获取合约侧任务超时时间。

- 返回：
  - `Promise<number>`

### `getReportTxReceipt(reportTxHash, confirmations = 1, timeoutMs = 60000)`

等待并返回交易回执。

### `getAllJsonResponse(taskId)`

获取缓存的完整 JSON 响应（仅在 attestation 时设置 `allJsonResponseFlag: 'true'` 才会写入）。

- 返回：
  - `string | undefined`（实际结构依赖扩展返回）

## 迁移说明（Primus -> NexaID）

如果你之前文档/代码基于 Primus 包命名：

- 包导入：
  - 从旧 Primus 包路径
  - 改为 `@nexaid/network-js-sdk`
- 类名：
  - 从 `PrimusNetwork`
  - 改为 `NexaIDNetwork`
- 推荐流程保持一致：
  - `init` -> `submitTask` -> `attest` -> `verifyAndPollTaskResult` -> 可选 `withdrawBalance`

## 错误处理与排查

### 常见 SDK 错误信息

- `chainId is not supported`
- `Please connect to the chain with ID ... first.`
- `user rejected transaction`
- `insufficient balance`
- `may insufficient balance`
- `Nothing to refund`

### 排查清单

- 确认钱包网络在 `supportedChainIds` 之内。
- 确认钱包账户已连接且具备交易签名权限。
- 确认浏览器中 NexaID 扩展桥接可用（attestation 依赖）。
- 如遇轮询超时，可适当增大 `timeoutMs` 后重试。

## License

ISC