EVM Tool
========

EVM Tool is a stand alone EVM executor and test execution tool. The
principal purpose of the tool is for testing and validation of the EVM
and enclosing data structures.

Using EVM Tool in execution-specification-tests
-----------------------------------------------

To use EVM Tool in Execution Spec tests it is recommended that you use
the GraalVM build, as the framework incurs significant startup penalties
for each invocation when run via the Java runtime.

### Building Execution Tests on macOS

Current as of 24 Jun 2023.

MacOS users will typically encounter two problems,one relating to the
version of Python used and one relating to zsh.

Homebrew will only install the most recent version of Python
as `python3`, and that is 3.11. The execution tests require 3.10. The
solution is to use a 3.10 version of python to set up the virtual
environment.

```zsh
python3.10 -m venv ./venv/
```

Zsh requires braces to be escaped in the command line, so the step to
install python packages needs to escape the brackets

```zsh
pip install -e .\[docs,lint,test\]
```

An all-in-one script, including homebrew, would look like

```zsh
brew install ethereum solidity
git clone https://github.com/ethereum/execution-spec-tests
cd execution-spec-tests
python3 -m venv ./venv/
source ./venv/bin/activate
pip install -e .[docs,lint,test]
```

### Building EvmTool with GraalVM on macOS

First you need a GraalVM JDK installed, if not already installed.

It is recommended you install [SDKMAN](https://sdkman.io/install) to
manage the graalVM install, homebrew has issues with native attributes
and code signing.

```zsh
sdk install java 22.3.r17-grl 
sdk use java 22.3.r17-grl
```

You can also manually install GraalVM from
the [GraalVM website](https://www.graalvm.org/downloads)..

Once GraalVM is installed you use the `nativeCompile` target.

```zsh
./gradlew nativeCompile 
```

The resulting binary
is `./ethereum/evmtool/build/native/nativeCompile/evmtool`

If the testing repository and besu are installed in the same parent
directory, the command to run the execution tests is

```zsh
fill -v tests --evm-bin ../besu/ethereum/evmtool/build/install/evmtool/bin/evm 
```

Assuming homebrew and SDKMan are both installed, the complete script is

```zsh
sdk install java 22.3.r17-grl 
sdk use java 22.3.r17-grl
git clone https://github.com/hyperledger/besu
cd besu
./gradlew nativeCompile
cd ..

brew install ethereum solidity
git clone https://github.com/ethereum/execution-spec-tests
cd execution-spec-tests
python3 -m venv ./venv/
source ./venv/bin/activate
pip install -e .[docs,lint,test]

fill -v tests --evm-bin ../besu/ethereum/evmtool/build/install/evmtool/bin/evm
```

If you don't want to use the GraalVM tool the binary that is compatible
is generated by the `ethereum:evmtool:installdist` target and is located
at `./ethereum/evmtool/build/install/evmtool/bin/evm`

Why not GraalVM for everything?
-------------------------------

Using GraalVM in execution-spec-tests results in over 20x performance
increase in execution. It will be faster to build GraalVM from scratch
and run the execution-spec-tests than to run just the Java version.

It is demonstrably faster to run the Java version for a node.
All the test execution gains are the result of reduced startup
penalties. Larger benchmarks will show that performance intensive EVM
code will be slower in GraalVM than the Java version due to the adaptive
compiler.

For contracts that execute 30 million gas in small operations it is
often faster to run the Java EVMTool than the GraalVM EVMTool, including
startup penalty. The execution tests focus on smaller VM tests that
demonstrate specification conformance.

We would also need to reconsider some library choices. GraalVM does not
work with Log4J, and we would have to ban that library across Besu and
all dependents. Libraries such as Netty also have some problematic entry
points that interact poorly with how SLF4J needs to initialize.