evm-toolkit

Shared EVM/Solidity handling primitives for the necromancer suite.

A small, zero-runtime-dependency Python library that consolidates the EVM loading code that was previously duplicated across oracle (symbolic execution) and omen (trace vulnerability scanner):

• evm_toolkit.bytecode — parse hex / load runtime bytecode from a file
• evm_toolkit.rpc — a minimal, stdlib-only JSON-RPC client for eth_getCode
• evm_toolkit.source — Solidity source → runtime bytecode dispatch (sidecar .bin precedence, then solc)

oracle is pinned to Python 3.13 (requires-python = ">=3.13,<3.14") and must install without the heavy eth-* stack (web3 / eth-keys / coincurve), which historically broke on bleeding-edge Pythons. evm-toolkit therefore:

• implements its JSON-RPC client with urllib + json only — no web3;
• implements EIP-55 address checksumming with a from-scratch Keccak-256 — no eth-utils;
• treats py-solc-x as an optional extra, never a hard dependency.

This means anywhere oracle installs, evm-toolkit installs.

pip install "evm-toolkit @ git+https://github.com/bugsyhewitt/evm-toolkit"

from evm_toolkit import parse_bytecode, load_bytecode_file

parse_bytecode("0x6001")        # -> b"\x60\x01"
parse_bytecode("60 01\n")       # whitespace tolerated -> b"\x60\x01"
load_bytecode_file("code.bin")  # read a hex file -> bytes

from evm_toolkit import eth_get_code, normalize_address

normalize_address("0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed")
# -> '0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed' (EIP-55)

code = eth_get_code("https://rpc.example", "0xabc...def")  # eth_getCode only

eth_get_code issues only eth_getCode — it never submits a transaction.

from evm_toolkit import load_runtime_bytecode

# Precedence: a precompiled <source>.bin sidecar wins (no solc needed),
# otherwise compile via py-solc-x (if installed) or a solc binary on PATH.
code = load_runtime_bytecode("Contract.sol", contract_name="Contract")

To enable on-demand compilation via py-solc-x:

pip install "evm-toolkit[solcx] @ git+https://github.com/bugsyhewitt/evm-toolkit"

pip install -e ".[test]"
pytest

Tests are hermetic: RPC is exercised against a local mock server, source compilation is tested via the sidecar path, and Keccak-256 is verified against canonical Ethereum vectors. No live network and no solc binary required.

MIT. See LICENSE and NOTICE.