Fuel 网络 TypeScript SDK 中的 B512 类型Sway 公钥/签名处理与合约调用实战指南【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts本文聚焦 Fuel 生态中的B512512 位类型讲解它在 Sway 侧如何定义、在 fuels-ts SDK 中如何表示与可视化以及如何调用接受B512参数的合约函数。读完本文你将掌握在 fuels-ts 中将钱包公钥作为B512输入传给合约、并用 TypeScript 校验返回值的一套完整写法同时理解B512在 ABI 编解码与类型生成链路中的底层工作原理。B512是什么两个b256拼成的 64 字节结构在 Sway 中B512通常被用来承载公钥和签名等需要 512 位64 字节表达的二进制数据。文档明确说明B512本质上是两个b256的包装器wrapper用于表示 64 字节的值并被定义为一个结构体struct。SDK 文档在 Sway 示例 bytecode-input/src/main.sw 中给出了这一结构的典型定义// #region b512-1 pub struct B512 { /// The two B256s that make up the B512. bits: [b256; 2], } // #endregion b512-1需要说明的是上述代码片段是文档用于演示B512结构形态的自定义定义。在真实项目中Sway 标准库已经提供了成熟的B512位于std::b512::B512模块因此在实际的 Sway 合约中通常直接以use std::b512::B512;方式导入使用——这一点在下面的回显合约示例中可以看到而无需自行重新声明结构体。从底层看b256是 Sway 对 256 位哈希值的原生表达一个b256占 32 字节[b256; 2]数组即 2 × 32 64 字节正好构成 512 位。该字段名bits也直观表明这一结构体本质上就是一组比特集合可以被扁平化为一段连续的 64 字节缓冲区参与 ABI 编解码。B512在 SDK 中如何表示一个 0x 前缀的 64 字节十六进制字符串与 Sway 侧结构体的视角不同在 fuels-ts SDK 中B512并不需要被显式构造为对象而是直接以带0x前缀、长度为 64 字节的十六进制字符串来参与类型交互。理解这一点最直观的方式是查看钱包公钥——secp256k1 公钥恰好就是 64 字节正好以B512形式呈现。文档在 b512-in-the-sdk.ts 中展示了这一可视化过程import { Provider, Wallet } from fuels; import { LOCAL_NETWORK_URL } from ../../../../env; const provider new Provider(LOCAL_NETWORK_URL); const wallet Wallet.generate({ provider }); console.log(public key, wallet.publicKey); // 0x97e3a666e4cd34b6b3cf778ef5ec617de4439b68f7a629245442a1fece7713094a1cb0aa7ad0ac253ca1ea47d4618f9090b2a881e829e091fb2c426763e94cca在上面的例子中通过Provider(LOCAL_NETWORK_URL)连接本地 Fuel 节点LOCAL_NETWORK_URL来自文档应用的环境配置文件 apps/docs/src/env.ts用Wallet.generate({ provider })生成一个新钱包访问wallet.publicKey属性即可获得一个形如0x97e3a6...e94cca的 128 位十六进制字符即 64 字节、512 位的公钥字符串它天然就是一个合法的B512值。这类可以原样直传的十六进制值使得 SDK 侧对B512的处理非常轻量你不需要从钱包公钥、签名或其他 64 字节数据手动构造任何包装类直接把字符串传入合约函数参数即可。从源码印证B512在 ABI 层被当作定长字节串处理SDK 对B512的字符串化处理并非临时约定而是贯穿 ABI 类型系统与编解码器两处源码实现的确定性行为。类型生成侧abi-typegen在类型识别器 B512Type.ts 中B512被识别为 Sway ABI 里的struct std::b512::B512匹配正则/^struct (std::b512::)?B512$/m而它作为生成的 TypeScript 参数/返回值标签直接就是string——其单元测试 B512Type.test.ts 断言了attributes.inputLabel string且outputLabel string且无需额外的 fuels 成员导入。也就是说由fuels typegen生成出来的合约方法签名中B512参数的类型就是普通的string。编解码侧abi-coder在编码器分派逻辑 getCoderV1.ts 中ABI 类型名struct std::b512::B512常量定义见 constants.ts被映射到专门的B512Coder。该编解码器实现于 B512Coder.tsexport class B512Coder extends Coderstring, string { constructor() { super(b512, struct B512, WORD_SIZE * 8); // WORD_SIZE 8故编码长度为 64 字节 } encode(value: string): Uint8Array { // 通过 arrayify 将十六进制字符串转为字节 // 长度必须严格等于 64否则抛出 FuelErrorInvalid struct B512 } decode(data: Uint8Array, offset: number): [string, number] { // 校验 data 长度 ≥ 64 字节 // 若整段为零值则规范化为 64 个零字节 // 最终经 toHex 补齐为固定 64 字节的十六进制字符串返回 } }从上述实现可以得到几个关键事实B512Coder的encode通过arrayify把传入字符串转为字节并强制校验长度恰好为 64 字节多一字节或少一字节都会抛出Invalid struct B512错误decode在解码时会把字节补齐、统一输出为 64 字节固定宽度的十六进制字符串且对全零值做了专门处理与之对应的单元测试 B512Coder.test.ts 覆盖了零值编解码、标准 64 字节编解码、过短/过长十六进制字符串报错、非十六进制字符串报错、用 32 字节b256值冒充B512报错等边界情况。一言以蔽之ABI 侧的B512就是一段必须严格的 64 字节数据SDK 用固定宽度的十六进制字符串与之互转。理解这一点你就能解释为什么调用合约时传入的公钥字符串不能截断、不能补位不足。实战合约函数中回显echo一个B512值Sway 合约端声明接受B512的函数文档在示例合约 docs/sway/echo-values/src/main.sw 中定义了名为EchoValues的 ABI其中echo_b512函数接受一个B512参数并原样返回contract; use std::b512::B512; abi EchoValues { fn echo_b512(input: B512) - B512; } impl EchoValues for Contract { // #region b512-3 fn echo_b512(input: B512) - B512 { input } // #endregion b512-3 }注意这里与自定义结构体版本的区别合约通过use std::b512::B512;引入了 Sway 标准库定义函数签名直接书写B512类型即可。当合约被编译后ABI 描述中该参数的类型为struct std::b512::B512SDK 的类型生成器与编码器上文所述会自动将其与 TypeScript 的string对接。TypeScript 端把钱包公钥作为B512传入并校验返回值文档在 echoing-a-b512.ts 中给出了完整调用流程import { Provider, Wallet } from fuels; import { LOCAL_NETWORK_URL, WALLET_PVT_KEY } from ../../../../env; import { EchoValuesFactory } from ../../../../typegend; const provider new Provider(LOCAL_NETWORK_URL); const wallet Wallet.fromPrivateKey(WALLET_PVT_KEY, provider); const deploy await EchoValuesFactory.deploy(wallet); const { contract } await deploy.waitForResult(); // #region snippet-1 const b512 wallet.publicKey; const { value } await contract.functions.echo_b512(b512).get(); // #endregion snippet-1 console.log(value, value);这段代码包含四个关键步骤准备钱包与 ProviderWallet.fromPrivateKey(WALLET_PVT_KEY, provider)通过文档测试环境配置的私钥恢复出一个签名钱包用于部署合约LOCAL_NETWORK_URL与WALLET_PVT_KEY均来自 apps/docs/src/env.ts部署合约调用由 ABI 类型生成产生的EchoValuesFactory该工厂来自fuels typegen针对 Sway 合约产物生成的结果通过deploy.waitForResult()等待部署完成并拿到contract实例构造B512输入并调用直接取wallet.publicKey64 字节十六进制字符串作为b512变量把它传给生成的合约方法contract.functions.echo_b512(b512)——无需任何装箱或转换因为生成的参数类型就是string读取结果并校验.get()执行一次只读/模拟dry-run调用获取返回值文档强调期望返回的value与传入的原始公钥完全一致即echo_b512忠实回显了输入的B512值。注意事项示例中的b512直接取自钱包公钥这正好符合文档对B512用途的定位承载公钥/签名。如果你的输入来自其他来源例如签名结果只要它是一个严格 64 字节、带0x前缀的十六进制字符串即可同样直传调用用的是.get()模拟调用适用于需要读取返回值的场景若需要将写入型调用上链则需换成.call()等提交方式输入必须是完整 64 字节若误传 32 字节的b256值或长度不符的字符串编码层会抛出Invalid struct B512参见 B512Coder.test.ts 中encoding a 256 bit hash string等用例。总结围绕B512你可以在三个层面建立一致的心智模型层面B512的形态依据Sway 语言层两个b256组成的结构体共 64 字节bytecode-input/src/main.sw、std::b512::B512SDK / ABI 类型层普通string十六进制字符串由类型生成器自动映射B512Type.ts、B512Type.test.ts编解码层固定 64 字节缓冲与 hex 字符串双向转换、严格校验长度B512Coder.ts、B512Coder.test.ts实际开发中你只需记住最实用的两条SDK 里B512就是字符串钱包publicKey以及 64 字节签名等可以直接作为合约B512参数传入无需构造包装对象长度必须严格为 64 字节任何长度不符的输入都会被 ABI 编码器以Invalid struct B512拒绝。若需进一步了解相近类型可继续阅读本指南的 b256.md32 字节哈希与 bytes32.md以及 types 指南索引 中的其他原生类型章节。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考