integrate BIP21-style silent payment URI support

Author: kratm2

electrum/bip21.py

@@ -7,7 +7,8 @@
 from .util import format_satoshis_plain
 from .bitcoin import COIN, TOTAL_COIN_SUPPLY_LIMIT_IN_BTC
 from .lnaddr import lndecode, LnDecodeException
-from .silent_payment import is_silent_payment_address
+from .silent_payment import SilentPaymentAddress
+from . import constants
 
 # note: when checking against these, use .lower() to support case-insensitivity
 BITCOIN_BIP21_URI_SCHEME = 'bitcoin'
@@ -17,6 +18,10 @@
 class InvalidBitcoinURI(Exception):
     pass
 
+class MissingFallbackAddress(Exception):
+    """Raised when a fallback address was required but not provided in the BIP21 URI."""
+    pass
+
 
 def parse_bip21_URI(uri: str) -> dict:
     """Raises InvalidBitcoinURI on malformed URI."""
@@ -50,7 +55,7 @@ def parse_bip21_URI(uri: str) -> dict:
 
     out = {k: v[0] for k, v in pq.items()}
     if address:
-        if not bitcoin.is_address(address) and not is_silent_payment_address(address):
+        if not bitcoin.is_address(address):
             raise InvalidBitcoinURI(f"Invalid bitcoin address: {address}")
         out['address'] = address
     if 'amount' in out:
@@ -101,6 +106,17 @@ def parse_bip21_URI(uri: str) -> dict:
             if ln_fallback_addr != address:
                 raise InvalidBitcoinURI("Inconsistent lightning field in bip21: address")
 
+    # silent payment
+    for key in ('sp', 'tsp'):
+        if key in out:
+            if key != constants.net.BIP352_HRP:
+                raise InvalidBitcoinURI(
+                    f"Silent payment field '{key}' does not match expected network HRP '{constants.net.BIP352_HRP}'")
+            try:
+                SilentPaymentAddress(out[key])  # validates SP address
+            except Exception as e:
+                raise InvalidBitcoinURI(f"Failed to decode '{key}' field: {e!r}") from e
+
     return out
 
 

electrum/gui/qt/send_tab.py

@@ -223,7 +223,7 @@ def on_amount_changed(self, text):
         is_spk_script = pi.type == PaymentIdentifierType.SPK and not pi.spk_is_address
         valid_amount = is_spk_script or bool(self.amount_e.get_amount())
         ready_to_finalize = not pi.need_resolve()
-        sp_ok = self.wallet_can_send_sp if pi.involves_silent_payments() else True
+        sp_ok = self.wallet_can_send_sp if pi.involves_silent_payments(self.wallet_can_send_sp) else True
         self.send_button.setEnabled(pi.is_valid() and not pi_error and valid_amount and ready_to_finalize and sp_ok)
 
     def do_paste(self):
@@ -427,7 +427,7 @@ def update_fields(self):
 
         self.clear_button.setEnabled(True)
 
-        involves_sp = pi.involves_silent_payments() # invoices involving silent payment are not persisted
+        involves_sp = pi.involves_silent_payments(self.wallet_can_send_sp) # invoices involving silent payment are not persisted
         sp_ok = self.wallet_can_send_sp if involves_sp else True
 
         if pi.is_multiline():
@@ -457,7 +457,7 @@ def update_fields(self):
                          lock_max=lock_max,
                          lock_description=False)
         if lock_recipient:
-            fields = pi.get_fields_for_GUI()
+            fields = pi.get_fields_for_GUI(bip21_prefer_fallback=not self.wallet_can_send_sp)
             if fields.recipient:
                 self.payto_e.setText(fields.recipient)
             if fields.description:

electrum/payment_identifier.py

@@ -19,9 +19,11 @@
 from .bitcoin import opcodes, construct_script
 from .lnaddr import LnInvoiceException
 from .lnutil import IncompatibleOrInsaneFeatures
