0
# web3-eth-abi
1

2
web3-eth-abi is a comprehensive TypeScript library for encoding and decoding Ethereum Virtual Machine (EVM) input and output data, specifically handling Application Binary Interface (ABI) operations. It provides functions for encoding function calls and constructor parameters, decoding function return values and event logs, handling contract error data decoding, and supporting EIP-712 typed data encoding.
3

4
## Package Information
5

6
- **Package Name**: web3-eth-abi
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install web3-eth-abi`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  encodeFunctionSignature,
16
  encodeFunctionCall,
17
  decodeFunctionCall,
18
  decodeFunctionReturn,
19
  encodeParameter,
20
  encodeParameters,
21
  decodeParameter,
22
  decodeParameters,
23
  encodeEventSignature,
24
  decodeLog,
25
  encodeErrorSignature,
26
  decodeContractErrorData,
27
  getEncodedEip712Data
28
} from "web3-eth-abi";
29
```
30

31
For CommonJS:
32

33
```javascript
34
const {
35
  encodeFunctionSignature,
36
  encodeFunctionCall,
37
  decodeFunctionCall,
38
  decodeFunctionReturn,
39
  encodeParameter,
40
  encodeParameters,
41
  decodeParameter,
42
  decodeParameters,
43
  encodeEventSignature,
44
  decodeLog,
45
  encodeErrorSignature,
46
  decodeContractErrorData,
47
  getEncodedEip712Data
48
} = require("web3-eth-abi");
49
```
50

51
## Basic Usage
52

53
```typescript
54
import {
55
  encodeFunctionCall,
56
  decodeFunctionReturn,
57
  encodeParameters,
58
  decodeLog
59
} from "web3-eth-abi";
60

61
// Encode a function call
62
const encodedCall = encodeFunctionCall(
63
  {
64
    name: "transfer",
65
    type: "function",
66
    inputs: [
67
      { type: "address", name: "to" },
68
      { type: "uint256", name: "amount" }
69
    ]
70
  },
71
  ["0x742d35Cc6638C2532C1CCF6344D4039be6498C2f", "1000000000000000000"]
72
);
73

74
// Decode function return value
75
const decodedReturn = decodeFunctionReturn(
76
  {
77
    name: "balanceOf",
78
    type: "function",
79
    inputs: [{ type: "address", name: "account" }],
80
    outputs: [{ type: "uint256", name: "" }]
81
  },
82
  "0x000000000000000000000000000000000000000000000000016345785d8a0000"
83
);
84

85
// Encode parameters
86
const encoded = encodeParameters(
87
  ["string", "uint256"],
88
  ["Hello World", "42"]
89
);
90

91
// Decode event logs
92
const decodedLog = decodeLog(
93
  [
94
    { type: "address", name: "from", indexed: true },
95
    { type: "address", name: "to", indexed: true },
96
    { type: "uint256", name: "value", indexed: false }
97
  ],
98
  "0x000000000000000000000000000000000000000000000000016345785d8a0000",
99
  [
100
    "0x000000000000000000000000a0b86a33e6288db8e74b93f60e5c5e7b56b7b8f5",
101
    "0x000000000000000000000000742d35cc6638c2532c1ccf6344d4039be6498c2f"
102
  ]
103
);
104
```
105

106
## Architecture
107

108
web3-eth-abi is built around several key components:
109

110
- **Function Encoding/Decoding**: Core functionality for encoding function calls and decoding return values
111
- **Parameter Processing**: Low-level encoding/decoding of individual parameters and parameter arrays
112
- **Event Processing**: Event signature encoding and log data decoding with indexed parameter handling
113
- **Error Handling**: Contract error signature encoding and error data decoding with EIP-838 support
114
- **EIP-712 Support**: Structured data encoding for typed message signing
115
- **Type Safety**: Full TypeScript integration with comprehensive type definitions and guards
116
- **ABI Utilities**: Helper functions for ABI fragment validation and type conversion
117

118
## Capabilities
119

120
### Function Operations
121

122
Core functionality for encoding function calls and decoding function return values. Essential for smart contract interactions and transaction building.
123

124
```typescript { .api }
125
function encodeFunctionSignature(functionName: string | AbiFunctionFragment): string;
126

127
function encodeFunctionCall(
128
  jsonInterface: AbiFunctionFragment,
129
  params: unknown[]
130
): string;
131

132
function decodeFunctionCall(
133
  functionsAbi: AbiFunctionFragment | AbiConstructorFragment,
134
  data: HexString,
135
  methodSignatureProvided?: boolean
136
): DecodedParams & { __method__: string };
137

138
function decodeFunctionReturn(
139
  functionsAbi: AbiFunctionFragment,
140
  returnValues?: HexString
141
): unknown;
142
```
143

144
[Function Operations](./function-operations.md)
145

146
### Parameter Processing
147

148
Low-level parameter encoding and decoding operations for individual values and parameter arrays. Supports all Solidity data types including complex structs.
149

