[Feature Request] Add option to prefer BitTorrent v2 swarm for hybrid torrents

[absolutep]

Suggestion

I am requesting a new flag in add_torrent_params (or a session setting) that allows a client to explicitly prefer the BitTorrent v2 swarm when seed/leech a hybrid torrent.

Currently, when libtorrent seed/leech a hybrid torrent (which has both v1 and v2 info hashes), it defaults to connecting primarily to the v1 swarm to ensure maximum compatibility. While this is safe, it effectively stalls the migration to v2 because the v2 swarm remains empty even when v2-capable peers are available.

Proposed Change: Introduce a flag (e.g., prefer_v2_swarm or hybrid_mode::prefer_v2) that instructs the torrent object to:

• Prioritize peer connections that support the v2 protocol.
• Request pieces primarily from the v2 swarm (using the v2 info hash).
• Maintain v1 connectivity as a fallback if v2 peers are unavailable or slow, ensuring no loss of download capability.
• This is not a protocol change but a peer selection policy. BiglyBT has already proven this logic works safely in their Java implementation, allowing users to "force" v2 usage on hybrids without breaking compatibility.

Use Case

The "Hybrid Stagnation" Problem: As a user, I often download hybrid torrents from trackers that require them for compatibility. However, I want to support the v2 ecosystem.

• Current Behavior: My client connects to 50 v1 peers and 2 v2 peers. I upload/download almost exclusively via v1. The v2 swarm stays dead.
• Desired Behavior: With this flag, my client would actively seek out and prioritize the v2 peers. Even if there are only a few of us, we would form a healthy v2 sub-swarm within the hybrid torrent.

Why this helps libtorrent:

• Real-world Testing: More traffic on the v2 side of hybrids helps stress-test the v2 implementation in real-world scenarios.
• Organic Migration: It allows users who want to use v2 features (Merkle trees, per-file hashes) to do so immediately, without waiting for trackers to ban v1.
• Swarm Merging Foundation: This logic is a prerequisite for future "swarm merging" features, where the client intelligently balances load between v1 and v2.

Extra Information / Examples / Attachments

1. Prior Art

BiglyBT implemented this successfully in 2021/2023:

They added an option to "explicitly run the v2 swarm on a hybrid download."
They added an option to "run hybrid torrents as v2 rather than v1."

Links:

[1] FEATURE: Core | Option to explicitly run the v2 swarm on a hybrid download [Parg] = https://github.com/BiglySoftware/BiglyBT/releases/tag/v2.6.0.0

[2] FEATURE: Core | Added option to run hybrid torrents as v2 rather than v1 [Parg] = https://github.com/BiglySoftware/BiglyBT/releases/tag/v3.3.0.0

2. Technical Context

I understand that torrent internally manages two swarms for hybrids. Currently, the logic seems to bias towards v1 for legacy reasons.

Reference: In the original v2 implementation discussion (Issue #2197), it was noted that torrent would hold both v1 and v2 swarms. This request asks for a policy switch to bias the active peer selection toward the v2 handle.

Safety: This flag should not disable v1. If the v2 swarm has no seeds, the client must seamlessly fall back to v1 to complete the download. This ensures no user experiences a "stuck" download.

3. Impact on Clients

If this flag exists in libtorrent, clients like qBittorrent, Deluge, and others can expose a simple checkbox to users: "Prefer v2 protocol for hybrid torrents." This empowers the community to drive v2 adoption from the bottom up.

[absolutep]

I have used ChatGPT, to first make it in English and be as succinct as possible. If there is any errors developers can refer to the links provided, considering those are the requested features. Thank you.

[master255]

During our discussion of V2, we concluded that V1 is better and that V2 has absolutely no advantages.

[arvidn]

there's a torrent_flag you can set on add_torrent_params called torrent_flags::disable_v1_hashes.

This will only affect hybrid torrents by not computing the v1 piece hashes, but only the v2 block hashes. This obviously saves CPU but also likely saves disk read-back during downloading.

Does that cover what you're asking for?

If it's about peer-selection, it doesn't cover that. It's not obvious what the benefit would be to deliberately fragment the swarm.