从 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 SDK（fuels-ts）中 packages/account/CHANGELOG.md 为骨架，系统梳理@fuel-ts/account从 v0.1.0（2022 年 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；
• 生态集成：connectors（Fuel 钱包连接器）、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 || ^24（Node 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.0，2022-03）即交付了三样奠基能力：基于 BIP-0032 与 BIP-0044 的 HDWallet 实现、助记词支持、生成钱包时配置 Provider；同时支持sendTransaction携带签名发送，以及hashTransaction前将输出字段清零。0.7.0（2022-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.0：BaseWalletLocked更名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.0：Predicate 构造器两度改版

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构造器的必传参数（breaking）；0.101.0 又引入了“带参数的 predicate 强制要求 predicateData（breaking）”，同时把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到订阅式waitForResult

• 0.94.5 起交易改用submitAndAwaitStatus提交，并开始为各订阅路径补充SqueezedOut状态的兜底处理（0.77.0）。
• 0.94.0 将订阅封装为 Promise（wrap subscriptions in promise），且从交易状态中读取 malleable 字段。
• 0.98.0 删除了已废弃的submitAndAwaitGraphQL 操作，提交统一走 TransactionResponse 的waitForResult（0.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到estimateTxDependencies

0.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 永不为 0；
• 0.93.0 重构该方法（breaking），并把 UTXO 缓存默认开启；
• 0.96.1 引入gas modifier；
• 0.99.0 允许调用方显式传入gasPrice；
• 0.98.0 新增autoCost——把“估算 + 注资”合并为一次动作，并移除冗余的 gas price 请求（0.98.0feat!: remove redundant gas price call for tx summary）；
• 0.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 policies（0.71.0）与2dd75b9（0.84.0）的“可选 policy 处理”支持了最新协议的策略字段。
• 输入输出上限保护：0.96.1 校验 TX 最大输入数、0.94.0 处理“注资超出最大输入数”、0.94.0 增加 TX 最大输出数校验。
• 防止隐性资产燃烧：0.98.0feat!: prevent implicit asset burn（breaking），与 0.100.0 “允许向合约转发 0 金额”配套，语义上更严谨。
• 批量操作：0.97.0 实现批量向合约转账，0.89.0 实现向多个地址转账（transfer for multiple addresses）。

五、演进主线三：燃料链版本兼容与 GraphQL 层迭代

@fuel-ts/account对 fuel-core 的版本跟随极其紧密，几乎每个 fuel-core 大版本都会触发本包连带发版。把 CHANGELOG 里的升级点提出来可以得到清晰的兼容性轨迹：

表格信息均来自 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、优化余额查询与getBalances（0.99.0 移除pageInfo，breaking）、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)（初始化时拉取并缓存 chainInfo）；0.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返回鉴权 URL；0.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.0（breaking）：资源缓存考虑 message（0.100.0 再补上“资源属主”）；
• 0.100.4：新增基础资产 coins 合并方法，0.101.3 扩展出自动合并 coins（auto-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/LogData；0.75.0 起无论交易是否由BaseInvocationScope发起都可解码日志（0.79.0 修复外部交易日志）；0.100.5 保证解码时存在合约调用 receipt；0.100.1 跳过无 JSON ABI 的外部合约日志；0.100.3 增加groupedLogs分组；0.102.0 保证“无法解码的日志不再抛异常”。解码工具见 packages/account/src/providers/transaction-response/getAllDecodedLogs.ts。
• 错误体系：0.58.0 起全包改用统一的FuelError（packages/fuel-gauge 的集成测试可佐证）；0.80.0 增强 TX 错误处理与消息格式化；0.101.2 支持新的 ABI 错误码；0.101.3 将 JSON ABI 错误条目并入FuelError.metadata；0.94.4 将“not enough coins”映射为可读错误。错误定义集中在 packages/errors/src/error-codes.ts。

七、升级迁移速查：历次破坏性变更一览

对已在用 fuels-ts 的开发者，CHANGELOG 中最该通读的是带!的条目。按主题归纳如下（均可在 packages/account/CHANGELOG.md 中溯源）：

构造器与实例化

• 0.58.0：Provider.create(url)变为异步初始化；Predicate构造不再需要chainId。
• 0.77.0：Predicate构造器改为对象参数；移除setData（0.101.0 以新形式回归）。
• 0.90.0：Provider 的call更名为dryRun。
• 0.97.0：Predicate构造强制要求abi。
• 0.98.0：Provider 初始化恢复同步；移除submitAndAwait、Provider.create与废弃属性。
• 0.101.0：带参数的 predicate 必须显式提供predicateData。
• 0.101.1：Account.signTransaction返回类型变为TransactionRequest。

命名与常量

• 0.36.0：@fuel-ts/constants删除，常量迁入各包<package>/configs。
• 0.48.0：NativeAssetId更名BaseAssetId。
• 0.94.0：AssetId测试类型更名TestAssetId；废弃FUEL_NETWORK_URL、LOCAL_NETWORK_URL。
• 0.77.0：资产类型Fuel→NetworkFuel、Ethereum→NetworkEthereum。
• 0.86.0：移除 ABI 的 V0 编码；不再为 predicate 添加 witness。
• 0.89.0：forc/fuel-core不再随 SDK 内置二进制。
• 0.98.0：防止隐性资产燃烧、autoCost成为默认交易估算注资方式。
• 0.100.0：ResourceCache缓存键考虑资源属主；启用任意数据签名。
• 0.103.0：devnet 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.md，@fuel-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