0
# Buidler Ethers Plugin
1

2
The @nomiclabs/buidler-ethers plugin integrates ethers.js into the Buidler development environment, providing convenient access to blockchain interaction functionality through the Buidler Runtime Environment.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
// Plugin activation in buidler.config.js
15
usePlugin("@nomiclabs/buidler-ethers");
16
```
17

18
The plugin extends the Buidler Runtime Environment and does not export functions directly. Access is through the BRE:
19

20
```typescript
21
// In tasks, tests, or scripts
22
const { ethers } = require("@nomiclabs/buidler");
23
// or in TypeScript with proper types
24
import { BuidlerRuntimeEnvironment } from "@nomiclabs/buidler/types";
25
```
26

27
## Basic Usage
28

29
```javascript
30
usePlugin("@nomiclabs/buidler-ethers");
31

32
// Use in a task
33
task("example", "Example task", async (_, { ethers }) => {
34
  // Get current block number
35
  const blockNumber = await ethers.provider.getBlockNumber();
36
  console.log("Current block:", blockNumber);
37
  
38
  // Get signers
39
  const signers = await ethers.signers();
40
  console.log("First signer address:", await signers[0].getAddress());
41
  
42
  // Get a contract factory
43
  const Greeter = await ethers.getContract("Greeter");
44
  const greeter = await Greeter.deploy("Hello, world!");
45
});
46
```
47

48
## Architecture
49

50
The plugin uses a lazy initialization pattern to extend the Buidler Runtime Environment with three key components:
51

52
- **Provider Wrapper**: `EthersProviderWrapper` adapts Buidler's `IEthereumProvider` to ethers' `JsonRpcProvider` interface
53
- **Contract Factory Creation**: Automated loading of contract artifacts and factory creation with signer connection
54
- **Signer Management**: Conversion of provider accounts into ethers `Signer` instances
55

56
The integration is seamless and requires no additional setup beyond plugin activation.
57

58
## Capabilities
59

60
### Provider Access
61

62
Access to an ethers-compatible JSON-RPC provider that wraps Buidler's network provider.
63

64
```typescript { .api }
65
ethers.provider: EthersProviderWrapper
66
```
67

68
The provider is an instance of `EthersProviderWrapper` that extends `JsonRpcProvider` and provides all standard ethers provider functionality including:
69

70
- `send(method: string, params: any): Promise<any>` - Send JSON-RPC requests
71
- `getBlockNumber(): Promise<number>` - Get current block number
72
- `listAccounts(): Promise<string[]>` - Get available accounts
73
- `getSigner(account: string): Signer` - Get signer for specific account
74
- All other standard `JsonRpcProvider` methods
75

76
### Contract Factory Creation
77

78
Create ethers ContractFactory instances from compiled contract artifacts.
79

80
```typescript { .api }
81
ethers.getContract: (name: string) => Promise<ContractFactory>
82
```
83

84
**Parameters:**
85
- `name` (string): Name of the contract artifact (without .sol extension)
86

87
**Returns:**
88
- `Promise<ContractFactory>`: ContractFactory instance connected to the first available signer
89

90
**Usage Example:**
91

92
```typescript
93
// Assuming you have a Greeter.sol contract compiled in artifacts/
94
const Greeter = await ethers.getContract("Greeter");
95

96
// Deploy the contract
97
const greeter = await Greeter.deploy("Hello, Buidler!");
98
await greeter.deployed();
99

100
// Call contract methods
101
const greeting = await greeter.greet();
102
console.log(greeting);
103
```
104

105
### Signer Access
106

107
Get array of ethers Signer instances for all available accounts.
108

109
```typescript { .api }
110
ethers.signers: () => Promise<Signer[]>
111
```
112

113
**Returns:**
114
- `Promise<Signer[]>`: Array of ethers Signer instances for each account returned by the provider
115

116
**Usage Example:**
117

118
```typescript
119
const signers = await ethers.signers();
120

121
// Get the first signer's address
122
const address = await signers[0].getAddress();
123
console.log("Deployer address:", address);
124

125
// Get balance
126
const balance = await signers[0].getBalance();
127
console.log("Balance:", ethers.utils.formatEther(balance), "ETH");
128
```
129

130
## Types
131

132
### EthersProviderWrapper
133

134
```typescript { .api }
135
class EthersProviderWrapper extends JsonRpcProvider {
136
  constructor(buidlerProvider: IEthereumProvider);
137
  send(method: string, params: any): Promise<any>;
138
}
139
```
140

141
Internal wrapper class that adapts Buidler's provider to ethers' JsonRpcProvider interface. Emits debug events following ethers conventions.
142

143
### Buidler Runtime Environment Extension
144

145
```typescript { .api }
146
interface BuidlerRuntimeEnvironment {
147
  ethers: {
148
    provider: JsonRpcProvider;
149
    getContract: (name: string) => Promise<ContractFactory>;
150
    signers: () => Promise<Signer[]>;
151
  };
152
}
153
```
154

155
The plugin extends the Buidler Runtime Environment with the `ethers` property containing the three core functions.
156

157
## TypeScript Support
158

159
For TypeScript projects, include the type extensions in your `tsconfig.json`:
160

161
```json
162
{
163
  "files": [
164
    "node_modules/@nomiclabs/buidler-ethers/src/type-extensions.d.ts"
165
  ]
166
}
167
```
168

169
This provides full type safety for the extended BRE interface, including autocompletion and type checking for the `ethers` property.
170

171
## Error Handling
172

173
The plugin follows ethers.js conventions for error handling:
174

175
- Provider errors are propagated from the underlying Buidler provider
176
- Contract factory creation may throw if the specified artifact is not found
177
- Signers array reflects the accounts available from the current network provider
178

179
Debug information is emitted for all JSON-RPC requests through the provider's debug events.