=pod

=encoding utf-8

=head1 NAME

Net::BitTorrent::Protocol::BEP23 - Compact Peer Address Formatting

=head1 SYNOPSIS

    use Net::BitTorrent::Protocol::BEP23;

    # Pack a list of peers for a tracker response or PEX update
    my $packed = Net::BitTorrent::Protocol::BEP23::pack_peers_ipv4(
        { ip => '1.2.3.4', port => 6881 },
        { ip => '5.6.7.8', port => 6882 }
    );

    # Unpack a compact list from a tracker
    my $peers = Net::BitTorrent::Protocol::BEP23::unpack_peers_ipv4($binary_data);
    for my $p (@$peers) {
        say "Found peer at $p->{ip}:$p->{port}";
    }

=head1 DESCRIPTION

C<Net::BitTorrent::Protocol::BEP23> implements the compact binary representation of peer addresses used throughout the
BitTorrent ecosystem. By avoiding bencoding for large peer lists, this format significantly reduces the bandwidth
required for tracker announces and Peer Exchange (PEX).

=head1 Functions

=head2 C<pack_peers_ipv4( @peers )>

Takes a list of hashrefs (C<{ip, port}>) and returns a binary string where each peer is represented as 6 bytes (4 for
IP, 2 for Port).

=head2 C<unpack_peers_ipv4( $data )>

The inverse of C<pack_peers_ipv4>. Takes a binary string and returns an arrayref of hashrefs. Throws an exception if
the input length is not a multiple of 6.

=head2 C<pack_peers_ipv6( @peers )>

Implements the B<BEP 07> extension for IPv6. Each peer is represented as 18 bytes (16 for IP, 2 for Port).

=head2 C<unpack_peers_ipv6( $data )>

Unpacks an 18-byte-per-peer binary string into IPv6 peer hashrefs.

=head1 Specifications

=over

=item * B<BEP 23>: Tracker Returns Compact Peer Lists

=item * B<BEP 07>: IPv6 Support (Compact Format)

=back

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 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.

=cut
