开发工具与完整接入示例

运行 SDK 自带浏览器示例，使用模拟钱包测试接入，并在不主动申请钱包权限的默认模式下检查 Provider 接口兼容性。

以下工具随 SDK 0.1.0 分发，使用独立入口。导入 SDK 主入口不会加载 mock，也不会运行诊断。

​

运行浏览器示例

在其他项目安装 SDK 压缩包后执行：

node node_modules/@arksat/wallet-sdk/examples/serve.mjs

打开 http://127.0.0.1:4174。默认使用模拟钱包：连接、发送，再点击 Simulate confirmation。示例包含能力检查、显式历史权限、具名结果、状态查询、等待取消、事件清理和账户变化处理。

使用真实插件时，在连接前关闭模拟选项并填写实际收款地址。真实模式会请求钱包授权并移动资金，要求插件声明支持 getTransaction。返回 txid 只代表提交；failed、cancelled、recoverable 使用不同提示，不自动重试付款。

​

模拟钱包

import { createArksatClient, waitForTransaction } from '@arksat/wallet-sdk'
import { createMockProvider } from '@arksat/wallet-sdk/mock'

const provider = createMockProvider({ balance: 10000 })
const client = createArksatClient(provider)
await client.connect({ read: ['transactions'] })
const { txid } = await client.sendToAddress({ address: 'mock:recipient', amount: 1000 })
const waiting = waitForTransaction(provider, txid)
provider.mock.setTransactionStatus(txid, 'confirmed')
console.log((await waiting).status)

测试控制方法：rejectNext()、setLocked(boolean)、setAccount(address)、setTransactionStatus(txid, status)。可选 approve(method) 回调支持异步批准或拒绝。读取不主动授权；权限升级和资金操作经过确认，并检查等待期间的上下文变化。代币使用精确最小单位字符串，相同资产的重复分配先汇总检查，避免超额扣减。

数据仅保存在内存，不注入 window.arksat，不签名、不广播、不计算费用、不校验真实地址的密码学编码。地址、交易 ID 和确认均为模拟值，只声明已经实现的方法。切换账户或网络会清空模拟余额和历史；修改失败状态不会模拟退款或退回余额。它用于界面和接入测试，不模拟底层协议。

​

接口兼容性检查

import { runConformance } from '@arksat/wallet-sdk/conformance'

const report = await runConformance(provider)
console.table(report.checks)

默认检查能力声明、公开连接状态和事件订阅清理。不会调用 connect、申请权限、签名或发送。每项默认超时 5000 毫秒；诊断超时不能取消已经发送到插件的 RPC。

用户已经授权后，可主动开启读取：

const report = await runConformance(provider, {
  readAuthorized: true,
  transactionId: txid,
  timeoutMs: 5000,
})

readAuthorized 读取余额和资产。transactionId 单独查询指定记录，需要 transactions 权限。缺少权限时该项检查失败，不自动弹窗索取。通过检查只代表所检查的接口行为符合预期，不是安全审计或付款凭证。

​

按 ID 查询交易

const capabilities = await client.getCapabilities()
if (!capabilities.methods.includes('getTransaction')) throw new Error('请更新插件')
await client.connect({ read: ['transactions'] })
const tx = await client.getTransaction({ txid })

支持交易 txid 或钱包记录 ID，查询当前钱包快照保留的全部活动，不受历史分页 100 条限制。它不查询全局链上索引；返回 null 只代表未找到保留的记录，不证明付款从未发生。无权限或历史尚不可用时抛出错误。

waitForTransaction 优先使用该方法；没有该便捷方法的旧 Provider 继续回退到最近 100 条历史。非 pending 状态即返回，调用方仍须判断 status 后再显示成功。见事件文档和方法契约。

超时与轮询选项要求有限的毫秒数，范围 0–2147483647；无效值抛出 TypeError。waitForTransaction 的实际轮询间隔最短为 1000 毫秒。兼容性诊断的 timeoutMs 必须大于 0。