add hold invoice cli functionality

Author: f321x

electrum/commands.py

@@ -46,7 +46,7 @@
 from .logging import Logger
 from .onion_message import create_blinded_path, send_onion_message_to
 from .util import (bfh, json_decode, json_normalize, is_hash256_str, is_hex_str, to_bytes,
-                   parse_max_spend, to_decimal, UserFacingException, InvalidPassword)
+                   parse_max_spend, to_decimal, UserFacingException, InvalidPassword, make_aiohttp_session)
 
 from . import bitcoin
 from .bitcoin import is_address,  hash_160, COIN
@@ -55,15 +55,13 @@
 from .transaction import (Transaction, multisig_script, TxOutput, PartialTransaction, PartialTxOutput,
                           tx_from_any, PartialTxInput, TxOutpoint)
 from . import transaction
-from .invoices import PR_PAID, PR_UNPAID, PR_UNKNOWN, PR_EXPIRED
+from .invoices import PR_PAID, PR_UNPAID, PR_UNKNOWN, PR_EXPIRED, pr_tooltips
 from .synchronizer import Notifier
 from .wallet import Abstract_Wallet, create_new_wallet, restore_wallet_from_text, Deterministic_Wallet, BumpFeeStrategy, Imported_Wallet
 from .address_synchronizer import TX_HEIGHT_LOCAL
 from .mnemonic import Mnemonic
-from .lnutil import SENT, RECEIVED
-from .lnutil import LnFeatures
 from .lntransport import extract_nodeid
-from .lnutil import channel_id_from_funding_tx
+from .lnutil import channel_id_from_funding_tx, LnFeatures, SENT, RECEIVED, MIN_FINAL_CLTV_DELTA_FOR_INVOICE
 from .plugin import run_hook, DeviceMgr, Plugins
 from .version import ELECTRUM_VERSION
 from .simple_config import SimpleConfig
