0
# ABI Parsing
1

2
Complete ABI parsing system that converts raw JSON ABI files into structured TypeScript representations with full type safety.
3

4
## Capabilities
5

6
### Main Parser Function
7

8
#### parse Function
9

10
Main ABI parser function that converts raw ABI to Contract object.
11

12
```typescript { .api }
13
/**
14
 * Main ABI parser function that converts raw ABI to Contract object
15
 * @param abi - Array of raw ABI definitions from JSON
16
 * @param path - Contract file path for name resolution
17
 * @param documentation - Optional documentation from devdoc/userdoc
18
 * @returns Parsed contract object with functions, events, and metadata
19
 */
20
function parse(abi: RawAbiDefinition[], path: string, documentation?: DocumentationResult): Contract;
21
```
22

23
**Usage Example:**
24

25
```typescript
26
import { parse, extractAbi } from "typechain";
27

28
const rawJson = `{
29
  "abi": [
30
    {
31
      "type": "function",
32
      "name": "transfer",
33
      "inputs": [
34
        {"name": "to", "type": "address"},
35
        {"name": "value", "type": "uint256"}
36
      ],
37
      "outputs": [{"name": "", "type": "bool"}],
38
      "stateMutability": "nonpayable"
39
    }
40
  ]
41
}`;
42

43
const abi = extractAbi(rawJson);
44
const contract = parse(abi, "./MyToken.sol/MyToken.json");
45
console.log(contract.functions.transfer[0].inputs[0].type); // AddressType
46
```
47

48
### Extraction Functions
49

50
#### extractAbi Function
51

52
Extracts ABI array from various JSON formats.
53

54
```typescript { .api }
55
/**
56
 * Extracts ABI array from various JSON formats (Truffle, Hardhat, raw ABI)
57
 * @param rawJson - Raw JSON string containing ABI data
58
 * @returns Array of raw ABI definitions
59
 * @throws MalformedAbiError if JSON is invalid or ABI not found
60
 */
61
function extractAbi(rawJson: string): RawAbiDefinition[];
62
```
63

64
#### extractBytecode Function
65

66
Extracts bytecode from various JSON formats.
67

68
```typescript { .api }
69
/**
70
 * Extracts bytecode from various JSON formats
71
 * @param rawContents - Raw JSON string containing bytecode
72
 * @returns Bytecode with optional link references, or undefined if not found
73
 */
74
function extractBytecode(rawContents: string): BytecodeWithLinkReferences | undefined;
75
```
76

77
#### extractDocumentation Function
78

79
Extracts documentation from compiler output.
80

81
```typescript { .api }
82
/**
83
 * Extracts documentation from compiler output (devdoc/userdoc)
84
 * @param rawContents - Raw JSON string containing documentation
85
 * @returns Combined documentation result, or undefined if not found
86
 */
87
function extractDocumentation(rawContents: string): DocumentationResult | undefined;
88
```
89

90
### Contract Structure
91

92
#### Contract Interface
93

94
Represents a complete smart contract with all its components.
95

96
```typescript { .api }
97
interface Contract {
98
  /** Contract name (normalized) */
99
  name: string;
100
  /** Original contract name from file */
101
  rawName: string;
102
  /** Contract path components for organization */
103
  path: string[];
104
  /** Optional fallback function */
105
  fallback?: FunctionWithoutInputDeclaration;
106
  /** Constructor functions (can be overloaded) */
107
  constructor: FunctionWithoutOutputDeclaration[];
108
  /** Contract functions grouped by name */
109
  functions: Dictionary<FunctionDeclaration[]>;
110
  /** Contract events grouped by name */
111
  events: Dictionary<EventDeclaration[]>;
112
  /** Contract structs grouped by name */
113
  structs: Dictionary<StructType[]>;
114
  /** Optional contract documentation */
115
  documentation?: object;
116
}
117

118
type Dictionary<T> = { [key: string]: T };
119
```
120

121
### Function Types
122

123
#### FunctionDeclaration Interface
124

125
Represents a smart contract function with full signature information.
126

