Repository navigation
Description
Problem
Scanner::decode rejects a BIP 321 URI that has no address and only a Lightning request. It returns DecodingError::InvalidAddress.
BIP 321 allows the address to be empty when a payment method parameter is present, for example bitcoin:?lightning=<bolt11> or bitcoin:?lno=<bolt12 offer>. Point-of-sale terminals use this form:
- Numo serves
bitcoin:?lightning=<BOLT11>over NFC. - Square Register (2nd generation) serves
lightning:<BOLT11>over NFC today and plans to move to the BIP 321 form.
Bitkit can't pay either of those requests until the decoder accepts it, whether it arrives as a QR code, an NFC tag or over Bluetooth.
Reproduction (v0.8.0-rc15)
I ran each input through Scanner::decode in a test on tag v0.8.0-rc15. The invoice is a real 447-character signet BOLT11, uppercase as Square serves it.
| Input | Result |
|---|---|
lightning:LNTBS79900N1P4TZ… |
Lightning ✅ |
bitcoin:?lightning=LNTBS79900N1P4TZ… |
Err(InvalidAddress) ❌ |
BITCOIN:?LIGHTNING=LNTBS79900N1P4TZ… |
Err(InvalidAddress) ❌ |
bitcoin:?lightning=lntbs79900n1p4tz… (lowercase) |
Err(InvalidAddress) ❌ |
bitcoin:?lno=lno1… |
Err(InvalidAddress) ❌ |
bitcoin:bc1q…?lightning=lnbc… |
OnChain with a lightning param ✅ |
Cause: in src/modules/scanner/implementation.rs, the bitcoin: branch validates the address part before anything else. An empty address fails BitcoinAddressValidator::validate_address, so the decoder never reads the query parameters.
Expected
- With an empty address and a
lightningparameter, decode the Lightning request and returnScanner::Lightning. Scheme and parameter names should be case-insensitive. - With an empty address and an
lnoparameter, decode it as a BOLT12 offer. - With an empty address and no supported payment parameter (for example
bitcoin:?amount=0.001), keep returningInvalidAddress. - Unified URIs that include an address behave as they do now.
Tests to add
bitcoin:?lightning=<uppercase signet invoice>returnsLightningBITCOIN:?LIGHTNING=<invoice>returnsLightningbitcoin:?amount=0.0000799&lightning=<invoice>&creq=…returnsLightning(extra parameters are ignored)bitcoin:?lno=<offer>returns the offer typebitcoin:?amount=0.001andbitcoin:?lightning=returnInvalidAddress
Context
Until this is fixed, the Bitkit NFC and nearby payments PRs rewrite bitcoin:?lightning=X to lightning:X in the app before decoding. Requests read from NFC tags and Bluetooth go through that rewrite; QR codes don't. Once core decodes the form, the app rewrite can be removed.
Activity
test: add Square and Numo NFC regression tests
test: add Square and Numo NFC regression tests
jvsena42 commentedon Nov 16, 2026
#218 covers everything here except the BOLT12 offer type.
bitcoin:?lno=<offer>returnsUnsupportedTypethere, becauseScannerhas no offer variant and neither app can pay an offer yet. This issue stays open for that part.