or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

artifact-management.mdbuidlerevm-provider.mdbuiltin-tasks.mdconfiguration.mdindex.mdplugin-system.mdtask-system.md
tile.json

tessl/npm-nomiclabs--buidler

Extensible Ethereum development framework with task runner, local network simulation, compilation tools, and plugin system.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@nomiclabs/buidler@1.1.x

To install, run

npx @tessl/cli install tessl/npm-nomiclabs--buidler@1.1.0

index.mddocs/

Buidler

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.

Package Information

  • Package Name: @nomiclabs/buidler
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @nomiclabs/buidler

Core Imports

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

For configuration files:

import { task, internalTask, extendEnvironment, extendConfig, usePlugin, types } from "@nomiclabs/buidler/config";

For plugins:

import { BuidlerPluginError, saveArtifact, readArtifact, readArtifactSync, lazyObject, lazyFunction, ensurePluginLoadedWithUsePlugin, BUIDLEREVM_NETWORK_NAME } from "@nomiclabs/buidler/plugins";

For plugin testing:

import { resetBuidlerContext, loadPluginFile } from "@nomiclabs/buidler/plugins-testing";

Register environment globally:

import "@nomiclabs/buidler/register";

Basic Usage

// buidler.config.ts
import { BuidlerConfig, usePlugin } from "@nomiclabs/buidler/config";

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

const config: BuidlerConfig = {
  defaultNetwork: "buidlerevm",
  solc: {
    version: "0.5.15",
    optimizer: {
      enabled: true,
      runs: 200
    }
  },
  networks: {
    localhost: {
      url: "http://127.0.0.1:8545"
    }
  }
};

export default config;

Architecture

Buidler is built around several key architectural patterns:

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

Capabilities

Task System

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

function task<ArgsT extends TaskArguments>(
  name: string,
  description?: string,
  action?: ActionType<ArgsT>
): ConfigurableTaskDefinition;

function internalTask<ArgsT extends TaskArguments>(
  name: string,
  description?: string,
  action?: ActionType<ArgsT>
): ConfigurableTaskDefinition;

interface BuidlerRuntimeEnvironment {
  readonly config: ResolvedBuidlerConfig;
  readonly buidlerArguments: BuidlerArguments;
  readonly tasks: TasksMap;
  readonly run: RunTaskFunction;
  readonly network: Network;
  /** @deprecated Use network.provider instead */
  readonly ethereum: EthereumProvider;
}

Task System

Configuration System

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

interface BuidlerConfig {
  defaultNetwork?: string;
  networks?: Networks;
  paths?: Omit<Partial<ProjectPaths>, "configFile">;
  solc?: DeepPartial<SolcConfig>;
  mocha?: Mocha.MochaOptions;
  analytics?: Partial<AnalyticsConfig>;
}

function extendConfig(extender: ConfigExtender): void;
function extendEnvironment(extender: EnvironmentExtender): void;

Configuration

BuidlerEVM Provider

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

interface EthereumProvider extends EventEmitter {
  send(method: string, params?: any[]): Promise<any>;
}

interface Network {
  name: string;
  config: NetworkConfig;
  provider: EthereumProvider;
}

BuidlerEVM Provider

Plugin System

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

function usePlugin(pluginName: string): void;

class BuidlerPluginError extends Error {
  constructor(
    pluginName: string,
    message: string,
    parent?: Error
  );
}

function ensurePluginLoadedWithUsePlugin(): void;

Plugin System

Built-in Tasks

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

// Core task names
const TASK_CLEAN = "clean";
const TASK_COMPILE = "compile";
const TASK_CONSOLE = "console";
const TASK_HELP = "help";
const TASK_RUN = "run";
const TASK_TEST = "test";
const TASK_FLATTEN = "flatten";

Built-in Tasks

Artifact Management

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

interface Artifact {
  contractName: string;
  abi: any;
  bytecode: string;
  deployedBytecode: string;
  linkReferences: LinkReferences;
  deployedLinkReferences: LinkReferences;
}

function saveArtifact(artifactsPath: string, artifact: Artifact): Promise<void>;
function readArtifact(artifactsPath: string, contractName: string): Promise<Artifact>;
function readArtifactSync(artifactsPath: string, contractName: string): Artifact;

Artifact Management

Types

type TaskArguments = any;

type ActionType<ArgsT extends TaskArguments> = (
  taskArgs: ArgsT,
  env: BuidlerRuntimeEnvironment,
  runSuper: RunSuperFunction<ArgsT>
) => Promise<any>;

type RunTaskFunction = (
  name: string,
  taskArguments?: TaskArguments
) => Promise<any>;

interface RunSuperFunction<ArgT extends TaskArguments> {
  (taskArguments?: ArgT): Promise<any>;
  isDefined: boolean;
}

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

type ConfigExtender = (
  config: ResolvedBuidlerConfig,
  userConfig: DeepReadonly<BuidlerConfig>
) => void;

interface TasksMap {
  [name: string]: TaskDefinition;
}

interface TaskDefinition extends ConfigurableTaskDefinition {
  readonly name: string;
  readonly description?: string;
  readonly action: ActionType<TaskArguments>;
  readonly isInternal: boolean;
  readonly paramDefinitions: ParamDefinitionsMap;
  readonly positionalParamDefinitions: Array<ParamDefinition<any>>;
}

interface ParamDefinitionsMap {
  [paramName: string]: ParamDefinition<any>;
}

interface ParamDefinition<T> {
  name: string;
  defaultValue?: T;
  type: ArgumentType<T>;
  description?: string;
  isOptional: boolean;
  isFlag: boolean;
  isVariadic: boolean;
}

interface ArgumentType<T> {
  name: string;
  parse(argName: string, strValue: string): T;
}

interface LinkReferences {
  [libraryFileName: string]: {
    [libraryName: string]: Array<{ length: number; start: number }>;
  };
}

type NetworkConfig = BuidlerNetworkConfig | HttpNetworkConfig;

interface Networks {
  [networkName: string]: NetworkConfig;
}

type NetworkConfigAccounts =
  | "remote"
  | string[]
  | HDAccountsConfig
  | OtherAccountsConfig;

interface ProjectPaths {
  root: string;
  configFile: string;
  cache: string;
  artifacts: string;
  sources: string;
  tests: string;
}

interface BuidlerNetworkAccount {
  privateKey: string;
  balance: string;
}

interface HDAccountsConfig {
  mnemonic: string;
  initialIndex?: number;
  count?: number;
  path?: string;
}

interface OtherAccountsConfig {
  type: string;
}

interface SolcConfig {
  version: string;
  optimizer: SolcOptimizerConfig;
  evmVersion?: string;
}

interface SolcOptimizerConfig {
  enabled: boolean;
  runs: number;
}

interface AnalyticsConfig {
  enabled: boolean;
}

interface ResolvedBuidlerConfig extends BuidlerConfig {
  defaultNetwork: string;
  paths: ProjectPaths;
  networks: Networks;
  solc: SolcConfig;
  analytics: AnalyticsConfig;
}

interface BuidlerArguments {
  network?: string;
  showStackTraces: boolean;
  version: boolean;
  help: boolean;
  emoji: boolean;
  config?: string;
  verbose: boolean;
  maxMemory?: number;
}