cli: add max_cltv parameter to lnpay

Adds a `max_cltv` parameter to the `lnpay` cli command which allows to
specify the maximum total locktime of the payment. This is enabled by
constructing a custom `PaymentFeeBudget` object in the lnpay command and
passing it as argument to `LNWallet.pay_invoice()`.
Allowing to specify a `max_cltv` value can be useful for certain
usecases, e.g. see #10056.

Closes #10056

Author: f321x

electrum/commands.py

@@ -67,7 +67,8 @@
 )
 from .address_synchronizer import TX_HEIGHT_LOCAL
 from .mnemonic import Mnemonic
-from .lnutil import channel_id_from_funding_tx, LnFeatures, SENT, MIN_FINAL_CLTV_DELTA_FOR_INVOICE
+from .lnutil import (channel_id_from_funding_tx, LnFeatures, SENT, MIN_FINAL_CLTV_DELTA_FOR_INVOICE,
+                     PaymentFeeBudget, NBLOCK_CLTV_DELTA_TOO_FAR_INTO_FUTURE)
 from .plugin import run_hook, DeviceMgr, Plugins
 from .version import ELECTRUM_VERSION
 from .simple_config import SimpleConfig
@@ -1725,7 +1726,16 @@ async def decode_invoice(self, invoice: str):
         return invoice.to_debug_json()
 
     @command('wnpl')
-    async def lnpay(self, invoice, timeout=120, password=None, wallet: Abstract_Wallet = None):
+    async def lnpay(
+        self,
+        invoice: str,
+        timeout: int = 120,
+        max_cltv: Optional[int] = None,
+        max_fee_millionths: Optional[int] = None,
+        fee_cutoff_msat: Optional[int] = None,
+        password=None,
+        wallet: Abstract_Wallet = None
+    ):
         """
         Pay a lightning invoice
         Note: it is *not* safe to try paying the same invoice multiple times with a timeout.
@@ -1734,6 +1744,9 @@ async def lnpay(self, invoice, timeout=120, password=None, wallet: Abstract_Wall
 
         arg:str:invoice:Lightning invoice (bolt 11)
         arg:int:timeout:Timeout in seconds (default=120)
+        arg:int:max_cltv:Maximum total time lock for the route (default=4032+invoice_final_cltv_delta)
+        arg:int:max_fee_millionths:Maximum fees allowed for this payment (default=ConfigVar(lightning_payment_fee_max_millionths))
+        arg:int:fee_cutoff_msat:Minimum absolute fee budget for this payment (default=ConfigVar(lightning_payment_fee_cutoff_msat))
         """
         # note: The "timeout" param works via black magic.
         #       The CLI-parser stores it in the config, and the argname matches config.cv.CLI_TIMEOUT.key().
