zevem

Ethereum Virtual Machine (EVM) implemented in Zig – just the EVM.

zevem is primarily designed to be embedded into a host Ethereum client as a library but also plans to incorporate various developer-focused features like:

1. Bytecode debugger (with worldstate via EVMC if not library).
2. Bytecode (dis)assembler.
3. Solidity decompiler (NOTE: Extremely “maybe” since this will also require deep knowledge of how the Solidity compiler and it’s various versions likes to compile things etc).

Status

Pre-alpha work-in-progress. Currently only concerned about use within Phant as the first host client (and therefore real-world proof of zevem’s correct implementation etc). Contributions and ideation of course welcome (open an issue or contact via email for discussion beforehand please).

See zevem’s project planning file for TODOs, further resources etc.

Build / Develop / Contribute

The only real dependency is Zig 0.14.0, everything is developer tooling.

A justfile (see: Just) provides simpler access to common project commands. Execute just anywhere within this project repo to see a list of available commands, common ones are:

To build:

just build
# zig build

To run all tests:

just test
# zig build test

The justfile is configured (by default) to echo the commands it executes; it’s syntax is very readable however and is mostly a convenient alias for various Zig build-system commands.

Both just commands above accept zero or more additional parameters which are passed directly to the Zig build-system. Further build options (e.g. tracing, building the zevem cli) are at the top of build.zig.

Developer Environments / Tooling

The .jam directory includes a Containerfile (aka. Dockerfile) for container-based workflows. It is primarily written for use with Podman but should also work with Docker. It is currently written for macOS hosts running containers; i.e. an implicit Linux-VM which itself is actually managing containers.

The jam file (shell-script) at the repository root can be used to build/create/run development containers. These are not based on “Development Containers” from Micro$oft as that specification, amongst others, are JSON-plagued overly complicated hellscapes.

To build a container image with all zevem dependencies including extra utilities for general debugging:

./jam make

To create and run the built container image, replacing any that may exist:

./jam run

This repo’s files are bind-mounted into the container at /home/jammy/project so no work is lost when deleting/re-building/re-creating (etc) the container so long as you stick within that bind-mounted directory.

Tracing

Tracy is integrated and available by passing -Dtracy=true to just build or just test. If you alter Tracy versions do note that Tracy does not guarantee compatibility between any versions (even semver patch releases), thus exact matching versions must be used. Tracy provides tools to update older trace versions to newer ones amongst a lot more described in their PDF manual which can be found at the Tracy repo.

To get you started though: the instrumented application (i.e. zevem) is called the “client”, and the Tracy profiler the “server”. Instrumented clients gather and send trace information to the server at runtime over a network connection (local or wide, enabling remote profiling). Finally Tracy provides a GUI to explore trace information. The GUI also has an embedded server so it can receive trace information directly if preferred.

The easiest way to get started is to compile zevem with tracing, execute the Tracy capture utility capture, and then execute the zevem artifacts upon which a trace will be captured.