Awesome
Oyente
An Analysis Tool for Smart Contracts
This repository is currently maintained by Xiao Liang Yu (@yxliang01). If you encounter any bugs or usage issues, please feel free to create an issue on our issue tracker.
Quick Start
A container with required dependencies configured can be found here. The image is however outdated. We are working on pushing the latest image to dockerhub for your convenience. If you experience any issue with this image, please try to build a new docker image by pulling this codebase before open an issue.
To open the container, install docker and run:
docker pull luongnguyen/oyente && docker run -i -t luongnguyen/oyente
To evaluate the greeter contract inside the container, run:
cd /oyente/oyente && python oyente.py -s greeter.sol
and you are done!
Note - If need the version of Oyente referred to in the paper, run the container from here
To run the web interface, execute
docker run -w /oyente/web -p 3000:3000 oyente:latest ./bin/rails server
Custom Docker image build
docker build -t oyente .
docker run -it -p 3000:3000 -e "OYENTE=/oyente/oyente" oyente:latest
Open a web browser to http://localhost:3000
for the graphical interface.
Installation
Execute a python virtualenv
python -m virtualenv env
source env/bin/activate
Install Oyente via pip:
$ pip2 install oyente
Dependencies:
The following require a Linux system to fufill. macOS instructions forthcoming.
Full installation
Install the following dependencies
solc
$ sudo add-apt-repository ppa:ethereum/ethereum
$ sudo apt-get update
$ sudo apt-get install solc
evm from go-ethereum
- https://geth.ethereum.org/downloads/ or
- By from PPA if your using Ubuntu
$ sudo apt-get install software-properties-common
$ sudo add-apt-repository -y ppa:ethereum/ethereum
$ sudo apt-get update
$ sudo apt-get install ethereum
z3 Theorem Prover version 4.5.0.
Download the source code of version z3-4.5.0
Install z3 using Python bindings
$ python scripts/mk_make.py --python
$ cd build
$ make
$ sudo make install
Requests library
pip install requests
web3 library
pip install web3
Evaluating Ethereum Contracts
#evaluate a local solidity contract
python oyente.py -s <contract filename>
#evaluate a local solidity with option -a to verify assertions in the contract
python oyente.py -a -s <contract filename>
#evaluate a local evm contract
python oyente.py -s <contract filename> -b
#evaluate a remote contract
python oyente.py -ru https://gist.githubusercontent.com/loiluu/d0eb34d473e421df12b38c12a7423a61/raw/2415b3fb782f5d286777e0bcebc57812ce3786da/puzzle.sol
And that's it! Run python oyente.py --help
for a list of options.
Paper
The accompanying paper explaining the bugs detected by the tool can be found here.
Miscellaneous Utilities
A collection of the utilities that were developed for the paper are in misc_utils
. Use them at your own risk - they have mostly been disposable.
generate-graphs.py
- Contains a number of functions to get statistics from contracts.get_source.py
- The get_contract_code function can be used to retrieve contract source from EtherScantransaction_scrape.py
- Contains functions to retrieve up-to-date transaction information for a particular contract.
Benchmarks
Note: This is an improved version of the tool used for the paper. Benchmarks are not for direct comparison.
To run the benchmarks, it is best to use the docker container as it includes the blockchain snapshot necessary.
In the container, run batch_run.py
after activating the virtualenv. Results are in results.json
once the benchmark completes.
The benchmarks take a long time and a lot of RAM in any but the largest of clusters, beware.
Some analytics regarding the number of contracts tested, number of contracts analysed etc. is collected when running this benchmark.
Contributing
Checkout out our contribution guide and the code structure here.