How Torrent Clients Download Magnet Link Metadata

When you click a magnet link, your torrent client receives only a cryptographic identifier rather than a complete blueprint of the files you wish to download. Unlike traditional .torrent files, which contain full file listings and piece hashes, a magnet link requires the client to dynamically fetch this missing metadata from other peers in the swarm. This process involves parsing the link's info hash, querying decentralized networks to locate active peers, negotiating protocol extensions, downloading the metadata in blocks, and verifying its cryptographic integrity before file transfers can begin.

1. Parsing the Magnet URI

The process begins the moment the magnet URI is loaded into the client. The client parses the uniform resource identifier to extract critical parameters:

  • The Exact Topic (xt): The cryptographic info hash (usually a 40-character hexadecimal SHA-1 hash for BitTorrent v1, or a 64-character SHA-256 hash for BitTorrent v2). This hash serves as the unique global identifier for the swarm.
  • Trackers (tr): Optional URLs pointing to centralized tracker servers.
  • Display Name (dn): A temporary filename shown in the UI while the real metadata is pending.

2. Peer Discovery

Because the client does not yet know the file structure, it must immediately find peers that possess the full .torrent file. It does this via multiple discovery mechanisms simultaneously:

  • Distributed Hash Table (DHT): The client queries its local Kademlia-based DHT routing table with a get_peers message, using the info hash as the target key. Neighboring DHT nodes return IP addresses and ports of peers associated with that hash.
  • Trackers: If tracker URLs are embedded in the magnet link, the client sends HTTP or UDP scrape and announce requests to obtain peer lists.
  • Peer Exchange (PEX) and Local Peer Discovery (LSD): Once initial connections are made, the client queries those peers for additional nodes or broadcasts on the local subnet.

3. The Extension Handshake (BEP 10)

Once the client establishes a TCP or uTP connection with a peer, both clients perform the standard BitTorrent protocol handshake. Immediately following this, they initiate the BitTorrent Extension Protocol (BEP 10).

During the BEP 10 handshake, the clients exchange a dictionary of supported extended features. The initiating client looks for support for BEP 9 (Extension for Transferring Metadata), commonly identified in the handshake as ut_metadata. If supported, the remote peer sends the total byte size of the metadata dictionary alongside an ID number allocated for metadata messages.

4. Requesting Metadata Blocks (BEP 9)

BitTorrent metadata can be several megabytes in size for torrents containing thousands of files. To transfer it efficiently, the client treats the metadata dictionary as a mini-payload divided into fixed 16 KiB (16,384 bytes) blocks.

  1. Calculation: The client calculates how many 16 KiB pieces it needs based on the total metadata size reported by the peer.
  2. Requesting (msg_type: 0): The client sends request messages to one or more connected peers, asking for specific metadata piece indexes.
  3. Receiving (msg_type: 1): Peers respond with data messages containing the raw binary payload of the requested 16 KiB block.
  4. Rejection Handling (msg_type: 2): If a peer is overloaded or lacks the metadata, it sends a reject message, prompting the client to request that block from a different peer.

5. Verification and Swarm Initialization

After all metadata blocks are successfully received in memory:

  1. Assembly: The client concatenates the 16 KiB slices in sequential order to form the complete Bencoded info dictionary.
  2. Hash Verification: The client generates a SHA-1 (or SHA-256) hash of the assembled info dictionary and compares it against the info hash originally extracted from the magnet link.
  3. Failure or Success: If the generated hash does not match, the payload is discarded as corrupted or malicious, and the client restarts the request cycle. If the hash matches perfectly, the metadata is verified.

Once verified, the client decodes the file tree, file sizes, piece lengths, and individual SHA-1 piece hashes. The UI updates to show the real file list, pre-allocates disk space if configured, and transitions the torrent task into standard data piece downloading.