Skip to main content

Ethereum EVM utilities

Project description

EVM lab utilities

This package contains various tools to interact with the Ethereum virtual machine.

Project Structure

Folder Description
docs Project documentation
evmlab The evmlab package
utilities Example utilities and proof-of-concepts
files Sample trace files and trace logs
output output directory for artefacts
templates Web application templates (currently used with reproducer)
containers Docker container files


From source:

Consider creating a virtualenv.

#> virtualenv -p python3 .env3
#> . .env3/bin/activate
#> python3 -m pip install -r requirements.txt
#> python3 install
#> python3 -m evmlab  # verify installation

From PIP:

TODO: publish to pip!

#> python3 -m pip install evmlab
#> python3 -m evmlab[consolegui,abidecoder,docker]  # verify installation

EVMLab comes with a commandline utility that can be invoked by calling python3 -m evmlab <subcommand> <args>


The 'compiler' is a tool to build evm binaries, using a pythonic way to construct the programs using assembly.

Here's an example that tests ecdsaRecover:

	p = compiler.Program()
	p.mstore(0 ,0x38d18acb67d25c8bb9942764b62f18e17054f66a817bd4295423adf9ed98873e)
	v = 0x000000000000000000000000000000000000000000000000000000000000001b
	p.mstore(32   , v)
	p.mstore(64   ,0x723841761d213b60ac1cbf063207cbeba6c2725bcaf7c189e63f13d93fc1dc07)
	p.mstore(96   ,0x789d1dd423d25f0772d2748d60f7e4b81bb14d086eba8e8e8efb6dcff8a4ae02),1,0,0,0x80,0x80,0x20)
	code = p.bytecode()

Here's an example of stuffing JUMPDEST into a program:

	p = compiler.Program()
	for i in range(0,20000):

	return p.bytecode()


The vm module contais some abstractions to run arbitrary virtual machines, primarily geth evm and parity's parity-evm.


The etherchain package contains an API for interacting with the Etherchain API.


An example app is which can reproduce an on-chain transaction as a totally local event, and run it in the evm.

The app takes a txhash, and

  1. Fetch the transaction data from an API.
  2. Mark (source, destination) as need-to-fetch
  3. Fetch balance and nonce at source, add to genesis
  4. Execute transaction on the evm
  5. If transaction has any externally reaching ops (BALANCE, EXTCODECOPY, CALL etc),
  • Add those accounts as need-to-fetch
  1. Go back to 3 until the execution does not result in any more accounts to be fetched.
  2. Save the transaction trace and genesis


The '' is a simple debugger-like trace-viewer. It can be used against an evm-trace and navigate the data in a bit more friendly manner than raw json. Invoke via e.g. python -f example2.json


Running it

The easiest way to get it working is to use a docker image.

docker build . -t evmlab && docker run -it evmlab

The docker image should also be available at, as an automated build:

docker pull holiman/evmlab && docker run -it holiman/evmlab


EVM format

Here's what to think about if you want to add an evm to evmlab.


The evm should take the following inputs:

  • --code <code> - code to be executed.
  • --codeFile <file> - file containing code to be executed. Sometimes really large chunks of input cannot be passed through bash.
  • --gas <int>
  • --price <int>
  • --sender <address> - address of ORIGIN
  • --receiver <address - address of ADDRESS
  • --input <code> : CALLDATA
  • --value <int>
  • --json - boolean flag, output json output for each opcode or not (it's useful to disable json when benchmarking)
  • --nomemory - disable showing the full memory output for each op
  • --create - if specified, it's executed as initcode
  • --prestate - a chain specification, the same one that the client normally would use.

Basically, the evm should be able to run things very simply, like so:

$evm --code 6040 --json run

But it should also be able to reconstruct an actual on-chain transaction, with complex options including prestate, where no code is passed, since it's already been showed into the prestate:

$evm --prestate /home/martin/workspace/evmlab/output//0xd6d519-genesis-geth_wq38zsy5.json --gas 150000 --sender 0x69ea6b31ef305d6b99bb2d4c9d99456fa108b02a --receiver 0xb97048628db6b661d4c2aa833e95dbe1a905b280 --input a9059cbb0000000000000000000000008eef795fd9150f118bddeca556a5a2a2438ab865000000000000000000000000000000000000000000000081ebd8ffd6b2a58000 --json run


The evm should output a json object for each operation. Example:


Required: pc, op, gas, stack, depth Optional: opName, gasCost, error

The stack, memory and memSize are the values before execution of the op.

At the end of execution, some summarical info is good, e.g.


When errors occur, geth and parity handles them differently.

Minor changes to how things work is ok, we can handle discrepancies in format and minor quirks.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Evmlab- (42.9 kB view hashes)

Uploaded Source

Built Distribution

Evmlab- (48.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page