First-hand information for everyone
This paper presents dexamine, a Python package that turns raw Uniswap v2 and v3 event logs on Ethereum into structured observations of trades and liquidity changes. The software reads transaction receipt logs and reports token quantities, pool state, the order of events inside a transaction, and transaction gas information. Version 1 of the package has already been used to build data for an empirical study of price discovery in decentralized markets.
The authors separated the work into clear parts: fetching on‑chain data, resolving contract and token metadata, decoding protocol events, and writing the output. The code is available on GitHub and can be installed directly from the repository. It requires Python 3.10 or newer and depends on web3.py and Requests. The repository includes recorded Ethereum responses and an offline example so users can reproduce parsing without a live node.
At a high level dexamine asks for block number and transaction index positions and then uses Ethereum’s JSON‑RPC (a JSON remote procedure call interface) to retrieve blocks, transactions, and receipt logs. The parsers decode event topics and fields, join them with contract metadata such as token decimals and symbols, and scale integer amounts into token units. The package accounts for protocol differences: Uniswap v2 uses a preceding Sync event to report reserve updates, while v3 swap logs report price, tick, and active liquidity directly. The output can include the original node responses or one flat row per event; each event is given a receipt_log_index that is zero‑based inside the receipt and thus identifies its order inside the transaction.
This work matters because public blockchains record contract execution but not ready‑to‑use economic observations. Researchers studying liquidity, trading costs, arbitrage, or price formation need consistent decoding, units, and event ordering. By providing a reusable parser that preserves event sequence and joins execution metadata, dexamine reduces duplicated effort and the risk of inconsistent signs, units, or ordering across studies. The paper also gives an illustrative example: a recorded Ethereum transaction in block 12,561,528 contains four Uniswap v3 swaps across three pools and dexamine reconstructs those swaps in receipt order with post‑event pool state.
There are important limits to keep in mind. dexamine needs access to a JSON‑RPC endpoint that still serves the requested historical blocks and receipts and supports contract metadata calls; without that it cannot parse live history. Token and pool metadata are cached at the latest block, so metadata changes after the recorded event can change repeated runs unless the caller seeds the resolver with recorded metadata. Normalized token amounts are produced with floating‑point arithmetic and can have rounding error; the original integer logs are retained if exact accounting is required. Gas and fee fields are reported per transaction and are not allocated to individual events. The tool does not reconstruct internal call paths, identify traders, or measure maximal extractable value, and the authors do not claim any special performance or throughput advantage over other extraction tools.