Buidler Ethers Plugin

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.

Package Information

• Package Name: @nomiclabs/buidler-ethers
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev @nomiclabs/buidler-ethers ethers@^4.0.23

Core Imports

// Plugin activation in buidler.config.js
usePlugin("@nomiclabs/buidler-ethers");

The plugin extends the Buidler Runtime Environment and does not export functions directly. Access is through the BRE:

// In tasks, tests, or scripts
const { ethers } = require("@nomiclabs/buidler");
// or in TypeScript with proper types
import { BuidlerRuntimeEnvironment } from "@nomiclabs/buidler/types";

Basic Usage

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

// Use in a task
task("example", "Example task", async (_, { ethers }) => {
  // Get current block number
  const blockNumber = await ethers.provider.getBlockNumber();
  console.log("Current block:", blockNumber);
  
  // Get signers
  const signers = await ethers.signers();
  console.log("First signer address:", await signers[0].getAddress());
  
  // Get a contract factory
  const Greeter = await ethers.getContract("Greeter");
  const greeter = await Greeter.deploy("Hello, world!");
});

Architecture

The plugin uses a lazy initialization pattern to extend the Buidler Runtime Environment with three key components:

• Provider Wrapper: EthersProviderWrapper adapts Buidler's IEthereumProvider to ethers' JsonRpcProvider interface
• Contract Factory Creation: Automated loading of contract artifacts and factory creation with signer connection
• Signer Management: Conversion of provider accounts into ethers Signer instances

The integration is seamless and requires no additional setup beyond plugin activation.

Capabilities

Provider Access

Access to an ethers-compatible JSON-RPC provider that wraps Buidler's network provider.

ethers.provider: EthersProviderWrapper

The provider is an instance of EthersProviderWrapper that extends JsonRpcProvider and provides all standard ethers provider functionality including:

• send(method: string, params: any): Promise<any> - Send JSON-RPC requests
• getBlockNumber(): Promise<number> - Get current block number
• listAccounts(): Promise<string[]> - Get available accounts
• getSigner(account: string): Signer - Get signer for specific account
• All other standard JsonRpcProvider methods

Contract Factory Creation

Create ethers ContractFactory instances from compiled contract artifacts.

ethers.getContract: (name: string) => Promise<ContractFactory>

Parameters:

• name (string): Name of the contract artifact (without .sol extension)

Returns:

• Promise<ContractFactory>: ContractFactory instance connected to the first available signer

Usage Example:

// Assuming you have a Greeter.sol contract compiled in artifacts/
const Greeter = await ethers.getContract("Greeter");

// Deploy the contract
const greeter = await Greeter.deploy("Hello, Buidler!");
await greeter.deployed();

// Call contract methods
const greeting = await greeter.greet();
console.log(greeting);

Signer Access

Get array of ethers Signer instances for all available accounts.

ethers.signers: () => Promise<Signer[]>

Returns:

• Promise<Signer[]>: Array of ethers Signer instances for each account returned by the provider

Usage Example:

const signers = await ethers.signers();

// Get the first signer's address
const address = await signers[0].getAddress();
console.log("Deployer address:", address);

// Get balance
const balance = await signers[0].getBalance();
console.log("Balance:", ethers.utils.formatEther(balance), "ETH");

Types

EthersProviderWrapper

class EthersProviderWrapper extends JsonRpcProvider {
  constructor(buidlerProvider: IEthereumProvider);
  send(method: string, params: any): Promise<any>;
}

Internal wrapper class that adapts Buidler's provider to ethers' JsonRpcProvider interface. Emits debug events following ethers conventions.

Buidler Runtime Environment Extension

interface BuidlerRuntimeEnvironment {
  ethers: {
    provider: JsonRpcProvider;
    getContract: (name: string) => Promise<ContractFactory>;
    signers: () => Promise<Signer[]>;
  };
}

The plugin extends the Buidler Runtime Environment with the ethers property containing the three core functions.

TypeScript Support

For TypeScript projects, include the type extensions in your tsconfig.json:

{
  "files": [
    "node_modules/@nomiclabs/buidler-ethers/src/type-extensions.d.ts"
  ]
}

This provides full type safety for the extended BRE interface, including autocompletion and type checking for the ethers property.

Error Handling

The plugin follows ethers.js conventions for error handling:

• Provider errors are propagated from the underlying Buidler provider
• Contract factory creation may throw if the specified artifact is not found
• Signers array reflects the accounts available from the current network provider

Debug information is emitted for all JSON-RPC requests through the provider's debug events.