@@ -1346,6 +1344,117 @@ async def add_request(self, amount, memo='', expiry=3600, lightning=False, force
         req = wallet.get_request(key)
         return wallet.export_request(req)
 
+    @command('wnl')
+    async def add_hold_invoice(
+            self,
+            payment_hash,
+            amount = None,
+            memo = "",
+            expiry = 3600,
+            callback_url = None,
+            wallet: Abstract_Wallet = None
+        ) -> str:
+        """
+        Create a lightning hold invoice for the given payment hash. Hold invoices have to get settled manually later.
+        The invoice has a final cltv delta of 147 blocks.
+        HTLCs will get failed if local_height + 144 > htlc.cltv_abs.
+
+        arg:str:payment_hash:Hex encoded payment hash to be used for the invoice
+        arg:decimal:amount:Optional requested amount (in btc)
+        arg:str:memo:Optional description of the invoice
+        arg:int:expiry:Optional expiry in seconds (default: 3600s)
+        arg:str:callback_url:Optional callback URL for the invoice, if provided a POST request will be triggered once all htlcs arrived (doesn't use proxy)
+        """
+        assert len(payment_hash) == 64, f"Invalid payment hash length: {len(payment_hash)} != 64"
+        assert payment_hash not in wallet.lnworker.payment_info, "Payment already in use"
+        inbound_capacity = wallet.lnworker.num_sats_can_receive()
+        amount = amount if amount and amount > 0 else None  # make amount >0 or None
+        assert inbound_capacity > satoshis(amount or 0), \
+            f"Not enough incoming capacity [{inbound_capacity} sat] to receive this payment"
+        if callback_url:
+            assert callback_url.startswith("http"), "Callback URL must be http(s)://"
+        lnaddr, invoice = wallet.lnworker.get_bolt11_invoice(
+            payment_hash=bfh(payment_hash),
+            amount_msat=satoshis(amount) * 1000 if amount else None,
+            message=memo,
+            expiry=expiry,
+            min_final_cltv_expiry_delta=MIN_FINAL_CLTV_DELTA_FOR_INVOICE,
+            fallback_address=None
+        )
+        wallet.lnworker.add_payment_info_for_hold_invoice(
+            bfh(payment_hash),
+            satoshis(amount) if amount else None,
+        )
+        wallet.lnworker.register_cli_hold_invoice(payment_hash, callback_url)
+        result = json.dumps({
+            "invoice": invoice
+        }, indent=4, sort_keys=True)
+        return result
+
+    @command('wnl')
+    async def settle_hold_invoice(self, preimage, wallet: Abstract_Wallet = None) -> str:
+        """
+        Settles lightning hold invoice with 'preimage'.
+        Doesn't wait for actual settlement of the HTLCs.
+
+        arg:str:preimage:Hex encoded preimage of the payment hash
+        """
+        assert len(preimage) == 64, f"Invalid preimage length: {len(preimage)} != 64"
+        payment_hash: str = crypto.sha256(bfh(preimage)).hex()
+        assert payment_hash in wallet.lnworker.payment_info, \
+            f"Couldn't find lightning invoice for payment hash {payment_hash}"
+        assert wallet.lnworker.is_accepted_mpp(bfh(payment_hash)), \
+            f"MPP incomplete, cannot settle hold invoice with preimage {preimage}"
+        wallet.lnworker.preimages[payment_hash] = preimage
+        result: str = json.dumps({
+            "settled": payment_hash
+        }, indent=4)
+        return result
+
+    @command('wnl')
+    async def cancel_hold_invoice(self, payment_hash, wallet: Abstract_Wallet = None) -> str:
+        """
+        Cancels lightning hold invoice 'payment_hash'.
+
+        arg:str:payment_hash:Payment hash in hex of the hold invoice
+        """
+        assert payment_hash in wallet.lnworker.payment_info, \
+            f"Couldn't find lightning invoice for payment hash {payment_hash}"
+        assert payment_hash not in wallet.lnworker.preimages, \
+            f"Hold invoice already settled with preimage: {crypto.sha256(bfh(payment_hash)).hex()}"
+        wallet.lnworker.set_payment_status(bfh(payment_hash), PR_UNPAID)
+        wallet.lnworker.delete_payment_info(payment_hash)
+        wallet.lnworker.unregister_hold_invoice(bfh(payment_hash))
+        result: str = json.dumps({
+            "cancelled": payment_hash
+        }, indent=4)
+        return result
+
+    @command('wnl')
+    async def check_hold_invoice(self, payment_hash, wallet: Abstract_Wallet = None) -> str:
+        """
+        Checks the status of a lightning hold invoice 'payment_hash'.
+        Possible states: unpaid, paid, settled, unknown (cancelled or not found)
+
+        arg:str:payment_hash:Payment hash in hex of the hold invoice
+        """
+        info = wallet.lnworker.get_payment_info(bfh(payment_hash))
+        amount_sat = (wallet.lnworker.get_payment_mpp_amount_msat(bfh(payment_hash)) or 0) // 1000
+        status = "unknown"
+        if info is None:
+            pass
+        elif info.status == PR_UNPAID or not wallet.lnworker.is_accepted_mpp(bfh(payment_hash)):
+            status = "unpaid"
+        elif info.status == PR_PAID and payment_hash not in wallet.lnworker.preimages:
+            status = "paid"
+        elif payment_hash in wallet.lnworker.preimages:
+            status = "settled"
+        result: str = json.dumps({
+            "status": status,
+            "amount_sat": amount_sat
+        }, indent=4)
+        return result
+
     @command('w')
     async def addtransaction(self, tx, wallet: Abstract_Wallet = None):
         """

electrum/lnworker.py

@@ -20,6 +20,7 @@
 from concurrent import futures
 import urllib.parse
 import itertools
+import json
 
 import aiohttp
 import dns.resolver
@@ -885,6 +886,9 @@ def __init__(self, wallet: 'Abstract_Wallet', xprv):
 
         # payment_hash -> callback:
         self.hold_invoice_callbacks = {}                # type: Dict[bytes, Callable[[bytes], Awaitable[None]]]
+        self.cli_hold_invoice_callbacks = self.db.get_dict('cli_hold_invoice_callbacks')   # type: Dict[str, Optional[str]]  # payment_hash -> url callback
+        for payment_hash, callback_url in self.cli_hold_invoice_callbacks.items():
+            self.register_cli_hold_invoice(payment_hash, callback_url)
         self.payment_bundles = []                       # lists of hashes. todo:persist
 
         self.nostr_keypair = generate_keypair(BIP32Node.from_xkey(xprv), LnKeyFamily.NOSTR_KEY)
@@ -2300,8 +2304,9 @@ def get_payment_info(self, payment_hash: bytes) -> Optional[PaymentInfo]:
                 amount_msat, direction, status = self.payment_info[key]
                 return PaymentInfo(payment_hash, amount_msat, direction, status)
 
-    def add_payment_info_for_hold_invoice(self, payment_hash: bytes, lightning_amount_sat: int):
-        info = PaymentInfo(payment_hash, lightning_amount_sat * 1000, RECEIVED, PR_UNPAID)
+    def add_payment_info_for_hold_invoice(self, payment_hash: bytes, lightning_amount_sat: Optional[int]):
+        amount = lightning_amount_sat * 1000 if lightning_amount_sat else None
+        info = PaymentInfo(payment_hash, amount, RECEIVED, PR_UNPAID)
         self.save_payment_info(info, write_to_disk=False)
 
     def register_hold_invoice(self, payment_hash: bytes, cb: Callable[[bytes], Awaitable[None]]):
@@ -2310,6 +2315,27 @@ def register_hold_invoice(self, payment_hash: bytes, cb: Callable[[bytes], Await
     def unregister_hold_invoice(self, payment_hash: bytes):
         self.hold_invoice_callbacks.pop(payment_hash)
 
+    def register_cli_hold_invoice(self, payment_hash: str, callback_url: Optional[str] = None):
+        async def cli_hold_invoice_callback(payment_hash_bytes: bytes):
+            """Hold invoice callback for hold invoices registered via CLI."""
+            self.logger.info(f"Hold invoice {payment_hash_bytes.hex()} ready for settlement")
+            self.set_payment_status(payment_hash_bytes, PR_PAID)
+            if not callback_url:
+                return
+            amount_sat = (self.get_payment_mpp_amount_msat(payment_hash_bytes) or 0) // 1000
+            data = {
+                "payment_hash": payment_hash_bytes.hex(),
+                "amount_sat": amount_sat
+            }
+            try:
+                async with make_aiohttp_session(proxy=None) as s:
+                    await s.post(callback_url, json=data, raise_for_status=False)
+            except Exception as e:
+                self.logger.info(f"hold invoice callback request to {callback_url} raised: {str(e)}")
+        self.register_hold_invoice(bfh(payment_hash), cli_hold_invoice_callback)
+        if payment_hash not in self.cli_hold_invoice_callbacks:
+            self.cli_hold_invoice_callbacks[payment_hash] = callback_url
+
     def save_payment_info(self, info: PaymentInfo, *, write_to_disk: bool = True) -> None:
         key = info.payment_hash.hex()
         assert info.status in SAVED_PR_STATUS
@@ -2394,17 +2420,34 @@ def set_mpp_resolution(self, *, payment_key: bytes, resolution: RecvMPPResolutio
         self.received_mpp_htlcs[payment_key.hex()] = mpp_status._replace(resolution=resolution)
 
     def is_mpp_amount_reached(self, payment_key: bytes) -> bool:
-        mpp_status = self.received_mpp_htlcs.get(payment_key.hex())
-        if not mpp_status:
+        amounts = self.get_mpp_amounts(payment_key)
+        if amounts is None:
             return False
-        total = sum([_htlc.amount_msat for scid, _htlc in mpp_status.htlc_set])
-        return total >= mpp_status.expected_msat
+        total, expected = amounts
+        return total >= expected
 
     def is_accepted_mpp(self, payment_hash: bytes) -> bool:
         payment_key = self._get_payment_key(payment_hash)
         status = self.received_mpp_htlcs.get(payment_key.hex())
         return status and status.resolution == RecvMPPResolution.ACCEPTED
 
+    def get_payment_mpp_amount_msat(self, payment_hash: bytes) -> Optional[int]:
+        """Returns the received mpp amount for given payment hash."""
+        payment_key = self._get_payment_key(payment_hash)
+        amounts = self.get_mpp_amounts(payment_key)
+        if not amounts:
+            return None
+        total_msat, _ = amounts
+        return total_msat
+
+    def get_mpp_amounts(self, payment_key: bytes) -> Optional[Tuple[int, int]]:
+        """Returns (total received amount, expected amount) or None."""
+        mpp_status = self.received_mpp_htlcs.get(payment_key.hex())
+        if not mpp_status:
+            return None
+        total = sum([_htlc.amount_msat for scid, _htlc in mpp_status.htlc_set])
+        return total, mpp_status.expected_msat
+
     def get_first_timestamp_of_mpp(self, payment_key: bytes) -> int:
         mpp_status = self.received_mpp_htlcs.get(payment_key.hex())
         if not mpp_status: