wagmi Tempo 奖励模块指南：使用 `reward.useSetRecipient` 设置与变更代币持有者奖励接收者

wagmi Tempo 奖励模块指南使用reward.useSetRecipient设置与变更代币持有者奖励接收者【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi导读本文讲解 wagmi Tempo 奖励模块中的reward.useSetRecipientHook如何在 React 应用中为某个 TIP-20 代币的持有者设置或变更奖励接收地址包括同步*Sync与异步两种调用方式、退出奖励与委托奖励的实战写法并结合仓库源码packages/react/src/tempo/hooks/reward.ts 与 packages/core/src/tempo/actions/reward.ts剖析其底层实现与参数类型。读完本文你将掌握在 wagmi Tempo 环境下完整实现设置奖励接收者功能的能力。功能概览reward.useSetRecipient用于设置或更改某个代币持有者的奖励接收者地址。它的底层对应 Action 为reward.setRecipient二者共同解决了 Tempo 奖励分发体系中的一个核心问题当持有者产生可分配奖励时系统应将奖励发放到哪个地址。默认情况下奖励会流向持有者自身账户通过该 Hook你可以委托奖励将recipient设置为另一个地址把自己的奖励委托给该地址接收退出奖励Opt Out将recipient设置为零地址0x0000...0000即可从奖励分发中退出。值得注意的是仓库文档site/tempo/actions/reward.setRecipient.md特别提示了一个关键机制Rewards are automatically distributed to the current recipient before changing. This happens during any balance-changing operation (transfers, mints, burns).即在变更接收者之前系统会自动先将已累计的奖励分发给当前接收者该结算行为同样会发生在任何改变余额的操作转账、铸造、销毁期间。这保证了切换接收者不会造成奖励丢失。准备工作创建 Tempo 配置无论使用哪种调用方式都需要一个连接 Tempo 链的 wagmiConfig。仓库文档中的标准配置示例如下完整代码见 site/snippets/react/config-tempo.ts// config.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(), }, })要点说明tempoWallet()Tempo 链的钱包连接器是交易签名与发送的基础chains: [tempo]声明应用只面向 Tempo 链multiInjectedProviderDiscovery: false关闭多注入提供方自动发现避免与tempoWallet冲突transports为 Tempo 链指定http()传输方式用于读写链上状态。基本用法同步等待确认的*Sync变体文档推荐的最直接用法是*Sync变体reward.useSetRecipientSync()它会等待交易被打包进区块后再返回因此mutate回调中拿到的data已经是包含收据的完整结果。// example.ts import { Hooks } from wagmi/tempo const setRecipientSync Hooks.reward.useSetRecipientSync() // 在用户动作按钮点击、表单提交中调用 mutate setRecipientSync.mutate({ recipient: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, token: 0x20c0000000000000000000000000000000000000, }) console.log(Holder:, setRecipientSync.data?.holder) // log: Holder: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 console.log(Recipient:, setRecipientSync.data?.recipient) // log: Recipient: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb返回的data中holder发起设置操作的代币持有者地址recipient设置完成后的奖励接收者地址receipt本次交易的收据。异步用法非 Sync 变体 手动等待如果你更看重性能例如不希望在 mutation 内阻塞等待出块应使用非同步的reward.useSetRecipient配合useWaitForTransactionReceipt手动等待交易确认import { Hooks } from wagmi/tempo import { Actions } from viem/tempo import { useWaitForTransactionReceipt } from wagmi const setRecipient Hooks.reward.useSetRecipient() const { data: receipt } useWaitForTransactionReceipt({ hash: setRecipient.data }) // 在用户动作按钮点击、表单提交中调用 mutate setRecipient.mutate({ recipient: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, token: 0x20c0000000000000000000000000000000000000, }) if (receipt) { const { args: { holder, recipient } } Actions.reward.setRecipient.extractEvent(receipt.logs) }这里setRecipient.data是mutate返回的交易哈希hash拿到收据后可通过 viem 的Actions.reward.setRecipient.extractEvent(receipt.logs)从事件日志中解构出holder与recipient参数用于后续 UI 更新或埋点。两种模式的选择原则可以概括为追求简单直接选*Sync追求吞吐与响应速度选非 Sync 手动等待。退出奖励与委托奖励recipient参数赋予了两种特殊业务能力退出奖励Opt Out——将接收者设为零地址import { Actions } from wagmi/tempo import { config } from ./config await Actions.reward.setRecipientSync(config, { recipient: 0x0000000000000000000000000000000000000000, token: 0x20c0000000000000000000000000000000000000, })委托奖励Delegate——将接收者设为另一地址import { Actions } from wagmi/tempo import { config } from ./config await Actions.reward.setRecipientSync(config, { recipient: 0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC, token: 0x20c0000000000000000000000000000000000000, })在 Hook 场景下只需把同样的recipient/token参数传入mutate即可实现上述两种策略。返回类型Return Typereward.useSetRecipient的返回值基于 TanStack Query 的useMutation参见 TanStack Query mutation 文档核心字段如下datamutate成功后得到的数据其结构由 Action 返回值决定。Sync 变体的完整返回类型定义在 site/tempo/actions/reward.setRecipient.md 的 Return Type 一节type ReturnType { /** Token holder address who set their reward recipient */ holder: Address /** Transaction receipt */ receipt: TransactionReceipt /** Reward recipient address (zero address indicates opt-out) */ recipient: Address }其中recipient为零地址即表示已退出奖励分发。mutate / mutateAsync由 TanStack Query 提供的提交函数其变量variables类型对应 Actionreward.setRecipient的 Parameters详见 site/tempo/actions/reward.setRecipient.md 的 Parameters 一节。参数详解Parametersconfig类型Config | undefined可显式传入Config以覆盖从最近的WagmiProvider上下文获取的配置。不传时默认使用上下文中的配置。mutation类型TanStack Query 的UseMutationParameters与 TanStack QueryuseMutation的参数一致可配置onSuccess、onError、onSettled、onMutate、onPending等生命周期回调。类型测试packages/react/src/tempo/hooks/reward.test-d.ts验证了这些回调中data、variables、context的类型均与Actions.reward.setRecipient.*严格对应。提交变量mutate 入参recipient必填— 类型Address奖励接收者地址设为零地址可退出奖励。token必填— 类型AddressTIP-20 代币地址。除上述两个必填项外Action 层面还接受一组可选的事务覆盖参数完整定义见 site/shared/tempo-write-parameters.md参数类型说明accountAccount \| Address发送交易使用的账户默认使用当前已连接的 Wagmi 账户feeTokenAddress \| bigint交易手续费代币可为 TIP-20 代币地址或 IDfeePayerAccount \| true手续费支付方传true表示使用 Fee Payer Servicegasbigint交易的 gas 上限maxFeePerGasbigint每单位 gas 的最大费用maxPriorityFeePerGasbigint每单位 gas 的最大优先费用noncenumber交易 noncenonceKeyexpiring \| bigint交易 nonce 键validBeforenumber交易必须被包含进区块的 Unix 时间戳上限validAfternumber交易可被包含进区块的 Unix 时间戳下限throwOnReceiptRevertboolean默认true收据表明回滚时是否抛错仅对*Sync动作生效源码级实现剖析从源码可以确认 Hook 与 Action 的完整调用链。Hook 层packages/react/src/tempo/hooks/reward.ts中useSetRecipient本质上是 TanStack QueryuseMutation的一层封装export function useSetRecipientconfig extends Config, context unknown( parameters: useSetRecipient.Parametersconfig, context {}, ): useSetRecipient.ReturnTypeconfig, context { const { mutation } parameters const config useConfig(parameters) return useMutation({ ...mutation, async mutationFn(variables) { return Actions.reward.setRecipient(config, variables as never) }, mutationKey: [setRecipient], }) as never }其类型签名在useSetRecipient命名空间中声明Parameters由ConfigParameter含可选config与可选的mutationUseMutationParametersReturnValue, ErrorType, Parameters, context构成ReturnType则是标准的UseMutationResult。useSetRecipientSync结构完全相同只是mutationFn改为调用Actions.reward.setRecipientSync、mutationKey为[setRecipientSync]。Action 层packages/core/src/tempo/actions/reward.ts中setRecipient通过getConnectorClient获取已连接的钱包客户端再委托给 viem 的 Tempo 实现export async function setRecipientconfig extends Config( config: config, parameters: setRecipient.Parametersconfig, ): PromiseActions.reward.setRecipient.ReturnValue { const { account, chainId, connector } parameters const client await getConnectorClient(config, { account, assertChainId: false, chainId, connector, }) return Actions.reward.setRecipient(client, parameters as never) }值得注意的实现细节通过getConnectorClient且assertChainId: false意味着该动作不强制断言链 ID事务最终由当前连接的钱包客户端提交setRecipient返回交易哈希Actions.reward.setRecipient.ReturnValue而setRecipientSync返回交易收据与事件数据Actions.reward.setRecipientSync.ReturnValue这正是是否等待确认两种模式的根本差异参数类型由ChainIdParameter、ConnectorParameter与 viem 层OptionalTransactionOverrides组合而成并通过UnionLooseOmit剔除chain字段确保与 wagmi 的Config体系对齐。此外同文件还提供了配套的getUserRewardInfo查询用户奖励信息、claim领取累计奖励、distribute分发奖励以及watchRewardRecipientSet监听接收者变更事件等动作可组合成完整的 Tempo 奖励生命周期管理方案。相关参考Action 完整文档site/tempo/actions/reward.setRecipient.mdHook 实现源码packages/react/src/tempo/hooks/reward.tsAction 实现源码packages/core/src/tempo/actions/reward.ts类型测试packages/react/src/tempo/hooks/reward.test-d.ts事务覆盖参数site/shared/tempo-write-parameters.mdTempo 配置示例site/snippets/react/config-tempo.ts【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考