Building BitTorrent from Scratch: What 2500 Lines of Modern C++ Can Do

Tyler Tan — Mon, 18 May 2026 15:51:50 +0000

A working BitTorrent downloader — from raw TCP sockets to SHA-1 hashing, all written by hand.

This project starts at the socket level: I wrote my own SHA-1, hand-rolled HTTP requests, implemented bencoding from scratch, defined all seven peer wire protocol message types one by one, and finally spawned multiple peer connections with std::jthread for parallel downloading. It supports both .torrent files and magnet links, and comes with 83 unit tests. Apart from a JSON formatting library and the test framework, it has zero external dependencies.

GitHub: TinyBitTorrent, built with C++23.

What BitTorrent Is

Before diving into the implementation, let's take a minute to understand what BitTorrent actually does.

The traditional file download model is straightforward: you click a link, your browser sends an HTTP request, and the server pushes the file to you. The bottleneck is equally straightforward — all the bandwidth pressure sits on a single server. More users means slower speeds, and if the server goes down, the file is gone.

BitTorrent turns this model on its head by making every downloader an uploader at the same time. A file is split into many small chunks called pieces, each with its own SHA-1 hash. Instead of downloading all pieces from one central server, you grab a few from each of dozens — or hundreds — of peers who are also downloading, or have already finished. Meanwhile, the pieces you already have can be uploaded to other peers. Paradoxically, the more people participate, the faster the entire distribution network becomes.

To implement this protocol, the first problem to solve is: how do you encode and transmit data and metadata? BitTorrent uses a format called bencoding — simple, compact, and unambiguous. Let's start there.

Bencoding: BitTorrent's JSON

Bencoding is BitTorrent's native serialization format. You can think of it as JSON's binary cousin. Where JSON uses curly braces and square brackets to mark structure, bencoding uses type prefixes and length prefixes. There are only four types.

The first is the string, formatted as length:content. For example, 4:spam means the string "spam", and 11:hello world means "hello world". The number before the colon must be a decimal integer with no leading zeros.

The second type is the integer, wrapped in i and e. So i42e is 42, and i-3e is -3. Leading zeros are forbidden, and i-0e is not allowed either.

The third type is the list, wrapped in l and e, containing any number of bencoded values. For instance, l4:spami42ee is a list with the string "spam" and the integer 42. Lists can nest other lists and dictionaries.

The fourth type is the dictionary, wrapped in d and e, with keys and values alternating. Keys must be strings; values can be any type. Something like d3:foo3:bar4:infod6:lengthi1024eee represents {"foo": "bar", "info": {"length": 1024}}. Dictionary keys must be sorted in lexicographic order when encoding — the protocol explicitly requires this.

At this point you might wonder — why not just use JSON? Two reasons. First, JSON can't directly represent binary data like SHA-1 hashes without Base64 encoding, which is costly. Second, bencoding is extremely simple to parse — no quote escaping, no Unicode handling, none of the complexity a JSON parser has to deal with. For BitTorrent in 2001, a format with zero library dependencies was the right call.

My implementation uses std::variant as the data model. Each of the four types is a struct, all wrapped together in a variant:

using String = std::string;
using Integer = int64_t;

struct List { std::vector<Value> items_; };
struct Dict { std::vector<std::pair<String, Value>> items_; };

using Value = std::variant<String, Integer, List, Dict>;

There's an interesting circular dependency here: the definition of Value uses List and Dict, and both List and Dict contain Value. Strictly speaking, this is an incomplete type issue in C++, but std::variant and std::vector implementations since C++17 actually support this recursive pattern in practice, so the compiler lets it through. It's the cleanest way to write it, so that's what I went with.

The parser is a recursive descent design that takes a mutable string_view reference and dispatches on the first character:

auto decode(std::string_view& data) -> Value {
    if (data[0] >= '0' && data[0] <= '9') [[likely]] {
        auto colon = data.find(':');
        auto len = /* parse int from data[0..colon) */;
        data.remove_prefix(colon + 1);
        auto str = std::string{data.substr(0, len)};
        data.remove_prefix(len);
        return str;
    }
    if (data[0] == 'i') [[unlikely]] { /* parse integer... */ }
    if (data[0] == 'l') [[unlikely]] { /* parse list... */ }
    if (data[0] == 'd') [[unlikely]] { /* parse dict... */ }
    // ...
}

If the first character is a digit, we enter the string branch (the most common case, marked [[likely]]); i means integer, and so on. The encoder runs in reverse, using std::format_to to assemble the prefix strings, with dict keys sorted via std::ranges::sort before encoding.