@@ -1745,7 +1758,24 @@ async def lnpay(self, invoice, timeout=120, password=None, wallet: Abstract_Wall
         payment_hash = lnaddr.paymenthash
         invoice_obj = Invoice.from_bech32(invoice)
         wallet.save_invoice(invoice_obj)
-        success, log = await lnworker.pay_invoice(invoice_obj)
+        if max_cltv is not None:
+            # The cltv budget excludes the final cltv delta which is why it is deducted here
+            # so the whole used cltv is <= max_cltv
+            assert max_cltv <= NBLOCK_CLTV_DELTA_TOO_FAR_INTO_FUTURE, \
+                    f"{max_cltv=} > {NBLOCK_CLTV_DELTA_TOO_FAR_INTO_FUTURE=}"
+            max_cltv_remaining = max_cltv - lnaddr.get_min_final_cltv_delta()
+            assert max_cltv_remaining > 0, f"{max_cltv=} - {lnaddr.get_min_final_cltv_delta()=} < 1"
+            max_cltv = max_cltv_remaining
+        assert max_fee_millionths is None or 0 < max_fee_millionths < 250_000, max_fee_millionths
+        assert fee_cutoff_msat is None or 0 < fee_cutoff_msat < 10_000_000, fee_cutoff_msat
+        budget = PaymentFeeBudget.custom(
+            invoice_amount_msat=invoice_obj.amount_msat,
+            config=wallet.config,
+            max_cltv_delta=max_cltv,
+            fee_millionths=max_fee_millionths,
+            fee_cutoff_msat=fee_cutoff_msat,
+        )
+        success, log = await lnworker.pay_invoice(invoice_obj, budget=budget)
         return {
             'payment_hash': payment_hash.hex(),
             'success': success,

electrum/lnutil.py

@@ -1948,23 +1948,63 @@ class PaymentFeeBudget(NamedTuple):
 
     @classmethod
     def default(cls, *, invoice_amount_msat: int, config: 'SimpleConfig') -> 'PaymentFeeBudget':
-        millionths_orig = config.LIGHTNING_PAYMENT_FEE_MAX_MILLIONTHS
-        millionths = min(max(0, millionths_orig), 250_000)  # clamp into [0, 25%]
-        cutoff_orig = config.LIGHTNING_PAYMENT_FEE_CUTOFF_MSAT
-        cutoff = min(max(0, cutoff_orig), 10_000_000)  # clamp into [0, 10k sat]
-        if millionths != millionths_orig:
+        fee_msat = PaymentFeeBudget._calculate_fee_msat(
+            invoice_amount_msat=invoice_amount_msat,
+            config=config,
+        )
+        return PaymentFeeBudget(
+            fee_msat=fee_msat,
+            cltv=NBLOCK_CLTV_DELTA_TOO_FAR_INTO_FUTURE,
+        )
+
+    @classmethod
+    def custom(
+        cls,
+        *,
+        invoice_amount_msat: int,
+        config: 'SimpleConfig',
+        fee_millionths: int = None,
+        fee_cutoff_msat: int = None,
+        max_cltv_delta: int = None,
+        ):
+        fee_msat = PaymentFeeBudget._calculate_fee_msat(
+            invoice_amount_msat=invoice_amount_msat,
+            config=config,
+            fee_millionths=fee_millionths,
+            fee_cutoff_msat=fee_cutoff_msat,
+        )
+        if max_cltv_delta is None:
+            max_cltv_delta = NBLOCK_CLTV_DELTA_TOO_FAR_INTO_FUTURE
+        assert max_cltv_delta > 0, max_cltv_delta
+        return PaymentFeeBudget(
+            fee_msat=fee_msat,
+            cltv=max_cltv_delta,
+        )
+
+    @classmethod
+    def _calculate_fee_msat(cls,
+        *,
+        invoice_amount_msat: int,
+        config: 'SimpleConfig',
+        fee_millionths: int = None,
+        fee_cutoff_msat: int = None,
+    ) -> int:
+        if fee_millionths is None:
+            fee_millionths = config.LIGHTNING_PAYMENT_FEE_MAX_MILLIONTHS
+        if fee_cutoff_msat is None:
+            fee_cutoff_msat = config.LIGHTNING_PAYMENT_FEE_CUTOFF_MSAT
+        millionths_clamped = min(max(0, fee_millionths), 250_000)  # clamp into [0, 25%]
+        cutoff_clamped = min(max(0, fee_cutoff_msat), 10_000_000)  # clamp into [0, 10k sat]
+        if fee_millionths != millionths_clamped:
             _logger.warning(
                 f"PaymentFeeBudget. found insane fee millionths in config. "
-                f"clamped: {millionths_orig}->{millionths}")
-        if cutoff != cutoff_orig:
+                f"clamped: {fee_millionths}->{millionths_clamped}")
+        if fee_cutoff_msat != cutoff_clamped:
             _logger.warning(
                 f"PaymentFeeBudget. found insane fee cutoff in config. "
-                f"clamped: {cutoff_orig}->{cutoff}")
+                f"clamped: {fee_cutoff_msat}->{cutoff_clamped}")
         # for small payments, fees <= constant cutoff are fine
         # for large payments, the max fee is percentage-based
-        fee_msat = invoice_amount_msat * millionths // 1_000_000
-        fee_msat = max(fee_msat, cutoff)
-        return PaymentFeeBudget(
-            fee_msat=fee_msat,
-            cltv=NBLOCK_CLTV_DELTA_TOO_FAR_INTO_FUTURE,
-        )
+        fee_msat = invoice_amount_msat * millionths_clamped // 1_000_000
+        fee_msat = max(fee_msat, cutoff_clamped)
+        return fee_msat

electrum/lnworker.py

@@ -1525,6 +1525,7 @@ async def pay_invoice(
             attempts: int = None,  # used only in unit tests
             full_path: LNPaymentPath = None,
             channels: Optional[Sequence[Channel]] = None,
+            budget: Optional[PaymentFeeBudget] = None,
     ) -> Tuple[bool, List[HtlcLog]]:
         bolt11 = invoice.lightning_invoice
         lnaddr = self._check_bolt11_invoice(bolt11, amount_msat=amount_msat)
@@ -1547,7 +1548,8 @@ async def pay_invoice(
         self.save_payment_info(info)
         self.wallet.set_label(key, lnaddr.get_description())
         self.set_invoice_status(key, PR_INFLIGHT)
-        budget = PaymentFeeBudget.default(invoice_amount_msat=amount_to_pay, config=self.config)
+        if budget is None:
+            budget = PaymentFeeBudget.default(invoice_amount_msat=amount_to_pay, config=self.config)
         if attempts is None and self.uses_trampoline():
             # we don't expect lots of failed htlcs with trampoline, so we can fail sooner
             attempts = 30