Torrent file

The BitTorrent v2 protocol (BEP-0052) introduces a new definition of the torrent file.[2] The basic structure is:

• announce—the URL of the tracker
• info—this maps to a dictionary whose keys are dependent on whether one or more files are being shared:
  • name—suggested directory name where the files are to be saved
  • piece length—number of bytes per piece. This is commonly 2⁸ KiB = 256 KiB = 262,144 B. In v2, it must be a power of 2.
  • meta version—number, "2".
  • file tree—a tree of dictionaries. Each key represents a directory name or a file name. The file is
    • length—size of the file in bytes (only when one file is being shared though)
    • piece root—For non-empty files this is the root hash of a merkle tree with a branching factor of 2, constructed from 16KiB blocks of the file.
• piece layers—A dictionary of strings, containing the new type of merkle root hashes for each piece.

The new format uses SHA-256 in both the piece-hashing and the infohash, replacing the broken SHA-1 hash. The "btmh" magnet link would contain the full 32-byte hash, while communication with trackers and on the DHT uses the 20-byte truncated version to fit into the old message structure.[2] It is possible to construct a torrent file with only updated new fields for a "v2" torrent, or with both the old and new fields for a "hybrid" format. However, as a torrent would have different infohashes in v1 and v2 networks, two swarms would form, requiring special handling by the client to merge the two. [3]

A core feature of the new format is its application of merkle trees, allowing for 16KiB blocks of a piece to be individually verified and re-downloaded. Each file now always occupy whole piece sizes and have an independent merkle root hash, so that it's possible to find duplicate files across unrelated torrent files of any piece length. The file size is not reduced (assuming piece size stays the same; v2's tree structure allows larger pieces with fewer ill effects), but the info dictionary required for magnet links are (only in v2-only torrents).[3]

These extensions have been deployed in one or more implementations as well as having been proven useful through consistent and widespread use. While they may require minor revisions, they are largely considered to be complete, only awaiting the blessing of Bram Cohen in order to be elevated to the status of Final/Active Process.

BEP-0005[5] extends BitTorrent to support distributed hash tables, specifically Mainline DHT.

A trackerless torrent dictionary does not have an announce key. Instead, a trackerless torrent has a nodes key:

{
  # ...
  'nodes': [["<host>", <port>], ["<host>", <port>], ...],
  # ...
}

For example,

  'nodes': [["127.0.0.1", 6881], ["your.router.node", 4804]],

The specification recommends that nodes "should be set to the K closest nodes in the torrent generating client's routing table. Alternatively, the key could be set to a known good node such as one operated by the person generating the torrent."

BEP-0012[6] extends BitTorrent to support multiple trackers.

A new key, announce-list, is placed in the top-most dictionary (i.e., with announce and info)

{
  # ...
  'announce-list': [['<tracker1-url>']['<tracker2-url>']],
  # ...
}

BEP-0019[7] is one of two extensions allowing HTTP seeds to be used in BitTorrent.

In BEP-0019, a new key url-list, is placed in the top-most list. The client uses the links to assemble ordinary HTTP URLs – no server-side support is required. This feature is very commonly used by open source projects offering software downloads. Web seeds allow smart selection and simultaneous use of mirror sites, P2P or HTTP(S), by the client. Doing so reducing the load on the project's servers while maximizing download speed. MirrorBrain automatically generates torrents with web seeds.

BEP-0027[8] extends BitTorrent to support private torrents.

A new key, private, is placed in the info dictionary. This key's value is 1 if the torrent is private:

{
  # ...
  'info': {
    # ...
    'private': 1,
    # ...
  },
  # ...
}

Private torrents are to be used with a private tracker. Such a tracker restricts access to torrents it tracks by checking the peer's IP, refusing to provide a peer list if the IP is unknown. The peer itself is usually registered to the tracker via a gated online community; the private tracker typically also keep statistics of data transfer for use in the community.

Decentralized methods like DHT, PeX, LSD are disabled to maintain the centralized control. A private torrent can be manually edited to remove the private flag, but doing so will change the info-hash (deterministically), forming a separate "swarm" of peers. On the other hand, changing the tracker list will not change the hash. The flag does not offer true privacy, instead operating as a gentlemen's agreement.

These extensions are under consideration for standardization. Most are already widely adopted as de facto standards.

BEP-0017[9] extends BitTorrent to support HTTP seeds, later more commonly termed "web seeds" to be inclusive of HTTPS.

In BEP-0017, a new key, httpseeds, is placed in the top-most list (i.e., with announce and info). This key's value is a list of web addresses where torrent data can be retrieved. Special server support is required. It remains at Draft status.

{
  # ...
  'httpseeds': ['http://www.site1.com/source1.php', 'http://www.site2.com/source2.php'],
  # ...
}

BEP-0030[10] extends BitTorrent to support Merkle trees (originally implemented in Tribler). The purpose is to reduce the file size of torrent files, which reduces the burden on those that serve torrent files.

A torrent file using Merkle trees does not have a pieces key in the info list. Instead, such a torrent file has a root_hash key in the info list. This key's value is the root hash of the Merkle hash:

{
  # ...
  'info': {
    # ...
    'root hash': <binary SHA1 hash>,
    # ...
  },
  # ...
}

BitTorrent v2 uses a different type of Merkel tree.[3]

A de-bencoded torrent file (with piece length 256 KiB = 262,144 bytes) for a file debian-503-amd64-CD-1.iso (whose size is 678 301 696 bytes) might look like:

{
    'announce': 'http://bttracker.debian.org:6969/announce',
    'info':
    {
        'length': 678301696,
        'name': 'debian-503-amd64-CD-1.iso',
        'piece length': 262144,
        'pieces': <binary SHA1 hashes>
    }
}

Note: pieces here would be a 51 KiB value (${\displaystyle {\color {Blue}\left\lceil {\color {Black}{\frac {\mathtt {length}}{\mathtt {piece\ length}}}}\right\rceil }\times 160=414080\ \mathrm {bits} }$).

A de-bencoded torrent file (with 'piece length' 256 KiB = 262144 B) for two files, 111.txt and 222.txt, might look like:

{
    'announce': 'http://tracker.example.com/announce',
    'info':
    {
        'files':
        [
            {'length': 111, 'path': ['111.txt']},
            {'length': 222, 'path': ['222.txt']}
        ],
        'name': 'directoryName',
        'piece length': 262144,
        'pieces': <binary SHA1 hashes>
    }
}