hera/README.md

Hera

Hera is an ewasm virtual machine implemented in C++ conforming to EVMC.

It can be used with cpp-ethereum and perhaps in the future with other implementations through appropriate bindings.

Currently it uses Binaryen's interpreter for running WebAssembly bytecode and it should be improved to support wabt and wavm as backends.

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. eth from cpp-ethereum).

Runtime options

These are to be used via EVM-C set_option:

• metering=true will enable metering of bytecode at deployment using the Sentinel system contract (set to false by default)
• evm2wasm=true will enable metering of bytecode at deployment using the EVM Transcompiler (set to false by default)
• fallback=true will allow EVM bytecode to be passed through to the client for execution (if set to false, the default, it will be rejected as invalid) (note: is ignored if evm2wasm is true)
• evm2wasm.js=true will use a evm2wasm.js as an external commandline tool instead of the system contract
• evm2wasm.js-trace=true will turn on EVM tracing for evm2wasm.js
• evm2wasm.cpp=true will use a evm2wasm as a compiled-in dependency instead of the system contract
• evm2wasm.cpp-trace=true will turn on EVM tracing for evm2wasm.cpp

Interfaces

Hera implements two interfaces: EEI and a debugging module.

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.

EVM Tracing

• debug::evmTrace(pc: i32, opcode: i32, cost: i32, sp: i32)

This is useful to trace the transpiled code from evm2wasm. This is only enabled if Hera is compiled with debugging on.

Note: it is valid to invoke evmTrace with a negative value for sp. In this case, no stack values will be printed.

Caveats

Although Hera enables the execution of eWASM bytecode, there are more elements to eWASM an Ethereum node must be aware of:

• backwards compatibility provisions
• injecting metering code to eWASM contracts
• transcompiling EVM1 contracts to eWASM if desired

All of the above must be implemented outside of Hera.

Author(s)

Alex Beregszaszi

License

MIT