wagmi Tempo 奖励分发指南reward.distribute动作的同步/异步用法与参数详解【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本篇技术指南聚焦 wagmi 对 Tempo专为支付场景设计的 Layer 1 区块链提供的原生奖励分发动作reward.distribute讲解如何将代币分发给已「选择加入」opted-in的奖励接收者。通过阅读本文你将掌握distributeSync与distribute两种调用形态的差异、事务回执与事件解析的正确姿势以及amount、token等全部参数的含义并能结合源码理解其底层实现链路。什么是reward.distribute在 Tempo 的奖励机制中reward.distribute是核心的发币动作它把指定数量的 TIP-20 代币分发给所有已选择加入的持有人opted-in holders。它的姊妹动作reward.claim则负责让持有人领取累积的奖励——两者构成「分发 → 领取」的完整闭环。在 wagmi 中Tempo 相关的动作统一通过wagmi/tempoReact/Core 通用与wagmi/core/tempo仅 Core入口导出命名空间为Actions。reward.distribute提供两个变体Actions.reward.distribute仅广播交易并返回交易哈希性能最优Actions.reward.distributeSync等待交易被打包确认后才返回直接拿到回执与事件数据。完整的 Tempo 动作清单可参考 actions 总览其中 Reward 分类下还包含reward.claim、reward.getUserRewardInfo、reward.setRecipient、reward.watchRewardDistributed等配套动作。前置准备Tempo 配置所有 Tempo 动作都依赖一个指向 Tempo 链的 wagmiConfig。官方示例使用config-tempo.ts中的配置import { createConfig, http } from wagmi import { tempo } from wagmi/chains import { tempoWallet } from wagmi/tempo export const config createConfig({ connectors: [tempoWallet()], chains: [tempo], multiInjectedProviderDiscovery: false, transports: { [tempo.id]: http(), }, })要点说明connectors: [tempoWallet()]注册 Tempo 专用钱包连接器使账户能够通过钱包完成签名chains: [tempo]只挂载 Tempo 一条链multiInjectedProviderDiscovery: false关闭多注入提供者发现避免浏览器中其他钱包扩展干扰transports为 Tempo 链配置 JSON-RPC 传输层。若从零开始接入请先阅读 Tempo 快速上手并确保安装的viem版本满足要求2.55.2。同步用法distributeSync文档推荐的最简用法是直接调用*Sync变体它会在返回前等待交易被包含进区块因此一次await即可拿到完整的执行结果import { Actions } from wagmi/tempo import { parseEther } from viem import { config } from ./config const { amount, funder, receipt } await Actions.reward.distributeSync(config, { amount: parseEther(1000), token: 0x20c0000000000000000000000000000000000000, }) console.log(Amount:, amount) // log: Amount: 1000000000000000000000n示例细节解读amount: parseEther(1000)使用 viem 的parseEther工具将 1000 个代币换算为最小精度单位的bigint1000000000000000000000n避免浮点误差token传入 TIP-20 代币合约地址返回值中amount为实际分发总量bigintfunder为出资分发奖励的地址receipt为事务回执。异步用法distribute 手动等待如果你对性能有更高要求官方建议使用非*Sync变体它只负责把交易广播出去并返回hash由你决定何时、以何种方式等待确认避免阻塞在等待打包上。import { Actions as viem_Actions } from viem/tempo import { Actions } from wagmi/tempo import { parseEther } from viem import { waitForTransactionReceipt } from wagmi/actions const hash await Actions.reward.distribute(config, { amount: parseEther(1000), token: 0x20c0000000000000000000000000000000000000, }) const receipt await waitForTransactionReceipt(config, { hash }) const { args: { funder, amount } } viem_Actions.reward.distribute.extractEvent(receipt.logs)这段代码揭示了两层调用链Actions.reward.distribute(config, ...)返回hash交易哈希通过 wagmi 的waitForTransactionReceipt轮询链上状态拿到TransactionReceipt由于非Sync变体不解析事件需要借助viem 同名动作的extractEvent从receipt.logs中提取RewardDistributed事件参数funder、amount。这种「先广播、后等待、再解析」的模式适合需要把等待逻辑交给 UI 层如轮询组件、进度提示处理的场景。返回值类型distributeSync以及distribute事件解析后的结果的返回结构如下type ReturnType { /** Total amount distributed */ amount: bigint /** Address that funded the distribution */ funder: Address /** Transaction receipt */ receipt: TransactionReceipt }amount本次实际分发的代币总量以最小精度单位的 bigint 表示funder出资发起分发的地址可通过它追踪奖励资金来源receipt完整的事务回执可用于进一步的日志分析或上链存证。参数详解amount必填类型bigint要分发的代币数量。必须大于 0。推荐用parseEther或parseUnits从十进制字符串构造避免精度丢失。token必填类型AddressTIP-20 代币的合约地址。TIP-20 是 Tempo 协议内置的代币标准对标 ERC-20代币的铸造、转账、审批等操作由协议原生支持。通用写事务参数除上述两个必填参数外reward.distribute还支持一组 Tempo 写事务通用参数与*Sync变体共用完整定义见 tempo-write-parameters.md汇总如下参数类型说明account可选Account \| Address发送事务的账户默认使用已连接的 Wagmi 账户feeToken可选Address \| bigint事务手续费代币可为 TIP-20 代币地址或 IDfeePayer可选Account \| true手续费代付方可为 Viem Account或传true表示使用 Fee Payer Service 代付gas可选bigint事务 gas 上限maxFeePerGas可选bigint每单位 gas 的最大费用maxPriorityFeePerGas可选bigint每单位 gas 的最大优先费小费nonce可选number事务 noncenonceKey可选expiring \| bigint事务 nonce key用于支持并发事务validBefore可选number事务必须被包含进区块的 Unix 时间戳上限validAfter可选number事务可以被包含进区块的 Unix 时间戳下限throwOnReceiptRevert可选boolean默认true仅对*Sync动作生效回执显示回滚时是否抛出错误其中feePayer、feeToken、nonceKey、validBefore/validAfter是 Tempo 事务类型特有的能力feePayer: true可将手续费转嫁给 Fee Payer ServicenonceKey允许同一账户并发发起多条事务而互不阻塞时间窗口参数则可用于调度执行。补充说明在 源码示例 中distribute的参数还出现了seconds: 86400奖励分发的持续时间秒数供调用方按需传入具体字段以你所安装的 viem 版本中Actions.reward.distribute.Parameters类型为准。源码实现链路在 wagmi 仓库中reward.distribute由 packages/core/src/tempo/actions/reward.ts 实现。核心逻辑分三步获取连接客户端从参数中解构account、chainId、connector调用getConnectorClient(config, { account, assertChainId: false, chainId, connector })拿到对应链与账户的 Viem 客户端委托给 viem 动作return Actions.reward.distribute(client, parameters)即 wagmi 侧只是薄封装真正的合约调用与交易构造由viem/tempo的Actions.reward.distribute完成类型收窄通过ChainIdParameter、ConnectorParameter与UnionLooseOmitOptionalTransactionOverrides..., chain的组合在保留所有 Tempo 写事务可选参数的同时剔除掉 viem 层与 wagmi 配置模型不一致的chain字段。distributeSync的封装几乎一致仅调用Actions.reward.distributeSync并返回回执与事件数据。类型层面的约束由 reward.test-d.ts 这类测试文件验证例如必填参数缺失时编译器应报错、可选事务覆盖参数可自由传入。这种「wagmi 负责连接与配置、viem 负责链上交互」的分层意味着reward.distribute与标准 wagmi 动作如useSendTransactionSync共享同一套连接器和账户模型无需额外学习成本。在 React 中使用useDistributeHooks除了命令式 Actionwagmi 还为 React 提供了对应的 TanStack Query Hooks定义在 packages/react/src/tempo/hooks/reward.tsHooks.reward.useDistribute()封装Actions.reward.distribute返回 mutation 结果Hooks.reward.useDistributeSync()封装Actions.reward.distributeSync等待确认后data即携带完整返回值。例如在 reward.useDistribute 文档 中同步变体的用法为import { Hooks } from wagmi/tempo import { parseEther } from viem const distributeSync Hooks.reward.useDistributeSync() // 在用户交互点击按钮、提交表单时调用 mutate distributeSync.mutate({ amount: parseEther(1000), token: 0x20c0000000000000000000000000000000000000, }) console.log(Amount:, distributeSync.data?.amount) // log: Amount: 1000000000000000000000n非Sync变体配合useWaitForTransactionReceipt手动等待确认import { Hooks } from wagmi/tempo import { Actions } from viem/tempo import { parseEther } from viem import { useWaitForTransactionReceipt } from wagmi const distribute Hooks.reward.useDistribute() const { data: receipt } useWaitForTransactionReceipt({ hash: distribute.data }) distribute.mutate({ amount: parseEther(1000), token: 0x20c0000000000000000000000000000000000000, }) if (receipt) { const { args: { funder, amount } } Actions.reward.distribute.extractEvent(receipt.logs) }Hook 的data对应 Action 的返回值类型mutate/mutateAsync的入参对应 Action 的参数类型并通过config与mutation两个可选参数支持自定义配置和 TanStack Query mutation 选项详见 TanStack Query 文档约定 与useMutation参考。配套的 Reward 动作生态要完整落地一套「分发奖励」业务通常还需要以下配套动作全部收录于 actions 总览动作作用reward.setRecipient持有人设置/变更奖励接收地址零地址表示退出reward.getUserRewardInfo查询账户的可领取奖励余额、每代币奖励检查点与接收地址reward.claim持有人领取已累积的奖励reward.watchRewardDistributed订阅RewardDistributed事件可按funder地址过滤典型的业务流程为持有人通过setRecipient选择加入 → 运营方调用distribute分发奖励 → 持有人通过claim领取期间可用getUserRewardInfo查看累积情况用watchRewardDistributed实时感知分发事件。最佳实践小结金额一律使用 bigint用parseEther/parseUnits构造amount校验其大于 0默认用*Sync需要性能优化时再拆分distributeSync一次调用拿到全部结果、出错即抛throwOnReceiptRevert默认开启高频或 UI 驱动场景再用distributewaitForTransactionReceipt事件解析记得走 viem非Sync变体的回执日志需要用viem/tempo的Actions.reward.distribute.extractEvent提取funder/amount善用 Tempo 事务特性通过feePayer、nonceKey、validAfter/validBefore实现手续费代付、并发事务与定时执行组合 Reward 动作形成闭环分发前用getUserRewardInfo校验参与情况分发后用watchRewardDistributed监听结果。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
