add support for HODL invoices

Author: txalkan

README.md

@@ -203,9 +203,11 @@ The node currently exposes the following APIs:
 - `/assetmetadata` (POST)
 - `/backup` (POST)
 - `/btcbalance` (POST)
+- `/cancelhodlinvoice` (POST)
 - `/changepassword` (POST)
 - `/checkindexerurl` (POST)
 - `/checkproxyendpoint` (POST)
+- `/claimhodlinvoice` (POST)
 - `/closechannel` (POST)
 - `/connectpeer` (POST)
 - `/createutxos` (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:
@@ -169,6 +187,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/EmptyResponse'
+  /claimhodlinvoice:
+    post:
+      tags:
+        - Invoices
+      summary: Claim a HODL invoice
+      description: Claim a held HTLC for a HODL invoice
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ClaimHodlInvoiceRequest'
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ClaimHodlInvoiceResponse'
   /closechannel:
     post:
       tags:
@@ -674,7 +710,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:
@@ -1416,6 +1452,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
       required:
@@ -1538,6 +1582,24 @@ components:
         proxy_endpoint:
           type: string
           example: rpc://127.0.0.1:3000/json-rpc
+    ClaimHodlInvoiceRequest:
+      type: object
+      required:
+        - payment_hash
+        - payment_preimage
+      properties:
+        payment_hash:
+          type: string
+          example: b4cb2da889477082a2e47f37a07e646e60ef6f97ffa7a4d88c823efd673da94b
+        payment_preimage:
+          type: string
+          example: eade701c7b23b8799465f4284ad84710fc16a776fbc6483001291149122695a8
+    ClaimHodlInvoiceResponse:
+      type: object
+      properties:
+        changed:
+          type: boolean
+          example: true
     CloseChannelRequest:
       type: object
       required:
@@ -1819,7 +1881,10 @@ components:
       type: string
       enum:
         - Pending
+        - Claimable
+        - Claiming
         - Succeeded
+        - Cancelled
         - Failed
     IndexerProtocol:
       type: string
@@ -1882,7 +1947,10 @@ components:
       type: string
       enum:
         - Pending
+        - Claimable
+        - Claiming
         - Succeeded
+        - Cancelled
         - Failed
         - Expired
     InvoiceStatusRequest:
@@ -2238,6 +2306,10 @@ components:
             - integer
             - 'null'
           example: 42
+        payment_hash:
+          type: string
+          description: Optional. When provided, the invoice is created as HODL.
+          example: 3febfae1e68b190c15461f4c2a3290f9af1dae63fd7d620d2bd61601869026cd
     LNInvoiceResponse:
       type: object
       required:
@@ -2467,11 +2539,17 @@ components:
         temporary_channel_id:
           type: string
           example: a8b60c8ce3067b5fc881d4831323e24751daec3b64353c8df3205ec5d838f1c5
+    PaymentType:
+      type: string
+      enum:
+        - Outbound
+        - InboundAutoClaim
+        - InboundHodl
     Payment:
       type: object
       required:
         - payment_hash
-        - inbound
+        - payment_type
         - status
         - created_at
         - updated_at
@@ -2495,9 +2573,8 @@ components:
         payment_hash:
           type: string
           example: 3febfae1e68b190c15461f4c2a3290f9af1dae63fd7d620d2bd61601869026cd
-        inbound:
-          type: boolean
-          example: true
+        payment_type:
+          $ref: '#/components/schemas/PaymentType'
         status:
           $ref: '#/components/schemas/HTLCStatus'
         created_at:

src/error.rs

@@ -167,6 +167,9 @@ pub enum APIError {
     #[error("Invalid payment hash: {0}")]
     InvalidPaymentHash(String),
 
+    #[error("Invalid payment preimage")]
+    InvalidPaymentPreimage,
+
     #[error("Invalid payment secret")]
     InvalidPaymentSecret,
 
@@ -221,6 +224,24 @@ pub enum APIError {
     #[error("Invalid transport endpoints: {0}")]
     InvalidTransportEndpoints(String),
 
+    #[error("HTLC claim deadline exceeded")]
+    ClaimDeadlineExceeded,
+
+    #[error("Invoice is already claimed")]
+    InvoiceAlreadyClaimed,
+
+    #[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),
 
@@ -266,6 +287,9 @@ pub enum APIError {
     #[error("Output below the dust limit")]
     OutputBelowDustLimit,
 
+    #[error("Payment hash already used")]
+    PaymentHashAlreadyUsed,
+
     #[error("Payment not found: {0}")]
     PaymentNotFound(String),
 
@@ -467,6 +491,8 @@ impl IntoResponse for APIError {
             | APIError::InvalidOnionData(_)
             | APIError::InvalidPassword(_)
             | APIError::InvalidPaymentHash(_)
+            | APIError::PaymentHashAlreadyUsed
+            | APIError::InvalidPaymentPreimage
             | APIError::InvalidPaymentSecret
             | APIError::InvalidPeerInfo(_)
             | APIError::InvalidPrecision(_)
@@ -482,10 +508,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())
             }
@@ -510,6 +538,8 @@ impl IntoResponse for APIError {
             | APIError::InvalidIndexer(_)
             | APIError::InvalidProxyEndpoint
             | APIError::InvalidProxyProtocol(_)
+            | APIError::InvoiceNotHodl
+            | APIError::InvoiceSettlingInProgress
             | APIError::LockedNode
             | APIError::MaxFeeExceeded(_)
             | APIError::MinFeeNotMet(_)
@@ -532,6 +562,10 @@ impl IntoResponse for APIError {
             | APIError::UnsupportedTransportType => {
                 (StatusCode::FORBIDDEN, self.to_string(), self.name())
             }
+            APIError::InvoiceAlreadyClaimed => {
+                (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(),