0
# Hardhat Ethers
1

2
The Hardhat Ethers plugin integrates [ethers.js](https://ethers.org/) into Hardhat, adding an `ethers` object to each network connection with enhanced functionality for smart contract development, testing, and deployment. It provides Hardhat-specific helpers for contract deployment, factory creation, signer management, and library linking while maintaining full compatibility with the standard ethers.js API.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import hardhatEthers from "@nomicfoundation/hardhat-ethers";
15
```
16

17
For TypeScript types:
18

19
```typescript
20
import type { HardhatEthers, FactoryOptions, Libraries } from "@nomicfoundation/hardhat-ethers/types";
21
```
22

23
For configuration in `hardhat.config.ts`:
24

25
```typescript
26
import hardhatEthers from "@nomicfoundation/hardhat-ethers";
27

28
export default {
29
  plugins: [hardhatEthers],
30
};
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { network } from "hardhat";
37

38
// Connect to network and access ethers
39
const { ethers } = await network.connect();
40

41
// Deploy a contract
42
const counter = await ethers.deployContract("Counter");
43
await counter.inc();
44
console.log(await counter.x());
45

46
// Get signers
47
const [signer] = await ethers.getSigners();
48

49
// Get contract factory
50
const Counter = await ethers.getContractFactory("Counter");
51
```
52

53
## Architecture
54

55
Hardhat Ethers is built around several key components:
56

57
- **Plugin System**: Integrates with Hardhat's hook system to provide network-specific ethers instances
58
- **Enhanced Provider**: `HardhatEthersProvider` extends ethers provider with Hardhat-specific functionality
59
- **Enhanced Signers**: `HardhatEthersSigner` provides direct address access and Hardhat integration
60
- **Helper Functions**: Convenient methods for contract deployment, factory creation, and signer management
61
- **Library Linking**: Automatic library linking for contracts with dependencies
62
- **Artifact Integration**: Seamless integration with Hardhat's artifact system for contract metadata
63

64
## Capabilities
65

66
### Contract Deployment
67

68
Deploy contracts directly from project artifacts with constructor arguments, library linking, and deployment options.
69

70
```typescript { .api }
71
function deployContract(
72
  name: string,
73
  signerOrOptions?: ethers.Signer | DeployContractOptions
74
): Promise<ethers.Contract>;
75

76
function deployContract(
77
  name: string,
78
  args: any[],
79
  signerOrOptions?: ethers.Signer | DeployContractOptions
80
): Promise<ethers.Contract>;
81

82
interface DeployContractOptions extends FactoryOptions, ethers.Overrides {}
83
```
84

85
[Contract Deployment](./contract-deployment.md)
86

87
### Contract Factories
88

89
Create ethers ContractFactory instances from project artifacts, ABI/bytecode, or contract names with library linking support.
90

91
```typescript { .api }
92
function getContractFactory<A extends any[], I = ethers.Contract>(
93
  name: string,
94
  signerOrOptions?: ethers.Signer | FactoryOptions
95
): Promise<ethers.ContractFactory<A, I>>;
96

97
function getContractFactory<A extends any[], I = ethers.Contract>(
98
  abi: any[] | Abi,
99
  bytecode: ethers.BytesLike,
100
  signer?: ethers.Signer
101
): Promise<ethers.ContractFactory<A, I>>;
102

103
function getContractFactoryFromArtifact<A extends any[], I = ethers.Contract>(
104
  artifact: Artifact<Abi>,
105
  signerOrOptions?: ethers.Signer | FactoryOptions
106
): Promise<ethers.ContractFactory<A, I>>;
107
```
108

109
[Contract Factories](./contract-factories.md)
110

111
### Contract Instances
112

113
Get contract instances at specific addresses using project artifacts or ABI, with automatic signer binding.
114

115
```typescript { .api }
116
function getContractAt(
117
  nameOrAbi: string | any[] | Abi,
118
  address: string | ethers.Addressable,
119
  signer?: ethers.Signer
120
): Promise<ethers.Contract>;
121

122
function getContractAtFromArtifact(
123
  artifact: Artifact,
124
  address: string,
125
  signer?: ethers.Signer
126
): Promise<ethers.Contract>;
127
```
128

129
[Contract Instances](./contract-instances.md)
130

131
### Signer Management
132

133
Access and manage signers for transactions, including account impersonation for testing.
134

135
```typescript { .api }
136
function getSigners(): Promise<HardhatEthersSigner[]>;
137

138
function getSigner(address: string): Promise<HardhatEthersSigner>;
139

140
function getImpersonatedSigner(address: string): Promise<HardhatEthersSigner>;
141

142
interface HardhatEthersSigner extends ethers.Signer {
143
  address: string;
144
}
145
```
146

147
[Signer Management](./signer-management.md)
148

149
### Provider Access
150

151
Access the enhanced Hardhat provider with network-specific capabilities and Hardhat RPC method support.
152

153
```typescript { .api }
154
interface HardhatEthersProvider extends ethers.Provider {
155
  getSigner(address?: number | string): Promise<HardhatEthersSigner>;
156
  send(method: string, params?: any[]): Promise<any>;
157
}
158
```
159

160
[Provider Access](./provider-access.md)
161

162
## Core Types
163

164
```typescript { .api }
165
interface FactoryOptions {
166
  signer?: ethers.Signer;
167
  libraries?: Libraries;
168
}
169

170
interface Libraries {
171
  [libraryName: string]: string | ethers.Addressable;
172
}
173

174
type DeployContractOptions = FactoryOptions & ethers.Overrides;
175

176
type HardhatEthers = typeof ethers & HardhatEthersHelpers;
177

178
interface HardhatEthersHelpers {
179
  provider: HardhatEthersProvider;
180
  getContractFactory: typeof getContractFactory;
181
  getContractFactoryFromArtifact: typeof getContractFactoryFromArtifact;
182
  getContractAt: typeof getContractAt;
183
  getContractAtFromArtifact: typeof getContractAtFromArtifact;
184
  deployContract: typeof deployContract;
185
  getSigner: typeof getSigner;
186
  getSigners: typeof getSigners;
187
  getImpersonatedSigner: typeof getImpersonatedSigner;
188
}
189
```