150
```typescript { .api }
151
function encodeParameter(abi: AbiInput, param: unknown): string;
152

153
function encodeParameters(
154
  abi: AbiInput[] | ReadonlyArray<AbiInput>,
155
  params: unknown[]
156
): string;
157

158
function inferTypesAndEncodeParameters(params: unknown[]): string;
159

160
function decodeParameter(abi: AbiInput, bytes: HexString): unknown;
161

162
function decodeParameters(
163
  abi: AbiInput[] | ReadonlyArray<AbiInput>,
164
  bytes: HexString
165
): { [key: string]: unknown; __length__: number };
166

167
function decodeParametersWith(
168
  abis: AbiInput[] | ReadonlyArray<AbiInput>,
169
  bytes: HexString,
170
  loose: boolean
171
): { [key: string]: unknown; __length__: number };
172
```
173

174
[Parameter Processing](./parameter-processing.md)
175

176
### Event Processing
177

178
Event signature encoding and log data decoding with support for indexed parameters and anonymous events.
179

180
```typescript { .api }
181
function encodeEventSignature(functionName: string | AbiEventFragment): string;
182

183
function decodeLog<ReturnType extends DecodedParams>(
184
  inputs: Array<AbiParameter> | ReadonlyArray<AbiParameter>,
185
  data: HexString,
186
  topics: string | string[]
187
): ReturnType;
188
```
189

190
[Event Processing](./event-processing.md)
191

192
### Error Handling
193

194
Contract error signature encoding and comprehensive error data decoding with support for EIP-838 execution errors.
195

196
```typescript { .api }
197
function encodeErrorSignature(functionName: string | AbiErrorFragment): string;
198

199
function decodeContractErrorData(
200
  errorsAbi: AbiErrorFragment[],
201
  error: Eip838ExecutionError
202
): void;
203
```
204

205
[Error Handling](./error-handling.md)
206

207
### EIP-712 Structured Data
208

209
Complete support for EIP-712 structured data encoding and message preparation for typed data signing.
210

211
```typescript { .api }
212
function getEncodedEip712Data(
213
  typedData: Eip712TypedData,
214
  hash?: boolean
215
): string;
216
```
217

218
[EIP-712 Support](./eip-712.md)
219

220
### Utility Functions
221

222
Helper functions for working with ABI fragments, type validation, and data formatting.
223

224
```typescript { .api }
225
function isAbiFunctionFragment(item: unknown): item is AbiFunctionFragment;
226
function isAbiEventFragment(item: unknown): item is AbiEventFragment;
227
function isAbiErrorFragment(item: unknown): item is AbiErrorFragment;
228
function isAbiConstructorFragment(item: unknown): item is AbiConstructorFragment;
229
function isAbiFragment(item: unknown): item is AbiFragment;
230

231
function jsonInterfaceMethodToString(json: AbiFragment): string;
232
function flattenTypes(includeTuple: boolean, puts: ReadonlyArray<AbiParameter>): string[];
233
function formatParam(type: string, param: unknown): unknown;
234
function isOddHexstring(param: unknown): boolean;
235
function formatOddHexstrings(param: string): string;
236

237
function mapStructNameAndType(structName: string): AbiStruct;
238
function mapStructToCoderFormat(struct: AbiStruct): Array<AbiCoderStruct>;
239
function mapTypes(types: AbiInput[]): Array<string | AbiParameter | Record<string, unknown>>;
240
function isSimplifiedStructFormat(
241
  type: string | Partial<AbiParameter> | Partial<AbiInput>
242
): boolean;
243
```
244

245
## Core Types
246

247
```typescript { .api }
248
interface AbiFunctionFragment {
249
  type: "function";
250
  name?: string;
251
  inputs?: AbiInput[];
252
  outputs?: AbiOutput[];
253
  stateMutability?: "pure" | "view" | "nonpayable" | "payable";
254
}
255

256
interface AbiEventFragment {
257
  type: "event";
258
  name?: string;
259
  inputs?: AbiParameter[];
260
  anonymous?: boolean;
261
}
262

263
interface AbiErrorFragment {
264
  type: "error";
265
  name?: string;
266
  inputs?: AbiInput[];
267
}
268

269
interface AbiConstructorFragment {
270
  type: "constructor";
271
  inputs?: AbiInput[];
272
  stateMutability?: "nonpayable" | "payable";
273
}
274

275
interface AbiInput {
276
  name?: string;
277
  type: string;
278
  indexed?: boolean;
279
  components?: AbiInput[];
280
}
281

282
interface AbiOutput {
283
  name?: string;
284
  type: string;
285
  components?: AbiOutput[];
286
}
287

288
interface AbiParameter extends AbiInput {
289
  name: string;
290
}
291

292
interface DecodedParams {
293
  [key: string]: unknown;
294
  __length__: number;
295
}
296

297
type HexString = string;
298

299
interface AbiFragment {
300
  type: "function" | "event" | "constructor" | "error";
301
  name?: string;
302
  inputs?: AbiInput[];
303
}
304

305
interface AbiStruct {
306
  [key: string]: string | AbiStruct;
307
}
308

309
interface AbiCoderStruct {
310
  name: string;
311
  type: string;
312
  components?: AbiCoderStruct[];
313
}
314

315
interface Eip712TypedData {
316
  types: Record<string, Array<{ name: string; type: string }>>;
317
  primaryType: string;
318
  domain: Record<string, unknown>;
319
  message: Record<string, unknown>;
320
}
321

322
interface Eip838ExecutionError extends Error {
323
  data?: string;
324
  setDecodedProperties(
325
    errorName: string,
326
    errorSignature?: string,
327
    errorArgs?: { [K in string]: unknown }
328
  ): void;
329
}
330
```