0
# Configuration System
1

2
Buidler's configuration system provides flexible, type-safe configuration management with support for network definitions, compilation settings, file paths, and plugin integration. Configuration is merged from defaults, user settings, and plugin extensions.
3

4
## Capabilities
5

6
### Basic Configuration
7

8
Define project configuration with network settings, compilation options, and file paths.
9

10
```typescript { .api }
11
/**
12
 * Main Buidler configuration interface
13
 */
14
interface BuidlerConfig {
15
  /** Default network name to use when none specified */
16
  defaultNetwork?: string;
17
  /** Network configuration definitions */
18
  networks?: Networks;
19
  /** Project file system paths (excluding configFile) */
20
  paths?: Omit<Partial<ProjectPaths>, "configFile">;
21
  /** Solidity compiler configuration */
22
  solc?: DeepPartial<SolcConfig>;
23
  /** Mocha test runner configuration */
24
  mocha?: Mocha.MochaOptions;
25
  /** Analytics configuration */
26
  analytics?: Partial<AnalyticsConfig>;
27
}
28

29
/**
30
 * Resolved configuration with all defaults applied
31
 */
32
interface ResolvedBuidlerConfig extends BuidlerConfig {
33
  defaultNetwork: string;
34
  paths: ProjectPaths;
35
  networks: Networks;
36
  solc: SolcConfig;
37
  analytics: AnalyticsConfig;
38
}
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
// buidler.config.ts
45
import { BuidlerConfig } from "@nomiclabs/buidler/config";
46

47
const config: BuidlerConfig = {
48
  defaultNetwork: "buidlerevm",
49
  
50
  networks: {
51
    localhost: {
52
      url: "http://127.0.0.1:8545"
53
    },
54
    mainnet: {
55
      url: "https://mainnet.infura.io/v3/your-key",
56
      accounts: ["0x..."],
57
      gas: "auto",
58
      gasPrice: "auto"
59
    }
60
  },
61
  
62
  solc: {
63
    version: "0.5.15",
64
    optimizer: {
65
      enabled: true,
66
      runs: 200
67
    }
68
  },
69
  
70
  paths: {
71
    sources: "./contracts",
72
    tests: "./test",
73
    cache: "./cache",
74
    artifacts: "./artifacts"
75
  }
76
};
77

78
export default config;
79
```
80

81
### Network Configuration
82

83
Define network-specific settings for local development, testnets, and mainnet deployment.
84

85
```typescript { .api }
86
/**
87
 * Union type for network configurations
88
 */
89
type NetworkConfig = BuidlerNetworkConfig | HttpNetworkConfig;
90

91
/**
92
 * Configuration for the local BuidlerEVM network
93
 */
94
interface BuidlerNetworkConfig extends CommonNetworkConfig {
95
  /** Predefined accounts with private keys and balances */
96
  accounts?: BuidlerNetworkAccount[];
97
  /** Block gas limit for the network */
98
  blockGasLimit?: number;
99
  /** Ethereum hardfork to simulate */
100
  hardfork?: string;
101
  /** Whether to throw on transaction failures */
102
  throwOnTransactionFailures?: boolean;
103
  /** Whether to throw on call failures */
104
  throwOnCallFailures?: boolean;
105
}
106

107
/**
108
 * Configuration for HTTP-based networks (testnets, mainnet)
109
 */
110
interface HttpNetworkConfig extends CommonNetworkConfig {
111
  /** RPC endpoint URL */
112
  url?: string;
113
  /** Request timeout in milliseconds */
114
  timeout?: number;
115
  /** Account configuration (private keys, HD wallet, or "remote") */
116
  accounts?: NetworkConfigAccounts;
117
}
118

119
/**
120
 * Common network configuration properties
121
 */
122
interface CommonNetworkConfig {
123
  /** Chain ID for the network */
124
  chainId?: number;
125
  /** Default from address */
126
  from?: string;
127
  /** Gas limit ("auto" or specific amount) */
128
  gas?: "auto" | number;
129
  /** Gas price ("auto" or specific price in wei) */
130
  gasPrice?: "auto" | number;
131
  /** Gas price multiplier for estimation adjustments */
132
  gasMultiplier?: number;
133
}
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
const config: BuidlerConfig = {
140
  networks: {
141
    // Local BuidlerEVM with custom accounts
142
    buidlerevm: {
143
      hardfork: "istanbul",
144
      blockGasLimit: 9500000,
145
      accounts: [
146
        {
147
          privateKey: "0x...",
148
          balance: "10000000000000000000000" // 10k ETH
149
        }
150
      ]
151
    },
152
    
153
    // HTTP network with HD wallet
154
    ropsten: {
155
      url: "https://ropsten.infura.io/v3/your-key",
156
      accounts: {
157
        mnemonic: "word1 word2 word3...",
158
        initialIndex: 0,
159
        count: 10,
160
        path: "m/44'/60'/0'/0"
161
      },
162
      gas: 5000000,
163
      gasPrice: 20000000000 // 20 gwei
164
    },
165
    
166
    // HTTP network with private keys
167
    mainnet: {
168
      url: "https://mainnet.infura.io/v3/your-key",
169
      accounts: ["0xprivatekey1", "0xprivatekey2"],
170
      gas: "auto",
171
      gasPrice: "auto",
172
      gasMultiplier: 1.2
173
    }
174
  }
175
};
176
```
177

