Home

Awesome

Etheno

Slack Status PyPI version

<p align="center"> <img src="logo/etheno.png?raw=true" width="256" title="Etheno"> </p> <br />

Etheno is the Ethereum testing Swiss Army knife. It’s a JSON RPC multiplexer, analysis tool wrapper, and test integration tool. It eliminates the complexity of setting up analysis tools like Echidna on large, multi-contract projects.

If you are a smart contract developer, you should use Etheno to test your contracts. If you are an Ethereum client developer, you should use Etheno to perform differential testing on your implementation.

Etheno is named after the Greek goddess Stheno, sister of Medusa, and mother of Echidna—which also happens to be the name of our EVM property-based fuzz tester.

Features

Quickstart

Use our prebuilt Docker container to quickly install and try Etheno:

docker pull trailofbits/etheno
docker run -it trailofbits/etheno

NOTE: Many of Etheno's capabilities will require publishing one or more ports and persisting data using volumes as part of the docker run command.

Alternatively, natively install Etheno in a few shell commands:

# Install system dependencies
sudo apt-get update && sudo apt-get install python3 python3-pip -y

# Install Etheno
pip3 install --user etheno

# Use the Etheno CLI
cd /path/to/a/truffle/project
etheno --ganache --truffle

Usage

Etheno can be used in many different ways and therefore has numerous command-line argument combinations.

Ganache Integration

A Ganache instance can automatically be run within Etheno:

etheno --ganache

Running a Ganache instance via Etheno can be used to deploy large, multi-contract projects in tandem with Echidna. To learn more on how to use Echidna and Ganache together, click here.

NOTE: We recommend using the latest version of Ganache (v7.3.2) and Node 16.x. After the upstream bug (see below) is fixed, the Ganache package should be upgraded.

NOTE: Currently, there is an upstream bug in the latest version of Ganache (v7.3.2) that prevents the Etheno integration from working if the contract size that is being tested is very large (https://github.com/trufflesuite/ganache/issues/3332).

JSON RPC Server and Multiplexing

This command starts a JSON RPC server and forwards all messages to the given clients:

etheno https://client1.url.com:1234/ https://client2.url.com:8545/ http://client3.url.com:8888/

Geth and Parity Integration

A Geth and/or Parity instance can be run as a private chain with

Each will be instantiated with an autogenerated genesis block. You may provide a custom genesis.json file in Geth format using the --genesis or -j argument. The genesis used for each run will automatically be saved to the log directory (if one is provided using the --log-dir option), or it can be manually saved to a location provided with the --save-genesis option.

The network ID of each client will default to 0x657468656E6F (equal to the string etheno in ASCII). This can be overridden with the --network-id or -i option.

EIP and hard fork block numbers can be set within a custom genesis.json as usual, or they may be specified as command-line options such as --constantinople.

Differential Testing

Whenever two or more clients are run within Etheno, the differential testing plugin will automatically be loaded. This plugin checks for a variety of different discrepancies between the clients, such as gas usage differences. A report is printed when Etheno exits.

This plugin can be disabled with the --no-differential-testing option.

Truffle Integration

Truffle migrations can automatically be run within a Truffle project:

etheno --truffle

Additional arguments can be passed to Truffle using --truffle-args.

Logging

By default, Etheno only prints log messages to the console with a log level defaulting to INFO. An alternative log level can be specified with --log-level or -l. You can specify a log file with the --log-file option. In addition, you can provide the path to a logging directory with --log-dir in which the following will be saved:

Requirements

Optional Requirements

Getting Help

Feel free to stop by our Slack channel for help on using or extending Etheno.

License

Etheno is licensed and distributed under the AGPLv3 license. Contact us if you’re looking for an exception to the terms.