127
```typescript { .api }
128
interface FunctionDeclaration {
129
  /** Function name */
130
  name: string;
131
  /** State mutability (pure, view, nonpayable, payable) */
132
  stateMutability: StateMutability;
133
  /** Input parameters */
134
  inputs: AbiParameter[];
135
  /** Output parameters */
136
  outputs: AbiOutputParameter[];
137
  /** Optional function documentation */
138
  documentation?: FunctionDocumentation;
139
}
140

141
type StateMutability = 'pure' | 'view' | 'nonpayable' | 'payable';
142
```
143

144
#### FunctionWithoutOutputDeclaration Interface
145

146
Function with no outputs (like constructors).
147

148
```typescript { .api }
149
interface FunctionWithoutOutputDeclaration {
150
  name: string;
151
  stateMutability: StateMutability;
152
  inputs: AbiParameter[];
153
  outputs: [];
154
  documentation?: FunctionDocumentation;
155
}
156
```
157

158
#### FunctionWithoutInputDeclaration Interface
159

160
Function with no inputs (like fallback functions).
161

162
```typescript { .api }
163
interface FunctionWithoutInputDeclaration {
164
  name: string;
165
  stateMutability: StateMutability;
166
  inputs: [];
167
  outputs: AbiOutputParameter[];
168
  documentation?: FunctionDocumentation;
169
}
170
```
171

172
### Parameter Types
173

174
#### AbiParameter Interface
175

176
Represents an ABI function parameter.
177

178
```typescript { .api }
179
interface AbiParameter {
180
  /** Parameter name */
181
  name: string;
182
  /** EVM type information */
183
  type: EvmType;
184
}
185
```
186

187
#### AbiOutputParameter Interface
188

189
Represents an ABI function output parameter.
190

191
```typescript { .api }
192
interface AbiOutputParameter {
193
  /** Parameter name (may be empty) */
194
  name: string;
195
  /** EVM output type information */
196
  type: EvmOutputType;
197
}
198
```
199

200
### Event Types
201

202
#### EventDeclaration Interface
203

204
Represents a smart contract event.
205

206
```typescript { .api }
207
interface EventDeclaration {
208
  /** Event name */
209
  name: string;
210
  /** Whether event is anonymous */
211
  isAnonymous: boolean;
212
  /** Event arguments */
213
  inputs: EventArgDeclaration[];
214
}
215
```
216

217
#### EventArgDeclaration Interface
218

219
Represents an event argument.
220

221
```typescript { .api }
222
interface EventArgDeclaration {
223
  /** Whether argument is indexed for filtering */
224
  isIndexed: boolean;
225
  /** Optional argument name */
226
  name?: string;
227
  /** EVM type */
228
  type: EvmType;
229
}
230
```
231

232
### Documentation Types
233

234
#### FunctionDocumentation Interface
235

236
Documentation metadata for functions from NatSpec comments.
237

238
```typescript { .api }
239
interface FunctionDocumentation {
240
  /** Function author */
241
  author?: string;
242
  /** Detailed description */
243
  details?: string;
244
  /** User notice */
245
  notice?: string;
246
  /** Parameter descriptions by name */
247
  params?: { [paramName: string]: string };
248
  /** Return value description */
249
  return?: string;
250
}
251
```
252

253
#### DocumentationResult Interface
254

255
Combined devdoc and userdoc documentation.
256

257
```typescript { .api }
258
interface DocumentationResult {
259
  /** Author information */
260
  author?: string;
261
  /** Detailed description */
262
  details?: string;
263
  /** User notice */
264
  notice?: string;
265
  /** Documentation title */
266
  title?: string;
267
  /** Method documentation by signature */
268
  methods?: { [methodName: string]: FunctionDocumentation };
269
}
270
```
271

272
### Raw ABI Types
273

274
#### RawAbiDefinition Interface
275

276
Raw ABI definition from JSON (before parsing).
277

278
```typescript { .api }
279
interface RawAbiDefinition {
280
  /** Function/event name */
281
  name: string;
282
  /** Legacy constant flag */
283
  constant: boolean;
284
  /** Legacy payable flag */
285
  payable: boolean;
286
  /** State mutability (preferred over constant/payable) */
287
  stateMutability?: StateMutability;
288
  /** Input parameters */
289
  inputs: RawAbiParameter[];
290
  /** Output parameters */
291
  outputs: RawAbiParameter[];
292
  /** ABI type (function, event, constructor, fallback, receive) */
293
  type: string;
294
}
295
```
296

297
#### RawAbiParameter Interface
298

299
Raw ABI parameter definition from JSON.
300

301
```typescript { .api }
302
interface RawAbiParameter {
303
  /** Parameter name */
304
  name: string;
305
  /** Solidity type string */
306
  type: string;
307
  /** Optional internal type for structs */
308
  internalType?: string;
309
  /** Optional tuple components for complex types */
310
  components?: RawAbiParameter[];
311
}
312
```
313

314
### Bytecode Types
315

316
#### BytecodeWithLinkReferences Interface
317

318
Bytecode with library link references.
319

320
```typescript { .api }
321
interface BytecodeWithLinkReferences {
322
  /** Contract bytecode as hex string */
323
  bytecode: string;
324
  /** Optional library link references */
325
  linkReferences?: BytecodeLinkReference[];
326
}
327

328
interface BytecodeLinkReference {
329
  /** Reference placeholder in bytecode */
330
  reference: string;
331
  /** Optional library name */
332
  name?: string;
333
}
334
```
335

336
### Utility Functions
337

338
#### parseContractPath Function
339

340
Parses contract file path into name components.
341

342
```typescript { .api }
343
/**
344
 * Parses contract file path into name components
345
 * @param path - Contract file path (e.g., "./contracts/MyToken.sol/MyToken.json")
346
 * @returns Object with normalized name, raw name, and path components
347
 */
348
function parseContractPath(path: string): { name: string; rawName: string; path: string[] };
349
```
350

351
#### parseEvent Function
352

353
Parses event ABI definition.
354

355
```typescript { .api }
356
/**
357
 * Parses event ABI definition
358
 * @param abiPiece - Raw event ABI definition
359
 * @param registerStruct - Callback to register discovered struct types
360
 * @returns Parsed event declaration
361
 */
362
function parseEvent(abiPiece: RawEventAbiDefinition, registerStruct: (struct: StructType) => void): EventDeclaration;
363

364
interface RawEventAbiDefinition extends RawAbiDefinition {
365
  type: 'event';
366
  anonymous?: boolean;
367
}
368
```
369

370
#### getFunctionDocumentation Function
371

372
Extracts documentation for a specific function.
373

374
```typescript { .api }
375
/**
376
 * Extracts documentation for a specific function from contract documentation
377
 * @param abiPiece - Raw ABI definition for the function
378
 * @param documentation - Contract documentation result
379
 * @returns Function documentation if found, undefined otherwise
380
 */
381
function getFunctionDocumentation(abiPiece: RawAbiDefinition, documentation?: DocumentationResult): FunctionDocumentation | undefined;
382
```
383

384
#### ensure0xPrefix Function
385

386
Ensures hex string has 0x prefix.
387

388
```typescript { .api }
389
/**
390
 * Ensures hex string has 0x prefix
391
 * @param hexString - Hex string that may or may not have 0x prefix
392
 * @returns Hex string with 0x prefix
393
 */
394
function ensure0xPrefix(hexString: string): string;
395
```
396

397
### Function Classification
398

399
#### isConstant Function
400

401
Checks if function is a constant (view/pure with no inputs and single output).
402

403
```typescript { .api }
404
/**
405
 * Checks if function is a simple constant (getter)
406
 * @param fn - Function declaration to check
407
 * @returns True if function is a constant getter
408
 */
409
function isConstant(fn: FunctionDeclaration): boolean;
410
```
411

412
#### isConstantFn Function
413

414
Checks if function is constant (view/pure) but not a simple constant.
415

416
```typescript { .api }
417
/**
418
 * Checks if function is constant (view/pure) but not a simple getter
419
 * @param fn - Function declaration to check
420
 * @returns True if function is constant but has inputs or multiple outputs
421
 */
422
function isConstantFn(fn: FunctionDeclaration): boolean;
423
```