Buidler comes built-in with Buidler EVM, a local Ethereum network designed for development. It allows you to deploy your contracts, run your tests and debug your code.
How does it work?
- It mines a block with each transaction that it receives, in order and with no delay.
- It's backed by the
ethereumjs-vmEVM implementation, the same one used by ganache, Remix and Ethereum Studio.
- It supports the following hardforks:
How can I use it?
- Buidler will always spin up an instance on startup when
defaultNetworkis empty or set to
buidlerevm. It's the default behavior.
- It can be used to run tests, in the console, scripts, and tasks
- Plugins (web3.js, ethers.js, Truffle, etc) connect directly to the provider
- There's no need to make any changes to your tests or scripts.
- It's simply another network and it can be used with
Connecting to Buidler EVM from wallets and other software
Buidler EVM can be run as a server or testing node. To do this, you just need to run
npx buidler node
It will start Buidler EVM, and expose it as a JSON-RPC and WebSocket server.
Then, just connect your wallet or application to
If you want to connect Buidler to this node, you only need to run it using
Solidity stack traces
Buidler EVM has first-class Solidity support. It always knows which smart contracts are being run, what they do exactly and why they fail.
This is an example of a Buidler EVM exception:
Error: Transaction reverted: function selector was not recognized and there's no fallback function at ERC721Mock.<unrecognized-selector> (contracts/mocks/ERC721Mock.sol:9) at ERC721Mock._checkOnERC721Received (contracts/token/ERC721/ERC721.sol:334) at ERC721Mock._safeTransferFrom (contracts/token/ERC721/ERC721.sol:196) at ERC721Mock.safeTransferFrom (contracts/token/ERC721/ERC721.sol:179) at ERC721Mock.safeTransferFrom (contracts/token/ERC721/ERC721.sol:162) at TruffleContract.safeTransferFrom (node_modules/@nomiclabs/truffle-contract/lib/execute.js:157:24) at Context.<anonymous> (test/token/ERC721/ERC721.behavior.js:321:26)
Automatic error messages
Buidler EVM always knows why your transaction or call failed, and uses this information to make debugging your contracts easier.
When a transaction fails without a reason, Buidler EVM will create a clear error message in the following cases:
Calling a non-payable function with ETH
Sending ETH to a contract without a payable fallback function
Calling a non-existent function when there's no fallback function
Calling a function with incorrect parameters
Calling an external function that doesn't return the right amount of data
Calling an external function on a non-contract account
Failing to execute an external call because of its parameters (e.g. trying to send too much ETH)
Calling a library without
Incorrectly calling a precompiled contract
Buidler EVM allows you to print logging messages and contract variables calling
console.log() from your Solidity code. You can see an example in the Sample Project. Follow the steps in Quick Start to try it out.
- You can use it in calls and transactions. It works with
viewfunctions, but not in
- It always works, regardless of the call or transaction failing or being successful.
- To use it you need to import
- It works with Solidity 0.5.x and 0.6.x.
- You can call
console.logwith up to 4 parameters in any order of following types:
- There's also the single parameter API for the types above, and additionally
bytes1.. up to
console.logString(string memory s)
console.logBytes(bytes memory b)
console.logimplements the same formatting options that can be found in Node.js'
console.log, which in turn uses
console.log("Changing owner from %s to %s", currentOwner, newOwner)
- It works with any library: web3.js, ethers.js, truffle-contract, waffle, etc.
console.logis implemented in standard Solidity and then detected in Buidler EVM. This makes its compilation work with any other tools (like Remix or Truffle).
console.logcalls can run in other networks, like mainnet, kovan, ropsten, etc. They do nothing in those networks, but spend a minimal amount of gas.
Buidler EVM uses its tracing infrastructure to offer rich logging that will help you develop and debug smart contracts.
For example, a successful transaction and a failed call would look like this:
eth_sendTransaction Contract deployment: Greeter Contract address: 0x8858eeb3dfffa017d4bce9801d340d36cf895ccf Transaction: 0x7ea2754e53f09508d42bd3074046f90595bedd61fcdf75a4764453454733add0 From: 0xc783df8a850f42e7f7e57013759c285caa701eb6 Value: 0 ETH Gas used: 568851 of 2844255 Block: #2 - Hash: 0x4847b316b12170c576999183da927c2f2056aa7d8f49f6e87430e6654a56dab0 console.log: Deploying a Greeter with greeting: Hello, world! eth_call Contract call: Greeter#greet From: 0xc783df8a850f42e7f7e57013759c285caa701eb6 Error: VM Exception while processing transaction: revert Not feeling like it at Greeter.greet (contracts/Greeter.sol:14) at process._tickCallback (internal/process/next_tick.js:68:7)
This logging is enabled by default when using Buidler EVM's node (i.e.
npx buidler node), but disabled when using
the in-process Buidler EVM provider. See Buidler EVM's config enabled it in both.
Buidler EVM initial state
Buidler EVM is initialized by default in this state:
- A brand new blockchain, just with the genesis block.
- 20 accounts with 10000 ETH each
To customise it, take a look at the configuration section.
JSON-RPC methods support
Special testing/debugging methods
evm_increaseTime– same as Ganache.
evm_mine– same as Ganache, except it doesn’t accept a timestamp.
evm_revert– same as Ganache.
evm_snapshot– same as Ganache.
Supported Solidity versions
Buidler EVM can run any smart contract, but it only understands Solidity 0.5.1 and newer.
If you are compiling with an older version of Solidity, or using another language, you can use Buidler EVM, but Solidity stack traces won't be generated.
Solidity optimizer support
Buidler EVM can work with smart contracts compiled with optimizations, but this may lead to your stack traces' line numbers being a little off.
We recommend compiling without optimizations when testing and debugging your contracts.
Contracts reloading after recompilation
If you start Buidler EVM's node and change your contract afterwards, you won't get Solidity stack traces for those, and the logging functionality will be more limited.
As a temporal workaround, you need to restart Buidler EVM's node, after recompiling your contracts.
This limitation will be removed in a future update.