WTF Solidity 极简入门:第 27 讲 ABI 编码与解码 —— 合约数据交互的底层基础
WTF Solidity 极简入门:第 27 讲 ABI 编码与解码 —— 合约数据交互的底层基础
导读
ABI(Application Binary Interface,应用二进制接口)是以太坊中外部应用与智能合约交互的标准,它规定数据必须按类型进行编码,且由于编码结果不包含类型信息,解码时必须显式声明参数类型。本讲基于 WTF-Solidity 仓库第 27 讲(对应西班牙语版文档 Languages/es/27_CodificacionDecodificacionABI_es/readme.md)展开,完整讲解 Solidity 内置的 4 个 ABI 编码函数(abi.encode、abi.encodePacked、abi.encodeWithSignature、abi.encodeWithSelector)与 1 个 ABI 解码函数(abi.decode)的原理、编码结果逐字节拆解与三大实战场景。读完本讲,你将能够理解合约调用时 calldata 的生成过程,并掌握在没有源码与接口的情况下通过 ABI 与任意合约交互的能力。
ABI 是什么
ABI 是 Ethereum 上外部应用(前端、脚本、其他合约)与智能合约之间通信的标准协议。它解决的核心问题是:数据以何种字节布局在交易中传输。由于 ABI 编码结果本身不携带类型信息,解码方必须提前知道每个字段的类型,才能正确还原数据。
在 Solidity 中,ABI 能力被封装为全局函数:
- ABI 编码(4 个):
abi.encode、abi.encodePacked、abi.encodeWithSignature、abi.encodeWithSelector - ABI 解码(1 个):
abi.decode,专门用于解码abi.encode生成的二进制数据
本讲完整示例代码位于 27_ABIEncode/ABIEncode.sol(西班牙语版镜像位于 Languages/es/27_CodificacionDecodificacionABI_es/ABIEncode.sol),合约声明了 4 个待编码变量,贯穿全讲:
uint x = 10;
address addr = 0x7A58c0Be72BE218B41C608b7Fe7C5bB630736C71;
string name = "0xAA";
uint[2] array = [5, 6];
四个变量的类型分别是 uint256(别名 uint)、address、string、uint256[2],涵盖了固定长度值类型与动态类型两种 ABI 编码形态,是理解编码规则的最佳样例。
ABI 编码的四种函数
abi.encode:与合约交互的标准编码
abi.encode 将给定参数按照 ABI 规范编码:每个参与编码的参数元素(包括偏移量、长度)都被填充为 32 字节(EVM 字长)并依次拼接。如果需要与合约交互,必须使用 abi.encode,因为它是 EVM 唯一认可的 calldata 布局。
function encode() public view returns(bytes memory result) {
result = abi.encode(x, addr, name, array);
}
编码结果为:
0x000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000007a58c0be72be218b41c608b7fe7c5bb630736c7100000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000043078414100000000000000000000000000000000000000000000000000000000
逐段拆解这段编码,可以直观理解 ABI 的布局规则:
000000000000000000000000000000000000000000000000000000000000000a // x = 10
0000000000000000000000007a58c0be72be218b41c608b7fe7c5bb630736c71 // addr
00000000000000000000000000000000000000000000000000000000000000a0 // name 参数的偏移量 (offset = 160)
0000000000000000000000000000000000000000000000000000000000000005 // array[0]
0000000000000000000000000000000000000000000000000000000000000006 // array[1]
0000000000000000000000000000000000000000000000000000000000000004 // name 参数的长度,4 字节
3078414100000000000000000000000000000000000000000000000000000000 // name 的 UTF-8 字节值 "0xAA"
这里体现了 ABI 规范中两个关键点:
- 动态类型需要偏移量:
string属于动态类型,其数据不直接嵌入头部,而是在头部写入该参数数据区起始位置的偏移量(0xa0= 160 字节),实际内容(长度 + 字节值)放在编码数据的尾部。name字符串"0xAA"被转换为 UTF-8 字节值0x30784141,长度 4 字节。 - 32 字节对齐填充:由于每个元素(含偏移量、长度)都按 EVM 字长 32 字节填充,编码结果中充斥着大量
0,这也是abi.encode体积较大的原因。
abi.encodePacked:最小空间的紧凑编码
abi.encodePacked 根据参数所需的最低空间进行编码,省略了 abi.encode 中的大量 0 填充。例如 uint8 类型只占用 1 字节。它适合不需要与合约交互、仅需节省空间的场景,最典型的是计算数据的 hash 值。
function encodePacked() public view returns(bytes memory result) {
result = abi.encodePacked(x, addr, name, array);
}
编码结果为:
0x000000000000000000000000000000000000000000000000000000000000000a7a58c0be72be218b41c608b7fe7c5bb630736c713078414100000000000000000000000000000000000000000000000000000000000000050000000000000000000000000000000000000000000000000000000000000006
相比 abi.encode,长度大幅缩短。从仓库源码可以印证这一函数在哈希计算中的高频使用:
- 25_Create2/Create2.sol 中通过
keccak256(abi.encodePacked(token0, token1))计算 create2 部署所需的salt; - 36_MerkleTree/MerkleTree.sol 中通过
keccak256(abi.encodePacked(account))计算 Merkle 树的叶子哈希; - 28_Hash/Hash.sol 中通过
keccak256(abi.encodePacked(_num, _string, _addr))对多类型参数统一取哈希。
安全警告:abi.encodePacked 不做填充,不同的输入拼接后可能产生相同的编码结果(如 "ab" + "c" 与 "a" + "bc"),从而引发哈希碰撞,带来潜在安全风险。若需消除歧义,应改用 abi.encode 或使用长度前缀等明确分隔手段。
abi.encodeWithSignature:带函数签名的编码
与 abi.encode 功能类似,只是第一个参数为函数签名(function signature),例如 "foo(uint256,address,string,uint256[2])"。它等价于在 abi.encode 的编码结果前拼接 4 字节的函数选择器,可直接用于调用其他合约。
function encodeWithSignature() public view returns(bytes memory result) {
result = abi.encodeWithSignature("foo(uint256,address,string,uint256[2])", x, addr, name, array);
}
编码结果为(注意开头多出的 4 字节 e87082f1 即函数选择器):
0xe87082f1000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000007a58c0be72be218b41c608b7fe7c5bb630736c7100000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000005000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000043078414100000000000000000000000000000000000000000000000000000000
函数签名必须严格遵循规范:签名由函数名 + 括号包裹的逗号分隔参数类型构成,参数类型之间不能有空格,例如 "foo(uint256,address,string,uint256[2])" 而非 "foo(uint256, address, string, uint256[2])",否则计算出的选择器不一致,调用会失败。
abi.encodeWithSelector:直接传入选择器的编码
与 abi.encodeWithSignature 功能一致,区别在于第一个参数直接传入函数选择器(function selector)——即函数签名 Keccak 哈希的前 4 个字节:
function encodeWithSelector() public view returns(bytes memory result) {
result = abi.encodeWithSelector(bytes4(keccak256("foo(uint256,address,string,uint256[2])")), x, addr, name, array);
}
由于 keccak256("foo(uint256,address,string,uint256[2])") 的前 4 字节恰好就是 0xe87082f1,因此编码结果与 abi.encodeWithSignature 完全一致。两者的本质区别在于:Signature 版本在内部完成"签名 → 选择器"的转换,Selector 版本则直接使用已经算好的选择器,因此在不知晓完整签名、只掌握选择器(例如反编译合约场景)时只能使用 abi.encodeWithSelector。
关于函数选择器的更多细节,可参考仓库 29_Selector/Selector.sol:它展示了 mint(address) 对应 0x6a627842、elementaryParamSelector(uint256,bool) 对应 0x3ec37834 等各类参数类型的 selector 计算方式,以及利用 abi.encodeWithSelector 直接发起调用的完整示例(29_Selector/Selector.sol)。
ABI 解码:abi.decode
abi.decode 用于将 abi.encode 生成的二进制编码还原为原始参数。解码时必须提供与编码时完全一致的参数类型列表,因为编码数据中不包含任何类型信息。
function decode(bytes memory data) public pure returns(uint dx, address daddr, string memory dname, uint[2] memory darray) {
(dx, daddr, dname, darray) = abi.decode(data, (uint, address, string, uint[2]));
}
将 abi.encode 的二进制输出作为 data 传入 decode,即可还原出 x = 10、addr = 0x7A58c0Be72BE218B41C608b7Fe7C5bB630736C71、name = "0xAA"、array = [5, 6] 四组原始值。注意解码只针对 abi.encode 的布局(32 字节对齐 + 偏移量规则),abi.encodePacked 的紧凑结果因缺少边界信息,无法被 abi.decode 正确还原。
在 Remix 上验证
部署 27_ABIEncode/ABIEncode.sol(或西班牙语版 Languages/es/27_CodificacionDecodificacionABI_es/ABIEncode.sol),可以在 Remix 中依次验证:
- 调用
encode方法查看abi.encode的编码结果(32 字节对齐、含大量0); - 对比
encode、encodePacked、encodeWithSignature、encodeWithSelector四种方法的异同——观察encodeWithSignature与encodeWithSelector输出一致、encodePacked结果最短、encode结果最规整; - 将
encode的输出粘贴到decode方法,验证解码还原出的原始参数。
ABI 的三大使用场景
场景一:配合 call 实现对合约的底层调用
ABI 在合约开发中最常见的组合是配合 call(低级成员函数)实现对目标合约的底层调用,适合在不知道对方源码或 ABI 时动态构造调用数据。仓库 22_Call/Call.sol 提供了完整范例:
bytes4 selector = contract.getValue.selector;
bytes memory data = abi.encodeWithSelector(selector, _x);
(bool success, bytes memory returnedData) = address(contract).staticcall(data);
require(success);
return abi.decode(returnedData, (uint256));
在该文件中可以看到两个方向的 ABI 运用(22_Call/Call.sol):
- 编码方向:
abi.encodeWithSignature("setX(uint256)", x)生成调用setX的 calldata,配合_addr.call{value: msg.value}(...)发送 ETH 并调用目标函数; - 解码方向:
abi.decode(data, (uint256))解析call返回的原始bytes,还原出目标合约getX()的返回值。
需要注意的是,call 调用不存在的函数时会触发目标合约的 fallback 函数且返回 success = true,因此使用底层调用时必须自行校验返回数据的合法性。
场景二:在 ethers.js 中导入合约与调用函数
在前端或脚本中,ABI(通常以 JSON 数组形式存在)是连接 JavaScript 与链上合约的桥梁。仓库 54_CrossChainBridge/crosschain.js 展示了 ethers.js 的标准用法:
const wavePortalContract = new ethers.Contract(contractAddress, contractABI, signer);
/*
* Llama al método getAllWaves de tu contrato inteligente
*/
const waves = await wavePortalContract.getAllWaves();
new ethers.Contract(address, abi, signer) 将合约地址与 ABI 绑定后,即可像调用本地对象方法一样调用链上函数——ABI 在此处负责把函数名与参数编码为 calldata、并把返回值解码为 JavaScript 数据类型,整个过程对开发者透明。
场景三:通过选择器调用反编译合约中的匿名函数
对未开源合约进行反编译后,部分函数只有编码结果、无法查到函数签名(例如图中的 0x533ba33a()),此时既无法构造 interface,也无法用常规方式声明合约变量调用,但可以直接通过 ABI 函数选择器发起调用:
bytes memory data = abi.encodeWithSelector(bytes4(0x533ba33a));
(bool success, bytes memory returnedData) = address(contract).staticcall(data);
require(success);
return abi.decode(returnedData, (uint256));
这正是 abi.encodeWithSelector 区别于 abi.encodeWithSignature 的实战价值所在:当只知道 4 字节选择器而不知道完整签名时,前者是唯一可行的编码途径。结合 staticcall(只读调用)与 abi.decode,可以完整地读取这类函数的返回值。
总结
在以太坊中,数据必须编码成字节码才能与智能合约交互,ABI 正是这套编码标准的载体。本讲介绍了 4 种 ABI 编码函数和 1 种 ABI 解码函数:
| 函数 | 作用 | 适用场景 |
|---|---|---|
abi.encode |
按 ABI 规范将参数填充为 32 字节并拼接 | 与合约交互的标准 calldata |
abi.encodePacked |
按最小空间紧凑编码,省略填充 | 节省空间、计算 hash |
abi.encodeWithSignature |
在 abi.encode 前拼接签名对应的选择器 |
调用其他合约(已知签名) |
abi.encodeWithSelector |
同左,但直接传入 4 字节选择器 | 调用其他合约(仅知选择器) |
abi.decode |
解码 abi.encode 生成的二进制数据 |
解析 call/staticcall 返回值 |
掌握 ABI 编码解码,不仅能帮助你读懂交易的 calldata,更是深入理解底层调用、跨合约交互与链上安全分析的基础。建议结合本讲源码 27_ABIEncode/ABIEncode.sol、22_Call/Call.sol 与 29_Selector/Selector.sol 在 Remix 中动手验证每一个编码结果。





