libtorrent Documentation

libtorrent is a feature-complete C++ BitTorrent implementation designed for efficiency and scalability, suitable for both embedded devices and desktops.

Key capabilities include:

• BitTorrent v2 Support: Full support for BEP 52, featuring SHA-256, Merkle hash trees for per-file validation, and a more efficient directory-based file structure.
• Extensibility: A plugin interface for custom extensions and support for various protocols (DHT, Magnet links/BEP 9, PEX, etc.).
• Advanced Disk Management: Asynchronous multi-threaded disk I/O, fast resume support, and multi-threaded SHA-1 verification.
• Optimized Networking: High-quality uTP implementation (BEP 29), block-level piece picking, and automatic upload slot management.
• Specialized Modes: Includes a 'share mode' for optimizing upload ratios rather than downloading.

This extension allows the BitTorrent DHT to store and retrieve arbitrary data. It supports two types of items:

1. Immutable Items: Stored under the SHA-1 hash of the data itself. Since they cannot be modified, no authentication is required. A requesting node should verify that the received data's hash matches the requested target.
2. Mutable Items: Stored under the SHA-1 hash of the publisher's public key (optionally concatenated with a salt). These items can be updated by the original publisher using a private key. Updates are secured via a monotonically increasing sequence number (seq) and an ed25519 signature (sig).

While libtorrent is a C++ library, bindings are available for several other languages:

• Python: Use the Python bindings.
• Java: Available via frostwire-jlibtorrent.
• Golang: Available via libtorrent-go.
• Node.js: Available via node-libtorrent.

Libtorrent uses a Pimpl (pointer to implementation) pattern to separate the public interface from internal state.

• session: The public interface to the session. It hides the session_impl object to maintain binary compatibility.
• session_impl: The internal state object containing global information such as m_torrent (list of torrents), m_connections (peer connections), m_settings (global rate limits), m_dht (DHT state), and port mapping state (m_upnp and m_natpmp).
• torrent_handle: The public interface to a torrent. It holds a weak reference to the internal torrent object and communicates with the network thread via messages.

Libtorrent provides two ways to manage peer request queues for ordered data:

1. sequential_download: A simple mode that waits for a queue slot to open and requests the next piece in sequence. While it saturates bandwidth and keeps pieces roughly in-order, it is sub-optimal for streaming because a slow peer holding up an early piece can prevent fast peers from receiving requests for later, more critical pieces.

2. Streaming (Time-critical logic): An advanced version of sequential download that actively manages peer request queues. It ensures the most time-critical pieces occupy the "best" queue slots across all available peers, making it more suitable for real-time media playback.

uTP is a transport protocol designed to prevent BitTorrent traffic from saturating a user's internet connection and causing high latency for interactive applications (like web browsing or Skype).

Unlike TCP, which primarily reacts to packet loss, uTP uses a congestion controller called LEDBAT that reacts to changes in one-way delays. This allows uTP to detect when a modem's send buffer is filling up and proactively reduce its send rate before packet loss occurs, leaving headroom for other traffic. Once interactive traffic ceases, uTP automatically scales back up to utilize the available bandwidth.

This proposal (superseded by dht_put) describes a BitTorrent DHT extension for decentralized RSS-like functionality. It allows creating repositories of torrents where a single identity (a private key) has the authority to add content.

Key Concepts:

• Target ID: The SHA-1 hash of a feed name and a 512-bit public key. This is where the repository is stored in the DHT.
• Storage Node: A DHT node to which an item is being announced.
• Subscribing Node: A node that performs lookups in the DHT to find storage nodes and request items.
• Security: Every item must be signed with the private key corresponding to the public key used in the Target ID. Recipients must verify both the public key against the Target ID and the signature of each individual item.

Libtorrent utilizes multiple threads to manage network, disk, and name resolution tasks. The number of threads depends on the settings_pack::aio_threads setting.

• Main Network Thread: Manages all sockets, sends/receives messages, and maintains session, torrent, and peer state. It typically blocks on system calls like epoll() when idle.
• Disk I/O Threads: Handles all disk read/write operations and performs SHA-1/SHA-256 piece verification. Messages are passed back to the main thread upon completion. Multiple threads may be used to prevent disk starvation.
• Asynchronous Host Name Resolution Thread: Spawned by boost.asio on systems lacking native asynchronous host name resolution to simulate non-blocking getaddrinfo().