0
# Buidler
1

2
Buidler is an extensible Ethereum development framework that helps smart contract developers increase productivity by reliably bringing together the tools they want. It provides a task runner, local development network (BuidlerEVM), compilation tools, testing framework, and plugin system designed around task-based architecture.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
// Main runtime environment (auto-loaded when using require/import in Node.js context)
15
const hre = require("@nomiclabs/buidler");
16
// The main export is the BuidlerRuntimeEnvironment instance
17
```
18

19
For configuration files:
20

21
```typescript
22
import { task, internalTask, extendEnvironment, extendConfig, usePlugin, types } from "@nomiclabs/buidler/config";
23
```
24

25
For plugins:
26

27
```typescript
28
import { BuidlerPluginError, saveArtifact, readArtifact, readArtifactSync, lazyObject, lazyFunction, ensurePluginLoadedWithUsePlugin, BUIDLEREVM_NETWORK_NAME } from "@nomiclabs/buidler/plugins";
29
```
30

31
For plugin testing:
32

33
```typescript
34
import { resetBuidlerContext, loadPluginFile } from "@nomiclabs/buidler/plugins-testing";
35
```
36

37
Register environment globally:
38

39
```typescript
40
import "@nomiclabs/buidler/register";
41
```
42

43
## Basic Usage
44

45
```typescript
46
// buidler.config.ts
47
import { BuidlerConfig, usePlugin } from "@nomiclabs/buidler/config";
48

49
usePlugin("@nomiclabs/buidler-ethers");
50

51
const config: BuidlerConfig = {
52
  defaultNetwork: "buidlerevm",
53
  solc: {
54
    version: "0.5.15",
55
    optimizer: {
56
      enabled: true,
57
      runs: 200
58
    }
59
  },
60
  networks: {
61
    localhost: {
62
      url: "http://127.0.0.1:8545"
63
    }
64
  }
65
};
66

67
export default config;
68
```
69

70
## Architecture
71

72
Buidler is built around several key architectural patterns:
73

74
- **Task System**: Everything is organized around tasks that can be composed, extended, and overridden
75
- **Plugin Architecture**: Functionality is extended through plugins that can register tasks and modify the runtime environment
76
- **Provider Abstraction**: Network interaction is abstracted through EIP-1193 compatible providers with middleware support
77
- **Configuration Merging**: Default, user, and plugin configurations are merged with validation
78
- **Runtime Environment**: Global environment providing access to configuration, tasks, network, and utilities
79

80
## Capabilities
81

82
### Task System
83

84
Core task definition and execution system for organizing build workflows and development operations.
85

86
```typescript { .api }
87
function task<ArgsT extends TaskArguments>(
88
  name: string,
89
  description?: string,
90
  action?: ActionType<ArgsT>
91
): ConfigurableTaskDefinition;
92

93
function internalTask<ArgsT extends TaskArguments>(
94
  name: string,
95
  description?: string,
96
  action?: ActionType<ArgsT>
97
): ConfigurableTaskDefinition;
98

99
interface BuidlerRuntimeEnvironment {
100
  readonly config: ResolvedBuidlerConfig;
101
  readonly buidlerArguments: BuidlerArguments;
102
  readonly tasks: TasksMap;
103
  readonly run: RunTaskFunction;
104
  readonly network: Network;
105
  /** @deprecated Use network.provider instead */
106
  readonly ethereum: EthereumProvider;
107
}
108
```
109

110
[Task System](./task-system.md)
111

112
### Configuration System
113

114
Flexible configuration system supporting network definitions, compilation settings, and plugin integration.
115

116
```typescript { .api }
117
interface BuidlerConfig {
118
  defaultNetwork?: string;
119
  networks?: Networks;
120
  paths?: Omit<Partial<ProjectPaths>, "configFile">;
121
  solc?: DeepPartial<SolcConfig>;
122
  mocha?: Mocha.MochaOptions;
123
  analytics?: Partial<AnalyticsConfig>;
124
}
125

126
function extendConfig(extender: ConfigExtender): void;
127
function extendEnvironment(extender: EnvironmentExtender): void;
128
```
129

130
[Configuration](./configuration.md)
131

132
### BuidlerEVM Provider
133

134
Local Ethereum network simulation providing instant transactions, debugging features, and stack trace generation.
135

136
```typescript { .api }
137
interface EthereumProvider extends EventEmitter {
138
  send(method: string, params?: any[]): Promise<any>;
139
}
140

141
interface Network {
142
  name: string;
143
  config: NetworkConfig;
144
  provider: EthereumProvider;
145
}
146
```
147

148
[BuidlerEVM Provider](./buidlerevm-provider.md)
149

150
### Plugin System
151

152
Extensible plugin architecture for adding functionality and integrating with external tools.
153

154
```typescript { .api }
155
function usePlugin(pluginName: string): void;
156

157
class BuidlerPluginError extends Error {
158
  constructor(
159
    pluginName: string,
160
    message: string,
161
    parent?: Error
162
  );
163
}
164

