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,6 +218,7 @@ The node currently exposes the following APIs:
 - `/getassetmedia` (POST)
 - `/getchannelid` (POST)
 - `/getpayment` (POST)
+- `/getpaymentpreimage` (POST)
 - `/getswap` (POST)
 - `/init` (POST)
 - `/invoicestatus` (POST)
@@ -248,6 +250,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:
@@ -636,7 +672,7 @@ paths:
       tags:
         - Invoices
       summary: Get a LN invoice
-      description: Get a LN invoice to receive a payment
+      description: Get a LN invoice to receive a payment. Provide `payment_hash` to create a HODL invoice.
       requestBody:
         content:
           application/json:
@@ -892,6 +928,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 +1299,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 +1392,7 @@ components:
     CheckProxyEndpointRequest:
       type: object
       properties:
-        proxy_url:
+        proxy_endpoint:
           type: string
           example: rpc://127.0.0.1:3000/json-rpc
     CloseChannelRequest:
@@ -1519,6 +1581,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 +1616,9 @@ components:
       type: string
       enum:
         - Pending
+        - Claimable
         - Succeeded
+        - Cancelled
         - Failed
     IndexerProtocol:
       type: string
@@ -1561,6 +1642,7 @@ components:
       enum:
         - Pending
         - Succeeded
+        - Cancelled
         - Failed
         - Expired
     InvoiceStatusRequest:
@@ -1784,6 +1866,10 @@ components:
         asset_amount:
           type: integer
           example: 42
+        payment_hash:
+          type: string
+          description: Optional. When provided, the invoice is created as HODL.
+          example: 3febfae1e68b190c15461f4c2a3290f9af1dae63fd7d620d2bd61601869026cd
     LNInvoiceResponse:
       type: object
       properties:
@@ -2184,6 +2270,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)) {

src/error.rs

@@ -161,6 +161,9 @@ pub enum APIError {
     #[error("Invalid payment hash: {0}")]
     InvalidPaymentHash(String),
 
+    #[error("Invalid payment preimage")]
+    InvalidPaymentPreimage,
+
     #[error("Invalid payment secret")]
     InvalidPaymentSecret,
 
@@ -212,6 +215,24 @@ pub enum APIError {
     #[error("Invalid transport endpoints: {0}")]
     InvalidTransportEndpoints(String),
 
+    #[error("HTLC claim deadline exceeded")]
+    ClaimDeadlineExceeded,
+
+    #[error("Invoice is already settled")]
+    InvoiceAlreadySettled,
+
+    #[error("Invoice is expired")]
+    InvoiceExpired,
+
+    #[error("No claimable HTLC found for this invoice")]
+    InvoiceNotClaimable,
+
+    #[error("Invoice is not marked as HODL")]
+    InvoiceNotHodl,
+
+    #[error("Invoice settlement is in progress")]
+    InvoiceSettlingInProgress,
+
     #[error("IO error: {0}")]
     IO(#[from] std::io::Error),
 
@@ -257,6 +278,9 @@ pub enum APIError {
     #[error("Output below the dust limit")]
     OutputBelowDustLimit,
 
+    #[error("Payment hash already used")]
+    PaymentHashAlreadyUsed,
+
     #[error("Payment not found: {0}")]
     PaymentNotFound(String),
 
@@ -443,6 +467,8 @@ impl IntoResponse for APIError {
             | APIError::InvalidOnionData(_)
             | APIError::InvalidPassword(_)
             | APIError::InvalidPaymentHash(_)
+            | APIError::PaymentHashAlreadyUsed
+            | APIError::InvalidPaymentPreimage
             | APIError::InvalidPaymentSecret
             | APIError::InvalidPeerInfo(_)
             | APIError::InvalidPrecision(_)
@@ -457,10 +483,12 @@ impl IntoResponse for APIError {
             | APIError::InvalidTlvType(_)
             | APIError::InvalidTransportEndpoint(_)
             | APIError::InvalidTransportEndpoints(_)
+            | APIError::InvoiceExpired
             | APIError::MediaFileEmpty
             | APIError::MediaFileNotProvided
             | APIError::MissingSwapPaymentPreimage
             | APIError::OutputBelowDustLimit
+            | APIError::ClaimDeadlineExceeded
             | APIError::UnsupportedBackupVersion { .. } => {
                 (StatusCode::BAD_REQUEST, self.to_string(), self.name())
             }
@@ -485,6 +513,8 @@ impl IntoResponse for APIError {
             | APIError::InvalidIndexer(_)
             | APIError::InvalidProxyEndpoint
             | APIError::InvalidProxyProtocol(_)
+            | APIError::InvoiceNotHodl
+            | APIError::InvoiceSettlingInProgress
             | APIError::LockedNode
             | APIError::MaxFeeExceeded(_)
             | APIError::MinFeeNotMet(_)
@@ -506,6 +536,10 @@ impl IntoResponse for APIError {
             | APIError::UnsupportedTransportType => {
                 (StatusCode::FORBIDDEN, self.to_string(), self.name())
             }
+            APIError::InvoiceAlreadySettled => {
+                (StatusCode::CONFLICT, self.to_string(), self.name())
+            }
+            APIError::InvoiceNotClaimable => (StatusCode::NOT_FOUND, self.to_string(), self.name()),
             APIError::Network(_) | APIError::NoValidTransportEndpoint => (
                 StatusCode::SERVICE_UNAVAILABLE,
                 self.to_string(),