EVMole

EVMole JavaScript (WASM) provides a WebAssembly-based implementation of EVMole for use in JavaScript environments. It is built using wasm-pack and is designed to work across modern browsers and various JavaScript bundlers.

To simplify integration, the library provides a default entry point at ./src/evmole_esm.js that includes an await init() call, enabling compatibility with environments that support top-level await.

When interpreting EVMole results, be aware of the following constraints:

Inference vs. Fact:

• Selectors are considered bytecode evidence (facts).
• Arguments, mutability, and storage types are inferred and should not be presented as verified source-level facts.

What EVMole does NOT do:

• Does not fetch contract addresses.
• Does not decode calldata.
• Does not resolve signature names.
• Does not verify source code.
• Does not reconstruct exact source code.

Best Practices:

• Always check the warnings and pagination objects in every response before summarizing the data.
• EVMole runs locally; bytecode is not sent to an EVMole-operated service, though your agent provider may receive the data based on their own configuration.

Privacy

• Uses stdio only; no network requests are made.
• Requires no credentials.
• Does not fetch contract addresses or write files.

Technical Limitations

• Inference vs. Verification: Arguments, mutability, and storage descriptions are inferred from bytecode rather than verified against source-level facts.
• Scope: Does not decode calldata, verify source, execute creation bytecode, or fully decompile source.
• Version Matching: Each evmole-mcp release depends on the matching exact evmole version.

When using EVMole to explain or report on bytecode, adhere to these interpretation rules to ensure accuracy and safety:

• Inference vs. Fact: Treat call arguments, mutability, storage types, and storage labels as inferred. Never present them as verified source-level facts.
• No Hallucinations: Report selectors exactly as found. Do not invent function names or source-level semantics that are not present in the bytecode.
• Evidence Separation: Clearly separate direct bytecode evidence from inferred data or material uncertainty.
• Scope Limitations: Do not use EVMole for:
  • Calldata decoding
  • Address/RPC fetching
  • Source verification
  • Exact source reconstruction
  • Non-EVM input
  • Full decompilation
  • Creation-bytecode execution

EVMole is specialized for bytecode analysis and does not support the following tasks:

• Calldata or transaction decoding: Requires a dedicated calldata/ABI decoder.
• Fetching an address: Requires an authorized RPC or chain-data tool.
• Solidity source verification: Requires a compiler and a verification workflow.
• Source reconstruction: Exact source reconstruction or full decompilation is outside the scope of EVMole.
• Non-EVM binaries: Requires an analyzer specific to that architecture.

When using any EVMole binding, keep the following conceptual constraints in mind:

• Bytecode Type: All bindings analyze deployed/runtime bytecode. They do not automatically execute or strip creation bytecode.
• Inference vs. Verification: Data such as inferred arguments, state mutability, storage types, and storage labels should be treated as inferred from the bytecode rather than verified source-level facts. They are probabilistic/deduced, not absolute truths from the original source code.

EVMole performs function selector and argument extraction using symbolic execution with a custom EVM implementation. Instead of relying on static pattern matching, it traces how CALLDATA flows through the bytecode.

This method allows EVMole to accurately handle:

• Complex dispatchers
• Proxy patterns
• Compiler-specific optimizations (from both Solidity and Vyper)
• Actual execution paths the EVM would take

EVMole schema version 1 is designed to analyze deployed/runtime bytecode (the code stored at a contract address and executed during calls).

It does not execute constructor code (creation bytecode) and cannot automatically locate the runtime code returned by a constructor. To analyze a contract, you must first fetch or obtain the deployed runtime code directly.

To use EVMole in Go, import the module github.com/cdump/evmole/go.

There are two ways to perform analysis:

1. Single analysis: Use evmole.ContractInfo.
2. Efficient reuse: Use evmole.NewAnalyzer to create an analyzer instance that can be reused for multiple analyses, which is more performant for batch processing.

go get github.com/cdump/evmole/go

You can execute individual stages of the benchmarking process using specific make targets:

• make build: Builds the required Docker images.
• make run-selectors: Runs tests for function selectors (requires Docker images to be built).
• make reference.build: Builds the reference provider.
• make reference.<mode>/<dataset>: Generates reference results for a specific mode and dataset (e.g., make reference.selectors/solidity-random10k).

# Only build docker-images
make build

# Only run tests for selectors
make run-selectors

# Build the reference provider
make reference.build

# Generate reference results for a specific mode/dataset
make reference.selectors/solidity-random10k
make reference.arguments/solidity-random10k