upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
path: root/57.md
diff options
context:
space:
mode:
Diffstat (limited to '57.md')
-rw-r--r--57.md31
1 files changed, 18 insertions, 13 deletions
diff --git a/57.md b/57.md
index 95dba3b..6d89620 100644
--- a/57.md
+++ b/57.md
@@ -4,7 +4,7 @@ NIP-57
4Lightning Zaps 4Lightning Zaps
5-------------- 5--------------
6 6
7`draft` `optional` `author:jb55` `author:kieran` 7`draft` `optional`
8 8
9This NIP defines two new event types for recording lightning payments between users. `9734` is a `zap request`, representing a payer's request to a recipient's lightning wallet for an invoice. `9735` is a `zap receipt`, representing the confirmation by the recipient's lightning wallet that the invoice issued in response to a `zap request` has been paid. 9This NIP defines two new event types for recording lightning payments between users. `9734` is a `zap request`, representing a payer's request to a recipient's lightning wallet for an invoice. `9735` is a `zap receipt`, representing the confirmation by the recipient's lightning wallet that the invoice issued in response to a `zap request` has been paid.
10 10
@@ -36,7 +36,7 @@ A `zap request` is an event of kind `9734` that is _not_ published to relays, bu
36In addition, the event MAY include the following tags: 36In addition, the event MAY include the following tags:
37 37
38- `e` is an optional hex-encoded event id. Clients MUST include this if zapping an event rather than a person. 38- `e` is an optional hex-encoded event id. Clients MUST include this if zapping an event rather than a person.
39- `a` is an optional NIP-33 event coordinate that allows tipping parameterized replaceable events such as NIP-23 long-form notes. 39- `a` is an optional event coordinate that allows tipping parameterized replaceable events such as NIP-23 long-form notes.
40 40
41Example: 41Example:
42 42
@@ -45,7 +45,7 @@ Example:
45 "kind": 9734, 45 "kind": 9734,
46 "content": "Zap!", 46 "content": "Zap!",
47 "tags": [ 47 "tags": [
48 ["relays", "wss://nostr-pub.wellorder.com"], 48 ["relays", "wss://nostr-pub.wellorder.com", "wss://anotherrelay.example.com"],
49 ["amount", "21000"], 49 ["amount", "21000"],
50 ["lnurl", "lnurl1dp68gurn8ghj7um5v93kketj9ehx2amn9uh8wetvdskkkmn0wahz7mrww4excup0dajx2mrv92x9xp"], 50 ["lnurl", "lnurl1dp68gurn8ghj7um5v93kketj9ehx2amn9uh8wetvdskkkmn0wahz7mrww4excup0dajx2mrv92x9xp"],
51 ["p", "04c915daefee38317fa734444acee390a8269fe5810b2241e5e6dd343dfbecc9"], 51 ["p", "04c915daefee38317fa734444acee390a8269fe5810b2241e5e6dd343dfbecc9"],
@@ -66,7 +66,7 @@ A signed `zap request` event is not published, but is instead sent using a HTTP
66- `nostr` is the `9734` `zap request` event, JSON encoded then URI encoded 66- `nostr` is the `9734` `zap request` event, JSON encoded then URI encoded
67- `lnurl` is the lnurl pay url of the recipient, encoded using bech32 with the prefix `lnurl` 67- `lnurl` is the lnurl pay url of the recipient, encoded using bech32 with the prefix `lnurl`
68 68
69This request should return a JSON response with a `pr` key, which is the invoice the sender must pay to finalize his zap. Here is an example flow: 69This request should return a JSON response with a `pr` key, which is the invoice the sender must pay to finalize his zap. Here is an example flow in javascript:
70 70
71```javascript 71```javascript
72const senderPubkey // The sender's pubkey 72const senderPubkey // The sender's pubkey
@@ -78,7 +78,7 @@ const sats = 21
78const amount = sats * 1000 78const amount = sats * 1000
79const relays = ['wss://nostr-pub.wellorder.net'] 79const relays = ['wss://nostr-pub.wellorder.net']
80const event = encodeURI(JSON.stringify(await signEvent({ 80const event = encodeURI(JSON.stringify(await signEvent({
81 kind: [9734], 81 kind: 9734,
82 content: "", 82 content: "",
83 pubkey: senderPubkey, 83 pubkey: senderPubkey,
84 created_at: Math.round(Date.now() / 1000), 84 created_at: Math.round(Date.now() / 1000),
@@ -110,7 +110,8 @@ When a client sends a `zap request` event to a server's lnurl-pay callback URL,
1104. It MUST have 0 or 1 `e` tags 1104. It MUST have 0 or 1 `e` tags
1115. There should be a `relays` tag with the relays to send the `zap receipt` to. 1115. There should be a `relays` tag with the relays to send the `zap receipt` to.
1126. If there is an `amount` tag, it MUST be equal to the `amount` query parameter. 1126. If there is an `amount` tag, it MUST be equal to the `amount` query parameter.
1137. If there is an `a` tag, it MUST be a valid NIP-33 event coordinate 1137. If there is an `a` tag, it MUST be a valid event coordinate
1148. There MUST be 0 or 1 `P` tags. If there is one, it MUST be equal to the `zap receipt`'s `pubkey`.
114 115
115The event MUST then be stored for use later, when the invoice is paid. 116The event MUST then be stored for use later, when the invoice is paid.
116 117
@@ -128,7 +129,7 @@ The following should be true of the `zap receipt` event:
128 129
129- The `content` SHOULD be empty. 130- The `content` SHOULD be empty.
130- The `created_at` date SHOULD be set to the invoice `paid_at` date for idempotency. 131- The `created_at` date SHOULD be set to the invoice `paid_at` date for idempotency.
131- `tags` MUST include the `p` tag AND optional `e` tag from the `zap request`. 132- `tags` MUST include the `p` tag (zap recipient) AND optional `e` tag from the `zap request` AND optional `a` tag from the `zap request` AND optional `P` tag from the pubkey of the zap request (zap sender).
132- The `zap receipt` MUST have a `bolt11` tag containing the description hash bolt11 invoice. 133- The `zap receipt` MUST have a `bolt11` tag containing the description hash bolt11 invoice.
133- The `zap receipt` MUST contain a `description` tag which is the JSON-encoded invoice description. 134- The `zap receipt` MUST contain a `description` tag which is the JSON-encoded invoice description.
134- `SHA256(description)` MUST match the description hash in the bolt11 invoice. 135- `SHA256(description)` MUST match the description hash in the bolt11 invoice.
@@ -148,13 +149,13 @@ Example `zap receipt`:
148 "kind": 9735, 149 "kind": 9735,
149 "tags": [ 150 "tags": [
150 ["p", "32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245"], 151 ["p", "32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245"],
152 ["P", "97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322"],
151 ["e", "3624762a1274dd9636e0c552b53086d70bc88c165bc4dc0f9e836a1eaf86c3b8"], 153 ["e", "3624762a1274dd9636e0c552b53086d70bc88c165bc4dc0f9e836a1eaf86c3b8"],
152 ["bolt11", "lnbc10u1p3unwfusp5t9r3yymhpfqculx78u027lxspgxcr2n2987mx2j55nnfs95nxnzqpp5jmrh92pfld78spqs78v9euf2385t83uvpwk9ldrlvf6ch7tpascqhp5zvkrmemgth3tufcvflmzjzfvjt023nazlhljz2n9hattj4f8jq8qxqyjw5qcqpjrzjqtc4fc44feggv7065fqe5m4ytjarg3repr5j9el35xhmtfexc42yczarjuqqfzqqqqqqqqlgqqqqqqgq9q9qxpqysgq079nkq507a5tw7xgttmj4u990j7wfggtrasah5gd4ywfr2pjcn29383tphp4t48gquelz9z78p4cq7ml3nrrphw5w6eckhjwmhezhnqpy6gyf0"], 154 ["bolt11", "lnbc10u1p3unwfusp5t9r3yymhpfqculx78u027lxspgxcr2n2987mx2j55nnfs95nxnzqpp5jmrh92pfld78spqs78v9euf2385t83uvpwk9ldrlvf6ch7tpascqhp5zvkrmemgth3tufcvflmzjzfvjt023nazlhljz2n9hattj4f8jq8qxqyjw5qcqpjrzjqtc4fc44feggv7065fqe5m4ytjarg3repr5j9el35xhmtfexc42yczarjuqqfzqqqqqqqqlgqqqqqqgq9q9qxpqysgq079nkq507a5tw7xgttmj4u990j7wfggtrasah5gd4ywfr2pjcn29383tphp4t48gquelz9z78p4cq7ml3nrrphw5w6eckhjwmhezhnqpy6gyf0"],
153 ["description", "{\"pubkey\":\"32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245\",\"content\":\"\",\"id\":\"d9cc14d50fcb8c27539aacf776882942c1a11ea4472f8cdec1dea82fab66279d\",\"created_at\":1674164539,\"sig\":\"77127f636577e9029276be060332ea565deaf89ff215a494ccff16ae3f757065e2bc59b2e8c113dd407917a010b3abd36c8d7ad84c0e3ab7dab3a0b0caa9835d\",\"kind\":9734,\"tags\":[[\"e\",\"3624762a1274dd9636e0c552b53086d70bc88c165bc4dc0f9e836a1eaf86c3b8\"],[\"p\",\"32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245\"],[\"relays\",\"wss://relay.damus.io\",\"wss://nostr-relay.wlvs.space\",\"wss://nostr.fmt.wiz.biz\",\"wss://relay.nostr.bg\",\"wss://nostr.oxtr.dev\",\"wss://nostr.v0l.io\",\"wss://brb.io\",\"wss://nostr.bitcoiner.social\",\"ws://monad.jb55.com:8080\",\"wss://relay.snort.social\"]]}"], 155 ["description", "{\"pubkey\":\"97c70a44366a6535c145b333f973ea86dfdc2d7a99da618c40c64705ad98e322\",\"content\":\"\",\"id\":\"d9cc14d50fcb8c27539aacf776882942c1a11ea4472f8cdec1dea82fab66279d\",\"created_at\":1674164539,\"sig\":\"77127f636577e9029276be060332ea565deaf89ff215a494ccff16ae3f757065e2bc59b2e8c113dd407917a010b3abd36c8d7ad84c0e3ab7dab3a0b0caa9835d\",\"kind\":9734,\"tags\":[[\"e\",\"3624762a1274dd9636e0c552b53086d70bc88c165bc4dc0f9e836a1eaf86c3b8\"],[\"p\",\"32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245\"],[\"relays\",\"wss://relay.damus.io\",\"wss://nostr-relay.wlvs.space\",\"wss://nostr.fmt.wiz.biz\",\"wss://relay.nostr.bg\",\"wss://nostr.oxtr.dev\",\"wss://nostr.v0l.io\",\"wss://brb.io\",\"wss://nostr.bitcoiner.social\",\"ws://monad.jb55.com:8080\",\"wss://relay.snort.social\"]]}"],
154 ["preimage", "5d006d2cf1e73c7148e7519a4c68adc81642ce0e25a432b2434c99f97344c15f"] 156 ["preimage", "5d006d2cf1e73c7148e7519a4c68adc81642ce0e25a432b2434c99f97344c15f"]
155 ], 157 ],
156 "content": "", 158 "content": "",
157 "sig": "b0a3c5c984ceb777ac455b2f659505df51585d5fd97a0ec1fdb5f3347d392080d4b420240434a3afd909207195dac1e2f7e3df26ba862a45afd8bfe101c2b1cc"
158 } 159 }
159``` 160```
160 161
@@ -166,18 +167,22 @@ A client can retrieve `zap receipt`s on events and pubkeys using a NIP-01 filter
166- The `invoiceAmount` contained in the `bolt11` tag of the `zap receipt` MUST equal the `amount` tag of the `zap request` (if present). 167- The `invoiceAmount` contained in the `bolt11` tag of the `zap receipt` MUST equal the `amount` tag of the `zap request` (if present).
167- The `lnurl` tag of the `zap request` (if present) SHOULD equal the recipient's `lnurl`. 168- The `lnurl` tag of the `zap request` (if present) SHOULD equal the recipient's `lnurl`.
168 169
169### Appendix G: `zap` tag on zapped event 170### Appendix G: `zap` tag on other events
170 171
171When an event includes a `zap` tag, clients SHOULD calculate the lnurl pay request based on its value instead of the profile's field. An optional third argument on the tag specifies the type of value, either `lud06` or `lud16`. 172When an event includes one or more `zap` tags, clients wishing to zap it SHOULD calculate the lnurl pay request based on the tags value instead of the event author's profile field. The tag's second argument is the `hex` string of the receiver's pub key and the third argument is the relay to download the receiver's metadata (Kind-0). An optional fourth parameter specifies the weight (a generalization of a percentage) assigned to the respective receiver. Clients should parse all weights, calculate a sum, and then a percentage to each receiver. If weights are not present, CLIENTS should equally divide the zap amount to all receivers. If weights are only partially present, receivers without a weight should not be zapped (`weight = 0`).
172 173
173```json 174```js
174{ 175{
175 "tags": [ 176 "tags": [
176 [ "zap", "pablo@f7z.io", "lud16" ] 177 [ "zap", "82341f882b6eabcd2ba7f1ef90aad961cf074af15b9ef44a09f9d2a8fbfbe6a2", "wss://nostr.oxtr.dev", "1" ], // 25%
178 [ "zap", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52", "wss://nostr.wine/", "1" ], // 25%
179 [ "zap", "460c25e682fda7832b52d1f22d3d22b3176d972f60dcdc3212ed8c92ef85065c", "wss://nos.lol/", "2" ] // 50%
177 ] 180 ]
178} 181}
179``` 182```
180 183
184Clients MAY display the zap split configuration in the note.
185
181## Future Work 186## Future Work
182 187
183Zaps can be extended to be more private by encrypting `zap request` notes to the target user, but for simplicity it has been left out of this initial draft. 188Zaps can be extended to be more private by encrypting `zap request` notes to the target user, but for simplicity it has been left out of this initial draft.