Skip to content

feat: decode BIP 321 URIs without an address - #218

Merged
jvsena42 merged 4 commits into
masterfrom
feat/bip321-uris
Nov 16, 2026
Merged

jvsena42 merged 4 commits into
masterfrom
feat/bip321-uris

Conversation

@jvsena42

@jvsena42 jvsena42 commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Part of #212. The BOLT12 offer type that #212 asks for is left for a follow-up, so the issue stays open.

Adds BIP 321 support to Scanner::decode for bitcoin: URIs without an address. Numo terminals send bitcoin:?lightning=<BOLT11> over NFC, and Square plans to switch to it. Before this change, the decoder returned InvalidAddress for that form.

Description

Results for a bitcoin: URI:

URI Before After
bitcoin:<address>?… OnChain unchanged
bitcoin:?lightning=<BOLT11>, any case InvalidAddress Lightning
bitcoin:?lightning=<LNURL> InvalidAddress the LNURL result
bitcoin:?bc=<bc1…>, ?tb=<tb1…>, ?bcrt=<bcrt1…> InvalidAddress OnChain with that address; lightning and the other parameters stay in params
bitcoin:?bc=<tb1…> (address in the wrong parameter) InvalidAddress InvalidAddress
bitcoin:?lno=…, ?sp=…, ?pay=… with no other instruction InvalidAddress UnsupportedType
bitcoin: with no payment instruction (?amount=0.001, ?lightning=) InvalidAddress InvalidAddress
any req- parameter, req-pop included decoded InvalidFormat
  • Without an address: the URI goes through the same checks as one with an address: embedded second URIs, repeated amount/label/message/pop, and required parameters. Only then does the decoder pick an instruction. A segwit fallback address comes first, so the apps get the same unified result as bitcoin:<address>?lightning=…. Otherwise the decoder uses lightning.
  • req- parameters: BIP 321 says an unknown required parameter makes the whole URI invalid. For req-pop, the wallet must not pay if it won't open the proof-of-payment callback. Bitkit opens no callbacks, so every req- parameter is now rejected.
    • Breaking change: a req-pop URI that used to decode now returns InvalidFormat.
    • Optional pop is still ignored.
  • Embedded URIs: detection now also treats lno, sp, pay, bc, tb and bcrt as payment parameters.
  • Not covered:

Test vectors

