> ## 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.

# 事件与交易记录

> 订阅钱包状态变化，查询和等待交易状态。

## getTransactionHistory

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

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

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

## getTransaction

参数为 `{ txid: string }`，返回 `Promise<ArksatTransaction | null>`。Client 与 Provider 都需要显式 `transactions` 读取权限，调用前先检查方法支持情况。

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

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

## on / off

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

```ts theme={null}
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。账户、网络或锁定状态变化后应更新页面上下文。[事件接入指南](https://docs.arksat.xyz/events.md)。

## subscribe

SDK 提供取消函数，便于组件卸载时清理：

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

## waitForTransaction

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

返回 `Promise<ArksatTransaction>`。可选 `signal: AbortSignal`；默认超时 120 秒、轮询 3 秒，轮询最短 1 秒。优先通过 getTransaction 查询钱包保留的全部活动；不提供该方法的旧 Provider 回退到最近 100 条。遇到非 pending 状态即返回，可能包含 failed、cancelled、recoverable，并不保证成功。

上下文变化会中止等待。超时后先查询记录，避免重复付款；通知或钱包状态不应作为商户付款证明。


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