Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

NIP-47 notifications #1164

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

NIP-47 notifications #1164

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 116 additions & 12 deletions 47.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 payment_sent`.

### 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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -120,7 +146,8 @@ Response:
{
"result_type": "pay_invoice",
"result": {
"preimage": "0123456789abcdef..." // preimage of the payment
"preimage": "0123456789abcdef...", // preimage of the payment
"fees_paid": 123, // value in msats, optional
}
}
```
Expand Down Expand Up @@ -155,7 +182,8 @@ payment hash of the invoice should be used.
{
"result_type": "multi_pay_invoice",
"result": {
"preimage": "0123456789abcdef..." // preimage of the payment
"preimage": "0123456789abcdef...", // preimage of the payment
"fees_paid": 123, // value in msats, optional
}
}
```
Expand Down Expand Up @@ -189,6 +217,7 @@ Response:
"result_type": "pay_keysend",
"result": {
"preimage": "0123456789abcdef...", // preimage of the payment
"fees_paid": 123, // value in msats, optional
}
}
```
Expand Down Expand Up @@ -225,7 +254,8 @@ pubkey should be used.
{
"result_type": "multi_pay_keysend",
"result": {
"preimage": "0123456789abcdef..." // preimage of the payment
"preimage": "0123456789abcdef...", // preimage of the payment
"fees_paid": 123, // value in msats, optional
}
}
```
Expand Down Expand Up @@ -396,6 +426,59 @@ Response:
"block_height": 1,
"block_hash": "hex string",
"methods": ["pay_invoice", "get_balance", "make_invoice", "lookup_invoice", "list_transactions", "get_info"], // list of supported methods for this connection
"notifications": ["payment_received", "payment_sent"], // list of supported notifications for this connection, optional.
}
}
```

## 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.
}
}
```

### `payment_sent`

Description: A payment was successfully sent by the wallet.

Notification:
```jsonc
{
"notification_type": "payment_sent",
"notification": {
"type": "outgoing",
"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.
}
}
```
Expand All @@ -409,3 +492,24 @@ Response:

## 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.

## Appendix

### Example NIP-47 info event

```jsonc
{
"id": "df467db0a9f9ec77ffe6f561811714ccaa2e26051c20f58f33c3d66d6c2b4d1c",
"pubkey": "c04ccd5c82fc1ea3499b9c6a5c0a7ab627fbe00a0116110d4c750faeaecba1e2",
"created_at": 1713883677,
"kind": 13194,
"tags": [
[
"notifications",
"payment_received payment_sent"
]
],
"content": "pay_invoice pay_keysend get_balance get_info make_invoice lookup_invoice list_transactions multi_pay_invoice multi_pay_keysend sign_message notifications",
"sig": "31f57b369459b5306a5353aa9e03be7fbde169bc881c3233625605dd12f53548179def16b9fe1137e6465d7e4d5bb27ce81fd6e75908c46b06269f4233c845d8"
}
```