Merge nip44-big-payloads into bigger-nip44bigger-nip44

1 files changed, 283 insertions, 97 deletions

diff --git a/47.md b/47.md
index 84f710e..6830820 100644
--- a/47.md
+++ b/47.md
@@ -28,15 +28,16 @@ Fundamentally NWC is communication between a **client** and **wallet service** b
  
  4. Once the payment is complete the **wallet service** will send an encrypted `response` (kind 23195) to the **user** over the relay(s) in the URI.
  
- 5. The **wallet service** may send encrypted notifications (kind 23196) of wallet events (such as a received payment) to the **client**.
+ 5. The **wallet service** may send encrypted notifications (kind 23197) of wallet events (such as a received payment) to the **client**.
 
 ## Events
 
 There are four event kinds:
+
 - `NIP-47 info event`: 13194
 - `NIP-47 request`: 23194
 - `NIP-47 response`: 23195
-- `NIP-47 notification event`: 23196
+- `NIP-47 notification event`: 23197 (23196 for backwards compatibility with NIP-04)
 
 ### Info Event
 
@@ -46,34 +47,71 @@ The content should be a plaintext string with the supported capabilities space-s
 
 If the **wallet service** supports notifications, the info event SHOULD contain a `notifications` tag with the supported notification types space-separated, eg. `payment_received payment_sent`.
 
+It should also contain supported encryption modes as described in the [Encryption](#encryption) section. For example:
+
+```jsonc
+{
+    "kind": 13194,
+    "tags": [
+        ["encryption", "nip44_v2 nip04"], // List of supported encryption schemes as described in the Encryption section.
+        ["notifications", "payment_received payment_sent"]
+        // ...
+    ],
+    "content": "pay_invoice get_balance make_invoice lookup_invoice list_transactions get_info notifications",
+    // ...
+}
+```
+
 ### Request and Response Events
 
 Both the request and response events SHOULD contain one `p` tag, containing the public key of the **wallet service** if this is a request, and the public key of the **client** if this is a response. The response event SHOULD contain an `e` tag with the id of the request event it is responding to.
 Optionally, a request can have an `expiration` tag that has a unix timestamp in seconds. If the request is received after this timestamp, it should be ignored.
 
-The content of requests and responses is encrypted with [NIP04](04.md), and is a JSON-RPCish object with a semi-fixed structure:
+The content of requests and responses is encrypted with [NIP44](44.md), and is a JSON-RPCish object with a semi-fixed structure.
 
-Request:
-```jsonc
+**Important note for backwards-compatibility:** The initial version of the protocol used [NIP04](04.md). If a **wallet service** or client app does not include the `encryption` tag in the
+`info` or request events, it should be assumed that the connection is using NIP04 for encryption. See the [Encryption](#encryption) section for more information.
+
+Example request:
+
+```js
 {
-    "method": "pay_invoice", // method, string
-    "params": { // params, object
-        "invoice": "lnbc50n1..." // command-related data
-    }
+    "kind" 23194,
+    "tags": [
+        ["encryption", "nip44_v2"],
+        ["p", "03..." ] // public key of the wallet service.
+        // ...
+    ],
+    "content": nip44_encrypt({ // Encryption type corresponds to the `encryption` tag.
+        "method": "pay_invoice", // method, string
+        "params": { // params, object
+            "invoice": "lnbc50n1..." // command-related data
+        }
+    }),
 }
 ```
 
-Response:
-```jsonc
+Example response:
+
+```js
 {
-    "result_type": "pay_invoice", //indicates the structure of the result field
-    "error": { //object, non-null in case of error
-        "code": "UNAUTHORIZED", //string error code, see below
-        "message": "human readable error message"
-    },
-    "result": { // result, object. null in case of error.
-        "preimage": "0123456789abcdef..." // command-related data
-    }
+    "kind" 23195,
+    "tags": [
+        ["p", "03..." ] // public key of the requesting client app
+        ["e", "1234"] // id of the request event this is responding to
+        // ...
+    ],
+    "content": nip44_encrypt({ // Encrypted using the scheme requested by the client.
+        "result_type": "pay_invoice", //indicates the structure of the result field
+        "error": { //object, non-null in case of error
+            "code": "UNAUTHORIZED", //string error code, see below
+            "message": "human readable error message"
+        },
+        "result": { // result, object. null in case of error.
+            "preimage": "0123456789abcdef..." // command-related data
+        }
+    })
+    // ...
 }
 ```
 
@@ -83,9 +121,9 @@ If the command was successful, the `error` field must be null.
 
 ### Notification Events
 
-The notification event SHOULD contain one `p` tag, the public key of the **client**.
+The notification event is a kind 23197 event SHOULD contain one `p` tag, the public key of the **client**.
 
-The content of notifications is encrypted with [NIP04](04.md), and is a JSON-RPCish object with a semi-fixed structure:
+The content of notifications is encrypted with [NIP44](44.md) (or NIP-04 for legacy client apps), and is a JSON-RPCish object with a semi-fixed structure:
 
 ```jsonc
 {
@@ -96,7 +134,6 @@ The content of notifications is encrypted with [NIP04](04.md), and is a JSON-RPC
 }
 ```
 
-
 ### Error codes
 - `RATE_LIMITED`: The client is sending commands too fast. It should retry in a few seconds.
 - `NOT_IMPLEMENTED`: The command is not known or is intentionally not implemented.
@@ -105,6 +142,7 @@ The content of notifications is encrypted with [NIP04](04.md), and is a JSON-RPC
 - `RESTRICTED`: This public key is not allowed to do this operation.
 - `UNAUTHORIZED`: This public key has no wallet connected.
 - `INTERNAL`: An internal error.
+- `UNSUPPORTED_ENCRYPTION`: The encryption type of the request is not supported by the wallet service.
 - `OTHER`: Other error.
 
 ## Nostr Wallet Connect URI
@@ -148,6 +186,7 @@ Request:
     "params": {
         "invoice": "lnbc50n1...", // bolt11 invoice
         "amount": 123, // invoice amount in msats, optional
+        "metadata": {} // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc, optional
     }
 }
 ```
@@ -166,42 +205,6 @@ Response:
 Errors:
 - `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar.
 
