add support for HODL invoices

Author: txalkan

README.md

@@ -203,6 +203,7 @@ The node currently exposes the following APIs:
 - `/assetmetadata` (POST)
 - `/backup` (POST)
 - `/btcbalance` (POST)
+- `/cancelhodlinvoice` (POST)
 - `/changepassword` (POST)
 - `/checkindexerurl` (POST)
 - `/checkproxyendpoint` (POST)
@@ -217,7 +218,9 @@ The node currently exposes the following APIs:
 - `/getassetmedia` (POST)
 - `/getchannelid` (POST)
 - `/getpayment` (POST)
+- `/getpaymentpreimage` (POST)
 - `/getswap` (POST)
+- `/hodlinvoice` (POST)
 - `/init` (POST)
 - `/invoicestatus` (POST)
 - `/issueassetcfa` (POST)
@@ -248,6 +251,7 @@ The node currently exposes the following APIs:
 - `/sendonionmessage` (POST)
 - `/sendpayment` (POST)
 - `/sendrgb` (POST)
+- `/settlehodlinvoice` (POST)
 - `/shutdown` (POST)
 - `/signmessage` (POST)
 - `/sync` (POST)

openapi.yaml

@@ -115,6 +115,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/BtcBalanceResponse'
+  /cancelhodlinvoice:
+    post:
+      tags:
+        - Invoices
+      summary: Cancel a HODL invoice
+      description: Cancel a held HTLC for a HODL invoice. Rejects cancellation if a settlement is already in progress.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InvoiceCancelRequest'
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmptyResponse'
   /changepassword:
     post:
       tags:
@@ -368,6 +386,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/GetPaymentResponse'
+  /getpaymentpreimage:
+    post:
+      tags:
+        - Payments
+      summary: Get a payment preimage by its payment hash
+      description: Get the preimage for an outbound payment when it has been completed successfully
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GetPaymentPreimageRequest'
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GetPaymentPreimageResponse'
   /getswap:
     post:
       tags:
@@ -386,6 +422,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/GetSwapResponse'
+  /hodlinvoice:
+    post:
+      tags:
+        - Invoices
+      summary: Create a HODL LN invoice
+      description: Create a BOLT11 invoice with a caller-provided payment hash; settlement is deferred until settle/cancel. Metadata is persisted first to preserve HODL semantics across restarts.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InvoiceHodlRequest'
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InvoiceHodlResponse'
   /init:
     post:
       tags:
@@ -892,6 +946,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/SendRgbResponse'
+  /settlehodlinvoice:
+    post:
+      tags:
+        - Invoices
+      summary: Settle a HODL invoice
+      description: Claim a held HTLC for a HODL invoice
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SettleHodlInvoiceRequest'
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SettleHodlInvoiceResponse'
   /shutdown:
     post:
       tags:
@@ -1245,6 +1317,14 @@ components:
           $ref: '#/components/schemas/BtcBalance'
         colored:
           $ref: '#/components/schemas/BtcBalance'
+    CancelHodlInvoiceRequest:
+      type: object
+      required:
+        - payment_hash
+      properties:
+        payment_hash:
+          type: string
+          example: 3febfae1e68b190c15461f4c2a3290f9af1dae63fd7d620d2bd61601869026cd
     ChangePasswordRequest:
       type: object
       properties:
@@ -1330,7 +1410,7 @@ components:
     CheckProxyEndpointRequest:
       type: object
       properties:
-        proxy_url:
+        proxy_endpoint:
           type: string
           example: rpc://127.0.0.1:3000/json-rpc
     CloseChannelRequest:
@@ -1519,6 +1599,23 @@ components:
       properties:
         payment:
           $ref: '#/components/schemas/Payment'
+    GetPaymentPreimageRequest:
+      type: object
+      required:
+        - payment_hash
+      properties:
+        payment_hash:
+          type: string
+          example: b4cb2da889477082a2e47f37a07e646e60ef6f97ffa7a4d88c823efd673da94b
+    GetPaymentPreimageResponse:
+      type: object
+      properties:
+        status:
+          $ref: '#/components/schemas/HTLCStatus'
+        preimage:
+          type: string
+          nullable: true
+          example: eade701c7b23b8799465f4284ad84710fc16a776fbc6483001291149122695a8
     GetSwapRequest:
       type: object
       properties:
@@ -1537,7 +1634,9 @@ components:
       type: string
       enum:
         - Pending
+        - Claimable
         - Succeeded
+        - Cancelled
         - Failed
     IndexerProtocol:
       type: string
@@ -1556,11 +1655,45 @@ components:
         mnemonic:
           type: string
           example: skill lamp please gown put season degree collect decline account monitor insane
