echidna

Echidna is a weird creature that eats bugs and is highly electrosensitive (with apologies to Jacob Stanley)

More seriously, it's a Haskell library designed for fuzzing/property based testing of EVM code. Currently it is quite alpha, and the API isn't guaranteed to be functional, let alone stable. It supports relatively sophisticated grammar-based fuzzing campaigns to falsify a variety of predicates.

Installation

stack is highly recommended to install echidna. If you are a particularly opinionated experienced Haskell user, cabal or hpack should work, but they are neither officially supported nor tested.

Before starting with it, make sure you have libgmp-dev installed otherwise ghc will fail to compile. Also, libbz2 and libreadline are required by some packages. For instance, in Ubuntu/Debian you can execute:

# apt-get install libgmp-dev libbz2-dev libreadline-dev

solc is another echidna dependency not handled via stack. It is technically optional, but working with solidity source will fail without it.

Once solc is installed, installing stack and running stack upgrade; stack setup; stack install from inside the directory should be all that's needed.

If you have weird problems involving readline on MacOS, try brew install readline; brew link readline; stack install readline --extra-include-dirs=/usr/local/opt/readline/include --extra-lib-dirs=/usr/local/opt/readline/lib; stack install.

Notably, if you are using stack, stack ghci will set up a REPL with all functions in scope. This can be quite useful for playing around with the library.

Usage (as an executable)

Echidna builds an executable, echidna-test that can be used from the command line to fuzz solidity code. It expects unit tests in the form of functions with names starting with echidna_ that take no arguments and return a bool indicating success or failure. For each unit test it finds, it will execute a fuzzing campaign to try and find a set of calls such that executing that call sequence, then the test either returns false or results in a VM failure.

An example contract with tests can be found solidity/cli.sol echidna-test solidity/cli.sol should find a call sequence such that echidna_sometimesfalse fails, but be unable to do so for echidna_alwaystrue.

Usage (as a library)

Echidna is actively being developed with relatively little regard for stability. As a result of this, there is a lack of extensive documentation at the present time. There is a small working example provided that should be relatively instructional.

Echidna.ABI

This module provides Hedgehog generators for most of the EVM ABI. It can be used without any other module to provide random "ASTs" (e.g. a random dynamic array of static arrays of 16 248-bit unsigned ints) or calldata (EVM-encoded function calls with these arguments).

Whenever possible, it tries to copy the convention of hevm.

Echidna.Exec

This module provides functionality for executing fuzzing campaigns. It's highly recommended to use ePropertySeq and checkParallel to do this. The standalone executable is a pretty good example of recommended usage. fuzz can also be used, but if the predicate doesn't need IO, it's not recommended.

It also provides some convenience functions for writing custom campaigns (checkETest, cleanUp, eCommand, execCall.) The state machine example is a pretty good example of how to use these.

Echidna.Solidity

This module provides loadSolidity, which takes a solidity source file and provides a VM with the first contract therein loaded as well as a fuzz-compatible ABI definition. At the moment, it is only compatible with single-contract solidity files, though if given a multi-contract file it will load the first and print a warning.

Questions/complaints/etc.

Leave an issue or shoot me a line at jp@trailofbits.com