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

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 44314772033

Coverage increased (+0.1%) to 87.842%

Details

  • Coverage increased (+0.1%) from the base build.
  • Patch coverage: 9 uncovered changes across 2 files (295 of 304 lines covered, 97.04%).
  • No coverage regressions found.

Uncovered Changes

File Changed Covered %
payjoin/src/core/uri/mod.rs 282 277 98.23%
payjoin/src/core/uri/error.rs 19 15 78.95%
Total (4 files) 304 295 97.04%

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 18564
Covered Lines: 16307
Line Coverage: 87.84%
Coverage Strength: 128.22 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.

@caarloshenriq
caarloshenriq marked this pull request as ready for review November 11, 2026 20:41
@DanGould DanGould removed the blocked label Nov 12, 2026
@caarloshenriq
caarloshenriq force-pushed the update/bitcoin_uri-0.2 branch 2 times, most recently from 2299db4 to 6ece25d Compare November 13, 2026 18:43

@xstoicunicornx xstoicunicornx left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interested in hearing your thoughts on the set_amount comment, since I'm not at all confident that my feedback is the most appropriate way to handle this. I think I am pretty confident that we would want a way to retain the req- prefixes when appropriate when constructing one uri from another, but could be convinced that it's fine to accept this regression for now and clean it up in a follow up.

/// This rebuilds the URI from its address, amount, label, message and
/// payjoin parameters, so on a parsed URI any other parameter
/// (`lightning`, `sp`, ...) is dropped.
pub fn set_amount(&mut self, amount: Amount) {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Parsing req-pj=… and then calling set_amount prints pj=…. The same happens to req-pjos. This seems to be because the Uri is completely rebuilt piecemeal rather than from the original uri.

I almost think bitcoin_uri should add UriBuilder::from(Uri), or an into_builder(), that seeds the builder with the parsed entries. Alternatively, we could just add a set_amount type helper to bitcoin_uri. Honestly both seem to be nice to have if we expect this to be a universal parser leveraged for things other than just payjoin, however the set_amount helper would probably be the easiest for this PR.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropping req-pj is worse than dropping lightning, since it turns a required payjoin into an optional one, so I fixed that here: set_amount now keeps the req- prefix on amount, pj and pjos when the parsed URI had it. Didn't want to block this PR on a bitcoin_uri release for into_builder.

Other params like lightning are still dropped, which is the documented behavior from #2050. Receivers that want them in the URI should build it with UriBuilder once step 2 there lands, and into_builder looks like a good fit for that

Comment thread Cargo-minimal.lock Resolved
Comment thread payjoin/src/core/uri/mod.rs Outdated
pub(crate) struct PayjoinExtrasAdapter(pub(crate) PayjoinExtras);
/// The extension parameters this crate handles, so `req-pj` and `req-pjos`
/// are accepted while any other `req-` parameter rejects the URI.
const UNDERSTOOD_PARAMS: &[&str] = &["pj", "pjos"];

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bots are suggesting that we should include "amount" here, so that we can accept "req-amount" param. Also maybe add a test for it. They note that this is not a regression introduced by this PR.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added amount, since amount() already reads req-amount through the base key and bitcoin_uri's docs say a caller that honors req-amount should list it. Added a test for it, plus req-label in the rejected cases so it's clear only amount was opened up

Comment thread payjoin/src/core/uri/error.rs Outdated
}
}

impl From<PjParseError> for UriParseError {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know if we need this to be public? Since PjParseError and UriParseError are both re-exported this impl would travel with them.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, replaced it with a pub(super) UriParseError::from_payjoin_params like the other constructors, so nothing leaks into the public API.

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.

@xstoicunicornx xstoicunicornx left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

utACK d8f4b71

This is a straightforward change to upgrade bitcoin_uri dependency to v0.2 which enables more universal bip321 token parsing.

There are two follow ups that I don't think should hold up merging this:

  1. Create an into_builder() api for bitcoin_uri to allow for rebuilding a Uri from an existing one while retaining req- params appropriately. I believe this is also tracked as step 2 from #2050.
  2. Update set_amount() to leverage the new bitcoin_uri api

@caarloshenriq let me know if either of these 2 follow ups need to be adjusted.

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.

4 participants