diff --git a/47.md b/47.md index 90338477b5..c16fb1f200 100644 --- a/47.md +++ b/47.md @@ -8,32 +8,42 @@ Nostr Wallet Connect ## Rationale -This NIP describes a way for clients to access a remote Lightning wallet through a standardized protocol. Custodians may implement this, or the user may run a bridge that bridges their wallet/node and the Nostr Wallet Connect protocol. +This NIP describes a way for clients to access a remote lightning wallet through a standardized protocol. Custodians may implement this, or the user may run a bridge that bridges their wallet/node and the Nostr Wallet Connect protocol. ## Terms -* **client**: Nostr app on any platform that wants to pay Lightning invoices. -* **user**: The person using the **client**, and want's to connect their wallet app to their **client**. +* **client**: Nostr app on any platform that wants to interact with a lightning wallet. +* **user**: The person using the **client**, and wants to connect their wallet to their **client**. * **wallet service**: Nostr app that typically runs on an always-on computer (eg. in the cloud or on a Raspberry Pi). This app has access to the APIs of the wallets it serves. ## Theory of Operation - 1. **Users** who wish to use this NIP to send lightning payments to other nostr users must first acquire a special "connection" URI from their NIP-47 compliant wallet application. The wallet application may provide this URI using a QR screen, or a pasteable string, or some other means. + 1. **Users** who wish to use this NIP to allow **client(s)** to interact with their wallet must first acquire a special "connection" URI from their NIP-47 compliant wallet application. The wallet application may provide this URI using a QR screen, or a pasteable string, or some other means. - 2. The **user** should then copy this URI into their **client(s)** by pasting, or scanning the QR, etc. The **client(s)** should save this URI and use it later whenever the **user** makes a payment. The **client** should then request an `info` (13194) event from the relay(s) specified in the URI. The **wallet service** will have sent that event to those relays earlier, and the relays will hold it as a replaceable event. + 2. The **user** should then copy this URI into their **client(s)** by pasting, or scanning the QR, etc. The **client(s)** should save this URI and use it later whenever the **user** (or the **client** on the user's behalf) wants to interact with the wallet. The **client** should then request an `info` (13194) event from the relay(s) specified in the URI. The **wallet service** will have sent that event to those relays earlier, and the relays will hold it as a replaceable event. 3. When the **user** initiates a payment their nostr **client** create a `pay_invoice` request, encrypts it using a token from the URI, and sends it (kind 23194) to the relay(s) specified in the connection URI. The **wallet service** will be listening on those relays and will decrypt the request and then contact the **user's** wallet application to send the payment. The **wallet service** will know how to talk to the wallet application because the connection URI specified relay(s) that have access to the wallet app API. - 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. + 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**. ## Events -There are three event kinds: +There are four event kinds: - `NIP-47 info event`: 13194 - `NIP-47 request`: 23194 - `NIP-47 response`: 23195 +- `NIP-47 notification event`: 23196 + +### Info Event + +The info event should be a replaceable event that is published by the **wallet service** on the relay to indicate which capabilities it supports. + +The content should be a plaintext string with the supported capabilities space-separated, eg. `pay_invoice get_balance notifications`. -The info event should be a replaceable event that is published by the **wallet service** on the relay to indicate which commands it supports. The content should be -a plaintext string with the supported commands, space-separated, eg. `pay_invoice get_balance`. Only the `pay_invoice` command is described in this NIP, but other commands might be defined in different NIPs. +If the **wallet service** supports notifications, the info event SHOULD contain a `notifications` tag with the supported notification types space-separated, eg. `payment_received balance_changed`. + +### 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 **user** 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. @@ -68,6 +78,22 @@ The `result_type` field MUST contain the name of the method that this event is r The `error` field MUST contain a `message` field with a human readable error message and a `code` field with the error code if the command was not successful. 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 **user**. + +The content of notifications is encrypted with [NIP04](https://github.com/nostr-protocol/nips/blob/master/04.md), and is a JSON-RPCish object with a semi-fixed structure: + +```jsonc +{ + "notification_type": "payment_received", //indicates the structure of the notification field + "notification": { + "payment_hash": "0123456789abcdef..." // notification-related data + } +} +``` + + ### 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. @@ -400,6 +426,33 @@ Response: } ``` +## Notifications + +### `payment_received` + +Description: A payment was successfully received by the wallet. + +Notification: +```jsonc +{ + "notification_type": "payment_received", + "notification": { + "type": "incoming", + "invoice": "string", // encoded invoice + "description": "string", // invoice's description, optional + "description_hash": "string", // invoice's description hash, optional + "preimage": "string", // payment's preimage + "payment_hash": "string", // Payment hash for the payment + "amount": 123, // value in msats + "fees_paid": 123, // value in msats + "created_at": unixtimestamp, // invoice/payment creation time + "expires_at": unixtimestamp, // invoice expiration time, optional if not applicable + "settled_at": unixtimestamp, // invoice/payment settlement time + "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.