0
# TypeChain Ethers v5 Target
1

2
@typechain/ethers-v5 is a TypeChain target that generates TypeScript bindings compatible with Ethers.js v5. It transforms smart contract ABIs and bytecode into type-safe TypeScript interfaces, providing compile-time verification for Ethereum smart contract interactions.
3

4
## Package Information
5

6
- **Package Name**: @typechain/ethers-v5
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @typechain/ethers-v5`
10

11
## Core Imports
12

13
```typescript
14
import Ethers from "@typechain/ethers-v5";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const Ethers = require("@typechain/ethers-v5").default;
21
```
22

23
## Basic Usage
24

25
### As TypeChain Target (Recommended)
26

27
Configure this target in your TypeChain setup:
28

29
```bash
30
# CLI usage
31
typechain --target ethers-v5 --out-dir ./types/ethers-contracts/ './contracts/**/*.json'
32
```
33

34
With TypeChain configuration file:
35

36
```typescript
37
import { TypeChainConfig } from 'typechain';
38

39
const config: TypeChainConfig = {
40
  target: 'ethers-v5',
41
  outDir: './types/ethers-contracts/',
42
  inputDir: './contracts/',
43
  allFiles: ['./contracts/**/*.json'],
44
  flags: {
45
    alwaysGenerateOverloads: false,
46
    discriminateTypes: false,
47
    environment: 'hardhat'
48
  }
49
};
50
```
51

52
### Using Generated Types
53

54
Once TypeChain generates the bindings, use them with ethers.js:
55

56
```typescript
57
import { ethers } from 'ethers';
58
import { MyContract, MyContract__factory } from './types/ethers-contracts';
59

60
// Connect to a deployed contract
61
const provider = new ethers.providers.JsonRpcProvider();
62
const signer = provider.getSigner();
63
const contract: MyContract = MyContract__factory.connect(contractAddress, signer);
64

65
// Call contract methods with full type safety
66
const result = await contract.myMethod(param1, param2);
67
```
68

69
## Architecture
70

71
@typechain/ethers-v5 is built around several key components:
72

73
- **Main Target Class**: `Ethers` class extending `TypeChainTarget`, orchestrates the generation process
74
- **Code Generation Modules**: Specialized modules for generating functions, events, types, and struct definitions
75
- **Factory Generation**: Creates both concrete and abstract factory classes for contract deployment and connection
76
- **Type System**: Comprehensive TypeScript type generation for all contract interfaces, events, and data structures
77
- **Static Utilities**: Common type definitions and utility types copied to generated output
78

79
## Capabilities
80

81
### Ethers Target Class
82

83
The main TypeChain target class that orchestrates the generation of TypeScript bindings for Ethers.js v5 contracts. This is the only public export of the package.
84

85
```typescript { .api }
86
export default class Ethers extends TypeChainTarget {
87
  readonly name: string; // Always "Ethers"
88
  
89
  /**
90
   * Creates new Ethers target instance with TypeChain configuration
91
   * @param config - TypeChain configuration including output directory and file list
92
   */
93
  constructor(config: Config);
94
  
95
  /**
96
   * Transforms a single contract file (ABI/bytecode) into TypeScript bindings
97
   * @param file - File description containing path and contents
98
   * @returns Array of generated files or void if file cannot be processed
99
   */
100
  transformFile(file: FileDescription): FileDescription[] | void;
101
  
102
  /**
103
   * Called after all files are processed to generate supporting files
104
   * @returns Array of additional files (common.ts, index.ts, hardhat.d.ts)
105
   */
106
  afterRun(): FileDescription[];
107
}
108
```
109

110
[Target Class](./target-class.md)
111

112
### Generated Output Types
113

114
The target generates several types of files for type-safe contract interaction:
115

116
#### Contract Interfaces
117
```typescript { .api }
118
// Example generated contract interface
119
export interface MyContract extends BaseContract {
120
  connect(signerOrProvider: Signer | Provider | string): this;
121
  attach(addressOrName: string): this;
122
  deployed(): Promise<this>;
123
  
124
  // Type-safe contract methods
125
  myMethod(param1: string, param2: BigNumberish): Promise<string>;
126
  
127
  // Event filters and types
128
  filters: {
129
    MyEvent(param?: string): TypedEventFilter<MyEvent>;
130
  };
131
}
132
```
133

134
#### Factory Classes
135
```typescript { .api }
136
// Example generated factory class
137
export class MyContract__factory extends ContractFactory {
138
  constructor(signer?: Signer);
139
  deploy(constructorArg: string): Promise<MyContract>;
140
  attach(address: string): MyContract;
141
  connect(signer: Signer): MyContract__factory;
142
  static connect(address: string, signerOrProvider: Signer | Provider): MyContract;
143
}
144
```
145

146
#### Common Types
147
```typescript { .api }
148
// Common utility types included in generated output
149
export interface TypedEvent<TArgsArray extends Array<any> = any, TArgsObject = any> 
150
  extends Event {
151
  args: TArgsArray & TArgsObject;
152
}
153

154
export interface TypedEventFilter<_TEvent extends TypedEvent> extends EventFilter {}
155

156
export type PromiseOrValue<T> = T | Promise<T>;
157
```
158

159
### Usage Guide
160

161
Comprehensive guide for using the generated TypeScript contract bindings with ethers.js v5, including deployment, method calls, event handling, and type safety best practices.
162

163
[Using Generated Types](./using-generated-types.md)
164

165
## Types
166

167
```typescript { .api }
168
// Configuration interface for TypeChain target
169
interface Config {
170
  cwd: string;
171
  outDir?: string;
172
  inputDir: string;
173
  allFiles: string[];
174
  target: string;
175
  flags: CodegenConfig;
176
}
177

178
// Code generation configuration flags
179
interface CodegenConfig {
180
  alwaysGenerateOverloads?: boolean;
181
  discriminateTypes?: boolean;
182
  environment?: 'hardhat' | 'truffle' | string;
183
}
184

185
// File description for processing
186
interface FileDescription {
187
  path: string;
188
  contents: string;
189
}
190
```