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 Manticore and Echidna on large, multi-contract projects. In particular, custom Manticore analysis scripts require less code, are simpler to write, and integrate with Truffle.
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. For example, Etheno is capable of automatically reproducing the Constantinople gas usage consensus bug that caused a fork on Ropsten.
- JSON RPC Multiplexing: Etheno runs a JSON RPC server that can multiplex calls to one or more clients
- API for filtering and modifying JSON RPC calls
- Enables differential testing by sending JSON RPC sequences to multiple Ethereum clients
- Deploy to and interact with multiple networks at the same time
- Analysis Tool Wrapper: Etheno provides a JSON RPC client for advanced analysis tools like Manticore
- Lowers barrier to entry for using advanced analysis tools
- No need for custom scripts to set up account and contract state
- Analyze arbitrary transactions without Solidity source code
- Integration with Test Frameworks like Ganache and Truffle
- Run a local test network with a single command
- Use Truffle migrations to bootstrap Manticore analyses
- Symbolic semantic annotations within unit tests
Use our prebuilt Docker container to quickly install and try Etheno:
docker pull trailofbits/etheno docker run -it trailofbits/etheno # Run one of the examples etheno@982abdc96791:~$ cd examples/BrokenMetaCoin/ etheno@982abdc96791:~/examples/BrokenMetaCoin$ etheno --truffle --ganache --manticore --manticore-max-depth 2 --manticore-script ExploitMetaCoinManticoreScript.py
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 --manticore --ganache --truffle
Etheno can be used in many different ways and therefore has numerous command-line argument combinations.
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/
-pallows you to specify a port on which to run Etheno’s JSON RPC server (default is 8545)
--run-publiclyallows incoming JSON RPC connections from external computers on the network
--debugwill run a web-based interactive debugger in the event that an internal Etheno client throws an exception while processing a JSON RPC call; this should never be used in conjunction with
-swill set the “master” client, which will be used for synchronizing with Etheno clients like Manticore. If a master is not explicitly provided, it defaults to the first client listed.
--raw, when prefixed before a client URL, will cause Etheno to auto-sign all transactions and submit then to the client as raw transactions
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
-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
The network ID of each client will default to 0x657468656E6F (equal to the string
etheno in ASCII). This can be overridden with the
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
A Ganache instance can automatically be run within Etheno:
--ganache-portwill set the port on which Ganache is run; if omitted, Etheno will choose the lowest port higher than the port on which Etheno’s JSON RPC server is running
--ganache-argslets you pass additional arguments to Ganache
-asets the number of accounts to create in Ganache (default is 10)
-bsets the default balance (in Ether) to seed to each Ganache account (default is 100.0)
-csets the default gas price for Ganache (default is 20000000000)
NOTE: As of September, 2020, there is
an upstream bug in
ganache-cli that prevents it from being run on Node version 14.
If you intend to use Truffle and/or Ganache, we suggest using Node 12 (e.g.,
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
Property-Based Fuzz Testing
Echidna can be run to fuzz test the clients, which is useful for differential testing:
By default, Echidna deploys a generic fuzz testing contract to all clients, enumerates a minimal set of transactions that maximize the coverage of the contract, sends those transactions to the clients, and then exits.
--fuzz-limitlimits the number of transactions that Echidna will emit
--fuzz-contractlets the user specify a custom contract for Echidna to deploy and fuzz
Manticore—which, by itself, does not implement a JSON RPC interface—can be run as an Etheno client, synchronizing its accounts with Etheno’s master client and symbolically executing all transactions sent to Etheno.
This alone will not run any Manticore analyses; they must either be run manually, or automated through the
--manticore-verbositysets Manticore’s logging verbosity (default is 3)
--manticore-max-depthsets the maximum state depth for Manticore to explore; if omitted, Manticore will have no depth limit
Truffle migrations can automatically be run within a Truffle project:
When combined with the
--manticore option, this will automatically run Manticore’s default analyses on all contracts created once the Truffle migration completes:
etheno --truffle --manticore
This requires a master JSON RPC client, so will most often be used in conjunction with Ganache. If a local Ganache server is not running, you can simply add that to the command:
etheno --truffle --manticore --ganache
If you would like to run a custom Manticore script instead of the standard Manticore analysis and detectors, it can be specified using the
This script does not need to import Manticore or create a
ManticoreEVM object; Etheno will run the script with a global variable called
manticore that already contains all of the accounts and contracts automatically provisioned. See the
BrokenMetaCoin Manticore script for an example.
Additional arguments can be passed to Truffle using
By default, Etheno only prints log messages to the console with a log
level defaulting to
INFO. An alternative log level can be specified
-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
- a complete log file including log messages at all log levels;
- separate log files for each Etheno client and plugin;
- the genesis file used to instantiate clients;
- a subdirectory in which each client and plugin can store additional files such as test results;
- a script to re-run Geth and/or Parity using the same genesis and chain data that Etheno used.
- Python 3.6 or newer
- Manticore release 0.2.2 or newer
- Flask, which is used to run the JSON RPC server
- Truffle and Ganache for their associated integrations
- Geth and/or Parity, if you would like to have Etheno run them
- Echidna, for smart contract fuzzing and differential testing
Feel free to stop by our Slack channel for help on using or extending Etheno.
Documentation is available in several places:
The wiki contains some basic information about getting started with Etheno and contributing
The examples directory has some very minimal examples that showcase API features