.torrent Files: the Download Shopping List

With bencoding in place, parsing .torrent files is the natural next step. So why do we even need a torrent file? The answer is simple: to download something, you have to know what it is, how big it is, and where to find people who have it. A .torrent file is exactly that shopping list — it tells you the file size, how many pieces it's split into, the hash of each piece, and the tracker URL for finding peers.

A .torrent file is essentially a single bencoded dictionary. At the top level there are two critical keys: announce, which is the tracker URL, and info, a sub-dictionary containing everything directly related to the download — length (total file size in bytes), piece length (the size of each piece, typically 256 KB to 1 MB), and pieces (a long string of all 20-byte SHA-1 hashes concatenated together).

My Metainfo struct captures exactly these six fields:

struct Metainfo {
    std::string announce_;              // tracker URL
    int64_t length_{};                  // total file size
    std::string info_hash_;             // 20-byte raw SHA1
    int64_t piece_length_{};            // size of each piece
    std::vector<std::string> piece_hashes_;  // hex hashes per piece
};

Parsing is a two-level iteration. First pass over the top-level dict grabs announce and info; second pass over the info sub-dict extracts length, piece length, and pieces. The pieces field needs a bit of special handling — the raw data is every 20-byte SHA-1 hash concatenated end-to-end. I slice it into 20-byte chunks and convert each one into a 40-character hex string for storage.

The most noteworthy step is computing the info_hash. This isn't just any hash — you re-bencode the entire info dictionary, then compute SHA-1 over the encoded result. Think of it as taking a "fingerprint" of the info dict. Everything downstream — tracker requests, peer handshakes — identifies the file by this fingerprint. The info_hash is the file's universal identity card in the BitTorrent world.

util::Sha1 hasher;
hasher.update(bencode::encode(Value{*info}));
info_hash = hasher.finalize();

As a side note, there's also a from_info_dict function that reconstructs a Metainfo from an info dictionary obtained through the ut_metadata extension protocol. This comes into play with magnet link downloads, which I'll cover later.

Finding Peers, Shaking Hands, Downloading

Once you have the metadata from a .torrent file, the first order of business is finding who has your data. That's the tracker's job.

A tracker is essentially an HTTP service. You send it your info_hash and your peer_id (a 20-byte random string that identifies you), and it returns a list of peers currently downloading or seeding that file. I construct an HTTP GET request with the info_hash, peer_id, port number, and download progress as URL parameters, appending compact=1 at the end. compact=1 means "give me the peer list in compact form" — 6 bytes per peer: 4 for the IP address and 2 for the port. This keeps the tracker response tiny; even dozens of peers fit in a few hundred bytes. After parsing the response, I split the peers field into 6-byte chunks, extract the IP and port from each, and the peer list is ready.

With a peer's IP and port in hand, the next step is to open a TCP connection and perform the BitTorrent handshake. The handshake packet is a neat 68 bytes, each segment with a clear purpose. Byte 1 is the protocol string length (always 19). The next 19 bytes are "BitTorrent protocol". Then 8 reserved bytes (where bit 4 of byte 26, if set, signals extension protocol support). Then 20 bytes of info_hash. Finally, 20 bytes of peer_id. The peer responds with an identically formatted packet; I verify the protocol string and info_hash match, and the handshake is done. The code for this is shorter than the description:

auto make_handshake(string_view info_hash, string_view peer_id,
                    bool reserve_extensions) -> string {
    string msg(68, '\0');
    msg[0] = 19;
    copy("BitTorrent protocol", msg.begin() + 1);
    msg[25] = reserve_extensions ? '\x10' : '\x00';
    copy(info_hash, msg.begin() + 28);
    copy(peer_id, msg.begin() + 48);
    return msg;
}

After the handshake, both sides enter a simple state machine. The peer first sends a bitfield message — a bitmap where each bit indicates whether the peer has the corresponding piece. After inspecting the bitfield, I send an interested message, essentially saying "I'd like to download from you." Then I wait for an unchoke message. Only after receiving it am I officially granted permission to request data. Choke and unchoke form BitTorrent's flow control mechanism; a peer can choke you at any time to deny transfers, though in practice most peers unchoke right after receiving an interested message.

The logic for actually downloading a piece is the most interesting part of the entire project. A piece can be several megabytes; you can't just request it all at once — that would be slow, and the retransmission cost after packet loss would be punishing. BitTorrent's approach is to split each piece into 16 KB blocks, sending a separate Request message for each block with the piece index, the block's offset within the piece, and its length. But waiting for one block to arrive before requesting the next wastes network bandwidth. The better approach is pipelining: keep up to 5 requests in flight at all times. Whenever a Piece message arrives, I copy the data into the piece buffer at the correct offset and immediately send a new Request to fill the freed slot.

