> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arksat.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 事件与交易记录

> 事件订阅、交易记录和状态查询。

订阅使用原始 Provider。`subscribe()` 返回可重复调用的取消函数，组件卸载或路由离开时调用。

```ts theme={null}
import { subscribe, type ArksatProvider } from '@arksat/wallet-sdk'

export function watchWallet(provider: ArksatProvider, refresh: () => void) {
  const stops = [
    subscribe(provider, 'assets:changed', refresh),
    subscribe(provider, 'balance:changed', refresh),
    subscribe(provider, 'account:changed', refresh),
    subscribe(provider, 'network:changed', refresh),
    subscribe(provider, 'wallet:locked', refresh),
    subscribe(provider, 'connection:disconnected', refresh),
  ]
  return () => stops.forEach(stop => stop())
}
```

`refresh` 应重新读取状态；断连 / 锁定时清空敏感展示，账户 / 网络变化时丢弃旧会话，防止旧请求覆盖新数据。刷新失败也要处理。

| 事件 | 数据 |
| - | - |
| `account:changed` | 地址数组 |
| `network:changed` | `mainnet` 或 `mutinynet` |
| `balance:changed`、`assets:changed` | 更新提示或 null，不是完整余额 |
| `transaction:updated`、`transfer:received`、`transfer:settled` | 交易 ID、状态、rail、网络等 |
| `connection:connected` | 空对象 |
| `connection:disconnected` | `{ message }` |
| `wallet:locked`、`wallet:unlocked` | null |

仅提供事件协议 2，旧事件名已移除。事件通知不是付款凭据。

## 历史与等待

```ts theme={null}
import { createArksatClient, waitForTransaction, type ArksatProvider } from '@arksat/wallet-sdk'

export async function trackTransaction(provider: ArksatProvider, txid: string, signal: AbortSignal) {
  const client = createArksatClient(provider)
  // 在用户点击查询时申请，已有权限时不会重复申请。
  await client.connect({ read: ['transactions'] })
  const latest = await client.getTransactionHistory({ limit: 50, offset: 0 })
  const terminal = await waitForTransaction(provider, txid, { signal })
  return { latest, terminal }
}
```

历史按新到旧排列，limit 为 1–100，默认 50，offset 默认 0。新记录可能使分页移动，按交易 ID 去重。这是钱包记录快照，不是全局索引器。

`waitForTransaction` 检查最近 100 条，默认超时 120 秒、轮询间隔 3 秒。上下文变化或读取错误会拒绝，返回任意非 pending 状态，包括 failed、cancelled、recoverable，须检查 status。超时不取消交易，不自动重发。商户收款按对应 rail 独立核验。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.