Hevm

An EVM for testing and verification, with a nimble debugger that runs in the terminal.

COMMANDS

$ hvem dapp-test            run dappsys unit tests
$ hvem interactive          enter the interactive debugger

OPTIONS

--json-file      run against a specific output file
--rpc            fetch external contracts via rpc from the latest block

About

The hevm project is an implementation of the Ethereum virtual machine (EVM) made specifically for unit testing and debugging smart contracts. It is developed by DappHub and integrates especially well with the dapp tool suite. The hevm command line program can run unit tests, interactively debug contracts while showing the Solidity source, or run arbitrary EVM code.

This software is alpha quality. It is not yet a 100% complete EVM (almost everything is implemented, but e.g. the precompiled contracts are missing). Testing against the Ethereum Foundation's reference test suite is begun but not completed. See the hevm v0.10 test report.

Usage

After running dapp build, you can then run hevm dapp-test to run a ds-test suite, or hevm interactive to enter the debugger. If the out directory contains multiple .t.sol files then the --json-file flag should be used to specify a target:

  hevm dapp-test --json-file out/my-dapp.t.sol.json

Key Bindings

The following key bindings are available when running in interactive mode:

n
step forward by one instruction
p
step backward by one instruction
N
step several instructions until the source map location changes (like stepping by subexpression)
Ctl-n
like N except that it steps over CALL and CREATE
Esc
exit

Installation

Setting up the DappHub toolkit

If you are running GNU/Linux or macOS you can take advantage of our all in one installer.

$ curl https://dapp.tools/install | sh

This script downloads the Nix package manager, setups binary cache with Cachix and installs our most used tools.

Manual installation

We recommend using the Nix package manager. It works on Linux and OS X and is self-contained and unobtrusive.

$ curl https://nixos.org/nix/install | sh
$ . "$HOME/.nix-profile/etc/profile.d/nix.sh"
$ nix-env -if https://github.com/cachix/cachix/tarball/master --substituters https://cachix.cachix.org --trusted-public-keys cachix.cachix.org-1:eWNHQldwUO7G2VkjpnjDbWwy4KQ/HNxht7H4SSoMckM=
$ cachix use dapp
$ git clone --recursive https://github.com/dapphub/dapptools $HOME/.dapp/dapptools
$ nix-env -f $HOME/.dapp/dapptools -iA dapp seth solc hevm ethsign

Contributing

Tools for dapps

We believe that the free software movement is the most important cultural predecessor to the modern-day renaissance in decentralized technologies.

To catalyze the growth of this ecosystem, and to empower hackers to participate, we’re building a comprehensive suite of blockchain-oriented developer tools in the spirit of the Unix philosophy.

Dapp is all you need to start developing for Ethereum. It creates new dapps, runs Solidity unit tests, debugs, deploys, launches testnets, and more.

Seth is a handy tool for slicing and dicing transactions, querying the blockchain, converting between data formats, performing remote calls, and other everyday tasks.

Hevm is our own EVM implementation with a nimble terminal-based Solidity debugger. It’s used for dapp test and dapp debug.

Evmdis is an EVM disassembler written and maintained by Nick Johnson. It’s useful to make sense of EVM bytecode, especially when developing contracts at the assembly or raw bytecode level.

Dappsys - smart contract building blocks

We also maintain Dappsys, an audited collection of smart contract building blocks designed to complement each other. They include;

Using these proven parts lets us focus on the novel features of the systems we develop. We share Dappsys to benefit the smart contract ecosystem.