wagmi 中 waitForTransactionReceipt：等待交易上链并获取收据的完整指南

wagmi 中 waitForTransactionReceipt：等待交易上链并获取收据的完整指南

发布时间：2026/9/17 22:45:30
wagmi 中 waitForTransactionReceipt：等待交易上链并获取收据的完整指南 wagmi 中 waitForTransactionReceipt等待交易上链并获取收据的完整指南【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本篇技术指南以wagmi/core的waitForTransactionReceiptAction 为核心讲解如何在以太坊应用中等待一笔交易被打包进区块、获取交易收据并优雅处理交易回滚revert与被替换replaced/repriced/cancelled等真实场景。读完本文你将掌握该 Action 的导入方式、全部参数chainId、confirmations、onReplaced、hash、pollingInterval的用法与默认行为理解其底层实现原理并能结合 TanStack Query 与 React Hook 在实战项目中落地。功能概述waitForTransactionReceipt会持续等待指定交易被包含进某个区块一旦交易上链立即返回对应的TransactionReceipt交易收据。它有两个值得关注的内置行为交易回滚检测如果最终交易状态为reverted该 Action 会主动抛出错误而不是静默返回一个失败状态的收据替换检测支持识别交易被替换的情况例如用户提高了 gas 加速交易、或取消交易可配合onReplaced回调处理。这意味着你可以在发送交易如sendTransaction、writeContract之后用它把「等待确认」这段异步过程收敛为一次可等待的 Promise让流程代码更线性、更可预测。Import从wagmi/core直接导入import { waitForTransactionReceipt } from wagmi/core同时wagmi/core还导出了配套的类型import { type WaitForTransactionReceiptParameters } from wagmi/core import { type WaitForTransactionReceiptReturnType } from wagmi/core import { type WaitForTransactionReceiptErrorType } from wagmi/core其中WaitForTransactionReceiptErrorType底层透传自 viem 的WaitForTransactionReceiptErrorType见 实现源码。UsagewaitForTransactionReceipt是典型的 wagmi 风格函数第一个参数是 Config 实例第二个参数是调用参数对象。import { waitForTransactionReceipt } from wagmi/core import { config } from ./config const transactionReceipt waitForTransactionReceipt(config, { hash: 0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d, })示例中使用的config来自仓库内共享的配置片段 site/snippets/core/config.ts它是通过createConfig创建、同时配置了mainnet与sepolia两条链的典型配置import { createConfig, http } from wagmi/core import { mainnet, sepolia } from wagmi/core/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })在实际调用中该函数是异步的因此通常配合await使用const transactionReceipt await waitForTransactionReceipt(config, { hash: 0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d, })底层调用链从 actions/waitForTransactionReceipt.ts 的源码可以看到该 Action 的实现遵循一条清晰的责任链从参数中解构出chainId与timeout其余参数透传给 viem通过config.getClient({ chainId })获取对应链的 viem Client使用getAction挂载 viem 的waitForTransactionReceipt并执行等待若收据状态为reverted则进一步通过getTransactioncall回溯交易的执行尝试解析出 revert 的具体原因见下文「错误处理」最终返回的收据上会额外附加chainId字段值为client.chain.id。测试用例 actions/waitForTransactionReceipt.test.ts 验证了该行为的正确性在sendTransaction发送交易并mine一个区块后waitForTransactionReceipt解析结果应匹配{ chainId: 1, transactionHash: hash }。Parameters参数类型为WaitForTransactionReceiptParameters它由 viem 的WaitForTransactionReceiptParameters与 wagmi 的ChainIdParameter组合而成见 实现源码因此同时支持 viem 层的全部等待参数与 wagmi 层的链选择参数。import { type WaitForTransactionReceiptParameters } from wagmi/corechainId类型config[chains][number][id] | undefined作用指定从哪条链获取数据。当 Config 中配置了多条链时通过chainId明确目标链import { waitForTransactionReceipt } from wagmi/core import { mainnet } from wagmi/core/chains import { config } from ./config const transactionReceipt await waitForTransactionReceipt(config, { chainId: mainnet.id, hash: 0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d, })省略时使用 Config 当前的默认链。confirmations类型number | undefined作用等待多少个确认即目标交易之后又打包了多少个区块后才 resolve。默认值取决于 viem 层定义通常为 1。在需要更高安全性的场景如大额转账、跨链桥操作可提高确认数import { waitForTransactionReceipt } from wagmi/core import { config } from ./config const transactionReceipt await waitForTransactionReceipt(config, { confirmations: 2, hash: 0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d, })onReplaced类型(({ reason: replaced | repriced | cancelled; replacedTransaction: Transaction; transaction: Transaction; transactionReceipt: TransactionReceipt }) void) | undefined作用当交易被替换时触发的可选回调。交易被替换通常有三种原因replaced被新交易替代、repriced被重新定价/加速、cancelled被取消。回调参数中包含被替换的旧交易、当前生效的新交易以及最终收据可用于 UI 提示或业务补偿逻辑import { waitForTransactionReceipt } from wagmi/core import { config } from ./config const transactionReceipt await waitForTransactionReceipt(config, { hash: 0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d, onReplaced: replacement console.log(replacement), })hash类型0x${string}作用要等待的交易哈希。这是唯一必填参数。注意在 query 层的实现中hash也是启用查询的必要条件——见 query/waitForTransactionReceipt.ts 中enabled: Boolean(options.hash ...)的逻辑import { waitForTransactionReceipt } from wagmi/core import { config } from ./config const transactionReceipt await waitForTransactionReceipt(config, { hash: 0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d, })pollingInterval类型number | undefined作用轮询频率单位毫秒。默认值继承自 Config 的pollingInterval配置参见 createConfig 文档 中的相关说明。轮询间隔越小交易上链后被感知的延迟越低但对 RPC 节点的请求压力也越大实际使用时建议在体验与成本之间取平衡import { waitForTransactionReceipt } from wagmi/core import { config } from ./config const transactionReceipt await waitForTransactionReceipt(config, { hash: 0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d, pollingInterval: 1_000, })Return Typeimport { type WaitForTransactionReceiptReturnType } from wagmi/core返回值为 viem 的TransactionReceipt类型即标准交易收据对象其中包含transactionHash、blockNumber、status、gasUsed、logs事件日志等字段。与 viem 原生返回略有不同的是wagmi 的返回类型是泛型的它会根据传入的chainId推导出对应的链类型并在收据上附加chainId字段见 实现源码 与第 93-96 行的返回逻辑方便调用方无需额外记录来源链。Errorimport { type WaitForTransactionReceiptErrorType } from wagmi/coreWaitForTransactionReceiptErrorType继承自 viem 的错误类型体系任何等待失败如 RPC 错误、交易最终回滚都会以该类型抛错。回滚错误的原因解析最值得关注的错误场景是交易被回滚。源码在收到receipt.status reverted后并不会简单地抛出一个通用错误而是会执行一段「原因回溯」逻辑见 实现源码通过getTransaction获取原交易数据通过call以交易相同的参数account、data、gas 价格等重放执行捕获 revert 数据若code.data存在则用hexToString将数据中第 138 个字符之后的部分解码为 revert reason即 Solidityrevert(...)或require(cond, ...)中的字符串否则返回unknown reason整个过程受withTimeout保护超时上限为min(timeout, 10_000)毫秒timeout为 0 时按 10 秒处理超时同样回退为unknown reason避免原因解析挂起。测试用例 actions/waitForTransactionReceipt.test.ts 验证了这一点对一个已知回滚的交易调用该函数会抛出包含Execution reverted with reason: PartyBid::claim: contribution already claimed.详细信息的错误。另一组测试第 62-126 行则验证了当回滚原因解析链路中的eth_call无限挂起时函数会在超时后以unknown reason拒绝且 RPC 调用顺序为eth_getTransactionReceipt→eth_getTransactionByHash→eth_call符合上述实现。因此在实际业务中你可以用try/catch捕获回滚错误并向用户展示真实原因而不是笼统提示「交易失败」。TanStack Query 集成wagmi/core还提供了 query 层封装让waitForTransactionReceipt无缝接入 TanStack Query 的缓存与状态管理import { type WaitForTransactionReceiptData, type WaitForTransactionReceiptOptions, type WaitForTransactionReceiptQueryFnData, type WaitForTransactionReceiptQueryKey, waitForTransactionReceiptQueryKey, waitForTransactionReceiptQueryOptions, } from wagmi/core/query对应入口文件为 query/waitForTransactionReceipt.ts核心要点waitForTransactionReceiptQueryOptions(config, options)生成标准 query options其中queryKey为[waitForTransactionReceipt, { ...参数 }]enabled在未提供hash时自动为false测试见 query/waitForTransactionReceipt.test.tsqueryFn 内部会以参数中的hash调用 action 层并把onReplaced回调透传下去。React Hook 封装在 React 应用中更常用的入口是useWaitForTransactionReceiptHook实现见 packages/react/src/hooks/useWaitForTransactionReceipt.tsimport { useWaitForTransactionReceipt } from wagmi const { data: receipt, isLoading, isError } useWaitForTransactionReceipt({ hash, })该 Hook 通过useConfig读取全局 Config通过useChainId获取当前链并在未显式传chainId时自动回退到当前链然后基于waitForTransactionReceiptQueryOptions驱动useQuery因此返回的是标准 TanStack Query 结果data、isLoading、isSuccess、isError等。典型的组合用法是配合写操作const { data: hash } useSendTransaction() const { data: receipt } useWaitForTransactionReceipt({ hash })当hash存在时查询自动启用一旦交易上链receipt即可用于展示成功状态、解析事件日志或触发后续业务。小结waitForTransactionReceipt是构建「发送 → 等待 → 确认 → 后续处理」完整交易流程的关键一环。总结其核心要点必填hash其余参数chainId、confirmations、onReplaced、pollingInterval均为可选交易回滚时主动抛错并尽力解码出 revert reason供 UI 与业务层呈现通过onReplaced感知交易被替换/加速/取消的情况返回收据自带chainId便于多链场景下溯源在 React 项目中优先使用useWaitForTransactionReceiptHook天然获得 TanStack Query 的缓存、重试与状态管理能力。更多框架适配Vue、Solid与底层 viem 行为可分别参考 Vue 的 composable 封装 与 Solid 的 primitive 封装 目录下对应的等待收据实现。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考