Document OHTTP relay random selection guidance

Fixed relay order creates a fingerprintable pattern at the network layer even though OHTTP protects the user's IP. Document that callers SHOULD select relays randomly and track failed ones for resilience, following the existing RelayManager implementation in payjoin-cli.

Closes #1328

Author: bc1cindy

payjoin-cli/src/app/v2/ohttp.rs

@@ -4,6 +4,15 @@ use anyhow::{anyhow, Result};
 
 use super::Config;
 
+/// Manages OHTTP relay selection with privacy and resilience in mind.
+///
+/// Relays are selected randomly from the configured list to avoid creating
+/// a fingerprintable pattern at the network layer. Even though OHTTP protects
+/// the user's IP address, always contacting the same relay in the same order
+/// reveals metadata about the client's behavior.
+///
+/// Failed relays are tracked and excluded from future selections until
+/// the session is reset, providing resilience without sacrificing privacy.
 #[derive(Debug, Clone)]
 pub struct RelayManager {
     selected_relay: Option<url::Url>,
@@ -46,6 +55,10 @@ pub(crate) async fn unwrap_ohttp_keys_or_else_fetch(
     }
 }
 
+/// Fetches OHTTP keys using a randomly selected relay from the configured list.
+///
+/// Random relay selection prevents network-layer fingerprinting. See [`RelayManager`]
+/// for details on the selection and failure-tracking strategy.
 async fn fetch_ohttp_keys(
     config: &Config,
     directory: Option<url::Url>,

payjoin/src/core/io.rs

@@ -13,6 +13,12 @@ use crate::OhttpKeys;
 ///   directory.  Proxying requests for ohttp keys ensures a client IP address is never revealed to
 ///   the payjoin directory.
 ///
+///   When multiple relays are available, callers SHOULD select one at random rather than
+///   always using the same relay. A fixed selection order creates a fingerprintable pattern
+///   at the network layer even though the IP is protected by OHTTP.
+///   See `payjoin-cli`'s `RelayManager` for a reference implementation that combines
+///   random selection with failed-relay tracking for resilience.
+///
 /// * `payjoin_directory`: The payjoin directory from which to fetch the ohttp keys.  This
 ///   directory stores and forwards payjoin client payloads.
 pub async fn fetch_ohttp_keys(