178
### Account Configuration
179

180
Configure account management for different network types.
181

182
```typescript { .api }
183
/**
184
 * Account configuration union type
185
 */
186
type NetworkConfigAccounts =
187
  | "remote"                    // Use accounts from RPC provider
188
  | string[]                    // Array of private keys
189
  | HDAccountsConfig           // HD wallet configuration
190
  | OtherAccountsConfig;       // Plugin-defined account types
191

192
/**
193
 * HD wallet account configuration
194
 */
195
interface HDAccountsConfig {
196
  /** BIP39 mnemonic phrase */
197
  mnemonic: string;
198
  /** Starting account index */
199
  initialIndex?: number;
200
  /** Number of accounts to derive */
201
  count?: number;
202
  /** HD derivation path */
203
  path?: string;
204
}
205

206
/**
207
 * BuidlerEVM account with balance
208
 */
209
interface BuidlerNetworkAccount {
210
  /** Account private key */
211
  privateKey: string;
212
  /** Account balance in wei (as string) */
213
  balance: string;
214
}
215

216
/**
217
 * Plugin-defined account configuration
218
 */
219
interface OtherAccountsConfig {
220
  /** Account provider type */
221
  type: string;
222
  // Additional properties defined by plugins
223
}
224
```
225

226
### File Path Configuration
227

228
Configure project directory structure and file locations.
229

230
```typescript { .api }
231
/**
232
 * Project file system paths
233
 */
234
interface ProjectPaths {
235
  /** Project root directory */
236
  root: string;
237
  /** Configuration file path */
238
  configFile: string;
239
  /** Build cache directory */
240
  cache: string;
241
  /** Compilation artifacts directory */
242
  artifacts: string;
243
  /** Contract source files directory */
244
  sources: string;
245
  /** Test files directory */
246
  tests: string;
247
}
248
```
249

250
### Solidity Compiler Configuration
251

252
Configure Solidity compilation settings and optimization.
253

254
```typescript { .api }
255
/**
256
 * Solidity compiler configuration
257
 */
258
interface SolcConfig {
259
  /** Solidity compiler version */
260
  version: string;
261
  /** Optimizer configuration */
262
  optimizer: SolcOptimizerConfig;
263
  /** EVM version target */
264
  evmVersion?: string;
265
}
266

267
/**
268
 * Solidity optimizer configuration
269
 */
270
interface SolcOptimizerConfig {
271
  /** Whether optimizer is enabled */
272
  enabled: boolean;
273
  /** Number of optimization runs */
274
  runs: number;
275
}
276

277
/**
278
 * Analytics configuration
279
 */
280
interface AnalyticsConfig {
281
  /** Whether to send usage analytics */
282
  enabled: boolean;
283
}
284
```
285

