BitTorrent Client Documentation

Complete documentation for the Simple BitTorrent Client (fast-peer) implementation.

Installation & Requirements

This BitTorrent client requires Python 3.10+ and has minimal dependencies for maximum compatibility.

System Requirements

Installation Steps

pip install requests # Optional for seeding functionality pip install libtorrent

Project Structure

bit_torrent_v1/ ├── app/ │ ├── main.py # Main client implementation │ ├── seeder.py # Seeding functionality │ ├── test.py # Testing utilities │ └── *.torrent # Sample torrent files ├── README.md └── your_program.sh # Execution script

Command Reference

The BitTorrent client supports multiple commands for different operations. All commands are executed through the main.py file.

Basic Commands

decode

Decode bencoded data and display as JSON.

python app/main.py decode <bencoded_string>

Example:

python app/main.py decode "d8:announce9:test.com4:name4:teste"
info

Display detailed information about a torrent file.

python app/main.py info <torrent_file>

Example:

python app/main.py info sample.torrent

Output includes: Tracker URL, file length, info hash, piece length, and piece hashes.

peers

Discover and list available peers for a torrent.

python app/main.py peers <torrent_file>

Example:

python app/main.py peers sample.torrent
handshake

Perform BitTorrent handshake with a specific peer.

python app/main.py handshake <torrent_file> <peer_ip:port>

Example:

python app/main.py handshake sample.torrent 192.168.1.100:6881
download_piece

Download a specific piece from a torrent.

python app/main.py download_piece -o <output_file> <torrent_file> <piece_index>

Example:

python app/main.py download_piece -o piece0.dat sample.torrent 0
download

Download the complete file from a torrent.

python app/main.py download -o <output_file> <torrent_file>

Example:

python app/main.py download -o myfile.zip sample.torrent

Magnet Link Commands

magnet_parse

Parse and display information from a magnet link.

python app/main.py magnet_parse "<magnet_link>"

Example:

python app/main.py magnet_parse "magnet:?xt=urn:btih:1234567890abcdef..."
magnet_handshake

Perform handshake using magnet link information.

python app/main.py magnet_handshake "<magnet_link>"
magnet_info

Retrieve and display metadata from magnet link.

python app/main.py magnet_info "<magnet_link>"
magnet_download_piece

Download a specific piece using magnet link.

python app/main.py magnet_download_piece -o <output_file> "<magnet_link>" <piece_index>
magnet_download

Download complete file using magnet link.

python app/main.py magnet_download -o <output_file> "<magnet_link>"

Example:

python app/main.py magnet_download -o file.zip "magnet:?xt=urn:btih:..."

DHT Commands

dht

Use DHT for peer discovery and download files.

python app/main.py dht -o <output_file> "<magnet_link>"

Features:

  • Trackerless peer discovery
  • DHT node bootstrapping
  • Automatic peer replenishment
  • Metadata exchange via DHT
nhandshake

Perform negotiated handshake with extended protocol support.

python app/main.py nhandshake <torrent_file> <peer_ip:port>

Core Classes

The BitTorrent client is built around several key classes that handle different aspects of the protocol.

PeerManager

Manages peer connections, DHT integration, and peer discovery strategies.

Key Responsibilities:

  • Maintain active peer connections
  • Integrate with DHT for peer discovery
  • Handle peer connection lifecycle
  • Manage unchoked peer list

Key Methods:

  • add_peer(peer_info)
    Add a new peer to the connection pool
  • get_best_peers(count)
    Get the best performing peers based on throughput
  • replenish_peers()
    Use DHT to find new peers when connections drop
  • cleanup_dead_peers()
    Remove disconnected or unresponsive peers
PieceManager

Handles piece downloading, verification, and distribution among peers.

Key Responsibilities:

  • Track which pieces need to be downloaded
  • Assign pieces to available peers
  • Handle piece verification and retry logic
  • Manage download priorities

Key Methods:

  • get_piece_for_peer(have_pieces)
    Get next piece to download based on peer's available pieces
  • mark_failed(idx)
    Mark a piece as failed and add back to needed pieces
  • get_size()
    Get number of remaining pieces to download
DHT (Distributed Hash Table)

Implements BEP 5 DHT protocol for trackerless peer discovery.

Key Responsibilities:

  • Bootstrap with known DHT nodes
  • Handle DHT queries (ping, find_node, get_peers)
  • Maintain routing table of known nodes
  • Discover peers for specific info hashes

DHT Messages Supported:

  • ping
    Basic connectivity test between DHT nodes
  • find_node
    Find nodes closest to a target node ID
  • get_peers
    Find peers downloading/seeding a specific torrent
  • announce_peer
    Announce that this node is downloading/seeding

Bootstrap Nodes:

  • router.bittorrent.com:6881
  • dht.transmissionbt.com:6881
  • router.utorrent.com:6881
  • dht.aelitis.com:6881
  • dht.libtorrent.org:25401
MetadataManager

Manages torrent metadata exchange for magnet links.

Key Responsibilities:

  • Download metadata pieces from peers
  • Assemble complete metadata from pieces
  • Handle metadata piece verification
  • Retry failed metadata downloads

Key Methods:

  • get_next_missing()
    Get next metadata piece that needs to be downloaded
  • add_piece(index, data)
    Add a downloaded metadata piece
  • is_complete()
    Check if all metadata pieces have been downloaded
  • assemble()
    Assemble complete metadata from all pieces

Usage Examples

Basic File Download

# Download a complete file python app/main.py download -o ubuntu.iso ubuntu.torrent # Download specific piece only python app/main.py download_piece -o piece0.dat ubuntu.torrent 0

Magnet Link Usage

# Parse magnet link python app/main.py magnet_parse "magnet:?xt=urn:btih:1234567890abcdef..." # Download from magnet link python app/main.py magnet_download -o file.zip "magnet:?xt=urn:btih:..."

DHT-based Download

# Use DHT for trackerless download python app/main.py dht -o file.zip "magnet:?xt=urn:btih:..."

Peer Discovery

# Discover peers for a torrent python app/main.py peers sample.torrent # Perform handshake with specific peer python app/main.py handshake sample.torrent 192.168.1.100:6881

Seeding (requires libtorrent)

# Run seeder for localhost testing python app/seeder.py

Troubleshooting

Common Issues

No peers found

Symptoms: Download fails with "no peers available"

Solutions:

  • Check if torrent is still active/seeded
  • Try using DHT command for trackerless discovery
  • Verify network connectivity and firewall settings
  • Check if tracker URLs are accessible
Slow download speeds

Symptoms: Downloads are slower than expected

Solutions:

  • Increase number of concurrent connections
  • Check network bandwidth and latency
  • Try different torrents to isolate the issue
  • Monitor peer connection quality
DHT not working

Symptoms: DHT commands fail or timeout

Solutions:

  • Check UDP port 6881 is not blocked
  • Verify internet connectivity
  • Try different bootstrap nodes
  • Check firewall/NAT configuration

Debug Mode

Enable verbose logging by modifying the log level in main.py:

# Enable debug logging def log(message, level="INFO"): if level in ["DEBUG", "INFO", "ERROR"]: print(f"[{level}] {message}")

Performance Tuning