Document best client-side BIP-77 health check practice (if any)

[DanGould]

Which crate is this feature request for (if any)?

• payjoin
• payjoin-cli (maybe, if we ever include an infastructure check as reference. Seems like implementations like this.

Question

Bull Bitcoin Mobile is fetching OHTTP Keys from its receiving directory every time it starts up through an OHTTP Relay as a way to check the health of the infrastructure. Please consider what metadata we're leaking by doing this. Seems like the type of thing that would be best if it were a uniform behavior but also one that is not enforceable. I noticed there was a health check in BBMobile and was very curious if it leaked IP. Fortunately, it uses the Relay and therefore seems to have approximately the same network threat model as the protocol itself, granted timing is a bit different.

Consider what Cake is doing as well

Is this best practice? If so why not. If yes, document it

[bc1cindy]

hi @DanGould ,

I've been digging around this issue, analyzed the source code of both Bull Bitcoin Mobile and Cake Wallet, so i'd like to share what I've found and try to help you guys.

both implementations go through the relay correctly, the payjoin directory never sees the user's IP.

BBMobile:

bullbitcoin-mobile % rg "checkOhttpRelayHealth" lib/core/payjoin/data/repository/payjoin_repository_impl.dart -n -A 4
119:  Future<bool> checkOhttpRelayHealth() async {
120-    final (ohttpKeys, ohttpRelay) = await _pdkPayjoinDatasource
121-        .fetchOhttpKeyAndRelay(payjoinDirectory: PayjoinConstants.directoryUrl);
122-    return ohttpKeys != null && ohttpRelay != null;
123-  }

Cake Wallet:

cake_wallet % rg "initReceiver" cw_bitcoin/lib/payjoin/manager.dart -n -A 5
165:    return initReceiver(address);
166-  }
167-
168:  Future<Receiver> initReceiver(String address, [bool isTestnet = false, int retryCount = 0]) async {
169-    try {
170-      final ohttpKeys = await PayjoinUri.fetchOhttpKeys(
171-        ohttpRelay: await randomOhttpRelayUrl(),
172-        payjoinDirectory: payjoinDirectoryUrl,
173-      );

the health check for BB mobile isn't triggered on startup, it only fires when the user manually opens the settings screen.
BB mobile calls fetchOhttpKeyAndRelay in two places: as a pure health check in settings, and when creating a receiver session. Neither uses random relay selection.

settings_router.dart:90 checkStatus() it is only created when navigating to settings
all_settings_screen.dart:32 it's triggered when the screen is opened
wallet_home_app_bar.dart:135 settings only opens when the user taps it

// settings_router.dart:90
create: (_) => locator<ServiceStatusCubit>()..checkStatus(),

// all_settings_screen.dart:32
void initState() {
  super.initState();
  context.read<ServiceStatusCubit>().checkStatus();
}

// wallet_home_app_bar.dart:135
onTap: () => context.pushNamed(SettingsRoute.settings.name),

for Cake Wallet though, it fires every time the app resumes from background, but only if bitcoin wallet and payjoin are enabled. Cake Wallet calls fetch_ohttp_keys to resume active payjoin sessions. The timing is a side effect of a necessary operation, not a health check.

// root.dart:198
if (widget.appStore.wallet?.type == WalletType.bitcoin &&
    widget.appStore.settingsStore.usePayjoin) {
  bitcoin!.resumePayjoinSessions(widget.appStore.wallet!);
}

It also picks a relay randomly:

dart// manager.dart:37
static String randomOhttpRelayUrl() =>
    ohttpRelayUrls[Random.secure().nextInt(ohttpRelayUrls.length)];

BB mobile always tries in the same fixed order:

dart// constants.dart:50
static const List<String> ohttpRelayUrls = [
  'https://ohttp.achow101.com', // always first
  'https://pj.bobspacebkk.com',
  'https://ohttp.cakewallet.com',
];

moreover, BB mobile wallet fixed relay order is not limited to the health check. It appears in every payjoin communication in pdk_payjoin_datasource.dart:

bullbitcoin-mobile % rg ohttpRelayUrls
lib/core/utils/constants.dart
50:  static const List<String> ohttpRelayUrls = [

lib/core/payjoin/data/datasources/pdk_payjoin_datasource.dart
58:    for (final ohttpRelayUrl in PayjoinConstants.ohttpRelayUrls) {
562:      for (final ohttpRelay in PayjoinConstants.ohttpRelayUrls) {
616:    for (final ohttpRelayUrl in PayjoinConstants.ohttpRelayUrls) {
650:    for (final ohttpProxyUrl in PayjoinConstants.ohttpRelayUrls) {
703:      for (final ohttpRelay in PayjoinConstants.ohttpRelayUrls) {

and there is no use of random anywhere in BB mobile wallet relay selection code

rg "Random\|random\|shuffle" lib/ -n --type dart | grep -i "relay\|ohttp" | head -10
rg "Random.secure\|Random()" lib/ -n | head -10
(no results)

IP doesn't leak, the relay handles that, but some metadata does leak at the network layer regardless of OHTTP, just by nature of making an HTTP request:

Timing: the exact moment of the request reveals when the user opened settings or creates a receiver session (BB mobile) or resumed the app (Cake Wallet)
Which relay was used: BB mobile creates an identifiable pattern by always hitting achow101 first. Cake Wallet mitigates this with Random.secure()
That the user is on BIP-77: both hardcode payjo.in as the directory

dart// BBMobile constants.dart:55
static const String directoryUrl = 'https://payjo.in';

// Cake Wallet manager.dart:40
static const payjoinDirectoryUrl = 'https://payjo.in';

I don't see the problem as the health check itself, it's the fixed relay order. Using random would be good practice, just like Cake Wallet does.

fetch_ohttp_keys already documents why you should always route through a relay. What's missing is guidance on picking the relay randomly, and tracking failed relays for resilience. The payjoin-cli already implements it correctly.

random selection:

// payjoin-cli/src/app/v2/ohttp.rs:70
70:            match remaining_relays.choose(&mut payjoin::bitcoin::key::rand::thread_rng()) {
71-                Some(relay) => relay.clone(),
72-                None => return Err(anyhow!("Failed to select from remaining relays")),
73-            };

failed relays:

// payjoin-cli/src/app/v2/ohttp.rs:59
59:        let failed_relays =
60:            relay_manager.lock().expect("Lock should not be poisoned").get_failed_relays();
61-
62-        let remaining_relays: Vec<_> =
63:            relays.iter().filter(|r| !failed_relays.contains(r)).cloned().collect();
64-
65-        if remaining_relays.is_empty() {
66-            return Err(anyhow!("No valid relays available"));
--
114:                    .add_failed_relay(selected_relay);

BB mobile does a simple catch, just continue to the next relay in the list

// pdk_payjoin_datasource.dart:67
67:      } catch (e) {
68-        continue;
69-      }

Cake Wallet retries up to 5 times, picking a random relay each attempt, but without tracking which relays failed, so it may retry a failing relay.

// manager.dart:189
189:      if (e.toString().contains("error sending request for url") && retryCount < 5) {
190:        return initReceiver(address, isTestnet, ++retryCount);
191-      } else {
192-        rethrow;
193-      }

my take is that would be good to add docs in two places:

1. payjoin/src/core/io.rs, to guide library consumers:

/// * `ohttp_relay`: The http CONNECT method proxy to request the ohttp keys from a payjoin
///   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.

2. payjoin-cli/src/app/v2/ohttp.rs, to guide implementers reading the CLI as reference:

/// 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.
pub struct RelayManager {

/// 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(

what do you think about it?

[DanGould]

This makes sense to me. Happy to accept the PR and documentation and to endorse an issue/PR on bbmobile referencing here. Great so see you around again @bc1cindy ! Thanks for this measured, through contribution.

[bc1cindy]

This makes sense to me. Happy to accept the PR and documentation and to endorse an issue/PR on bbmobile referencing here. Great so see you around again @bc1cindy ! Thanks for this measured, through contribution.

thank you @DanGould

I'll be happy to work on it. it's really good to be around again