fuels-rs 类型指南：Bits256 与 Fuel `b256` 的表示、转换与合约调用

fuels-rs 类型指南Bits256 与 Fuelb256的表示、转换与合约调用【免费下载链接】fuels-rsFuel Network Rust SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs导读b256是 Fuel 与 Sway 中承载哈希值、地址等 256 位数据的核心内建类型。本文围绕 fuels-rsFuel Network 官方 Rust SDK中与b256一一对应的包装类型Bits256完整讲解其定义结构、from_hex_str十六进制转换、作为合约方法输入输出参数的调用方式并结合 SDK 源码与端到端测试剖析其在Parameterize/Tokenizable体系下的编码原理以及由其衍生出的B512、EvmAddress、Identity等相关类型。读完后你将能够准确地在 Rust 侧构造、转换并传递b256数据写出可运行、可验证的合约交互代码。Fuel 的b256与 Rust 侧的Bits256在 Fuel 生态中b256用于表示256 位32 字节的定长值最常见的用途是承载各种哈希与标识符例如 Sway 标准库中的Address、ContractId以及资产标识AssetId的底层原始数据本质上都是 256 位。Rust 与 Rust 原生数组类型之间并没有直接的b256对应物因此 fuels-rs 在 packages/fuels-core/src/types/core/bits.rs 中提供了一个元组结构体包装// A simple wrapper around [u8; 32] representing the b256 type. #[derive(Debug, PartialEq, Eq, Copy, Clone)] pub struct Bits256(pub [u8; 32]);其字段.0是一个[u8; 32]——恰好 32 个字节按顺序排列与 Sway 侧b256的内存布局一一对应。包装器同时派生了Debug、PartialEq、Eq、Copy、Clone意味着Bits256既可以参与assert_eq!等比较运算也能以值语义自由复制传递。从源码注释可以看出这个包装的存在是有意为之它主要为了让Bits256拥有与裸[u8; 32]不同的类型身份从而能在 SDK 的编码体系中与普通定长字节数组区分开来单独映射到 ABI 中的b256基本类型。这一点在 fuels-core 的编码测试中体现得很直接——在 bits.rs 的单元测试里EvmAddress的参数字段被映射为ParamType::B256而其into_token结果则是Token::B256。也就是说Bits256↔ 编码体系的ParamType::B256序列化后对应 ABI 中的Token::B256底层是一个 32 字节数组。关键事实速览项目说明Sway/Fuel 侧类型b256256 位定长值常用于哈希与标识符fuels-rs 侧类型Bits256(pub [u8; 32])元组结构体包装占用字节32 字节256 bit派生的 traitDebug、PartialEq、Eq、Copy、Clone编码位置ParamType::B256/Token::B256主要源码packages/fuels-core/src/types/core/bits.rs构造与转换Bits256直接以字节数组构造由于Bits256的字段是pub的最常见的构造方式是直接传入 32 个字节的数组字面量let b256 Bits256([1; 32]); // 32 个值为 1 的字节这也是端到端测试中惯用的写法。通过from_hex_str从十六进制字符串转换真实场景中哈希与地址通常以十六进制字符串的形式出现例如0x0...0形式的区块哈希、合约 ID。为此Bits256提供了关联函数from_hex_str见 packages/fuels-core/src/types/core/bits.rs#L19-L32pub fn from_hex_str(hex: str) - ResultSelf { let hex if let Some(stripped_hex) hex.strip_prefix(0x) { stripped_hex } else { hex }; let mut bytes [0u8; 32]; hex::decode_to_slice(hex, mut bytes as mut [u8])?; Ok(Bits256(bytes)) }支持两种输入形式函数会先通过strip_prefix(0x)判断字符串是否带0x前缀无论带不带都会正常处理随后用hex::decode_to_slice将十六进制字符串解码进一个恰好 32 字节的缓冲区最终包裹成Bits256。它的返回类型是ResultSelf由于解码目标是固定长度的[u8; 32]字符串必须恰好是 64 个十六进制字符128 字符带0x时对应 64 个十六进制位。字符串长度不符或包含非十六进制字符时函数会通过?将解码错误向上传播调用方需要妥善处理。单元测试见 bits.rs同时验证了两种形式// 不带 0x 前缀 let hex_str 0101010101010101010101010101010101010101010101010101010101010101; let bits256 Bits256::from_hex_str(hex_str)?; assert_eq!(bits256.0, [1u8; 32]); // 带 0x 前缀 let hex_str 0x0101010101010101010101010101010101010101010101010101010101010101; let bits256 Bits256::from_hex_str(hex_str)?; assert_eq!(bits256.0, [1u8; 32]);提示十六进制字符串中每两个字符编码一个字节因此01 01 ... 0132 对恰好解码为[1u8; 32]。获取全零值SDK 还提供了一个便捷构造函数zeroed()返回内部为 32 个零字节的Bits256见 bits.rspub fn zeroed() - Self { Self([0; 32]) }它在初始化默认哈希/占位地址时很实用。在合约调用中传入和接收b256Sway 侧的定义端到端测试的合约 e2e/sway/types/contracts/b256/src/main.sw 提供了一个最小可运行的例子分别演示了b256作为返回值与入参contract; abi MyContract { fn b256_as_output() - b256; fn b256_as_input(foo: b256) - bool; } impl MyContract for Contract { fn b256_as_output() - b256 { 0x0202020202020202020202020202020202020202020202020202020202020202 } fn b256_as_input(foo: b256) - bool { foo 0x0101010101010101010101010101010101010101010101010101010101010101 } }合约方法b256_as_output返回固定的全0x02哈希b256_as_input接收一个b256并与全0x01的期望值比较返回是否相等。Rust 侧的调用必须传Bits256编写 Rust 调用代码时的核心约束是只要合约方法以b256作为参数从 SDK 调用时就务必传入Bits256([u8; 32])而Bytes32、裸数组等其他类型不会被识别为该参数。对应的集成测试位于 e2e/tests/types_contracts.rs#L1401-L1437test_b256文档所引用的输入示例256_arg完整形态如下// ANCHOR: 256_arg let b256 Bits256([1; 32]); let call_handler contract_instance.methods().b256_as_input(b256); // ANCHOR_END: 256_arg assert!(call_handler.call().await?.value);测试使用setup_program_test!宏完成钱包创建、ABI 生成与合约部署合约工程指向e2e/sway/types/contracts/b256随后构造Bits256([1; 32])32 个1字节等价于十六进制0x0101...01通过生成的contract_instance.methods().b256_as_input(b256)发起调用断言返回值value为true——因为合约内正是拿入参与全0x01期望值比较。返回值与测试中的双向验证同一个测试还验证了b256作为方法返回值时的解码见 types_contracts.rs#L1416-L1424assert_eq!( Bits256([2; 32]), // 期望值全 0x02 contract_instance .methods() .b256_as_output() .call() .await? .value );合约返回字面量0x0202...02SDK 解码后得到 Rust 侧的Bits256([2; 32])两者经assert_eq!直接比对一致。这证明Bits256实现了对称的编码入参与解码出参能力是 SDK 与 FuelVM 之间传输b256数据的标准通道。业务代码中的组合用法实践中哈希地址常以十六进制字符串存储因此更常见的写法是先from_hex_str转换、再传入调用。以同一测试文件中的test_evm_address场景为例types_contracts.rs#L347-L386let b256 Bits256::from_hex_str( 0x1616060606060606060606060606060606060606060606060606060606060606, )?; // ……将 b256 转换为 EvmAddress 后作为方法入参基于Bits256衍生与组合的类型Bits256是 fuels-core 中一批大字节类型的基础构件在 packages/fuels-core/src/types/core/bits.rs 中可直接看到其衍生关系B512包裹[Bits256; 2]两个 256 位值组成 512 位并实现From(Bits256, Bits256)。它对应 Sway 中的b512签名类型文档说明见 docs/src/types/B512.md。EvmAddress内部字段value: Bits256但只使用其中后 20 字节构造时通过clear_12_bytes将最左侧 12 字节清零对应 EVM 的 20 字节地址在 256 位容器中的存放约定见 bits.rs#L68-L92。类型互转Bits256实现了FromAssetId与FromSubAssetId见 bits.rs#L35-L45可以直接从fuel_types::AssetId等底层标识类型转换而来。此外地址与合约 ID 在 SDK 中多以Bits256作为基础载体——例如测试中使用Identity::Address(expected_address)构造身份枚举types_contracts.rs#L1035-L1041Identity::Address变体内部承载的正是 256 位的地址原始数据。与其他 256 位类型的辨析文档 docs/src/types/bytes32.md 对易混淆点做了明确说明Fuel 中还存在同样承载 256 位哈希的Bytes32但它与b256/Bits256在 Rust SDK 中的身份与用途不同——合约方法签名中的b256参数只能用Bits256([u8; 32])传递。因此开发时请遵循以下对应关系你在 Sway 中看到的类型传给 fuels-rs 应使用的类型b256Bits256([u8; 32])Address/ContractId本质上基于 256 位哈希由 SDK 生成的对应包装类型其内部承载Bits256哈希返回值的 Rust 侧接收Bits256小结与建议围绕b256类型可以总结出三条实用准则构造字面量用Bits256([...; 32])字符串用Bits256::from_hex_str(hex)兼容或不带0x前缀字符串长度必须恰为 64 个十六进制字符空值可用Bits256::zeroed()调用Sway 方法签名里的b256参数Rust 侧一律以Bits256传入返回值解码后同样是Bits256可直接参与assert_eq!等比较转换需要AssetId/SubAssetId场景可直接通过From互转遇到b512、EVM 地址、身份枚举等复合类型时留意它们内部都以Bits256为底层存储可据此推断正确的数据组织方式。相关验证代码与源码锚点端到端 b256 测试、Sway 测试合约、Bits256 核心实现。【免费下载链接】fuels-rsFuel Network Rust SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考