Wagmi Tempotoken.burn实战指南销毁 TIP-20 代币的同步与异步调用【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiWagmi Tempo 的token.burn是一组用于从调用者caller自身余额中销毁 TIP-20 代币的 Action帮助开发者在 Tempo 链上实现通缩代币、代币回购销毁、错误铸币回收等场景。通过本文你将掌握token.burn与token.burnSync的完整参数语义、同步与异步两种调用模式的取舍、返回类型结构以及它在 wagmi 核心层与 React Hook 层useBurn/useBurnSync中的实际使用方式。一、token.burn是什么token.burn是 wagmi Tempo 模块中Actions.token命名空间下的一个写操作Write Action其语义是从调用者自己的余额中销毁burn指定数量的 TIP-20 代币销毁后这部分代币将从流通供应中永久移除。它与token.burnBlocked从被封禁地址销毁不同burn的销毁来源是调用者自身。从源码看wagmi 提供的burn实际上是 viem/tempo它先通过getConnectorClient拿到连接器对应的客户端支持自定义account、chainId、connector再透传给 viem 的Actions.token.burn执行最终返回交易哈希或交易收据。与burn配套wagmi 还提供了burnSync——一个同步变体会在交易被打包进区块后才返回结果。二、快速上手同步调用burnSync最常见的用法是直接使用*Sync变体它会在等待交易被包含进区块之后才返回因此返回值里直接带有receipt交易收据无需额外轮询import { Actions } from wagmi/tempo import { parseUnits } from viem import { config } from ./config const { receipt } await Actions.token.burnSync(config, { amount: parseUnits(10.5, 6), token: 0x20c0000000000000000000000000000000000000, }) console.log(Transaction hash:, receipt.transactionHash) // log: Transaction hash: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef其中config是 wagmi 的配置对象需要正确装配 Tempo 链与钱包连接器参考 config-tempo.tsimport { 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(), }, })三、异步调用burn手动等待交易确认如果你的应用对性能敏感不希望一个写操作长时间阻塞在等待确认上应使用非 Sync 的token.burn。它只负责提交交易并立即返回哈希交易是否成功打包需要你手动等待import { Actions as viem_Actions } from viem/tempo import { Actions } from wagmi/tempo import { parseUnits } from viem import { waitForTransactionReceipt } from wagmi/actions const hash await Actions.token.burn(config, { amount: parseUnits(10.5, 6), token: 0x20c0000000000000000000000000000000000000, }) const receipt await waitForTransactionReceipt(config, { hash }) const { args } viem_Actions.token.burn.extractEvent(receipt.logs)这段代码展示了两种调用方式的配合Actions.token.burn返回交易hash字符串再用 wagmi 的waitForTransactionReceipt等待该哈希对应的交易上链最后通过 viem 的Actions.token.burn.extractEvent(receipt.logs)从收据日志中解析出 Burn 事件的args包含amount、from等字段便于在 UI 中精确展示销毁明细。提示extractEvent需要 viem 侧提供收据日志因此示例中同时导入了viem_Actions与Actions两者命名空间不同用途也不同——前者用于事件解析后者用于 wagmi 层的配置化调用。四、返回类型详解无论同步还是异步调用成功后的返回结构如下*Sync变体会额外包含receipttype ReturnType { /** Amount of tokens burned */ amount: bigint /** Address tokens were burned from */ from: Address /** Transaction receipt */ receipt: TransactionReceipt }字段说明字段类型含义amountbigint被销毁的代币数量最小单位配合parseUnits使用fromAddress代币被销毁的来源地址即调用者receiptTransactionReceipt交易收据包含transactionHash、logs、status等信息注意区分非 Sync 的burn返回值是交易哈希hash: Hex而burnSync返回的是{ amount, from, receipt }结构。五、参数说明amount必填类型bigint要销毁的代币数量。必须使用最小单位如 6 位小数示例中使用parseUnits(10.5, 6)表示 10.5 个代币。销毁数量不能超过调用者当前余额否则交易会失败。memo可选类型Hex包含在转账中的备注信息。可用于记录销毁原因、对账编号等链上元数据。token必填类型Address | bigint要销毁的 TIP-20 代币。既可以是代币合约地址Address也可以是代币 IDbigint具体取决于该 TIP-20 代币的标识方式。通用交易参数可选以下参数继承自共享文档 tempo-write-parameters.md适用于所有 Tempo 写操作参数类型说明accountAccount \| Address发送交易的账户默认使用 Wagmi 已连接的账户feeTokenAddress \| bigint交易手续费代币可为 TIP-20 代币地址或 IDfeePayerAccount \| true手续费支付方可传 Viem Account 私钥账户或传true使用 Fee Payer Servicegasbigint交易 gas 上限maxFeePerGasbigint每单位 gas 的最高手续费maxPriorityFeePerGasbigint每单位 gas 的最高优先费小费noncenumber交易的 noncenonceKeyexpiring \| bigint交易的 nonce 键用于 nonce 管理validBeforenumber交易必须被打包前的时间戳Unix 秒validAfternumber交易可被打包后的时间戳Unix 秒throwOnReceiptRevertboolean默认true当收据显示交易回滚时是否抛错仅对*Sync变体生效从 utils.ts 可以看到account、gas、maxFeePerGas、maxPriorityFeePerGas、nonce属于OptionalTransactionOverrides这些交易覆盖项在 wagmi 层均为可选未指定时由客户端viem/钱包自行推导。六、源码层面的调用链在 wagmi 核心层burn/burnSync的完整调用链为Actions.token.burn(config, params) └─ getConnectorClient(config, { account, chainId, connector, assertChainId: false }) └─ Actions.token.burn(client, params) // viem/tempo入口 token.ts 中burn使用getConnectorClient获取连接器客户端并以assertChainId: false跳过链 ID 断言避免与 Tempo 链的链 ID 校验冲突burnSynctoken.ts实现与burn完全一致的客户端解析逻辑差异仅在于透传的是 viem 的burnSync它会等待交易上链并解析 Burn 事件后返回{ amount, from, receipt }类型层面burn.Parameters由ChainIdParameter、ConnectorParameter与 viem 参数类型组合而来见 token.ts因此你可以传入chainId指定目标链、connector指定使用的连接器。七、测试用例验证wagmi 为burn与burnSync都提供了端到端测试见 token.test.ts。以burnSync测试为例其完整流程为连接默认连接器config.connectors[0]调用token.createSync创建一个名为 Burnable Token Sync、符号 BURNSYNC 的新代币调用token.grantRolesSync给自己授予issuer发行者角色调用token.mintSync铸造 1000 个代币调用token.burnSync销毁 1 个代币断言返回的receipt存在且事件数据为{ amount: 1000000n, from: 0xf39F...2266 }。这个测试链路也印证了实际业务中销毁的前提必须先持有代币通过铸币或转账获得并且账户具备相应角色权限才能成功销毁。八、React 中的useBurn/useBurnSyncHook在 React 层wagmi 通过Hooks.token.useBurn/Hooks.token.useBurnSync暴露同样的能力见 token.tsimport { Hooks } from wagmi/tempo function App() { const { mutate, isPending } Hooks.token.useBurn() return ( button onClick{() mutate({ amount: 100n, token: 0x... })} disabled{isPending} Burn /button ) }Hook 内部通过useMutation封装了Actions.token.burn以mutationKey: [burn]标识该变更返回标准的 TanStack Query mutation 结果mutate、isPending、isError等并支持透传mutation配置。若需要提交后立即拿到收据改用Hooks.token.useBurnSync()即可。九、常见错误与注意事项余额不足销毁数量超过账户余额时交易会失败建议先通过Actions.token.getBalance查询余额该查询 Action 在 token.ts 中提供且自带queryOptions/queryKey可无缝接入 TanStack Query权限不足部分 TIP-20 代币对销毁有角色要求如issuer需要先通过token.grantRoles获得相应角色参考上文测试用例单位混淆amount使用最小单位务必用parseUnits转换避免出现 10.5 与 10500000 之类的数量级错误同步阻塞burnSync会阻塞到交易打包若链上确认慢建议在高并发场景改用异步burnwaitForTransactionReceipt手动编排并将轮询/等待逻辑放到非阻塞环境回滚处理throwOnReceiptRevert默认true*Sync变体在收据显示回滚时会抛错无需手动检查receipt.status。十、总结token.burn与token.burnSync是 wagmi Tempo 模块中销毁 TIP-20 代币的标准入口前者追求性能、返回哈希并让你自行等待确认后者开箱即用、直接返回收据与事件数据。两者共享同一套参数体系amount、token、memo及通用的 fee/gas/nonce/时间窗口参数底层通过getConnectorClient桥接 viem/tempo 实现并且在 React 层有对应的useBurn/useBurnSyncHook 可供声明式调用。无论是构建通缩机制还是清理错误铸币这套 API 都能以极少的样板代码接入 Tempo 生态。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考