Buidler is an extensible developer tool that helps Ethereum developers increase productivity by reliably bringing together the tools they want. Developed by Nomic Labs and funded by an Ethereum Foundation grant.
Buidler is:
- A task runner.
- Equipped with built-in tasks for compiling and testing your smart contracts.
- Fully extensible.
- Flexible and lean.
- Usable programmatically as a library.
- Equipped with an interactive console.
- Unopinionated. Choose your own libraries and tools.
Read our announcement to know more about our vision for Buidler.
Join our read-only Buidler News Telegram group to stay up to date on new releases, plugins and tutorials.
The recommended way of using Buidler is through a local installation in your project. This way your environment will be reproducible and you will avoid future version conflicts.
To use it in this way you will need to prepend npx to run it (i.e. npx buidler).
To install locally initialize your npm project using npm init and follow the instructions. Once ready run:
npm install --save-dev @nomiclabs/buidler
Be careful about inconsistent behavior across different projects that use different Buidler versions.
npm -g install @nomiclabs/buidler
Just run buidler in your project root and follow the instructions to initialize a sample Buidler project.
Install one of the core plugins so you have a simple way to interact with your contracts through an Ethereum library.
For example to use Buidler’s Truffle 5 plugin, you should run:
npm install @nomiclabs/buidler-truffle5 @nomiclabs/buidler-web3 web3@1.0.0-beta.37
And make your buidler.config.js file look like this:
require("@nomiclabs/buidler-truffle5");
// You can define your own tasks in this file
task("balance", "Prints an account's balance")
.addParam("account", "The account")
.setAction(async ({ account }) => {
account = web3.utils.toChecksumAddress(account);
const balance = await web3.eth.getBalance(account);
console.log(web3.utils.fromWei(balance, "ether"), "ETH");
});
module.exports = {};After that, all you need to know is that your contracts go in <project-root>/contracts and your tests in <project-root>/tests, as you would do with Truffle 5.
To compile and run your tests:
buidler compile
buidler test
and to test your task:
buidler balance --account 0x6bac6948840a018271a2c9d731c9677a14de9f0c
To learn how to use Buidler in-depth refer to one of our guides:
- How to get started with Buidler
- How to migrate from Truffle
- How to create a Buidler plugin
- How to create a Buidler task
- @nomiclabs/buidler-truffle4: integration with TruffleContract from Truffle 4.
- @nomiclabs/buidler-truffle5: integration with TruffleContract from Truffle 5.
- @nomiclabs/buidler-web3: injects the Web3 1.x module and a live instance into the Buidler Runtime Environment.
- @nomiclabs/buidler-web3-legacy: injects the Web3 0.20.x module and a live instance into the Buidler Runtime Environment.
- @nomiclabs/buidler-ethers: injects ethers.js into the Buidler Runtime Environment.
By default, you can write your tests using mocha. Just put them in <project-root>/test and run them with buidler test. The Buidler Runtime Environment will be available in the global scope.
You can also write your tests as ad-hoc scripts by requiring the Buidler Runtime Environment just like with any other library. Read section Using Buidler in your own scripts for more information.
If you’d like to use a different test runner or testing framework, you can override the test task or simply use Buidler programmatically from your test runner to enable that.
Deployments using Buidler are scripted. You can write a standalone script that uses Buidler as a library (node deploy.js) or it can be a Buidler script (buidler run deploy.js).
Here’s a very simple example of a Buidler deployment script using @nomiclabs/buidler-truffle5.
deploy.js:
const Greeter = artifacts.require("Greeter");
async function deploy() {
const greeter = await Greeter.new("Hello, Buidler!");
console.log("Greeter address:", greeter.address);
}
deploy().catch(console.error);buidler run deploy.js
buidler.config.js in the root of your project is the main config file. You can add any application-specific configurations you may need to this file, just make sure to assign your config to module.exports so it's accessible later on through the config object in the Buidler Runtime Environment.
An empty buidler.config.js is enough for Buidler to work. For a detailed specification of buidler.config.js take a look at our wiki.
Buidler's config file will always run before any task, so you can use it to integrate with other tools, like requiring @babel/register at the top.
Whether you are writing a test, script or creating a new task, Buidler will always provide you with the same environment, which consists of an object with these properties:
config: An object consisting of all of Buidler's configuration.buidlerArguments: An object with the arguments Buidler was run with.run: A function to execute any of Buidler's tasks.ethereum: an EIP1193 Ethereum provider.
You can leverage Buidler's infrastructure and configuration in your own scripts.
By running them with buidler run <path> the Buidler Runtime Environment will be initialized, making all of its properties globally available. Your contracts will be compiled before if necessary.
You can also build them as standalone scripts and run them directly without buidler, you just need to import the Buidler Runtime Environment with require("@nomiclabs/buidler"). If you run them this way, you have to use environment variables to pass arguments directly to Buidler (e.g. BUIDLER_NETWORK=develop).
The way to interact with Ethereum on Buidler works the same as in dapp browsers, through an EIP1193 provider. This provider will handle gas limit, gas price, network validation and default sender for you. There are plugins available for the most used Ethereum libraries. Choose the one you like the most, or write a plugin to integrate a new one (it’s super easy!).
The default artifact format consists of a json containing:
contractName: a string with the nameabi: the abi arraybytecode: A hex (without"0x") string of the unlinked deployment bytecode. If the contract is not deployable then this is an empty string.linkReferences: The link references object as returned bysolc-js. If no link is present then this is an empty object.
You can use TypeScript everywhere in your Buidler project. Your Buidler config, your tests, and your custom scripts can all be typed.
To enable this features, Typescript and ts-node should be installed in the same way that Buidler was. If you installed Buidler globally, run npm i -g typescript ts-node. If you installed Buidler inside of a project, run npm i typescript ts-node.
We’re still working on the stability of the ganache integration to be able to get an instance running automatically when you run Buidler, so we’ve excluded it from this release. We will re-include this feature back into Buidler by the time we ship the first stable release.
Until then, to use the develop network locally you’ll need to install and manually run ganache-cli:
npm install -g ganache-cli
ganache-cli
Contributions are always welcome! Feel free to open any issue or send a pull request.
Buidler Support Telegram group: for any questions or feedback you may have, you can find us here.
Buidler News Telegram group: to remain up to date on Buidler releases, tutorials and news all around. Low-bandwith, read-only group.
MIT
👷♀️👷♂️👷♀️👷♂️👷♀️👷♂️👷♀️👷♂️👷♀️👷♂️👷♀️👷♂️👷♀️👷♂️