document ohttp relay best practice in payjoin lib

Author: bc1cindy

payjoin/src/core/io.rs

@@ -1,4 +1,34 @@
 //! IO-related types and functions. Specifically, fetching OHTTP keys from a payjoin directory.
+//!
+//! When multiple relays are configured, callers **should pick one at random per request**
+//! to avoid a fixed contact pattern at the network layer. The POST request (immediate
+//! response) and the GET requests (typically several 30-second responses followed by one
+//! shorter but likely non-immediate response) of a single client follow a temporal pattern
+//! that is different for the sender and the receiver (poll followed by post for receiver,
+//! post followed by poll for sender). OHTTP does not hide the client IP from the relay,
+//! which lets the relay link this information of "likely sender" or "likely receiver" to
+//! the IP address, which can reveal information like geographic location in some cases, or
+//! be linkable to personally identifying information. Due to the temporal pattern of the
+//! session as a whole, the relay may be able to narrow down to a list of candidate
+//! transactions, and then narrow those down further to those whose likely sender or
+//! receiver, assuming they are payjoin transactions, matches the fingerprint of the IP
+//! address.
+//!
+//! ## Health checks
+//!
+//! Some clients call [`fetch_ohttp_keys`] periodically to verify that the
+//! directory and relay infrastructure is reachable. Given the threat model
+//! above, this is acceptable only when:
+//!
+//! - The call is **not** triggered automatically on every app startup.
+//!   Prefer triggering on user action (e.g. opening a settings/status
+//!   screen) or piggybacking on operations the user already initiated
+//!   (e.g. resuming an existing session).
+//! - The call is rate-limited so it does not produce a recurring timing
+//!   pattern observable by the relay.
+//!
+//! A health check leaks the same metadata as a real payjoin request.
+//! Treat its frequency as part of your privacy budget.
 use std::time::Duration;
 
 use http::header::ACCEPT;