第2章 Web3 包中 Packages ABI 编码与解码指南

ABI web3.eth.abi 函数可用于将函数调用的参数编码和解码为 ABI（Application Binary Interface，应用二进制接口），目标为 EVM（Ethereum Virtual Machine，以太坊虚拟机）。 使用 Web3 ABI 函数前，先通过 `npm i web3` 或 `yarn add web3` 安装 Web3 包。 安装完成后，即可使用 Web3 ABI 函数： import { Web3 } from 'web3';

const web3 = new Web3();
const encoded = web3.eth.abi.encodeFunctionSignature({
name: 'myMethod',
type: 'function',
inputs: [{
type: 'uint256',
name: 'myNumber'
},{
type: 'string',
name: 'myString'
}]
});

若仅使用独立包，请通过 `npm i web3-eth-abi` 或 `yarn add web3-eth-abi` 安装 web3-eth-abi，并只导入所需函数。 这种按需导入的方式更适合构建轻量级应用： import { encodeFunctionSignature } from 'web3-eth-abi';

const encoded = encodeFunctionSignature({
name: 'myMethod',
type: 'function',
inputs: [{
type: 'uint256',
name: 'myNumber'
},{
type: 'string',
name: 'myString'
}]
});

Functions decodeFunctionCall ▸ decodeFunctionCall(functionsAbi, data, methodSignatureProvided?): DecodedParams & { __method__: string } 根据 JSON 接口对象解码函数调用数据。 JSON 接口规范文档：https://docs.soliditylang.org/en/latest/abi-spec.html#json Parameters NameTypeDefault valueDescriptionfunctionsAbiAbiConstructorFragment | AbiFunctionFragmentundefined函数的 JSON 接口对象。datastringundefined待解码的数据。methodSignatureProvidedbooleantrue（可选）若为 false，则不移除前 4 字节（该部分通常包含函数签名）。 Returns DecodedParams & { __method__: string } 根据传入的 ABI 解码后的数据。 Example const data =
'0xa413686200000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000548656c6c6f0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010416e6f74686572204772656574696e6700000000000000000000000000000000';
const params = decodeFunctionCall(
{
inputs: [
{ internalType: 'string', name: '_greeting', type: 'string' },
{ internalType: 'string', name: '_second_greeting', type: 'string' },
],
name: 'setGreeting',
outputs: [
{ internalType: 'bool', name: '', type: 'bool' },
{ internalType: 'string', name: '', type: 'string' },
],
stateMutability: 'nonpayable',
type: 'function',
},
data,
);

console.log(params);
> {
> '0': 'Hello',
> '1': 'Another Greeting',
> __length__: 2,
> __method__: 'setGreeting(string,string)',
> _greeting: 'Hello',
> _second_greeting: 'Another Greeting',
> }
decodeFunctionReturn​ ▸ decodeFunctionReturn(functionsAbi, returnValues?): unknown 根据 JSON 接口对象解码函数调用的返回数据。 JSON 接口规范文档 https://docs.soliditylang.org/en/latest/abi-spec.html#json 参数​ 名称类型描述functionsAbiAbiFunctionFragment函数的 JSON 接口对象。returnValues?string待解码的数据（函数返回值） 返回值​ unknown ABI 编码的函数调用数据，包含函数签名及传入的参数。 按传入 ABI 解码后的函数返回值。如果有多个值，会以如下示例中的对象形式返回；如果只有一个值，为简洁起见则直接返回该值本身。 Example // 解码方法的多个返回值
const data =
'0x00000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000548656c6c6f000000000000000000000000000000000000000000000000000000';
const decodedResult = decodeFunctionReturn(
{
inputs: [
{ internalType: 'string', name: '_greeting', type: 'string' }
],
name: 'setGreeting',
outputs: [
{ internalType: 'string', name: '', type: 'string' },
{ internalType: 'bool', name: '', type: 'bool' },
],
stateMutability: 'nonpayable',
type: 'function',
},
data,
);

console.log(decodedResult);
> { '0': 'Hello', '1': true, __length__: 2 }

// 解码方法的单个返回值
const data =
'0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000548656c6c6f000000000000000000000000000000000000000000000000000000';
const decodedResult = decodeFunctionReturn(
{
inputs: [
{ internalType: 'string', name: '_greeting', type: 'string' }
],
name: 'setGreeting',
outputs: [{ internalType: 'string', name: '', type: 'string' }],
stateMutability: 'nonpayable',
type: 'function',
},
data,
);

