From 400d975da36955a11c22f682cbcd3776ecb09867 Mon Sep 17 00:00:00 2001
From: Roland <33993199+rolznz@users.noreply.github.com>
Date: Mon, 15 Sep 2025 23:42:07 +0700
Subject: [PATCH] feat: add metadata to NIP-47 make_invoice and payment
 commands (#2063)

---
 47.md | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/47.md b/47.md
index 10649496..ac85019f 100644
--- a/47.md
+++ b/47.md
@@ -188,6 +188,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
     }
 }
 ```
@@ -217,7 +218,7 @@ Request:
     "params": {
         "invoices": [
           {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11 invoice and amount in msats, amount is optional
-          {"id":"3da52c32a1", "invoice": "lnbc50n1..."},
+          {"id":"3da52c32a1", "invoice": "lnbc50n1...", "metadata": {} }, // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc, optional
         ],
     }
 }
@@ -324,7 +325,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
     }
 }
 ```
@@ -612,6 +614,38 @@ The **client** should check the `encryption` tag in the `info` event to determin
 ## 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": [],
+    // ... 
+  }, // NIP-57 (Nostr Zaps)
+  "tlv_records": [ // tlv records, optional
+    {
+      "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