[WIP] Add AS-aware relay selection by Mshehu5 · Pull Request #1514 · payjoin/rust-payjoin

Mshehu5 · 2026-05-01T23:05:51Z

This PR addresses #919 which adds AS-aware, stateless relay selection to payjoin crate and implements in payjoin-cli Reviewers will probably want to read #919 for the full context behind the design and tradeoffs.

The implementation adds optional ASMap-based filtering for trusted directories and OHTTP relays then demonstrates relay selection that separates POST and POLL traffic without storing a selected relay or relay index. Relay ordering is derived from the receiver key, request/message type and short time windows with polling avoiding POST-reserved AS buckets for nearby windows.

The main payjoin crate now contains the reusable deterministic relay-ordering logic. payjoin-cli handles the application-specific parts: DNS resolution, ASMap lookup, trusted-directory filtering, and HTTP transport.
Relay candidates are grouped into privacy buckets:

with ASMap: by ASN;
without ASMap: by relay URL.

Notes to reviwers :
Open question: non-ASMap behavior and #1696.
When ASMap is not configured, this PR treats each relay URL as its own bucket. Relay choice is pseudorandom rather than plain config order buckets are ranked by hashing the receiver key, time window, and relay URL. Different receiver keys normally produce different-looking relay choices.
The limitation is that URL buckets are weaker than ASN buckets. Without ASMap, two different relay URLs in the same ASN are treated as independent so POST/POLL separation only works at the URL level, not the ASN level.
I would like reviewer feedback on whether this URL-bucket fallback is the right default for implementations that do not use ASMap or whether the non-ASMap path should align more directly with the SelectContext direction in #1696.

Disclosure: co-authored by Codex

Pull Request Checklist

Please confirm the following before requesting review:

I have disclosed my use of
AI
in the body of this PR.
I have read CONTRIBUTING.md and rebased my branch to produce hygienic commits.

coveralls · 2026-05-01T23:11:10Z

Coverage Report for CI Build 29664763774

Coverage decreased (-0.7%) to 85.623%

Details

Coverage decreased (-0.7%) from the base build.
Patch coverage: 284 uncovered changes across 8 files (691 of 975 lines covered, 70.87%).
4 coverage regressions across 2 files.

Uncovered Changes

File	Changed	Covered	%
payjoin-cli/src/app/v2/ohttp.rs	91	20	21.98%
payjoin-cli/src/app/v2/relay_selection.rs	252	181	71.83%
payjoin-cli/src/app/v2/network.rs	86	46	53.49%
payjoin/src/core/io.rs	61	21	34.43%
payjoin-cli/src/app/config.rs	52	19	36.54%
payjoin-cli/src/app/v2/mod.rs	120	93	77.5%
payjoin-cli/src/app/mod.rs	9	8	88.89%
payjoin/src/core/relay_selection.rs	304	303	99.67%

Coverage Regressions

4 previously-covered lines in 2 files lost coverage.

File	Lines Losing Coverage	Coverage
payjoin-cli/src/app/v2/ohttp.rs	3	22.92%
payjoin/src/core/io.rs	1	49.38%

Coverage Stats


Relevant Lines:	16819
Covered Lines:	14401
Line Coverage:	85.62%
Coverage Strength:	333.98 hits per line

💛 - Coveralls

arminsabouri · 2026-05-19T14:59:36Z

cc @nothingmuch to approach Ack/Nack

nothingmuch

approach ack

not 100% sure about relaymanager getting removed it may still have a job (keeping track of failures, arguably important enough to be in scope for reference client)

relay selection looks good, but i didn't review carefully since only seeking approach ack

nothingmuch · 2026-05-25T00:40:26Z

+    Post(MessageKind),
+    Poll(MessageKind),


is message kind for diagnostic purposes?

bc1cindy

this is looking good!

an io-style feature seems viable, instead of a separate crate

since this is well underway, i'll close #1452

bc1cindy · 2026-05-25T14:16:36Z

