How URN BTMH Identifies BitTorrent v2 Magnet Links

The urn:btmh Uniform Resource Name (URN) namespace serves as the primary identifier for BitTorrent v2 content by utilizing the self-describing Multihash format instead of legacy single-algorithm hashes. This article breaks down how the urn:btmh namespace is structured, how it encapsulates SHA-256 Merkle root hashes within the Exact Topic (xt) parameter of a magnet link, and how modern BitTorrent clients read this data to uniquely identify, discover, and verify files across a decentralized swarm.

The Shift from BTIH to BTMH

Traditional BitTorrent v1 magnet links rely on the urn:btih (BitTorrent Info Hash) namespace. These legacy identifiers contain a raw SHA-1 hash of the torrent metadata's info dictionary. Due to known collision vulnerabilities in SHA-1 and the need for per-file verification, the BitTorrent v2 specification (BEP 52) transitioned to SHA-256 and introduced the urn:btmh (BitTorrent Multihash) namespace to allow for a more secure and extensible hashing standard.

The Multihash Architecture

The urn:btmh scheme adopts the open Multihash protocol, a self-describing hash format that encodes the hashing algorithm, the digest length, and the actual digest into a single hexadecimal sequence:

  1. Header Prefix: The xt parameter in a magnet URI is written as xt=urn:btmh:<multihash-hex>.
  2. Algorithm Identifier: The first byte (represented as two hex characters) specifies the cryptographic hash function used. For BitTorrent v2, SHA2-256 is assigned the code 0x12.
  3. Digest Length: The second byte specifies the length of the hash in bytes. For SHA2-256, the length is 32 bytes, denoted by 0x20.
  4. Digest Value: The remaining 32 bytes (64 hex characters) represent the root hash of the file or torrent's Merkle tree.

Because of this standard, a canonical BitTorrent v2 urn:btmh string almost always begins with the prefix 1220 followed by the 64-character SHA-256 digest:

xt=urn:btmh:1220[64-character-sha256-hash]

When a BitTorrent client parses a magnet link containing urn:btmh, it executes the following steps:

  • Namespace Detection: The client recognizes urn:btmh as a BitTorrent v2 identifier, signaling that the network must communicate via v2-capable protocols.
  • Algorithm Parsing: The client decodes the 1220 prefix, confirming that the hash function is SHA-256 with a 32-byte payload. This design also leaves room for future cryptographic algorithm upgrades without breaking compatibility.
  • Swarm Matching: The client queries the Distributed Hash Table (DHT) and trackers using this SHA-256 root hash to locate peers hosting the specific Merkle tree.
  • Data Integrity: Unlike v1 torrents, where piece verification is flat, the urn:btmh identifier points to the root of a Merkle tree. This allows individual file blocks to be validated on the fly against the root hash without needing to download adjacent files.

To ensure backward compatibility, many modern magnet links include multiple xt parameters. A hybrid link contains both xt=urn:btih:<sha1-hash> and xt=urn:btmh:1220<sha256-hash>. Clients supporting BitTorrent v2 prioritize the urn:btmh parameter to leverage enhanced security, per-file deduplication, and block-level verification, while falling back to urn:btih when connecting to legacy peers.