wagmi Tempo 链 TIP-20 代币元数据查询：`token.getMetadata` 实战与源码解析
发布时间：2026/9/17 19:49:06 作者：尧图编辑部 阅读量：1,286
wagmi Tempo 链 TIP-20 代币元数据查询token.getMetadata实战与源码解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本文围绕 wagmi 仓库中 Tempo 链相关文档 site/tempo/actions/token.getMetadata.md 展开系统讲解如何使用Actions.token.getMetadata读取 TIP-20 代币的名称、符号、精度、计价货币currency与总供应量等链上元数据。你将掌握从 Config 初始化、Action 调用到返回值字段含义的完整链路并通过仓库源码与测试用例理解其底层实现与 TanStack Query 集成方式可直接用于基于 Tempo 链的 DeFi、稳定币与支付类应用开发。TIP-20 与token.getMetadata的定位Tempo 是 wagmi 仓库内置支持的 EVM 兼容链可在wagmi/chains中直接导入tempo其上部署的 TIP-20 代币标准在标准 ERC-20 语义之外还扩展了paused暂停状态、quoteToken报价代币、supplyCap供应上限、transferPolicyId转账策略等字段。token.getMetadata是一条只读read-only查询 Action用于一次性取回这些元数据是构建代币详情页、资产列表、交易对展示等功能的公共基础能力。在 wagmi 中该 Action 位于packages/core/src/tempo/actions/token.ts是对 viem 的viem/tempo中同名 Action 的封装见 packages/core/src/tempo/AGENTS.md 中Wagmi actions are wrappers around Viem actions的约定同时补齐了 Wagmi Config 解析、chainId参数以及 TanStack Query 工具方法。快速上手完整可运行示例1. 准备 Tempo 链 Config所有wagmi/tempo的 Action 都依赖一个createConfig创建的 Config。仓库文档使用的标准模板见 site/snippets/react/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(), }, })关键点chains: [tempo]声明当前应用连接的链为 Tempotransport使用默认的http()RPC 通道tempoWallet()提供 Tempo 生态钱包连接能力读取元数据这类只读操作实际上不需要签名但应用通常需要它完成后续的转账、授权等写操作multiInjectedProviderDiscovery: false关闭多钱包注入探测避免与tempoWallet冲突。2. 调用token.getMetadata文档给出的核心调用示例源自 site/tempo/actions/token.getMetadata.mdimport { Actions } from wagmi/tempo import { config } from ./config const metadata await Actions.token.getMetadata(config, { token: 0x20c0000000000000000000000000000000000000, }) console.log(Currency:, metadata.currency) // log: Currency: USD console.log(Decimals:, metadata.decimals) // log: Decimals: 18 console.log(Name:, metadata.name) // log: Name: United States Dollar console.log(Symbol:, metadata.symbol) // log: Symbol: USD console.log(Total Supply:, metadata.totalSupply) // log: Total Supply: 1000000000000000000000nActions.token.getMetadata(config, { token })返回一个 Promise可直接await使用示例中的0x20c0...是文档演示用的报价/稳定币代币地址实际开发时替换为目标 TIP-20 代币地址即可。参数详解token类型Address | bigint必填是既支持传入代币合约地址Address如0x20c0...也支持传入代币的数字 IDbigint。该参数同时承担查询键职责在queryOptions中enabled被显式设置为Boolean(rest.token (query?.enabled ?? true))见 packages/core/src/tempo/actions/token.ts#L950-L964即未提供token时查询会被自动禁用避免无意义的 RPC 请求。chainId可选从源码类型ChainIdParameterconfig Actions.token.getMetadata.Parameterspackages/core/src/tempo/actions/token.ts#L933可以看出除文档明示的token外还支持可选chainId指定查询目标链。实现中通过config.getClient({ chainId })按需解析对应链的 Clientexport function getMetadataconfig extends Config( config: config, parameters: getMetadata.Parametersconfig, ): PromisegetMetadata.ReturnValue { const { chainId, ...rest } parameters const client config.getClient({ chainId }) return Actions.token.getMetadata(client, rest) }不传chainId时使用 Config 的默认链多链场景下可显式指定实现与文档中以 token 为唯一必填参数的约定保持一致。返回值详解ReturnType定义如下见文档 site/tempo/actions/token.getMetadata.mdtype ReturnType { currency: string decimals: number name: string paused?: boolean quoteToken?: Address supplyCap?: bigint symbol: string totalSupply: bigint transferPolicyId?: bigint }各字段含义字段类型说明currencystring计价货币代码如USDTempo 上稳定币体系的核心标识decimalsnumber代币精度用于金额展示与换算namestring代币全称如United States Dollarsymbolstring代币符号如USDtotalSupplybigint当前总供应量以最小单位wei 级表示pausedboolean可选代币是否处于暂停不可转账状态quoteTokenAddress可选报价代币地址用于价格锚定场景supplyCapbigint可选供应上限超出后将无法继续铸造transferPolicyIdbigint可选当前生效的转账策略 ID对应链上的策略管理合约仓库单元测试给出了真实返回数据的快照见 packages/core/src/tempo/actions/token.test.ts#L61-L104测试使用的AlphaUSD代币返回{ currency: USD, decimals: 6, name: AlphaUSD, paused: false, quoteToken: 0x20C0000000000000000000000000000000000000, supplyCap: 340282366920938463463374607431768211455n, symbol: AlphaUSD, totalSupply: 202914184810805067765n, transferPolicyId: 1n, }两点实践提示totalSupply、supplyCap、transferPolicyId均为bigint前端展示需配合formatUnits等工具按decimals换算decimals因代币而异示例中的 USD 报价代币为 18而测试中的AlphaUSD为 6不要硬编码精度务必以链上返回值为准。底层实现从 Wagmi Action 到 TanStack Query只读 Action 的标准封装范式getMetadata是 wagmi Tempo 模块中查询型Query-based只读Action的典型实现。按照 packages/core/src/tempo/AGENTS.md 中定义的代码生成规范它完整包含三部分packages/core/src/tempo/actions/token.ts#L923-L988核心函数解析chainId→ 通过config.getClient获取 viem Client → 调用Actions.token.getMetadata(client, rest)并返回结果queryKey[getMetadata, parameters]用于 TanStack Query 的缓存标识相同参数的多次调用共享缓存queryOptions生成可直接交给queryClient.fetchQuery的配置对象queryFn内部重新调用getMetadata并内置了token缺失时禁用查询的逻辑。测试对实现的印证packages/core/src/tempo/actions/token.test.ts对两种调用方式分别做了断言直接调用token.getMetadata(config, { token })并比对内联快照通过token.getMetadata.queryOptions(config, { token })queryClient.fetchQuery(options)走 TanStack Query 路径验证其返回结果与直接调用完全一致。这意味着在生产代码中你可以根据场景选择一次性await或接入查询缓存两种消费方式二者数据口径一致。React 场景useGetMetadataHook若使用 React仓库还提供了等价的 Hook 封装Hooks.token.useGetMetadata文档见 site/tempo/hooks/token.useGetMetadata.md。其实现位于 packages/react/src/tempo/hooks/token.ts#L967-L997核心逻辑是先通过useConfig与useChainId解析当前 Config 和链再透传给Actions.token.getMetadata.queryOptions并交给useQueryimport { Hooks } from wagmi/tempo function TokenInfo() { const { data: metadata, isLoading } Hooks.token.useGetMetadata({ token: 0x20c0000000000000000000000000000000000000, }) if (isLoading) return divLoading.../div return div{metadata?.name} ({metadata?.symbol})/div }Hook 返回的是标准 TanStack Query 结果对象data/isLoading/error/refetch等且自动继承查询缓存与去重能力。注意 Hook 的data在首次加载时为undefined因此访问字段需使用可选链metadata?.name。其返回类型与参数直接复用 Action 侧定义可参考 packages/react/src/tempo/hooks/token.test.ts#L127 的测试保证类型与运行时一致性。常见问题与注意事项精度不可假设文档示例日志中的Decimals: 18是演示用 USD 代币的精度实际 TIP-20 代币如测试中的AlphaUSD为 6各不相同展示前必须使用返回的decimalsbigint处理totalSupply等字段为bigint直接模板渲染会报错需先格式化如formatUnits(totalSupply, decimals)可选字段paused、quoteToken、supplyCap、transferPolicyId为可选读取时需判空不同代币实现可能不返回这些扩展字段查询自动禁用通过queryOptions/Hook 使用时token为空会令查询处于disabled状态属于预期行为可据此实现输入地址后再查询的交互。更多相关资源本主题文档site/tempo/actions/token.getMetadata.mdReact Hook 文档site/tempo/hooks/token.useGetMetadata.md核心实现packages/core/src/tempo/actions/token.ts单元测试packages/core/src/tempo/actions/token.test.tsHook 实现packages/react/src/tempo/hooks/token.tsConfig 模板site/snippets/react/config-tempo.tsTempo 模块整体概览site/tempo/index.md 与 site/tempo/chains.md【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 