286
### Configuration Extension
287

288
Extend and modify configuration through plugins and environment extenders.
289

290
```typescript { .api }
291
/**
292
 * Extend the resolved configuration
293
 * @param extender - Function to modify configuration
294
 */
295
function extendConfig(extender: ConfigExtender): void;
296

297
/**
298
 * Extend the runtime environment after initialization
299
 * @param extender - Function to modify runtime environment
300
 */
301
function extendEnvironment(extender: EnvironmentExtender): void;
302

303
/**
304
 * Configuration extender function signature
305
 * @param config - Resolved configuration to modify
306
 * @param userConfig - Original user configuration (read-only)
307
 */
308
type ConfigExtender = (
309
  config: ResolvedBuidlerConfig,
310
  userConfig: DeepReadonly<BuidlerConfig>
311
) => void;
312

313
/**
314
 * Environment extender function signature
315
 * @param env - Runtime environment to modify
316
 */
317
type EnvironmentExtender = (env: BuidlerRuntimeEnvironment) => void;
318
```
319

320
**Usage Examples:**
321

322
```typescript
323
import { extendConfig, extendEnvironment } from "@nomiclabs/buidler/config";
324

325
// Extend configuration
326
extendConfig((config, userConfig) => {
327
  // Add custom path based on user config
328
  if (userConfig.customPath) {
329
    config.paths.custom = userConfig.customPath;
330
  }
331
  
332
  // Modify network settings
333
  config.networks.development = {
334
    url: "http://localhost:8545",
335
    gas: 9500000
336
  };
337
});
338

339
// Extend runtime environment
340
extendEnvironment((hre) => {
341
  // Add custom utilities
342
  hre.customUtils = {
343
    deployContract: async (name: string) => {
344
      // Custom deployment logic
345
    }
346
  };
347
});
348
```
349

350
### Command Line Arguments
351

352
Access parsed command-line arguments within tasks and environment.
353

354
```typescript { .api }
355
/**
356
 * Buidler command-line arguments
357
 */
358
interface BuidlerArguments {
359
  /** Target network name */
360
  network?: string;
361
  /** Show stack traces on errors */
362
  showStackTraces: boolean;
363
  /** Show version information */
364
  version: boolean;
365
  /** Show help information */
366
  help: boolean;
367
  /** Enable emoji output */
368
  emoji: boolean;
369
  /** Custom config file path */
370
  config?: string;
371
  /** Enable verbose logging */
372
  verbose: boolean;
373
  /** Maximum memory usage */
374
  maxMemory?: number;
375
}
376
```
377

378
### Default Configuration Values
379

380
Standard default values used when not explicitly configured.
381

382
```typescript { .api }
383
// Default network name
384
const BUIDLEREVM_NETWORK_NAME = "buidlerevm";
385

386
// Default configuration values:
387
const defaultConfig = {
388
  defaultNetwork: "buidlerevm",
389
  
390
  networks: {
391
    buidlerevm: {
392
      hardfork: "istanbul",
393
      blockGasLimit: 9500000,
394
      gas: 9500000,
395
      gasPrice: 8000000000,
396
      chainId: 31337,
397
      throwOnTransactionFailures: true,
398
      throwOnCallFailures: true,
399
      accounts: [/* 20 accounts with 10k ETH each */]
400
    },
401
    
402
    localhost: {
403
      url: "http://127.0.0.1:8545"
404
    }
405
  },
406
  
407
  solc: {
408
    version: "0.5.15",
409
    optimizer: {
410
      enabled: false,
411
      runs: 200
412
    }
413
  },
414
  
415
  paths: {
416
    root: process.cwd(),
417
    sources: "./contracts",
418
    tests: "./test",
419
    cache: "./cache",
420
    artifacts: "./artifacts"
421
  },
422
  
423
  analytics: {
424
    enabled: true
425
  },
426
  
427
  mocha: {
428
    timeout: 20000
429
  }
430
};
431
```