NexaID Network JS SDK

English

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

概览

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

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

安装

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

前置条件

1. 支持链

当前内置支持：

• 84532（Base Sepolia）
• 8453（Base Mainnet）

可在运行时查看：

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

const sdk = new NexaIDNetwork();
console.log(sdk.supportedChainIds); // [84532, 8453]

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）。

快速开始

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, 84532); // Base Sepolia

  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