// Fill the pipeline: send up to 5 block requests at once
while (pending < 5 && send_idx < total_blocks) {
    send(encode(Request{piece_index, blocks[send_idx].begin_,
                        blocks[send_idx].length_}));
    ++send_idx; ++pending;
}

// Event loop: receive Pieces, fill buffer, replenish requests
while (received < total_blocks) {
    auto msg = recv_message();
    visit(Overloaded{
        [&](const Piece& pce) {
            copy(pce.block_, piece_data.begin() + pce.begin_);
            ++received; --pending;
            if (send_idx < total_blocks && pending < 5) { /* send next request */ }
        },
        [](const auto&) {}  // ignore other message types
    }, msg);
}

// After all blocks arrive, verify SHA-1
if (sha1_hex(piece_data) != expected_hash) throw ...;

Once all blocks are in, I run SHA-1 over the assembled piece and compare it against the hash recorded in the .torrent file. A match means the piece is good. A mismatch means something went wrong in transit or the peer gave us bad data, so we throw an exception.

Multithreading: Full-Speed Download

If you can download one piece, you can download the entire file. The logic connecting these two concepts is surprisingly straightforward.

First, I pre-allocate the output file to its final size with ftruncate. Think of this as "reserving your spot" on disk — the file already occupies its full footprint, and each piece's data just gets written to its correct offset with pwrite. No need to accumulate a file-sized buffer in memory.

Then comes the multithreading. I spawn one std::jthread worker per peer, each responsible for a contiguous range of pieces. Within a thread, a single TCP connection is established and reused for all pieces in that worker's range (saving handshake overhead). Across threads, everything runs in parallel, each talking to a different peer. The core logic is clean enough to fit in a handful of lines:

// Pre-allocate the file
ftruncate(fd, metainfo.length_);

for (size_t i = 0; i < num_workers; ++i) {
    workers.emplace_back([&, start, end, peer_idx = i]() {
        auto conn = establish_connection(
            peers[peer_idx].ip_, peers[peer_idx].port_, ...);
        for (int pi = start; pi < end; ++pi) {
            auto data = download_piece_on_connection(conn, metainfo, pi);
            pwrite(fd, data.data(), data.size(),
                   pi * metainfo.piece_length_);
        }
    });
}

Error handling is taken care of too. If any worker throws, I capture the first exception with std::exception_ptr behind a mutex, and rethrow it after all threads have joined. This ensures a single failure doesn't crash the whole process before other threads have a chance to clean up their resources.

Magnet Links: Throw Away the Torrent File

The .torrent file path is done, but there's another — arguably more common — way to start a download: magnet links. You've definitely seen something like this: magnet:?xt=urn:btih:abc123...&dn=filename&tr=tracker_url. At its core, it's just a URL embedding the file's info_hash, a suggested display name, and one or more tracker addresses.

Why magnet links? A .torrent file may be small, but it's still a file — you have to get it from a website, a forum, or some other channel first. A magnet link is just a string. Sharing a link is infinitely more convenient than sharing a file. For the BitTorrent network, magnet links are also more decentralized: even if every torrent index site goes down, as long as someone is still seeding, pasting a link is enough to start downloading.

The full magnet download flow adds one critical step compared to the .torrent path: since you don't have a torrent file, you have no idea how big the file is or what its piece hashes are — you have to ask a peer for this information. The rough flow goes like this: parse the magnet link to extract the info_hash and tracker URL, query the tracker for a peer list, establish a TCP connection and perform the base handshake, then use the extension protocol to request the info dictionary from the peer. Once the info_dict passes verification, the rest is exactly the same as the .torrent path — download all the pieces as usual.

Parsing the magnet link itself is straightforward string processing: check for the magnet:? prefix, find the 40-character hex hash after xt=urn:btih: and convert it to 20 raw bytes, locate the tracker URL after tr= and URL-decode it. Compared to bencoding, this is about as hard as drinking a glass of water.

The Extension Handshake

The core challenge of magnet link downloads is "without a torrent file, how do I know what to download?" BitTorrent's answer is the ut_metadata extension defined in BEP 9, which allows peers to exchange torrent info dictionaries. But to use ut_metadata, you first need to complete the extension handshake defined in BEP 10.

