Tracker exchange extension

This extension makes it possible for BitTorrent peers to learn about new trackers for a swarm they have joined. Ideally ending up with every peer knowing about every tracker used for the torrent.

definitions

In this extension, every peer has a list of trackers. In this list are only verified trackers. A verified tracker is a tracker that either was in the .torrent file that was loaded (just like without this extension, they are assumed to be good) or a tracker that we have received over the TEX protocol and received a successful response from.

The tracker list used by this extension is hence different from the tracker list used by the client itself, since it does not include some trackers that we have never successfully announced with. This list of trackers is the only list of verified trackers referred to in this extension, unless explicitly stated otherwise.

The extension message is used to send changes to the tracker list to other peers. If the peers have different tracker lists on handshake, the first message MUST contain the full list of trackers. Any subsequent message SHOULD only contain added trackers. If the peers have the same tracker list when connecting, the first extension message SHOULD only contain added trackers.

extension header

The tracker exchange extension (TEX for short) uses the extension protocol (specified in BEP 10) to advertize support. It adds the "lt_tex" entry to the "m" dictionary in the extension header hand-shake message. This identifies the message code used for this message. It also adds "tr" to the handshake message specifying a hash of the current tracker list this peer has for this torrent.

Example extension handshake message:

{'m': {'lt_tex', 3}, 'tr': '426c8fe69d59ce85626177749d66e864cc39a82d'}

Note that the string under the 'tr' key is binary. It is printed as a hex encoded string here for clarity. It is always supposed to be 20 bytes.

The tracker list hash is computed as follows:

1. All tracker urls are put in a list
2. All urls SHOULD be normalized
   1. the protocol part (before the '://') is made lower case
   2. the hostname is made lower case
   3. the path and argument components are quote-normalized. Any %-encoding that decodes into an unreserved character (as defined by RFC 2396) should be decoded. Any remaining encoded characters should use lower case hex encoding. i.e. %ff instead of %FF
3. The list of urls is sorted in ascending lexicographical order. Where each byte is interpreted as its ascii value, and sorted by it.
4. The SHA-1 hash is constructed of the concatenation of all urls in the order in the list.

The wording "SHOULD" in point 2 means that an implementation that skips this step is assumed to work efficiently in the vast majority of cases, but might be slightly more susceptible to attacks.

The tracker list hash in the handshake is used to compare with ones own tracker list. In most cases it is assumed that this hash will be the same for both peers. If this is the case, the client SHOULD assume that the peers have the same list, and not send a full tracker list message.

extension message

The extension message is sent on a regular interval. It is recommended not to be sent more often than every 2 minutes.

Any message that does not contain any new trackers SHOULD be omitted (i.e. not sent at all).

The extension message is bencoded and contains a single key: added which is a list of strings. Each string is the url of a tracker that was added since the last update.

example message:

{ 'added': ['http://tracker.bittorrent.com/announce', 'http://tracker2.bittorrent.com'] }

trackers

Trackers discovered through this protocol SHOULD be treated with a certain amount of suspicion. Since the source of a tracker exchange message cannot be trusted, an implementation SHOULD have a lower number of retries before giving up entirely.

Also, as specified under the definitions section, a tracker that has not worked should never be propagated to other peers over the tracker exchange protocol.