Fast assembler and disassembler for the Ethereum Virtual Machine (EVM) supporting expressive syntax.
# Build from source
git clone https://github.com/wjmelements/evm.git
cd evm
make bin/evm
# Append bin/ to your $PATH
export PATH=$PATH:$pwd/bin
# Install
echo -n PATH='$PATH:' >> ~/.bashrc
echo $pwd/bin' >> ~/.bashrc
source ~/.bashrc
# 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.
$ cat selfdestruct.out
33ff
# Outputs valid assembly
$ evm -d selfdestruct.out
SELFDESTRUCT(CALLER)
# Can read from stdin
$ cat selfdestruct.out | evm -d
SELFDESTRUCT(CALLER)
$ 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)
By using -w config.json
, you can define the precondition state before execution.
[
{
"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.
[
{
"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
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"
}
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
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.
-w
config
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 | ✅ | ❓ |
SHA3 | ✅ | ✅ |
ADDRESS | ✅ | ✅ |
BALANCE | ✅ | ✅ |
ORIGIN | ✅ | ❓ |
CALLER | ✅ | ✅ |
CALLVALUE | ✅ | ✅ |
CALLDATALOAD | ✅ | ✅ |
CALLDATASIZE | ✅ | ✅ |
CALLDATACOPY | ✅ | ✅ |
CODESIZE | ✅ | ✅ |
CODECOPY | ✅ | ✅ |
GASPRICE | ✅ | ❌ |
EXTCODESIZE | ✅ | ✅ |
EXTCODECOPY | ✅ | ✅ |
RETURNDATASIZE | ✅ | ✅ |
RETURNDATACOPY | ✅ | ✅ |
EXTCODEHASH | ✅ | ❌ |
BLOCKHASH | ✅ | ❌ |
COINBASE | ✅ | ✅ |
TIMESTAMP | ✅ | ❓ |
NUMBER | ✅ | ❓ |
DIFFICULTY | ✅ | ❌ |
GASLIMIT | ✅ | ❌ |
CHAINID | ✅ | ❓ |
SELFBALANCE | ✅ | ✅ |
BASEFEE | ✅ | ❌ |
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 | ✅ | ❓ |
AUTH | ✅ | ❌ |
AUTHCALL | ✅ | ❌ |
STATICCALL | ✅ | ✅ |
REVERT | ✅ | ✅ |
INVALID | ✅ | ❌ |
SELFDESTRUCT | ✅ | ❓ |
Please use camelCase for methods and variables but snake_case for types. Write errors to stderr. Use the C preprocessor.
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
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.
If you create a new test file, you may need to update the TESTS
field in the Makefile
.
Then make your change.
Lastly, verify your test now passes.
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 live in tst/in/*.evm
.
The assembler assembles those files and compares the output to the corresponding file in tst/out/
.
EVM execution tests use the dio
testing system.
They can be found at tst/*.json
.
They can be run individually with evm -w
.
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