Research
dexamine: A Python package for Uniswap event data on Ethereum
Public blockchains record every Uniswap trade and liquidity change, but those records are contract execution artifacts expressed as raw event logs, not economic observations.

- arXiv
- 2609.10407
- Published
- 2026-09-09
- Authors
- Magnus Hansson
AI summary
Overview
Research area: Trading and Market Microstructure, with a focus on empirical data construction for decentralized finance (DeFi) markets on Ethereum.
Technical level: Intermediate. The paper assumes familiarity with Ethereum's account model, JSON-RPC, transaction receipts and event logs, and with the mechanics of automated market makers. It is a software description rather than a theoretical or econometric paper, and it contains no statistical estimation.
Scope (one sentence): The paper describes dexamine, a Python package that decodes Uniswap v2 and v3 swap, mint, and burn events from Ethereum transaction receipt logs and joins them to transaction-level execution metadata such as ordering and gas, and it demonstrates the output on a single recorded transaction.
What This Paper Is About
Public blockchains record every Uniswap trade and liquidity change, but those records are contract execution artifacts expressed as raw event logs, not economic observations. Turning them into usable data requires protocol-specific decoding, token metadata resolution, unit conversion, and joins to execution metadata, and repeating these steps separately in each project invites inconsistent units, signs, and event ordering. The paper presents a reusable Python library that performs these transformations in one place, together with recorded inputs and an offline example so that results can be reproduced without a live node.
Key Contributions
- A reusable parser for Uniswap v2 and v3 events on Ethereum mainnet.
dexamineconverts transaction receipt logs into records for swaps, mints, and burns, including token symbols, decimal precision, normalized token quantities, and event-specific pool information. - A layered architecture that keeps stages separable. The package separates JSON-RPC retrieval, contract metadata resolution, protocol interpretation, and output construction, so researchers can reuse node-access and contract-call facilities while embedding protocol interpretation in their own pipelines. Transaction discovery, storage, and statistical estimation remain independent stages.
- A common event representation joined to execution metadata. Flat output carries block index, transaction index, transaction hash, and
receipt_log_index— the event's zero-based position within its receipt's log list, which the paper distinguishes from Ethereum's block-widelogIndex. Gas consumption and fee fields are attached at transaction level. - A reproducible offline artifact. The repository ships recorded Ethereum responses, recorded pool and token metadata, expected JSON output, and a verification script, so the worked example and integrity checks run in continuous integration without a node.
Main Findings
- Protocol differences are handled explicitly, not smoothed over. Uniswap v2 reports reserve updates in a preceding
Syncevent, so the parser checks that the immediately preceding log is aSyncfrom the same pool and skips the event if that condition fails. Uniswap v3 swap logs report price, tick, and active liquidity directly, and the parser derives price and virtual reserves from them. - Sign conventions encode direction of flow. Liquidity additions are positive and removals negative; swap quantities describe the pool's net token flows, with positive quantities entering the pool and negative quantities leaving it.
- Virtual reserves are not pool balances. For v3, the derived reserves describe the local trading curve at the reported active liquidity and are reported as missing when active liquidity is zero. The paper specifically warns that the large DAI/USDC virtual reserves in its example should not be read as assets held by that pool.
- Execution order within a transaction is recoverable only through receipt position. A block timestamp does not recover the order of multiple events inside one transaction, and the parser may group different supported event types, so the example sorts rows by
receipt_log_index. - The worked example decodes four swaps across three pools in one transaction. Transaction 31 in Ethereum block 12,561,528 (recorded 3 June 2021) contains four Uniswap v3 swaps at receipt positions 3, 6, 10, and 13, with intervening token transfers and other unsupported logs explaining the gaps. The first and last swaps concern the same USDC/WETH pool but remain distinct observations.
- Post-swap state differs sharply across the three pools. Reported prices are token 0 per token 1: 2802.766431 at tick 196936 (position 3), 0.998748 at tick -276312 (position 6), 2800.001801 at tick -79378 (position 10), and 2802.194884 at tick 196938 (position 13).
- Transaction-level cost fields must not be summed across events. Gas usage of 476,588 and an effective gas price of 40 gwei apply to the whole transaction and repeat on every row, so summing them across the four swaps would count the same cost four times.
- Destination labels are shallow by design. Transactions with no destination are labeled
contract_creation, destinations matching a bundled list of Uniswap router addresses are labeleduniswap_router, and all remaining destinations are labeledother_contract. The paper states this classification does not reconstruct internal call paths or establish trader identity, arbitrage, or maximal extractable value. - Reproducibility is conditional on captured inputs and metadata. Pool and token metadata are queried at the latest block and cached, so changes to token metadata can affect repeated runs even when historical logs are unchanged. The
MetadataResolver.seedmethod accepts recorded metadata, normalizes addresses, and replaces supplied cache entries, while missing entries still trigger endpoint queries. - Normalized quantities are floating point. The output is intended for empirical analysis rather than exact integer accounting; retaining the original logs allows recovery of integer quantities.
- No performance benchmark is reported. The paper states that processing rates depend on endpoint latency and capacity, batch size, and metadata cache misses, and explicitly claims no throughput advantage over other extraction tools.
Methodology in Plain English
The author built a library rather than running an empirical study. The package takes a transaction position — a block number plus a transaction index — along with a protocol selection and an optional pool address, retrieves the transaction, receipt, and block over an Ethereum JSON-RPC endpoint using Requests, and uses web3.py for contract calls that fetch pool and token metadata and for address checksum conversion. A session object loads contract interfaces and caches pool and token metadata across calls, and requests for multiple positions are batched with results yielded incrementally so records need not accumulate in memory.
The decoding itself is written directly in Python: parsers read event topics and fixed-width data fields out of the receipt logs, apply the protocol-specific checks described above, scale amounts by token decimal precision, and hand the event records to an output layer that joins them to transaction and block metadata. Output can retain the raw node payloads or produce one flat row per event.
Verification has three layers. Offline tests exercise event decoding, signed quantities, reserve ordering, pool filtering, and missing values using recorded responses and constructed event logs. An optional integration suite checks the public interface against a live endpoint. Continuous integration runs tests, formatting, linting, and strict type checking on Python 3.10 through 3.13. For the demonstration, the recorded transaction is replayed with dexamine 1.1.0: the example ships the full transaction, receipt, and block responses, the transaction hash and capture provenance, and metadata for all three pools and tokens, with metadata captured through contract calls at the recorded block rather than at the latest block, supplied through MetadataResolver.seed. The --check option compares all four rows with the committed JSON, and a separate script independently re-derives each swap's amounts and pool state using ABI decoding and high-precision decimal arithmetic, checking transaction and block identity and decoding the archived metadata calls.
Why This Matters
Empirical DeFi research depends on transformations that are easy to get subtly wrong and hard to audit once buried in project-specific scripts. By publishing the interpretation layer as a standalone library with recorded inputs and offline checks, the paper lowers the cost of building consistent datasets and makes the conversion from logs to observations inspectable. Version 1 of the package has already been used to construct data for an empirical study of price discovery in decentralized markets, an application that requires preserving event sequence and associated pool information.
Real-world applications:
- Market microstructure studies of DEX trading costs and liquidity. Researchers can obtain normalized quantities and post-trade pool state without rebuilding decoding logic for each project.
- Research on arbitrage and transaction ordering. Because each event retains its block index, transaction index, receipt position, and transaction-level gas and fee fields, analysts can describe the conditions under which a trade executed rather than only its timestamp.
- Liquidity provision analysis. Mint and burn events with signed quantities support tracking of pool liquidity changes alongside swaps in the same representation.
- Reproducible replication packages. Shipped recorded responses, seeded metadata, and an offline
--checkpath let others verify published figures without node access.
Industry relevance: The package targets analysts and researchers at universities, data vendors, and protocol teams who need auditable event-level DEX data. Its explicit scope limits matter commercially as well: the shallow destination labeling, the absence of trader identification, and the transaction-level (not per-trade) cost allocation mean the output is a starting point for pipeline construction rather than a finished analytics product. The paper positions dexamine alongside Ethereum ETL, cryo, Graph Node, and TrueBlocks, noting that it does not import or invoke them and that researchers can use such tools to select transactions before passing positions to dexamine.
Future Directions
- Extending coverage beyond Uniswap v2 and v3 on Ethereum mainnet. The current scope is a single chain and two protocol versions; other AMM designs and layer-2 deployments would require new parsers and new event semantics.
- Removing the latest-block metadata dependency. Because pool and token metadata are queried at the latest block and cached, repeated runs can drift even when historical logs are unchanged. Resolving metadata at the historical block by default, rather than relying on
MetadataResolver.seed, would strengthen reproducibility. - Adding exact integer accounting alongside the float output. The paper notes that normalized quantities carry rounding error; a parallel integer or high-precision path would support reconciliation and accounting use cases that the current output explicitly does not serve.
- Benchmarking and reorg handling. No throughput comparison against other extraction tools is claimed, leaving the performance question open, and the paper warns that chain reorganizations can change the transaction at a recent position, which argues for position-handling or reorg-detection support.
- Deeper transaction semantics. Reconstructing internal call paths and trader identity, which the destination labeling deliberately avoids, would enable questions about arbitrage and maximal extractable value that the current output cannot answer.
Target Audience
This paper is most useful to empirical researchers in market microstructure and DeFi who need event-level Uniswap data and want to avoid reimplementing decoding logic; to research software engineers and data engineers building blockchain data pipelines who want a reference design separating RPC access, metadata, protocol interpretation, and output; and to replication-focused economists who value recorded inputs and offline verification. Readers without prior exposure to Ethereum receipts, event logs, and AMM mechanics will need background reading first, and readers seeking econometric results or performance comparisons will not find them here.
Authors’ abstract
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…
The full abstract on arXiv