NIP-47 Add Hold Invoice Support

47.md

@@ -440,6 +440,88 @@ Response:
 }
 ```
 
+### `make_hold_invoice`
+
+Creates a hold invoice using a pre-generated preimage.
+
+Request:
+```jsonc
+{
+    "method": "make_hold_invoice",
+    "params": {
+        "amount": 123, // value in msats
+        "description": "string", // invoice's description, optional
+        "description_hash": "string", // invoice's description hash, optional
+        "expiry": 213 // expiry in seconds from time invoice is created for a payment to be initiated, optional. This does not determine how long a payment can be held (see `settle_deadline`)
+        "payment_hash": "string" // Payment hash for the payment generated from the preimage
+    }
+}
+```
+
+Response:
+```jsonc
+{
+    "result_type": "make_hold_invoice",
+    "result": {
+        "type": "incoming", // "incoming" for invoices, "outgoing" for payments
+        "invoice": "string", // encoded invoice, optional
+        "description": "string", // invoice's description, optional
+        "description_hash": "string", // invoice's description hash, optional
+        "payment_hash": "string", // Payment hash for the payment
+        "amount": 123, // value in msats
+        "created_at": unixtimestamp, // invoice/payment creation time
+        "expires_at": unixtimestamp, // invoice expiration time, optional if not applicable
+        "metadata": {} // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc.
+    }
+}
+```
+
+### `cancel_hold_invoice`
+
+Cancels a hold invoice using the payment hash
+
+Request:
+```jsonc
+{
+    "method": "cancel_hold_invoice",
+    "params": {
+        "payment_hash": "string" // Payment hash for the payment generated from the preimage
+    }
+}
+```
+
+Response:
+```jsonc
+{
+    "result_type": "cancel_hold_invoice",
+    "result": {}
+}
+```
+
+### `settle_hold_invoice`
+
+Settles a hold invoice using the preimage
+
+
+Request:
+```jsonc
+{
+    "method": "settle_hold_invoice",
+    "params": {
+        "preimage": "string" // preimage for the payment
+    }
+}
+```
+
+Response:
+```jsonc
+{
+    "result_type": "settle_hold_invoice",
+    "result": {}
+}
+```
+
+
 ## Notifications
 
 ### `payment_received`
@@ -492,6 +574,30 @@ Notification:
 }
 ```
 
+### `hold_invoice_accepted`
+
+Description: Sent when a payer accepts (locks in) a hold invoice. To avoid locking up funds in channels the hold invoice SHOULD be settled or canceled within a few minutes of receiving this event.
+
+Notification:
+```jsonc
+{
+    "notification_type": "hold_invoice_accepted",
+    "notification": {
+        "type": "incoming",
+        "invoice": "string", // encoded invoice
+        "description": "string", // invoice's description, optional
+        "description_hash": "string", // invoice's description hash, optional
+        "payment_hash": "string", // Payment hash for the payment
+        "amount": 123, // value in msats
+        "created_at": unixtimestamp, // invoice/payment creation time
+        "expires_at": unixtimestamp, // invoice expiration time, optional if not applicable
+        "settled_at": unixtimestamp, // invoice/payment settlement time
+        "settle_deadline": blocknumber, // invoice can only be safely settled or canceled before this block number.
+        "metadata": {} // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc.
+    }
+}
+```
+
 ## Example pay invoice flow
 
 0. The user scans the QR code generated by the **wallet service** with their **client** application, they follow a `nostr+walletconnect://` deeplink or configure the connection details manually.
@@ -522,3 +628,14 @@ This NIP does not specify any requirements on the type of relays used. However,
   "sig": "31f57b369459b5306a5353aa9e03be7fbde169bc881c3233625605dd12f53548179def16b9fe1137e6465d7e4d5bb27ce81fd6e75908c46b06269f4233c845d8"
 }
 ```
+
+### Example Hold Invoice Support Flow
+
+1. Client generates a 32-byte hex-encoded preimage.
+2. Computes SHA-256 to derive payment hash.
+3. Sends `make_hold_invoice` with payment hash and desired parameters.
+4. Waits for `hold_invoice_accepted` notification.
+5. Upon receiving notification, either:
+
+   * Calls `settle_hold_invoice` with the original preimage to release funds, or
+   * Calls `cancel_hold_invoice` with payment hash to abort.