165
function ensurePluginLoadedWithUsePlugin(): void;
166
```
167

168
[Plugin System](./plugin-system.md)
169

170
### Built-in Tasks
171

172
Core development tasks for compilation, testing, deployment, and project management.
173

174
```typescript { .api }
175
// Core task names
176
const TASK_CLEAN = "clean";
177
const TASK_COMPILE = "compile";
178
const TASK_CONSOLE = "console";
179
const TASK_HELP = "help";
180
const TASK_RUN = "run";
181
const TASK_TEST = "test";
182
const TASK_FLATTEN = "flatten";
183
```
184

185
[Built-in Tasks](./builtin-tasks.md)
186

187
### Artifact Management
188

189
Compilation artifact management for reading, writing, and processing contract compilation results.
190

191
```typescript { .api }
192
interface Artifact {
193
  contractName: string;
194
  abi: any;
195
  bytecode: string;
196
  deployedBytecode: string;
197
  linkReferences: LinkReferences;
198
  deployedLinkReferences: LinkReferences;
199
}
200

201
function saveArtifact(artifactsPath: string, artifact: Artifact): Promise<void>;
202
function readArtifact(artifactsPath: string, contractName: string): Promise<Artifact>;
203
function readArtifactSync(artifactsPath: string, contractName: string): Artifact;
204
```
205

206
[Artifact Management](./artifact-management.md)
207

208
## Types
209

210
```typescript { .api }
211
type TaskArguments = any;
212

213
type ActionType<ArgsT extends TaskArguments> = (
214
  taskArgs: ArgsT,
215
  env: BuidlerRuntimeEnvironment,
216
  runSuper: RunSuperFunction<ArgsT>
217
) => Promise<any>;
218

219
type RunTaskFunction = (
220
  name: string,
221
  taskArguments?: TaskArguments
222
) => Promise<any>;
223

224
interface RunSuperFunction<ArgT extends TaskArguments> {
225
  (taskArguments?: ArgT): Promise<any>;
226
  isDefined: boolean;
227
}
228

229
type EnvironmentExtender = (env: BuidlerRuntimeEnvironment) => void;
230

231
type ConfigExtender = (
232
  config: ResolvedBuidlerConfig,
233
  userConfig: DeepReadonly<BuidlerConfig>
234
) => void;
235

236
interface TasksMap {
237
  [name: string]: TaskDefinition;
238
}
239

240
interface TaskDefinition extends ConfigurableTaskDefinition {
241
  readonly name: string;
242
  readonly description?: string;
243
  readonly action: ActionType<TaskArguments>;
244
  readonly isInternal: boolean;
245
  readonly paramDefinitions: ParamDefinitionsMap;
246
  readonly positionalParamDefinitions: Array<ParamDefinition<any>>;
247
}
248

249
interface ParamDefinitionsMap {
250
  [paramName: string]: ParamDefinition<any>;
251
}
252

253
interface ParamDefinition<T> {
254
  name: string;
255
  defaultValue?: T;
256
  type: ArgumentType<T>;
257
  description?: string;
258
  isOptional: boolean;
259
  isFlag: boolean;
260
  isVariadic: boolean;
261
}
262

263
interface ArgumentType<T> {
264
  name: string;
265
  parse(argName: string, strValue: string): T;
266
}
267

268
interface LinkReferences {
269
  [libraryFileName: string]: {
270
    [libraryName: string]: Array<{ length: number; start: number }>;
271
  };
272
}
273

274
type NetworkConfig = BuidlerNetworkConfig | HttpNetworkConfig;
275

276
interface Networks {
277
  [networkName: string]: NetworkConfig;
278
}
279

280
type NetworkConfigAccounts =
281
  | "remote"
282
  | string[]
283
  | HDAccountsConfig
284
  | OtherAccountsConfig;
285

286
interface ProjectPaths {
287
  root: string;
288
  configFile: string;
289
  cache: string;
290
  artifacts: string;
291
  sources: string;
292
  tests: string;
293
}
294

295
interface BuidlerNetworkAccount {
296
  privateKey: string;
297
  balance: string;
298
}
299

300
interface HDAccountsConfig {
301
  mnemonic: string;
302
  initialIndex?: number;
303
  count?: number;
304
  path?: string;
305
}
306

307
interface OtherAccountsConfig {
308
  type: string;
309
}
310

311
interface SolcConfig {
312
  version: string;
313
  optimizer: SolcOptimizerConfig;
314
  evmVersion?: string;
315
}
316

317
interface SolcOptimizerConfig {
318
  enabled: boolean;
319
  runs: number;
320
}
321

322
interface AnalyticsConfig {
323
  enabled: boolean;
324
}
325

326
interface ResolvedBuidlerConfig extends BuidlerConfig {
327
  defaultNetwork: string;
328
  paths: ProjectPaths;
329
  networks: Networks;
330
  solc: SolcConfig;
331
  analytics: AnalyticsConfig;
332
}
333

334
interface BuidlerArguments {
335
  network?: string;
336
  showStackTraces: boolean;
337
  version: boolean;
338
  help: boolean;
339
  emoji: boolean;
340
  config?: string;
341
  verbose: boolean;
342
  maxMemory?: number;
343
}
344
```