+
+pub(crate) const WINDOW_SECS: u64 = 30;
+const CLOCK_SKEW_WINDOWS: i64 = 2;
+const POST_RESERVED_COUNT: usize = 3;


at time t_i, avoid making any real GET requests (i.e. dummy GET requests are OK) using the relays
whose hash is lexicographically smallest not just at time t_i, but at times t_{i-2}..t_{i+2} or at least
t_{i-1}..t_{i+1}
they should always use a different relay for the post and the get, avoiding the worst case leak

k=3 and skew=2 are fixed at the upper end of #919 (comment)

with 3-5 public OHTTP relays, the reservation budget (up to 15 buckets) can swallow the whole pool, so POLL falls back (286-289) to POST-reserved buckets, silently violating the spec when poll_candidates is empty (small pool)

picking k and skew based on pool size (k=2/skew=1 when small) would reduce reserved bucket to 6 and avoid the fallback for B ≥ 7, while keeping max protection when B ≥ 16. The remaining edge case (B ≤ 6) would still hit the warn!, possibly worth surfacing to the caller, maybe with a typed error

makes sense?

Yeah, that makes sense. Fixed k=3 / skew=2 is good for larger pools but too aggressive for small relay sets since it can reserve every bucket.

bc1cindy · 2026-05-25T14:44:30Z

+    ///
+    /// The ordering is recomputed from the receiver key and current time, so no
+    /// relay-selection progress needs to be stored between requests.
+    pub(crate) fn select_relays_for_request(


would be good to add tests for the deterministic selection

selection_hash stability (interop), deterministic ordering per (pubkey, RequestKind, TimeWindow), POLL/POST exclusion, and round-robin fairness

Yeah was trying to keep PR small and only keep essential so it can be easier to review and get approach ack with the smaller PR's test should be added

bc1cindy · 2026-05-25T15:08:09Z

+        bail!("No valid relays available for the selected directory {}", directory.url.as_str());
+    }
+
+    relays.shuffle(&mut thread_rng());


btw, relays.shuffle seems inert as ordered_candidates reorders everything afterwards

leftover of the old shuffle?

Yep, good catch. This looks like leftover behavior from the old random relay ordering. Since request-time selection now goes through ordered_candidates, the initial relays.shuffle does not affect POST/POLL ordering. I’ll remove it.

bc1cindy · 2026-05-25T15:42:09Z


 [dependencies]
 anyhow = "1.0.99"
+asmap = { version = "0.1.0", optional = true }


would be good to know what the team think about adding this dep to parse the binary, especially if we are moving to the payjoin crate

is it a good idea or would it be better to have our own parser? #1452 (comment)

I did check out the library also saw a contibutor to asmap bitcoin core library give it a star but more eyes on the library would be nice

bc1cindy · 2026-05-27T21:33:07Z

+pub struct AsmapConfig {
+    #[serde(rename = "asmap_file")]
+    pub asmap: LoadedAsmap,


a configured, per-integration asmap file is a client fingerprint two ways: (1) only some integrations load one, so the AS-aware ones stand out (uses-it-or-not), and (2) selection is deterministic from the asmap, so even those that do load one diverge unless they're on the exact same snapshot.

could the lib ship one bundled snapshot per version instead, so every integration on a given version has the same file with nothing to fetch?

it's ~1.5 MB, and asmap-data updates ~monthly (irregular, gaps up to ~2 months), but relay ASNs are stable so across versions keeping everyone consistent

https://github.com/bitcoin-core/asmap-data

wdyt?

No answer for this yet , this might require more discussion will get back to you

bc1cindy · 2026-05-27T23:38:02Z

+    #[serde(default)]
+    pub user_public_ips: Vec<IpAddr>,
+    #[serde(default)]
+    pub user_asns: Vec<u32>,


Given a list of trusted directories and relays, these lists should be filtered to exclude servers that share an AS with the user. This is potentially tricky as it users to be able to determine their public IP(s).

requiring the user's own ASN/IP makes AS-aware mode operator-only, a NAT'd wallet can't supply it without an external lookup, which is a privacy leak of its own

#919 lists four AS-overlap risks:

sender∩receiver → inherent: relay selection can't fix it (it's the two endpoints themselves). VPN/Tor territory. out of scope.

