0
# Hardhat Ethers Plugin
1

2
The @nomiclabs/hardhat-ethers plugin integrates ethers.js into the Hardhat development environment, providing developers with a comprehensive set of utilities for interacting with Ethereum smart contracts. It extends the Hardhat Runtime Environment with an ethers object that includes the full ethers.js API plus additional Hardhat-specific functionality.
3

4
## Package Information
5

6
- **Package Name**: @nomiclabs/hardhat-ethers
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @nomiclabs/hardhat-ethers 'ethers@^5.0.0'`
10

11
## Core Imports
12

13
Add the plugin to your `hardhat.config.ts`:
14

15
```typescript
16
import "@nomiclabs/hardhat-ethers";
17
```
18

19
Or in `hardhat.config.js`:
20

21
```javascript
22
require("@nomiclabs/hardhat-ethers");
23
```
24

25
Access ethers through the Hardhat Runtime Environment:
26

27
```typescript
28
import { ethers } from "hardhat";
29
// or access via HRE parameter in tasks, tests, scripts
30
```
31

32
## Basic Usage
33

34
```typescript
35
import { ethers } from "hardhat";
36

37
// Deploy a contract
38
const contractFactory = await ethers.getContractFactory("MyContract");
39
const contract = await contractFactory.deploy(arg1, arg2);
40
await contract.deployed();
41

42
// Get signers
43
const [deployer, user] = await ethers.getSigners();
44

45
// Interact with existing contract
46
const existingContract = await ethers.getContractAt("MyContract", contractAddress);
47
const result = await existingContract.someMethod();
48
```
49

50
## Architecture
51

52
The hardhat-ethers plugin is built around several key components:
53

54
- **Environment Extension**: Extends Hardhat Runtime Environment with ethers object containing full ethers.js API plus Hardhat helpers
55
- **Helper Functions**: Streamlined functions for contract deployment, factory creation, and contract interaction
56
- **Signer Management**: Enhanced signer functionality with SignerWithAddress class that includes address property
57
- **Provider Integration**: Automatic provider setup connected to the selected Hardhat network
58
- **Library Linking**: Support for Solidity library linking in complex contract deployments
59

60
## Capabilities
61

62
### Contract Factories
63

64
Functions for creating contract factories from artifacts, names, or ABI/bytecode combinations. Supports library linking for complex contracts.
65

66
```typescript { .api }
67
function getContractFactory(
68
  name: string,
69
  signerOrOptions?: ethers.Signer | FactoryOptions
70
): Promise<ethers.ContractFactory>;
71

72
function getContractFactory(
73
  abi: any[],
74
  bytecode: ethers.utils.BytesLike,
75
  signer?: ethers.Signer
76
): Promise<ethers.ContractFactory>;
77

78
function getContractFactoryFromArtifact(
79
  artifact: Artifact,
80
  signerOrOptions?: ethers.Signer | FactoryOptions
81
): Promise<ethers.ContractFactory>;
82

83
interface FactoryOptions {
84
  signer?: ethers.Signer;
85
  libraries?: Libraries;
86
}
87

88
interface Libraries {
89
  [libraryName: string]: string;
90
}
91
```
92

93
[Contract Factories](./contract-factories.md)
94

95
### Contract Interaction
96

97
Functions for interacting with deployed contracts at specific addresses using contract names, artifacts, or ABI definitions.
98

99
```typescript { .api }
100
function getContractAt(
101
  nameOrAbi: string | any[],
102
  address: string,
103
  signer?: ethers.Signer
104
): Promise<ethers.Contract>;
105

106
function getContractAtFromArtifact(
107
  artifact: Artifact,
108
  address: string,
109
  signer?: ethers.Signer
110
): Promise<ethers.Contract>;
111
```
112

113
[Contract Interaction](./contract-interaction.md)
114

115
### Contract Deployment
116

117
Simplified contract deployment functionality that combines factory creation and deployment in a single function call.
118

119
```typescript { .api }
120
function deployContract(
121
  name: string,
122
  args?: any[],
123
  signerOrOptions?: ethers.Signer | FactoryOptions
124
): Promise<ethers.Contract>;
125

