事件与交易记录 - Arksat

getTransactionHistory

需要网站获得 transactions 读取权限。Client 与 Provider 都接受可选的 { limit?, offset? }，返回 Promise<ArksatTransaction[]>。

await client.connect({ read: ['transactions'] })
const history = await client.getTransactionHistory({ limit: 20, offset: 0 })

记录按最新优先返回。offset 分页不是稳定快照；新记录插入后需按 ID 去重。

on / off

直接在 Provider 上监听和移除事件：

const onNetwork = (network: 'mainnet' | 'mutinynet') => {
  console.log(network)
}
provider.on('network:changed', onNetwork)
// 页面卸载时
provider.off('network:changed', onNetwork)

事件	数据
account:changed	string[]
network:changed	ArksatNetwork
balance:changed / assets:changed	ArksatDataEvent 或 null
transaction:updated / transfer:received / transfer:settled	ArksatTransactionEvent
connection:connected	空对象
connection:disconnected	message 字符串字段
wallet:locked / wallet:unlocked	null

事件协议为 2。账户、网络或锁定状态变化后应更新页面上下文。事件接入指南。 SDK 提供取消函数，便于组件卸载时清理：

import { subscribe } from '@arksat/wallet-sdk'
const stop = subscribe(provider, 'balance:changed', () => {
  // 重新读取余额
})
stop()

waitForTransaction

import { waitForTransaction } from '@arksat/wallet-sdk'
const tx = await waitForTransaction(provider, txid, {
  timeoutMs: 120000,
  pollIntervalMs: 3000,
})

返回 Promise<ArksatTransaction>。可选 signal: AbortSignal；默认超时 120 秒、轮询 3 秒，轮询最短 1 秒。只搜索最新 100 条授权记录，遇到非 pending 状态即返回，可能包含 failed 等状态。上下文变化会中止等待。超时后先查询记录，避免重复付款；通知或钱包状态不应作为商户付款证明。