0
# BuidlerEVM Provider
1

2
BuidlerEVM is Buidler's local Ethereum network designed for development. It provides instant transaction mining, comprehensive debugging features, stack trace generation, and console.sol logging support. The provider implements the standard EIP-1193 Ethereum provider interface.
3

4
## Capabilities
5

6
### Ethereum Provider Interface
7

8
Standard EIP-1193 compatible provider for interacting with the BuidlerEVM network.
9

10
```typescript { .api }
11
/**
12
 * EIP-1193 compatible Ethereum provider
13
 */
14
interface EthereumProvider extends EventEmitter {
15
  /**
16
   * Send JSON-RPC request to the provider
17
   * @param method - RPC method name
18
   * @param params - Method parameters array
19
   * @returns Promise resolving to RPC result
20
   */
21
  send(method: string, params?: any[]): Promise<any>;
22
}
23

24
/**
25
 * Legacy provider interface alias (deprecated)
26
 */
27
type IEthereumProvider = EthereumProvider;
28
```
29

30
**Usage Examples:**
31

32
```typescript
33
// Access provider through runtime environment
34
task("balance", "Get account balance", async (taskArgs, hre) => {
35
  const provider = hre.network.provider;
36
  
37
  // Get accounts
38
  const accounts = await provider.send("eth_accounts");
39
  
40
  // Get balance
41
  const balance = await provider.send("eth_getBalance", [
42
    accounts[0],
43
    "latest"
44
  ]);
45
  
46
  console.log(`Balance: ${balance}`);
47
});
48

49
// Direct provider usage
50
const balance = await hre.ethereum.send("eth_getBalance", [
51
  "0x742d35cc6cb34f4c9e5fb5e5a0c2eb9df0b2ae7a",
52
  "latest"
53
]);
54
```
55

56
### Network Configuration
57

58
Access network configuration and provider through the runtime environment.
59

60
```typescript { .api }
61
/**
62
 * Network information and provider access
63
 */
64
interface Network {
65
  /** Network name from configuration */
66
  name: string;
67
  /** Network configuration object */
68
  config: NetworkConfig;
69
  /** Ethereum provider instance */
70
  provider: EthereumProvider;
71
}
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
task("network-info", "Show network information", async (taskArgs, hre) => {
78
  const { network } = hre;
79
  
80
  console.log(`Network: ${network.name}`);
81
  console.log(`Config:`, network.config);
82
  
83
  // Check if it's BuidlerEVM
84
  if (network.name === "buidlerevm") {
85
    console.log("Using local BuidlerEVM network");
86
    
87
    // BuidlerEVM specific operations
88
    const blockNumber = await network.provider.send("eth_blockNumber");
89
    console.log(`Current block: ${parseInt(blockNumber, 16)}`);
90
  }
91
});
92
```
93

94
### BuidlerEVM Features
95

96
BuidlerEVM provides development-focused features not available on other networks.
97

98
```typescript { .api }
99
// BuidlerEVM specific RPC methods (examples)
100

101
/**
102
 * Mine a new block instantly
103
 */
104
await provider.send("evm_mine");
105

106
/**
107
 * Set the next block timestamp
108
 */
109
await provider.send("evm_setNextBlockTimestamp", [timestamp]);
110

111
/**
112
 * Increase time by specified seconds
113
 */
114
await provider.send("evm_increaseTime", [seconds]);
115

116
/**
117
 * Take a snapshot of current blockchain state
118
 */
119
const snapshotId = await provider.send("evm_snapshot");
120

121
/**
122
 * Revert to a previous snapshot
123
 */
124
await provider.send("evm_revert", [snapshotId]);
125

126
/**
127
 * Set account balance
128
 */
129
await provider.send("buidler_setBalance", [address, balance]);
130

131
/**
132
 * Impersonate an account
133
 */
134
await provider.send("buidler_impersonateAccount", [address]);
135

136
/**
137
 * Stop impersonating an account
138
 */
139
await provider.send("buidler_stopImpersonatingAccount", [address]);
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
task("test-setup", "Setup test environment", async (taskArgs, hre) => {
146
  const provider = hre.network.provider;
147
  
148
  // Take initial snapshot
149
  const snapshotId = await provider.send("evm_snapshot");
150
  console.log(`Snapshot taken: ${snapshotId}`);
151
  
152
  // Set up test accounts with specific balances
153
  const testAccounts = [
154
    "0x742d35cc6cb34f4c9e5fb5e5a0c2eb9df0b2ae7a",
155
    "0x8ba1f109551bd432803012645hac136c98cdcf6b"
156
  ];
157
  
158
  for (const account of testAccounts) {
159
    await provider.send("buidler_setBalance", [
160
      account,
161
      "0x21e19e0c9bab2400000" // 10k ETH
162
    ]);
163
  }
164
  
165
  // Fast forward time for testing
166
  await provider.send("evm_increaseTime", [86400]); // 1 day
167
  await provider.send("evm_mine");
168
  
169
  console.log("Test environment ready");
170
});
171
```
172

