BitTorrent v2 (BEP 52) Support Audit
=====================================
Date: 2025-12-01
Overall Compliance: ~40% (Metainfo framework only)
Status: V2 torrents CANNOT be downloaded with current codebase

=====================================
WHAT'S IMPLEMENTED (Working)
=====================================

1. Info Hash (32-byte SHA-256) - COMPLETE
   - File: src/metainfo/info_hash.rs (371 lines)
   - InfoHashV2 struct with proper SHA256 hashing
   - Hex encoding/decoding for 64-character strings
   - Hybrid (BEP-47) support for dual v1/v2 hashes

2. File Tree Parsing - COMPLETE
   - File: src/metainfo/file_tree.rs (154 lines)
   - FileTree enum with File/Directory variants
   - Per-file pieces_root field (32-byte Merkle root)
   - Hierarchical structure handling
   - Flatten-to-flat-list conversion

3. Torrent Version Detection - COMPLETE
   - File: src/metainfo/torrent.rs (lines 150-162)
   - Correctly identifies V1, V2, and Hybrid torrents
   - Proper info hash algorithm selection per version

4. Magnet Link V2 Support - COMPLETE
   - File: src/metainfo/magnet.rs (272 lines)
   - Parses urn:btmh:1220 prefix
   - Generates correct v2 magnet URIs

5. Merkle Tree Implementation - COMPLETE (but unused)
   - File: src/metainfo/merkle.rs (126 lines)
   - Tree construction from 32-byte SHA256 hashes
   - Proof generation and verification
   - Proper power-of-two padding

=====================================
CRITICAL MISSING FEATURES
=====================================

1. PIECE LAYERS - NOT IMPLEMENTED
   Impact: FATAL - Cannot read piece hashes from v2 torrents

   BEP 52 requires v2 torrents to use a "piece layers" dictionary
   instead of the v1 "pieces" field. Current code in torrent.rs
   (lines 281-297) is hardcoded to read v1 format only:

       let pieces_bytes = dict
           .get(b"pieces".as_slice())  // WRONG - only reads v1 format
           ...

   This will FAIL on all pure v2 torrents.

2. FILE TREE NOT INTEGRATED
   Impact: HIGH - Multi-file v2 torrents cannot be downloaded

   The FileTree struct exists and parses correctly, but
   Metainfo::from_bytes() never uses it:
   - Line 174 calls parse_info() unconditionally
   - parse_info() always uses v1-only logic
   - File struct has no pieces_root field
   - Flattening of file tree never happens

3. PEER PROTOCOL V2 - NOT IMPLEMENTED
   Impact: CRITICAL - Cannot download data from v2-capable peers

   Missing:
   - Message ID 21: HashRequest
   - Message ID 22: Hashes
   - Message ID 23: HashReject
   - Merkle proof exchange in peer protocol

   File: src/peer/message.rs has no v2 support

4. BLOCK-LEVEL MERKLE VERIFICATION - NOT IMPLEMENTED
   Impact: HIGH - Cannot verify partial blocks

   BEP 52 supports merkle proofs for individual blocks, but:
   - BlockCache only does flat hash verification (v1-style)
   - MerkleTree::verify() is implemented but never called
   - No merkle proof exchange in peer protocol

5. PIECE LENGTH VALIDATION - NOT IMPLEMENTED
   Impact: MEDIUM - Invalid torrents accepted

   BEP 52 requires:
   - Piece length MUST be power of 2
   - Minimum 16 KiB (16384 bytes)

   Current code (line 276-279) accepts any integer.

6. PADDING FILES - NOT IMPLEMENTED
   Impact: LOW - File alignment issues in some torrents

   BEP 52 feature: Special padding files marked with attr: "p"
   Not recognized or handled.

=====================================
ARCHITECTURAL PROBLEMS
=====================================

Problem 1: Mismatched Data Structures
- Info struct only has pieces: Vec<[u8; 20]> (v1 SHA1)
- File struct has no pieces_root field
- Cannot polymorphically handle v1 and v2 piece hashes

Problem 2: Orphaned Code
- FileTree::from_bencode() is written but never called
- FileTreeEntry::pieces_root is parsed then discarded
- MerkleTree verification exists but is unused at runtime

Problem 3: Hardcoded V1 Parser
- parse_info() only reads v1 "pieces" and "length"/"files" fields
- No branching on TorrentVersion enum
- Would fail even if piece layers were in the dict

Problem 4: No Runtime Integration
- Merkle tree code is present but never invoked during downloads
- Block cache uses flat hash verification only
- Peer protocol has no v2 support

=====================================
WHY V2 DOWNLOADS FAIL
=====================================

1. Torrent is detected as V2 (detection works)
2. parse_info() tries to read "pieces" (doesn't exist in v2)
3. Parser returns MissingField("pieces") error
4. Metainfo::from_bytes() fails (entire torrent rejected)

Even if a v2 torrent somehow loaded, it would fail again because:
- File tree is never parsed or flattened
- No peer protocol support for v2
- No merkle tree verification

=====================================
IMPLEMENTATION CHECKLIST
=====================================

Feature                      | Implemented | Integrated | Working
-----------------------------|-------------|------------|--------
Info Hash (32-byte SHA256)   | Yes         | Yes        | Yes
File Tree Parsing            | Yes         | No         | No
Piece Layers Dictionary      | No          | No         | No
Merkle Tree Code             | Yes         | No         | No
Per-File Merkle Root         | Partial     | No         | No
Piece Length Validation      | No          | No         | No
Torrent Version Detection    | Yes         | Yes        | Yes
Hybrid Torrent Support       | Partial     | Yes        | Partial
Magnet Links (v2)            | Yes         | Yes        | Yes
Peer Protocol (v2)           | No          | No         | No
Block-Level Merkle Verify    | No          | No         | No
Padding Files                | No          | No         | No

=====================================
KEY FILES TO FIX
=====================================

Critical (Reading torrents):
- src/metainfo/torrent.rs (lines 281-297, 174, 316)
  - Replace hardcoded v1 parser with conditional logic
  - Parse piece layers dict for v2
  - Parse and integrate file tree

Important (Storage):
- src/storage/file.rs
  - Add pieces_root: Option<[u8; 32]> to File struct

Critical (Protocol):
- src/peer/message.rs
  - Add v2 extension messages (21, 22, 23)
  - Add merkle proof handling

Integration (Verification):
- src/cache/block_cache.rs
  - Wire merkle verification into piece validation

=====================================
ESTIMATED EFFORT TO FULL COMPLIANCE
=====================================

Current: 40% (metainfo framework)
Missing: 60% (integration + protocol + verification)

Task Breakdown:
- Parse piece layers dictionary: 1 week
- Integrate file tree & merkle verification: 1 week
- Peer protocol v2 messages: 1-2 weeks
- Testing & edge cases: 1 week

Total: 4-5 weeks for one developer

Critical path: Peer protocol support (blocks all downloading)

=====================================
SUMMARY
=====================================

The rbit library has a solid metainfo parsing framework but
critical gaps prevent v2 functionality:

1. Can parse v2 info hashes but cannot read piece hashes
2. File tree parsing works but is never used
3. Merkle tree implementation complete but not integrated
4. Peer protocol has no v2 support
5. No piece length validation

Conclusion: rbit currently supports BEP 52 at the metainfo
detection level only. To actually download v2 torrents,
the integration work described above must be completed.
