Pieces and verification
A file transferred from strangers arrives intact because every piece of it was hashed before the transfer began and is checked against that hash on arrival, which is also why a torrent file hash checker is already built into every BitTorrent client: checking hashes is not an optional extra in this protocol, it is the protocol.
The torrent carries one cryptographic hash for every piece of the data, and the client compares each arriving piece against its hash before counting it as received. A piece that does not match is thrown away whole and requested again from a different machine, so nothing that fails is ever written into the finished file.
What a piece is, and what its hash proves
A piece is a fixed length block of the data, numbered from zero, and it is the unit the protocol counts in. Pieces run straight across file boundaries, so in a torrent with three files a single piece can hold the end of one and the start of the next. Only the final piece is shorter, because the total rarely divides evenly.
Each piece has a hash stored in the torrent's info dictionary, 20 bytes long in the original version of the format, written as 40 hexadecimal characters when a human reads one. What the hash proves is narrow and absolute: this run of bytes is bit for bit the run the torrent describes. It proves nothing about who sent it, and nothing about whether the person who built the torrent was honest.
How the info hash becomes a magnet link
The info hash is a hash of the description rather than of the data, and it is what a magnet link carries. The client takes the info dictionary exactly as encoded in the torrent file, hashes that block, and the result identifies this torrent across the network. Writing a magnet link from it is formatting: magnet:?xt=urn:btih: followed by the hash in hexadecimal, with a display name and any trackers appended as extras.
That relationship runs one way only, which is the point of using a hash. Any machine produces the magnet link from a torrent file offline in an instant. No machine produces the torrent file from a magnet link by calculation, because reversing the hash is what a cryptographic hash is designed to prevent. Every generator that turns an info hash into a magnet link is doing string formatting; every tool that turns a magnet link into a torrent file is doing a download.
How to check a torrent's own hashes without a separate tool
Force recheck is the checker, and it is a menu item on the torrent in every client. It reads the data already on disk, hashes each piece, and compares the results against the stored hashes. Matching pieces are marked present, the rest are queued again. The state during this is checking, which is neither downloading nor stalled: nothing is arriving, and nothing is wrong.
- Stop the torrent first, so nothing writes to the files while they are read.
- Choose force recheck from the context menu in qBittorrent, Transmission or Deluge.
- Watch the percentage, which counts pieces verified rather than bytes downloaded.
- Restart the torrent, and let the client fetch whatever the check marked missing.
Rechecking answers four situations: a transfer that finished but produced a file the target program will not open, files copied in from elsewhere that you want the client to adopt, a crash during writing, and a disk that has thrown errors. It is also how a client accepts data you already have.
How piece length is chosen, and what a bad choice costs
Piece length is chosen when the torrent is created and can never change, because changing it changes the info hash and so creates a different torrent. It is conventionally a power of two, and the version 2 format makes that a requirement. It is often a quarter or half a megabyte for a set of ordinary size and larger for very big ones. The person building the torrent picks it, and the trade runs both ways.
| Piece length | Effect on the torrent file | Effect on the transfer |
|---|---|---|
| Small | More pieces, so more hashes, so a larger torrent file | Less data lost when a piece fails, and finer progress reporting |
| Large | Fewer hashes, so a compact torrent file even for a huge set | More data discarded per failed piece, and a slower first piece to complete |
This is why a torrent describing many gigabytes, such as a Linux installation image, does not come with a torrent file of proportional size: doubling the piece length halves the number of hashes. The visible cost is that a transfer appears to do nothing for longer at the start, because progress only moves when a whole piece verifies.
The second version of the format, BEP 52, changes the arrangement. It uses SHA-256 rather than SHA-1, hashes each file separately, and builds a merkle tree over 16 kibibyte leaves, so a client can verify a small block without waiting for a whole piece.
What happens when a piece fails its check
A failed piece is discarded in full and fetched again, and the client does not attempt to repair it. There is no partial credit: a piece assembled from blocks supplied by five peers, one of which sent something wrong, is thrown away entirely. Most clients record which peers contributed to failed pieces, and one that keeps appearing there is banned for the session.
Occasional failures are normal. A steady stream of them points at one of three things: a peer sending bad data deliberately, hardware corrupting blocks before they are written, or a file being modified by something else while the transfer runs, which antivirus software and backup tools both do. The transfer still completes correctly in each case; it simply takes longer, and the waste shows as a downloaded total larger than the data.
Why verification is not the same as trusting the contents
Verification proves the bytes match the torrent, and proves nothing about whether those bytes are what you wanted. If the person who created the torrent hashed something harmful, every hash matches and the client reports success, because its whole job was to deliver faithfully what the description named. The swarm cannot audit its own contents and does not try.
The check that closes the gap is published by whoever produced the data rather than by whoever made the torrent. Projects distributing installation images publish a checksum for the finished file on their own site, and comparing that against the file you hold answers a different question: not is this intact, but is this the thing the publisher released. Whether a file is safe to open is a matter of what it is rather than how it traveled, and how a transfer works describes only the traveling.