Practical overview
When it fits
Use it in a Python workflow when you have a contract ABI and need to turn Ethereum receipt logs or Geth trace data into named event records.
Who it is for
- Python developers working with Ethereum contract event data.
- Developers who need to interpret receipt logs or Geth trace struct logs using contract ABIs.
Documented uses
- Generate event topic maps from ABI files.
- Decode event names and input values from transaction receipt logs.
- Decode events from Geth debug_traceTransaction struct logs.
Requirements & limits
The repository is public and identifies the project as MIT-licensed. The README documents installation through pip or setuptools.
- A contract ABI is needed to build a useful topic map.
- Trace decoding requires Geth structLogs; supplying initial_address is necessary to include event-emitting addresses.
- Indexed array topics are hashed and cannot be decoded, and anonymous events are unsupported.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Install Eth Event and prepare an ABI topic map
Install the library and generate a topic map from a contract ABI file.
Before you start
- Python 3
- An Ethereum contract ABI available as abi.json
Steps
Install the latest release with pip install eth-event, or clone the repository and install it using setuptools.
Import get_topic_map from eth_event.
Read the ABI file and pass its contents to get_topic_map.
Expected outcome
A topic map containing event topic hashes and their event names and input definitions.
Guide limitations
- This procedure prepares the topic map; decoding logs or traces is a separate use of the library.
- Indexed array values cannot be decoded from their hashed topics, and anonymous events cannot be decoded.
Decode receipt logs or Geth trace events
Use a topic map to decode Ethereum event data from a transaction receipt or Geth trace.
Before you start
- Eth Event installed in a Python environment
- A topic map generated from the relevant contract ABI
- Transaction receipt logs, or structLogs from Geth debug_traceTransaction
Steps
For receipt data, pass the transaction's logs and topic map to eth_event.decode_logs.
For trace data, obtain structLogs from the Geth debug_traceTransaction response.
Pass the struct logs and topic map to eth_event.decode_trace; supply initial_address when decoded event records should include the emitting address.
Use allow_undecoded with decode_logs or decode_trace when undecoded logs should be returned without raising an exception.
Expected outcome
Decoded event records with event names and available input values; trace records can include event addresses when an initial address is supplied.
Guide limitations
- Indexed array values are hashed and remain undecoded.
- Anonymous events cannot be decoded.
- The initial address for a trace call cannot be determined by the library.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 13 October 2026
- Original website title
- iamdefinitelyahuman/eth-event · Official homepage title · retained in its source language