Chain-Lens is a high-performance Bitcoin transaction and block analyzer built from scratch during the Summer of Bitcoin 2025 bootcamp. It consists of a protocol-accurate CLI engine and an interactive web visualizer designed to simplify low-level cryptographic data for non-technical users.
1. Execution Engine & CLI
The CLI tool (executed via cli.sh) operates in two primary modes to parse raw serialized Bitcoin data structures without relying on third-party node APIs:
- Transaction Mode (Default): Parses raw transaction hex payloads, reads input/output vectors, resolves matching prevouts, and outputs complete correctness-verified JSON summaries.
-
Block Mode: Parses raw block data direct from Bitcoin Core
blk*.datfiles and matches spent inputs utilizing Core's undo record database files (rev*.dat). It decodes obfuscated block files by applying an XOR-decode mask derived from the user's database settings.
2. Protocol Accounting & BIP Implementations
The parser implements strict consensus rules and transaction serialization specifications:
- BIP141 Segregated Witness (SegWit): Computes transaction sizes, weight units, and virtual sizes (vbytes). It measures witness discount efficiency by comparing the actual SegWit weight against hypothetical legacy serialized weights.
- Relative & Absolute Timelocks: Detects absolute timelock type constraints (by block height or Unix epoch timestamp). Evaluates relative locktime constraints (via BIP68 Sequence locks) on input streams, classifying locks in block counts or seconds.
- BIP125 RBF (Replace-by-Fee): Evaluates sequence values across inputs to determine replaceability status.
- BIP34 Height Verification: In block mode, extracts the coinbase scriptSig payload to verify the encoded block height matches the block header index.
3. Script Decoding & Classification
Inputs and outputs are analyzed down to raw stack operations for precise classification:
-
Script Disassembly: Translates scriptPubKey hex payloads into clean, space-separated assembly instructions using standard OP code naming conventions (supporting direct data pushes and extended opcodes like
OP_PUSHDATA1/2/4). -
Script Types & Address Derivation: Identifies and formats output scripts including
p2pkh,p2sh,p2wpkh,p2wsh, and Taproot (p2tr), generating valid mainnet Bech32/Bech32m or Base58Check addresses. - OP_RETURN Metadata: Isolates embedded metadata payloads and decodes protocols using prefix heuristics (e.g., identifying Omni Layer or OpenTimestamps records).
4. Web-Based Visualizer
The web visualization frontend (served via web.sh) translates serialized data into a structured layout:
- Value Flow Graph: Displays inputs on the left and outputs on the right, highlighting transaction fee margins as the unallocated difference.
- Explainers & Warnings: Offers step-by-step plain English explanations of cryptographic scripts, and flags critical warnings like dust outputs (non-OP_RETURN outputs under 546 satoshis), abnormal fees, and unknown script patterns.