Metadata-Version: 2.4
Name: tx-forensics
Version: 0.1.0
Summary: Transaction Forensics TUI — analyze traces for balance divergence & more
Author: CE Hirschauer
License: All Rights Reserved
Project-URL: Homepage, https://github.com/74Thirsty
Project-URL: Source, https://github.com/74Thirsty
Keywords: forensics,ethereum,trace,balance-divergence,tui,textual
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=1.0
Requires-Dist: rich>=13.0
Dynamic: license-file

# Transaction Forensics TUI

A Textual-based terminal UI for analyzing Ethereum transaction traces — detects balance divergence, decodes revert errors, and provides full forensic breakdowns from JSON forensic artifacts or CSV traces.

## Features

- **Forensic analysis** from JSON artifacts (tx info, trace calls, token deltas, errors)
- **CSV trace support** (Etherscan trace exports)
- **Balance divergence detection** — spots vesting/rebasing token shortfalls
- **Decoded revert errors** — Error(string), Panic(uint256), and raw hex
- **Export** results to CSV and JSON
- **Toggleable sections** — trace, errors, gas analysis, token deltas

## Installation

```bash
pip install tx-forensics
```

## Usage

```bash
# Launch interactive TUI
tx-forensics

# Analyze a specific file (JSON or CSV)
tx-forensics --file trace.json
tx-forensics --file trace.csv

# Batch CLI mode with JSON output
tx-forensics --file trace.csv --json

# Quiet mode (exit code only)
tx-forensics --file trace.csv --quiet
```

### Keyboard bindings (TUI)

| Key | Action |
|-----|--------|
| `q` / `Escape` | Quit / Go back |
| `t` | Toggle trace section |
| `e` | Toggle errors section |
| `g` | Toggle gas section |
| `d` | Toggle deltas section |
| `c` | Export CSV |
| `j` | Export JSON |

## Input Formats

- **JSON** — full forensic artifacts (generated by VANTAGE `tx-forensic-gui.py`)
- **CSV** — Etherscan trace exports

## License

All Rights Reserved — Copyright 2026 CE Hirschauer
