Hevm

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

COMMANDS

hevm -- Ethereum evaluator written in Haskell

Usage: hevm (exec | dapp-test | interactive | bc-test | compliance | flatten |
            emacs | version | rlp | abiencode | merkle-test | strip-metadata)

Available options:
  -h,--help                Show this help text

Available commands:
  exec
  dapp-test
  interactive
  bc-test
  compliance
  flatten
  emacs
  version
  rlp
  abiencode
  merkle-test
  strip-metadata

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, property tests, interactively debug contracts while showing the Solidity source, or run arbitrary EVM code. State can be fetched from a remote node, or stored locally over several executions.

hevm is a fully compliant EVM implementation which passes the General State Tests and supports all the Instanbul precompiles.

Standalone usage

hevm can execute arbitrary EVM code by the command hevm exec. For example, to run a simple EVM Quine, try: hevm exec --code 0x647175696e6550383480393834f3 --gas 0xff

If given the --rpc flag, state will be fetched from the url provided: hevm exec --rpc https://mainnet.infura.io/v3/$INFURA_API_KEY --address 0x64043a98f097fD6ef0D3ad41588a6B0424723b3a --debug --gas 0xffffff --calldata $(seth calldata "nonces(address)" 0x64043a98f097fD6ef0D3ad41588a6B0424723b3a)

For more information, refer to the hevm README

Usage with dapp tests

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:

a
step to start of execution
e
step to end of execution
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
m
toggle memory pane
Enter
display contract overview
Esc
exit

Installation

Setting up the DappHub toolkit

Dapptools requires Nix, so make sure you have it installed first. After that, you can take advantage of our one-line installer.

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

This script downloads the latest version of dapptools, sets up a binary cache using 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 -L https://nixos.org/nix/install | sh
$ . "$HOME/.nix-profile/etc/profile.d/nix.sh"
$ nix-env -iA dapp hevm seth solc -if https://github.com/dapphub/dapptools/tarball/master --substituters https://dapp.cachix.org --trusted-public-keys dapp.cachix.org-1:9GJt9Ja8IQwR7YW/aF0QvCa6OmjGmsKoZIist0dG+Rs=

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.

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.