Wagmi 库中 useWaitForTransactionReceipt 钩子的交易回滚处理机制分析

问题背景

在区块链DApp开发中，Wagmi库的useWaitForTransactionReceipt钩子用于等待交易收据并获取交易执行结果。然而，开发者发现当交易因gas不足而回滚时，该钩子的行为存在一些值得探讨的地方。

核心问题表现

当交易因gas不足而失败时，useWaitForTransactionReceipt钩子会出现以下现象：

1. 不会立即抛出错误
2. isLoading状态保持为true
3. failureReason和failureCount会被设置
4. 错误状态(error)会延迟几秒后才被设置

技术原理分析

底层机制

这种现象源于Wagmi底层使用的Tanstack Query库的默认行为：

1. 默认会进行3次重试
2. 错误会被静默处理
3. 每次重试之间会有延迟

交易生命周期

1. 交易被发送到区块链网络
2. 节点返回交易收据，包含失败原因
3. Wagmi钩子接收到收据数据
4. Tanstack Query执行重试逻辑
5. 最终确定交易状态

解决方案

方案一：禁用重试机制

开发者可以通过以下方式禁用重试：

// 单个钩子级别禁用
const result = useWaitForTransactionReceipt({
  query: { retry: false }
});

// 全局级别禁用
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: false
    },
  },
});

方案二：自定义错误处理

开发者可以基于failureReason和failureCount自行实现更及时的错误处理逻辑，而不完全依赖error状态。

最佳实践建议

1. 对于关键交易操作，建议禁用重试以获得即时反馈
2. 同时监听failureReason和error状态
3. 根据应用场景平衡用户体验和错误处理的及时性
4. 在UI设计中考虑交易状态的中间态处理

技术思考

虽然Tanstack Query的重试机制在网络请求失败时很有价值，但对于区块链交易这种确定性操作，重试可能并不总是必要。Wagmi未来版本可能会针对区块链交易特性优化这一行为。

开发者应当理解，区块链交易失败与API请求失败有本质区别：前者是确定性状态，后者可能是暂时性网络问题。这种差异应该在错误处理策略中得到体现。