区块链Web3【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址https://gitcode.com/GitHub_Trending/fu/fuels-ts点击查看免费下载本篇以fuel-ts/script包的变更记录packages/script/CHANGELOG.md为主线结合当前仓库源码讲清这个包在 Fuel Network TypeScript SDK 中的职责边界、Script/ScriptInvocationScope/ScriptRequest三类核心 API 的调用链路、可配置常量与 Blob 部署机制并完整继承 changelog 中从 2022 年 v0.1.0 到当前 0.103.0 的全部版本里程碑。读完本文你既能照着仓库测试用例跑通一个带main参数的 Sway script也能理解每次版本升级forc、fuel-core、Provider 初始化方式、Node 支持矩阵对实际使用方的影响。包定位与项目结构fuel-ts/script是 fuels-ts 单体仓库中负责执行 Sway script 程序的库包源码位于packages/script/。从 packages/script/package.json 可以看到当前版本为0.103.0与 changelog 最新条目一致运行环境要求node: ^20.0.0 || ^22.0.0 || ^24.0.0产物同时提供 CJSdist/index.js、ESMdist/index.mjs与类型声明dist/index.d.ts。它的运行时依赖恰好是 changelog 中反复出现的那批 workspace 兄弟包这一点对理解 changelog 至关重要——绝大多数版本条目其实是这些依赖包的同步升级依赖版本策略fuel-ts/abi-coderworkspace:*fuel-ts/accountworkspace:*fuel-ts/errorsworkspace:*fuel-ts/mathworkspace:*fuel-ts/programworkspace:*fuel-ts/transactionsworkspace:*fuel-ts/utilsworkspace:*devDependencies 中只有internal/forc用于编译测试用的 Sway 工程。构建脚本也很直接pretest先执行build:forcpnpm fuels-forc build -p test/fixtures/forc-projects --releasebuild用 tsuppostbuild执行 scripts/postbuild.ts。源码文件极少、职责清晰见 packages/script/src/index.ts 的三个导出文件职责src/script.tsScript类bytecode ABI Account 的封装、setConfigurableConstants、deploysrc/script-invocation-scope.tsScriptInvocationScope构造ScriptRequest并挂载到ScriptTransactionRequestsrc/scripts.tsreturnZeroScript内置的返回零极简脚本用于纯转账交易src/types.tsAbstractScript抽象基类继承自fuel-ts/program的AbstractProgram要求实现bytes: Uint8Array核心 API从构造函数到 functions.main1. Script 类Script的构造函数接收编译产物bytecode、JSON ABI 和一个Account见 packages/script/src/script.ts#L70-L82constructor(bytecode: BytesLike, abi: JsonAbi, account: Account) { super(); this.bytes arrayify(bytecode); this.interface new Interface(abi); this.provider account.provider; // Provider 直接取自 Account this.account account; this.functions { main: (...args: TInput) new ScriptInvocationScope(this, this.interface.getFunction(main), args), }; }关键点provider不是单独传入的而是从account.provider派生的这也呼应了 changelog 0.98.0 的 breaking changemakingproviderinitializationsyncagain——Provider 与 Account 的绑定关系决定了 script 初始化时不需要额外异步操作。functions只暴露main一个入口。这与 Sway script 的语言模型一致script 没有可被外部选择的函数集入口固定为main泛型TInput/TOutput约束了参数与返回值类型。调用script.functions.main(...args)返回的是一个ScriptInvocationScope而不是立即发送交易。2. ScriptInvocationScope 与调用链packages/script/src/script-invocation-scope.ts 继承自fuel-ts/program的FunctionInvocationScope核心是两个方法protected override async updateScriptRequest() { if (!this.scriptRequest) { await this.buildScriptRequest(); } this.transactionRequest.setScript(this.scriptRequest, this.args); } private async buildScriptRequest() { const programBytes (this.program as AbstractScript).bytes; const chainInfoCache await (this.program.provider as Provider).getChain(); if (!chainInfoCache) { throw new FuelError( FuelError.CODES.CHAIN_INFO_CACHE_EMPTY, Provider chain info cache is empty. ... ); } this.scriptRequest new ScriptRequest( programBytes, (args: TArgs) this.func.encodeArguments(args), () [] as unknown as TReturn ); }可以推断出完整调用链functions.main(args)→ScriptInvocationScope→buildScriptRequest()需要provider.getChain()的缓存因此 Provider 必须先正确初始化这正是 changelog 0.58.0 要求Provider.create(url)异步初始化的原因→transactionRequest.setScript(...)ScriptTransactionRequest来自fuel-ts/account→ 基类BaseInvocationScope的call()。call()定义在 packages/program/src/functions/base-invocation-scope.ts#L503-L549它先执行fundWithRequiredCoins自动估计并填充费用输入再account.sendTransaction最终返回{ transactionId: string; waitForResult: () PromiseFunctionResultT; waitForPreConfirmation: () PromisePreConfirmationFunctionResultT; }即提交是两步式的先拿到transactionId再决定是否waitForResult。结果组装由 packages/program/src/response.ts 中的buildFunctionResult完成——它从 receipts 中提取value返回值解码、logs、groupedLogs、gasUsed与transactionId。3. ScriptRequest数据偏移与结果解码ScriptRequest位于 packages/program/src/script-request.ts承担三件事数据偏移计算getScriptDataOffsetWithScriptBytes(byteLength, maxInputs)用SCRIPT_FIXED_SIZE calculateVmTxMemory({ maxInputs }) byteLength计算 script data 在 VM 内存中的起始位置——maxInputs来自链的 consensus parameters所以这也是调用前必须拉取 chain info的底层原因。参数编码encodeScriptData(data)支持两种编码器返回形态——直接Uint8Array或{ data, script }对象后者允许编码阶段改写脚本字节。结果解码decodeCallResult会遍历 receipts 找ScriptResult与Return/ReturnData/Revertreceipt遇到Revert时抛出SCRIPT_REVERTED并由extractTxError结合 logs、receipts、dry-run status 组装出带原因的可读错误——这正是 changelog 0.13.0 起Failures now output the reason这条改进在多年后的完整形态。4. returnZeroScript内置极简脚本packages/script/src/scripts.ts 中硬编码了一个 4 字节的脚本源码注释标明其汇编语义为RET(REG_ZERO); NOOP字节为0x24000000用于 coin 转账交易。它是 SDK 内部在纯转账场景下构造 script 交易的兜底手段代码中的 TODO 注明未来应移除硬编码脚本对应上游 issue #281。可配置常量setConfigurableConstantschangelog 0.43.0 引入了 add support for configurable constants on scriptsPR #1003对应实现是Script的setConfigurableConstantspackages/script/src/script.ts#L91-L122setConfigurableConstants(configurables: { [name: string]: unknown }) { try { if (!Object.keys(this.interface.configurables).length) { throw new FuelError( FuelError.CODES.INVALID_CONFIGURABLE_CONSTANTS, The script does not have configurable constants to be set ); } Object.entries(configurables).forEach(([key, value]) { if (!this.interface.configurables[key]) { throw new FuelError( FuelError.CODES.CONFIGURABLE_NOT_FOUND, The script does not have a configurable constant named: ${key} ); } const { offset } this.interface.configurables[key]; const encoded this.interface.encodeConfigurable(key, value as InputValue); this.bytes.set(encoded, offset); // 直接把编码值写回字节码 }); } catch (err) { throw new FuelError( FuelError.CODES.INVALID_CONFIGURABLE_CONSTANTS, Error setting configurable constants: ${(Errorerr).message}. ); } return this; }实现方式是把编码后的常量值直接写进脚本字节码中 ABI 声明的 offset 位置this.bytes.set(encoded, offset)因此必须在执行前调用。packages/script/src/script.test.ts 中有两条对应的负向用例脚本没有 configurables 时抛INVALID_CONFIGURABLE_CONSTANTSThe script does not have configurable constants to be set常量名拼错时抛 does not have a configurable constant named: NOT_DEFINED。部署脚本deploy() 与 Blob 机制较新的Script提供deploy方法packages/script/src/script.ts#L133-L141底层是fuel-ts/account的deployScriptOrPredicatepackages/account/src/utils/deployScriptOrPredicate.ts。其流程为用getBytecodeId(bytecode)计算blobId把去掉 configurables 段的字节码放进BlobTransactionRequest的 witness用getPredicateScriptLoaderInstructions生成一段loader 字节码负责在运行期从 blob 加载完整脚本并同步调整 ABI 中 configurable 的 offsetadjustConfigurableOffsets先provider.getBlobs([blobId])查询链上是否已存在该 blob——已存在则直接返回 loader 实例不重复提交否则由部署方钱包出资assembleTx组装 blob 交易、sendTransaction提交并等待成功失败抛TRANSACTION_FAILED返回{ blobId, waitForResult }waitForResult解析出加载后的Script实例。fuels CLI 的部署命令直接复用了这条链路见 packages/fuels/src/cli/commands/deploy/deployScripts.ts#L31-L35const script new Script(bytecode, abi, wallet); const { bytes: loaderBytecode, interface: { jsonAbi }, } await (await script.deploy(wallet)).waitForResult();部署完成后记录的是loader 字节码 调整后的 ABI后续调用方只需持有这段 loader bytecode 即可完整脚本体留在链上 blob 中按需加载。实战实例化并运行一个 script仓库内置的端到端示例packages/script自带 Sway 测试工程 test/fixtures/forc-projects/call-test-script/src/main.swscript; struct MyStruct { arg_one: bool, arg_two: u64, } fn main(my_struct: MyStruct) - MyStruct { log(my_struct.arg_one); log(my_struct.arg_two); MyStruct { arg_one: my_struct.arg_one, arg_two: my_struct.arg_two, } }对应的测试 packages/script/src/script.test.ts#L55-L98 演示了不经过类型生成typegen、手工构造ScriptRequest的手写封装路线const abiInterface new Interface(scriptJsonAbi); scriptRequest new ScriptRequest( scriptBin, (myStruct: MyStruct) arrayify(abiInterface.functions.main.encodeArguments([myStruct])), (scriptResult) { if (scriptResult.returnReceipt.type ReceiptType.Revert) throw new Error(Reverted); if (scriptResult.returnReceipt.type ! ReceiptType.ReturnData) throw new Error(fail); const decoded abiInterface.functions.main.decodeOutput(scriptResult.returnReceipt.data); return (decoded as any)[0]; } ); const request new ScriptTransactionRequest(); request.setScript(script, data); await request.estimateAndFund(account); const response await account.sendTransaction(request); const transactionResult await response.waitForResult(); const result script.decodeCallResult(transactionResult);这条路径对应官方文档 apps/docs/src/guide/scripts/running-scripts.md 中 hand code out a solution wrapper 的写法如果你使用fuels typegen生成的类型则可以走更简洁的new FuelScript(bytecode, abi, wallet)路线见 apps/docs/src/guide/scripts/instantiating-a-script.md。使用类型生成后的典型调用packages/fuel-gauge/src/script-main-args.test.ts 覆盖了带main参数的 script 的多种形态单参 u8、双参 struct、struct 返回、txParams 校验const scriptInstance new FuelScriptBigNumberish[], BigNumberish( ScriptMainArgs.bytecode, ScriptMainArgs.abi, wallet ); const { waitForResult } await scriptInstance.functions.main(foo).call(); const { value, logs, groupedLogs } await waitForResult(); expect(value?.toString()).toEqual(bn(foo).toString()); expect(logs).toStrictEqual([u8 foo, 33]); expect(groupedLogs).toStrictEqual({ [ZeroBytes32]: [u8 foo, 33] });几个可验证的行为细节waitForResult()返回对象同时带value、logs、groupedLogs、gasUsed等字段由 packages/program/src/response.ts#L157-L168 组装Sway 侧log(...)的输出会按标签 值成对出现在logs中并归组到groupedLogs[ZeroBytes32]下txParams({ gasLimit: 10 })若低于交易需求会直接拒绝报错匹配/Gas limit 10 is lower than the required/——gas 策略TX policies在 changelog 0.70.0/0.71.0 加入PR #1437/#1624。版本演进changelog 的完整继承与解读fuel-ts/script的 changelog 覆盖2022-03-04 的 v0.1.0 到 2026 年的 0.103.0采用 Conventional Commits 约定文件尾注See Conventional Commits for commit guidelines。下面按时间正序完整列出全部版本及其要义其中只有依赖同步的补丁版本统一标注依赖同步。2022 年v0.1.0 → v0.7.0版本日期要义v0.1.02022-03-04首个版本v0.3.02022-03-04版本推进v0.4.02022-03-13版本推进v0.5.02022-03-30版本推进v0.6.02022-04-25版本推进v0.7.02022-06-02启用 UTXO 校验PR #2780.8.0 → 0.18.0工具链与数字类型奠基版本类型要义0.8.0Minor全包 bump minorPR #405新增 README#374修复 fuels 包列表#3970.9.0Patch依赖同步0.10.0Minor从 providers 包移除 transactions 再导出PR #4280.11.0Patch修复包链接到node_modules内部的问题、移除旧 Lerna 配置PR #437——monorepo 从 Lerna 迁移的印记0.12.0Patch依赖同步0.13.0Minor失败现在会输出原因PR #4560.14.0Patch依赖同步0.15.0Patch用 bn.js 重构替代原生 bigintPR #468——fuel-ts/math的bn自此贯穿 SDK0.16.0Minor修复ByteArrayCoder导入PR #5090.17.0Minor升级forc到 0.24.3#511解析 Logs 与 Log DataPR #5170.18.0Patch依赖更新#543全仓库forc fmt格式化#5350.19.0 → 0.33.0Account 化与 main 参数版本类型要义0.19.0Minor交易增加 output 变量PR #5490.20.0–0.22.1Patch依赖同步0.22.2 增加文档与示例 #6120.23.0Patch文档更新#639revert/失败时改进日志输出PR #6400.24.0–0.28.1Patch依赖同步0.24.2 调整文档更新时序 #6460.29.0Patch库导出与测试工具分离PR #709新增 scripts 文档PR #6700.30.0–0.31.0Patch依赖同步0.32.0MinorBaseWalletLocked更名Account后的全量适配PR #789——账户模型统一的节点0.33.0Minorscript 支持 main 参数PR #745——functions.main(...args)用法的确立0.34.0 → 0.58.0ABI 现代化版本类型要义0.35.0Patch调整所有包的导出字段PR #8190.36.0Minor删除fuel-ts/constants包常量迁移到各包package/configs并由fuels伞包统一导出PR #8200.37.0–0.37.1Patch依赖同步0.38.0Minor文档引擎从 Jekyll 切换到 VitePressPR #811——当前apps/docs的来历0.38.1Patch依赖同步0.39.0Minorabi-coder 重构编解码移入FunctionFragment指针类型也携带选择器/签名信息PR #8910.40.0–0.42.0Patch依赖同步0.43.0Minorscript 支持 configurable constantsPR #10030.44.0Minor全量重构包配置、支持本地安装PR #9840.45.0–0.45.xPatch依赖同步0.46.0MinorScriptTransactionRequest可用性与文档改进PR #1072forc-bin发布形态调整#1073用.d.ts declaration map 替代publishConfigs#10550.47.0Minor清除旧版 ABI 格式PR #1094改进 Vector 支持PR #10460.48.0PatchNativeAssetId更名BaseAssetId与 Rust SDK 对齐PR #11210.48.2Patch弃用 tx funding call 选项——所有交易都要求 spendable inputPR #11360.49.0–0.50.0Patch依赖同步0.51.0Minor升级fuel-core到 0.20.3PR #11120.52.0–0.57.0Minor/Patch版本推进无独立变更描述0.58.0MinorchainInfo在 Provider 初始化时拉取并缓存需改为await Provider.create(url)Predicate构造移除chainId全量改用FuelErrorPR #1181、#12300.59.0 → 0.86.0CLI、策略与节点/编译器升级版本类型要义0.63.0Patch清除 ethers v5 的arrayify改用 ethers v6 的getBytesPR #12550.64.0–0.66.0Patch版本推进0.66.1 调整包管理器配置 #14150.67.0Minor修复交易出资funding问题PR #13720.68.0Patch标准化所有 forc 工程、修复 turbo 缓存、降低pretest噪音PR #14420.69.0–0.70.1Minor/Patch版本推进0.70.0 / 0.71.0Minoru8/bool 按 small bytes 右对齐编解码新增pnpm create fuelsCLI对应packages/create-fuelsTX policies 支持PR #1437/#1565、#16240.72.0–0.72.xPatch版本推进0.73.0Patchforc升级到 0.49.2PR #17070.74.0MinorAccount 相关包重构PR #16750.75.0Patch使用内部工具替代 ethers 的arrayify/hexlify/concat/BytesLikePR #1775——摆脱 ethers 字节工具的里程碑0.76.0–0.82.0Patch/Minor版本推进0.81.0 引入 knip 依赖检查 #37743e80.83.0Minorforc0.56.0fuel-core0.24.3base asset ID 从链上获取不再硬编码0.84.0Minorfuel-core升级到 0.26.00.85.0Patch依赖同步0.86.0Minorforc升级到 0.58.0 并移除V0编码breaking0.87.0 → 0.98.0统一错误与 Provider 同步化版本类型要义0.87.0–0.93.0Patch依赖同步0.94.0Patch错误体系统一Error全面切换为FuelError751d6380.94.1–0.94.9Patch依赖同步0.94.7 修复导出类型 80df9000.95.0–0.96.0Patch依赖同步0.97.0–0.97.2Patch依赖同步0.97.1 增加noImplicitOverride编译选项 c904a98注意从 0.98.0 起fuel-ts/interfaces不再出现在依赖列表中因该包被重新分配/移除0.98.0Minorprovider初始化重新变回同步458b7cfbreaking文档优化前端应用13977dffuel-ts/interfaces包重新分配0b4c3ab清理无用依赖并更新 knip 配置68ef74d0.99.0 → 0.103.0当前版本版本要义0.99.0依赖同步16 项上游变更0.100.0–0.100.6依赖同步0.101.0–0.101.3依赖同步0.101.2支持 Node 24弃用 Node 188c19d93——与 package.json 中engines: ^20 \|\| ^22 \|\| ^24互相印证0.102.0依赖同步4 项上游变更0.103.0当前版本依赖同步014a606如何阅读这份 changelog三个可复用的规律版本号与依赖同步monorepo 用 changesets 管理account、program、abi-coder、errors、math、transactions、utils任一包变更都会驱动fuel-ts/script出 patch 版因此 Updated dependencies 条目远多于功能条目升级时建议以fuels伞包版本为准统一升级。!标记与 Minor Changes 代表 breaking change历史上真正影响使用方式的共五处0.36.0constants 包删除、0.58.0Provider 必须异步create、0.70.0/0.71.0TX policies、0.83.0/0.84.0/0.86.0节点与编译器大版本、移除 V0 编码、0.98.0Provider 初始化重新同步化。编译器/节点升级驱动了 Sway 工程兼容forc从 0.24.30.17.0→ 0.49.20.73.0→ 0.56.00.83.0→ 0.58.00.86.0fuel-core从 0.20.30.51.0→ 0.24.30.83.0→ 0.26.00.84.0。仓库内fuel-toolchain.toml如 apps/create-fuels-counter-guide/fuel-toolchain.toml与 internal/forc、internal/fuel-core 锁定了测试环境的工具链版本可据此核对本地forc build产物与 SDK 的兼容区间。环境要求与适用前提Node^20.0.0 || ^22.0.0 || ^24.0.0自 0.101.2 起不再支持 Node 18安装作为 npm 包fuel-ts/script安装日常开发通常直接安装伞包fuels并从fuels导入Scriptfuel-gauge 测试即如此如 packages/fuel-gauge/src/script-main-args.test.ts#L1-L3 的import { bn, Script as FuelScript, ZeroBytes32 } from fuels前提调用前Account必须已绑定正确初始化的Providerprovider.getChain()缓存非空否则buildScriptRequest抛CHAIN_INFO_CACHE_EMPTY只读说明本文所有路径均可在当前仓库中直接查看运行本包测试需先执行pnpm build:forc编译test/fixtures/forc-projects下的 Sway 工程。小结与延伸阅读路径fuel-ts/script包体量小但卡住了 Sway 字节码 → VM 内存布局 → 交易发送 → 结果解码 的关键路径Script负责字节码与常量注入ScriptInvocationScope负责把编码后的main参数挂进ScriptTransactionRequestScriptRequest负责偏移计算与解码最终由BaseInvocationScope.call()提交并交付waitForResult。结合 2022 年至今的 changelog 可以看到这个包的变化主要是被 Provider 生命周期0.58.0/0.98.0、ABI 与编码体系0.39.0/0.47.0、数字类型0.15.0、错误体系0.58.0/0.94.0与 Node 支持矩阵0.91.0/0.101.2这几条主线牵引的。进一步阅读建议按此顺序packages/script/src/script.ts ——Script全量实现packages/script/src/script.test.ts 与 test/fixtures/forc-projects/call-test-script/src/main.sw —— 可运行的最小闭环packages/program/src/script-request.ts 与 packages/program/src/functions/base-invocation-scope.ts —— 调用与费用组装机制packages/account/src/utils/deployScriptOrPredicate.ts —— Blob 部署原理apps/docs/src/guide/scripts/ —— 官方脚本使用指南实例化、运行、日志、可配置常量、部署。赞分享区块链Web3【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址https://gitcode.com/GitHub_Trending/fu/fuels-ts点击查看免费下载相关推荐fuels-ts 交易层演进全解fuel-ts/transactions 从 v0.1 到 v0.103 的序列化变迁与源码剖析fuels ts 交易层演进全解 fuel ts/transactions 从 v0.1 到 v0.103 的序列化变迁与源码剖析 fuel ts/tra区块链Web3fuels-ts 中实例化 Sway 脚本Script从 compiled bytecode 到 ScriptRequest 的完整指南fuels ts 中实例化 Sway 脚本Script从 compiled bytecode 到 ScriptRequest 的完整指南 本指南基于 fu区块链Web3fuels-ts 纯浏览器 CDN 引入指南用 script typemodule 直连 Fuel 主网fuels ts 纯浏览器 CDN 引入指南用 script typemodule 直连 Fuel 主网 fuels ts Fuel Network区块链Web3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考