Repository navigation
feat: decode BIP 321 URIs without an address - #218
Conversation
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>
talosmachina
left a comment
There was a problem hiding this comment.
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=…containslightning=, notlightning:, so it reaches thebitcoin:branch rather than the bare-Lightning one, and the@node-id check needs an@before the first:. - Existing
req-poptests: every one of them already expectsInvalidFormat, 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 thestarts_with("bc1")check, andbcrt=must start withbcrt1, 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/paytois_bip21_payment_parameteronly matters right after a secondbitcoin:in the query, which a valid URI does not contain. - Amount on an addressless URI with an amountless invoice: the URI's
amountis 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
left a comment
There was a problem hiding this comment.
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)
Pull request was converted to draft
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
left a comment
There was a problem hiding this comment.
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 throughdecode. I ran it in a scratch copy and it passes. With that branch changed toif false && ..., it fails at bip321_tests.rs:356 withErr(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_failsandtest_repeated_req_pop_fails(tests.rs:448, 461, 472), andpop_must_not_appear_twiceaddspop=…&pop=…(bip321_tests.rs:245-260). I removed the"pop"singleton arm (implementation.rs:416) in a scratch copy.pop_must_not_appear_twiceandtest_duplicate_singleton_pop_failsthen 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 servebitcoin:?lightning=<BOLT11>over NFC, and that Square only plans to and serveslightning:<BOLT11>today. This matches issue #212 and thesquare_register_lightning_urifixture.
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 anlnoparameter, decode it as a BOLT12 offer" under Expected. Its test list includes "bitcoin:?lno=<offer>returns the offer type". The PR returnsDecodingError::UnsupportedTypefor this input (implementation.rs:200-205), becauseScannerhas 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, andgh pr view 218lists no closing issues. But the body of commit c82f8a2 still ends withCloses #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 toPart of #212) before merge.
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::decodeforbitcoin:URIs without an address. Numo terminals sendbitcoin:?lightning=<BOLT11>over NFC, and Square plans to switch to it. Before this change, the decoder returnedInvalidAddressfor that form.Description
Results for a
bitcoin:URI:bitcoin:<address>?…OnChainbitcoin:?lightning=<BOLT11>, any caseInvalidAddressLightningbitcoin:?lightning=<LNURL>InvalidAddressbitcoin:?bc=<bc1…>,?tb=<tb1…>,?bcrt=<bcrt1…>InvalidAddressOnChainwith that address;lightningand the other parameters stay inparamsbitcoin:?bc=<tb1…>(address in the wrong parameter)InvalidAddressInvalidAddressbitcoin:?lno=…,?sp=…,?pay=…with no other instructionInvalidAddressUnsupportedTypebitcoin:with no payment instruction (?amount=0.001,?lightning=)InvalidAddressInvalidAddressreq-parameter,req-popincludedInvalidFormatamount/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 asbitcoin:<address>?lightning=…. Otherwise the decoder useslightning.req-parameters: BIP 321 says an unknown required parameter makes the whole URI invalid. Forreq-pop, the wallet must not pay if it won't open the proof-of-payment callback. Bitkit opens no callbacks, so everyreq-parameter is now rejected.req-popURI that used to decode now returnsInvalidFormat.popis still ignored.lno,sp,pay,bc,tbandbcrtas payment parameters.labelandmessageare still not percent-decoded.UnsupportedTypeuntil the scanner has a type for them. Decode BIP 321 URIs without an address (bitcoin:?lightning=…) #212 stays open for the offer type.Test vectors
src/modules/scanner/bip321_tests.rs(31 tests):lno1bogusofferandsp1qsilentpaymentvalues are used verbatim.lightning:<INVOICE>.bitcoin:?lightning=<INVOICE>,BITCOIN:?LIGHTNING=…, and lowercase.amountandcreqparameters.req-checks on URIs without an address.lightningvalue.lightning, lowercase and uppercase. It decodes offline, so it covers the LNURL branch without a network call.Review round 1
lightning_instruction_with_lnurl. It fails when the LNURL branch is disabled.req-poptests intests.rsafter thereq-rule they now hit.pop_must_not_appear_twicealso checkspop=…&pop=…, so it fails if the duplicate-poprule is removed.bitcoin:?lightning=today.Closes #212toPart 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 fmtis clean.cargo clippy --libreports no new warnings in the scanner.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