document ohttp relay best practice in payjoin lib

Author: bc1cindy

payjoin/src/core/io.rs

@@ -1,4 +1,33 @@
 //! 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.
+//!
+//! Sender and receiver have distinct request patterns:
+//! - Receiver: long-poll GETs, then a POST
+//! - Sender: a POST, then long-poll GETs
+//!
+//! OHTTP does not hide the client IP from the relay. A relay that sees the same
+//! client repeatedly can correlate these patterns with the IP to infer whether
+//! the IP is acting as sender or receiver, potentially linking to identity or
+//! location. Across a full session, a relay may narrow down to candidate
+//! transactions and match the sender/receiver role fingerprint against the IP.
+//!
+//! ## 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 on any deterministic, recurring event
+//!   (e.g. app startup, periodic timer). Prefer user-initiated actions
+//!   (e.g. opening a settings/status screen) or piggybacking on operations
+//!   the user already triggered (e.g. resuming an existing session).
+//! - The caller throttles invocations so they don't 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;