metamesh-plugin-fullhash/docs/btih_v2.md

BitTorrent v2 Hashes (BEP 52)

Purpose

Generate BitTorrent v2 compatible hashes for magnet links and peer verification. Enables creating magnet links for files without a full .torrent file.

Two Output Hashes

1. Pieces Root (cid_bt_pieces_root)

• Multicodec: 0xb702 (official bittorrent-pieces-root)
• CID codec: 0x55 (raw)
• Description: Merkle tree root of SHA-256 hashes of 16KB file blocks
• Use case: File verification, piece-level integrity checking

2. Info Hash (cid_bt_info_hash)

• Multicodec: 0x12 (standard SHA-256)
• CID codec: 0x55 (raw)
• Description: SHA-256 of bencoded info dictionary
• Use case: Magnet links, torrent identification

Algorithm

1. Read file in 16KB blocks
2. SHA-256 hash each block (pad last block with zeros)
3. Build merkle tree from leaf hashes:
   - Pad to next power of 2 with zero hashes
   - Each parent = SHA-256(left_child || right_child)
   → Result: pieces_root (32 bytes)

4. Create info dictionary:
   {
     "file tree": { filename: { "": { "length": N, "pieces root": <pieces_root> } } },
     "meta version": 2,
     "name": filename,
     "piece length": 16384
   }

5. Bencode the dictionary
6. SHA-256(bencoded_info)
   → Result: info_hash (32 bytes)

Merkle Tree Structure

                    [Root]
                   /      \
            [Node]          [Node]
           /      \        /      \
        [Leaf0] [Leaf1] [Leaf2] [Zero]

Leaf = SHA-256(16KB block)
Node = SHA-256(left || right)

Magnet Link Generation

magnet:?xt=urn:btmh:1220<info_hash_hex>&dn=<filename>

Where:

• btmh = BitTorrent Multihash
• 1220 = 0x12 (SHA-256 code) + 0x20 (32 bytes = 0x20 in hex)
• info_hash_hex = 64 hex characters
• dn = display name (URL-encoded filename)

Example

File: ubuntu-24.04-desktop-amd64.iso
Info Hash: a1b2c3d4...
Magnet: magnet:?xt=urn:btmh:1220a1b2c3d4...&dn=ubuntu-24.04-desktop-amd64.iso

BEP 52 Compliance

This implementation follows BEP 52:

Requirement	Implementation
Block size	16 KiB (16,384 bytes)
Piece size	16 KiB (minimum, power of 2)
Hash algorithm	SHA-256
Merkle tree	Binary, power-of-2 padded
Info dict	v2 format with file tree
Meta version	2 (v2-only torrent)

Properties

Property	Pieces Root	Info Hash
Hash size	32 bytes	32 bytes
Algorithm	Merkle SHA-256	SHA-256
Multicodec	0xb702 (official)	0x12 (SHA-256)
Time complexity	O(n)	O(n)
Space complexity	O(log n)	O(1)

Use Cases

1. Magnet link creation - Share files via magnet links without .torrent files
2. Peer verification - Verify file integrity in BitTorrent v2 swarms
3. Deduplication - Identify identical files across BitTorrent network
4. Hybrid torrents - Create v1+v2 hybrid torrents

Limitations

• Pieces root depends on filename (included in info dict)
• Single-file torrents only (no multi-file directory support)
• Requires full file read for both hashes

References

• BEP 52: The BitTorrent Protocol Specification v2
• Multicodec Table - bittorrent-pieces-root = 0xb702