hera

README

Hera

Hera is an ewasm (revision 4) virtual machine implemented in C++ conforming to EVMC ABIv6.

It is designed to leverage various Wasm backends, both interpreters and AOT/JITs.

Building Hera

First clone this repository and make sure the submodules are checked out:

$ git clone https://github.com/ewasm/hera
$ cd hera
$ git submodule update --init

The preferred way is building Hera as a shared library:

$ mkdir build
$ cd build
$ cmake -DBUILD_SHARED_LIBS=ON ..
$ cmake --build .

In this case the built library will be placed at build/src/libhera/libhera.so on Linux or build/src/libhera/libhera.dylib on MacOS.

Please also check the build options listed in the following section.

Build options

• -DHERA_DEBUGGING=ON will turn on debugging features and messages
• -DBUILD_SHARED_LIBS=ON is a standard CMake option to build libraries as shared. This will build Hera shared library that can be then dynamically loaded by EVMC compatible Clients (e.g. aleth from [aleth]). This is the preferred way of compilation.

wabt support

Complete support.

wabt is built by default and needs no build options. It can be disabled with:

• -DHERA_WABT=OFF

Binaryen support

Complete support.

Binaryen support needs to be enabled via the following build option and requested at runtime with engine=binaryen:

• -DHERA_BINARYEN=ON will request the compilation of Binaryen support

WAVM support

Complete support.

WAVM support needs to be enabled via the following build option and requested at runtime with engine=wavm:

• -DHERA_WAVM=ON will request the compilation of WAVM support
• -DLLVM_DIR=... one will need to specify the path to LLVM's CMake file. In most installations this has to be within the lib/cmake/llvm directory, such as /usr/local/Cellar/llvm/6.0.1/lib/cmake/llvm on Homebrew.

Runtime options

These are to be used via EVMC set_option:

• engine=<engine> will select the underlying WebAssembly engine, where the only accepted values currently are binaryen, wabt, and wavm
• benchmark=true will produce execution timings and output it to both standard error output and hera_benchmarks.log file.

Interfaces

Hera implements two interfaces: EEI and a debugging module.

Debugging module

• ethereum::print32(value: i32) - print value
• ethereum::print64(value: i64) - print value
• ethereum::printMem(offset: i32, len: i32) - print memory segment as printable characters
• ethereum::printMemHex(offset: i32, len: i32) - print memory segment as hex
• ethereum::printStorage(pathOffset: i32) - print storage value as printable characters
• ethereum::printStorageHex(pathOffset: i32) - print storage value as hex

These are only enabled if Hera is compiled with debugging on.

Fuzzing

To enable fuzzing you need clang compiler and provide -DHERA_FUZZING=ON option to CMake. You should also enable both Binaryen and WABT engines. This will build additional executable hera-fuzzer. Check out its help and libFuzzer documentation.

test/fuzzing/hera-fuzzer -help=1

Author(s)

• Alex Beregszaszi
• Jake Lang

License

Apache 2.0

#WAVM install:

###LLVM 6.0 deb http://apt.llvm.org/zesty/ llvm-toolchain-zesty-6.0 main

wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key|sudo apt-key add -

apt-get install clang-6.0 lldb-6.0 lld-6.0

System deps

RUN apt-get update RUN apt-get install -y
autoconf
automake
build-essential
cmake
libtool
llvm-6.0
make __ ninja-build
sudo
unzip
zlib1g-dev

RUN apt-get clean autoclean RUN apt-get autoremove -y