The extension handshake is an extra round of negotiation that happens immediately after the standard handshake. First, bit 4 of byte 26 (the 5th byte of the reserved field) in my handshake packet is set to 1 — this flag tells the peer "I speak the extension protocol." If the peer also supports it, it will set the same bit in its handshake response.

Right after the handshake, I send an extension handshake message. This message has type Extended with message ID 0 (by convention, ID 0 is always the extension handshake), and its payload is the bencoded dictionary {"m": {"ut_metadata": 1}}. This says "I want to use the ut_metadata extension, and I'll call it ID 1." The peer responds with a similarly structured dictionary {"m": {"ut_metadata": N}}, telling me what message ID it has assigned to ut_metadata — it might be 1, 2, or some other number. From this point on, all ut_metadata messages use that ID.

// After the standard handshake, check if the peer supports extensions
bool has_ext = (hs_buf[25] & 0x10) != 0;

if (has_ext) {
    // Send extension handshake: {"m": {"ut_metadata": 1}}
    Dict ext{{"m", Dict{{"ut_metadata", Integer{1}}}}};
    send(sock, encode(Extended{0, bencode::encode(Value{ext})}));

    // Parse the response to get the peer's ut_metadata message ID
    auto msg = recv_message(sock);
    auto metadata_ext_id = parse_ext_handshake_response(msg.payload_);
}

Once this step completes, I know exactly which message ID to use when requesting metadata.

Asking a Peer for Metadata

With the peer's ut_metadata message ID in hand, requesting metadata means constructing the bencoded dictionary {"msg_type": 0, "piece": 0} and sending it as an Extended message. msg_type=0 means "this is a request," and piece=0 means "give me chunk 0 of the metadata." (The ut_metadata protocol splits the info dictionary into 16 KB chunks for transmission; the overwhelming majority of torrents have an info dict that fits in a single chunk, so piece=0 is all you need.)

The peer responds with an Extended message whose payload is {"msg_type": 1, "piece": 0, "total_size": N, ...info dict bencoded data appended at the end...}. msg_type=1 means this is a response, and total_size tells me how many bytes the info dictionary's bencoded form takes. The key operation is extracting the last total_size bytes from the payload — that's the complete bencoded info dictionary.

Once I have info_bencode, I do two things. First, bencode-decode it and feed it into from_info_dict to reconstruct a Metainfo — now I have piece_hashes, length, and piece_length, everything I need. Second, and this is the critical part, I compute SHA-1 over info_bencode and compare it against the info_hash from the magnet link. If they don't match, the peer gave me bogus data — throw an exception, try a different peer. This is "trust but verify"; the entire BitTorrent protocol's security rests on hash verification.

// Request metadata
send_metadata_request(sock, metadata_ext_id, 0);

// Receive the response
auto msg = recv_message(sock);
auto info_bencode = parse_metadata_data(msg.payload_);

// Parse the info dict
auto info_dict = std::get<Dict>(bencode::decode(info_bencode));
auto metainfo = from_info_dict(info_dict);

// Verify: info_hash must match the magnet link
if (sha1(info_bencode) != info_hash) throw ...;

Once verification passes, the path forward is identical to the .torrent download: use the Metainfo to query the tracker for a peer list, spawn multiple threads for parallel piece download, and pwrite everything to disk. Magnet links and .torrent files converge on the same destination.

Wrapping Up

From raw TCP sockets to bencoding, from .torrent parsing and tracker communication to the peer wire protocol's handshake and block pipelining, from multithreaded parallel download to magnet links and extension protocols — bit by bit, a working BitTorrent client came together. Around 2500 lines of source code, just under 3500 including tests and build configuration.

The biggest takeaway from this project is that the best way to understand a protocol or a system is to implement it yourself. The BitTorrent protocol specification is only a handful of pages. But there's an ocean of difference between calling someone else's library and filling every byte of a socket buffer by hand, cross-referencing BEP documents to figure out why the peer won't send an unchoke.

Of course, this implementation is aggressively minimal. No seeding (download-only), no DHT for decentralized peer discovery (fully tracker-dependent), no UDP tracker support (HTTP only), no rarest-first piece selection (just sequential assignment), no PEX peer exchange, and no end-game mode. These are the clear dividing lines between a production-grade BitTorrent client and a "learning wheel." As a practical tool, it doesn't hold a candle to qBittorrent or Transmission. As a learning exercise, it did everything I wanted it to do.

If the project interests you, the code is at https://github.com/Tenaryo/TinyBitTorrent. Feedback and drive-by comments welcome.

DEV Community: Tyler Tan