wagmi Tempo 写操作参数详解feeToken、feePayer、nonceKey 与时间窗控制全解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本文围绕 wagmi 文档站中的共享参数页 tempo-write-parameters 展开系统讲解 Tempo 链上写类动作write actions通用的交易控制参数。读完你将掌握如何为 Tempo 交易指定付费代币feeToken与代付方feePayer、如何用nonceKey与validBefore/validAfter控制交易的有效性与包含时机以及如何正确区分*Sync与非*Sync动作下throwOnReceiptRevert的语义差异。一、这是什么Tempo 写操作参数的共享文档页site/shared/tempo-write-parameters.md 是 wagmi 文档站的一个共享片段文件。它本身不独立成页而是通过include指令被大量 Tempo 动作文档页复用例如 fee.setUserToken 页面的末尾就写着!--include: shared/tempo-write-parameters.md--这类文档页对应的是wagmi/core中Actions命名空间下的 Tempo 动作。从 动作入口 可以看到Tempo 动作按业务域拆分为 10 个模块amm、dex、faucet、fee、nonce、policy、reward、token、wallet、zone。其中凡是会发起交易的写动作如fee.setUserToken、zone.depositSync、wallet.transfer等除了各自独有的业务参数外都支持同一组交易控制参数——本共享页正是这组通用参数的权威说明包含 11 个字段参数类型默认值说明accountAccount \| Address当前已连接的 Wagmi 账户发送交易的账户feeTokenAddress \| bigint—交易手续费代币TIP-20 代币地址或 IDfeePayerAccount \| true—手续费代付方Viem Account 或true使用 Fee Payer Servicegasbigint—交易 gas 上限maxFeePerGasbigint—每 gas 最大费用maxPriorityFeePerGasbigint—每 gas 最大优先级费noncenumber—交易 noncenonceKeyexpiring \| bigint—交易的 nonce keyvalidBeforenumber—交易必须在该 Unix 时间戳前被包含validAfternumber—交易仅可在该 Unix 时间戳后被包含throwOnReceiptRevertbooleantrue回执显示 revert 时是否抛错仅对*Sync动作生效下面逐个结合仓库源码展开。二、account谁来发这笔交易account的类型是Account | Address缺省时回落到当前已连接的 Wagmi 账户。这一行为可以从写动作的实现模式中确认以 fee.setUserToken 为例实现体先解构出account, chainId, connector然后调用getConnectorClient(config, { account, assertChainId: false, chainId, connector })解析出带账户的 viem 客户端再交给底层的Actions.fee.setUserToken(client, parameters)执行。也就是说传了account时它会覆盖连接器当前账户用于用指定账户发交易的场景没传时由连接器的已连接账户自动补全若最终客户端上没有账户动作会抛出错误例如 zone.depositSync 中的断言if (!account_) throw new Error(accountis required.)。值得注意的一个类型细节这些写动作的account等交易覆盖字段在类型层面被刻意设为可选。utils.ts 定义了OptionalTransactionOverrides类型把account、gas、maxFeePerGas、maxPriorityFeePerGas、nonce这五个字段从 viem 原始参数类型中放宽为可选——因为 wagmi 层会从连接上下文补全账户、nonce 等值。这解释了为什么同一组参数在纯 viem 客户端里可能必填而在 wagmi 动作里却可以省略。三、feeToken 与 feePayerTempo 的付费机制Tempo 与普通 EVM 链最大的差异之一交易手续费可以用 TIP-20 代币支付且可以由第三方代付。这两个参数正是为此设计的。feeToken类型为Address | bigint即地址或 ID。仓库测试用例印证了地址写法amm.test.ts 中以feeToken: tokenAddress传入。当传入bigint形式的代币 ID 时内部会通过TokenId.toAddress(...)之类的工具将其还原为地址zone.ts 中depositSync的处理即TokenId.toAddress(token)因此两种写法等价选更顺手的一种即可。feePayer类型为Account | true传入一个 ViemAccount指定具体账户作为代付方传入true表示使用 Fee Payer Service 代付即不显式指定账户而是把付费决策交给 Tempo 的 Fee Payer 服务端。各动作的类型测试统一以feePayer: true来校验该字段的可传性如 amm.test-d.ts、fee.test-d.ts、policy.test-d.ts而从 wallet.test.ts 中feePayer: false的用例可以推断运行时底层遵循的是 viem 的Account | boolean参数类型false等价于不启用代付。四、gas、maxFeePerGas、maxPriorityFeePerGas标准 EIP-1559 覆盖项这三个参数语义与 viem 的sendTransaction一致gas是 gas 上限maxFeePerGas与maxPriorityFeePerGas分别是每 gas 费用上限与优先级费上限单位都是 wei类型均为bigint。不传时由客户端自动估算传入即覆盖估算值。在源码层面这些字段属于上面提到的OptionalTransactionOverrides放宽范围utils.ts最终随...tx展开透传给 viem 的交易发送接口——zone.depositSync 中解构出业务字段后把剩余交易字段整体...tx传入viem_sendTransactionSync是这一透传模式的典型示例。五、nonce、nonceKeyTempo 的账户 nonce key模型Tempo 引入nonceKey概念后nonce 不再是单账户单序列而是账户 nonce key维度的多通道序列nonceKey的类型为expiring | bigint传入bigint如1n表示使用自定义 nonce 通道同一账户下不同 key 的 nonce 互不干扰适合并发写、业务分通道等场景传入字符串expiring表示使用可过期nonce 语义与下面两个时间窗参数配合可实现交易可在一定时间窗内被丢弃而不污染正常 nonce 序列的行为。配套的读取动作是nonce.getNonce其 JSDoc 示例直接演示了带 key 的查询方式nonce.tsconst nonce await Actions.nonce.getNonce(config, { account: 0x..., nonceKey: 1n, })而 nonce.ts 源码 中对nonceKey的校验if (nonceKey undefined) throw new Error(nonceKey is required.)表明按 key 读取 nonce 时该字段是必需的。写动作中nonce则是普通的number型覆盖项不传由客户端按对应 key 自动获取。六、validBefore 与 validAfter交易有效时间窗两者都是 Unix 时间戳number秒级validBefore交易必须在此时间戳之前被包含进区块过期则不再被接受validAfter交易只在此时间戳之后才能被包含实现定时生效。这两个参数与nonceKey: expiring组合使用价值最大为交易设定过期即作废的窗口后即使它迟迟没被打包也不会永久占用 nonce 位后续重试不受阻塞。这是 Tempo 针对gasless 代付场景下交易生命周期不确定问题的设计手段。七、throwOnReceiptRevert仅作用于 *Sync 动作throwOnReceiptRevert类型为boolean默认true含义是当交易回执receipt显示执行 revert 时动作直接抛出错误而不是静默返回。文档明确限定该参数只对*Sync动作生效。原因是非*Sync动作在拿到交易 hash 后就返回了此时回执尚不存在无从判断 revert只有*Sync变体会等到交易上链、拿到 receipt 才返回结果。源码印证见 zone.depositSyncconst { account, chainId, connector, throwOnReceiptRevert true, ...rest } parameters随后该值被显式传入viem_sendTransactionSync(client, { ...tx, calls: [...], throwOnReceiptRevert })zone.ts#L657-L678。如果你需要即便 revert 也想拿到回执和事件自行处理把throwOnReceiptRevert设为false即可。Sync 与非 Sync 的完整差异以 fee.setUserToken 文档 为例两种用法对比// Sync 版等待交易被包含后返回 { receipt }可配合 throwOnReceiptRevert const { receipt } await Actions.fee.setUserTokenSync(config, { token: 0x20c0000000000000000000000000000000000001, }) // 非 Sync 版立即返回 hash手动等待回执 const hash await Actions.fee.setUserToken(config, { token: 0x20c0000000000000000000000000000000000001, }) const receipt await waitForTransactionReceipt(config, { hash })八、端到端示例一次带 Tempo 特有参数的写操作把上述参数组合起来一个典型的 Tempo 写动作调用如下以设置默认费用代币为例配置参考 config-tempo.tsimport { Actions } from wagmi/core/tempo const result await Actions.fee.setUserTokenSync(config, { token: 0x20c0000000000000000000000000000000000001, // TIP-20 代币 feeToken: 2n, // 用 TIP-20 代币 ID 支付手续费 feePayer: true, // 由 Fee Payer Service 代付 nonceKey: expiring, // 过期型 nonce 通道 validBefore: Date.now() / 1000 300, // 5 分钟内必须被包含 throwOnReceiptRevert: true, // revert 时抛错默认即 true }) console.log(result.receipt.transactionHash)调用链路在源码中是wagmi 动作如 setUserTokenSync→getConnectorClient解析账户/链 → 透传给viem/tempo的Actions执行。wagmi 层负责账户与连接上下文Tempo 的付费模型、nonce key、时间窗等语义均由底层 viem Tempo 动作实现这组共享参数就是两层之间的公共契约。九、在框架适配器中的对应形态同样的参数体系在 React / Vue / Solid 的响应式 API 中同样可用tempo hooks 文档 中的每个写动作都有对应的useXxxhook如fee.useSetUserToken其 mutation 参数与 Actions 的写参数一致即上文所有字段在 hook 的mutate参数中同样生效。查阅某一具体动作时可对照site/tempo/actions/下的动作文档参数表部分均 include 本共享页与site/tempo/hooks/下的同名 hook 文档。十、速查与注意事项适用前提这组参数仅在 Tempo 链如tempo、tempoModerato等wagmi/core/chains提供的链的写动作上有效普通 viem 风格的sendTransaction/writeContract不支持feeToken、nonceKey、validBefore等字段默认值只有一个throwOnReceiptRevert默认true其余参数缺省均交由客户端/链侧默认行为决定*Sync语义只有 Sync 变体会等回执throwOnReceiptRevert也因此只对 Sync 变体有意义追求吞吐时用非 Sync 变体 waitForTransactionReceipt手动等待地址或 ID 二选一feeToken、token等 TIP-20 字段普遍接受Address | bigintbigint形式为代币 ID内部会做地址还原feePayer: true的边界它依赖 Tempo 的 Fee Payer Service仅在该服务可用的网络上成立本地开发或测试网请显式传入Account或省略该字段如测试中feePayer: false的写法。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考