console.log(decodedResult);
> 'Hello'
decodeLog ▸ decodeLog(inputs, data, topics): ReturnType 解码 ABI 编码的日志数据和索引的主题数据。 类型参数 名称 类型 ReturnType 扩展 DecodedParams 参数 名称 类型 说明 inputs readonly AbiParameter[] | AbiParameter[] AbiParameter 输入数组。有关类型列表，请参阅 Solidity 文档。 data string 日志 data 字段中的 ABI 字节码。 topics string | string[] 包含日志索引参数主题数组的数组。对于非匿名事件，不包含 topic[0]；对于匿名事件，则包含 topic[0]。 返回值 ReturnType 包含解码后参数的结果对象。 示例 let res = web3.eth.abi.decodeLog(
[
{
type: "string",
name: "myString",
},
{
type: "uint256",
name: "myNumber",
indexed: true,
},
{
type: "uint8",
name: "mySmallNumber",
indexed: true,
},
],
"0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000748656c6c6f252100000000000000000000000000000000000000000000000000",
[
"0x000000000000000000000000000000000000000000000000000000000000f310",
"0x0000000000000000000000000000000000000000000000000000000000000010",
]
);
> {
'0': 'Hello%!',
'1': 62224n,
'2': 16n,
__length__: 3,
myString: 'Hello%!',
myNumber: 62224n,
mySmallNumber: 16n
}
decodeParameter ▸ decodeParameter(abi, bytes): unknown 将 ABI 编码的参数解码为其 JavaScript 类型。 参数 名称 类型 说明 abi AbiInput 参数的类型。有关类型列表，请参阅 Solidity 文档。 bytes string 待解码的 ABI 字节码。 返回值 unknown 解码后的参数。 示例 const res = web3.eth.abi.decodeParameter(
"uint256",
"0x0000000000000000000000000000000000000000000000000000000000000010"
);
console.log(res);
> 16n

const res = web3.eth.abi.decodeParameter(
"string",
"0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000848656c6c6f212521000000000000000000000000000000000000000000000000"
);

console.log(res);
> Hello!%!

const res = web3.eth.abi.decodeParameter(
{
ParentStruct: {
propertyOne: "uint256",
propertyTwo: "uint256",
childStruct: {
propertyOne: "uint256",
propertyTwo: "uint256",
},
},
},
"0x000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000000000000000000000000000000000000000038000000000000000000000000000000000000000000000000000000000000002d000000000000000000000000000000000000000000000000000000000000004e"
);

console.log(res);
{
'0': 42n,
'1': 56n,
'2': {
'0': 45n,
'1': 78n,
__length__: 2,
propertyOne: 45n,
propertyTwo: 78n
},
__length__: 3,
propertyOne: 42n,
propertyTwo: 56n,
childStruct: {
'0': 45n,
'1': 78n,
__length__: 2,
propertyOne: 45n,
propertyTwo: 78n
}
}
decodeParameters ▸ decodeParameters(abi, bytes): Object 将 ABI 编码的参数解码为 JavaScript 类型。 参数 名称 类型 描述 abi AbiInput[] | readonly AbiInput[] AbiInput 数组。类型列表参见 Solidity 文档。 bytes string 待解码的 ABI 字节码。 返回值 Object 包含解码后参数的结果对象。 名称 类型 __length__ number 示例 let res = web3.eth.abi.decodeParameters(
["string", "uint256"],
"0x000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000ea000000000000000000000000000000000000000000000000000000000000000848656c6c6f212521000000000000000000000000000000000000000000000000"
);
console.log(res);
> { '0': 'Hello!%!', '1': 234n, __length__: 2 }

let res = web3.eth.abi.decodeParameters(
[
{
type: "string",
name: "myString",
},
{
type: "uint256",
name: "myNumber",
},
],
"0x000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000ea000000000000000000000000000000000000000000000000000000000000000848656c6c6f212521000000000000000000000000000000000000000000000000"
); console.log(res);
> {
'0': 'Hello!%!',
'1': 234n,
__length__: 2,
myString: 'Hello!%!',
myNumber: 234n
}

