Skip to content

Decode BIP 321 URIs without an address (bitcoin:?lightning=…) #212

Closed

Description

@jvsena42

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 lightning parameter, decode the Lightning request and return Scanner::Lightning. Scheme and parameter names should be case-insensitive.
  • With an empty address and an lno parameter, decode it as a BOLT12 offer.
  • With an empty address and no supported payment parameter (for example bitcoin:?amount=0.001), keep returning InvalidAddress.
  • Unified URIs that include an address behave as they do now.

Tests to add

  • bitcoin:?lightning=<uppercase signet invoice> returns Lightning
  • BITCOIN:?LIGHTNING=<invoice> returns Lightning
  • bitcoin:?amount=0.0000799&lightning=<invoice>&creq=… returns Lightning (extra parameters are ignored)
  • bitcoin:?lno=<offer> returns the offer type
  • bitcoin:?amount=0.001 and bitcoin:?lightning= return InvalidAddress

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

  1. self-assigned this
    on Nov 12, 2026
  2. jvsena42 commented on Nov 16, 2026

    @jvsena42
    MemberAuthor

    #218 covers everything here except the BOLT12 offer type. bitcoin:?lno=<offer> returns UnsupportedType there, because Scanner has no offer variant and neither app can pay an offer yet. This issue stays open for that part.

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

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions