fuels-ts 中 Asset ID资产标识类型详解从类型定义到合约调用实战【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-tsAsset ID 是 Fuel 区块链上唯一标识一类资产的 256 位哈希值可用于表示原生资产与各类自定义 Token。本指南以 fuels-ts 官方文档asset-id.md为骨架结合 SDK 源码与配套 Sway 合约完整讲解AssetId类型的内存结构、构造方式以及如何把它作为参数传入智能合约并验证返回值。读完你将能够在自己的 fuels-ts 项目中正确创建、传递与比较AssetId。AssetId 的本质包装 B256 的结构体在 fuels-ts 中AssetId被建模为一个 JavaScript 对象类型的Struct其内部只有一个名为bits的 B256 字段。SDK 官方文档对该类型的描述是它的定义与 Sway 标准库中的AssetId一致——即一个内层包裹B256值的结构体包装器Struct wrapper around an inner B256 value。在 packages/address/src/types.ts 中可以看到其精确的 TypeScript 定义/** * prop bits - A wrapped 256 bit hash string */ export type AssetId { bits: B256Address; };其中B256Address是string类型的别名同文件中export type B256Address string;实际使用时是带0x前缀的 64 位十六进制字符串。也就是说一个合法的AssetId在运行时就是{ bits: 0x... }这样形状的普通对象。TS SDK 在 ABI 类型解析侧同样对AssetId有专门的映射处理在 packages/abi-typegen/src/abi/types/AssetIdType.ts 中AssetIdType直接继承自B256Type其swayType为struct AssetId匹配正则/^struct AssetId$/m。这说明类型生成器typegen会把 Sway ABI 中的struct AssetId精确识别并翻译为上述{ bits }结构而不会把它误当作裸b256。构造一个 AssetId 实例构造AssetId最直接的方式是使用对象字面量填充bits字段。若你想先得到一个随机值用于测试可以借助 fuels 导出的getRandomB256函数。以下代码来自官方示例 apps/docs/src/guide/types/snippets/asset-id/intro.tsimport type { AssetId } from fuels; import { getRandomB256 } from fuels; const b256 getRandomB256(); const assetId: AssetId { bits: b256, };需要留意两点这里AssetId以import type方式引入因为它仅用于类型标注运行时对象并不依赖任何构造函数。也可以直接手写固定的十六进制字符串例如bits: 0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c后续小节中的合约交互示例采用的就是这种硬编码方式。在 Sway 合约中比较与返回 AssetIdAssetId常被用在需要做资产判断的业务场景里。为了演示如何在合约间传递该类型官方提供了一个配套的 Sway 合约echo-asset-id完整源码位于 apps/docs/sway/echo-asset-id/src/main.sw其核心 ABI 如下abi EvmTest { fn echo_asset_id() - AssetId; fn echo_asset_id_comparison(asset_id: AssetId) - bool; fn echo_asset_id_input(asset_id: AssetId) - AssetId; } const ASSET_ID: AssetId AssetId::from(0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c);该合约演示了AssetId的三种典型用法echo_asset_id直接返回一个硬编码常量ASSET_IDecho_asset_id_comparison接收一个AssetId入参与ASSET_ID做相等比较并返回布尔值echo_asset_id_input原样回传传入的AssetId。注意合约常量中的0x9ae5b658...与 TS 侧示例使用的bits值完全一致——这正是为了验证「TS 构造的对象能通过 ABI 编码被合约精确还原并比较相等」。实战调用合约方法并验证返回值将 AssetId 传入合约函数先通过类型生成工具typegen得到的EchoAssetIdFactory部署合约再把构造好的AssetId作为参数调用echo_asset_id_comparison完整代码见 apps/docs/src/guide/types/snippets/asset-id/using-an-asset-id-1.tsimport type { AssetId } from fuels; import { Provider, Wallet } from fuels; import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from ../../../../env; import { EchoAssetIdFactory } from ../../../../typegend; const provider new Provider(LOCAL_NETWORK_URL); const wallet Wallet.fromPrivateKey(WALLET_PVT_KEY, provider); const deploy await EchoAssetIdFactory.deploy(wallet); const { contract } await deploy.waitForResult(); const assetId: AssetId { bits: 0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c, }; const { value } await contract.functions .echo_asset_id_comparison(assetId) .get();执行流程拆解建立与本地测试网络的Provider连接并用私钥恢复出签名wallet对应 apps/docs/src/env.ts 中导出的LOCAL_NETWORK_URL、WALLET_PVT_KEY测试常量EchoAssetIdFactory.deploy(wallet)将合约部署上链waitForResult()等待交易确认并取出contract实例contract.functions.echo_asset_id_comparison(assetId)完成参数编码与调用.get()触发链上执行并解码返回结果。由于 TS 侧传入的bits与合约常量ASSET_ID相同value应当为true。这是 SDK 类型系统与 Swaystruct AssetId编解码对齐的直观证明入参对象被 ABI 编码后合约端能正确读取并参与比较。读取合约返回的 AssetId反向验证同样重要——合约返回的AssetId应能被 TS SDK 解码回{ bits: 0x... }结构。官方示例 apps/docs/src/guide/types/snippets/asset-id/using-an-asset-id-2.ts 展示了这一过程const { value } await contract.functions.echo_asset_id().get(); console.log(value, value); // const value: AssetId { // bits: 0x9ae5b658754e096e4d681c548daf46354495a437cc61492599e33fc64dcdc30c, // };从类型生成器产物的视角看echo_asset_id的返回类型会被生成为AssetId因此value被推断为{ bits: string }。这里能解码回与合约常量完全一致的哈希字符串印证了AssetId在整个调用链路TS 编码 → Sway 解码 → Sway 编码 → TS 解码中的无损往返。关键实践要点记得区分AssetId与裸b256AssetId是基于b256的结构体包装TypeScript 类型上二者并不等价调用以struct AssetId声明参数的合约函数时必须传{ bits }形状的对象。确保bits是合法 B256bits需为 64 位十六进制含0x前缀字符串传入非法格式会在 ABI 编码阶段被 SDK 校验拦截。善用 typegen 产物部署合约时优先使用fuels typegen生成的 Factory 与强类型 ABI本示例中的EchoAssetIdFactory可获得AssetId的编译期类型检查与自动编解码无需手写参数处理。测试网络配置示例均基于本地 Fuel 节点LOCAL_NETWORK_URL在真实网络上运行时请替换 Provider 地址与资金充足的私钥。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
