evmole 0.3.2

Extracts function selectors and arguments from EVM bytecode

EVMole

This library extracts function selectors and arguments from Ethereum Virtual Machine (EVM) bytecode, even for unverified contracts.

• JavaScript, Rust and Python implementations
• Clean code with zero external dependencies (py & js)
• Faster and more accurate than other existing tools
• Tested on Solidity and Vyper compiled contracts

Try it online

Usage

JavaScript

$ npm i evmole

import {functionArguments, functionSelectors} from 'evmole'
// Also supported: const e = require('evmole'); e.functionSelectors();

const code = '0x6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256'
console.log( functionSelectors(code) )
// Output(list): [ '2125b65b', 'b69ef8a8' ]

console.log( functionArguments(code, '2125b65b') )
// Output(str): 'uint32,address,uint224'

Rust

Documentation available on docs.rs

let code = hex::decode("6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256").unwrap();

println!("{:x?}", evmole::function_selectors(&code, 0));
// Output(Vec<[u8;4]>): [[21, 25, b6, 5b], [b6, 9e, f8, a8]]

println!("{}", evmole::function_arguments(&code, &[0x21, 0x25, 0xb6, 0x5b], 0));
// Output(String): uint32,address,uint224

Python

$ pip install evmole --upgrade

from evmole import function_arguments, function_selectors

code = '0x6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256'
print( function_selectors(code) )
# Output(list): ['2125b65b', 'b69ef8a8']

print( function_arguments(code, '2125b65b') )
# Output(str): 'uint32,address,uint224'

See examples for more

Benchmark

function selectors

FP/FN - False Positive/False Negative errors; smaller is better

Dataset		evmole rs · js · py	whatsabi	evm-hound-rs	heimdall-rs	simple
largest1k 1000 contracts 24427 functions	FP contracts	1 🥈	0 🥇	75	18	95
	FN contracts	0 🥇	8	40	102	9
	FP functions	192 🥈	0 🥇	720	600	749
	FN functions	0 🥇	8 🥈	191	113	12
	Time	0.6s · 1.4s · 1.5s	2.6s	0.7s	598.6s	1.4s
random50k 50000 contracts 1171102 functions	FP contracts	1 🥇	43	693	waiting fixes	4136
	FN contracts	9 🥇	31	2903		77
	FP functions	3 🥇	51	10798		14652
	FN functions	10 🥇	32	3538		96
	Time	7.3s · 17.4s · 25.7s	46.8s	10.2s		33.9s
vyper 780 contracts 21244 functions	FP contracts	0 🥇	30	19	0	185
	FN contracts	0 🥇	780	300	780	480
	FP functions	0 🥇	30	19	0	197
	FN functions	0 🥇	21244	8273	21244	12971
	Time	0.5s · 0.8s · 1.0s	1.9s	0.5s	15.5s	1.0s

function arguments

Errors - when at least 1 argument is incorrect: (uint256,string) != (uint256,bytes); smaller is better

Dataset		evmole rs · js · py	heimdall-rs	simple
largest1k 1000 contracts 24427 functions	Errors	15.0%, 3664 🥇	42.6%, 10414	58.3%, 14242
	Time	0.8s · 6.0s · 9.6s	602.9s	0.6s
random50k 50000 contracts 1171102 functions	Errors	5.4%, 63124 🥇	waiting fixes	54.9%, 643213
	Time	17.2s · 179.2s · 300.9s		8.1s
vyper 780 contracts 21244 functions	Errors	52.4%, 11123 🥇	100.0%, 21244	56.8%, 12077
	Time	0.8s · 7.0s · 12.9s	15.6s	0.6s

See benchmark/README.md for the methodology and commands to reproduce these results

versions: evmole v0.3.1; whatsabi v0.10.0; evm-hound-rs v0.1.4; heimdall-rs v0.7.3

How it works

Short: Executes code with a custom EVM and traces CALLDATA usage.

Long: TODO

License

MIT