-from .bip21 import parse_bip21_URI, InvalidBitcoinURI, LIGHTNING_URI_SCHEME, BITCOIN_BIP21_URI_SCHEME
+from .bip21 import parse_bip21_URI, InvalidBitcoinURI, LIGHTNING_URI_SCHEME, BITCOIN_BIP21_URI_SCHEME, \
+    MissingFallbackAddress
 from . import paymentrequest
 from .silent_payment import is_silent_payment_address, SILENT_PAYMENT_DUMMY_SPK, SilentPaymentAddress
+from . import constants
 
 if TYPE_CHECKING:
     from .wallet import Abstract_Wallet
@@ -176,7 +178,8 @@ def is_onchain(self):
         if self._type in [PaymentIdentifierType.LNURLP, PaymentIdentifierType.BOLT11, PaymentIdentifierType.LNADDR]:
             return bool(self.bolt11) and bool(self.bolt11.get_address())
         if self._type == PaymentIdentifierType.BIP21:
-            return bool(self.bip21.get('address', None)) or (bool(self.bolt11) and bool(self.bolt11.get_address()))
+            return (bool(self.bip21.get('address', None)) or bool(self.bip21.get(constants.net.BIP352_HRP, None)) or
+                    (bool(self.bolt11) and bool(self.bolt11.get_address())))
 
     def is_multiline(self):
         return bool(self.multiline_outputs)
@@ -268,8 +271,9 @@ def parse(self, text: str):
                             self.bolt11.outputs = [PartialTxOutput.from_address_and_value(bip21_address, amount)]
                     except InvoiceError as e:
                         self.logger.debug(self._get_error_from_invoiceerror(e))
-                elif not self.bip21.get('address'):
-                    # no address and no bolt11, invalid
+                elif not self.bip21.get('address') and not self.bip21.get(constants.net.BIP352_HRP):
+                    print(self.bip21.get(constants.net.BIP352_HRP))
+                    # no address, no bolt11 and no silent payment address, invalid
                     self.set_state(PaymentIdentifierState.INVALID)
                     return
                 self.set_state(PaymentIdentifierState.AVAILABLE)