+    InvoiceHodlRequest:
+      type: object
+      required:
+        - payment_hash
+        - expiry_sec
+      properties:
+        amt_msat:
+          type: integer
+          example: 3000000
+        expiry_sec:
+          type: integer
+          example: 86400
+        asset_id:
+          type: string
+          example: rgb:CJkb4YZw-jRiz2sk-~PARPio-wtVYI1c-XAEYCqO-wTfvRZ8
+        asset_amount:
+          type: integer
+          example: 42
+        payment_hash:
+          type: string
+          example: 3febfae1e68b190c15461f4c2a3290f9af1dae63fd7d620d2bd61601869026cd
+        external_ref:
+          type: string
+          example: swap-123
+    InvoiceHodlResponse:
+      type: object
+      properties:
+        invoice:
+          type: string
+          example: lnbcrt30u1pjv6yzndqud3jxktt5w46x7unfv9kz6mn0v3jsnp4qdpc280eur52luxppv6f3nnj8l6vnd9g2hnv3qv6mjhmhvlzf6327pp5tjjasx6g9dqptea3fhm6yllq5wxzycnnvp8l6wcq3d6j2uvpryuqsp5l8az8x3g8fe05dg7cmgddld3da09nfjvky8xftwsk4cj8p2l7kfq9qyysgqcqpcxqzdylzlwfnkyw3jv344x4rzwgkk53ng0fhxy5rdduk4g5tpvea8xa6rfckkza35va28xjn2tqkhgarcxep5umm4x5k56wfcdvu95eq7qzp20vrl4xz76syapsa3c09j7lg5gerkaj63llj0ark7ph8hfketn6fkqzm8laf66dhsncm23wkwm5l5377we9e8lnlknnkwje5eefkccusqm6rqt8
+        payment_secret:
+          type: string
+          example: 777a7756c620868199ed5fdc35bee4095b5709d543e5c2bf0494396bf27d2ea2
     InvoiceStatus:
       type: string
       enum:
         - Pending
         - Succeeded
+        - Cancelled
         - Failed
         - Expired
     InvoiceStatusRequest:
@@ -2184,6 +2317,24 @@ components:
         txid:
           type: string
           example: 7c2c95b9c2aa0a7d140495b664de7973b76561de833f0dd84def3efa08941664
+    SettleHodlInvoiceRequest:
+      type: object
+      required:
+        - payment_hash
+        - payment_preimage
+      properties:
+        payment_hash:
+          type: string
+          example: b4cb2da889477082a2e47f37a07e646e60ef6f97ffa7a4d88c823efd673da94b
+        payment_preimage:
+          type: string
+          example: eade701c7b23b8799465f4284ad84710fc16a776fbc6483001291149122695a8
+    SettleHodlInvoiceResponse:
+      type: object
+      properties:
+        changed:
+          type: boolean
+          example: true
     SignMessageRequest:
       type: object
       properties:

regtest.sh

@@ -38,7 +38,7 @@ _is_port_bound() {
 _wait_for_bitcoind() {
     # wait for bitcoind to be up
     start_time=$(date +%s)
-    until $COMPOSE logs bitcoind |grep -q 'Bound to'; do
+    until $BITCOIN_CLI getblockcount >/dev/null 2>&1; do
         current_time=$(date +%s)
         if [ $((current_time - start_time)) -gt $TIMEOUT ]; then
             echo "Timeout waiting for bitcoind to start"
@@ -74,9 +74,10 @@ _start_services() {
             _die "port $port is already bound, services can't be started"
         fi
     done
-    $COMPOSE up -d
+    $COMPOSE up -d bitcoind
     echo && echo "preparing bitcoind wallet"
     _wait_for_bitcoind
+    $COMPOSE up -d electrs proxy
     $BITCOIN_CLI createwallet miner >/dev/null
     $BITCOIN_CLI -rpcwallet=miner -generate $INITIAL_BLOCKS >/dev/null
     echo "waiting for electrs to have completed startup"

src/disk.rs

@@ -15,15 +15,17 @@ use std::sync::Arc;
 
 use crate::error::APIError;
 use crate::ldk::{
-    ChannelIdsMap, InboundPaymentInfoStorage, NetworkGraph, OutboundPaymentInfoStorage,
-    OutputSpenderTxes, SwapMap,
+    ChannelIdsMap, ClaimablePaymentStorage, InboundPaymentInfoStorage, InvoiceMetadataStorage,
+    NetworkGraph, OutboundPaymentInfoStorage, OutputSpenderTxes, SwapMap,
 };
 use crate::utils::{parse_peer_info, LOGS_DIR};
 
 pub(crate) const LDK_LOGS_FILE: &str = "logs.txt";
 
 pub(crate) const INBOUND_PAYMENTS_FNAME: &str = "inbound_payments";
 pub(crate) const OUTBOUND_PAYMENTS_FNAME: &str = "outbound_payments";
+pub(crate) const INVOICE_METADATA_FNAME: &str = "invoice_metadata";
+pub(crate) const CLAIMABLE_HTLCS_FNAME: &str = "claimable_htlcs";
 
 pub(crate) const CHANNEL_PEER_DATA: &str = "channel_peer_data";
 
@@ -178,6 +180,28 @@ pub(crate) fn read_outbound_payment_info(path: &Path) -> OutboundPaymentInfoStor
     }
 }
 
+pub(crate) fn read_invoice_metadata(path: &Path) -> InvoiceMetadataStorage {
+    if let Ok(file) = File::open(path) {
+        if let Ok(info) = InvoiceMetadataStorage::read(&mut BufReader::new(file)) {
+            return info;
+        }
+    }
+    InvoiceMetadataStorage {
+        invoices: new_hash_map(),
+    }
+}
+
+pub(crate) fn read_claimable_htlcs(path: &Path) -> ClaimablePaymentStorage {
+    if let Ok(file) = File::open(path) {
+        if let Ok(info) = ClaimablePaymentStorage::read(&mut BufReader::new(file)) {
+            return info;
+        }
+    }
+    ClaimablePaymentStorage {
+        payments: new_hash_map(),
+    }
+}
+
 pub(crate) fn read_output_spender_txes(path: &Path) -> OutputSpenderTxes {
     if let Ok(file) = File::open(path) {
         if let Ok(info) = OutputSpenderTxes::read(&mut BufReader::new(file)) {