{"id":13759578,"url":"https://github.com/crytic/etheno","last_synced_at":"2025-12-09T21:30:15.585Z","repository":{"id":37451387,"uuid":"138937540","full_name":"crytic/etheno","owner":"crytic","description":"Simplify Ethereum security analysis and testing","archived":false,"fork":false,"pushed_at":"2023-06-29T20:51:18.000Z","size":751,"stargazers_count":339,"open_issues_count":37,"forks_count":32,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-02-12T12:14:01.454Z","etag":null,"topics":["differential-testing","ethereum","ganache","solidity","symbolic-execution","truffle"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crytic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-06-27T22:03:53.000Z","updated_at":"2025-01-24T09:46:59.000Z","dependencies_parsed_at":"2023-02-09T02:16:19.885Z","dependency_job_id":"51e251b2-abaa-42e1-81f0-06ca0163f795","html_url":"https://github.com/crytic/etheno","commit_stats":{"total_commits":380,"total_committers":16,"mean_commits":23.75,"dds":0.2710526315789473,"last_synced_commit":"fbac64189067e070c68b7084d13cf244ca8793ad"},"previous_names":["trailofbits/etheno"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crytic%2Fetheno","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crytic%2Fetheno/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crytic%2Fetheno/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crytic%2Fetheno/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crytic","download_url":"https://codeload.github.com/crytic/etheno/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239671422,"owners_count":19677872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["differential-testing","ethereum","ganache","solidity","symbolic-execution","truffle"],"created_at":"2024-08-03T13:00:55.651Z","updated_at":"2025-12-09T21:30:15.526Z","avatar_url":"https://github.com/crytic.png","language":"Python","funding_links":[],"categories":["dApps directory","Tools"],"sub_categories":["Fuzzing Tools"],"readme":"The repo is now archived. Use [medusa](https://github.com/crytic/medusa) for fuzzing. To learn more: https://secure-contracts.com/\n\n\n# Etheno\n[![Slack Status](https://slack.empirehacking.nyc/badge.svg)](https://slack.empirehacking.nyc)\n[![PyPI version](https://badge.fury.io/py/etheno.svg)](https://badge.fury.io/py/etheno)\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo/etheno.png?raw=true\" width=\"256\" title=\"Etheno\"\u003e\n\u003c/p\u003e\n\u003cbr /\u003e\n\n\nEtheno 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](https://github.com/trailofbits/echidna) on large, multi-contract projects.\n\nIf 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.\n\nEtheno is named after the Greek goddess [Stheno](https://en.wikipedia.org/wiki/Stheno), sister of Medusa, and mother of Echidna—which also happens to be the name of [our EVM property-based fuzz tester](https://github.com/trailofbits/echidna).\n\n## Features\n\n* **JSON RPC Multiplexing**: Etheno runs a JSON RPC server that can multiplex calls to one or more clients\n  * API for filtering and modifying JSON RPC calls\n  * Enables differential testing by sending JSON RPC sequences to multiple Ethereum clients\n  * Deploy to and interact with multiple networks at the same time\n* **Integration with Test Frameworks** like Ganache and Truffle\n  * Run a local test network with a single command\n\n## Quickstart\n\nUse our prebuilt Docker container to quickly install and try Etheno:\n\n```\ndocker pull trailofbits/etheno\ndocker run -it trailofbits/etheno\n```\n\n**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.\n- To learn about publishing ports, click [here](https://docs.docker.com/storage/volumes/)\n- To learn more about persisting data using volumes, click [here](https://docs.docker.com/storage/volumes/)\n\n\nAlternatively, natively install Etheno in a few shell commands:\n\n```\n# Install system dependencies\nsudo apt-get update \u0026\u0026 sudo apt-get install python3 python3-pip -y\n\n# Install Etheno\npip3 install --user etheno\n\n# Use the Etheno CLI\ncd /path/to/a/truffle/project\netheno --ganache --truffle\n```\n\n## Usage\n\nEtheno can be used in many different ways and therefore has numerous command-line argument combinations.\n\n### Ganache Integration\n\nA Ganache instance can automatically be run within Etheno:\n```\netheno --ganache\n```\n\n* `--ganache-port` will 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\n* `--ganache-args` lets you pass additional arguments to Ganache\n* `--accounts` or `-a` sets the number of accounts to create in Ganache (default is 10)\n* `--balance` or `-b` sets the default balance (in Ether) to seed to each Ganache account (default is 1000.0)\n* `--gas-price` or `-c` sets the default gas price in wei for Ganache (default is 20_000_000_000)\n\nRunning 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](https://github.com/crytic/building-secure-contracts/blob/master/program-analysis/echidna/end-to-end-testing.md).\n\n\n**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.\n\n\n**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). \n\n\n### JSON RPC Server and Multiplexing\n\nThis command starts a JSON RPC server and forwards all messages to the given clients:\n\n```\netheno https://client1.url.com:1234/ https://client2.url.com:8545/ http://client3.url.com:8888/\n```\n\n* `--port` or `-p` allows you to specify a port on which to run Etheno’s JSON RPC server (default is 8545)\n* `--run-publicly` allows incoming JSON RPC connections from external computers on the network\n* `--debug` will 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 `--run-publicly`\n* `--master` or `-s` will set the “master” client, which will be used for synchronizing with Etheno clients. If a master is not explicitly provided, it defaults to the first client listed.\n* `--raw`, when prefixed before a client URL, will cause Etheno to auto-sign all transactions and submit them to the client as raw transactions\n\n### Geth and Parity Integration\n\nA Geth and/or Parity instance can be run as a private chain with\n* `--geth` or `-go` for Geth\n* `--parity` or `-pa` for Parity\n\nEach 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.\n\nThe 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.\n\nEIP 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`.\n\n### Differential Testing\n\nWhenever two or more clients are run within Etheno, the differential\ntesting plugin will automatically be loaded. This plugin checks for a\nvariety of different discrepancies between the clients, such as gas\nusage differences. A report is printed when Etheno exits.\n\nThis plugin can be disabled with the `--no-differential-testing` option.\n\n### Truffle Integration\n\nTruffle migrations can automatically be run within a Truffle project:\n```\netheno --truffle\n```\n\nAdditional arguments can be passed to Truffle using `--truffle-args`.\n\n### Logging\n\nBy default, Etheno only prints log messages to the console with a log\nlevel defaulting to `INFO`. An alternative log level can be specified\nwith `--log-level` or `-l`.  You can specify a log file with the\n`--log-file` option. In addition, you can provide the path to a\nlogging directory with `--log-dir` in which the following will be\nsaved:\n* a complete log file including log messages at all log levels;\n* separate log files for each Etheno client and plugin;\n* the genesis file used to instantiate clients;\n* a subdirectory in which each client and plugin can store additional files such as test results;\n* a script to re-run Geth and/or Parity using the same genesis and chain data that Etheno used.\n\n## Requirements\n\n* Python 3.7 or newer \n\n### Optional Requirements\n* [Node](https://nodejs.org/en/) 16.x or newer to install various integrations\n* [Ganache](https://www.npmjs.com/package/ganache) 7.3.2 or newer for its associated integrations\n* [Truffle](https://www.npmjs.com/package/truffle) for its associated integrations\n* [Geth](https://github.com/ethereum/go-ethereum) and/or [Parity](https://github.com/paritytech/parity-ethereum), if you would like to have Etheno run them\n\n## Getting Help\n\nFeel free to stop by our [Slack channel](https://empirehacking.slack.com/) for help on using or extending Etheno.\n\n## License\n\nEtheno is licensed and distributed under the [AGPLv3](LICENSE) license. [Contact us](mailto:opensource@trailofbits.com) if you’re looking for an exception to the terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrytic%2Fetheno","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrytic%2Fetheno","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrytic%2Fetheno/lists"}