fuels-ts 的 @fuel-ts/abi-typegen 完全指南：从 Sway ABI JSON 生成 TypeScript 绑定

fuels-ts 的 fuel-ts/abi-typegen 完全指南从 Sway ABI JSON 生成 TypeScript 绑定【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts本文以 packages/abi-typegen/README.md 为主体结合fuel-ts/abi-typegen包的源码与测试用例展开。读完后你将掌握什么是 ABI typegen、如何用fuels-typegen独立生成合约/脚本/谓词类型、如何通过runTypegen编程式集成以及 Sway 各内建类型在 TypeScript 侧的输入输出映射关系。fuel-ts/abi-typegen是 Fuel 官方 TypeScript SDKfuels-ts 仓库中负责从 Sway 程序编译产物ABI JSON 文件自动生成类型安全的 TypeScript 绑定代码的核心包。编译 Sway 智能合约后你拿到的只是一份描述函数签名、类型结构与配置项的 JSON而 typegen 会基于该 JSON 把链上调用封装成带有完整类型标注的 TS 模块从而让开发者在使用合约、脚本与谓词时获得编译期类型检查与友好的 IDE 智能提示。它是 fuels-ts 生态中「类型安全从编译器直达前端」的关键一环其能力既可通过独立 CLI 使用也可被整体引入fuels工具链本文会带你完整走一遍这两种接入路径。一、这个包解决什么问题当开发者用 Sway 语言编写并编译一个合约forc build后会在out/debug/目录中得到类似my-contract-abi.json、my-contract.bin以及可选的*-storage_slots.json的文件。JSON ABI 只是纯数据描述若直接手工维护调用代码很容易出现参数类型写错、返回值解析错误等问题。fuel-ts/abi-typegen的作用就是读取这些 JSON ABI并产出面向Contract合约的类型与*Factory工厂类面向Script脚本的调用入口类型面向Predicate谓词的类型与工具代码。从源码结构看整个包以 AbiTypeGen.ts 为核心引擎它为每个 ABI 文件实例化一个Abi对象把-abi.json关联的.bin字节码与-storage_slots.json存储槽位配对解析随后根据 ProgramTypeEnumCONTRACT/SCRIPT/PREDICATE分派到不同的汇编管线最终通过 templates 目录下的 Handlebars.hbs模板渲染出真实的 TS 文件列表。生成的每个文件还会在首次写入前使用rimrafSync清理旧文件保证输出目录内容与最新 ABI 严格一致见 runTypegen.ts。二、安装方式fuel-ts/abi-typegen可以独立安装使用适用于只需要类型生成、不引入完整 SDK 的场景pnpm add fuel-ts/abi-typegen # 或 npm add fuel-ts/abi-typegen当前仓库中该包的版本号与 node 支持范围可在 package.json 中查看engines: { node: ^20.0.0 || ^22.0.0 || ^24.0.0 }其命令行二进制被注册为fuels-typegenbin: { fuels-typegen: typegen.js }typegen.js是一个极薄的启动脚本仅做require(./dist/bin.js)见 typegen.js真正的 CLI 逻辑集中在 cli.ts 与 bin.ts 中。此外如果你已经在使用完整 SDKfuelsumbrella 包则无需单独安装直接通过npx fuels typegen调用同一套能力即可后面「Full SDK 路径」一节会展开对比。三、CLI 帮助信息与命令选项独立安装后可直接查看内置帮助$ fuels-typegen -h Generate Typescript from Sway ABI JSON files Usage: fuels-typegen [options] Options: -V, --version output the version number -i, --inputs path|glob... Input paths/globals to your ABI JSON files -o, --output dir Directory path for generated files -c, --contract Generate types for Contracts [default] -s, --script Generate types for Scripts -p, --predicate Generate types for Predicates -S, --silent Omit output messages -h, --help display help for command对照源码理解各选项的实际行为cli.ts选项含义源码依据-V, --version打印版本号program.version(builtinVersion.FUELS)版本取自fuel-ts/versions内置常量-i, --inputs path\|glob...必填指向一个或多个 ABI JSON 文件路径/glob 表达式使用commander的requiredOption声明-o, --output dir必填生成的 TS 文件输出目录同样为requiredOption-c, --contract生成合约类型默认开启resolveProgramType中noneSpecified时回退到CONTRACT-s, --script生成脚本类型与-c/-p通过conflicts互斥-p, --predicate生成谓词类型与-c/-s通过conflicts互斥-S, --silent静默模式不输出生成过程信息传入runTypegen的silent控制console.log关于程序类型的选择有一个容易被忽略的细节类型解析函数resolveProgramTypecli.ts规定——当-c/-s/-p都没有指定时默认按合约处理一旦显式传了-p则优先判为谓词其余情况归为脚本。且三种模式之间是互斥的conflicts防止同时输出多种程序类型造成混淆。四、生成类型独立 CLI 用法当以独立包方式使用时其可执行文件统一带fuels-前缀即fuels-typegen。以典型的forc编译产物为例npx fuels-typegen -i ./out/debug/*-abi.json -o ./src/contracts命令执行过程可以拆解为依据 runTypegen.ts 的实现顺序展开输入对-i提供的每个 glob 用globSync(i, { cwd })展开为具体文件路径数组若一个 glob 都没匹配到任何文件会抛出NO_ABIS_FOUNDno ABI found at ...错误读取并解析 ABI逐个readFileSync读取 JSON 内容并记录路径为后续定位同名.bin做准备配对辅助文件通过 collectBinFilePaths 与collectStorageSlotsFilepaths收集字节码与存储槽位文件路径规则是xxx-abi.json对应xxx.bin与xxx-storage_slots.json在 AbiTypeGen.ts 中通过字符串替换-abi.json推导若对应的.bin缺失会调用 validateBinFile 给出明确报错模板渲染实例化AbiTypeGen依据programType走assembleContracts/assembleScripts/assemblePredicates三条分支用 contract/factory.hbs、main.hbs、common/index.hbs 等 Handlebars 模板渲染出可用的 TS 模块落盘先mkdirp确保输出目录存在对每个生成文件先rimrafSync再writeFileSync并在终端逐行打印写出路径最终输出Done.⚡。4.1 生成目录的结构从上文模板与汇编逻辑可以推断-o指向的目录并不是单个平铺文件对合约类型除主类型文件外还会生成一个*Factory.ts例如MyContractFactory.ts以及一个index.ts桶文件。index.hbs模板内容印证了这一点{{header}} {{#each members}} export { {{this}} } from ./{{this}}; {{/each}}即index.ts会重新导出该目录下全部已生成的成员模块方便import { MyContract } from ./src/contracts这类聚合导入。函数与方法输入输出、结构体与枚举的类型格式化逻辑则分散在 abi 目录的类型实现中并以 formatStructs.ts、formatEnums.ts 等工具辅助。五、编程式 APIrunTypegen除了 CLItypegen 的全部能力也通过 runTypegen.ts 暴露为可编程函数适合集成到构建脚本、代码生成流水线或 CI 流程中。import { ProgramTypeEnum, runTypegen } from fuel-ts/abi-typegen; const cwd process.cwd(); const input ./abis/**-abi.json; const output ./types; const filepaths [./abis/a-abi.json, ./abis/b-abi.json]; const programType ProgramTypeEnum.CONTRACT; // 方式一使用 glob 表达式 await runTypegen({ cwd, input, output, programType }); // 方式二使用文件路径数组 await runTypegen({ cwd, filepaths, output, programType });参数对照实现里的接口IGenerateFilesParamsrunTypegen.ts参数类型必填说明cwdstring是基准工作目录glob 与相对路径都会基于它解析inputstring[]二选一glob 表达式内部逐个调用globSyncfilepathsstring[]二选一精确文件路径数组跳过 glob 展开outputstring是输出目录programTypeProgramTypeEnum是CONTRACT/SCRIPT/PREDICATEsilentboolean否为true时抑制console.logversionsBinaryVersions否可覆盖内置二进制版本号从源码实现看有几点编程式调用时需要注意input与filepaths至少要提供其一否则抛出MISSING_REQUIRED_PARAMETER错误提示At least one parameter should be supplied: input or filepaths.同时提供时优先使用filepathsfilepaths传入的必须是真实存在的绝对或相对相对cwd路径函数内部直接readFileSync不会做 glob 匹配runTypegen内部把versions与fuel-ts/versions内置版本做浅合并{ FUELS: builtinVersions.FUELS, ...params.versions }让生成的代码头部能打印当前 SDK/工具链版本号。另外ProgramTypeEnum来自 ProgramTypeEnum.ts值为小写字符串CONTRACT contract、SCRIPT script、PREDICATE predicate。这也意味着参数必须是这三者之一否则AbiTypeGen会抛出INVALID_INPUT_PARAMETERS错误见 AbiTypeGen.ts。runTypegen还可以通过fuel-ts/abi-typegen/runTypegen子路径单独导入见 package.json 中exports的./runTypegen字段方便不依赖 CLI 的纯库调用场景。六、Full SDK 安装路径推荐如果项目本身就要与链交互发交易、调用合约等官方推荐直接安装完整 SDK 的 umbrella 包fuels避免单独维护fuel-ts/abi-typegen的版本pnpm add fuels # 或 npm add fuels装好后不再直接触碰fuels-typegen二进制而是通过fuelsCLI 的子命令typegen使用同款能力npx fuels typegen -i ./out/debug/*-abi.json -o ./src/contracts两种调用方式共享同一套参数语义-i/-o/-c/-s/-p/-S切换成本几乎为零。仓库里现成的使用案例可以参考 apps/demo-typegen内部按 demo-contract、demo-predicate、demo-script 组织以及 apps/create-fuels-counter-guide 这类同时含 contract/predicate/script 三种 Sway 程序的教学示例。七、Sway 类型与 TypeScript 类型的转换对照表下表是本包类型系统的核心契约描述了 Sway 类型如何与 TypeScript 输入/输出类型互相转换。它直接决定了 typegen 生成的函数签名——输入侧通常放宽为BigNumberish之类的联合类型以便调用方传参输出侧则是严格化、可直接使用的产物类型。Sway示例TS:inputTS:outputu8255BigNumberishnumberu1665535BigNumberishnumberu324294967295BigNumberishnumberu640xFFFFFFFFFFFFFFFFBigNumberishBNstranythingstringstringbooltruebooleanbooleanb2560x000...stringstringb512fuel1a7r...stringstringtuples(MyType,MyType)[MyType,MyType][MyType,MyType]enumsenumMyEnum{ y: (), n: () }MyEnumEnum{ y: [], n: [] }MyEnumEnum{ y: [], n: [] }structsMyStruct{ a: u8, b: u16 }MyStructMyStructvectorsVecMyTypeMyType[]MyType[]optionsOptionMyTypeOptionMyTypeOptionMyTyperaw untyped ptr123BigNumberishBN上表并非纸面约定而是有对应的单元测试做逐项校验例如在 abi/types 目录中U64Type.test.ts 断言 u64 的inputLabel BigNumberish、outputLabel BNU32Type.test.ts 断言 u32 输入BigNumberish、输出numberArrayType.test.ts 与 TupleType.test.ts 验证了嵌套数组/元组在输入侧如何递归包裹为BigNumberishRawUntypedPtr.test.ts 同时验证裸指针类型需要的 fuels 成员导入为[BigNumberish, BN]函数层面Function.test.ts 验证了诸如VecBigNumberish、OptionBigNumberish的输入参数标签生成。解读上表时需要结合 fuels-ts 的数学层约定u64 与裸指针这类「超出 JSNumber安全整数范围」的类型输出统一采用BNbig number来自fuel-ts/math见 packages/math 的 bn.ts避免精度丢失而输入侧BigNumberish允许调用方传 number / string / bigint / BN 等多种形式。对于OptionMyType与枚举这类可空类型生成代码会进一步使用类型参数化例如Enum{ y: [], n: [] }配合 SDK 的编码层packages/abi-coder在运行期完成 Sway 枚举/结构体与 TS 结构之间的互转。八、生成结果的消费方式以合约工厂为例一旦类型生成完成合约目录中通常会产出类似下面这样的模块化产物具体以实际 ABI 为准主类型模块含函数签名、入参输出类型、枚举/结构体定义、NameFactory工厂模块封装new MyContractFactory(wallet)与deploy以及汇总导出的index.ts。下游消费时大致是import { MyContractFactory } from ./src/contracts; // 工厂内部会读取生成时嵌入的字节码与 ABI配合钱包实例完成部署与调用 const contract await MyContractFactory.deploy(wallet); const { value } await contract.functions.my_method(42).call();得益于 input/output 双重类型标注传给合约函数的参数会先被编译期校验返回值也会带上精确的 TS 类型。底层执行链路则依托 packages/contract合约调用封装、packages/program 与 packages/abi-coder参数编码/解码完成typegen 只是把「类型安全」这一环提前到编译期。仓库中的端到端佐证可见于测试编排包内测试通过pnpm build:forc先编译 test/fixtures/forc-projects 下的真实 Sway 项目再对产物执行 typegen 并断言生成结果参见 package.json 的pretest脚本与 AbiTypeGen.test.ts、runTypegen.test.ts若改动影响生成快照可运行pnpm run test:update-fixtures借助UPDATE_FIXTUREStrue环境变量刷新。九、常见问题与排错提示提示no ABI found at ...-i的 glob 没匹配到任何-abi.json文件。请核对路径是否相对cwd正确以及forc build是否已真正执行out/debug下应存在 JSON 产物。也可以在 shell 中先ls ./out/debug/*-abi.json验证通配符。提示缺.bin文件typegen 按xxx-abi.json→xxx.bin的规则寻找字节码validateBinFile。Sway 脚本/谓词场景尤为依赖.bin请确认编译时使用了 release 模式输出。三选一参数互斥报错-c、-s、-p彼此冲突一次只传一个不传则默认走合约CONTRACT。版本不一致生成的头部会带版本信息若单独使用fuel-ts/abi-typegen而版本与链上 / SDK 相差较远建议切到fuelsumbrella 包统一版本管理。旧文件残留每次运行都会对要写出的文件先清理再重写若希望输出目录完全干净可在运行前自行清空-o目录文中不修改仓库仅说明本地使用方式。十、相关资源独立包入口与导出packages/abi-typegen/src/index.ts导出ProgramTypeEnum、IFunction、IConfigurable、JsonAbi等公共类型生成引擎packages/abi-typegen/src/AbiTypeGen.ts编程式入口packages/abi-typegen/src/runTypegen.tsCLI 实现与程序类型解析packages/abi-typegen/src/cli.ts模板集Contract/Script/Predicatepackages/abi-typegen/src/templatesABI 类型体系与单测packages/abi-typegen/src/abi/types真实 Sway 夹具packages/abi-typegen/test/fixtures/forc-projects类型消费者SDK 侧运行时支撑packages/abi-coder、packages/contract、packages/program、packages/math聚合 CLI 的 typegen 命令packages/fuels/src/cli端到端示例应用apps/demo-typegen、apps/create-fuels-counter-guide如需查看该包历史变更请查阅 CHANGELOG其许可协议为 Apache 2.0见 LICENSE。若你希望在完整 SDK 项目中自动化这一流程还可以进一步研究fuels包中围绕fuels.config.ts与typegen命令构建的开发工作流相关示例见 apps/demo-fuels/fuels.config.ts 与 apps/demo-fuels/fuels.config.full.ts让每次forc build后自动刷新类型成为可能。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考