Buidler is a new smart contracts development tool that aims to be lean and flexible. It provides a ready to use dev environment which is easy to extend and interoperable with the whole javascript ecosystem.

⚠️ Buidler is alpha software. You can start using it today, but bear in mind that some APIs may change, and you may encounter bugs ⚠️

1. Creating your project
2. Testing your contracts
3. Deploying your contracts
4. Configuration
5. Using buidler in your own scripts
6. The buidler environment
7. Creating your own tasks
8. Migrating from Truffle
9. Installation
10. Contributing
11. License

Just run buidler in your project root and follow the instructions.

A sample project will be created with examples on how to write contracts, tests and any scripts your project may need.

All you need to know is that your contracts go in <project-root>/contracts.

Buidler lets you test your project in any way you want. Replacing the test runner, using a different testing framework or running from an editor integration are all allowed, and super easy.

By default, you can write your tests using mocha and chai. Just put them in <project-root>/test and run them with buidler test. The buidler environment and chai's assert will be available in the global scope.

You can write your tests as normal scripts by requiring buidler's environment as any other library. Read section Using buidler in your own scripts for more info.

buidler deploy will guide you through an interactive process to deploy your contracts in an easy way.

If you prefer a non-interactive deployment process, you can write your own deployment script.

buidler-config.js in the root of your project is the main config file. Feel free to add whatever you want in there, just make sure to assign your config to module.exports so it's accessible later on.

Networks configuration is fully compatible with Truffle's, with one small but useful difference: buidler will estimate deployment gas cost for you. There's no need for you to specify it. Take a look here to learn how to configure it, or just copy over your existing config.

Buidler lets you choose which version of solc your project uses. In buidler-config.js:

module.exports = {
  solc: {
    version: "x.x.x"
  }
}

Buidler's config file will always run before any task, so you can use it to integrate with other tools, like importing babel-register.

You can leverage buidler's infrastructure and configuration in your own scripts.

By running them with buidler run <path> the buidler environment will be initialized, making all of its properties globally available. Your contracts will be compiled before if necessary.

You can also run them without using buidler, you just need to import the buidler environment with require("buidler"). If you run them this way, you have to use environment variables to pass arguments to buidler (e.g. NETWORK=develop).

Whether you are writing tests, a 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 the buidler's configuration.
• buidlerArguments: An object with the values of the different arguments that buidler accepts.
• Web3: The web3.js module.
• web3: a Web3 instance connected to the chosen network.
• pweb3: A promisified version of web3.
• run: A function to execute any of buidler's tasks.
• artifacts: an object containing two methods:
  • artifacts.require("ContractName") which can be used to obtain already initialized Truffle's contract abstractions.
  • artifacts.link(ContractAbstraction, ...libraries) for linking your contracts and libraries.

You can create your own tasks using a simple DSL. You just need to define them in your buidler-config.js file, and they will be automatically available through buidler's CLI. Arguments parsing and help messages will be taken care of for you.

We will write more documentation about how to define tasks soon, but until then you can use the tasks in src/builtin-tasks/ as a reference.

If you need to take your customization really far, you can even override the built-in tasks. By just redefining any of them, your own version will be run. You can use runSuper() within your task to execute the default version.

Note that most built-in tasks are composed of many micro-tasks, so most likely you only need to override one of those.

While buidler doesn't intend to provide every feature that truffle has, it aims to be a drop-in replacement for Truffle tests. As long as you are not using Truffle migrations, just rename your truffle config file to buidler-config.js, and run buidler test.

To use buidler you need to have node 8.x installed.

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 add npx before buidler to run it.

To install locally initialize your npm project using npm init and follow the instructions. Once ready run:

npm install --save-dev buidler

If you are willing to risk hours of your time to debug inconsistent behavior across different projects before discovering you are using different versions, just run:

npm -g install buidler

Contributions are always welcome! Feel free to open any issue or send a pull request.

MIT

👷‍♀️👷‍♂️👷‍♀️👷‍♂️👷‍♀️👷‍♂️👷‍♀️👷‍♂️👷‍♀️👷‍♂️👷‍♀️👷‍♂️👷‍♀️👷‍♂️