of the three that selection can address, two don't need your own AS:

relay∩directory → exclude relays in the directory's AS. Needs only the directory + relay ASes.

relay∩relay → the windowed ordering derived from the receiver key. Needs only the relays' ASes.

both use IPs you resolve via DNS anyway to connect, like Bitcoin Core's asmap, which diversifies its peers by AS (anti-eclipse) and never learns its own ASN; you bucket the servers, not yourself.

only user-AS exclusion user∩directory needs your own AS, and thats the one that could be dropped to the network layer (VPN/Tor) , not the selector:

a directory's AS (datacenter) vs a user's AS (residential/mobile) almost never coincide.

the sender uses the directory that came in the URI, so it can't pick a different one to escape its own AS. it can't be addressed in selection.

so, if we drop this and keep just:

directory-AS exclusion relay∩directory

windowed ordering relay∩relay

that way both use only server ASes, zero input, so AS-aware selection can be on by default for everyone, which removes the uses-it-or-not fingerprint, default and zero-input, instead of operator-only.

makes sense?

bc1cindy · 2026-05-28T00:51:33Z

+pub(crate) struct SystemNetwork {
+    #[cfg(feature = "asmap")]
+    asmap: Option<LoadedAsmap>,


with the asmap bundled and the user-AS input dropped, could this Option and the random fallback go, so AS-aware is the default instead of an opt-in?

xstoicunicornx · 2026-07-08T18:23:01Z

New to AS map stuff, but this brand new lib might help? Seems like wouldn't need to load the data from file ourselves?
https://crates.io/crates/asinfo

0xb10c's demo:
https://0xb10c.github.io/asmap-web/?ip=1.1.1.1,8.8.8.8,9.9.9.9&asmap=2026/1772726400_asmap.dat

Mshehu5 · 2026-07-09T15:41:38Z

New to AS map stuff, but this brand new lib might help? Seems like wouldn't need to load the data from file ourselves? https://crates.io/crates/asinfo

0xb10c's demo: https://0xb10c.github.io/asmap-web/?ip=1.1.1.1,8.8.8.8,9.9.9.9&asmap=2026/1772726400_asmap.dat

Thanks I looked into asinfo. I don’t think it replaces the current ASmap crate https://crates.io/crates/asmap for this use case.
asinfo maps:
ASN → metadata
For example given AS13335 it can return the handle/description/country.

But relay selection needs the URL and IP here are steps:
relay URL → DNS IP → ASN

That IP → ASN lookup is what the asmap crate gives us. The CLI resolves the relay/directory hostname then checks the resolved IP against asmap. Without that step we do not know which ASN the relay is actually in.
The 0xB10C demo is using asmap crate for the IP-to-ASN part too

Add a deterministic relay-selection module to the main crate. Applications provide prepared relay candidates. The selector groups them by privacy bucket, orders buckets and relays from the receiver key and time window, and separates POST from POLL when enough buckets are available. This keeps the reusable selection logic independent from DNS resolution, ASMap lookup, directory trust policy, and HTTP transport.

Add optional ASMap configuration for v2 relay selection. The CLI can load an ASMap file and accept user ASNs or user public IPs. Later commits use this information to avoid relays and directories that share an ASN with the user.

Expose OHTTP key fetching through a relay with known socket addresses. ASMap-aware callers resolve and classify relay IPs before making HTTP requests. Passing those addresses into reqwest prevents a second DNS lookup from using a different address than the one that was checked. Move the CLI HTTP client setup behind a builder helper so v2 code can add resolve_to_addrs before building the client. The v1 path still builds a client through http_agent.

Resolve configured v2 directories and OHTTP relays before selection. When ASMap is configured, the CLI maps resolved IPs to ASNs, rejects mixed-ASN hosts, skips directories that share the user ASN, and skips relays that share the user or selected directory ASN. The CLI then converts the remaining relays into main-crate RelayCandidate values. Without ASMap, relays are still resolved and treated as individual URL buckets.

Use the prepared relay selector for v2 OHTTP POST and POLL requests. Sender and receiver flows now derive relay order from the receiver key, request kind, and current time window. OHTTP key fetching also uses resolved relay addresses so the relay used for bootstrapping is the one that was checked. Update e2e child process invocations to pass the local test directory as a trusted directory. Sender and resume paths validate the directory embedded in the BIP21 URI, so the local test directory must be configured explicitly.

Document AS-aware v2 relay selection configuration. Describe how to configure trusted directories, OHTTP relays, ASMap input, and user ASN information so downstream implementations can understand the reference CLI behavior.

Mshehu5 force-pushed the ASN_asmap branch 4 times, most recently from 5a6c956 to d927140 Compare May 6, 2026 22:33

Mshehu5 mentioned this pull request May 7, 2026

PoC: Asmap for relay selection #1452

Closed

Mshehu5 force-pushed the ASN_asmap branch from d927140 to 5e03dea Compare May 7, 2026 15:47

bc1cindy mentioned this pull request May 12, 2026

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

Open

Mshehu5 force-pushed the ASN_asmap branch 7 times, most recently from 6f1528c to 4547e8e Compare May 18, 2026 23:06

Mshehu5 force-pushed the ASN_asmap branch 4 times, most recently from 364ce27 to fab4583 Compare May 24, 2026 14:03

nothingmuch reviewed May 25, 2026

View reviewed changes

bc1cindy reviewed May 25, 2026

View reviewed changes

bc1cindy reviewed May 28, 2026

View reviewed changes

bc1cindy mentioned this pull request May 28, 2026

Tracking: relay-observable behavioral fingerprinting #1586

Open

Mshehu5 force-pushed the ASN_asmap branch from fab4583 to 2d7734c Compare June 14, 2026 15:53

bc1cindy mentioned this pull request Jun 29, 2026

Add core RelaySelector #1694

Open

Mshehu5 force-pushed the ASN_asmap branch 4 times, most recently from 56f7415 to e40e9c3 Compare July 1, 2026 14:54

Mshehu5 force-pushed the ASN_asmap branch 6 times, most recently from 81946ed to 373841f Compare July 6, 2026 12:47

bc1cindy mentioned this pull request Jul 7, 2026

Add core RelaySelector #1696

Open

Mshehu5 force-pushed the ASN_asmap branch 7 times, most recently from 3d701ba to 9c5e332 Compare July 14, 2026 14:49

benalleng added this to the payjoin-cli-1.1 milestone Jul 16, 2026

benalleng added the payjoin-cli label Jul 16, 2026

Mshehu5 added 4 commits July 17, 2026 14:07

Add ASMap configuration

07354b8

Add optional ASMap configuration for v2 relay selection. The CLI can load an ASMap file and accept user ASNs or user public IPs. Later commits use this information to avoid relays and directories that share an ASN with the user.

Mshehu5 force-pushed the ASN_asmap branch from 9c5e332 to fa4f7a7 Compare July 18, 2026 22:48

Mshehu5 added 2 commits July 19, 2026 00:10

Document AS-aware relay selection

acf609f

Document AS-aware v2 relay selection configuration. Describe how to configure trusted directories, OHTTP relays, ASMap input, and user ASN information so downstream implementations can understand the reference CLI behavior.

Mshehu5 force-pushed the ASN_asmap branch from fa4f7a7 to acf609f Compare July 18, 2026 23:10

Uh oh!

Conversation

Mshehu5 commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for CI Build 29664763774

Coverage decreased (-0.7%) to 85.623%

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

arminsabouri commented May 19, 2026

Uh oh!

nothingmuch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bc1cindy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xstoicunicornx commented Jul 8, 2026

Uh oh!

Mshehu5 commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Mshehu5 commented May 1, 2026 •

edited

Loading

coveralls commented May 1, 2026 •

edited

Loading

Mshehu5 commented Jul 9, 2026 •

edited

Loading