EVM

Fast assembler, disassembler, execution, and testing for the Ethereum Virtual Machine (EVM) supporting expressive syntax.

Installation

Dependencies

libcurl is required to build dio.

macOS: already installed by default
Arch Linux: sudo pacman -S curl
Debian/Ubuntu: sudo apt-get install libcurl4-openssl-dev
RHEL/CentOS/Fedora: sudo dnf install libcurl-devel

Build from source

git clone https://github.com/wjmelements/evm.git
cd evm
make bin/evm bin/dio
# Append bin/ to your $PATH
export PATH=$PATH:$pwd/bin
# Install
echo -n PATH='$PATH:' >> ~/.bashrc
echo $pwd/bin' >> ~/.bashrc
source ~/.bashrc

Usage

Assembler

# Optional function-syntax
$ cat echo.evm
CALLDATACOPY(RETURNDATASIZE, RETURNDATASIZE, CALLDATASIZE)
RETURN(RETURNDATASIZE, CALLDATASIZE)
# Outputs evm bytecode
$ evm echo.evm
363d3d37363df3
# Wrap the minimum viable constructor with -c
$ evm -c echo.evm
66363d3d37363df33d5260076019f3
# Labels are lowercase, opcodes are uppercase
$ cat infinite.evm
start:
JUMP(start)
$ evm infinite.evm
5b600056
# Use decimal and hexadecimal constants directly without explicitly specifying PUSHx width
$ cat add.evm
MSTORE(RETURNDATASIZE,ADD(CALLDATALOAD(RETURNDATASIZE),CALLDATALOAD(32)))
RETURN(RETURNDATASIZE,0x20)
$ evm add.evm
6020353d35013d5260203df3
# Can read from stdin
$ cat add.evm | evm
6020353d35013d5260203df3

More examples can be found in the tst/in directory.

Data section

Besides instructions, you can inline raw data into the program using a data section, delimited with {}. Data section items are labeled and comma-separated. The location of a data section item can be accessed in the assembly by its label. The size of a data section item can be accessed in the code with #. Thereby, you can CODECOPY such data into memory.