const res = web3.eth.abi.decodeParameters(
[
"uint8[]",
{
ParentStruct: {
propertyOne: "uint256",
propertyTwo: "uint256",
childStruct: {
propertyOne: "uint256",
propertyTwo: "uint256",
},
},
},
],
"0x00000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000000000000000000000000000000000000000038000000000000000000000000000000000000000000000000000000000000002d000000000000000000000000000000000000000000000000000000000000004e0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000000000000000000000000000000000000000018"
);
console.log(res);
>
'0': [ 42n, 24n ],
'1': {
'0': 42n,
'1': 56n,
'2': {
'0': 45n,
'1': 78n,
__length__: 2,
propertyOne: 45n,
propertyTwo: 78n
},
__length__: 3,
propertyOne: 42n,
propertyTwo: 56n,
childStruct: {
'0': 45n,
'1': 78n,
__length__: 2,
propertyOne: 45n,
propertyTwo: 78n
}
},
__length__: 2,
ParentStruct: {
'0': 42n,
'1': 56n,
'2': {
'0': 45n,
'1': 78n,
__length__: 2,
propertyOne: 45n,
propertyTwo: 78n
},
__length__: 3,
propertyOne: 42n,
propertyTwo: 56n,
childStruct: {
'0': 45n,
'1': 78n,
__length__: 2,
propertyOne: 45n,
propertyTwo: 78n
}
}
}
decodeParametersWith ▸ decodeParametersWith(abis, bytes, loose): Object 用于解码参数列表 Parameters NameTypeabisAbiInput[] | readonly AbiInput[]bytesstringlooseboolean Returns Object NameType__length__number encodeErrorSignature ▸ encodeErrorSignature(functionName): string 将错误名称编码为 ABI 签名，即包含输入类型在内的错误名称的 SHA3 哈希值。 Parameters NameTypefunctionNamestring | AbiErrorFragment Returns string encodeEventSignature ▸ encodeEventSignature(functionName): string 将事件名称编码为 ABI 签名，即包含输入类型在内的事件名称的 SHA3 哈希值。 Parameters NameTypeDescriptionfunctionNamestring | AbiEventFragment要编码的事件名称，或该事件的 AbiEventFragment 对象。若为字符串，格式必须为 eventName(param1Type,param2Type,...)。示例：myEvent(uint256,bytes32)。 Returns string 该事件的 ABI 签名。 Example const event = web3.eth.abi.encodeEventSignature({ name: "myEvent", type: "event", inputs: [ { type: "uint256", name: "myNumber", }, { type: "bytes32", name: "myBytes", }, ], }); console.log(event); > 0xf2eeb729e636a8cb783be044acf6b7b1e2c5863735b60d6daae84c366ee87d97 const event = web3.eth.abi.encodeEventSignature({ inputs: [ { indexed: true, name: "from", type: "address", }, { indexed: true, name: "to", type: "address", }, { indexed: false, name: "value", type: "uint256", }, ], name: "Transfer", type: "event", }); console.log(event); > 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef encodeFunctionCall ▸ encodeFunctionCall(jsonInterface, params): string 使用 JSON 接口对象和给定参数对函数调用进行编码。 JSON 接口规范文档：https://docs.soliditylang.org/en/latest/abi-spec.html#json Parameters NameTypeDescriptionjsonInterfaceAbiFunctionFragment该函数的 JSON 接口对象。paramsunknown[]待编码的参数 Returns string 经过 ABI 编码的函数调用，包含函数签名及传入的参数。 Example const sig = web3.eth.abi.encodeFunctionCall( { name: "myMethod", type: "function", inputs: [ { type: "uint256",
name: "myNumber",
},
{
type: "string",
name: "myString",
},
],
},
["2345675643", "Hello!%"]
);
console.log(sig);
> 0x24ee0097000000000000000000000000000000000000000000000000000000008bd02b7b0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000748656c6c6f212500000000000000000000000000000000000000000000000000

const sig = web3.eth.abi.encodeFunctionCall(
{
inputs: [
{
name: "account",
type: "address",
},
],
name: "balanceOf",
outputs: [
{
name: "",
type: "uint256",
},
],
stateMutability: "view",
type: "function",
},
["0x1234567890123456789012345678901234567890"]
);