@@ -464,7 +468,7 @@ async def _do_notify_merchant(
             if on_finished:
                 on_finished(self)
 
-    def get_onchain_outputs(self, amount):
+    def get_onchain_outputs(self, amount, bip21_use_fallback=False):
         if self.bip70:
             return self.bip70_data.get_outputs()
         elif self.multiline_outputs:
@@ -476,7 +480,17 @@ def get_onchain_outputs(self, amount):
                 output.sp_addr = SilentPaymentAddress(addr)
             return [output]
         elif self.bip21:
-            address = self.bip21.get('address')
+            address = self.bip21.get('address') # fallback address if sp_address is present
+            sp_address = self.bip21.get(constants.net.BIP352_HRP)
+
+            if sp_address:
+                if bip21_use_fallback:
+                    if not address:
+                        raise MissingFallbackAddress('requested BIP21 fallback address but none was provided.')
+                    # fallback is requested and present, keep using `address`
+                else:
+                    address = sp_address  # use silent payment address
+
             scriptpubkey, is_address = self.parse_output(address)
             assert is_address  # unlikely, but make sure it is an address, not a script
             output = PartialTxOutput(scriptpubkey=scriptpubkey, value=amount)
@@ -581,7 +595,7 @@ def _get_error_from_invoiceerror(self, e: 'InvoiceError') -> str:
                 error = _("Invoice requires unknown or incompatible Lightning feature") + f":\n{e!r}"
         return error
 
-    def get_fields_for_GUI(self) -> FieldsForGUI:
+    def get_fields_for_GUI(self, *, bip21_prefer_fallback=False) -> FieldsForGUI:
         recipient = None
         amount = None
         description = None
@@ -633,6 +647,9 @@ def get_fields_for_GUI(self) -> FieldsForGUI:
         elif self.bip21:
             label = self.bip21.get('label')
             address = self.bip21.get('address')
+            sp_address = self.bip21.get(constants.net.BIP352_HRP)
+            if sp_address and not (address and bip21_prefer_fallback): # return fallback address if provided and needed
+                address = sp_address
             recipient = f'{label} <{address}>' if label else address
             amount = self.bip21.get('amount')
             description = self.bip21.get('message')
@@ -680,9 +697,14 @@ def has_expired(self):
             return bool(expires) and expires < time.time()
         return False
 
-    def involves_silent_payments(self):
+    def involves_silent_payments(self, wallet_can_send_sp=True) -> bool:
         try:
-            return any(o.is_silent_payment() for o in self.get_onchain_outputs(0))
+            return any(o.is_silent_payment() for o
+                       in self.get_onchain_outputs(0, bip21_use_fallback=not wallet_can_send_sp))
+        except MissingFallbackAddress:
+            # BIP21 URI contained only a silent payment address, and the wallet cannot send to it.
+            # Since no fallback address was provided, we treat this as involving silent payments.
+            return True
         except Exception as e:
             return False
 
@@ -704,7 +726,7 @@ def invoice_from_payment_identifier(
             invoice.set_amount_msat(int(amount_sat * 1000))
         return invoice
     else:
-        outputs = pi.get_onchain_outputs(amount_sat)
+        outputs = pi.get_onchain_outputs(amount_sat, bip21_use_fallback=not wallet.can_send_silent_payment())
         message = pi.bip21.get('message') if pi.bip21 else message
         bip70_data = pi.bip70_data if pi.bip70 else None
         return wallet.create_invoice(

electrum/silent_payment.py

@@ -14,40 +14,13 @@
 
 class SilentPaymentUnsupportedWalletException(Exception): pass
 
-class SilentPaymentAddress:
-    """
-        Takes a silent payment address and decodes into keys. Raises if address is invalid.
-    """
-    def __init__(self, address: str, *, net=None):
-        if net is None: net = constants.net
-        self._encoded = address
-        self._B_Scan, self._B_Spend = _decode_silent_payment_addr(net.BIP352_HRP, address)
-
-    @property
-    def encoded(self) -> str:
-        return self._encoded
-
-    @property
-    def B_Scan(self) -> ecc.ECPubkey:
-        return self._B_Scan
-
-    @property
-    def B_Spend(self) -> ecc.ECPubkey:
-        return self._B_Spend
-
-    def __eq__(self, other):
-        if not isinstance(other, SilentPaymentAddress):
-            return NotImplemented
-        return self.encoded == other.encoded
-
-    def __hash__(self):
-        return hash(self.encoded)
-
 class SilentPaymentException(Exception):
     def __init__(self, message: str):
         self.message = message
         super().__init__(message)
 
+class InvalidSilentPaymentAddress(SilentPaymentException): pass
+
 class SilentPaymentReuseException(SilentPaymentException):
     def __init__(self, reused_address: str):
         short_addr = reused_address[:8] + "…" + reused_address[-8:]
@@ -75,6 +48,38 @@ def __init__(self):
         )
         super().__init__(msg)
 
+class SilentPaymentAddress:
+    """
+        Takes a silent payment address and decodes into keys. Raises InvalidSilentPaymentAddress if address is invalid.
+    """
+    def __init__(self, address: str, *, net=None):
+        if net is None: net = constants.net
+        try:
+            self._B_Scan, self._B_Spend = _decode_silent_payment_addr(net.BIP352_HRP, address)
+        except Exception as e:
+            raise InvalidSilentPaymentAddress(address) from e
+        self._encoded = address
+
+    @property
+    def encoded(self) -> str:
+        return self._encoded
+
+    @property
+    def B_Scan(self) -> ecc.ECPubkey:
+        return self._B_Scan
+
+    @property
+    def B_Spend(self) -> ecc.ECPubkey:
+        return self._B_Spend
+
+    def __eq__(self, other):
+        if not isinstance(other, SilentPaymentAddress):
+            return NotImplemented
+        return self.encoded == other.encoded
+
+    def __hash__(self):
+        return hash(self.encoded)
+
 def create_silent_payment_outputs(input_privkeys: list[ECPrivkey],
                                   outpoints: list['TxOutpoint'],
                                   recipients: list[SilentPaymentAddress],

tests/test_payment_identifier.py

@@ -1,6 +1,7 @@
 import os
 
 from electrum import SimpleConfig
+from electrum.bip21 import MissingFallbackAddress
 from electrum.invoices import Invoice
 from electrum.payment_identifier import (maybe_extract_lightning_payment_identifier, PaymentIdentifier,
                                          PaymentIdentifierType, invoice_from_payment_identifier)
@@ -379,10 +380,30 @@ def test_silent_payment_multiline(self):
         self.assertEqual('3!', pi.multiline_outputs[2].value)
 
     def test_silent_payment_bip21(self):
-        bip21 = 'bitcoin:sp1qqvwfct0plnus9vnyd08tvvcwq49g7xfjt3fnwcyu5zc29fj969fg7q4ffc6dnhl9anhec779az46rstpp0t6kzxqmg4tkelfhrejl532ycfaxvsj?message=sp_unit_test?amount=0.001'
+        # The PaymentIdentifier is considered valid if the BIP21 URI itself is valid,
+        # regardless of whether the wallet is silent payment-capable.
+
+        # test no fallback
+        bip21 = 'bitcoin:?sp=sp1qqvwfct0plnus9vnyd08tvvcwq49g7xfjt3fnwcyu5zc29fj969fg7q4ffc6dnhl9anhec779az46rstpp0t6kzxqmg4tkelfhrejl532ycfaxvsj&message=sp_unit_test&amount=0.001'
         pi = PaymentIdentifier(None, bip21)
         self.assertTrue(pi.is_available())
-        self.assertFalse(pi.is_lightning())
         self.assertTrue(pi.is_onchain())
         self.assertIsNotNone(pi.bip21)
-        self.assertTrue(pi.involves_silent_payments())
+        self.assertTrue(pi.involves_silent_payments(True)) # wallet is sp-capable
+        self.assertTrue(pi.involves_silent_payments(False)) # wallet is not sp-capable, but there is no fallback -> involves
+        # Raise in get_onchain_outputs if fallback is requested but non is present
+        self.assertRaises(MissingFallbackAddress, pi.get_onchain_outputs, 0, bip21_use_fallback=True)
+
+        # test with fallback in context where wallet is silent payment capable
+        bip21 = 'bitcoin:1RustyRX2oai4EYYDpQGWvEL62BBGqN9T?sp=sp1qqvwfct0plnus9vnyd08tvvcwq49g7xfjt3fnwcyu5zc29fj969fg7q4ffc6dnhl9anhec779az46rstpp0t6kzxqmg4tkelfhrejl532ycfaxvsj&message=sp_unit_test&amount=0.001'
+        pi = PaymentIdentifier(None, bip21)
+        self.assertTrue(pi.is_available())
+        self.assertTrue(pi.is_onchain())
+        self.assertIsNotNone(pi.bip21)
+        self.assertTrue(pi.involves_silent_payments(True)) # wallet is sp-capable, so fallback is ignored
+        self.assertFalse(pi.involves_silent_payments(False))  # wallet is not sp-capable, so fallback is taken -> no sp-involvement
+        # make sure fallback is taken from get_onchain_outputs if wallet can not send sp
+        self.assertEqual(
+            pi.get_onchain_outputs(0, bip21_use_fallback=True)[0].address,
+            '1RustyRX2oai4EYYDpQGWvEL62BBGqN9T'
+        )

tests/test_util.py

@@ -187,6 +187,47 @@ def test_parse_URI_lightning_consistency(self):
         # bip21 uri that includes "lightning" key with garbage unparsable value
         self.assertRaises(InvalidBitcoinURI, parse_bip21_URI, 'bitcoin:tb1qu5ua3szskclyd48wlfdwfd32j65phxy9yf7ytl?amount=0.0008&message=test266&lightning=lntb700u1p3kqy26pp5l7rj7w0u5sdsj24umzdlhdasdasdasdasd')
 
+    def test_parse_URI_sp_with_no_fallback(self):
+        self._do_test_parse_URI(
+            'bitcoin:?sp=sp1qqvwfct0plnus9vnyd08tvvcwq49g7xfjt3fnwcyu5zc29fj969fg7q4ffc6dnhl9anhec779az46rstpp0t6kzxqmg4tkelfhrejl532ycfaxvsj&amount=0.001',
+            { 'sp': 'sp1qqvwfct0plnus9vnyd08tvvcwq49g7xfjt3fnwcyu5zc29fj969fg7q4ffc6dnhl9anhec779az46rstpp0t6kzxqmg4tkelfhrejl532ycfaxvsj', 'amount': 100000}
+        )
+
+    def test_parse_URI_sp_with_fallback(self):
+        self._do_test_parse_URI(
+            'bitcoin:15mKKb2eos1hWa6tisdPwwDC1a5J1y9nma?sp=sp1qqvwfct0plnus9vnyd08tvvcwq49g7xfjt3fnwcyu5zc29fj969fg7q4ffc6dnhl9anhec779az46rstpp0t6kzxqmg4tkelfhrejl532ycfaxvsj&amount=0.001',
+            { 'address': '15mKKb2eos1hWa6tisdPwwDC1a5J1y9nma', 'sp': 'sp1qqvwfct0plnus9vnyd08tvvcwq49g7xfjt3fnwcyu5zc29fj969fg7q4ffc6dnhl9anhec779az46rstpp0t6kzxqmg4tkelfhrejl532ycfaxvsj', 'amount': 100000}
+        )
+
+    def test_parse_URI_invalid_sp_addresses(self):
+        # hrp / network mismatch
+        self.assertRaises(InvalidBitcoinURI, parse_bip21_URI, 'bitcoin:?sp=tsp1qq0aut0j4rpngmjf55a6nr98h0kvlc2s83jwv8h9rmaqpgjqvc67wyqefkstjcfchzd9hpy84qara7dwu6jfpx2p9amjwg4j4hv3hsla8nvqa4ap0')
+        self.assertRaises(InvalidBitcoinURI, parse_bip21_URI, 'bitcoin:?tsp=sp1qqvwfct0plnus9vnyd08tvvcwq49g7xfjt3fnwcyu5zc29fj969fg7q4ffc6dnhl9anhec779az46rstpp0t6kzxqmg4tkelfhrejl532ycfaxvsj')
+        # invalid sp addr
+        self.assertRaises(InvalidBitcoinURI, parse_bip21_URI, 'bitcoin:?sp=sp_invalid_sp')
+
+
+    @as_testnet
+    def test_parse_URI_testnet_sp_with_no_fallback(self):
+        self._do_test_parse_URI(
+            'bitcoin:?tsp=tsp1qq0aut0j4rpngmjf55a6nr98h0kvlc2s83jwv8h9rmaqpgjqvc67wyqefkstjcfchzd9hpy84qara7dwu6jfpx2p9amjwg4j4hv3hsla8nvqa4ap0&amount=0.001',
+            {
+                'tsp': 'tsp1qq0aut0j4rpngmjf55a6nr98h0kvlc2s83jwv8h9rmaqpgjqvc67wyqefkstjcfchzd9hpy84qara7dwu6jfpx2p9amjwg4j4hv3hsla8nvqa4ap0',
+                'amount': 100000
+            }
+        )
+
+    @as_testnet
+    def test_parse_URI_testnet_sp_with_fallback(self):
+        self._do_test_parse_URI(
+            'bitcoin:tb1qesj6xuz9963tca9y8e09dpwu8a48t3nmvs26je?tsp=tsp1qq0aut0j4rpngmjf55a6nr98h0kvlc2s83jwv8h9rmaqpgjqvc67wyqefkstjcfchzd9hpy84qara7dwu6jfpx2p9amjwg4j4hv3hsla8nvqa4ap0&amount=0.001',
+            {
+                'address': 'tb1qesj6xuz9963tca9y8e09dpwu8a48t3nmvs26je',
+                'tsp': 'tsp1qq0aut0j4rpngmjf55a6nr98h0kvlc2s83jwv8h9rmaqpgjqvc67wyqefkstjcfchzd9hpy84qara7dwu6jfpx2p9amjwg4j4hv3hsla8nvqa4ap0',
+                'amount': 100000
+            }
+        )
+
     def test_is_hash256_str(self):
         self.assertTrue(is_hash256_str('09a4c03e3bdf83bbe3955f907ee52da4fc12f4813d459bc75228b64ad08617c7'))
         self.assertTrue(is_hash256_str('2A5C3F4062E4F2FCCE7A1C7B4310CB647B327409F580F4ED72CB8FC0B1804DFA'))