CODECOPY(0, child, #child)
MSTORE(0, CREATE(0, #child))
RETURN(0, 32)
{
    child: construct child.evm
}

Item Type	Example Item	Example Data
Hex	`balanceof: 0x70a08231`	`70a08231`
String	`hello: "Hello, world!"`	`48656c6c6f2c20776f726c6421`
Assembly	`selfdestruct: assemble tst/in/selfdestruct.evm`	`33ff`
Construct	`constructor: construct tst/in/selfdestruct.evm`	`6133ff3d526002601ef3`

Disassembler

$ cat selfdestruct.out
33ff
# Outputs valid assembly
$ evm -d selfdestruct.out
SELFDESTRUCT(CALLER)
# Can read from stdin
$ cat selfdestruct.out | evm -d
SELFDESTRUCT(CALLER)

EVM Execution

$ cat quine.evm
CODECOPY(
    RETURNDATASIZE,
    RETURNDATASIZE,
    CODESIZE
)
RETURN(
    RETURNDATASIZE,
    CODESIZE
)
# Executes the code and outputs the returndata
$ evm -c quine.evm | evm -x
383d3d39383df3
$ evm -c quine.evm | evm -x | evm -d
CODECOPY(RETURNDATASIZE,RETURNDATASIZE,CODESIZE)
RETURN(RETURNDATASIZE,CODESIZE)

Configuration (Dio)

By using -w config.json, you can define the precondition state before execution. The recommended way to generate this is bin/dio, which snapshots live chain state; see On-chain state below.

[
    {
        "address": "0x80d9b122dc3a16fdc41f96cf010ffe7e38d227c3",
        "nonce": "0x",
        "code": "0x383d3d39383df3",
        "storage": {
            "0x00" : "0xf1ecf98489fa9ed60a664fc4998db699cfa39d40",
            "0x01" : "0x01"
        }
    }
]

Account configuration fields are optional and default to zero. If you exclude address, one will be generated for you.

Besides declaring code, contracts can be constructed from assembly source. If code is also supplied for the entry, the code will be used to verify the result of the constructor.

Dio Key	Description	Example Values	Default Value or Behavior
`address`	address for the account	`0x83F20F44975D03b1b09e64809B757c47f942BEeA`
`balance`	value in the account	`0xde0b6b3a7640000`	`0x0`
`nonce`	nonce of the account	`0x1`	`0x0`
`storage`	account storage	`{"0x1":"0x115eec47f6cf7e35000000"}`	`{}`
`creator`	address of the account creating this contract	`0x3249936bDdF8bF739d3f06d26C40EEfC81029BD1`	`0x0000000000000000000000000000000000000000`
`initcode`	account creation code	`0x383d3d39383df3`, `tst/in/quine.evm`	`code` mocked without constructor
`construct`	specify `initcode` as minimum constructor of file	`tst/in/quine.evm`	`initcode`
`constructTest`	test constructor execution; shares fields of `tests` entries	`{"gasUsed": "0xd583"}`	none
`code`	account code ; validated if `initcode` specified	`0x383d3d39383df3`, `tst/in/quine.evm`	`0x`
`import`	load another configuration	`tst/quine.json`
`tests`	transactions executed sequentially, after account configuration	[ { "input": "0x18160ddd", "output": "0x115eec47f6cf7e35000000" } ]	`[]`

See the next section for test configuration.

On-chain state (`bin/dio`)

dio drives evm -nx against a real node and emits a -w config JSON capturing every account, balance, nonce, code, and storage slot the call touched. That config then replays offline and deterministically with evm -w. dio links libcurl and execs the evm binary at runtime, so build both (make bin/evm bin/dio).

# provider URL positionally, or via $ETH_RPC_URL
echo '{"to":"0x6b175474e89094c44da98b954eedeac495271d0f","data":"0x18160ddd"}' \
    | dio https://mainnet.infura.io/v3/KEY | jq

# write to a file instead of stdout
export ETH_RPC_URL=https://mainnet.infura.io/v3/KEY
dio $ETH_RPC_URL dai.json < call.json

# CREATE: omit "to"; with "from" the deployed address is derived from from+nonce
echo '{"from":"0xd8da6bf26964af9d7eed9e03e53415d37aa96045","data":"0x<initcode>"}' | dio $ETH_RPC_URL

The call JSON comes from -o, file arguments, or stdin, and may be a single object or an array of them. Each object becomes a tests entry (or constructTest, for a CREATE) on the generated account.

Call JSON key	Meaning	Default
`to`	contract called; omit for a CREATE	(CREATE)
`from`	`msg.sender` / deployer	`0x00…00`
`data` / `input`	calldata, or initcode when `to` is omitted	`0x`
`value`	wei sent with the call	`0x0`
`block`	`latest`, or a `0x`-prefixed hex block number, to pin state to	`latest`

dio argument	Meaning
1st positional	provider URL (`http(s)://` or `ws(s)://`); falls back to `$ETH_RPC_URL`
2nd positional	output file (default: stdout)
more positionals	files of call JSON to read
`-o <json>`	call JSON inline instead of stdin/file
`-h`, `--help`	usage

Testing

[
    {
        "construct": "tst/in/quine.evm",
        "code": "0x383d3d39383df3",
        "tests": [
            {
                "name": "ignores calldata",
                "input": "0xdeadbeef",
                "output": "0x383d3d39383df3"
            }
        ]
    }
]

Run unit tests with tests entries. All -w output goes to stderr, while -x output goes to stdout.

evm -w tst/quine.json

# tst/in/quine.evm
ignores calldata: pass

Test Key	Description	Example Value	Default Value or Behavior
`name`	label for the test case	`"decimals() = 18"`	index of the testcase
`input`	`msg.data`	`0x313ce567`	`0x`
`value`	`msg.value`	`0x38d7ea4c68000`	`0x0`
`from`	`tx.origin`	`0xd1236a6A111879d9862f8374BA15344b6B233Fbd`	`0x0000000000000000000000000000000000000000`
`gas`	`tx.gasLimit`	`0x5208`	`0xffffffffffffffff`
`op`	type of call	`STATICCALL`	`CALL`
`to`	account called	`0x83F20F44975D03b1b09e64809B757c47f942BEeA`	account `address`
`status`	expected return status	`0x0` (revert)	`0x1` (success)
`output`	expected return or revert data	`0x0000000000000000000000000000000000000000000000000000000000000012`	ignored
`logs`	expected logs by account	{ "0x6b175474e89094c44da98b954eedeac495271d0f": [ { "topics": [ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", "0xae461ca67b15dc8dc81ce7615e0320da1a9ab8d5", "0x650c1c32c383290a300ff952d2a1d238ee08e62f" ], "data": "0x000000000000000000000000000000000000000000000000000717500b588103" } ] }	ignored
`gasUsed`	expected gas used	`0x5208`	ignored
`accessList`	EIP-2929	`[{"0x22d8432cc7aa4f8712a655fc4cdfb1baec29fca9":["0x6"]}]`	`{}`
`blockNumber`	`block.number`	`0x1312d00`	`0x13a2228`
`timestamp`	`block.timestamp`	`0x68255820`	`0x65712600`
`debug`	debug flags	`0x20`	`0x0`

The current debug flags:

Debug Flag	Description
0x1	Stack
0x2	Memory
0x4	Opcodes
0x8	Gas
0x10	PC
0x20	Calls
0x40	Logs

Update Config

A gasUsed test field can be supplied (or updated) in-place with -u

evm -uw tst/quine.json
git diff tst/quine.json

diff --git a/tst/quine.json b/tst/quine.json
index 361c65f..1e8a9f4 100644
--- a/tst/quine.json
+++ b/tst/quine.json
@@ -5,6 +5,7 @@
         "tests": [
             {
                 "name": "ignores calldata",
+                "gasUsed": "0x525b",
                 "input": "0xdeadbeef",
                 "output": "0x383d3d39383df3"
             }

JSON Output

Using any of the following -x options will output JSON instead of the returndata. The JSON will always contain the returndata but other outputs can be specified.

-g: gasUsed
-l: logs
-s: status

Network mode (`-nx`)

evm -nx executes against live chain state. Rather than declaring every touched account and storage slot up front with -w, the interpreter fetches them on demand. Each fetch is a JSON-RPC request written to stdout; the matching response is read back from stdin.

evm never opens a socket itself. Use dio to forward requests to an Ethereum RPC.

The bytecode input becomes a JSON call object (the eth_call shape), one per line, each sharing the same EVM state:

{"to":"0x6b175474e89094c44da98b954eedeac495271d0f","from":"0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266","data":"0x18160ddd"}

Omit to to deploy data as initcode.

Request emitted by `evm`	When
`eth_blockNumber`	once, on the first fetch
`eth_getCode` + `eth_getTransactionCount` + `eth_getBalance`	first touch of an account (sent as one batch array)
`eth_getStorageAt`	first read of a storage slot

Accounts created during execution are served locally and never fetched.

Warning

EVM execution should mostly work but may not implement every opcode and corner-case. If you find a bug that disrupts you, please file an issue with its impact to you and code that reproduces it and I may find time to fix it, or alternatively you can submit a pull request.

Roadmap

Assembler

Implicit stack use
Stack underflow warnings
Explicit Constructor

Disassembler

Label JUMPDEST in JUMPI and JUMP args

Execution

Flags to include state changes in JSON
Mock calls via -w config

Opcodes supported

Opname	Assembly and Disassembly	Execution
STOP	✅	✅
ADD	✅	✅
MUL	✅	✅
SUB	✅	✅
DIV	✅	✅
SDIV	✅	✅
MOD	✅	✅
SMOD	✅	✅
ADDMOD	✅	✅
MULMOD	✅	✅
EXP	✅	✅
SIGNEXTEND	✅	✅
LT	✅	✅
GT	✅	✅
SLT	✅	✅
SGT	✅	✅
EQ	✅	❓
ISZERO	✅	✅
AND	✅	❓
OR	✅	✅
XOR	✅	✅
NOT	✅	❓
BYTE	✅	✅
SHL	✅	✅
SHR	✅	✅
SAR	✅	❓
CLZ	✅	✅
SHA3	✅	✅
ADDRESS	✅	✅
BALANCE	✅	✅
ORIGIN	✅	❓
CALLER	✅	✅
CALLVALUE	✅	✅
CALLDATALOAD	✅	✅
CALLDATASIZE	✅	✅
CALLDATACOPY	✅	✅
CODESIZE	✅	✅
CODECOPY	✅	✅
GASPRICE	✅	❌
EXTCODESIZE	✅	✅
EXTCODECOPY	✅	✅
RETURNDATASIZE	✅	✅
RETURNDATACOPY	✅	✅
EXTCODEHASH	✅	❌
BLOCKHASH	✅	❌
COINBASE	✅	✅
TIMESTAMP	✅	❓
NUMBER	✅	❓
PREVRANDAO	✅	❌
GASLIMIT	✅	❌
CHAINID	✅	❓
SELFBALANCE	✅	✅
BASEFEE	✅	❌
BLOBHASH	✅	❌
BLOBBASEFEE	✅	❌
POP	✅	❓
MLOAD	✅	✅
MSTORE	✅	✅
MSTORE8	✅	✅
SLOAD	✅	✅
SSTORE	✅	✅
JUMP	✅	✅
JUMPI	✅	✅
PC	✅	✅
MSIZE	✅	✅
GAS	✅	✅
JUMPDEST	✅	✅
TLOAD	✅	✅
TSTORE	✅	✅
MCOPY	✅	❓
PUSH0	✅	✅
PUSH1	✅	✅
PUSH2	✅	✅
PUSH3	✅	✅
PUSH4	✅	❓
PUSH5	✅	❓
PUSH6	✅	❓
PUSH7	✅	✅
PUSH8	✅	❓
PUSH9	✅	❓
PUSH10	✅	❓
PUSH11	✅	❓
PUSH12	✅	❓
PUSH13	✅	❓
PUSH14	✅	❓
PUSH15	✅	✅
PUSH16	✅	❓
PUSH17	✅	❓
PUSH18	✅	✅
PUSH19	✅	❓
PUSH20	✅	✅
PUSH21	✅	❓
PUSH22	✅	❓
PUSH23	✅	✅
PUSH24	✅	❓
PUSH25	✅	❓
PUSH26	✅	❓
PUSH27	✅	❓
PUSH28	✅	❓
PUSH29	✅	❓
PUSH30	✅	❓
PUSH31	✅	❓
PUSH32	✅	✅
DUP1	✅	✅
DUP2	✅	✅
DUP3	✅	✅
DUP4	✅	✅
DUP5	✅	✅
DUP6	✅	✅
DUP7	✅	❓
DUP8	✅	❓
DUP9	✅	❓
DUP10	✅	❓
DUP11	✅	❓
DUP12	✅	❓
DUP13	✅	❓
DUP14	✅	❓
DUP15	✅	❓
DUP16	✅	❓
SWAP1	✅	✅
SWAP2	✅	✅
SWAP3	✅	❓
SWAP4	✅	❓
SWAP5	✅	❓
SWAP6	✅	❓
SWAP7	✅	❓
SWAP8	✅	❓
SWAP9	✅	❓
SWAP10	✅	❓
SWAP11	✅	❓
SWAP12	✅	❓
SWAP13	✅	❓
SWAP14	✅	❓
SWAP15	✅	❓
SWAP16	✅	❓
LOG0	✅	✅
LOG1	✅	✅
LOG2	✅	✅
LOG3	✅	✅
LOG4	✅	✅
CREATE	✅	✅
CALL	✅	✅
CALLCODE	✅	❌
RETURN	✅	✅
DELEGATECALL	✅	✅
CREATE2	✅	✅
STATICCALL	✅	✅
REVERT	✅	✅
INVALID	✅	❓
SELFDESTRUCT	✅	❓

Precompiles

Precompile	Address	Execution Supported
`HOLE`	`0x0`	✅
`ECRECOVER`	`0x1`	✅
`SHA2_256`	`0x2`	❌
`RIPEMD160`	`0x3`	❌
`IDENTITY`	`0x4`	✅
`MODEXP`	`0x5`	❌
`EC_ADD`	`0x6`	❌
`EC_MUL`	`0x7`	❌
`EC_PAIRING`	`0x8`	❌
`BLACK2F`	`0x9`	❌
`ZKG_POINT`	`0xa`	❌

Contributing

Please use camelCase for methods and variables but snake_case for types. Write errors to stderr. Use the C preprocessor.

Makefile

make: build the things
make again: rebuild the things
make clean: remove the things
make check: run the tests
make distcheck: run all the tests

Test-driven development

If you are fixing a bug or adding a feature, first write a test in the tst directory that fails now but would pass after your change. Lastly, verify your test now passes using make check.

Unit tests

Some unit tests written in C are found in tst/*.c. If they pass, they should have no output and exit with a status of 0.

Assembler tests

Assembler tests live in tst/in/*.evm. The assembler assembles those files and compares the output to the corresponding file in tst/out/.

Execution tests

EVM execution tests use the dio testing system. They can be found at tst/*.json. They can be run individually with evm -w.

Updating the README

The README.md is assembled by concatentation when make. See the Makefile. If you want to update the opcodes supported table, it should be updated automatically. Otherwise, the files you want to edit are:

make/.rme.md
make/ops.sh
CONTRIBUTING.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
NOTICES		NOTICES
docs		docs
include		include
make		make
secp256k1 @ 6e2c8bc		secp256k1 @ 6e2c8bc
src		src
tst		tst
.gitignore		.gitignore
.gitmodules		.gitmodules
.uncrustify.cfg		.uncrustify.cfg
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
dio.c		dio.c
evm.c		evm.c
ops.c		ops.c
precompiles.c		precompiles.c

Navigation Menu

Repository files navigation

EVM

Installation

Dependencies

Build from source

Usage

Assembler

Data section

Disassembler

EVM Execution

Configuration (Dio)

On-chain state (`bin/dio`)

Testing

Update Config

JSON Output

Network mode (`-nx`)

Warning

Roadmap

Assembler

Disassembler

Execution

Opcodes supported

Precompiles

Contributing

Makefile

Test-driven development

Unit tests

Assembler tests

Execution tests

Updating the README

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

EVM

Installation

Dependencies

Build from source

Usage

Assembler

Data section

Disassembler

EVM Execution

Configuration (Dio)

On-chain state (bin/dio)

Testing

Update Config

JSON Output

Network mode (-nx)

Warning

Roadmap

Assembler

Disassembler

Execution

Opcodes supported

Precompiles

Contributing

Makefile

Test-driven development

Unit tests

Assembler tests

Execution tests

Updating the README

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

On-chain state (`bin/dio`)

Network mode (`-nx`)