Home > Specs > BitTorrent
Peer Connections

The basic peer to peer protocol is a simple message stream.  After initial handshake, messages are length-prefixed and start with a single-byte message type field.  The rest of the message content is dictated by the message type.

Peer connections may be encapsulated in an optional encryption layer.

Peer connections can be made over regular TCP or a special UDP peer connection protocol.


Upon outgoing connection to another peer, transmit the following three fields:

Protocol Identifier - 20 bytes

This is always the same.
 0x13 0x42 0x69 0x74 0x54 0x6f 0x72 0x72 0x65 0x6e 0x74 0x20 0x50 0x72 0x6f 0x74 0x6f 0x63 0x6f 0x6c

Flags - 8 bytes

This is a bit field that represents various binary flags for this connection.  At this time, there are only three flags in common use.

The lowest bit of the last byte (flags[7]&1) indicates support for DHT hint message #9.

The third-lowest bit of the last byte (flags[7]&4) indicates support of fast mode.

The fifth-lowest bit of the sixth byte (flags[5]&16) indicates support of the extension protocol message #20.

All three of these flags should be set.

Info-Hash - 20 bytes

This is the identifying info-hash for the torrent that this connection is in reference to.


If the incoming peer connection is not accepted, the connection will simply be dropped.

If the connection is accepted, a reply is sent in the exact same form as the initial handshake.


Once a connection reply is received (or sent), all messages are in a simple length-prefixed format.  The first four bytes are a big-endian integer that specifies the number of actual message bytes to follow.  If this number is zero, the message is an empty keep-alive.

The first byte of each message indicates the message type.  The meaning and format of the rest of the message is determined by its type.


Immediately after the initial handshake has been sent and received, the extended handshake should be sent.  It is sent in the form of the extension message.  This sets up support for several features that were not included in the original protocol but are now considered essential.

After the extended handshake, send the bitfield message.  This indicates to the remote peer which pieces the local peer has available to download.

After that, if support was indicated in the initial flags received from the remote peer during the connection handshake, send a DHT message, which is the message type 9 (one byte), followed by the big-endian port number (two bytes) that the local DHT client is listening on.  This is used to seed the DHT if it is empty and no bootstrap servers are available.


If the local peer does not yet have the torrent info map, it can be requested from a remote peer using the metadata extension message.  This is done in 16 KB chunks of the BEncoded representation of the info map.  Once all the chunks have been downloaded, they are assembled and hashed to see if they match the torrent's main info-hash that we know from the magnet link.


The local peer should indicate whether it is interested in downloading from the remote peer by using the interested and uninterested messages.  This is based upon the remote peer's bitfield compared to the local bitfield.

If the remote peer is interested, and the local peer has bandwidth available, an unchoke message can be sent, which can be reversed with a choke message.  A choked peer should not send any block requests, and any requests received while the remote peer is choked should be rejected.

If the local peer is unchoked, actual file bytes can be requested as 16 KB blocks using a block request message.  Once enough blocks are gathered to form a whole piece, they can be assembled and hash-checked against the known piece hash from the torrent info map.

As soon as a piece is downloaded and passes the hash-check, we can save it to disk and issue a HAVE message to all connected peers.  This allows all remote peers to keep track of what pieces we have at all times, so they can determine whether they are interested in downloading from the local peer.

Peer Exchange (PEX) messages are used to keep remote peers informed of our other remote peer connections.  This works in conjunction with holepunching messages which use common peers to synchronize connection attempts and get around NAT routers and firewalls.

If a message hasn't been sent in the last 28 seconds, a keep-alive message should be sent.  This is a message of zero length.  This will keep any hole-punched routes open and detect sooner if the connection has been dropped by the remote peer.  If a message has not been received for 2 minutes, the connection should be dropped.


This is a list of all messages in order of message type ID.  All integers are in big-endian format.

0 Choke
The receiving peer must stop sending block requests.

1 Unchoke
The receiving peer can send block requests.

2 Interested
The sending peer wants to download pieces that the receiving peer has.

3 Uninterested
The sending peer does not want to download pieces that the receiving peer has.

4 Have (4-byte integer)
The sending peer has a copy of the nth piece.

5 Bitfield (one bit for each piece, piece zero is the lowest bit of the first byte)
The sending peer has a copy of these pieces.  Only sent at the beginning of the connection.

6 Block Request (piece index 4-byte int) (byte offset in piece 4-byte int) (block length 4-byte int)
The sending peer requests piece data at a particular offset.  Block length should always be 16384 unless it's the last block or the last piece.

7 Block Request Reply (piece index 4-byte int) (byte offset in piece 4-byte int) (block length 4-byte int) (data...)
This is the result of a successful block request.

8 Block Request Cancel (piece index 4-byte int) (byte offset in piece 4-byte int) (block length 4-byte int)
This can be sent by the peer that sent a block request earlier.

9 DHT Port (2-byte integer)
The sending peer is advertising it's DHT port number.  This is usually done at the beginning of the connection.

14 Have All
This is the equivalent of the 5 Bitfield message with all bits set to 1.

15 Have None
This is the equivalent of the 5 Bitfield message with all bits set to 0.

16 Block Request Reject (piece index 4-byte int) (byte offset in piece 4-byte int) (block length 4-byte int)
This is the result of a block request that was rejected for any reason.

20 Extension Message (BEncoded map of parameters)
This is used for the initial extended handshake at the beginning of the connection to negotiate protocol features and connection parameters.  It is also used at any time to encapsulate various extended protocol features.