Peer Wire Protocol for BitTorrent

Unknown — Sat, 28 Feb 2026 00:00:00 +0000

PWP is the TCP-level protocol two BitTorrent peers use to exchange pieces once a connection is established. It sits after the tracker (which hands you a list of peers) and before whatever piece-assembly / disk-write logic you have. Everything here is binary, big-endian, over a raw TCP stream.</p>

ref: wiki.theory.org/BitTorrentSpecification</a></p> </blockquote>

1. Handshake</h2>

Before any messages flow, both sides exchange a handshake. It is not</strong> framed like regular messages - it has its own fixed layout.</p>

<pstrlen><pstr><reserved><info_hash><peer_id></span></span></code></pre>
    
        0</div>
        1</div>
        2</div>
        3</div>
    </div>
    
    
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
    </div>

    
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    pstrlen=19
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    pstr: "BitTorrent protocol" (19 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    reserved (8 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    info_hash (20 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    peer_id (20 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

        </div>
    

</div>

pstrlen</code>     = 19</code> (always)</li>
pstr</code>        = "BitTorrent protocol"</code> (literal ASCII)</li>
reserved</code>    = 8 zero bytes. extension bits, leave zeroed unless you implement extensions</li>
info_hash</code>   = SHA-1 of the bencoded info dict, 20 bytes</li>
peer_id</code>     = your client's self-assigned 20-byte ID</li>
</ul>
Total: 68 bytes</strong>, fixed.</p>
Send yours, read theirs. Validate: pstr</code> must match, info_hash</code> must match what you expect. If either fails, drop the connection.</p>
2. Message framing</h2>
All messages after the handshake share one wire format:</p>
<length prefix><message ID><payload></span></span></code></pre>
    
        0</div>
        1</div>
        2</div>
        3</div>
    </div>
    
    
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
    </div>

    
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    length prefix (4 bytes, big-endian uint32)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    message_id (1 byte)
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    payload (length - 1 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

        </div>
    

</div>
length</code> = bytes that follow = 1 (id) + len(payload)</code>.</p>
Parse loop:</p>
read 4 bytes -> decode uint32 -> length</span></span>
if length == 0 -> keep-alive, stop</span></span>
read length bytes -> id = first byte, payload = rest</span></span>
dispatch on id</span></span></code></pre>
Two reads per message, no delimiters.</p>
3. Message types</h2>
ID</th> Name</th> Payload</th></tr></thead>

-</td> keep-alive</td> none</td></tr>
0</td> choke</td> none</td></tr>
1</td> unchoke</td> none</td></tr>
2</td> interested</td> none</td></tr>
3</td> not interested</td> none</td></tr>
4</td> have</td> piece index</td></tr>
5</td> bitfield</td> bitfield bytes</td></tr>
6</td> request</td> index, begin, length</td></tr>
7</td> piece</td> index, begin, block</td></tr>
8</td> cancel</td> index, begin, length</td></tr>
</tbody></table>
3.1. keep-alive</h3>
<len=0x00000000></span></span></code></pre>
Zero-length frame. No id byte, no payload. Peers send these periodically to hold the TCP connection open. On receive: do nothing, reset your timeout counter. If nothing arrives (including keep-alives) for ~2 min, close the connection.</p>
3.2. choke (ID 0) / unchoke (ID 1) / interested (ID 2) / not interested (ID 3)</h3>
<len=0x00000001><id></span></span></code></pre>
    
        0</div>
        1</div>
        2</div>
        3</div>
    </div>
    
    
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
    </div>

    
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    length = 0x00000001
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    0x00 | 0x01 | 0x02 | 0x03
                </div>

            

        </div>
    

</div>
No payload. Four messages, same format.</p>
3.3. have (ID 4)</h3>
<len=0x00000005><id=0x04><piece index></span></span></code></pre>
    
        0</div>
        1</div>
        2</div>
        3</div>
    </div>
    
    
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
    </div>

    
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    length = 0x00000005
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    id=0x04
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    piece index (4 bytes)
                </div>

            

        </div>
    

</div>
Sent after you successfully download and verify a piece. Tells the peer you now have it.</p>
3.4. bitfield (ID 5)</h3>
<len=0x00000001+X><id=0x05><bitfield></span></span></code></pre>
    
        0</div>
        1</div>
        2</div>
        3</div>
    </div>
    
    
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
    </div>

    
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    length = 0x00000001 + X
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    id=0x05
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    bitfield (X bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

        </div>
    

</div>
Sent right after the handshake. Declares which pieces the sender already has. One bit per piece, MSB first. Bit i</code> is in byte floor(i/8)</code>, at position 7 - (i % 8)</code>. Trailing bits (if num_pieces</code> is not a multiple of 8) are zero. X = ceil(num_pieces / 8)</code>.</p>
Only sent if you have at least one piece. Optional - a peer with nothing won't send it.</p>
3.5. request (ID 6)</h3>
<len=0x0000000D><id=0x06><index><begin><length></span></span></code></pre>
    
        0</div>
        1</div>
        2</div>
        3</div>
    </div>
    
    
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
    </div>

    
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    length = 0x0000000D
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    id=0x06
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    index (4 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    begin (4 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    length (4 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

        </div>
    

</div>

index</code> - zero-based piece index</li>
begin</code> - byte offset within the piece</li>
length</code> - block size. conventionally 16 KiB</strong> (16 * 1024</code>). last block of a piece may be smaller</li>
</ul>
You can only send this when the peer has unchoked you (peer_choking == false</code>).</p>
3.6. piece (ID 7)</h3>
<len=0x00000009+X><id=0x07><index><begin><block></span></span></code></pre>
    
        0</div>
        1</div>
        2</div>
        3</div>
    </div>
    
    
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
    </div>

    
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    length = 0x00000009 + X
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    id=0x07
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    index (4 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    begin (4 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    block (X bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

        </div>
    

</div>
Response to a request</code>. block</code> is the raw bytes. X = block length.</p>
3.7. cancel (ID 8)</h3>
<len=0x0000000D><id=0x08><index><begin><length></span></span></code></pre>
    
        0</div>
        1</div>
        2</div>
        3</div>
    </div>
    
    
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
            
                2</div>
            
        
            
                3</div>
            
        
            
                4</div>
            
        
            
                5</div>
            
        
            
                6</div>
            
        
            
                7</div>
            
        
            
                8</div>
            
        
            
                9</div>
            
        
            
                0</div>
            
        
            
                1</div>
            
        
    </div>

    
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    length = 0x0000000D
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    id=0x08
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    index (4 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    begin (4 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

                
                
                

                
               
                
                    
                

                
                
                    length (4 bytes)
                </div>

            

        </div>
    
        

            

                
                
                

                
               
                
                    
                

                
                
                    ...
                </div>

            

        </div>
    

</div>
Same payload as request</code>. Cancels an in-flight block request. Used in end-game mode when the same block has been requested from multiple peers and one already responded.</p>
4. Parsing</h2>
read_message(stream):</span></span>
    len_buf = read_exact(stream, 4)</span></span>
    length  = decode_uint32_be(len_buf)</span></span>
</span>
    if length == 0:</span></span>
        return KeepAlive</span></span>
</span>
    msg_buf = read_exact(stream, length)</span></span>
    id      = msg_buf[0]</span></span>
    payload = msg_buf[1:]</span></span>
</span>
    switch id:</span></span>
        0 -> Choke</span></span>
        1 -> Unchoke</span></span>
        2 -> Interested</span></span>
        3 -> NotInterested</span></span>
        4 -> Have       { index = uint32_be(payload[0:4]) }</span></span>
        5 -> Bitfield   { bits = payload }</span></span>
        6 -> Request    { index, begin, length = three uint32_be }</span></span>
        7 -> Piece      { index, begin = uint32_be; block = payload[8:] }</span></span>
        8 -> Cancel     { index, begin, length = three uint32_be }</span></span>
        _ -> error: unknown id</span></span></code></pre>
read_exact</code> must loop until the full byte count is received - TCP does not guarantee a single read returns everything requested.</p>
5. Serialization</h2>
serialize(msg):</span></span>
    payload = msg.payload()          // empty slice for no-payload messages</span></span>
    length  = 1 + len(payload)       // id byte + payload</span></span>
</span>
    buf = uint32_be(length) + [msg.id()] + payload</span></span>
    return buf</span></span>
</span>
serialize_keepalive():</span></span>
    return uint32_be(0)              // 4 zero bytes, no id</span></span></code></pre>
Every message type exposes id()</code> and payload()</code>. Serialization is uniform - no special cases except keep-alive.</p>
Handshake is serialized separately (fixed layout, not length-prefixed):</p>
serialize_handshake(info_hash, peer_id):</span></span>
    buf = [19] + "BitTorrent protocol" + [0]*8 + info_hash + peer_id</span></span>
    return buf   // 68 bytes</span></span></code></pre>6. Connection lifecycle</h2>
client                              peer</span></span>
  |                                  |</span></span>
  |-------- handshake -------------->|</span></span>
  |<------- handshake ---------------|</span></span>
  |                                  |</span></span>
  |<------- bitfield (5) ------------|  peer declares what it has</span></span>
  |<------- keep-alive --------------|  may arrive between any messages</span></span>
  |                                  |</span></span>
  |-------- interested (2) --------->|  we want pieces from them</span></span>
  |                                  |</span></span>
  |<------- unchoke (1) -------------|  peer allows us to request</span></span>
  |                                  |</span></span>
  |-------- request (6) ------------>|  ask for a block</span></span>
  |<------- piece (7) ---------------|  receive block data</span></span>
  |-------- request (6) ------------>|</span></span>
  |<------- piece (7) ---------------|</span></span>
  |         ...                      |</span></span>
  |-------- have (4) --------------->|  tell peer we completed a piece</span></span></code></pre>
State per connection (both directions):</p>
am_choking      = true   // we are choking the peer</span></span>
am_interested   = false  // we are not interested in the peer</span></span>
peer_choking    = true   // peer is choking us</span></span>
peer_interested = false  // peer is not interested in us</span></span></code></pre>
Default on connect: both sides choking, neither interested. Update these as the corresponding messages arrive. Gate request</code> sends on peer_choking == false</code>.</p>
7. Blocks vs pieces</h2>
Pieces (from torrent metadata) are large - 256 KiB, 512 KiB, sometimes more. request</code> and piece</code> messages work at block</strong> granularity:</p>

standard block size: 16 KiB</strong></li>
last block of a piece: min(16384, remaining_bytes_in_piece)</code></li>
last block of the last piece: may be smaller if total file size is not piece-aligned</li>
</ul>
Reassemble received blocks into the full piece, then SHA-1 verify against the hash in the torrent metadata before writing to disk.</p>
8. Implementation notes</h2>
Two reads per message</strong> - read the 4-byte length prefix first, then read exactly length</code> bytes for the rest. Use a buffered reader on the raw connection to avoid a syscall per byte.</p>
Block length clamping</strong> - block_length(piece_remaining)</code> returns 16384</code> unless piece_remaining < 16384</code>, then returns piece_remaining</code>. Handles tail blocks without special-casing the request loop.</p>
Peer state as four booleans</strong> - am_choking</code>, am_interested</code>, peer_choking</code>, peer_interested</code>. Keep these in sync with arriving messages. Everything else (piece selection, queueing) reads from them.</p>


Hello World!
Unknown — Sun, 11 May 2025 00:00:00 +0000


first post, just to test if everything is working.</p>
here are a few cool pictures I clicked <⁠(⁠￣ ⁠︶ ⁠￣⁠)⁠></p>



    
     
</div>

ID</th>	Name</th>	Payload</th></tr></thead>
-</td>	keep-alive</td>	none</td></tr>
0</td>	choke</td>	none</td></tr>
1</td>	unchoke</td>	none</td></tr>
2</td>	interested</td>	none</td></tr>
3</td>	not interested</td>	none</td></tr>
4</td>	have</td>	piece index</td></tr>
5</td>	bitfield</td>	bitfield bytes</td></tr>
6</td>	request</td>	index, begin, length</td></tr>
7</td>	piece</td>	index, begin, block</td></tr>
8</td>	cancel</td>	index, begin, length</td></tr> </tbody></table> 3.1. keep-alive</h3> <len=0x00000000></span></span></code></pre> Zero-length frame. No id byte, no payload. Peers send these periodically to hold the TCP connection open. On receive: do nothing, reset your timeout counter. If nothing arrives (including keep-alives) for ~2 min, close the connection.</p> 3.2. choke (ID 0) / unchoke (ID 1) / interested (ID 2) / not interested (ID 3)</h3> <len=0x00000001><id></span></span></code></pre> 0</div> 1</div> 2</div> 3</div> </div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> </div> length = 0x00000001 </div> </div> 0x00 \| 0x01 \| 0x02 \| 0x03 </div> </div> </div> No payload. Four messages, same format.</p> 3.3. have (ID 4)</h3> <len=0x00000005><id=0x04><piece index></span></span></code></pre> 0</div> 1</div> 2</div> 3</div> </div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> </div> length = 0x00000005 </div> </div> id=0x04 </div> piece index (4 bytes) </div> </div> </div> Sent after you successfully download and verify a piece. Tells the peer you now have it.</p> 3.4. bitfield (ID 5)</h3> <len=0x00000001+X><id=0x05><bitfield></span></span></code></pre> 0</div> 1</div> 2</div> 3</div> </div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> </div> length = 0x00000001 + X </div> </div> id=0x05 </div> bitfield (X bytes) </div> </div> ... </div> </div> </div> Sent right after the handshake. Declares which pieces the sender already has. One bit per piece, MSB first. Bit i</code> is in byte floor(i/8)</code>, at position 7 - (i % 8)</code>. Trailing bits (if num_pieces</code> is not a multiple of 8) are zero. X = ceil(num_pieces / 8)</code>.</p> Only sent if you have at least one piece. Optional - a peer with nothing won't send it.</p> 3.5. request (ID 6)</h3> <len=0x0000000D><id=0x06><index><begin><length></span></span></code></pre> 0</div> 1</div> 2</div> 3</div> </div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> </div> length = 0x0000000D </div> </div> id=0x06 </div> index (4 bytes) </div> </div> ... </div> begin (4 bytes) </div> </div> ... </div> length (4 bytes) </div> </div> ... </div> </div> </div> index</code> - zero-based piece index</li> begin</code> - byte offset within the piece</li> length</code> - block size. conventionally 16 KiB</strong> (16 * 1024</code>). last block of a piece may be smaller</li> </ul> You can only send this when the peer has unchoked you (peer_choking == false</code>).</p> 3.6. piece (ID 7)</h3> <len=0x00000009+X><id=0x07><index><begin><block></span></span></code></pre> 0</div> 1</div> 2</div> 3</div> </div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> </div> length = 0x00000009 + X </div> </div> id=0x07 </div> index (4 bytes) </div> </div> ... </div> begin (4 bytes) </div> </div> ... </div> block (X bytes) </div> </div> ... </div> </div> </div> Response to a request</code>. block</code> is the raw bytes. X = block length.</p> 3.7. cancel (ID 8)</h3> <len=0x0000000D><id=0x08><index><begin><length></span></span></code></pre> 0</div> 1</div> 2</div> 3</div> </div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> 2</div> 3</div> 4</div> 5</div> 6</div> 7</div> 8</div> 9</div> 0</div> 1</div> </div> length = 0x0000000D </div> </div> id=0x08 </div> index (4 bytes) </div> </div> ... </div> begin (4 bytes) </div> </div> ... </div> length (4 bytes) </div> </div> ... </div> </div> </div> Same payload as request</code>. Cancels an in-flight block request. Used in end-game mode when the same block has been requested from multiple peers and one already responded.</p> 4. Parsing</h2> read_message(stream):</span></span> len_buf = read_exact(stream, 4)</span></span> length = decode_uint32_be(len_buf)</span></span> </span> if length == 0:</span></span> return KeepAlive</span></span> </span> msg_buf = read_exact(stream, length)</span></span> id = msg_buf[0]</span></span> payload = msg_buf[1:]</span></span> </span> switch id:</span></span> 0 -> Choke</span></span> 1 -> Unchoke</span></span> 2 -> Interested</span></span> 3 -> NotInterested</span></span> 4 -> Have { index = uint32_be(payload[0:4]) }</span></span> 5 -> Bitfield { bits = payload }</span></span> 6 -> Request { index, begin, length = three uint32_be }</span></span> 7 -> Piece { index, begin = uint32_be; block = payload[8:] }</span></span> 8 -> Cancel { index, begin, length = three uint32_be }</span></span> _ -> error: unknown id</span></span></code></pre> read_exact</code> must loop until the full byte count is received - TCP does not guarantee a single read returns everything requested.</p> 5. Serialization</h2> serialize(msg):</span></span> payload = msg.payload() // empty slice for no-payload messages</span></span> length = 1 + len(payload) // id byte + payload</span></span> </span> buf = uint32_be(length) + [msg.id()] + payload</span></span> return buf</span></span> </span> serialize_keepalive():</span></span> return uint32_be(0) // 4 zero bytes, no id</span></span></code></pre> Every message type exposes id()</code> and payload()</code>. Serialization is uniform - no special cases except keep-alive.</p> Handshake is serialized separately (fixed layout, not length-prefixed):</p> serialize_handshake(info_hash, peer_id):</span></span> buf = [19] + "BitTorrent protocol" + [0]*8 + info_hash + peer_id</span></span> return buf // 68 bytes</span></span></code></pre>6. Connection lifecycle</h2> client peer</span></span> \| \|</span></span> \|-------- handshake -------------->\|</span></span> \|<------- handshake ---------------\|</span></span> \| \|</span></span> \|<------- bitfield (5) ------------\| peer declares what it has</span></span> \|<------- keep-alive --------------\| may arrive between any messages</span></span> \| \|</span></span> \|-------- interested (2) --------->\| we want pieces from them</span></span> \| \|</span></span> \|<------- unchoke (1) -------------\| peer allows us to request</span></span> \| \|</span></span> \|-------- request (6) ------------>\| ask for a block</span></span> \|<------- piece (7) ---------------\| receive block data</span></span> \|-------- request (6) ------------>\|</span></span> \|<------- piece (7) ---------------\|</span></span> \| ... \|</span></span> \|-------- have (4) --------------->\| tell peer we completed a piece</span></span></code></pre> State per connection (both directions):</p> am_choking = true // we are choking the peer</span></span> am_interested = false // we are not interested in the peer</span></span> peer_choking = true // peer is choking us</span></span> peer_interested = false // peer is not interested in us</span></span></code></pre> Default on connect: both sides choking, neither interested. Update these as the corresponding messages arrive. Gate request</code> sends on peer_choking == false</code>.</p> 7. Blocks vs pieces</h2> Pieces (from torrent metadata) are large - 256 KiB, 512 KiB, sometimes more. request</code> and piece</code> messages work at block</strong> granularity:</p> standard block size: 16 KiB</strong></li> last block of a piece: min(16384, remaining_bytes_in_piece)</code></li> last block of the last piece: may be smaller if total file size is not piece-aligned</li> </ul> Reassemble received blocks into the full piece, then SHA-1 verify against the hash in the torrent metadata before writing to disk.</p> 8. Implementation notes</h2> Two reads per message</strong> - read the 4-byte length prefix first, then read exactly length</code> bytes for the rest. Use a buffered reader on the raw connection to avoid a syscall per byte.</p> Block length clamping</strong> - block_length(piece_remaining)</code> returns 16384</code> unless piece_remaining < 16384</code>, then returns piece_remaining</code>. Handles tail blocks without special-casing the request loop.</p> Peer state as four booleans</strong> - am_choking</code>, am_interested</code>, peer_choking</code>, peer_interested</code>. Keep these in sync with arriving messages. Everything else (piece selection, queueing) reads from them.</p> Hello World! Unknown — Sun, 11 May 2025 00:00:00 +0000 first post, just to test if everything is working.</p> here are a few cool pictures I clicked <⁠(⁠￣ ⁠︶ ⁠￣⁠)⁠></p> </div>

Vedant

Peer Wire Protocol for BitTorrent

Hello World!