NAME

Net::BitTorrent::Peer - Individual Peer Connection & State Tracking

SYNOPSIS

use Net::BitTorrent::Types qw[:encryption];

# Usually managed automatically by Net::BitTorrent::Torrent
my $peer = Net::BitTorrent::Peer->new(
    protocol   => $handler,
    torrent    => $torrent,
    transport  => $tcp_transport,
    ip         => '1.2.3.4',
    port       => 6881,
    encryption => ENCRYPTION_REQUIRED
);

# Access transport layer
my $transport = $peer->transport;

# Manual choking control
$peer->unchoke( );

# Check peer state
say 'Peer is interested' if $peer->peer_interested;
say 'Download rate: ' . ($peer->rate_down / 1024) . ' KB/s';

DESCRIPTION

Net::BitTorrent::Peer represents a single connection to a remote BitTorrent client. It maintains the choking/interested state machine and handles all message routing for a specific neighbor.

Reputation & Security

This class implements peer reputation tracking to protect the swarm from malicious or buggy clients:

• Peers start with a reputation of 100.

• Providing a verified piece increases reputation by 1.

• Providing a corrupt piece (failed hash) decreases reputation by 20.

• If reputation falls to 50 or below, the peer is automatically disconnected and blacklisted for the session.

• The score is capped only by the number of successful transfers (can exceed 100).

METHODS

new( %params )

Parameters;

• encryption: (default ENCRYPTION_PREFERRED) Connection security policy (ENCRYPTION_NONE, ENCRYPTION_PREFERRED, ENCRYPTION_REQUIRED). Supports both constants and strings ('none', 'preferred', 'required').

• transport: An instance of Net::BitTorrent::Transport::TCP or Net::uTP::Connection.

• protocol: An instance of Net::BitTorrent::Protocol::PeerHandler.

unchoke( ) / choke( )

Sends a CHOKE or UNCHOKE message to the peer. This controls whether the remote peer is allowed to request blocks from us.

send_suggest( $index ) / send_allowed_fast( $index )

Sends BEP 06 Fast Extension hints to the peer.

rate_down( ) / rate_up( )

Returns the current transfer rates in bytes per second, calculated via a 20% moving average decay.

reputation( )

Returns the current reputation score.

am_choking( ) / peer_choking( )

Returns the current choking status for both sides of the connection.

am_interested( ) / peer_interested( )

Returns the current interest status.

adjust_reputation( $delta )

Manually adjust the peer's reputation score. Triggers an automatic disconnect if the score drops below 50.

Specifications

• BEP 03: Core Peer Wire Protocol

• BEP 06: Fast Extension (HAVE_ALL, HAVE_NONE, SUGGEST, ALLOWED_FAST)

• BEP 10: Extension Protocol support

• BEP 11: PEX (Peer Exchange) data handling

• BEP 16: Super-seeding support

AUTHOR

Sanko Robinson <sanko@cpan.org>

COPYRIGHT

Copyright (C) 2008-2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

cpanm Net::BitTorrent

perl -MCPAN -e shell
install Net::BitTorrent