173
### Provider Access
174

175
Access providers through the Buidler runtime environment. Providers are automatically created and configured based on network settings.
176

177
### Console.sol Integration
178

179
BuidlerEVM automatically captures and displays console.sol output from smart contracts.
180

181
```solidity
182
// In your Solidity contract
183
import "buidler/console.sol";
184

185
contract MyContract {
186
    function test() public {
187
        console.log("Debug message from contract");
188
        console.log("Value:", 42);
189
        console.log("Address:", msg.sender);
190
    }
191
}
192
```
193

194
The console output appears in the Buidler console when transactions are executed:
195

196
```
197
Debug message from contract
198
Value: 42
199
Address: 0x742d35cc6cb34f4c9e5fb5e5a0c2eb9df0b2ae7a
200
```
201

202
### Stack Traces and Error Reporting
203

204
BuidlerEVM provides detailed stack traces for failed transactions, showing:
205

206
- **Solidity stack traces**: Function call hierarchy with line numbers
207
- **Revert reasons**: Custom error messages and require() failures  
208
- **Gas usage**: Detailed gas consumption analysis
209
- **State changes**: What state was modified before failure
210

211
**Example Error Output:**
212

213
```typescript
214
task("debug-transaction", async (taskArgs, hre) => {
215
  try {
216
    await hre.ethereum.send("eth_sendTransaction", [{
217
      from: "0x742d35cc6cb34f4c9e5fb5e5a0c2eb9df0b2ae7a",
218
      to: "0x8ba1f109551bd432803012645hac136c98cdcf6b",
219
      data: "0x..."
220
    }]);
221
  } catch (error) {
222
    // BuidlerEVM provides detailed error information
223
    console.log("Transaction failed with detailed stack trace:");
224
    console.log(error.message);
225
    // Shows Solidity stack trace with line numbers
226
  }
227
});
228
```
229

230
### Development Network Constants
231

232
Constants for identifying and working with BuidlerEVM.
233

234
```typescript { .api }
235
/** BuidlerEVM network name constant */
236
const BUIDLEREVM_NETWORK_NAME = "buidlerevm";
237

238
/** Default BuidlerEVM configuration */
239
const defaultBuidlerEVMConfig = {
240
  hardfork: "istanbul",
241
  blockGasLimit: 9500000,
242
  gas: 9500000,
243
  gasPrice: 8000000000, // 8 gwei
244
  chainId: 31337,
245
  throwOnTransactionFailures: true,
246
  throwOnCallFailures: true,
247
  accounts: [
248
    // 20 accounts with 10,000 ETH each
249
    // Private keys are deterministic for testing
250
  ]
251
};
252
```
253

254
### Provider Middleware
255

256
BuidlerEVM supports provider middleware for extending functionality.
257

258
**Example middleware integration:**
259

260
```typescript
261
import { extendEnvironment } from "@nomiclabs/buidler/config";
262

263
extendEnvironment((hre) => {
264
  // Wrap provider with custom middleware
265
  const originalProvider = hre.network.provider;
266
  
267
  hre.network.provider = {
268
    ...originalProvider,
269
    send: async (method: string, params?: any[]) => {
270
      // Log all RPC calls
271
      console.log(`RPC: ${method}`, params);
272
      
273
      const result = await originalProvider.send(method, params);
274
      
275
      console.log(`Result:`, result);
276
      return result;
277
    }
278
  };
279
});
280
```
281

282
### Gas Estimation and Management
283

284
BuidlerEVM provides accurate gas estimation and flexible gas management.
285

286
```typescript { .api }
287
// Automatic gas estimation (default)
288
const config: BuidlerConfig = {
289
  networks: {
290
    buidlerevm: {
291
      gas: "auto",        // Automatic gas limit
292
      gasPrice: "auto",   // Automatic gas price
293
      gasMultiplier: 1.2  // 20% buffer on estimates
294
    }
295
  }
296
};
297

298
// Manual gas configuration
299
const manualConfig: BuidlerConfig = {
300
  networks: {
301
    buidlerevm: {
302
      gas: 9500000,           // Fixed gas limit
303
      gasPrice: 8000000000,   // Fixed gas price (8 gwei)
304
      blockGasLimit: 9500000  // Block gas limit
305
    }
306
  }
307
};
308
```