-### `multi_pay_invoice`
-
-Description: Requests payment of multiple invoices.
-
-Request:
-```jsonc
-{
-    "method": "multi_pay_invoice",
-    "params": {
-        "invoices": [
-          {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11 invoice and amount in msats, amount is optional
-          {"id":"3da52c32a1", "invoice": "lnbc50n1..."},
-        ],
-    }
-}
-```
-
-Response:
-
-For every invoice in the request, a separate response event is sent. To differentiate between the responses, each
-response event contains a `d` tag with the id of the invoice it is responding to; if no id was given, then the
-payment hash of the invoice should be used.
-
-```jsonc
-{
-    "result_type": "multi_pay_invoice",
-    "result": {
-        "preimage": "0123456789abcdef...", // preimage of the payment
-        "fees_paid": 123, // value in msats, optional
-    }
-}
-```
-
-Errors:
-- `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar.
-
 ### `pay_keysend`
 
 Request:
@@ -236,44 +239,6 @@ Response:
 Errors:
 - `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar.
 
-### `multi_pay_keysend`
-
-Description: Requests multiple keysend payments.
-
-Has an array of keysends, these follow the same semantics as `pay_keysend`, just done in a batch
-
-Request:
-```jsonc
-{
-    "method": "multi_pay_keysend",
-    "params": {
-        "keysends": [
-          {"id": "4c5b24a351", "pubkey": "03...", "amount": 123},
-          {"id": "3da52c32a1", "pubkey": "02...", "amount": 567, "preimage": "abc123..", "tlv_records": [{"type": 696969, "value": "77616c5f6872444873305242454d353736"}]},
-        ],
-    }
-}
-```
-
-Response:
-
-For every keysend in the request, a separate response event is sent. To differentiate between the responses, each
-response event contains a `d` tag with the id of the keysend it is responding to; if no id was given, then the
-pubkey should be used.
-
-```jsonc
-{
-    "result_type": "multi_pay_keysend",
-    "result": {
-        "preimage": "0123456789abcdef...", // preimage of the payment
-        "fees_paid": 123, // value in msats, optional
-    }
-}
-```
-
-Errors:
-- `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar.
-
 ### `make_invoice`
 
 Request:
@@ -284,7 +249,8 @@ Request:
         "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, optional
+        "expiry": 213, // expiry in seconds from time invoice is created, optional
+        "metadata": {} // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc, optional
     }
 }
 ```
