wagmi Tempo 系列使用Hooks.dex.useBalance查询 Stablecoin DEX 上的用户代币余额【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmidex.useBalance是 wagmi Tempo 模块中用于查询用户在 Stablecoin DEX稳定币去中心化交易所上指定代币余额的 React Hook。本文以 site/tempo/hooks/dex.useBalance.md 为核心结合 packages/react/src/tempo/hooks/dex.ts 与 packages/core/src/tempo/actions/dex.ts 的源码实现完整讲解该 Hook 的参数、返回类型、底层调用链与测试验证帮助你在 React 应用中直接读取并订阅 DEX 上的代币余额。一、这个 Hook 解决什么问题在 Tempo 稳定币 DEX 中用户的代币余额分为两层链上钱包余额由 ERC-20 合约持有可通过标准的token.getBalance查询DEX 内部余额用户下单、撤单、做市过程中被 DEX 合约托管的资金例如placeSync挂单后冻结、cancelSync撤单后退回的代币这部分余额只能通过 DEX 自身的接口读取。Hooks.dex.useBalance正是面向第二种场景以 React Hook 的形式查询用户在 Stablecoin DEX 上的指定代币余额并将结果接入 TanStack Query 的缓存与状态管理让组件在数据变化时自动刷新。二、前置准备Tempo 配置使用该 Hook 前需要先创建支持 Tempo 链的 wagmi 配置。文档中引用的完整配置如下来源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(), }, })配置要点配置项说明connectors: [tempoWallet()]注册 Tempo 钱包连接器是完成 DEX 交易类操作的前提chains: [tempo]声明应用支持的链为tempoTempo 主网链定义来自wagmi/chainsmultiInjectedProviderDiscovery: false关闭多钱包注入发现避免与 Tempo 钱包产生干扰transports为tempo链指定http()传输方式用于 RPC 请求随后通过WagmiProvider将配置注入 React 组件树即可在任意组件中使用Hooks.dex.useBalance。三、基本用法import { Hooks } from wagmi/tempo const { data: balance } Hooks.dex.useBalance({ account: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, token: 0x20c0000000000000000000000000000000000001, }) console.log(DEX balance:, balance) // log: DEX balance: 1000000000naccount要查询余额的账户地址token要查询的代币地址如稳定币 DEX 的 base/quote 代币返回值data是一个bigint以最小单位如 1e6 精度表示余额。在真实组件中的典型写法与源码 JSDoc 示例一致见 packages/react/src/tempo/hooks/dex.tsimport { Hooks } from wagmi/tempo function App() { const { data, isLoading } Hooks.dex.useBalance({ account: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, token: 0x20c0000000000000000000000000000000000001, }) if (isLoading) return divLoading.../div return divBalance: {data?.toString()}/div }四、参数详解Hook 的参数类型定义为见 packages/react/src/tempo/hooks/dex.tstype Parameters ConfigParameterconfig QueryParameter ReturnValue, ErrorType, selectData, QueryKey ExactPartialActions.dex.getBalance.Parametersconfig即参数由三部分组成wagmi 通用config参数、TanStack Query 的query参数、以及 DEX 查询动作参数。1.account与tokenaccountAddress要查询余额的账户地址必填。在queryOptions中enabled字段显式依赖它enabled: Boolean(rest.account (query?.enabled ?? true))见 packages/core/src/tempo/actions/dex.ts未传account时查询不会发起queryFn中还会抛出account is required.错误tokenAddress要查询的代币地址。测试表明余额是按代币隔离的详见后文测试验证一节。完整参数定义可参考动作文档 site/tempo/actions/dex.getBalance.md。2.chainId继承自ChainIdParameterconfig用于指定查询所在链。Hook 内部逻辑为const chainId useChainId({ config }) const options Actions.dex.getBalance.queryOptions(config, { ...parameters, chainId: parameters.chainId ?? chainId, } as never) return useQuery(options)即未显式传入chainId时自动使用当前激活链的链 ID见 packages/react/src/tempo/hooks/dex.ts。3.queryquery透传给 TanStack Query 的useQuery支持select、enabled、refetchInterval、staleTime等全部 Query 配置。类型测试中展示了select的用法见 packages/react/src/tempo/hooks/dex.test-d.tsconst result dex.useBalance({ config, query: { select(data) { // data 的类型即 Actions.dex.getBalance.ReturnValue即 bigint return selected }, }, }) // result.data 的类型变为 typeof selected | undefined expectTypeOf(result.data).toEqualTypeOftypeof selected | undefined()五、返回类型Hook 返回 TanStack Query 的UseQueryReturnTypeselectData, Error默认selectData Actions.dex.getBalance.ReturnValue即bigintdatabigint | undefined。查询成功时为用户在 DEX 上的代币余额最小单位整数未加载完成时为undefinedisLoading/isError/error/refetch等与 TanStack Query 的useQuery返回一致用于渲染加载态、错误态与手动刷新。查询动作的返回类型在 packages/core/src/tempo/actions/dex.ts 中定义为type ReturnValue Actions.dex.getBalance.ReturnValue即底层 viem Tempo 动作的bigint返回值。六、底层原理从 Hook 到 viem 的调用链调用链可以概括为三层Hooks.dex.useBalance (React Hook) └─ Actions.dex.getBalance.queryOptions(config, params) (wagmi core构造查询) └─ Actions.dex.getBalance(config, params) (wagmi core action) └─ Actions.dex.getBalance(client, rest) (viem Tempo action)1. wagmi core 动作层packages/core/src/tempo/actions/dex.ts 中的getBalance先取出chainId通过config.getClient({ chainId })获取对应链的 viem client再委托给 viem 的 Tempo 动作export function getBalanceconfig extends Config( config: config, parameters: getBalance.Parametersconfig, ): PromisegetBalance.ReturnValue { const { chainId, ...rest } parameters const client config.getClient({ chainId }) return Actions.dex.getBalance(client, rest) }2. 查询键与查询选项同一文件中queryKey与queryOptions的实现packages/core/src/tempo/actions/dex.tsexport function queryKeyconfig extends Config( parameters: PartialByParametersconfig, account, ) { return [getBalance, parameters] as const } export function queryOptionsconfig extends Config, selectData ReturnValue( config: Config, parameters: queryOptions.Parametersconfig, selectData, ): queryOptions.ReturnValueconfig, selectData { const { query, ...rest } parameters return { ...query, enabled: Boolean(rest.account (query?.enabled ?? true)), queryKey: queryKey(rest), async queryFn({ queryKey }) { const [, { account, ...parameters }] queryKey if (!account) throw new Error(account is required.) return await getBalance(config, { account, ...parameters }) }, } }关键点查询键固定以[getBalance, parameters]为前缀account、token、chainId都参与序列化相同参数共享同一份缓存enabled由account驱动未传账户时查询自动禁用避免无效 RPC 请求queryFn从查询键中还原参数确保缓存命中时不会重复执行动作。3. React Hook 层Hook 层只是薄封装调用useConfig获取配置、useChainId兜底链 ID、queryOptions构造 Query 选项最后交给useQuery见 packages/react/src/tempo/hooks/dex.ts。七、测试验证行为与语义1. 动作层测试packages/core/src/tempo/actions/dex.test.ts 中的getBalance测试组验证了三个关键语义初始余额为 0新账户未参与交易时dex.getBalance返回0n挂单-撤单产生内部余额先dex.placeSync挂买单再dex.cancelSync撤单被冻结的 quote 代币退回后余额大于 0expect(balance).toBeGreaterThan(0n)余额按账户、按代币隔离不同账户查询同一代币互不影响同一账户在 quote 代币有余额时base 代币余额仍为 0。这些用例印证了useBalance读取的是 DEX 内部托管余额而非普通 ERC-20 钱包余额。2. Hook 层测试packages/react/src/tempo/hooks/dex.test.ts 起的describe(useBalance)通过renderHook验证 Hook 在真实 React 渲染环境中的表现覆盖默认查询、不同账户、不同代币等场景与动作层测试结论一致。3. 类型测试packages/react/src/tempo/hooks/dex.test-d.ts 使用expectTypeOf断言data的类型为Actions.dex.getBalance.ReturnValuebigint并验证query.select可以安全地将返回类型投影为自定义类型保证类型层面的契约不回归。八、与其他 DEX 操作的配合useBalance常与 DEX 的交易/挂单操作搭配使用构成完整的下单 → 查余额 → 撤单 → 查余额闭环场景推荐 API说明查询 DEX 内部余额Hooks.dex.useBalance本文主题读取托管在 DEX 合约中的代币同步挂单Hooks.dex.usePlaceSync挂单会冻结代币影响 DEX 内部余额同步撤单Hooks.dex.useCancelSync撤单退回冻结资金使内部余额增加查询买卖报价Hooks.dex.useBuyQuote/useSellQuote成交前评估所需/所得数量九、小结Hooks.dex.useBalance是 Tempo 稳定币 DEX 前端开发中查询用户内部代币余额的标准入口参数上account与token为必填核心参数chainId自动兜底query完全透传 TanStack Query 配置返回上data为bigint余额配合isLoading、error等状态字段即可构建完整 UI实现上Hook → wagmi coregetBalance→ viem Tempo 动作的三层委托清晰可追踪[getBalance, parameters]查询键与account驱动的enabled逻辑保证了缓存与请求效率语义上动作层与 Hook 层测试共同确认了按账户、按代币隔离撤单退回资金计入内部余额等关键行为。如需进一步了解底层动作的参数与返回值定义可继续阅读 site/tempo/actions/dex.getBalance.md或查看 wagmi 仓库中 packages/react/src/tempo/hooks/dex.ts 与 packages/core/src/tempo/actions/dex.ts 的完整源码。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考