0
# Error Handling
1

2
Contract error signature encoding and comprehensive error data decoding with support for EIP-838 execution errors. Essential for handling smart contract errors and providing meaningful error messages.
3

4
## Capabilities
5

6
### Encode Error Signature
7

8
Encodes the error name to its ABI signature, which is the sha3 hash of the error name including input types.
9

10
```typescript { .api }
11
/**
12
 * Encodes the error name to its ABI signature (sha3 hash)
13
 * @param functionName - The error name to encode or the AbiErrorFragment object
14
 * @returns The ABI signature of the error (32 bytes)
15
 */
16
function encodeErrorSignature(functionName: string | AbiErrorFragment): string;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { encodeErrorSignature } from "web3-eth-abi";
23

24
// Using error name string
25
const signature1 = encodeErrorSignature('InsufficientBalance(uint256,uint256)');
26
console.log(signature1);
27
// 0x...hash of error signature
28

29
// Using JSON interface object
30
const signature2 = encodeErrorSignature({
31
  name: "InsufficientBalance",
32
  type: "error",
33
  inputs: [
34
    { type: "uint256", name: "available" },
35
    { type: "uint256", name: "required" }
36
  ]
37
});
38
console.log(signature2);
39
// Same hash as above
40

41
// Simple error with no parameters
42
const signature3 = encodeErrorSignature({
43
  name: "Paused",
44
  type: "error",
45
  inputs: []
46
});
47
console.log(signature3);
48
// Hash of "Paused()"
49
```
50

51
### Decode Contract Error Data
52

53
Decodes contract error data using error ABI fragments. Supports custom errors defined in smart contracts as well as standard errors like "Error(string)" and "Panic(uint256)".
54

55
```typescript { .api }
56
/**
57
 * Decodes contract error data using error ABI fragments
58
 * @param errorsAbi - Array of error ABI fragments to match against
59
 * @param error - EIP-838 execution error with data field to decode
60
 * @returns Modifies the error object with decoded properties
61
 */
62
function decodeContractErrorData(
63
  errorsAbi: AbiErrorFragment[],
64
  error: Eip838ExecutionError
65
): void;
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import { decodeContractErrorData } from "web3-eth-abi";
72

73
// Define error ABI fragments
74
const errorAbi = [
75
  {
76
    name: "InsufficientBalance",
77
    type: "error",
78
    inputs: [
79
      { name: "available", type: "uint256" },
80
      { name: "required", type: "uint256" }
81
    ]
82
  },
83
  {
84
    name: "InvalidAddress",
85
    type: "error", 
86
    inputs: [
87
      { name: "addr", type: "address" }
88
    ]
89
  },
90
  {
91
    name: "Paused",
92
    type: "error",
93
    inputs: []
94
  }
95
];
96

97
// Mock error object (would come from web3 transaction)
98
const executionError = {
99
  message: "Transaction reverted",
100
  data: "0x12345678000000000000000000000000000000000000000000000000000000000000006400000000000000000000000000000000000000000000000000000000000000c8", // encoded error data
101
  setDecodedProperties: function(name, signature, args) {
102
    this.errorName = name;
103
    this.errorSignature = signature;
104
    this.errorArgs = args;
105
  }
106
};
107

108
// Decode the error data
109
decodeContractErrorData(errorAbi, executionError);
110

111
console.log(executionError.errorName); // "InsufficientBalance"
112
console.log(executionError.errorSignature); // "InsufficientBalance(uint256,uint256)"
113
console.log(executionError.errorArgs); 
114
// {
115
//   '0': 100n,
116
//   '1': 200n,
117
//   __length__: 2,
118
//   available: 100n,
119
//   required: 200n
120
// }
121
```
122

123
## Standard Error Handling
124

125
The `decodeContractErrorData` function automatically handles standard Ethereum errors even when no ABI is provided:
126

127
### Error(string) - 0x08c379a0
128

129
Standard revert with string message.
130

131
```typescript
132
// Error with signature 0x08c379a0... will be decoded as:
133
// {
134
//   errorName: "Error",
135
//   errorSignature: "Error(string)", 
136
//   errorArgs: { '0': "error message", __length__: 1, message: "error message" }
137
// }
138
```
139

140
### Panic(uint256) - 0x4e487b71
141

142
Panic errors with numeric codes.
143

144
```typescript
145
// Error with signature 0x4e487b71... will be decoded as:
146
// {
147
//   errorName: "Panic",
148
//   errorSignature: "Panic(uint256)",
149
//   errorArgs: { '0': 18n, __length__: 1, code: 18n } // 18 = arithmetic overflow
150
// }
151
```
152

153
## Common Panic Codes
154

155
- `0x01`: Assert false
156
- `0x11`: Arithmetic overflow/underflow
157
- `0x12`: Division by zero
158
- `0x21`: Invalid enum value
159
- `0x22`: Invalid storage byte array access
160
- `0x31`: Pop on empty array
161
- `0x32`: Array out of bounds access
162
- `0x41`: Out of memory
163
- `0x51`: Invalid function selector
164

165
## Error Processing Flow
166

167
1. Extract error signature (first 4 bytes) from error data
168
2. Match signature against provided error ABI fragments
169
3. If match found, decode parameters using the error's input specification
170
4. If no match, check for standard errors (Error/Panic)
171
5. Set decoded properties on the error object
172

173
## Types
174

175
```typescript { .api }
176
interface AbiErrorFragment {
177
  type: "error";
178
  name?: string;
179
  inputs?: AbiInput[];
180
}
181

182
interface AbiInput {
183
  name?: string;
184
  type: string;
185
  components?: AbiInput[];
186
}
187

188
interface Eip838ExecutionError extends Error {
189
  data?: string;
190
  setDecodedProperties(
191
    errorName: string,
192
    errorSignature?: string,
193
    errorArgs?: { [K in string]: unknown }
194
  ): void;
195
}
196
```