Awesome-Lenz: Bitcoin Transaction Parser & Visualizer

Awesome-Lenz is a tool I built to turn raw Bitcoin transactions into precise, machine-checkable JSON reports, paired with a web visualizer that explains those transactions to non-technical users using diagrams, annotations, and accessible language.

This is a heavily protocol-focused project. Instead of relying on external APIs, I built the parsing logic from the ground up based on Bitcoin transaction serialization and accounting rules to make the implementation robust against edge cases.

---

Project Scope & Assumptions

• Focus: The tool handles deep parsing, accounting, and script classification. It does not validate signatures or execute scripts.
• Data Source: It assumes input fixtures provide all required prevouts. It does not need to connect to an external node to fetch missing data.
• Network: Designed for Bitcoin Mainnet.

Core Components

The repository contains two main entry points:

1. cli.sh (CLI Analyzer)

A highly strict, machine-readable parser that reads raw hex and outputs detailed JSON reports.

• Operates in single-transaction mode or block parsing mode.
• Writes outputs to an out/ directory.
• Exits with standard 0 (success) or 1 (error) codes, making it easy to pipe into other scripts.

2. web.sh (Web Visualizer)

A user-friendly web interface running on top of the parser logic.

• Translates technical JSON into a "story" view (What happened? Who paid whom? What did it cost?).
• Features interactive graphs showing value flow and highlighting fees.
• Includes tooltips and plain-English explanations for concepts like SegWit, vbytes, and RBF.

---

Modes of Operation

Single-Transaction Analysis

By default, the CLI parses individual transaction fixtures.

Usage: bash ./cli.sh fixtures/transactions/tx_sample.json

Input Format: json { "network": "mainnet", "raw_tx": "0200000001...", "prevouts": [ { "txid": "11...aa", "vout": 0, "value_sats": 123456, "script_pubkey_hex": "0014..." } ] }

Block Parsing Mode

I also built native support for parsing raw Bitcoin Core block data files (blk*.dat), undo files (rev*.dat), and XOR keys (xor.dat).

Usage: bash ./cli.sh --block blk00000.dat rev00000.dat xor.dat

In this mode, the parser:

1. XOR-decodes the data (if obfuscated).
2. Parses the 80-byte block header and all transactions.
3. Parses the undo data to recover prevouts for all non-coinbase inputs (mirroring how Bitcoin Core handles reorgs).
4. Verifies the computed merkle root against the header.
5. Identifies the coinbase transaction and decodes the BIP34 block height.

Block Mode Output Example: json { "ok": true, "mode": "block", "block_header": { "version": 536870912, "prev_block_hash": "...", "merkle_root": "...", "merkle_root_valid": true, "timestamp": 1710000000, "bits": "...", "nonce": 12345, "block_hash": "..." }, "tx_count": 150, "coinbase": { "bip34_height": 800000, "coinbase_script_hex": "...", "total_output_sats": 631250000 }, "block_stats": { "total_fees_sats": 6250000, "total_weight": 3996000, "avg_fee_rate_sat_vb": 25.1, "script_type_summary": { "p2wpkh": 420, "p2tr": 180, "p2sh": 55, "p2pkh": 30 } } }

---

Technical Features

Detailed Script Classification

The tool classifies both input and output scripts into standard types (p2pkh, p2sh, p2wpkh, p2wsh, p2tr, op_return, unknown) and derives the corresponding mainnet addresses. For nested SegWit, it correctly identifies p2sh-p2wpkh and p2sh-p2wsh.

Full Script Disassembly

Generates space-separated opcode tokens for scriptPubKey and scriptSig. It supports all standard Bitcoin Core opcodes and renders data pushes correctly (e.g., OP_PUSHBYTES_20, OP_PUSHDATA4).

OP_RETURN Decoding

Extracts and parses OP_RETURN payloads, concatenating multiple push operations. It attempts UTF-8 decoding and detects known data protocols (like Omni or OpenTimestamps).

Advanced Feerate & SegWit Analysis

Computes size_bytes, weight, and vbytes strictly according to BIP141. For SegWit transactions, it calculates exact weight savings compared to legacy constructions.

Timelock & RBF Detection

• Detects BIP125 Replace-By-Fee (RBF) signaling.
• Decodes absolute locktimes (block height vs. UNIX timestamp).
• Parses BIP68 relative timelocks per input (blocks vs. time).

Smart Warning System

The parser flags edge cases or inefficiencies, such as:

• HIGH_FEE (>1M sats or >200 sat/vB)
• DUST_OUTPUT (<546 sats on non-OP_RETURN)
• UNKNOWN_OUTPUT_SCRIPT
• RBF_SIGNALING

---

Web Visualizer

The web app is designed to make the heavily technical outputs of the CLI easy to understand.

Features:

• Value Flow Graph: Visualizes inputs on the left, outputs on the right, and the miner fee as the "missing slice."
• Educational Tooltips: Explains Bitcoin-specific jargon inline.
• Progressive Disclosure: Hides raw hex/assembly data by default, with a "Show Technical Details" toggle for power users.
• Block Dashboard: When uploading raw .dat files, it presents a high-level block summary alongside a searchable, expandable transaction list.
• Offline Capable: Requires no external APIs to run once cloned.

---

Supported Scenarios & Edge Cases

I built the parser to handle complex and obscure transaction types, including:

• Taproot keypath (1 witness item) and scriptpath spends (control blocks).
• Complex P2WSH witnessScripts.
• Mixed relative/absolute timelocks and RBF signaling.
• OP_RETURN payloads with extended pushes (OP_PUSHDATA1/2/4) or non-UTF8 binary data.
• Malformed block data (invalid merkle roots, truncated undo data).
• Legacy Bitcoin Core undo data formats (special-type compression for P2PKH/P2SH, compressed P2PK scripts).