fuels-ts 钱包余额查询全指南getBalance 与 getBalances 的用法与原理解析【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts本指南以 Fuel Network TypeScript SDKfuels-ts官方文档 checking-balances.md 为主体讲解在 fuels-ts 中如何查询单个资产余额与账户全部资产余额。文章将结合 Account 与 Provider 的真实源码说明getBalance/getBalances的底层调用链、返回类型与分页行为帮助你既会写查询代码也理解其工作原理。一、概述两类余额查询场景在 fuels-ts 中钱包/账户对象Account封装了对链上资产状态的查询能力。查看余额通常分两种诉求场景方法返回值查询某个特定资产的余额getBalanceBNBigNumber 大数对象查询账户下所有资产的余额getBalances{ balances: CoinQuantity[], pageInfo? }两个方法都定义在 Account 上因此钱包Wallet、只读账户等一切继承 Account 的实体都能直接调用。官方文档对二者的定位分别是getBalance聚合钱包中给定资产所有未花费 CoinUTXO的金额总和getBalances返回一组CoinQuantity用于完整掌握账户的全部持仓。二、查询单个资产余额getBalance2.1 官方示例官方文档示例checking-balances.ts展示了最小可用写法import type { BN } from fuels; import { Provider, Wallet } from fuels; import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from ../../../env; const provider new Provider(LOCAL_NETWORK_URL); const myWallet Wallet.fromPrivateKey(WALLET_PVT_KEY, provider); // The returned amount is a BigNumber const balance: BN await myWallet.getBalance(await provider.getBaseAssetId());代码要点创建 Providernew Provider(LOCAL_NETWORK_URL)建立与 Fuel 节点的连接。LOCAL_NETWORK_URL指向本地测试网络节点通常是http://127.0.0.1:4000之类的地址在文档示例工程 apps/docs/src/env.ts 中以环境注入变量形式提供。从私钥实例化钱包Wallet.fromPrivateKey(WALLET_PVT_KEY, provider)其中WALLET_PVT_KEY对应一个预先注资的测试账户私钥。传入基准资产 IDprovider.getBaseAssetId()返回当前网络的基准资产Fuel 主资产ID。在标准 Fuel 网络中它通常是0x0000...0000零地址但为了与自定义网络的配置解耦官方示例统一通过 Provider 查询获取。返回值是 BNgetBalance返回BN大数类型而非普通number。余额以最小原子单位base asset 的最小精度单位计直接做数值运算或展示前应先转换如balance.toString()避免 JSnumber精度丢失。2.2 参数省略的默认行为从源码看Account.getBalance 的assetId参数是可选的async getBalance(assetId?: BytesLike): PromiseBN { const assetIdToFetch assetId ?? (await this.provider.getBaseAssetId()); const amount await this.provider.getBalance(this.address, assetIdToFetch); return amount; }也就是说当你不传任何参数直接调用wallet.getBalance()时它会自动取provider.getBaseAssetId()作为默认资产。显式传入与省略参数效果等价但建议显式传入以增强代码可读性。三、查询全部资产余额getBalances官方文档示例checking-balances-two.tsimport { Provider, Wallet } from fuels; import { WALLET_PVT_KEY_2, LOCAL_NETWORK_URL } from ../../../env; const provider new Provider(LOCAL_NETWORK_URL); const myOtherWallet Wallet.fromPrivateKey(WALLET_PVT_KEY_2, provider); const { balances } await myOtherWallet.getBalances(); console.log(balances:, balances);返回的balances是CoinQuantity数组其类型定义位于 coin-quantity.tsexport type CoinQuantity { amount: BN; assetId: string; max?: BN };每个元素包含字段类型含义assetIdstring资产 ID燃料链上的资产唯一标识amountBN该资产的可花费余额大数单位为原子单位maxBN可选可用的最大数量预留估算费用等场景下与 amount 可能不同getBalances是观察一个地址持仓全貌的最直接途径遍历该地址下所有资产逐个给出资产 ID 与对应金额适合做资产看板、余额列表展示等场景。四、底层原理方法调用链文档只展示了 Account 层的用法理解底层能帮你把握分页、节点兼容等行为。4.1 getBalance 的调用链Account.getBalance只是薄封装真正干活的是 Provider.getBalanceasync getBalance( owner: AddressInput, assetId: BytesLike ): PromiseBN { const { balance } await this.operations.getBalanceV2({ owner: new Address(owner).toB256(), assetId: hexlify(assetId), }); return bn(balance.amountU128, 10); }调用链为Wallet.getBalance(assetId)→Account.getBalance补齐默认 baseAssetId→Provider.getBalance(address, assetId)→ GraphQL 操作getBalanceV2→ 返回BN。关键实现事实地址会被规范化为 b256 格式Address(owner).toB256()资产 ID 会被hexlify统一处理确保链上查询参数格式正确余额金额来自节点响应中的amountU128字段属于u128 大整数因此 SDK 用BN承载文档描述聚合所有未花费 Coin 的金额总和正对应 Fuel 账户模型的 UTXO 特性——getBalanceV2在节点侧对同一资产的全部 UTXO 求和返回。4.2 getBalances 的调用链与分页Provider.getBalances 的实现揭示了文档未明说的节点兼容与分页逻辑async getBalances( owner: string | Address, paginationArgs?: CursorPaginationArgs ): PromiseGetBalancesResponse { // The largest possible size allowed by the node. let args: CursorPaginationArgs { first: NON_PAGINATED_BALANCES_SIZE }; const { balancesPagination: supportsPagination } await this.getNodeFeatures(); if (supportsPagination) { // If the node supports pagination, we use the provided pagination arguments. args validatePaginationArgs({ inputArgs: paginationArgs, paginationLimit: BALANCES_PAGE_SIZE_LIMIT, }); } const { balances: { edges, pageInfo }, } await this.operations.getBalancesV2({ ...args, filter: { owner: new Address(owner).toB256() }, supportsPagination, }); const balances edges.map(({ node }) ({ assetId: node.assetId, amount: bn(node.amountU128), })); return { balances, ...(supportsPagination ? { pageInfo } : {}), }; }值得注意的实现事实自动探测节点分页能力SDK 通过getNodeFeatures()读取节点的balancesPagination特性开关不支持分页的旧节点一次请求尽量取满NON_PAGINATED_BALANCES_SIZE 10000条常量定义见 provider.ts 顶部支持分页的新节点使用validatePaginationArgs校验用户传入的分页参数上限受BALANCES_PAGE_SIZE_LIMIT 100约束分页单页大小限制为 100返回结构差异当节点支持分页时返回值额外附带pageInfo含游标信息便于后续翻页字段映射每条余额同样取自amountU128并转为BN组装成{ assetId, amount }形状的CoinQuantity。因此在处理大量资产余额时若账户持仓种类很多你可能需要通过paginationArgsafter游标 first数量遍历所有页而对常规账户默认一次调用即可取回全部持仓。五、实操要点小结始终以原子单位处理余额BN表示的金额未做精度缩放UI 展示时应按资产精度换算切勿当作十进制小数额直接拼接字符串。不要丢失 UTXO 语境getBalance汇总的是未花费 Coin余额为可花费金额与账户锁定金额如进行中的交易占用不同。复用 ProviderProvider是重量级连接对象官方示例刻意将同一个provider注入多个钱包实际项目中也应复用而非每次新建。资产 ID 的统一来源多资产场景下用provider.getBaseAssetId()获取主资产 ID而非硬编码零地址以兼容不同网络配置。相关阅读余额查询是钱包基础操作之一可与本目录下的 私钥钱包、助记词钱包、资产转账 文档组合成完整的钱包开发工作流。六、结语fuels-ts 的余额查询 API 设计得非常克制getBalance解决某一资产有多少getBalances解决我持有哪些资产两者都收敛到Provider层的 GraphQL 查询。理解getBalance默认回退基准资产、getBalances随节点能力自动切换分页策略这两处实现细节能让你在编写余额展示、资产清单、自动化校验逻辑时少踩坑。配套的官方示例代码位于 wallets/snippets 目录可直接作为脚手架参考。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考