src/modules/scanner/bip321_tests.rs (31 tests):

  • BIP 321 appendix: every URI, invalid URI and proof-of-payment example.
    • The BIP's example addresses and invoice are intentionally invalid. A test checks that they fail.
    • The vectors that need a payable address or invoice use valid ones of the same kind: the genesis P2PKH address, BIP 173/350 segwit v0, v1 and testnet addresses, and a signed mainnet invoice.
    • The lno1bogusoffer and sp1qsilentpayment values are used verbatim.
  • Point-of-sale NFC payloads, from the Bitkit NFC work (feat: nfc and bluetooth nearby payments bitkit-android#1883, feat: nfc and bluetooth nearby payments bitkit-ios#1302):
    • A real signet invoice of the size a Square Register (2nd gen) serves: 447 characters, uppercase as in its QR code, 7,990 sats.
    • Square's current form, lightning:<INVOICE>.
    • Numo's form in each casing: bitcoin:?lightning=<INVOICE>, BITCOIN:?LIGHTNING=…, and lowercase.
    • The same with extra amount and creq parameters.
  • Edge cases:
    • Empty instructions.
    • Singleton and req- checks on URIs without an address.
    • An embedded URI after a lightning value.
    • Invalid Lightning and segwit instructions.
    • An LNURL-auth string in lightning, lowercase and uppercase. It decodes offline, so it covers the LNURL branch without a network call.

Review round 1

  • Added lightning_instruction_with_lnurl. It fails when the LNURL branch is disabled.
  • Renamed the req-pop tests in tests.rs after the req- rule they now hit. pop_must_not_appear_twice also checks pop=…&pop=…, so it fails if the duplicate-pop rule is removed.
  • The changelog no longer says Square serves bitcoin:?lightning= today.
  • Changed Closes #212 to Part of #212.

Preview

N/A (library).

QA Notes

  • cargo test --lib modules::scanner: 79 passed, the 48 existing scanner tests and the 31 new ones.
  • cargo fmt is clean. cargo clippy --lib reports no new warnings in the scanner.
  • After this ships, the apps can drop their bitcoin:?lightning= → lightning: rewrite for NFC and Bluetooth requests. QR codes in the Numo form will also start working. Both are follow-ups in the app repos.

🤖 Generated with Claude Code

bitcoin:?lightning=<BOLT11> decodes as Lightning, and a segwit address in
the bc/tb/bcrt parameter decodes as on-chain. Unsupported instructions
(lno, sp, pay) return UnsupportedType. Unknown req- parameters, req-pop
included, make the URI invalid as BIP 321 requires.

Adds the BIP 321 appendix vectors and the Square/Numo NFC payloads as tests.

Closes #212

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jvsena42 jvsena42 self-assigned this Nov 16, 2026

@talosmachina talosmachina left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

No findings. Decodes BIP 321 bitcoin: URIs that have no address: the bc/tb/bcrt fallback becomes on-chain, lightning becomes Lightning or LNURL, lno/sp/pay alone give UnsupportedType, and any req- parameter is now refused. Reviewed c82f8a2, full tier, static only: the build was skipped (talos-pr-run could not confirm the author's write permission and fails closed), so I did not run the new tests.

What I checked, and 6 candidates I ruled out

Read in full: scanner/implementation.rs (decode, decode_bitcoin_uri, decode_onchain, contains_embedded_bip21_uri, is_bip21_payment_parameter), the test names in bip321_tests.rs, and the req-pop cases in scanner/tests.rs.
Call sites traced: decode_onchain is called only from scanner (implementation and tests). is_bip21_payment_parameter is called only from contains_embedded_bip21_uri.
CI: no workflow runs modules::scanner. The cargo test jobs cover only paykit_route, usdt and wake, so neither CI nor this review has run the 30 new tests or the existing scanner tests against the req- change.

Ruled out

  • Dispatch order in decode: bitcoin:?lightning=… contains lightning=, not lightning:, so it reaches the bitcoin: branch rather than the bare-Lightning one, and the @ node-id check needs an @ before the first :.
  • Existing req-pop tests: every one of them already expects InvalidFormat, through a duplicate singleton or an embedded URI, so returning that error earlier does not change what they check.
  • Network prefix spoofing: bc=bcrt1… fails the starts_with("bc1") check, and bcrt= must start with bcrt1, so an address cannot hide in the wrong parameter.
  • Uppercase payloads: the scheme check, the keys and the values are all lowercased before matching or decoding, which covers the uppercase Square invoice.
  • New embedded-URI keywords: adding bc/tb/bcrt/lno/sp/pay to is_bip21_payment_parameter only matters right after a second bitcoin: in the query, which a valid URI does not contain.
  • Amount on an addressless URI with an amountless invoice: the URI's amount is dropped when it decodes as Lightning, but a payment terminal's invoice carries its own amount, so this needs a payload no known sender produces.

Merge confidence: 4/5, no findings, but no run has exercised the change: the build was skipped here and CI does not run the scanner tests.

@coreyphillips coreyphillips 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.

Two independent reviews.

worth doing, does not block

  • bitcoin:?lno= returns UnsupportedType, but issue #212 asks for an offer type (src/modules/scanner/implementation.rs:200-205)
  • No test covers the LNURL branch for bitcoin:?lightning=<LNURL> (src/modules/scanner/implementation.rs:191-197)

nits

  • Duplicate-pop tests now pass for a different reason than their names say (src/modules/scanner/bip321_tests.rs:236-245)

the reviewers disagree, your call

  • Changelog says Square terminals already serve bitcoin:?lightning= (CHANGELOG.md:5)

Comment thread src/modules/scanner/implementation.rs Resolved
Comment thread src/modules/scanner/implementation.rs Resolved
Comment thread src/modules/scanner/bip321_tests.rs Resolved
Comment thread CHANGELOG.md Resolved
@jvsena42
jvsena42 marked this pull request as draft November 16, 2026 12:13
auto-merge was automatically disabled November 16, 2026 12:13

Pull request was converted to draft

jvsena42 and others added 3 commits November 16, 2026 09:18
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@coreyphillips coreyphillips 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.

Rechecked after 3 new commits (727d53f, 89f6674, 4c93dc6). Nothing blocking remains.

addressed

  • No test covers the LNURL branch for bitcoin:?lightning=<LNURL> (src/modules/scanner/implementation.rs:191-197). Fixed: lightning_instruction_with_lnurl (src/modules/scanner/bip321_tests.rs:341-359) reaches the branch at implementation.rs:193 through decode. I ran it in a scratch copy and it passes. With that branch changed to if false && ..., it fails at bip321_tests.rs:356 with Err(InvalidFormat).
  • Duplicate-pop tests now pass for a different reason than their names say (src/modules/scanner/bip321_tests.rs:236-245). Fixed: The three tests are now test_pop_with_req_pop_fails, test_req_pop_then_pop_fails and test_repeated_req_pop_fails (tests.rs:448, 461, 472), and pop_must_not_appear_twice adds pop=…&pop=… (bip321_tests.rs:245-260). I removed the "pop" singleton arm (implementation.rs:416) in a scratch copy. pop_must_not_appear_twice and test_duplicate_singleton_pop_fails then fail, and the renamed tests still pass, which matches their new names.
  • Changelog says Square terminals already serve bitcoin:?lightning= (CHANGELOG.md:5). Fixed: CHANGELOG.md:5 now says Numo terminals serve bitcoin:?lightning=<BOLT11> over NFC, and that Square only plans to and serves lightning:<BOLT11> today. This matches issue #212 and the square_register_lightning_uri fixture.

still open

  • bitcoin:?lno= returns UnsupportedType, but issue #212 asks for an offer type (src/modules/scanner/implementation.rs:200-205). Issue #212 lists "With an empty address and an lno parameter, decode it as a BOLT12 offer" under Expected. Its test list includes "bitcoin:?lno=<offer> returns the offer type". The PR returns DecodingError::UnsupportedType for this input (implementation.rs:200-205), because Scanner has no offer variant. The description says so openly, but the PR still says "Closes #212", so merging it would close the issue with that requirement unmet. The BOLT11 path that Numo and Square need is complete. Either change the PR to "Part of #212" and open a follow-up for the offer type, or add the variant here. Claude still sees it: The PR body now says Part of #212, and gh pr view 218 lists no closing issues. But the body of commit c82f8a2 still ends with Closes #212. This repo merges PRs with merge commits, and its squash default (COMMIT_MESSAGES) would copy that line too, so merging still closes #212 with the offer type unmet. Leaving the variant out is fine. Reword that commit message (for example to Part of #212) before merge.

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