126
function deployContract(
127
  name: string,
128
  signerOrOptions?: ethers.Signer | FactoryOptions
129
): Promise<ethers.Contract>;
130
```
131

132
[Contract Deployment](./contract-deployment.md)
133

134
### Signer Management
135

136
Enhanced signer functionality with SignerWithAddress class and helper functions for managing test accounts and impersonation.
137

138
```typescript { .api }
139
function getSigners(): Promise<SignerWithAddress[]>;
140

141
function getSigner(address: string): Promise<SignerWithAddress>;
142

143
function getImpersonatedSigner(address: string): Promise<SignerWithAddress>;
144

145
class SignerWithAddress extends ethers.Signer {
146
  readonly address: string;
147
  static create(signer: ethers.providers.JsonRpcSigner): Promise<SignerWithAddress>;
148
  getAddress(): Promise<string>;
149
  signMessage(message: string | ethers.utils.Bytes): Promise<string>;
150
  signTransaction(transaction: ethers.utils.Deferrable<ethers.providers.TransactionRequest>): Promise<string>;
151
  sendTransaction(transaction: ethers.utils.Deferrable<ethers.providers.TransactionRequest>): Promise<ethers.providers.TransactionResponse>;
152
  connect(provider: ethers.providers.Provider): SignerWithAddress;
153
  _signTypedData(...params: Parameters<ethers.providers.JsonRpcSigner["_signTypedData"]>): Promise<string>;
154
  toJSON(): string;
155
}
156
```
157

158
[Signer Management](./signer-management.md)
159

160
### Provider Access
161

162
Direct access to the ethers provider automatically configured for the selected Hardhat network.
163

164
```typescript { .api }
165
const provider: ethers.providers.JsonRpcProvider;
166
```
167

168
The provider is available at `ethers.provider` and is automatically connected to the network specified in your Hardhat configuration.
169

170
## Types
171

172
```typescript { .api }
173
import { Artifact } from "hardhat/types";
174

175
interface Libraries {
176
  [libraryName: string]: string;
177
}
178

179
interface FactoryOptions {
180
  signer?: ethers.Signer;
181
  libraries?: Libraries;
182
}
183

184
interface HardhatEthersHelpers {
185
  provider: ethers.providers.JsonRpcProvider;
186
  getContractFactory: typeof getContractFactory;
187
  getContractFactoryFromArtifact: (
188
    artifact: Artifact,
189
    signerOrOptions?: ethers.Signer | FactoryOptions
190
  ) => Promise<ethers.ContractFactory>;
191
  getContractAt: (
192
    nameOrAbi: string | any[],
193
    address: string,
194
    signer?: ethers.Signer
195
  ) => Promise<ethers.Contract>;
196
  getContractAtFromArtifact: (
197
    artifact: Artifact,
198
    address: string,
199
    signer?: ethers.Signer
200
  ) => Promise<ethers.Contract>;
201
  getSigner: (address: string) => Promise<SignerWithAddress>;
202
  getSigners: () => Promise<SignerWithAddress[]>;
203
  getImpersonatedSigner: (address: string) => Promise<SignerWithAddress>;
204
  deployContract: typeof deployContract;
205
}
206
```
207

208
## Ethers.js Integration
209

210
The plugin provides the complete ethers.js v5 API through the `ethers` object, including:
211

212
- **Contracts**: `ethers.Contract`, `ethers.ContractFactory`
213
- **Providers**: `ethers.providers.*`
214
- **Signers**: `ethers.Signer`, `ethers.Wallet`
215
- **Utilities**: `ethers.utils.*`
216
- **Constants**: `ethers.constants.*`
217
- **BigNumber**: `ethers.BigNumber`
218

219
All ethers.js functionality is available alongside the Hardhat-specific helpers.