Skip to content

Migrate URI parsing to bitcoin_uri 0.2 - #1975

Open
caarloshenriq wants to merge 4 commits into
payjoin:masterfrom
caarloshenriq:update/bitcoin_uri-0.2
Open

caarloshenriq wants to merge 4 commits into
payjoin:masterfrom
caarloshenriq:update/bitcoin_uri-0.2

Conversation

@caarloshenriq

@caarloshenriq caarloshenriq commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Depends on payjoin/bitcoin_uri#17. Draft until that is merged and 0.2 is on crates.io, at which point the git dependency switches to the released version.

Moves payjoin onto bitcoin_uri 0.2. The 0.2 parser is a plain BIP 321 tokenizer, so the adapter traits we had for 0.1 are gone and pj/pjos handling now lives in this crate.

What changes:

  • Uri and PjUri wrap an owned bitcoin_uri::Uri and read pj/pjos off it. Duplicate params, pjos without pj and the endpoint checks are enforced here.
  • 0.1 rejected unknown req- params at parse time. 0.2 only reports them, so we reject them ourselves. req-pj and req-pjos are now accepted (0.1 rejected those too), which is what BIP 321 expects.
  • check_pj_supported rebuilds the URI in canonical order (standard params, then pjos, then pj), so the printed URI is the same as before whatever the input order.

The public API and the emitted URIs don't change, so send/receive code and their tests are untouched.

Tests: a bip321 module covering the req- rules, case-insensitive keys, all 120 orderings of five params printing the same, printing being a fixpoint, and every network round-tripping. Plus an integration test that pays, over v1 on regtest, a URI shaped the way a wallet shows it in a QR code (upper case, a lightning fallback, req-pj, reordered params).

Reviewer: @DanGould

Disclosure: co-authored by Claude

Pull Request Checklist

Please confirm the following before requesting review:

@coveralls

coveralls commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Coverage Report for CI Build 43485379827

Coverage decreased (-0.05%) to 87.779%

Details

  • Coverage decreased (-0.05%) from the base build.
  • Patch coverage: 9 uncovered changes across 2 files (267 of 276 lines covered, 96.74%).
  • 145 coverage regressions across 35 files.

Uncovered Changes

File Changed Covered %
payjoin/src/core/uri/mod.rs 256 251 98.05%
payjoin/src/core/uri/error.rs 17 13 76.47%
Total (4 files) 276 267 96.74%

Coverage Regressions

145 previously-covered lines in 35 files lost coverage.

Top 10 Files by Coverage Loss Lines Losing Coverage Coverage
payjoin-cli/src/app/v2/mod.rs 30 56.41%
payjoin-cli/src/app/v1.rs 11 67.37%
payjoin-mailroom/src/directory.rs 11 88.39%
payjoin/src/core/receive/v2/mod.rs 11 93.63%
payjoin/src/core/send/v2/mod.rs 10 88.38%
payjoin/src/core/send/v1.rs 6 92.46%
payjoin-mailroom/src/config.rs 5 65.18%
payjoin/src/core/receive/mod.rs 5 97.74%
payjoin-cli/src/app/config.rs 4 79.15%
payjoin-cli/src/app/v2/ohttp.rs 4 44.74%

Coverage Stats

Coverage Status
Relevant Lines: 18444
Covered Lines: 16190
Line Coverage: 87.78%
Coverage Strength: 128.49 hits per line

💛 - Coveralls

@DanGould

Copy link
Copy Markdown
Member

Merged 0.2.0 which is now on crates.io, so this can be taken out of draft

TODO:

  1. rebase on master
  2. depend on bitcoin_uri = { version = "0.2.0", optional = true } & regenerate lockfiles
  3. Add a changelog line for URIs that used to parse and now fail under BIP 321's rules (repeat keys, different case key counted as repeat, network mismatch) because some may consider this a breaking change though I sincerely doubt anyone depends on this internal behavior and I'm ok leaving it with 1.x
  4. Leave check_pj_supported (
    pub fn check_pj_supported(self) -> Result<PjUri, Box<Self>> {
    match self.extras {
    MaybePayjoinExtras::Supported(extras) => {
    // Rebuild the inner URI so its parameters are emitted in this
    // crate's canonical order (standard BIP21 params, then `pjos`,
    // then `pj`) regardless of the order they were parsed in.
    let address = self
    .inner
    .body()
    .expect("a payjoin BIP21 URI always carries an address")
    .clone();
    let amount = self.inner.amount();
    let label = self.inner.label().and_then(Result::ok);
    let message = self.inner.message().and_then(Result::ok);
    let inner = build_pj_uri(address, amount, label, message, &extras);
    Ok(PjUri { inner, extras })
    }
    MaybePayjoinExtras::Unsupported => Err(Box::new(self)),
    }
    }
    ) as it is for this PR. It rebuilds the URI it parsed, so a PjUri would print without non-payjoin params. That's the payjoin crate's work for Bitcoin-uri fuzzing crash bitcoin_uri#10. I'll open a separate issue for carrying params across this boundary (and in set_amount, perhaps deprecating it and recommending the Uri crate itself) as a follow-up

After this merges, the next thing to do is reading pj from any BIP 321 URI through payjoin-ffi including one with no address as its own PR.

bitcoin_uri 0.2 is a plain BIP 321 tokenizer and no longer takes a
deserialization hook for extension params, so the payjoin adapter
traits go away. Uri and PjUri now wrap an owned bitcoin_uri::Uri and
read pj/pjos with get_all, keeping the payjoin rules (duplicates, pjos
without pj, endpoint checks) in this crate.

bitcoin_uri 0.2 reports req- parameters instead of rejecting them, so
the BIP 321 rule that a URI with a required parameter we cannot handle
MUST be rejected is enforced here. req-pj and req-pjos are understood.

UriBuilder::build needs a network, but a checked address does not
expose its own, so network_of probes for one the address is valid for.

check_pj_supported rebuilds the inner URI so Display keeps the
canonical param order (standard params, then pjos, then pj) whatever
the input order was. The public API and the emitted URI are unchanged,
so senders, receivers and their tests are untouched.
Pin how the payjoin Uri consumes bitcoin_uri's BIP 321 tokenizer:
unknown req- parameters are rejected while req-pj and req-pjos are
understood, keys match case-insensitively, a URI needs a body address,
and every network survives a print and re-parse.

Display is checked to be canonical: all 120 orderings of the same five
parameters print identically, and printing is a fixpoint after one
round.
The integration tests hand the sender the receiver's own printed URI.
A wallet shows it differently in a QR code: upper-case scheme, keys
and bech32 address, a lightning fallback, pj marked as required and
the parameters reordered. Pay such a URI over v1 on regtest to check
that bitcoin_uri 0.2 parsing holds up through a full payjoin
check_pj_supported rebuilt the URI from the parameters payjoin reads,
so printing a sender's PjUri dropped any other parameter, such as a
lightning or sp fallback, and reordered the rest. Keep the parsed
bitcoin_uri::Uri instead, so a PjUri prints exactly what it parsed.

set_amount still rebuilds the URI, so document that it drops those
parameters on a parsed URI. Replacing it is left to a follow-up.

Tests that pinned the canonical output now check that the input is
printed unchanged.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants