[GH-ISSUE #3730] [Feature] Bitcoin reverse engineering: raw transactions, PSBT, Script/Tapscript, descriptors, Miniscript and UTXO-flow reconstruction #1440

New issue

Open

opened 2026-10-16 21:05:26 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:05:26 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3730

Problem Statement & Context

Bitcoin represents the foundational UTXO (Unspent Transaction Output) blockchain architecture. Modern Bitcoin development has evolved significantly beyond legacy P2PKH/P2SH scripts into complex multi-sig policies, smart custody setups, and privacy protocols:

Raw Transaction & Serialization Formats: Legacy, Segregated Witness (SegWit / BIP141), and Taproot (BIP341/342) transaction serializations, parsing inputs, outputs, locktimes, sequence numbers, and witness stacks.
Partially Signed Bitcoin Transactions (PSBT v0 & v2 / BIP174, BIP370): Key-value binary maps containing global, input, and output maps. Tracks BIP32 derivation paths, non-witness and witness UTXOs, sighash types, partial signatures, Taproot key/script spend trees, and MuSig2 aggregation metadata.
Script, Tapscript & Execution Engine: Forth-like stack-based bytecode (OP_CHECKSIG, OP_CHECKMULTISIG, OP_CHECKLOCKTIMEVERIFY, OP_CHECKSEQUENCEVERIFY, OP_CHECKSIGADD).
Output Descriptors & Miniscript: Standardized human-readable and machine-analyzable spending policies (wpkh(), wsh(), tr(), Miniscript Boolean expressions modeling and, or, thresh, older, after).
UTXO Graph & Transaction Lineage: Graphing spending chains, change detection heuristics, and multi-input clustering across analyst-provided transaction datasets.

REA currently lacks a dedicated Bitcoin engine capable of parsing raw transactions, inspecting PSBT signing states, disassembling Taproot trees, and modeling Miniscript policies offline.

Proposed Architecture

flowchart TD
    A["Bitcoin Artifact (Raw Hex Tx / PSBT Base64 / Block Dump / Descriptor)"] --> B["Bitcoin Semantic Engine"]
    B --> C["Transaction & PSBT Deserializer"]
    B --> D["Script & Tapscript Decompiler"]
    B --> E["Descriptor & Miniscript Policy Analyzer"]
    B --> F["UTXO Flow & Lineage Reconstructor"]
    
    C --> C1["SegWit & Taproot Serialization Parser"]
    C --> C2["PSBT v0 / v2 Map Entries & Signer Metadata"]
    
    D --> D1["Opcode Disassembly & Stack Semantics"]
    D --> D2["Taproot Mast Tree & Script Leaf Decoding"]
    
    E --> E1["Output Descriptors (wpkh, wsh, tr)"]
    E --> E2["Miniscript Policy AST & Spending Conditions"]
    
    F --> F1["Input-to-Output Flow & Change Detection"]
    F --> F2["Timelock & Multisig Threshold Graphs"]
    
    C & D & E & F --> G["Synthesized Bitcoin Transaction Blueprint & Spending Policy Flowchart"]

Technical Capabilities & Modules

Raw Transaction & Block Parsing:
- Deserialize raw transaction byte streams supporting legacy, SegWit (marker 0x00, flag 0x01), and Taproot formats.
- Decode input outpoints (TxID + Vout), scriptSig, nSequence (BIP68 relative timelocks), outputs (value in satoshis + scriptPubKey), and nLockTime (BIP65 absolute timelocks).
PSBT v0 and v2 Inspection:
- Parse binary PSBT maps: Global, Inputs, and Outputs.
- Extract BIP32 key derivations (fingerprints + paths), proprietary fields, sighash types, and partial signatures.
- Decode Taproot PSBT fields: internal keys, Taproot output keys, leaf hashes, script trees, and MuSig2 participant states without signing.
Script & Tapscript Disassembly:
- Disassemble Bitcoin Script opcodes into clean symbolic representations.
- Trace execution semantics on an abstract stack to determine satisfiability conditions.
- Reconstruct Taproot MAST (Merkelized Alternative Script Tree) hierarchies: internal key, leaf scripts, leaf versions, and parity bits.
Output Descriptors & Miniscript Analysis:
- Parse standard output script descriptors: pk(), pkh(), wpkh(), sh(), wsh(), tr().
- Parse Miniscript expressions: compile spending policies into logical trees detailing required signatures, time delays (older(), after()), and hash preimages (sha256(), ripemd160()).
- Audit spending policies for malleability risks or unreachable spending branches.
UTXO Lineage & Spending Graph:
- Build a directed acyclic graph (DAG) tracing transaction inputs back to parent UTXOs across provided transaction batches.
- Apply standard change output heuristics (round values, script type matching) to model economic transfer flows.

Acceptance Criteria

Static decoding of raw Bitcoin transactions across Legacy, SegWit, and Taproot.
Complete parsing and auditing of PSBT v0 and v2 packages, detailing missing signatures and required keys.
Disassembly of Tapscript leaves and visualization of Taproot script trees.
Parsing and AST validation of Miniscript spending policies.
Generation of an interactive UTXO flow graph depicting inputs, outputs, and locktime constraints.

Complements #3621 (Unknown binary file-format inference)
Complements #3698 (Interactive entertainment and asset reverse engineering tracker)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3730 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Blockchain RE](https://img.shields.io/badge/domain-blockchain_RE-orange.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ### Problem Statement & Context Bitcoin represents the foundational UTXO (Unspent Transaction Output) blockchain architecture. Modern Bitcoin development has evolved significantly beyond legacy P2PKH/P2SH scripts into complex multi-sig policies, smart custody setups, and privacy protocols: 1. **Raw Transaction & Serialization Formats**: Legacy, Segregated Witness (SegWit / BIP141), and Taproot (BIP341/342) transaction serializations, parsing inputs, outputs, locktimes, sequence numbers, and witness stacks. 2. **Partially Signed Bitcoin Transactions (PSBT v0 & v2 / BIP174, BIP370)**: Key-value binary maps containing global, input, and output maps. Tracks BIP32 derivation paths, non-witness and witness UTXOs, sighash types, partial signatures, Taproot key/script spend trees, and MuSig2 aggregation metadata. 3. **Script, Tapscript & Execution Engine**: Forth-like stack-based bytecode (`OP_CHECKSIG`, `OP_CHECKMULTISIG`, `OP_CHECKLOCKTIMEVERIFY`, `OP_CHECKSEQUENCEVERIFY`, `OP_CHECKSIGADD`). 4. **Output Descriptors & Miniscript**: Standardized human-readable and machine-analyzable spending policies (`wpkh()`, `wsh()`, `tr()`, Miniscript Boolean expressions modeling `and`, `or`, `thresh`, `older`, `after`). 5. **UTXO Graph & Transaction Lineage**: Graphing spending chains, change detection heuristics, and multi-input clustering across analyst-provided transaction datasets. REA currently lacks a dedicated Bitcoin engine capable of parsing raw transactions, inspecting PSBT signing states, disassembling Taproot trees, and modeling Miniscript policies offline. ### Proposed Architecture ```mermaid flowchart TD A["Bitcoin Artifact (Raw Hex Tx / PSBT Base64 / Block Dump / Descriptor)"] --> B["Bitcoin Semantic Engine"] B --> C["Transaction & PSBT Deserializer"] B --> D["Script & Tapscript Decompiler"] B --> E["Descriptor & Miniscript Policy Analyzer"] B --> F["UTXO Flow & Lineage Reconstructor"] C --> C1["SegWit & Taproot Serialization Parser"] C --> C2["PSBT v0 / v2 Map Entries & Signer Metadata"] D --> D1["Opcode Disassembly & Stack Semantics"] D --> D2["Taproot Mast Tree & Script Leaf Decoding"] E --> E1["Output Descriptors (wpkh, wsh, tr)"] E --> E2["Miniscript Policy AST & Spending Conditions"] F --> F1["Input-to-Output Flow & Change Detection"] F --> F2["Timelock & Multisig Threshold Graphs"] C & D & E & F --> G["Synthesized Bitcoin Transaction Blueprint & Spending Policy Flowchart"] ``` ### Technical Capabilities & Modules 1. **Raw Transaction & Block Parsing:** - Deserialize raw transaction byte streams supporting legacy, SegWit (marker `0x00`, flag `0x01`), and Taproot formats. - Decode input outpoints (TxID + Vout), scriptSig, nSequence (BIP68 relative timelocks), outputs (value in satoshis + scriptPubKey), and nLockTime (BIP65 absolute timelocks). 2. **PSBT v0 and v2 Inspection:** - Parse binary PSBT maps: Global, Inputs, and Outputs. - Extract BIP32 key derivations (fingerprints + paths), proprietary fields, sighash types, and partial signatures. - Decode Taproot PSBT fields: internal keys, Taproot output keys, leaf hashes, script trees, and MuSig2 participant states without signing. 3. **Script & Tapscript Disassembly:** - Disassemble Bitcoin Script opcodes into clean symbolic representations. - Trace execution semantics on an abstract stack to determine satisfiability conditions. - Reconstruct Taproot MAST (Merkelized Alternative Script Tree) hierarchies: internal key, leaf scripts, leaf versions, and parity bits. 4. **Output Descriptors & Miniscript Analysis:** - Parse standard output script descriptors: `pk()`, `pkh()`, `wpkh()`, `sh()`, `wsh()`, `tr()`. - Parse Miniscript expressions: compile spending policies into logical trees detailing required signatures, time delays (`older()`, `after()`), and hash preimages (`sha256()`, `ripemd160()`). - Audit spending policies for malleability risks or unreachable spending branches. 5. **UTXO Lineage & Spending Graph:** - Build a directed acyclic graph (DAG) tracing transaction inputs back to parent UTXOs across provided transaction batches. - Apply standard change output heuristics (round values, script type matching) to model economic transfer flows. ### Acceptance Criteria - [ ] Static decoding of raw Bitcoin transactions across Legacy, SegWit, and Taproot. - [ ] Complete parsing and auditing of PSBT v0 and v2 packages, detailing missing signatures and required keys. - [ ] Disassembly of Tapscript leaves and visualization of Taproot script trees. - [ ] Parsing and AST validation of Miniscript spending policies. - [ ] Generation of an interactive UTXO flow graph depicting inputs, outputs, and locktime constraints. ### Related Issues & Dependencies - Complements #3621 (Unknown binary file-format inference) - Complements #3698 (Interactive entertainment and asset reverse engineering tracker)

bsakaguchi referenced this issue

2026-10-17 21:11:26 +00:00

[PR #1440] [MERGED] docs(process): verify independent full-report hashing budgets #2889

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#1440

No description provided.

Rows
Columns