@@ -295,6 +261,7 @@ Response:
     "result_type": "make_invoice",
     "result": {
         "type": "incoming", // "incoming" for invoices, "outgoing" for payments
+        "state": "pending", // optional
         "invoice": "string", // encoded invoice, optional
         "description": "string", // invoice's description, optional
         "description_hash": "string", // invoice's description hash, optional
@@ -328,6 +295,7 @@ Response:
     "result_type": "lookup_invoice",
     "result": {
         "type": "incoming", // "incoming" for invoices, "outgoing" for payments
+        "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
@@ -376,6 +344,7 @@ Response:
         "transactions": [
             {
                "type": "incoming", // "incoming" for invoices, "outgoing" for payments
+               "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
@@ -440,6 +409,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`
@@ -452,6 +504,7 @@ Notification:
     "notification_type": "payment_received",
     "notification": {
         "type": "incoming",
+        "state": "settled", // optional
         "invoice": "string", // encoded invoice
         "description": "string", // invoice's description, optional
         "description_hash": "string", // invoice's description hash, optional
@@ -477,6 +530,7 @@ Notification:
     "notification_type": "payment_sent",
     "notification": {
         "type": "outgoing",
+        "state": "settled", // optional
         "invoice": "string", // encoded invoice
         "description": "string", // invoice's description, optional
         "description_hash": "string", // invoice's description hash, optional
@@ -492,6 +546,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.
@@ -499,9 +577,89 @@ Notification:
 2. **wallet service** verifies that the author's key is authorized to perform the payment, decrypts the payload and sends the payment.
 3. **wallet service** responds to the event by sending an event with kind `23195` and content being a response either containing an error message or a preimage.
 
+## Encryption
+
+The initial version of NWC used [NIP-04](04.md) for encryption which has been deprecated and replaced by [NIP-44](44.md). NIP-44 should always be preferred for encryption, but there may be legacy cases
+where the **wallet service** or **client** has not yet migrated to NIP-44. The **wallet service** and **client** should negotiate the encryption method to use based on the `encryption` tag in the `info` event.
+
+The encryption tag can contain either `nip44_v2` or `nip04`. The absence of this tag implies that the wallet only supports `nip04`.
+
+| Encryption code | Use                  | Notes                                                   |
+|-----------------|----------------------|---------------------------------------------------------|
+| `nip44_v2`      | NIP-44               | Required                                                |
+| `nip04`         | NIP-04               | Deprecated and only here for backward compatibility     |
+| `<not present>` | NIP-04               | Deprecated and only here for backward compatibility     |
+
+The negotiation works as follows.
+
+1. The **wallet service** includes an `encryption` tag in the `info` event. This tag contains a space-separated list of encryption schemes that the **wallet service** supports (eg. `nip44_v2 nip04`)
+2. The **client application** includes an `encryption` tag in each request event. This tag contains the encryption scheme which should be used for the request. The **client application** should always prefer nip44 if supported by the **wallet service**.
+
+When a **client application** establishes a connection, it should read the info event and look for the `encryption` tag.
+
+**Absence of this tag implies that the wallet only supports nip04.**
+
+If the `encryption` tag is present, the **client application** will choose optimal encryption supported by both itself, and the **wallet service**, which should always be nip44 if possible.
+
+### Request events
+
+When a **client application** sends a request event, it should include a `encryption` tag with the encryption scheme it is using. The scheme MUST be supported by the **wallet service** as indicated by the info event.
+For example, if the client application supports nip44, the request event might look like:
+
+```jsonc
+{
+    "kind": 23194,
+    "tags": [
+        ["encryption", "nip44_v2"],
+        // ...
+    ],
+    // ...
+}
+```
+
+If the **wallet service** does not support the specified encryption scheme, it will return an `UNSUPPORTED_ENCRYPTION` error. Absence of the `encryption` tag indicates use of nip04 for encryption.
+
+### Notification events
+
+If a **wallet service** supports both nip04 and nip44, it should publish two notification events for each notification - kind 23196 encrypted with NIP-04, and kind 23197 encrypted with NIP-44. If the **wallet service** only supports nip44, it should only publish kind 23197 events.
+
+The **client** should check the `encryption` tag in the `info` event to determine which encryption schemes the **wallet service** supports, and listen to the appropriate notification event.
+
 ## Using a dedicated relay
 This NIP does not specify any requirements on the type of relays used. However, if the user is using a custodial service it might make sense to use a relay that is hosted by the custodial service. The relay may then enforce authentication to prevent metadata leaks. Not depending on a 3rd party relay would also improve reliability in this case.
 
+## Metadata
+Metadata MAY be stored by the **wallet service** alongside invoices and payments. The metadata MUST be no more than 4096 characters, otherwise MUST be dropped. This is to ensure transactions do not get too large to be relayed.
+
+NWC relays SHOULD allow at least a payload size of 64KB and **clients** SHOULD fetch small page sizes (maximum of 20 transactions per page) otherwise there is risk of `list_transactions` responses being rejected.
+
+Here are some properties that are recognized by some NWC clients:
+
+```jsonc
+{
+  "comment": "string", // LUD-12 comment
+  "payer_data": {
+    "email": "string",
+    "name": "string",
+    "pubkey": "string",
+  }, // LUD-18 payer data
+  "recipient_data": {
+    "identifier": "string"
+  }, // similar to LUD-18 payer data, but to record recipient data e.g. the lightning address of the recipient
+  "nostr": {
+    "pubkey": "string",
+    "tags": [],
+    // ... rest of zap request event
+  }, // NIP-57 Zap Request event (kind 9734)
+  "tlv_records": [
+    {
+      "type": 5482373484, // tlv type
+      "value": "0123456789abcdef" // hex encoded tlv value
+    }
+  ] // keysend TLV records (e.g. for podcasting 2.0 boostagrams)
+} & Record<string, unknown>;
+```
+
 ## Appendix
 
 ### Example NIP-47 info event
@@ -513,6 +671,7 @@ This NIP does not specify any requirements on the type of relays used. However,
   "created_at": 1713883677,
   "kind": 13194,
   "tags": [
+    [ "encryption", "nip44_v2 nip04" ],
     [
       "notifications",
       "payment_received payment_sent"
@@ -522,3 +681,30 @@ 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.
+
+### 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.
+
+`nostrnwc://connect` and `nostrnwc+{app_name}://connect` can be registered by wallet apps and queried by apps that want to receive an NWC pairing code.
+
+All URI parameters, MUST be URI-encoded.
+
+URI parameters:
+ * `appicon` -- URL to an icon of the client that wants to create a connection.
+ * `appname` -- Name of the client that wants to create a connection.
+ * `callback` -- URI schema the wallet should open with the connection string
+
+Once a connection has been created by the wallet, it should be returned to the client by opening the callback with the following parameters
+ * `value` -- NWC pairing code (e.g. `nostr+walletconnect://...`)