企业官网建设流程全解析

wagmi 中 TIP-20 代币铸造 Hook：token.useMint与token.useMintSync完整实战指南

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi

本指南围绕 wagmi 仓库中 site/tempo/hooks/token.useMint.md 所讲解的Hooks.token.useMint/Hooks.token.useMintSync展开，介绍如何在 React 应用中向指定地址铸造 TIP-20 代币（Tempo 网络上的代币标准），包括*Sync与非同步两种用法的取舍、底层 Action 的调用链与返回类型、以及完整可运行的事务参数说明。读完本文，你将能够在自己的 wagmi + Tempo 项目中安全、高效地实现代币铸造功能。

概述：什么是token.useMint

token.useMint是 wagmi Tempo 集成中用于「向某个地址铸造新 TIP-20 代币」的 React Hook。它基于 TanStack Query 的useMutation封装，将底层 packages/core/src/tempo/actions/token.ts 中实现的Actions.token.mintAction 暴露为组件中可直接调用的mutate函数，从而把「发送交易 → 处理结果 → 更新 UI 状态」这一链路收敛为标准的 mutation 流程。

与它成对出现的是token.useMintSync。二者对应的是 wagmi Tempo 中普遍存在的*Sync/ 非*Sync双变体设计（类似的还有useBurn/useBurnSync、useCreate/useCreateSync等，见 packages/react/src/tempo/hooks/token.ts）：

• 非*Sync（useMint）：只发送交易，立即返回交易哈希，不等待交易被打包。
• *Sync（useMintSync）：等待交易被包含进区块后才返回，结果中直接携带交易收据与事件数据。

权限要求

铸造 TIP-20 代币要求调用者拥有该代币的ISSUER角色（Role-Based Access Control）。如果调用账户没有该角色，交易将失败。因此在实际产品中，铸造入口通常只对具备ISSUER角色的管理员账户开放，前端应通过Hooks.token.useHasRole或后端鉴权先行校验调用者权限。

快速上手：同步铸造（useMintSync）

对于交互路径简单、希望「一次调用就拿到最终结果」的场景，推荐使用useMintSync。以下示例来自原文档（site/tempo/hooks/token.useMint.md）：

import { Hooks } from 'wagmi/tempo' import { parseUnits } from 'viem' const mintSync = Hooks.token.useMintSync() // Call `mutate` in response to user action (e.g. button click, form submission) mintSync.mutate({ amount: parseUnits('10.5', 6), to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb', token: '0x20c0000000000000000000000000000000000000', }) console.log('Minted amount:', mintSync.data?.amount) // @log: Minted amount: 10500000n console.log('Recipient:', mintSync.data?.to) // @log: Recipient: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb

关键点说明：

• 金额单位：amount使用bigint表示。示例中parseUnits('10.5', 6)表示精度为 6 位小数的代币数量（即铸造10.5个代币，链上表示为10500000n）。
• to：接收铸造代币的地址。
• token：TIP-20 代币的地址（也可以是代币 ID，类型为Address | bigint）。
• data返回值：*Sync变体返回的data中直接包含amount与to字段，方便在铸造成交后立刻更新 UI。

useMintSync的 Hook 实现位于 packages/react/src/tempo/hooks/token.ts#L1337-L1352，其mutationFn直接委托给Actions.token.mintSync(config, variables)，mutationKey为['mintSync']。

配置config

useMintSync与useMint的配置来自最近的WagmiProvider。文档示例中的config（site/snippets/react/config-tempo.ts）展示了 Tempo 链的标准配置方式：

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(), }, })

如果你不想从WagmiProvider取配置，也可以在 Hook 参数中显式传入config（类型为Config | undefined）。

异步用法：useMint+ 手动等待收据

*Sync变体会在返回前等待交易打包，其代价是请求期间isPending状态会持续较久，且会阻塞调用方拿到交易哈希的时机。如果对性能更敏感——例如希望尽早把交易哈希展示给用户、或者在交易未确认时就让用户继续操作——应使用非同步的useMint，再配合useWaitForTransactionReceipt手动等待收据：

import { Hooks } from 'wagmi/tempo' import { Actions } from 'viem/tempo' import { parseUnits } from 'viem' import { useWaitForTransactionReceipt } from 'wagmi' const mint = Hooks.token.useMint() const { data: receipt } = useWaitForTransactionReceipt({ hash: mint.data }) // Call `mutate` in response to user action (e.g. button click, form submission) mint.mutate({ amount: parseUnits('10.5', 6), to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb', token: '0x20c0000000000000000000000000000000000000', }) if (receipt) { const { args: { amount, to } } = Actions.token.mint.extractEvent(receipt.logs) }

这个模式的要点：

• mint.mutate(...)只负责发送交易，返回后mint.data即交易哈希，useWaitForTransactionReceipt会持续监听该哈希直到收据产生。
• 拿到receipt后，可通过 viem Tempo 提供的Actions.token.mint.extractEvent(receipt.logs)从日志中提取铸造事件参数（amount、to），用于数据回填或业务后续处理。
• 相比*Sync，这种「发送与确认解耦」的方式把等待时间从mutate调用中剥离，交互反馈更快，适合需要展示交易进行中状态的场景。

从源码看，useMint（packages/react/src/tempo/hooks/token.ts#L1267-L1282）的mutationFn委托给Actions.token.mint(config, variables)，mutationKey为['mint']；而Actions.token.mint在 packages/core/src/tempo/actions/token.ts#L1324-L1336 中通过getConnectorClient获取连接器客户端后调用 viem 的Actions.token.mint，最终返回的是交易哈希。

