diff --git a/47.md b/47.md index 13037cb5..76c8f502 100644 --- a/47.md +++ b/47.md @@ -371,7 +371,7 @@ Response: "result_type": "lookup_invoice", "result": { "type": "incoming", // "incoming" for invoices, "outgoing" for payments - "state": "pending", // can be "pending", "settled", "expired" (for invoices) or "failed" (for payments), optional + "state": "pending", // can be "pending", "settled", "accepted" (for hold invoices), "expired" (for invoices) or "failed" (for payments), optional "invoice": "string", // encoded invoice, optional "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, optional @@ -420,7 +420,7 @@ Response: "transactions": [ { "type": "incoming", // "incoming" for invoices, "outgoing" for payments - "state": "pending", // can be "pending", "settled", "expired" (for invoices) or "failed" (for payments), optional + "state": "pending", // can be "pending", "settled", "accepted" (for hold invoices), "expired" (for invoices) or "failed" (for payments), optional "invoice": "string", // encoded invoice, optional "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, optional @@ -485,6 +485,89 @@ 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 + "min_cltv_expiry_delta": 144 // The minimum CLTV delta to use for the final hop, optional + } +} +``` + +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` @@ -539,6 +622,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", + "state": "accepted", // optional + "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 + "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. @@ -668,6 +775,16 @@ Here are some properties that are recognized by some NWC clients: } ``` +### 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. ### Deep-links Wallet applications can register deeplinks in mobile systems to make it possible to create a linking UX that doesn't require the user scanning a QR code or pasting some code.