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.