从 0.1.0 到 0.103.0：读懂 Fuel TypeScript SDK 中 `@fuel-ts/account` 模块的架构演进与 API 变迁

从 0.1.0 到 0.103.0读懂 Fuel TypeScript SDK 中fuel-ts/account模块的架构演进与 API 变迁【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts本文以 Fuel Network TypeScript SDKfuels-ts中 packages/account/CHANGELOG.md 为骨架系统梳理fuel-ts/account从 v0.1.02022 年 3 月到 v0.103.0 的演进脉络并结合仓库中 Account、Predicate、Provider、TransactionResponse 等实际源码讲清账户模型、钱包分层、交易估算、Gas 费用、资源合并等核心能力是怎么一步步变成今天这个样子的。阅读完你将对 fuels-ts 账户层的能力边界、破坏性变更的迁移要点以及如何把版本记录当作架构史料来用形成一份可落地的知识图谱。一、包定位fuel-ts/account是什么、装什么、依赖谁1.1 模块边界与导出面fuel-ts/account是 fuels-ts monorepo 中管理“标准外部账户EOA 链上交互”的核心子包。根据 packages/account/README.md 的描述它承载管理私钥与签名、与 Fuel 节点交互所需的类型与工具而真正的能力面比名字更宽从 packages/account/src/index.ts 可以看到该包对外统一导出账户与钱包account、wallet、hdwallet、mnemonic、wordlists、signer、wallet-manager链上对象providers含 Provider、TransactionRequest、TransactionResponse、TransactionSummary 等、predicate生态集成connectorsFuel 钱包连接器、assets资产元数据与图标解析工具函数consolidateCoins/getAllCoins/consolidateCoinsIfRequired、deployScriptOrPredicate、assembleTransferToContractScript、以及 bytecode ID 相关的getBytecodeId/getLegacyBlobId/getBytecodeConfigurableOffset/getBytecodeDataOffset见 packages/account/src/index.ts。安装方式在 README 中给出两种pnpm add fuel-ts/account # 或 npm add fuel-ts/account也可以直接安装伞形包fuels获得整套 SDK。1.2 依赖拓扑账户层下面垫了哪些基础包从 packages/account/package.json 的dependencies可以还原其分层结构。它依赖的是 monorepo 内的九个基础包fuel-ts/abi-coder、fuel-ts/address、fuel-ts/crypto、fuel-ts/errors、fuel-ts/hasher、fuel-ts/math、fuel-ts/merkle、fuel-ts/transactions、fuel-ts/utils、fuel-ts/versions。对照 CHANGELOG 末尾的 Patch 依赖清单可以发现几乎每一个版本发布时account 都会跟随一批底层包的 patch 版本同步发版——这正是 CHANGELOG 中反复出现的长串Updated dependencies列表的含义说明 account 处于“聚合业务逻辑、向上供给能力”的中间层位置。该包同时声明支持 Node^20 || ^22 || ^24Node 24 支持来自 0.101.2 的变更同一版本起不再支持 Node 18并用 tsup 构建出dist/index.js、dist/index.mjs与.d.ts双格式产物。二、CHANGELOG 的数据结构先学会“阅读版本档案”fuel-ts/account的 CHANGELOG 由仓库的 changesets 机制自动汇总生成因此每个版本条目都遵循统一的语义化结构这对阅读很关键Minor Changes本包自身的功能新增或行为变更其中标注feat!/fix!/chore!带感叹号的条目意味着破坏性变更breaking change升级时必须关注例如 0.103.0 的feat!: Update devnet Chain ID。Patch Changes本包的缺陷修复与内部优化例如 0.102.0 的feat: ensure that undecodable logs no longer throw。依赖升级Updated dependencies下方列表列出的其他fuel-ts/*子包跟随发版通常本包没有自身逻辑改动只是版本号连带前进典型如 0.87.0、0.96.0 这类整段只有依赖更新的版本。理解了这一结构就能把 2591 行的版本记录提炼为“四个演进主线”① 底层运行时与 fuel-core 的兼容性升级线② 账户/钱包/预言机的 API 设计线③ 交易组装、费用估算与提交的工程优化线④ 网络资产与生态连接器的扩充线。下面按主线还原而不是逐版本流水账。三、演进主线一从“钱包包”到“账户层”——API 大重构的三次关键跳跃3.1 起点HDWallet 与助记词v0.1.0 ~ v0.7.0最早的版本0.1.02022-03即交付了三样奠基能力基于 BIP-0032 与 BIP-0044 的 HDWallet 实现、助记词支持、生成钱包时配置 Provider同时支持sendTransaction携带签名发送以及hashTransaction前将输出字段清零。0.7.02022-06-06进一步启用了 UTXO 校验并完成从 BigNumber 到 BigInt 的内部数值迁移。这些至今仍是钱包功能的主干对应源码中的 packages/account/src/hdwallet/hdwallet.ts、packages/account/src/mnemonic/mnemonic.ts。3.2 0.15.0 的数值底座反转bigint → bn.js值得注意的是一次“先来后到”0.7.0 从 BigNumber 迁到 BigInt而 0.15.0 又“Refactor to use bn.js instead of bigint”即内部数值表示改为 fuel-ts/math 提供的BN大数对象。此后 fuel-gauge 等包对外 API 普遍接受BN输入CHANGELOG 中“amountPerCoinprop 接受 BN”“transferToContract允许大数”等条目即源于此设计。理解这一点有助于把握 fuels-ts 大量接口入参类型兼容bigint | BN | number | string的由来。3.3 0.32.0BaseWalletLocked更名Account抽象公共逻辑v0.32.0 是账户模型的第一次架构定型将BaseWalletLocked重命名为Account并把钱包的公共逻辑抽到 Account 上。今天 packages/account/src/account.ts 中的Account类正是账户层的唯一底座地址、签名者、Provider、余额查询、转账、交易签名等通用能力都被收敛于此。后续 0.19.0 完成的钱包“公私拆分”区分可解锁/锁定两种钱包形态代码见 packages/account/src/wallet/也统一挂靠在 Account 之上。3.4 0.77.0 与 0.97.0Predicate 构造器两度改版Predicate谓词是 Fuel 的账户抽象之一。CHANGELOG 在 0.77.0 记录了它的第一次破坏性改版构造器从“平铺参数”改为“对象参数”原文给出了完整迁移示例// 旧 API const predicate new Predicate(bytecode, provider, abi, configurableConstants); // 新 API const predicate new Predicate({ bytecode, abi, // 可选 provider, inputData, // 可选 configurableConstants, // 可选 });改版的动机是场景驱动当“只传 configurables、不传 inputData”时旧 API 被迫写成new Predicate(bytecode, provider, abi, undefined, configurableConstants)可读性差。对象参数让缺省字段自然省略。同版本还移除了setData方法要求“换数据就新建实例”。到 0.97.0 进一步收紧为abi成为Predicate构造器的必传参数breaking0.101.0 又引入了“带参数的 predicate 强制要求 predicateDatabreaking”同时把setData以新形态加了回来避免“忘传数据导致逻辑错误”。当前实现见 packages/account/src/predicate/predicate.ts并配套提供getPredicateRoot等工具packages/account/src/predicate/utils/getPredicateRoot.ts。这套演进体现了 fuels-ts 对“构造参数显式化、可选字段收窄”的一贯追求。四、演进主线二交易全链路——签名、提交、等待、估算与费用这一主线是 account 包工程量最大的部分对应源码目录 packages/account/src/providers/。它经历了一个清晰的“从手工作坊到流水线”的过程。4.1 提交与等待从submitAndAwait到订阅式waitForResult0.94.5 起交易改用submitAndAwaitStatus提交并开始为各订阅路径补充SqueezedOut状态的兜底处理0.77.0。0.94.0 将订阅封装为 Promisewrap subscriptions in promise且从交易状态中读取 malleable 字段。0.98.0 删除了已废弃的submitAndAwaitGraphQL 操作提交统一走 TransactionResponse 的waitForResult0.99.0 修复了该方法的this绑定问题。0.100.5 与 0.101.3 分别实现了TransactionResponse的序列化/反序列化与对象参数构造器让交易响应可以被持久化、跨进程传递后重建。对应类定义见 packages/account/src/providers/transaction-response/transaction-response.ts 与 packages/account/src/providers/transaction-request/其中 create-transaction-request.ts、upload-transaction-request.ts、upgrade-transaction-request.ts 还反映 0.94.6 引入的 upload/upgrade 两类新交易类型。4.2 从addMissingVariable到estimateTxDependencies0.41.0 将辅助函数addMissingVariable更名为estimateTxDependencies。这个名字更准确地描述了它的职责——估算合约调用所需的输出变量output variables与缺失的合约 ID。0.75.0 又把estimateTxDependencies与getTransactionCost的返回值统一扩充为包含outputVariables、missingContractIds同时移除了旧字段estimatedOutputs。在 Account 与 Predicate 上都能看到该方法的不同实现Predicate 版本还会返回估算用的 receipts。4.3 估算成本的“瘦身运动”从 4 次 dry-run 到 1 次CHANGELOG 非常直白地记录了 SDK 在减少节点请求上的努力0.75.0 是一次集中优化合约调用前的 dry-run 次数从 4 次降到 1 次合约模拟simulation前的 dry-run 从 3 次降到 1 次账户转账前的 dry-run 从 2 次降到 1 次若一笔交易中的所有 predicate 都已完成估算则不再请求节点。配套措施还包括0.96.1 的“每次估算都获取 node info”、0.97.1 的“在estimateTxDependencies时避免重复估算 gasPrice”、0.100.0 的“合并 gas price 与 predicate 估算请求”、0.93.0 的“交易提交后默认缓存 UTXO”见 packages/account/src/providers/resource-cache.ts以及 0.100.0 让ResourceCache在缓存键中考虑资源属主。一句话总结fuels-ts 的策略是“能复用缓存就复用缓存能合并请求就合并请求”。4.4 费用模型与getTransactionCost接口变迁getTransactionCost是估算入口接口在近期多次调整0.71.0 确保估算出的 fee 永不为 00.93.0 重构该方法breaking并把 UTXO 缓存默认开启0.96.1 引入gas modifier0.99.0 允许调用方显式传入gasPrice0.98.0 新增autoCost——把“估算 注资”合并为一次动作并移除冗余的 gas price 请求0.98.0feat!: remove redundant gas price call for tx summary0.75.0 起BaseInvocationScope.fundWithRequiredCoins在内部自行计算fee不再要求调用方传入。费用相关辅助逻辑集中在 packages/account/src/providers/utils/gas.ts 与 packages/account/src/providers/transaction-summary/calculate-tx-fee-for-summary.ts。4.5 策略与保护机制TX policies0.71.0与2dd75b90.84.0的“可选 policy 处理”支持了最新协议的策略字段。输入输出上限保护0.96.1 校验 TX 最大输入数、0.94.0 处理“注资超出最大输入数”、0.94.0 增加 TX 最大输出数校验。防止隐性资产燃烧0.98.0feat!: prevent implicit asset burnbreaking与 0.100.0 “允许向合约转发 0 金额”配套语义上更严谨。批量操作0.97.0 实现批量向合约转账0.89.0 实现向多个地址转账transfer for multiple addresses。五、演进主线三燃料链版本兼容与 GraphQL 层迭代fuel-ts/account对 fuel-core 的版本跟随极其紧密几乎每个 fuel-core 大版本都会触发本包连带发版。把 CHANGELOG 里的升级点提出来可以得到清晰的兼容性轨迹account 版本配套 fuel-core备注0.13.00.10.1早期兼容线0.31.00.17.1破坏性升级0.45.00.18.1forc 0.40.1工具链绑定0.74.00.22.1—0.84.0 / 0.85.00.26.0 / 0.27.0—0.90.00.28.0 / 0.29.0 / 0.30.0移除 beta-5 网络0.92.0 / 0.94.00.31.0 / 0.32.1 / 0.33.0大合约部署支持0.94.x0.34.0 / 0.35.0 / 0.36.0 / 0.38.0密集升级期0.97.0 / 0.99.00.40.0 / 0.40.4—0.100.0 / 0.100.40.41.7 / 0.43.1—0.102.00.44.0并支持 0.47.1—表格信息均来自 packages/account/CHANGELOG.md 对应版本条目。0.103.0 的feat!: Update devnet Chain ID则提醒我们链参数Chain ID、网络 URL、资产 ID也被收进 versions 包见依赖fuel-ts/versions跟着 SDK 版本走。这正是 0.58.0 以来“节点参数与链元数据同步化”路线的延续——0.58.0 起chainInfo在 Provider 初始化时被拉取并缓存。伴随链版本升级的还有 GraphQL 层的持续瘦身例如 0.94.7 合并chain与nodeInfo查询、0.95.0 精简chainInfoFragment/GasCostsFragment、优化余额查询与getBalances0.99.0 移除pageInfobreaking、0.97.0 优化 coin/transaction 查询并给getTransactionsSummaries增加分页上限、0.95.0 把分页上限提升到 60。这些改动都可以在 packages/account/src/providers/operations.graphql 与 fuel-core-schema.graphql 中对照验证。六、演进主线四钱包生态、资源与资产6.1 Provider 生命周期与可观测性初始化模型反转0.58.0 起要求const provider await Provider.create(url)初始化时拉取并缓存 chainInfo0.98.0 又“让 Provider 初始化重新变回同步”breaking。这条反复调整说明 fuels-ts 在“初始化易用性”与“启动即拥有链元数据”之间权衡。连接器与注入0.74.0 实现 wallet connectors、0.98.0 增加onBeforeSend钩子、0.94.7 增加“是否为外部 connector”标志、0.100.0 改进 connector 的 JSON RPC 接口主体实现见 packages/account/src/connectors/fuel-connector.ts。请求增强0.77.0 在ProviderOptions中加入requestMiddleware允许用户改写每一次 fetch 请求可用来注入认证头等0.94.6 支持 Basic Auth 并让provider.url返回鉴权 URL0.100.3 让链上请求失败“静默”而不再抛未处理异常0.94.5 完善了节点离线时的错误处理。网络辅助代码见 packages/account/src/providers/utils/auto-retry-fetch.ts。账号识别0.95.0 提供“判断某 hex 是否为一个账户”的检查工具0.100.0 起该工具还考虑assetId。6.2 资源coins/messages缓存与合并Account 的操作涉及 UTXO 型资源的选择fuels-ts 的策略经历了0.21.0用真实资源resources为交易注资0.90.0在Account上实现generateFakeResources配合fundWithFakeUtxos做离线模拟0.94.0breaking资源缓存考虑 message0.100.0 再补上“资源属主”0.100.4新增基础资产 coins 合并方法0.101.3 扩展出自动合并 coinsauto-consolidation并支持合并非基础资产0.102.0 暴露了与之配套的assembleTransferToContractScript工具见 packages/account/src/utils/consolidate-coins.ts 与 packages/account/src/utils/formatTransferToContractScriptData.ts。资源合并之所以重要是因为 Fuel 链对一笔交易的输入数量有上限见 0.96.1 的输入数量校验大量小额 UTXO 会让普通转账无法成行SDK 因此在提交前自动把零散币“化零为整”。6.3 日志与错误处理日志解码0.17.0 开始解析 Logs/LogData0.75.0 起无论交易是否由BaseInvocationScope发起都可解码日志0.79.0 修复外部交易日志0.100.5 保证解码时存在合约调用 receipt0.100.1 跳过无 JSON ABI 的外部合约日志0.100.3 增加groupedLogs分组0.102.0 保证“无法解码的日志不再抛异常”。解码工具见 packages/account/src/providers/transaction-response/getAllDecodedLogs.ts。错误体系0.58.0 起全包改用统一的FuelErrorpackages/fuel-gauge 的集成测试可佐证0.80.0 增强 TX 错误处理与消息格式化0.101.2 支持新的 ABI 错误码0.101.3 将 JSON ABI 错误条目并入FuelError.metadata0.94.4 将“not enough coins”映射为可读错误。错误定义集中在 packages/errors/src/error-codes.ts。七、升级迁移速查历次破坏性变更一览对已在用 fuels-ts 的开发者CHANGELOG 中最该通读的是带!的条目。按主题归纳如下均可在 packages/account/CHANGELOG.md 中溯源构造器与实例化0.58.0Provider.create(url)变为异步初始化Predicate构造不再需要chainId。0.77.0Predicate构造器改为对象参数移除setData0.101.0 以新形式回归。0.90.0Provider 的call更名为dryRun。0.97.0Predicate构造强制要求abi。0.98.0Provider 初始化恢复同步移除submitAndAwait、Provider.create与废弃属性。0.101.0带参数的 predicate 必须显式提供predicateData。0.101.1Account.signTransaction返回类型变为TransactionRequest。命名与常量0.36.0fuel-ts/constants删除常量迁入各包package/configs。0.48.0NativeAssetId更名BaseAssetId。0.94.0AssetId测试类型更名TestAssetId废弃FUEL_NETWORK_URL、LOCAL_NETWORK_URL。0.77.0资产类型Fuel→NetworkFuel、Ethereum→NetworkEthereum。0.86.0移除 ABI 的 V0 编码不再为 predicate 添加 witness。0.89.0forc/fuel-core不再随 SDK 内置二进制。0.98.0防止隐性资产燃烧、autoCost成为默认交易估算注资方式。0.100.0ResourceCache缓存键考虑资源属主启用任意数据签名。0.103.0devnet Chain ID 更新。升级建议破坏性变更常成组出现尤其 0.77、0.94、0.98 三个大版本。升级时先读对应版本条目再对照本仓库的集成测试packages/fuel-gauge/src 下的各类.test.ts了解新 API 的正确用法是最快的迁移路径。八、测试设施与调试从launchNode到实时节点fuel-ts/account同时也是整套 SDK 测试基建的所在地0.57.0 加入launchNodeAndGetWallets测试工具0.90.0 引入launchTestNode并推动其在整个仓库落地见 0.94.0 的“在其余包中集成 launchTestNode”0.72.0 起多个 fuel-core 配置项被移除改为通过args传入 CLI 参数const { cleanup, ip, port } await launchNode({ args: [--poa-interval-period, 750ms, --poa-instant, false], });0.64.0 支持对实时节点做集成测试。这些能力的当前形态可在 packages/account/src/test-utils/launchNode.ts、packages/account/src/test-utils/setup-test-provider-and-wallets.ts 中查看并可通过 packages/account/package.json 中的./test-utils导出子路径引入。结语把 CHANGELOG 当作架构史来读回看 packages/account/CHANGELOG.mdfuel-ts/account的演进呈现出非常一致的工程取向构造器参数从扁平到对象、再到必填字段收窄对节点请求的次数锱铢必较dry-run 4→1、请求合并、缓存命中网络元数据与燃料链版本强绑定、随 SDK 版本发布错误与日志一律收敛到统一的 FuelError / 可解码体系。这四个取向叠加在Account、Predicate、Provider、TransactionResponse等稳定类名之上构成了今天 fuels-ts 账户层“好上手、好维护、少打节点”的工程形态。对读者而言理解这份演进记录的价值不仅在于迁移升级更在于当你阅读任一版本对应的源码时你能准确说出“这段代码为什么长这样”。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考