nostr/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2024-12-22 16:35:52 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #529 from jiftechnify/fix-57-wording

Browse Source 
Minor Fixes of NIP-57
This commit is contained in:
Jon Staab 2023-05-14 06:03:32 -07:00 committed by GitHub
commit 00491aa9fa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
57.md
View File

@ -6,21 +6,21 @@ Lightning Zaps
`draft` `optional` `author:jb55` `author:kieran` `draft` `optional` `author:jb55` `author:kieran`
This 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. This 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.
Having lightning receipts on nostr allows clients to display lightning payments from entities on the network. These can be used for fun or for spam deterrence. Having lightning receipts on nostr allows clients to display lightning payments from entities on the network. These can be used for fun or for spam deterrence.
## Protocol flow ## Protocol flow
1. Client calculates a recipient's lnurl pay request url from the `zap` tag on the event being zapped (see Appendix G), or by decoding their lud06 or lud16 field on their profile according to the [lnurl specifications](https://github.com/lnurl/luds). The client MUST send a GET request to this url and parse the response. If `allowsNostr` exists and it is `true`, and if `nostrPubkey` exists and is a valid BIP 340 public key in hex, the client should associate this information with the user, along with the response's `callback`, `minSendable`, and `maxSendable` values. 1. Client calculates a recipient's lnurl pay request url from the `zap` tag on the event being zapped (see Appendix G), or by decoding their lud06 or lud16 field on their profile according to the [lnurl specifications](https://github.com/lnurl/luds). The client MUST send a GET request to this url and parse the response. If `allowsNostr` exists and it is `true`, and if `nostrPubkey` exists and is a valid BIP 340 public key in hex, the client should associate this information with the user, along with the response's `callback`, `minSendable`, and `maxSendable` values.
2. Clients may choose to display a lightning zap button on each post or on a user's profile. If the user's lnurl pay request endpoint supports nostr, the client SHOULD use this NIP to request a zap receipt rather than a normal lnurl invoice. 2. Clients may choose to display a lightning zap button on each post or on a user's profile. If the user's lnurl pay request endpoint supports nostr, the client SHOULD use this NIP to request a `zap receipt` rather than a normal lnurl invoice.
3. When a user (the "sender") indicates they want to send a zap to another user (the "recipient"), the client should create a `zap request` event as described in Appendix A of this NIP and sign it. 3. When a user (the "sender") indicates they want to send a zap to another user (the "recipient"), the client should create a `zap request` event as described in Appendix A of this NIP and sign it.
4. Instead of publishing the `zap request`, the `9734` event should instead be sent to the `callback` url received from the lnurl pay endpoint for the recipient using a GET request. See Appendix B for details and an example. 4. Instead of publishing the `zap request`, the `9734` event should instead be sent to the `callback` url received from the lnurl pay endpoint for the recipient using a GET request. See Appendix B for details and an example.
5. The recipient's lnurl server will receive this request and validate it. See Appendix C for details on how to properly configure an lnurl server to support zaps, and Appendix D for details on how to validate the `nostr` query parameter. 5. The recipient's lnurl server will receive this `zap request` and validate it. See Appendix C for details on how to properly configure an lnurl server to support zaps, and Appendix D for details on how to validate the `nostr` query parameter.
6. If the request is valid, the server should fetch a description hash invoice where the description is this note and this note only. No additional lnurl metadata is included in the description. This will be returned in the response according to [LUD06](https://github.com/lnurl/luds/blob/luds/06.md). 6. If the `zap request` is valid, the server should fetch a description hash invoice where the description is this `zap request` note and this note only. No additional lnurl metadata is included in the description. This will be returned in the response according to [LUD06](https://github.com/lnurl/luds/blob/luds/06.md).
7. On receiving the invoice, the client MAY pay it or pass it to an app that can pay the invoice. 7. On receiving the invoice, the client MAY pay it or pass it to an app that can pay the invoice.
8. Once the invoice is paid, the recipient's lnurl server MUST generate a `zap receipt` as described in Appendix E, and publish it to the `relays` specified in the `zap request`. 8. Once the invoice is paid, the recipient's lnurl server MUST generate a `zap receipt` as described in Appendix E, and publish it to the `relays` specified in the `zap request`.
9. Clients MAY fetch zap notes on posts and profiles, but MUST authorize their validity as described in Appendix F. If the zap request note contains a non-empty `content`, it may display a zap comment. Generally clients should show users the `zap request` note, and use the `zap note` to show "zap authorized by ..." but this is optional. 9. Clients MAY fetch `zap receipt`s on posts and profiles, but MUST authorize their validity as described in Appendix F. If the `zap request` note contains a non-empty `content`, it may display a zap comment. Generally clients should show users the `zap request` note, and use the `zap receipt` to show "zap authorized by ..." but this is optional.
## Reference and examples ## Reference and examples
@ -60,10 +60,10 @@ Example:
### Appendix B: Zap Request HTTP Request ### Appendix B: Zap Request HTTP Request
A signed zap request event is not published, but is instead sent using a HTTP GET request to the recipient's `callback` url, which was provided by the recipient's lnurl pay endpoint. This request should have the following query parameters defined: A signed `zap request` event is not published, but is instead sent using a HTTP GET request to the recipient's `callback` url, which was provided by the recipient's lnurl pay endpoint. This request should have the following query parameters defined:
- `amount` is the amount in _millisats_ the sender intends to pay - `amount` is the amount in _millisats_ the sender intends to pay
- `nostr` is the `9734` zap request event, JSON encoded then URI encoded - `nostr` is the `9734` `zap request` event, JSON encoded then URI encoded
- `lnurl` is the lnurl pay url of the recipient, encoded using bech32 with the prefix `lnurl` - `lnurl` is the lnurl pay url of the recipient, encoded using bech32 with the prefix `lnurl`
This 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: This 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:
@ -97,18 +97,18 @@ const {pr: invoice} = await fetchJson(`${callback}?amount=${amount}&nostr=${even
The lnurl server will need some additional pieces of information so that clients can know that zap invoices are supported: The lnurl server will need some additional pieces of information so that clients can know that zap invoices are supported:
1. Add a `nostrPubkey` to the lnurl-pay static endpoint `/.well-known/lnurlp/<user>`, where `nostrPubkey` is the nostr pubkey your server will use to sign `zap receipt` events. Clients will use this to validate zap receipts. 1. Add a `nostrPubkey` to the lnurl-pay static endpoint `/.well-known/lnurlp/<user>`, where `nostrPubkey` is the nostr pubkey your server will use to sign `zap receipt` events. Clients will use this to validate `zap receipt`s.
2. Add an `allowsNostr` field and set it to true. 2. Add an `allowsNostr` field and set it to true.
### Appendix D: LNURL Server Zap Request Validation ### Appendix D: LNURL Server Zap Request Validation
When a client sends a zap request event to a server's lnurl-pay callback URL, there will be a `nostr` query parameter where the contents of the event are URI- and JSON-encoded. If present, the zap request event must be validated in the following ways: When a client sends a `zap request` event to a server's lnurl-pay callback URL, there will be a `nostr` query parameter whose value is that event which is URI- and JSON-encoded. If present, the `zap request` event must be validated in the following ways:
1. It MUST have a valid nostr signature 1. It MUST have a valid nostr signature
2. It MUST have tags 2. It MUST have tags
3. It MUST have only one `p` tag 3. It MUST have only one `p` tag
4. It MUST have 0 or 1 `e` tags 4. It MUST have 0 or 1 `e` tags
5. There should be a `relays` tag with the relays to send the `zap` note to. 5. There should be a `relays` tag with the relays to send the `zap receipt` to.
6. If there is an `amount` tag, it MUST be equal to the `amount` query parameter. 6. If there is an `amount` tag, it MUST be equal to the `amount` query parameter.
7. If there is an `a` tag, it MUST be a valid NIP-33 event coordinate 7. If there is an `a` tag, it MUST be a valid NIP-33 event coordinate
@ -116,29 +116,29 @@ The event MUST then be stored for use later, when the invoice is paid.
### Appendix E: Zap Receipt Event ### Appendix E: Zap Receipt Event
A `zap receipt` is created by a lightning node when an invoice generated by a `zap request` is paid. Zap receipts are only created when the invoice description (committed to the description hash) contains a zap request note. A `zap receipt` is created by a lightning node when an invoice generated by a `zap request` is paid. `Zap receipt`s are only created when the invoice description (committed to the description hash) contains a `zap request` note.
When receiving a payment, the following steps are executed: When receiving a payment, the following steps are executed:
1. Get the description for the invoice. This needs to be saved somewhere during the generation of the description hash invoice. It is saved automatically for you with CLN, which is the reference implementation used here. 1. Get the description for the invoice. This needs to be saved somewhere during the generation of the description hash invoice. It is saved automatically for you with CLN, which is the reference implementation used here.
2. Parse the bolt11 description as a JSON nostr event. This SHOULD be validated based on the requirements in Appendix D, either when it is received, or before the invoice is paid. 2. Parse the bolt11 description as a JSON nostr event. This SHOULD be validated based on the requirements in Appendix D, either when it is received, or before the invoice is paid.
3. Create a nostr event of kind `9735` as described below, and publish it to the `relays` declared in the zap request. 3. Create a nostr event of kind `9735` as described below, and publish it to the `relays` declared in the `zap request`.
The following should be true of the zap receipt event: The following should be true of the `zap receipt` event:
- The content SHOULD be empty. - The content SHOULD be empty.
- The `created_at` date SHOULD be set to the invoice `paid_at` date for idempotency. - The `created_at` date SHOULD be set to the invoice `paid_at` date for idempotency.
- `tags` MUST include the `p` tag AND optional `e` tag from the zap request. - `tags` MUST include the `p` tag AND optional `e` tag from the `zap request`.
- The zap receipt MUST have a `bolt11` tag containing the description hash bolt11 invoice. - The `zap receipt` MUST have a `bolt11` tag containing the description hash bolt11 invoice.
- The zap receipt MUST contain a `description` tag which is the JSON-encoded invoice description. - The `zap receipt` MUST contain a `description` tag which is the JSON-encoded invoice description.
- `SHA256(description)` MUST match the description hash in the bolt11 invoice. - `SHA256(description)` MUST match the description hash in the bolt11 invoice.
- The zap receipt MAY contain a `preimage` tag to match against the payment hash of the bolt11 invoice. This isn't really a payment proof, there is no real way to prove that the invoice is real or has been paid. You are trusting the author of the zap receipt for the legitimacy of the payment. - The `zap receipt` MAY contain a `preimage` tag to match against the payment hash of the bolt11 invoice. This isn't really a payment proof, there is no real way to prove that the invoice is real or has been paid. You are trusting the author of the `zap receipt` for the legitimacy of the payment.
The zap receipt is not a proof of payment, all it proves is that some nostr user fetched an invoice. The existence of the zap receipt implies the invoice as paid, but it could be a lie given a rogue implementation. The `zap receipt` is not a proof of payment, all it proves is that some nostr user fetched an invoice. The existence of the `zap receipt` implies the invoice as paid, but it could be a lie given a rogue implementation.
A reference implementation for a zap-enabled lnurl server can be found [here](https://github.com/jb55/cln-nostr-zapper). A reference implementation for a zap-enabled lnurl server can be found [here](https://github.com/jb55/cln-nostr-zapper).
Example zap receipt: Example `zap receipt`:
```json ```json
{ {
@ -160,7 +160,7 @@ Example zap receipt:
### Appendix F: Validating Zap Receipts ### Appendix F: Validating Zap Receipts
A client can retrieve `zap receipts` on events and pubkeys using a NIP-01 filter, for example `{"kinds": [9735], "#e": [...]}`. Zaps MUST be validated using the following steps: A client can retrieve `zap receipt`s on events and pubkeys using a NIP-01 filter, for example `{"kinds": [9735], "#e": [...]}`. Zaps MUST be validated using the following steps:
- The `zap receipt` event's `pubkey` MUST be the same as the recipient's lnurl provider's `nostrPubkey` (retrieved in step 1 of the protocol flow). - The `zap receipt` event's `pubkey` MUST be the same as the recipient's lnurl provider's `nostrPubkey` (retrieved in step 1 of the protocol flow).
- The `invoiceAmount` contained in the `bolt11` tag of the `zap receipt` MUST equal the `amount` tag of the `zap request` (if present). - The `invoiceAmount` contained in the `bolt11` tag of the `zap receipt` MUST equal the `amount` tag of the `zap request` (if present).
@ -180,4 +180,4 @@ When an event includes a `zap` tag, clients SHOULD calculate the lnurl pay reque
## Future Work ## Future Work
Zaps 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. Zaps 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.