Source-linked AI summary
dexamine: A Python package for Uniswap event data on Ethereum
Magnus Hansson
TL;DR
Empirical analysis of decentralized-exchange activity requires interpreting blockchain records and linking them to execution metadata. dexamine provides a reusable Python package that parses Uniswap v2 and v3 events into observations with quantities, pool state, order, and gas information. Version 1 has been used to construct data for a study of price discovery in decentralized markets.
Problem
Public blockchain records describe contract execution, so empirical studies must interpret them into economic observations while preserving execution conditions and event order.
Method
dexam ine separates data retrieval, contract metadata resolution, protocol parsing, and output construction to produce common Uniswap event records joined to execution metadata.
Results
Version 1 has been used to construct data for an empirical study of price discovery in decentralized markets.
Takeaways & Limitations
The library provides reusable protocol interpretation and data joins for empirical research on Uniswap trading and liquidity events.
Takeaways & Limitations
Normalized quantities use floating-point arithmetic and may contain rounding error, while gas fields apply to transactions rather than individual trades.
Abstract
from arXiv · showhide
Decentralized exchanges record trading and liquidity provision on public blockchains, but empirical analysis requires interpreting these records and linking them to execution metadata. dexamine is a Python package that parses Uniswap v2 and v3 events on Ethereum. It converts transaction receipt logs into observations of trades and liquidity changes, with token quantities, pool state, transaction order, and gas information. The package separates data retrieval, contract metadata, protocol interpretation, and output construction. The repository provides recorded Ethereum responses and an offline reproducible example, and version 1 has been used to construct data for an empirical study of price discovery in decentralized markets.
1 Introduction
dexamine addresses the need to interpret Uniswap’s public execution records as economic observations while preserving transaction order, pool state, and execution metadata. It provides a reusable representation of Uniswap events joined to that metadata and has been used to construct data for price-discovery research.
- Motivation: A transaction can contain multiple trades or liquidity events whose execution order cannot be recovered from a block timestamp alone.Transaction position, fees, and post-trade pool state help describe execution conditions.
- Approach: The package decodes protocol-specific records, resolves token metadata, normalizes quantities, and joins events with transaction and block metadata.Researchers provide transaction positions, protocol selection, and optionally a pool address to receive supported event records.
- Contribution: dexamine provides a common representation of Uniswap events joined to execution metadata for researchers’ own empirical pipelines.Transaction discovery, storage, and statistical estimation remain independent stages.
- Related tools: Unlike related extraction and indexing tools, dexamine focuses on reusable protocol interpretation within a separate researcher-controlled library.The related tools remain external and are not imported or invoked by dexamine.
- Application: Version 1 has been used to construct data for an empirical study of price discovery in decentralized markets.The application preserves event sequence and associated pool information while consistently treating units, liquidity changes, and execution metadata.
2 Software design and implementation
dexamine separates retrieval, metadata resolution, protocol parsing, and output construction to convert Uniswap v2 and v3 events into ordered, normalized records. Its implementation supports batching, offline testing, and reproducibility, while documented limitations concern numerical precision, transaction-level gas attribution, destination classification, and metadata provenance.
- Processing: Batched results are yielded incrementally, but processing rates depend on endpoint latency, capacity, batch size, and metadata cache misses.The package makes no throughput advantage claim over other extraction tools.
- Functionality: The package parses Uniswap v2 and v3 swaps, mints, and burns into records with normalized quantities, token metadata, pool information, and execution identifiers.Liquidity additions are positive, removals are negative, and swap quantities represent pool net token flows.
- Protocol parsing: Uniswap v2 parsing validates a preceding same-pool Sync event, while Uniswap v3 parsing derives prices and virtual reserves from reported price, tick, and active liquidity.Uniswap v3 virtual reserves describe the local trading curve and are missing when active liquidity is zero.
- Limitations: Normalized token quantities use floating-point arithmetic and can contain rounding error, although retained logs allow recovery of integer quantities.The output is intended for empirical analysis rather than exact integer accounting.
- Architecture: The data flow separates RPC retrieval, contract metadata resolution, protocol parsing, and output construction, with offline replay using recorded RPC results and seeded metadata.A reusable session caches contract interfaces and pool and token metadata across calls.
- Limitations: Gas and fee fields apply to the whole transaction and repeat across events, so they do not allocate execution costs to individual trades.Summing repeated fields across events would count the same transaction cost multiple times.
- Limitations: Destination labels use the top-level transaction destination and do not reconstruct internal call paths or establish trader identity, arbitrage, or maximal extractable value.Reproducibility can also vary with software version, source responses, and metadata resolved at the latest block.
- Testing: Offline tests cover event decoding, signed quantities, reserve ordering, pool filtering, and missing values, while optional integration tests check the public interface against a live endpoint.Continuous integration runs across Python 3.10 through 3.13.
3 Illustrative example
The illustrative transaction contains four Uniswap v3 swaps across three pools, with receipt ordering and post-swap pool state represented in separate outputs. The example also exposes transaction-level metadata and an offline verification workflow.
- Four Uniswap v3 swaps across three pools are parsed from one transaction and ordered by receipt position.Table 1 reports amounts in token units, with receipt positions zero-based and rounded values shown to six decimal places.
- The first and last swaps involve the same USDC/WETH pool but remain distinct observations within the transaction.
- Post-swap prices and virtual reserves are reported for each event, with prices expressed according to each pool’s token0/token1 ordering.Virtual reserves describe the local trading curve and should not be interpreted as total pool balances.
- Gas usage of 476,588 and an effective gas price of 40 gwei apply to the whole transaction and repeat on every output row.Summing these fields across the four swaps would count the same transaction cost four times.
- The recorded example reproduces the output offline, while verification checks compare all four rows and independently validate swap amounts and pool state.The repository includes full transaction, receipt, and block responses plus metadata for the three pools and tokens.
4 Conclusions
dexamine converts Uniswap v2 and v3 receipt logs into event observations linked to Ethereum execution metadata. It provides reusable protocol interpretation and data joins for empirical research, with batch processing, offline verification, and an executable example.
- dexamine converts Uniswap v2 and v3 receipt logs into event observations linked to Ethereum execution metadata.
- The library implements reusable protocol interpretation and data joins for empirical research, supporting individual transactions and batched processing.
- Offline verification and an executable example accompany the library.
Code and data availability
The source code and recorded example materials are distributed with the repository. The paper describes version v1.1.0 under the GNU General Public License v3.0 or later.
- The source code is available under the GNU General Public License v3.0 or later, and the paper describes version v1.1.0.
- Recorded Ethereum responses, example scripts, expected output, historical metadata, and recorded inputs are distributed with the repository.