Wagmi Tempoamm.useLiquidityBalanceHook 详解查询 AMM 流动性池的 LP 余额【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本篇技术指南围绕 Wagmi Tempo 体系中的Hooks.amm.useLiquidityBalanceReact Hook 展开它用于查询某个地址在指定流动性池Liquidity Pool中持有的 LP 代币余额。读者将掌握该 Hook 的完整用法、全部可选/必填参数与返回类型、底层amm.getLiquidityBalanceAction 的调用链以及基于 TanStack Query 的缓存键queryKey与自动启停机制从而在基于 Tempo 链的 DEX、Fee AMM 场景中直接落地使用。背景Tempo 的 Fee AMM 与 LP 余额Tempo 是一条为支付场景专门设计的 Layer 1 区块链将 token 管理TIP-20、Fee AMM 与稳定币 DEXStablecoin Exchange直接内置于协议层。在 Tempo 的 AMM 中用户可以通过向交易对注入 user token 与 validator token 来提供流动性并因此获得对应数量的 LP 代币Liquidity Provider token。amm.useLiquidityBalance正是用来读取这笔 LP 持仓的 Hook传入地址与池子定位信息即可拿到该地址在该池中的流动性份额以bigint返回。在 Wagmi 中Tempo 的 React Hook 统一从wagmi/tempo入口导出与普通 Wagmi Hook如useSendTransactionSync风格一致且天然支持 TanStack Query 的缓存、重取与加载状态管理。完整环境搭建可参考 Tempo Getting Started。基本用法useLiquidityBalance是一个查询型queryHook它通过池子定位参数定位到具体的 AMM 池再查询给定地址在该池中的流动性余额import { Hooks } from wagmi/tempo const { data: balance } Hooks.amm.useLiquidityBalance({ address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, userToken: 0x20c0000000000000000000000000000000000000, validatorToken: 0x20c0000000000000000000000000000000000001, }) console.log(Liquidity balance:, balance) // log: Liquidity balance: 10500000000000000000n其中address是必填参数表示要查询 LP 余额的账户地址userToken与validatorToken共同定位池子两者组合唯一确定一个交易对返回值balance是bigintlog中展示的10500000000000000000n即余额的原始最小单位数值。配套 ConfiguseLiquidityBalance依赖 Wagmi 的Config上下文。下面是一份最小可用的 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(), }, })在组件树根部通过WagmiProvider config{config}挂载该配置后任意组件内即可直接调用Hooks.amm.useLiquidityBalance无需手动传入config也可通过参数中的config字段显式覆盖适用于测试或非 Provider 场景。参数ParametersuseLiquidityBalance的参数类型定义在 packages/react/src/tempo/hooks/amm.ts 中是ConfigParameter、QueryParameter与 Action 参数的组合。以下参数与底层 amm.getLiquidityBalance Action 一一对应参数类型必填说明addressAddress是要查询流动性余额的账户地址poolIdHex否池 ID。若已知池 ID 可直接传入userTokenAddress \| bigint否池中的 user token地址或 token IDvalidatorTokenAddress \| bigint否池中的 validator token地址或 token IDchainIdnumber否目标链 ID缺省时使用当前useChainId解析出的链configConfig否显式指定 Wagmi 配置缺省时取上下文中的 configqueryobject否TanStack Query 查询选项见下文定位池子的两种方式从getLiquidityBalance的参数设计看池子定位存在两种等价的输入路径直接传poolId如果已经拿到池 ID例如通过Hooks.amm.usePoolId({ userToken, validatorToken })查询得到则只需address poolId即可完成查询传userTokenvalidatorToken通过交易对的两个 token 定位池子此时无需知道池 ID。在 Hook 源码的 JSDoc 示例中官方演示了两种方式的组合使用见 amm.tsconst { data: poolId } Hooks.amm.usePoolId({ userToken: 0x..., validatorToken: 0x..., }) const { data, isLoading } Hooks.amm.useLiquidityBalance({ poolId, address: 0x20c...0055, }) if (isLoading) return divLoading.../div return divLP Balance: {data?.toString()}/divquery 选项query字段完整透传给 TanStack Query 的useQuery可用于控制缓存、重取、选择器等行为例如Hooks.amm.useLiquidityBalance({ address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb, userToken: 0x20c0000000000000000000000000000000000000, validatorToken: 0x20c0000000000000000000000000000000000001, query: { select(data) { // 将 bigint 转为可读字符串方便渲染 return data.toString() }, refetchInterval: 30_000, // 每 30 秒轮询一次余额 }, })返回类型Return Typedata的类型与底层 Action 的返回类型一致即bigintLP 流动性余额以最小单位表示。而 Hook 整体返回的是 TanStack Query 的查询结果对象UseQueryReturnType因此除了data之外还包含以下常用状态字段isLoading/isFetching是否处于首次加载 / 后台重取中isError与error查询失败状态与错误对象isSuccess查询是否成功refetch手动触发重新查询的函数statuspending | error | success状态机。由于data是bigint直接渲染到 UI 前建议先toString()或进行精度格式化例如除以 10 的 token 小数位次方这一点在官方示例中也有体现。源码级原理从 Hook 到链上读请求useLiquidityBalance的实现非常轻量核心逻辑全部委托给 Core 层 Action形成了清晰的调用链useLiquidityBalance (react) └─ Actions.amm.getLiquidityBalance.queryOptions(config, parameters) [core] └─ useQuery(options) [TanStack Query] └─ Actions.amm.getLiquidityBalance(client, parameters) [viem/tempo]React Hook 层在 packages/react/src/tempo/hooks/amm.ts 中useLiquidityBalance先通过useConfig获取配置、useChainId获取当前链 ID然后用Actions.amm.getLiquidityBalance.queryOptions构建查询选项最后交给useQuery执行export function useLiquidityBalance config extends Config ResolvedRegister[config], selectData Actions.amm.getLiquidityBalance.ReturnValue, (parameters: useLiquidityBalance.Parametersconfig, selectData {}) { const config useConfig(parameters) const chainId useChainId({ config }) const options Actions.amm.getLiquidityBalance.queryOptions(config, { ...parameters, chainId: parameters.chainId ?? chainId, } as never) return useQuery(options) as never }注意chainId: parameters.chainId ?? chainId这行当用户未显式传入chainId时Hook 会自动跟随当前激活的链多链场景下无需手动切换。Core Action 层在 packages/core/src/tempo/actions/amm.ts 中getLiquidityBalance的queryOptions定义了两个关键行为自动启停enabled查询只有在必要参数齐备时才会真正发起请求enabled: Boolean( rest.address (rest.poolId || (rest.userToken ! undefined rest.validatorToken ! undefined)) (query?.enabled ?? true), )也就是说address必须存在且poolId与userToken validatorToken两组定位方式至少满足其一查询才会执行。这解释了为什么在未拿到poolId前可以先用usePoolId查询池 ID——一旦依赖的数据就绪useLiquidityBalance会自动开始请求。查询键queryKeyqueryKey由[getLiquidityBalance, filterQueryOptions(parameters)]组成见 amm.ts参数不同如不同 address 或不同 token 对会生成不同的缓存条目TanStack Query 借此实现按参数粒度的缓存与去重。Action 层本身只做一件事从config取出对应chainId的 client然后把请求转发给viem/tempo的Actions.amm.getLiquidityBalance(client, rest)由 viem 完成最终的 RPC 调用。测试佐证余额查询的实际行为仓库中的集成测试 packages/core/src/tempo/actions/amm.test.ts 验证了该功能的行为describe(getLiquidityBalance, () { test(default, async () { const balance await ammActions.getLiquidityBalance(config, { userToken: addresses.alphaUsd, validatorToken: 0x20c0000000000000000000000000000000000001, address: account.address, }) expect(balance).toMatchInlineSnapshot(0n) }) describe(queryOptions, () { test(default, async () { const options ammActions.getLiquidityBalance.queryOptions(config, { userToken: addresses.alphaUsd, validatorToken: 0x20c0000000000000000000000000000000000001, address: account.address, }) const balance await queryClient.fetchQuery(options) expect(balance).toMatchInlineSnapshot(0n) }) }) })可以看到直接调用 Action 与通过queryOptionsfetchQuery走 TanStack Query 两条路径的返回一致未提供流动性时余额为0n。而在 burnSync 测试 中getLiquidityBalance还被用于在燃烧 LP 前读取余额作为后续burn的输入——这展示了它在查询余额 → 操作流动性完整流程中的典型定位。React 侧的类型测试 packages/react/src/tempo/hooks/amm.test-d.ts 则保证了query.select回调中的data类型与Actions.amm.getLiquidityBalance.ReturnValue即bigint严格一致且选中后的result.data类型会随之收窄。实战建议配合usePoolId使用当只持有 token 对信息时先查poolId再查询余额利用query.enabled的自动联动避免无效请求展示前格式化 bigintdata为原始最小单位UI 渲染前应结合 token 精度换算成可读金额避免出现一长串数字利用 TanStack Query 缓存多次渲染或组件重挂载不会重复发请求可通过query.refetchInterval实现余额轮询、通过select做派生数据查询失败兜底余额查询属于只读请求建议结合isLoading/isError做加载态与错误态展示。相关资源底层 Action 文档amm.getLiquidityBalanceTempo Hook 索引Tempo HooksTempo 环境搭建Tempo Getting StartedHook 实现packages/react/src/tempo/hooks/amm.tsCore Action 实现packages/core/src/tempo/actions/amm.ts【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考