A minimal Ethereum Virtual Machine implementation in Go
focusing on bytecode execution from the ground up
echoevm is a from-scratch implementation of the Ethereum Virtual Machine written in Go. It's designed to be educational, minimal, and focused on understanding how EVM bytecode execution works.
The project started as a learning exercise to understand the internals of the EVM, from basic opcode execution to complex smart contract interactions.
$ go run ./cmd/echoevm run \
-artifact contract.json \
-function "add(uint256,uint256)" \
-args "42,58"
Executing artifact file: contract.json
Contract result: 100Execute Solidity bytecode directly from .bin files or Hardhat artifacts with full opcode support.
Automatic ABI encoding for function calls with support for various data types and parameters.
Proper handling of REVERT conditions with appropriate exit codes and detailed error messages.
Comprehensive test suites covering data types, control flow, and edge cases for validation.
Fetch and execute blocks from Ethereum networks via RPC with range processing capabilities.
Comprehensive execution tracing with configurable log levels for debugging and analysis.
# Clone the repository
git clone https://github.com/smallyunet/echoevm.git
cd echoevm
# Build the binary
make build
# Run tests
make test-advanced# Execute a contract function
go run ./cmd/echoevm run \
-artifact contract.json \
-function "add(uint256,uint256)" \
-args "42,58"
# Process Ethereum blocks
go run ./cmd/echoevm block -block 1
Added comprehensive Solidity contracts as test cases covering basic data types, functions, control flow, modifiers, events, interfaces, libraries, and inline assembly. All tests pass with the convenient make test-advanced command.
Added support for reading bytecode from Hardhat artifact files, making it easier to work with standard Hardhat projects. Simplified the compilation and execution workflow significantly.
go run ./cmd/echoevm run -artifact ./artifacts/contracts/Add.sol/Add.json -function "add(uint256,uint256)" -args "1,2"Implemented the ability to execute Ethereum blocks via RPC! Successfully executes the first 10,000 blocks of Ethereum mainnet (which contain no contract transactions). Added single block and block range execution modes.
Added the ability to execute runtime bytecode after deployment. Introduced function calling capabilities with automatic ABI encoding for parameters, making it possible to interact with deployed contracts.
First working version! Successfully deploys a simple Add.sol contract and outputs runtime bytecode. This version established the fundamental understanding of the difference between deployment code and runtime code.