README.md
August 1, 2026 · View on GitHub
EVMole is a powerful library that extracts information from Ethereum Virtual Machine (EVM) bytecode, including function selectors, arguments, state mutability, persistent and transient storage layouts, and CBOR metadata, even for unverified contracts.
Key Features
- Multi-language support: Available as JavaScript, Rust, Python, and Go libraries.
- High accuracy and performance: Outperforms existing tools.
- Broad compatibility: Tested with both Solidity and Vyper compiled contracts.
- Lightweight: Clean codebase with minimal external dependencies.
- Unverified contract analysis: Extracts information even from unverified bytecode.
- Selector dispatch classification: Distinguishes normal ABI dispatch from selectors handled by fallback logic.
- CBOR metadata: Extracts string-keyed values from a terminal, length-suffixed CBOR map without assuming a particular compiler.
Usage
JavaScript
API documentation and usage examples (Node.js, Vite, webpack, Parcel, esbuild)
npm i evmole
import { contractInfo } from 'evmole'
const code = '0x6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256'
console.log( contractInfo(code, {selectors:true, arguments:true, stateMutability:true}) )
// {
// functions: [
// {
// selector: '2125b65b',
// bytecodeOffset: 52,
// dispatch: 'abi',
// arguments: 'uint32,address,uint224',
// stateMutability: 'pure'
// },
// ...
Rust
Documentation is available on docs.rs
let code = hex::decode("6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256").unwrap();
println!("{:?}", evmole::contract_info(
evmole::ContractInfoArgs::new(&code)
.with_selectors()
.with_arguments()
.with_state_mutability()
)
);
// Contract {
// functions: Some([
// Function {
// selector: [33, 37, 182, 91],
// bytecode_offset: 52,
// dispatch: Abi,
// arguments: Some([Uint(32), Address, Uint(224)]),
// state_mutability: Some(Pure)
// },
// ...
Python
pip install evmole --upgrade
from evmole import contract_info
code = '0x6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256'
print( contract_info(code, selectors=True, arguments=True, state_mutability=True) )
# Contract(
# functions=[
# Function(
# selector=2125b65b,
# bytecode_offset=52,
# dispatch="abi",
# arguments=uint32,address,uint224,
# state_mutability=pure),
# ...
Go
go get github.com/cdump/evmole/go
package main
import (
"context"
"encoding/hex"
"fmt"
"github.com/cdump/evmole/go"
)
func main() {
code, _ := hex.DecodeString("6080604052348015600e575f80fd5b50600436106030575f3560e01c80632125b65b146034578063b69ef8a8146044575b5f80fd5b6044603f3660046046565b505050565b005b5f805f606084860312156057575f80fd5b833563ffffffff811681146069575f80fd5b925060208401356001600160a01b03811681146083575f80fd5b915060408401356001600160e01b0381168114609d575f80fd5b80915050925092509256")
info, _ := evmole.ContractInfo(context.Background(), code, evmole.Options{
Selectors: true,
Arguments: true,
StateMutability: true,
})
for _, fn := range info.Functions {
fmt.Printf("%s: %s @ %d\n", fn.Selector, *fn.Arguments, fn.BytecodeOffset)
}
// 2125b65b: uint32,address,uint224 @ 52
// b69ef8a8: @ 68
}
Foundry
Foundry's cast uses the Rust implementation of EVMole
$ cast selectors $(cast code 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)
0x06fdde03 view
0x095ea7b3 address,uint256 nonpayable
0x18160ddd view
0x23b872dd address,address,uint256 nonpayable
...
$ cast selectors --resolve $(cast code 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)
0x06fdde03 view name()
0x095ea7b3 address,uint256 nonpayable approve(address,uint256)
0x18160ddd view totalSupply()
0x23b872dd address,address,uint256 nonpayable transferFrom(address,address,uint256)
...
AI agents
For application code, use one of the language bindings above. For agent-driven bytecode analysis, choose one integration.
JSON CLI
Use for one-off analysis and scripts:
npx -y evmole analyze --bytecode 0x...
Portable skill
Install routing and interpretation guidance for supported agents:
npx skills add cdump/evmole --skill evm-bytecode-analysis -g
Local MCP server
Expose EVMole as a typed local tool:
npx -y evmole-mcp
All integrations expect deployed/runtime bytecode and run locally without sending bytecode to an EVMole-operated service. See the agent integration guide for setup, schemas, limitations, and privacy details.
Benchmark
function selectors
FP/FN - False Positive/False Negative errors; smaller is better
| Dataset | evmole rs · js · py · go | whatsabi | sevm | evmhound | heimdall | |
| coverage2k solidity 2000 addresses 45650 functions |
FP addrs | 0 🥇 | 4 | 1 | 56 | 3 |
| FN addrs | 0 🥇 | 11 | 0 🥇 | 224 | 166 | |
| FP funcs | 0 🥇 | 10 | 10 | 616 | 27 | |
| FN funcs | 0 🥇 | 145 | 0 🥇 | 821 | 342 | |
| Time | 24ms · 0.3s · 31ms · 0.1s | 2.0s | 28s(*) | 86ms | 111s(*) | |
| random10k solidity 10000 addresses 223316 functions |
FP addrs | 0 🥇 | 19 | 16 | 224 | 7 |
| FN addrs | 0 🥇 | 44 | 1 | 838 | 819 | |
| FP funcs | 0 🥇 | 65 | 112 | 3157 | 260 | |
| FN funcs | 0 🥇 | 173 | 7 | 4112 | 1021 | |
| Time | 0.1s · 0.8s · 0.2s · 0.8s | 7.1s | 80s(*) | 0.4s | 533s(*) | |
| coverage1k vyper 1000 addresses 38759 functions |
FP addrs | 0 🥇 | 560 | 0 🥇 | 2 | 0 🥇 |
| FN addrs | 0 🥇 | 998 | 788 | 525 | 998 | |
| FP funcs | 0 🥇 | 560 | 0 🥇 | 5 | 0 🥇 | |
| FN funcs | 0 🥇 | 38759 | 34077 | 16218 | 38759 | |
| Time | 91ms · 0.4s · 0.1s · 0.3s | 1.9s | 5.4s(*) | 67ms | 12s(*) | |
function arguments
Errors - when at least 1 inferred argument is incorrect: (uint256,string) ≠ (uint256,bytes)
| Dataset | evmole rs · js · py · go | heimdall | |
| coverage2k solidity 45650 functions |
Errors | 8.5% 🥇 3883 |
23.3% 10643 |
| Time | 0.8s · 1.7s · 1.1s · 2.1s | 111s(*) | |
| random10k solidity 223316 functions |
Errors | 6.8% 🥇 15296 |
21.4% 47878 |
| Time | 3.5s · 6.9s · 4.2s · 9.7s | 511s(*) | |
| coverage1k vyper 38759 functions |
Errors | 45.4% 🥇 17590 |
100.0% 38759 |
| Time | 0.5s · 1.1s · 0.6s · 1.4s | 12s(*) | |
function state mutability
Errors - Results are not equal (treating view and pure as equivalent to nonpayable)
Errors strict - Results are strictly unequal (nonpayable ≠ view). Some ABIs mark pure/view functions as nonpayable, so not all strict errors indicate real issues.
| Dataset | evmole rs · js · py · go | whatsabi | sevm | heimdall | |
| coverage2k solidity 45647 functions |
Errors | 0.0% 🥇 18 |
52.2% 23810 |
11.2% 5133 |
19.6% 8951 |
| Errors strict | 9.0% 🥇 4107 |
70.9% 32346 |
62.3% 28429 |
41.3% 18835 |
|
| Time | 10s · 11s · 9.7s · 20s | 3.1s | 29s(*) | 112s(*) | |
| random10k solidity 223273 functions |
Errors | 0.0% 🥇 39 |
48.8% 108928 |
9.3% 20713 |
18.6% 41507 |
| Errors strict | 8.9% 🥇 19940 |
69.9% 156081 |
60.9% 136069 |
40.1% 89519 |
|
| Time | 48s · 50s · 46s · 88s | 12s | 81s(*) | 512s(*) | |
| coverage1k vyper 38278 functions |
Errors | 0.1% 🥇 34 |
100.0% 38278 |
96.2% 36814 |
100.0% 38278 |
| Errors strict | 1.2% 🥇 441 |
100.0% 38278 |
98.4% 37650 |
100.0% 38278 |
|
| Time | 45s · 39s · 44s · 89s | 2.0s | 5.5s(*) | 12s(*) | |
Control Flow Graph
False Negatives - Valid blocks possibly incorrectly marked unreachable by CFG analysis. Lower count usually indicates better precision.
| evmole rs · js · py · go | ethersolve | evm-cfg | sevm | heimdall-rs | evm-cfg-builder | |
| Basic Blocks | 92.8% 🥇 483212 |
52.5% 273518 |
58.6% 305248 |
37.3% 194368 |
32.6% 169980 |
14.5% 75383 |
| False Negatives | 7.2% 🥇 37496 |
47.5% 247190 |
41.4% 215460 |
62.7% 326340 |
67.4% 350728 |
85.5% 445325 |
| Time | 14s · 26s · 12s · 55s | 888s | 36s | 9.8s | 20s | 359s |
dataset flow-challenge500, 500 contracts, 520,708 blocks
notes
See benchmark/README.md for the methodology and commands to reproduce these results
versions: evmole v0.9.3; whatsabi v0.25.0; sevm v0.7.4; evm-hound-rs v0.1.4; heimdall-rs v0.9.3
(*): sevm and heimdall-rs are full decompilers, not limited to extracting function selectors
How it works
EVMole uses symbolic execution with a custom EVM implementation to trace how CALLDATA flows through the bytecode:
This approach is more accurate than static pattern matching because it follows the actual execution paths the EVM would take, correctly handling complex dispatchers, proxy patterns, and compiler-specific optimizations from both Solidity and Vyper.
Talks
- EVMole: function selectors and arguments from bytecode - BlockSplit 2024
- EVMole: function selectors and arguments from bytecode - EthCC 2024
- Reconstructing Control Flow Graphs from EVM Bytecode - ETHTaipei 2025
- Reconstructing Control Flow Graphs from EVM Bytecode: Faster, Better, Stronger - EthCC 2025
License
MIT