Sway 数据编码与 ABI 编解码机制深度解析合约调用、脚本、谓词、日志与 Configurables 的字节级真相【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/swaySwayFuel 链上的智能合约语言并不允许调用方直接把参数指针传递给合约而是引入了一套完整的AbiEncode/AbiDecode编码体系让所有跨合约边界的数据都以显式的字节形式交换。本文基于 docs/slides/encoding.md 与 docs/slides/trivial_encoding.md 两份内部技术讲稿结合 sway-lib-std/src/codec.sw 与 sway-core 编译器源码完整还原 Sway 编码体系的设计动机、调用双方的内存布局、各应用场景合约、脚本、谓词、日志、configurables的编译期展开过程以及“平凡编码trivially encodable”优化背后的零拷贝思想。读完本文你将能看懂 Sway 编译器生成代码中encode/abi_decode/__contract_call的全部细节并能在实际合约开发中主动利用平凡编码降低二进制体积与 Gas 消耗。一、为什么 Sway 需要一套编码体系合约 ABI应用二进制接口只定义了“交换什么类型”却没有定义“这些类型如何在内存中被传递”。例如下面的 ABI 声明abi MyContract { fn some_method(arg: Vecu64); }它只约定了some_method接收一个Vecu64但没有约定Vec在内存中的字节布局。如果调用方与合约实现方各自使用不同版本的stdlib对Vec内部字段的顺序定义不同双方就会互相“读错”数据。编码体系的第一个作用就是消除这种 ABI 不稳定ABI instability。它强制每个类型通过实现AbiEncode/AbiDecode特征来显式声明“自己如何被编码、如何被解码”implT AbiEncode for VecT where T: AbiEncode { fn abi_encode(self, buffer: Buffer) - Buffer { ... } } implT AbiDecode for VecT where T: AbiDecode { fn abi_decode(ref mut buffer: BufferReader) - VecT { ... } }为了改善开发体验编译器会自动为所有不含指针pointer的类型实现AbiEncode/AbiDecode——即结构体、元组、数组等普通数据类型无需开发者手写编解码逻辑。除此之外编码体系还要解决另外两个关键问题返回值降级Return Value Demotion与别名攻击Aliasing详见本文第三节。二、合约调用两侧的完整数据流2.1 调用方视角Caller POV当你写出下面这段代码时let contract abi(TestContract, CONTRACT_ID); contract.some_method(0);编译器会先把它脱糖desugar为对标准库std::codec::contract_call的调用std::codec::contract_call( CONTRACT_ID, some_method, (0,), )在 sway-lib-std/src/codec.sw 中contract_call的实际实现正是按照“编码 → 打包参数 → 调用内建函数 → 解码返回值”的流程展开的pub fn contract_callT, TArgs( contract_id: b256, method_name: raw_slice, args: TArgs, coins: u64, asset_id: b256, gas: u64, ) - T where T: AbiDecode, TArgs: AbiEncode, { let second_parameter encode(args); let params ( contract_id, asm(a: method_name.ptr()) { a: u64 }, asm(a: second_parameter.ptr()) { a: u64 }, ); __contract_call(params, coins, asset_id, gas); let ptr asm() { ret: raw_ptr }; decode_from_raw_ptr::T(ptr) }对应讲稿中的展开形式即let first_parameter encode(some_method); let second_parameter encode((0,)); let params encode(( CONTRACT_ID, first_parameter.ptr(), second_parameter.ptr(), )); let (ptr, len) __contract_call(params.ptr(), coins, asset_id, gas); let mut buffer BufferReader::from_parts(ptr, len); T::abi_decode(buffer)其中first_parameter对方法名字符串some_method编码得到的字节second_parameter对实参元组(0,)编码得到的字节params把合约 ID32 字节、方法名指针、实参指针打包后的参数区coins/asset_id/gas随调用携带的代币数量、资产 ID 与 Gas 上限。最终__contract_call会被编译为一条fuelVM 的call指令其内存布局如下$hp指向堆顶$ssp与$sp是栈指针$hp │ │ ┌────────────────────────────┐ ▼ │ │ ┌──────────────┬──────┴──────┬──────────────┬──────▼────────┬───────────────┐ │ │ │ │ │ │ HEAP │ CONTRACT_ID │ method name │ method args │ encoded bytes │ encoded bytes │ │ 32 bytes │ param1 │ param2 │ │ │ └──────▲───────┴─────────────┴──────┬───────┴───────────────┴───────▲───────┘ │ │ │ │ └───────────────────────────────┘ │ ... │ call $ra:ptr $rb:u64 $rc:ptr $rd:u64 ... coins │ gas │ ┌▼─────────────┐ │ │ STACK .................... │ ASSET_ID │ │ 32 bytes │ └──────────────┘ ▲ ▲ │ │ │ │ $ssp $sp可以看到被调用合约可以访问到的只是堆上的一段“编码后”字节以及栈上由调用方维护的ASSET_ID32 字节而永远无法拿到调用方内存中的真实对象指针——这正是下一节要讲的安全设计。2.2 被调用方视角Contract being called POV假设目标合约的实现是impl TestContract for Contract { fn some_method(qty: u64) { ... } }编译器会把合约入口脱糖为一个统一的__entry函数pub fn __entry() { let method_name std::codec::decode_first_param::str(); if method_name some_method { let mut buffer std::codec::BufferReader::from_second_parameter(); let args: (u64,) buffer.decode::(u64,)(); let result: () __contract_entry_some_method(args.0); let result: raw_slice encode::()(result); __contract_ret(result.ptr(), result.len::u8()); } __revert(123); }两个关键说明__contract_entry_some_method就是原始some_method的编译产物保持原样__contract_ret是一个“立即返回当前上下文”的特殊函数因此生成代码中不再需要return。这段脱糖逻辑与标准库中的实际 API 完全对应decode_first_param与decode_second_param分别从调用帧call frame的第 73 与 74 个字偏移处读取参数指针见 sway-lib-std/src/codec.sw 与其使用的BufferReader::from_first_parameter/from_second_parameter第 69–96 行其中FIRST_PARAMETER_OFFSET: u64 73、SECOND_PARAMETER_OFFSET: u64 74。被调用方在真正执行合约方法之前内存布局如下——注意栈上的param1 73 words、param2 74 words与上面偏移量逐一吻合$hp | | ---------------------------- v | | ----------------------------------------------v----------------------- | | | | | | HEAP | CONTRACT_ID | method name | method args | encoded bytes | encoded bytes | | 32 bytes | param1 | param2 | | | ----------------------------------------------^---------------^--^---- | | | | ------------------------------ | | | ------------------------- | | | | ------------------------------------- | | ------------------------------------- | | param1 param2 | STACK | ASSET_ID | 73 words 74 words | | 32 bytes | offset offset | --------------------------------------- ^ call frame metadata ^ | | | | $fp $ssp/$sp2.3 编译器侧的佐证在编译器源码中__contract_call与__contract_ret是作为内建函数intrinsic被类型检查的见 sway-core/src/semantic_analysis/ast_node/expression/intrinsic_function.rs而方法调用若指向合约会在类型化语法树中携带ContractCallParams含可选的 4 字节func_selector见 sway-core/src/language/ty/expression/contract.rs。从源码结构可以推断方法名、实参是否编码、如何编码完全由编译器在脱糖阶段决定合约作者无需手动干预。三、为什么不能直接传指针——编码的三大动机讲稿用了一个专门章节“Interlude: Why even encode the data?”来回答“为什么不把所有参数直接传递过去”核心原因有三条3.1 规避 ABI 不稳定ABI instabilityAPI 只定义类型不定义字节布局。设想调用方与被调用方都用std-lib v1编译VecT的内存结构是struct VecT { pointer: raw_ptr, cap: u64, len: u64, }而合约实现方随后升级到std-lib v2不知何故把字段顺序改成了struct VecT { len: u64, pointer: raw_ptr, cap: u64, }那么调用方从此再也无法正确调用该合约——这就是“ABI Hell”| BEFORE | AFTER | ----- { 0x...., 16, 4 } ---- | ----- { 0x...., 16, 4 } --- | | | | | | | | | | { pointer, capacity, len } { pointer, capacity, len } | { pointer, capacity, len } { len, pointer, capacity } | What What | What What CALLER CALLEE | CALLER CALLEE sends sees | sends sees Vec std-lib v1 Vec std-lib v1 | Vec std-lib v1 Vec std-lib v2再进一步想象库版本、编译器版本、编译参数、编译器优化都可能改变字节布局。这些变化不仅会悄无声息地破坏合约调用还会破坏所有消费这些字节的下游——索引器indexers、SDK、receipt 解析器等。而 Sway 的编码方案强制每个类型显式声明编解码方式从根上规避了这一类问题。3.2 返回值降级Return Value Demotion考虑一个返回Vecu64的合约方法impl TestContract for Contract { fn some_method() - Vecu64 { Vec::new() } }实际上它会被编译成类似下面的形式——这被称为“Return Value Demotion”fn __contract_entry_some_method(return_value: mut Vecu64) { *return_value Vec::new(); }问题在于return_value会指向被调用方callee的内存区域而合约无法写入对方内存。这要求return_value指向由合约自己分配的某处内存再交由被调用方复制过去。编码机制让返回值也以字节形式回传从而绕开了“跨内存空间写指针”的难题。3.3 别名攻击Aliasing与安全边界如果绕过编码、允许调用方直接把指针传给合约会立刻产生安全问题恶意调用方可以构造别名aliased数据结构来欺骗合约。例如impl TestContract for Contract { fn some_method(v: Vecu64) { let some_value1 do_something(v); // do some_thing that allocate memory let some_value2 do_something(v); } }恶意调用方可以构造一个指针指向合约自身内存的Vec。上面代码中就可能出现some_value1 ! some_value2这种完全反直觉的结果从而让调用方有机可乘地攻击合约。因此 Sway 的编码方案不允许传递指针、引用等——你永远只能传递数据本身。四、编码体系覆盖的全部场景除合约调用外Sway 的编码体系还覆盖以下四个场景讲稿将它们统称为“What we have left”4.1 脚本Scripts与谓词Predicatesscript和predicate的main函数可以带参数fn main(v: u64) - bool { ... }两种情况下编译器都会脱糖为类似下面的入口pub fn __entry() - raw_slice { let args: (u64,) decode_script_data::(u64,)(); // or decode_predicate_data let result: u64 main(args.0); encode::u64(result) }标准库中的对应实现分别是decode_script_data通过__gtf::raw_ptr(0, 0xA)读取脚本数据区与decode_predicate_data通过gm指令取得验证谓词索引再根据输入类型读取谓词数据见 sway-lib-std/src/codec.sw 及BufferReader::from_script_data/from_predicate_data第 98–119 行。4.2 日志与回执Logs / Receipts调用std::log时其参数同样会被编码。因此log(1);会被脱糖为__log(encode(1));在 sway-lib-std/src/logging.sw 中logT的实现是__log::T(value)在开启新编码experimental_new_encoding true时约束T: AbiEncode——也就是说日志内容会以编码后的字节形式出现在回执receipt中链下解析方只要遵循同一套编解码规则即可读取。4.3 Configurables可配置常量Configurables 稍微复杂一些它们的初始化值在编译期就被求值。例如configurable { SOMETHING: u64 1, }上面这个例子会求值为1。编译器随后调用encode(1)并把结果追加到二进制文件的末尾。为了允许 SDK 在部署前替换该值编译器会在生成的ABI JSON中写入一条记录包含该缓冲区在二进制中的偏移{ name: SOMETHING, configurableType: { ... }, offset: 7104 },那么 configurables 是如何“解码”的呢这部分由编译器自动完成。例如configurable { SOMETHING: u64 1 } fn main() - u64 { SOMETHING }会被脱糖为类似下面的样子注意这不是合法的 Sway 语法仅用于表达编译器的行为const SOMETHING: u64; fn __entry() - raw_slice { std::codec::abi_decode_in_place(mut SOMETHING, 7104, 8); encode(main()) } fn main() - u64 { SOMETHING }其中abi_decode_in_placesway-lib-std/src/codec.sw会直接在原位置解码若类型平凡可解码则用一条mcp内存复制指令完成否则先解码到临时变量再复制到目标地址。这里传入的7104正是 ABI JSON 中记录的offset8是u64的字节长度。五、平凡可编码 / 可解码类型Trivially Encodable/Decodable Types编码和解码并非免费它们会增加二进制体积也会增加 Gas 消耗。除非——参数是平凡可编码的trivially encodable且返回类型是平凡可解码的trivially decodable。5.1 定义内存表示 编码表示一个类型是“平凡可编码/可解码”的当且仅当它的运行时内存表示与其编码表示完全一致有一个下文会讲到的例外。这与“零拷贝反序列化zero-copy deserialization”是同一个思想零拷贝反序列化是一种允许直接从序列化字节缓冲区访问数据的技术无需分配新内存或将数据复制到独立结构中。这是通过保证序列化格式的内存布局与目标数据结构的运行时内存表示一致来实现的从而可以直接通过类型转换或指针偏移访问字段而无需任何解析或转换工作。例 1对齐的元组。一个全由u64组成的元组运行时与编码后完全相同fn main ( _: (1u64, 2u64, 3u64) ) { ... }运行时表示------------------------------------- | 00 ... 01 | 00 ... 02 | 00 ... 03 | -------------------------------------编码表示------------------------------------- | 00 ... 01 | 00 ... 02 | 00 ... 03 | -------------------------------------例 2出现填充padding的元组。一旦混入u8运行时为了对齐会插入 padding编码表示则不含 padding二者不再一致fn main ( _: (1u8, 2u64, 3u64) ) { ... }运行时表示------------------------------------------ | 01 | 00 ... 00 | 00 ... 02 | 00 ... 03 | ------------------------------------------ ^^^^^^^^^ padding编码表示------------------------------ | 01 | 00 ... 02 | 00 ... 03 | ------------------------------由于第二个例子的内存表示与编码表示存在错配二进制体积的代价一目了然。讲稿给出了同一程序的两次编译对比平凡场景136 字节Finished release [optimized fuel] target(s) [136 B] in 0.90s非平凡场景208 字节Finished release [optimized fuel] target(s) [208 B] in 0.89s5.2 底层实现is_encode_trivial/is_decode_trivial平凡性的判定与快路径fast path由标准库统一实现pub trait AbiEncode { fn is_encode_trivial() - bool; fn abi_encode(self, buffer: Buffer) - Buffer; } pub trait AbiDecode { fn is_decode_trivial() - bool; fn abi_decode(ref mut buffer: BufferReader) - Self; } pub fn encodeT(item: T) - raw_slice where T: AbiEncode { if T::is_encode_trivial() { ... } else { ... } } pub fn abi_decodeT(data: raw_slice) - T where T: AbiDecode { if T::is_decode_trivial() { ... } else { ... } }实际的encode实现sway-lib-std/src/codec.sw在平凡路径上直接aloc分配、mcp复制一份原样的字节并包装成raw_slice连一次逐字段编解码循环都省掉了abi_decode第 1759–1775 行的平凡路径同样只需mcp拷贝即可。5.3 各基础类型的平凡性一览从 sway-lib-std/src/codec.sw 的AbiEncode实现可以确认以下结论判定依据is_encode_trivial()的返回值类型平凡编码说明u64、u8✅u64按 8 字节、u8按 1 字节无 padding 问题u32、u16❌编码时需消除对齐差异bool✅编码/ ❌解码见下节 Trap Representationsb256、u256✅定长且对齐str动态字符串❌需编码长度信息str[N]视情况experimental_str_array_no_padding false时不平凡第 292–303 行开启 true后平凡第 305–316 行raw_slice❌引用类型数组[T; N]继承T见第 331–349 行元组逐元素判断元组平凡性 __mem_repr_eq::Self(runtime, encoding)且每个元素平凡第 362 行起单元类型()✅空编码元组平凡性判定的关键是内建函数__mem_repr_eq——它在编译期比较某个类型的“运行时表示”与“编码表示”是否等价见 sway-core/src/semantic_analysis/ast_node/expression/intrinsic_function.rs 及其type_check_mem_repr_eq实现。这保证了“内存布局是否与编码布局一致”由编译器静态判定而非运行时猜测。5.4 Trap Representations布局相同也不一定安全解码Trap representation陷阱表示是一种“对该类型而言无效的位模式”。有些类型的内存布局与编码布局一致却仍然不能安全地平凡解码bool平凡可编码但不平凡可解码——任何非 0/1 的位模式都是非法bool直接读取会得到陷阱值枚举enums因为带有“隐藏的判别值discriminant”且该判别值只接受特定取值enum A { A: ..., B: ..., C: ... }-------------------------- | 0000000000000000 | ... | -------------------------- ^^^^^^^^^^^^^^^^ Discriminant (8 bytes)如果开发者愿意承担风险、自行处理非法表示可以强制某个类型按平凡解码处理。讲稿给出的通用包装类型是pub struct TriviallyDecodableT { value: T } implT AbiDecode for TriviallyDecodableT { fn is_decode_trivial() - bool { true } fn abi_decode(ref mut buffer: BufferReader) - Self { let value T::abi_decode(buffer); Self { value } } } fn main(_: TriviallyDecodablebool) { ... }值得一提的还有bool编码侧的标准库特例bool的平凡编码sway-lib-std/src/codec.sw直接复用__encode_buffer_append追加原始字节而 codec.sw 中还提供了TrivialBool { value: u64 }这样的标准库内置平凡类型。务必只在你能保证输入位模式合法的前提下使用强制平凡解码否则会引入未定义行为级别的安全风险。六、实践建议与总结6.1 如何在合约开发中利用平凡编码优先使用无 padding 的紧凑类型组合全u64/u8/b256组成的元组与结构体在编译期会被判定为平凡编解码走零拷贝快路径不增加二进制体积与 Gas避免混入u16/u32/str等触发逐字节编码的类型除非确有必要在 ABI 边界两侧保持相同版本的stdlib与编译器虽然编码体系已隔离了内部字段布局差异但平凡性判定、编码格式仍与编译器版本绑定慎用TriviallyDecodable/TrivialBool这类强制平凡解码它们只适合确信输入受控的场景例如自己链下生成的、经过校验的数据。6.2 全文脉络回顾合约调用时调用方把方法名与实参分别编码打包进堆上的参数区再以call指令连同coins / asset_id / gas交给被调用方被调用方从调用帧第 73 / 74 字偏移读取两段字节并解码执行编码的三大动机是ABI 不稳定、返回值降级Return Value Demotion与别名Aliasing安全同一套编码机制同时服务合约调用、脚本 / 谓词入参、日志回执、configurables四大场景平凡编码 / 解码内存布局 编码布局走alocmcp的零拷贝快路径能显著节省二进制体积与 Gas但bool、枚举等存在 trap representation 的类型即便布局相同也不能安全平凡解码。如果希望继续深入可以阅读讲稿原文 docs/slides/encoding.md 与续篇 docs/slides/trivial_encoding.md研读标准库实现 sway-lib-std/src/codec.swBuffer/BufferReader/AbiEncode/AbiDecode/contract_call/encode/abi_decode跟踪编译器侧的内建函数类型检查 sway-core/src/semantic_analysis/ast_node/expression/intrinsic_function.rs 中的ContractCall、ContractRet、MemReprEq参考 sway-lib-std/src/logging.sw 中log的编码约束以及 examples 目录下的counter、wallet_smart_contract、configurable_constants等示例工程观察真实合约的 ABI 行为。【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Sway 数据编码与 ABI 编解码机制深度解析：合约调用、脚本、谓词、日志与 Configurables 的字节级真相
Sway 数据编码与 ABI 编解码机制深度解析合约调用、脚本、谓词、日志与 Configurables 的字节级真相【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/swaySwayFuel 链上的智能合约语言并不允许调用方直接把参数指针传递给合约而是引入了一套完整的AbiEncode/AbiDecode编码体系让所有跨合约边界的数据都以显式的字节形式交换。本文基于 docs/slides/encoding.md 与 docs/slides/trivial_encoding.md 两份内部技术讲稿结合 sway-lib-std/src/codec.sw 与 sway-core 编译器源码完整还原 Sway 编码体系的设计动机、调用双方的内存布局、各应用场景合约、脚本、谓词、日志、configurables的编译期展开过程以及“平凡编码trivially encodable”优化背后的零拷贝思想。读完本文你将能看懂 Sway 编译器生成代码中encode/abi_decode/__contract_call的全部细节并能在实际合约开发中主动利用平凡编码降低二进制体积与 Gas 消耗。一、为什么 Sway 需要一套编码体系合约 ABI应用二进制接口只定义了“交换什么类型”却没有定义“这些类型如何在内存中被传递”。例如下面的 ABI 声明abi MyContract { fn some_method(arg: Vecu64); }它只约定了some_method接收一个Vecu64但没有约定Vec在内存中的字节布局。如果调用方与合约实现方各自使用不同版本的stdlib对Vec内部字段的顺序定义不同双方就会互相“读错”数据。编码体系的第一个作用就是消除这种 ABI 不稳定ABI instability。它强制每个类型通过实现AbiEncode/AbiDecode特征来显式声明“自己如何被编码、如何被解码”implT AbiEncode for VecT where T: AbiEncode { fn abi_encode(self, buffer: Buffer) - Buffer { ... } } implT AbiDecode for VecT where T: AbiDecode { fn abi_decode(ref mut buffer: BufferReader) - VecT { ... } }为了改善开发体验编译器会自动为所有不含指针pointer的类型实现AbiEncode/AbiDecode——即结构体、元组、数组等普通数据类型无需开发者手写编解码逻辑。除此之外编码体系还要解决另外两个关键问题返回值降级Return Value Demotion与别名攻击Aliasing详见本文第三节。二、合约调用两侧的完整数据流2.1 调用方视角Caller POV当你写出下面这段代码时let contract abi(TestContract, CONTRACT_ID); contract.some_method(0);编译器会先把它脱糖desugar为对标准库std::codec::contract_call的调用std::codec::contract_call( CONTRACT_ID, some_method, (0,), )在 sway-lib-std/src/codec.sw 中contract_call的实际实现正是按照“编码 → 打包参数 → 调用内建函数 → 解码返回值”的流程展开的pub fn contract_callT, TArgs( contract_id: b256, method_name: raw_slice, args: TArgs, coins: u64, asset_id: b256, gas: u64, ) - T where T: AbiDecode, TArgs: AbiEncode, { let second_parameter encode(args); let params ( contract_id, asm(a: method_name.ptr()) { a: u64 }, asm(a: second_parameter.ptr()) { a: u64 }, ); __contract_call(params, coins, asset_id, gas); let ptr asm() { ret: raw_ptr }; decode_from_raw_ptr::T(ptr) }对应讲稿中的展开形式即let first_parameter encode(some_method); let second_parameter encode((0,)); let params encode(( CONTRACT_ID, first_parameter.ptr(), second_parameter.ptr(), )); let (ptr, len) __contract_call(params.ptr(), coins, asset_id, gas); let mut buffer BufferReader::from_parts(ptr, len); T::abi_decode(buffer)其中first_parameter对方法名字符串some_method编码得到的字节second_parameter对实参元组(0,)编码得到的字节params把合约 ID32 字节、方法名指针、实参指针打包后的参数区coins/asset_id/gas随调用携带的代币数量、资产 ID 与 Gas 上限。最终__contract_call会被编译为一条fuelVM 的call指令其内存布局如下$hp指向堆顶$ssp与$sp是栈指针$hp │ │ ┌────────────────────────────┐ ▼ │ │ ┌──────────────┬──────┴──────┬──────────────┬──────▼────────┬───────────────┐ │ │ │ │ │ │ HEAP │ CONTRACT_ID │ method name │ method args │ encoded bytes │ encoded bytes │ │ 32 bytes │ param1 │ param2 │ │ │ └──────▲───────┴─────────────┴──────┬───────┴───────────────┴───────▲───────┘ │ │ │ │ └───────────────────────────────┘ │ ... │ call $ra:ptr $rb:u64 $rc:ptr $rd:u64 ... coins │ gas │ ┌▼─────────────┐ │ │ STACK .................... │ ASSET_ID │ │ 32 bytes │ └──────────────┘ ▲ ▲ │ │ │ │ $ssp $sp可以看到被调用合约可以访问到的只是堆上的一段“编码后”字节以及栈上由调用方维护的ASSET_ID32 字节而永远无法拿到调用方内存中的真实对象指针——这正是下一节要讲的安全设计。2.2 被调用方视角Contract being called POV假设目标合约的实现是impl TestContract for Contract { fn some_method(qty: u64) { ... } }编译器会把合约入口脱糖为一个统一的__entry函数pub fn __entry() { let method_name std::codec::decode_first_param::str(); if method_name some_method { let mut buffer std::codec::BufferReader::from_second_parameter(); let args: (u64,) buffer.decode::(u64,)(); let result: () __contract_entry_some_method(args.0); let result: raw_slice encode::()(result); __contract_ret(result.ptr(), result.len::u8()); } __revert(123); }两个关键说明__contract_entry_some_method就是原始some_method的编译产物保持原样__contract_ret是一个“立即返回当前上下文”的特殊函数因此生成代码中不再需要return。这段脱糖逻辑与标准库中的实际 API 完全对应decode_first_param与decode_second_param分别从调用帧call frame的第 73 与 74 个字偏移处读取参数指针见 sway-lib-std/src/codec.sw 与其使用的BufferReader::from_first_parameter/from_second_parameter第 69–96 行其中FIRST_PARAMETER_OFFSET: u64 73、SECOND_PARAMETER_OFFSET: u64 74。被调用方在真正执行合约方法之前内存布局如下——注意栈上的param1 73 words、param2 74 words与上面偏移量逐一吻合$hp | | ---------------------------- v | | ----------------------------------------------v----------------------- | | | | | | HEAP | CONTRACT_ID | method name | method args | encoded bytes | encoded bytes | | 32 bytes | param1 | param2 | | | ----------------------------------------------^---------------^--^---- | | | | ------------------------------ | | | ------------------------- | | | | ------------------------------------- | | ------------------------------------- | | param1 param2 | STACK | ASSET_ID | 73 words 74 words | | 32 bytes | offset offset | --------------------------------------- ^ call frame metadata ^ | | | | $fp $ssp/$sp2.3 编译器侧的佐证在编译器源码中__contract_call与__contract_ret是作为内建函数intrinsic被类型检查的见 sway-core/src/semantic_analysis/ast_node/expression/intrinsic_function.rs而方法调用若指向合约会在类型化语法树中携带ContractCallParams含可选的 4 字节func_selector见 sway-core/src/language/ty/expression/contract.rs。从源码结构可以推断方法名、实参是否编码、如何编码完全由编译器在脱糖阶段决定合约作者无需手动干预。三、为什么不能直接传指针——编码的三大动机讲稿用了一个专门章节“Interlude: Why even encode the data?”来回答“为什么不把所有参数直接传递过去”核心原因有三条3.1 规避 ABI 不稳定ABI instabilityAPI 只定义类型不定义字节布局。设想调用方与被调用方都用std-lib v1编译VecT的内存结构是struct VecT { pointer: raw_ptr, cap: u64, len: u64, }而合约实现方随后升级到std-lib v2不知何故把字段顺序改成了struct VecT { len: u64, pointer: raw_ptr, cap: u64, }那么调用方从此再也无法正确调用该合约——这就是“ABI Hell”| BEFORE | AFTER | ----- { 0x...., 16, 4 } ---- | ----- { 0x...., 16, 4 } --- | | | | | | | | | | { pointer, capacity, len } { pointer, capacity, len } | { pointer, capacity, len } { len, pointer, capacity } | What What | What What CALLER CALLEE | CALLER CALLEE sends sees | sends sees Vec std-lib v1 Vec std-lib v1 | Vec std-lib v1 Vec std-lib v2再进一步想象库版本、编译器版本、编译参数、编译器优化都可能改变字节布局。这些变化不仅会悄无声息地破坏合约调用还会破坏所有消费这些字节的下游——索引器indexers、SDK、receipt 解析器等。而 Sway 的编码方案强制每个类型显式声明编解码方式从根上规避了这一类问题。3.2 返回值降级Return Value Demotion考虑一个返回Vecu64的合约方法impl TestContract for Contract { fn some_method() - Vecu64 { Vec::new() } }实际上它会被编译成类似下面的形式——这被称为“Return Value Demotion”fn __contract_entry_some_method(return_value: mut Vecu64) { *return_value Vec::new(); }问题在于return_value会指向被调用方callee的内存区域而合约无法写入对方内存。这要求return_value指向由合约自己分配的某处内存再交由被调用方复制过去。编码机制让返回值也以字节形式回传从而绕开了“跨内存空间写指针”的难题。3.3 别名攻击Aliasing与安全边界如果绕过编码、允许调用方直接把指针传给合约会立刻产生安全问题恶意调用方可以构造别名aliased数据结构来欺骗合约。例如impl TestContract for Contract { fn some_method(v: Vecu64) { let some_value1 do_something(v); // do some_thing that allocate memory let some_value2 do_something(v); } }恶意调用方可以构造一个指针指向合约自身内存的Vec。上面代码中就可能出现some_value1 ! some_value2这种完全反直觉的结果从而让调用方有机可乘地攻击合约。因此 Sway 的编码方案不允许传递指针、引用等——你永远只能传递数据本身。四、编码体系覆盖的全部场景除合约调用外Sway 的编码体系还覆盖以下四个场景讲稿将它们统称为“What we have left”4.1 脚本Scripts与谓词Predicatesscript和predicate的main函数可以带参数fn main(v: u64) - bool { ... }两种情况下编译器都会脱糖为类似下面的入口pub fn __entry() - raw_slice { let args: (u64,) decode_script_data::(u64,)(); // or decode_predicate_data let result: u64 main(args.0); encode::u64(result) }标准库中的对应实现分别是decode_script_data通过__gtf::raw_ptr(0, 0xA)读取脚本数据区与decode_predicate_data通过gm指令取得验证谓词索引再根据输入类型读取谓词数据见 sway-lib-std/src/codec.sw 及BufferReader::from_script_data/from_predicate_data第 98–119 行。4.2 日志与回执Logs / Receipts调用std::log时其参数同样会被编码。因此log(1);会被脱糖为__log(encode(1));在 sway-lib-std/src/logging.sw 中logT的实现是__log::T(value)在开启新编码experimental_new_encoding true时约束T: AbiEncode——也就是说日志内容会以编码后的字节形式出现在回执receipt中链下解析方只要遵循同一套编解码规则即可读取。4.3 Configurables可配置常量Configurables 稍微复杂一些它们的初始化值在编译期就被求值。例如configurable { SOMETHING: u64 1, }上面这个例子会求值为1。编译器随后调用encode(1)并把结果追加到二进制文件的末尾。为了允许 SDK 在部署前替换该值编译器会在生成的ABI JSON中写入一条记录包含该缓冲区在二进制中的偏移{ name: SOMETHING, configurableType: { ... }, offset: 7104 },那么 configurables 是如何“解码”的呢这部分由编译器自动完成。例如configurable { SOMETHING: u64 1 } fn main() - u64 { SOMETHING }会被脱糖为类似下面的样子注意这不是合法的 Sway 语法仅用于表达编译器的行为const SOMETHING: u64; fn __entry() - raw_slice { std::codec::abi_decode_in_place(mut SOMETHING, 7104, 8); encode(main()) } fn main() - u64 { SOMETHING }其中abi_decode_in_placesway-lib-std/src/codec.sw会直接在原位置解码若类型平凡可解码则用一条mcp内存复制指令完成否则先解码到临时变量再复制到目标地址。这里传入的7104正是 ABI JSON 中记录的offset8是u64的字节长度。五、平凡可编码 / 可解码类型Trivially Encodable/Decodable Types编码和解码并非免费它们会增加二进制体积也会增加 Gas 消耗。除非——参数是平凡可编码的trivially encodable且返回类型是平凡可解码的trivially decodable。5.1 定义内存表示 编码表示一个类型是“平凡可编码/可解码”的当且仅当它的运行时内存表示与其编码表示完全一致有一个下文会讲到的例外。这与“零拷贝反序列化zero-copy deserialization”是同一个思想零拷贝反序列化是一种允许直接从序列化字节缓冲区访问数据的技术无需分配新内存或将数据复制到独立结构中。这是通过保证序列化格式的内存布局与目标数据结构的运行时内存表示一致来实现的从而可以直接通过类型转换或指针偏移访问字段而无需任何解析或转换工作。例 1对齐的元组。一个全由u64组成的元组运行时与编码后完全相同fn main ( _: (1u64, 2u64, 3u64) ) { ... }运行时表示------------------------------------- | 00 ... 01 | 00 ... 02 | 00 ... 03 | -------------------------------------编码表示------------------------------------- | 00 ... 01 | 00 ... 02 | 00 ... 03 | -------------------------------------例 2出现填充padding的元组。一旦混入u8运行时为了对齐会插入 padding编码表示则不含 padding二者不再一致fn main ( _: (1u8, 2u64, 3u64) ) { ... }运行时表示------------------------------------------ | 01 | 00 ... 00 | 00 ... 02 | 00 ... 03 | ------------------------------------------ ^^^^^^^^^ padding编码表示------------------------------ | 01 | 00 ... 02 | 00 ... 03 | ------------------------------由于第二个例子的内存表示与编码表示存在错配二进制体积的代价一目了然。讲稿给出了同一程序的两次编译对比平凡场景136 字节Finished release [optimized fuel] target(s) [136 B] in 0.90s非平凡场景208 字节Finished release [optimized fuel] target(s) [208 B] in 0.89s5.2 底层实现is_encode_trivial/is_decode_trivial平凡性的判定与快路径fast path由标准库统一实现pub trait AbiEncode { fn is_encode_trivial() - bool; fn abi_encode(self, buffer: Buffer) - Buffer; } pub trait AbiDecode { fn is_decode_trivial() - bool; fn abi_decode(ref mut buffer: BufferReader) - Self; } pub fn encodeT(item: T) - raw_slice where T: AbiEncode { if T::is_encode_trivial() { ... } else { ... } } pub fn abi_decodeT(data: raw_slice) - T where T: AbiDecode { if T::is_decode_trivial() { ... } else { ... } }实际的encode实现sway-lib-std/src/codec.sw在平凡路径上直接aloc分配、mcp复制一份原样的字节并包装成raw_slice连一次逐字段编解码循环都省掉了abi_decode第 1759–1775 行的平凡路径同样只需mcp拷贝即可。5.3 各基础类型的平凡性一览从 sway-lib-std/src/codec.sw 的AbiEncode实现可以确认以下结论判定依据is_encode_trivial()的返回值类型平凡编码说明u64、u8✅u64按 8 字节、u8按 1 字节无 padding 问题u32、u16❌编码时需消除对齐差异bool✅编码/ ❌解码见下节 Trap Representationsb256、u256✅定长且对齐str动态字符串❌需编码长度信息str[N]视情况experimental_str_array_no_padding false时不平凡第 292–303 行开启 true后平凡第 305–316 行raw_slice❌引用类型数组[T; N]继承T见第 331–349 行元组逐元素判断元组平凡性 __mem_repr_eq::Self(runtime, encoding)且每个元素平凡第 362 行起单元类型()✅空编码元组平凡性判定的关键是内建函数__mem_repr_eq——它在编译期比较某个类型的“运行时表示”与“编码表示”是否等价见 sway-core/src/semantic_analysis/ast_node/expression/intrinsic_function.rs 及其type_check_mem_repr_eq实现。这保证了“内存布局是否与编码布局一致”由编译器静态判定而非运行时猜测。5.4 Trap Representations布局相同也不一定安全解码Trap representation陷阱表示是一种“对该类型而言无效的位模式”。有些类型的内存布局与编码布局一致却仍然不能安全地平凡解码bool平凡可编码但不平凡可解码——任何非 0/1 的位模式都是非法bool直接读取会得到陷阱值枚举enums因为带有“隐藏的判别值discriminant”且该判别值只接受特定取值enum A { A: ..., B: ..., C: ... }-------------------------- | 0000000000000000 | ... | -------------------------- ^^^^^^^^^^^^^^^^ Discriminant (8 bytes)如果开发者愿意承担风险、自行处理非法表示可以强制某个类型按平凡解码处理。讲稿给出的通用包装类型是pub struct TriviallyDecodableT { value: T } implT AbiDecode for TriviallyDecodableT { fn is_decode_trivial() - bool { true } fn abi_decode(ref mut buffer: BufferReader) - Self { let value T::abi_decode(buffer); Self { value } } } fn main(_: TriviallyDecodablebool) { ... }值得一提的还有bool编码侧的标准库特例bool的平凡编码sway-lib-std/src/codec.sw直接复用__encode_buffer_append追加原始字节而 codec.sw 中还提供了TrivialBool { value: u64 }这样的标准库内置平凡类型。务必只在你能保证输入位模式合法的前提下使用强制平凡解码否则会引入未定义行为级别的安全风险。六、实践建议与总结6.1 如何在合约开发中利用平凡编码优先使用无 padding 的紧凑类型组合全u64/u8/b256组成的元组与结构体在编译期会被判定为平凡编解码走零拷贝快路径不增加二进制体积与 Gas避免混入u16/u32/str等触发逐字节编码的类型除非确有必要在 ABI 边界两侧保持相同版本的stdlib与编译器虽然编码体系已隔离了内部字段布局差异但平凡性判定、编码格式仍与编译器版本绑定慎用TriviallyDecodable/TrivialBool这类强制平凡解码它们只适合确信输入受控的场景例如自己链下生成的、经过校验的数据。6.2 全文脉络回顾合约调用时调用方把方法名与实参分别编码打包进堆上的参数区再以call指令连同coins / asset_id / gas交给被调用方被调用方从调用帧第 73 / 74 字偏移读取两段字节并解码执行编码的三大动机是ABI 不稳定、返回值降级Return Value Demotion与别名Aliasing安全同一套编码机制同时服务合约调用、脚本 / 谓词入参、日志回执、configurables四大场景平凡编码 / 解码内存布局 编码布局走alocmcp的零拷贝快路径能显著节省二进制体积与 Gas但bool、枚举等存在 trap representation 的类型即便布局相同也不能安全平凡解码。如果希望继续深入可以阅读讲稿原文 docs/slides/encoding.md 与续篇 docs/slides/trivial_encoding.md研读标准库实现 sway-lib-std/src/codec.swBuffer/BufferReader/AbiEncode/AbiDecode/contract_call/encode/abi_decode跟踪编译器侧的内建函数类型检查 sway-core/src/semantic_analysis/ast_node/expression/intrinsic_function.rs 中的ContractCall、ContractRet、MemReprEq参考 sway-lib-std/src/logging.sw 中log的编码约束以及 examples 目录下的counter、wallet_smart_contract、configurable_constants等示例工程观察真实合约的 ABI 行为。【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