console.log(sig);
> 0x70a082310000000000000000000000001234567890123456789012345678901234567890
encodeFunctionSignature​ ▸ encodeFunctionSignature(functionName): string 将函数名编码为其 ABI 表示形式，即函数名（含参数类型）的 sha3 哈希值的前 4 字节。 JSON 接口规范文档 https://docs.soliditylang.org/en/latest/abi-spec.html#json 参数​ 名称 类型 描述 functionName string | AbiFunctionFragment 要编码的函数名或该函数的 JSON 接口对象。若传入参数为字符串，其格式必须为 functionName(param1Type,param2Type,...)。例如：myFunction(uint256,uint32[],bytes10,bytes) 返回值​ string 该函数的 ABI 签名。 示例 const signature = web3.eth.abi.encodeFunctionSignature({
name: "myMethod",
type: "function",
inputs: [
{
type: "uint256",
name: "myNumber",
},
{
type: "string",
name: "myString",
},
],
});
console.log(signature);
> 0x24ee0097

const signature = web3.eth.abi.encodeFunctionSignature('myMethod(uint256,string)')
console.log(signature);
> 0x24ee0097

const signature = web3.eth.abi.encodeFunctionSignature('safeTransferFrom(address,address,uint256,bytes)');
console.log(signature);
> 0xb88d4fde
encodeParameter​ ▸ encodeParameter(abi, param): string 根据参数类型将其编码为 ABI 表示形式。 参数​ 名称类型说明abiAbiInput参数的类型。类型列表请参阅 Solidity 文档。paramunknown要编码的实际参数。 返回值​ string ABI 编码后的参数 示例 const res = web3.eth.abi.encodeParameter("uint256", "2345675643");
console.log(res);
0x000000000000000000000000000000000000000000000000000000008bd02b7b

const res = web3.eth.abi.encodeParameter("uint", "2345675643");

console.log(res);
>0x000000000000000000000000000000000000000000000000000000008bd02b7b

const res = web3.eth.abi.encodeParameter("bytes32", "0xdf3234");

console.log(res);
>0xdf32340000000000000000000000000000000000000000000000000000000000

const res = web3.eth.abi.encodeParameter("bytes", "0xdf3234");

console.log(res);
> 0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000003df32340000000000000000000000000000000000000000000000000000000000

const res = web3.eth.abi.encodeParameter("bytes32[]", ["0xdf3234", "0xfdfd"]);

console.log(res);
> 0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000002df32340000000000000000000000000000000000000000000000000000000000fdfd000000000000000000000000000000000000000000000000000000000000

const res = web3.eth.abi.encodeParameter(
{
ParentStruct: {
propertyOne: "uint256",
propertyTwo: "uint256",
childStruct: {
propertyOne: "uint256",
propertyTwo: "uint256",
},
},
},
{
propertyOne: 42,
propertyTwo: 56,
childStruct: {
propertyOne: 45,
propertyTwo: 78,
},
}
);

console.log(res);
> 0x000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000000000000000000000000000000000000000038000000000000000000000000000000000000000000000000000000000000002d000000000000000000000000000000000000000000000000000000000000004e
encodeParameters​ ▸ encodeParameters(abi, params): string 根据参数的类型将其编码为 ABI 表示形式。 参数​ 名称类型说明abireadonly AbiInput[]AbiInput 数组，详情参见 Solidity 文档。paramsunknown[]待编码的实际参数。 返回值​ string ABI 编码后的参数 示例 const res = web3.eth.abi.encodeParameters(
["uint256", "string"],
["2345675643", "Hello!%"]
);

console.log(res);
> 0x000000000000000000000000000000000000000000000000000000008bd02b7b0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000748656c6c6f212500000000000000000000000000000000000000000000000000
getMessage​ ▸ getMessage(typedData, hash?): string 根据 typedData 对象获取待签名的 EIP-191 编码消息。如果启用了 hash，消息将使用 Keccak256 进行哈希。 参数​ 名称类型typedDataEip712TypedDatahash?boolean 返回值​ string inferTypesAndEncodeParameters​ ▸ inferTypesAndEncodeParameters(params): string 推断智能合约方法参数的类型，然后对该参数进行编码。 参数​ 名称类型说明paramsunknown[]待编码的参数。 返回值​ string ABI 编码后的参数 备注 当你不知道要编码参数的类型时，这个方法很有用。它会自动推断参数类型并进行编码。 但如果已经知道参数类型，则不建议使用该方法，此时应改用 encodeParameters 方法。 类型推断并不完美，可能产生意想不到的结果，尤其是在编码数组、非 uint256 的 uint 或 bytes 等类型时。 示例 const res = web3.eth.abi.encodeParameters(
["2345675643", "Hello!%"]
);

console.log(res);
> 0x000000000000000000000000000000000000000000000000000000008bd02b7b0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000748656c6c6f212500000000000000000000000000000000000000000000000000