返回类型详解

Hook 返回类型（TanStack Query Mutation）

useMint/useMintSync返回标准的UseMutationResult，其泛型参数直接对齐底层 Action（见 packages/react/src/tempo/hooks/token.ts#L1284-L1308）：

UseMutationResult< Actions.token.mint.ReturnValue, // data 类型 Actions.token.mint.ErrorType, // error 类型 Actions.token.mint.Parameters<config>, // mutate 入参类型 context >

常用成员包括mutate/mutateAsync、data、error、isPending/isSuccess/isError、reset等，行为与 TanStack Query v5 的useMutation一致。

data（mutation 结果）

data的具体结构取决于使用的变体：

• 非*Sync的useMint：data为交易哈希（0x...）。
• *Sync的useMintSync：data为「收据 + 事件数据」的组合，对应 Actiontoken.mint的 Return Type（详见 site/tempo/actions/token.mint.md）：

type ReturnType = { /** Amount of tokens minted */ amount: bigint /** Transaction receipt */ receipt: TransactionReceipt /** Address tokens were minted to */ to: Address }

mutate/mutateAsync

mutate与mutateAsync接受的参数即 Actiontoken.mint的 Parameters（含amount、to、token、memo以及下方列出的可选事务参数）。mutate为同步触发、通过回调观察结果；mutateAsync返回 Promise，可在 async 函数中await。

参数详解

必填参数

可选参数：memo

• 类型：Hex

铸造时可附加的备注（memo），会被包含在交易中。适合记录铸造原因、批次号等链上可追溯信息。

可选参数：事务通用参数

以下参数是 Tempo 写入类 Action 的通用可选参数（见 site/shared/tempo-write-parameters.md），useMint/useMintSync的mutate均支持：

这些参数让 Tempo 的铸币事务具备时间窗约束、代币化手续费、过期 nonce 等高级能力。其中validBefore/validAfter可用于构建「限时铸造」逻辑；feePayer: true配合 Fee Payer Service 可实现无 Gas 铸造（用户无需持有原生代币即可完成铸造）。

Hook 级参数

• config：Config | undefined，覆盖从最近WagmiProvider取得的配置。
• mutation：透传给 TanStack QueryuseMutation的配置（如onSuccess、onError、retry等）。

源码级实现：Hook 到 Action 的调用链

结合仓库源码可以完整还原useMint/useMintSync的底层链路：

1. Hook 层（packages/react/src/tempo/hooks/token.ts#L1267-L1282 与 packages/react/src/tempo/hooks/token.ts#L1337-L1352）：useMint通过useConfig(parameters)拿到配置，再用useMutation包装Actions.token.mint（或mintSync），并设置对应的mutationKey（['mint']/['mintSync']）。
2. Core Action 层（packages/core/src/tempo/actions/token.ts#L1324-L1336 与 packages/core/src/tempo/actions/token.ts#L1383-L1395）：从参数中解构account、chainId、connector，通过getConnectorClient获取已连接的钱包客户端（assertChainId: false允许跨链发送），再调用 viem Tempo 的Actions.token.mint/mintSync完成实际的合约交互。
3. 类型层：Core Action 的参数类型由ChainIdParameter、ConnectorParameter与OptionalTransactionOverrides组合而成（即「链 ID + 连接器 + 事务覆盖参数」），并剔除了 viem 层多余的chain字段，最终通过Actions.token.mint.Parameters暴露给 Hook。

此外，仓库测试（packages/react/src/tempo/hooks/token.test.ts）中多次以hooks.useMintSync()装配 mint 用例，验证了该 Hook 在测试环境下的可用性，可作为集成测试的参考写法。

实践建议与注意事项

• 按场景选择变体：交互闭环简单、需要「一把梭」拿结果时用useMintSync；需要快速反馈、展示交易哈希或做 pending 状态管理的产品化场景，用useMint+useWaitForTransactionReceipt。
• 铸造是写操作，务必受权限保护：只有ISSUER角色可铸造，前端应隐藏/禁用无权限用户的铸造入口，并以后端鉴权兜底。
• 金额精度：amount必须是bigint且使用代币的最小精度单位，避免直接用浮点数导致精度丢失。
• 事件数据回填：非*Sync场景下，铸造成功后通过Actions.token.mint.extractEvent(receipt.logs)提取{ amount, to }更新本地状态；*Sync场景则直接使用data.amount/data.to。
• Fee Payer 模式：若希望实现无 Gas 体验，可在mutate参数中传feePayer: true，由 Fee Payer Service 代付手续费。

关联资源

• Hook 文档：site/tempo/hooks/token.useMint.md
• Action 文档（含完整 Return Type 与参数）：site/tempo/actions/token.mint.md
• 事务通用参数说明：site/shared/tempo-write-parameters.md
• Hook 实现：packages/react/src/tempo/hooks/token.ts
• Core Action 实现：packages/core/src/tempo/actions/token.ts
• Hook 测试：packages/react/src/tempo/hooks/token.test.ts
• Tempo 链配置示例：site/snippets/react/config-tempo.ts
• 相关监听 Hook：token.useWatchMint（见 site/tempo/hooks/token.useWatchMint.md），可用于实时监听链上铸造事件

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi