0
# TypeChain
1

2
TypeChain is a TypeScript bindings generator for Ethereum smart contracts. It transforms ABI files into type-safe TypeScript interfaces, classes, and types, providing compile-time type checking and IntelliSense support for smart contract interactions.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { runTypeChain, Config, PublicConfig, TypeChainTarget } from "typechain";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { runTypeChain } = require("typechain");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { runTypeChain } from "typechain";
27

28
// Generate TypeScript bindings from ABI files
29
const config = {
30
  cwd: process.cwd(),
31
  filesToProcess: ["./artifacts/**/*.json"],
32
  allFiles: ["./artifacts/**/*.json"],
33
  target: "ethers-v5",
34
  outDir: "./typechain-types"
35
};
36

37
const result = await runTypeChain(config);
38
console.log(`Generated ${result.filesGenerated} files`);
39
```
40

41
## Architecture
42

43
TypeChain is built around several key components:
44

45
- **Core Runner**: `runTypeChain` function orchestrates the entire generation process
46
- **ABI Parser**: Converts raw ABI JSON into structured Contract objects with full type information
47
- **Type System**: Rich EVM type system with discriminated unions for all Solidity types
48
- **Target System**: Pluggable architecture supporting multiple target generators (ethers-v4, ethers-v5, truffle, web3)
49
- **Code Generation**: Template-based code generation with barrel files and syntax utilities
50
- **File Processing**: Utilities for path resolution, globbing, and file system operations
51
- **CLI Interface**: Complete command-line interface with extensive configuration options
52

53
## Capabilities
54

55
### Core API
56

57
Main entry point for programmatic usage of TypeChain with configuration management and target resolution.
58

59
```typescript { .api }
60
function runTypeChain(config: PublicConfig): Promise<{ filesGenerated: number }>;
61

62
interface PublicConfig {
63
  cwd: string;
64
  target: string;
65
  outDir?: string;
66
  prettier?: object;
67
  filesToProcess: string[];
68
  allFiles: string[];
69
  inputDir?: string;
70
  flags?: CodegenConfig;
71
}
72
```
73

74
[Core API](./core-api.md)
75

76
### ABI Parsing
77

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

80
```typescript { .api }
81
function parse(abi: RawAbiDefinition[], path: string, documentation?: DocumentationResult): Contract;
82
function extractAbi(rawJson: string): RawAbiDefinition[];
83
function extractBytecode(rawContents: string): BytecodeWithLinkReferences | undefined;
84

85
interface Contract {
86
  name: string;
87
  rawName: string;
88
  path: string[];
89
  fallback?: FunctionWithoutInputDeclaration;
90
  constructor: FunctionWithoutOutputDeclaration[];
91
  functions: Dictionary<FunctionDeclaration[]>;
92
  events: Dictionary<EventDeclaration[]>;
93
  structs: Dictionary<StructType[]>;
94
  documentation?: object;
95
}
96
```
97

98
[ABI Parsing](./abi-parsing.md)
99

100
### Code Generation
101

102
Tools for generating TypeScript code including barrel files, imports, and syntax utilities.
103

104
```typescript { .api }
105
function createBarrelFiles(
106
  paths: string[], 
107
  options: { typeOnly: boolean; postfix?: string; moduleSuffix?: string }
108
): FileDescription[];
109

110
interface FileDescription {
111
  path: string;
112
  contents: string;
113
}
114
```
115

116
[Code Generation](./code-generation.md)
117

118
### CLI Interface
119

120
Command-line interface for running TypeChain with extensive configuration options and file pattern matching.
121

122
```typescript { .api }
123
interface ParsedArgs {
124
  files: string[];
125
  target: string;
126
  outDir?: string;
127
  inputDir?: string;
128
  flags: {
129
    discriminateTypes: boolean;
130
    alwaysGenerateOverloads: boolean;
131
    tsNocheck: boolean;
132
    node16Modules: boolean;
133
  };
134
}
135

136
function parseArgs(): ParsedArgs;
137
```
138

139
[CLI Interface](./cli-interface.md)
140

141
### Types and Interfaces
142

143
Rich type system for representing EVM types, function signatures, and contract structures with full TypeScript integration.
144

145
```typescript { .api }
146
type EvmType = BooleanType | IntegerType | UnsignedIntegerType | StringType | 
147
               BytesType | DynamicBytesType | AddressType | ArrayType | TupleType | UnknownType;
148

149
type EvmOutputType = EvmType | VoidType;
150

151
interface FunctionDeclaration {
152
  name: string;
153
  stateMutability: StateMutability;
154
  inputs: AbiParameter[];
155
  outputs: AbiOutputParameter[];
156
  documentation?: FunctionDocumentation;
157
}
158
```
159

160
[Types and Interfaces](./types-interfaces.md)
161

162
### File Utilities
163

164
Comprehensive file system utilities for path manipulation, globbing, and cross-platform compatibility.
165

166
```typescript { .api }
167
function glob(cwd: string, patternsOrFiles: string[], ignoreNodeModules?: boolean): string[];
168
function detectInputsRoot(allFiles: string[]): string;
169
function normalizeName(rawName: string): string;
170
```
171

172
[File Utilities](./file-utilities.md)
173

174
### Signature Utilities
175

176
Functions for generating contract function and event signatures for ABI compatibility and tooling.
177

178
```typescript { .api }
179
function getSignatureForFn(fn: FunctionDeclaration): string;
180
function getFullSignatureForEvent(event: EventDeclaration): string;
181
function getFullSignatureAsSymbolForEvent(event: EventDeclaration): string;
182
```