Hera: Ewasm virtual machine conforming to the EVMC API
It is designed to leverage various Wasm backends, both interpreters and AOT/JITs.
First clone this repository and make sure the submodules are checked out:
bash $ 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.soon Linux or
Please also check the build options listed in the following section.
-DHERA_DEBUGGING=ONwill turn on debugging features and messages. This is off by default.
-DBUILD_SHARED_LIBS=ONis 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.
alethfrom aleth). This is the preferred way of compilation.
wabt is built by default and needs no build options. It can be disabled with:
Binaryen support needs to be enabled via the following build option and requested at runtime with
-DHERA_BINARYEN=ONwill request the compilation of Binaryen support
WAVM support needs to be enabled via the following build option and requested at runtime with
-DHERA_WAVM=ONwill 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/llvmdirectory, such as
These are to be used via EVMC
engine=will select the underlying WebAssembly engine, where the only accepted values currently are
metering=truewill enable metering of bytecode at deployment using the Sentinel system contract
benchmark=truewill produce execution timings and output it to both standard error output and
evm1mode=will select how EVM1 bytecode is handled
sys:=file.wasmwill override the code executing at the specified address with code loaded from a filepath at runtime. This option supports aliases for system contracts as well, such that
sys:evm2wasm=file.wasmare both valid. This option is intended for debugging purposes.
rejectwill reject any EVM1 bytecode with an error (the default setting)
fallbackwill allow EVM1 bytecode to be passed through to the client for execution
evm2wasmwill enable transformation of bytecode using the EVM Transcompiler
runevmwill transform EVM1 bytecode using runevm
Hera implements two interfaces: EEI and a debugging module.
debug::print32(value: i32)- print value
debug::print64(value: i64)- print value
debug::printMem(offset: i32, len: i32)- print memory segment as printable characters
debug::printMemHex(offset: i32, len: i32)- print memory segment as hex
debug::printStorage(pathOffset: i32)- print storage value as printable characters
debug::printStorageHex(pathOffset: i32)- print storage value as hex
These are only enabled if Hera is compiled with debugging on.
debug::evmTrace(pc: i32, opcode: i32, cost: i32, sp: i32)
This is useful to trace the translated code by EVM Transcompiler. This is only enabled if Hera is compiled with debugging on.
Note: it is valid to invoke
evmTracewith a negative value for
sp. In this case, no stack values will be printed.
To enable fuzzing you need clang compiler and provide
-DHERA_FUZZING=ONoption 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.