nips/47.md

113 lines
4.6 KiB
Markdown
Raw Normal View History

2023-03-29 21:35:13 +00:00
NIP-47
======
Nostr Wallet Connect
--------------------
`draft` `optional` `author:kiwiidb` `author:bumi` `author:semisol` `author:vitorpamplona`
## Rationale
Paying zaps should be possible without the user needing to open a different app to only pay a Lightning invoice.
This NIP describes a way for users to control a remote Lightning node or a custodial Lightning wallet. When self-hosting, this setup does not require the user to run their own server, thereby bypassing certain hurdles that are commonly encountered when trying to connect to a Lightning node remotely.
## Terms
* **client**: Nostr app on any platform that wants to pay Lightning invoices
* **wallet service**: Nostr app that typically runs on an always-on computer (eg. in the cloud or on a Raspberry Pi).
## Events
There are two event kinds:
- `NIP-47 request`: 23194
- `NIP-47 response`: 23195
Both the request and response events SHOULD only contain one `p` tag, containing the public key of the **wallet service** if this is a request, and the public key of the **client** if this is a response.
The content is encrypted with [NIP04](https://github.com/nostr-protocol/nips/blob/master/04.md), and is a JSON object. The content depends on the kind.
Request:
```jsonc
{
"cmd": "pay_invoice", // command, string
"data": { // data, object
"invoice": "lnbc50n1..." // command-related data
}
}
```
Response:
```jsonc
{
"status": "ok", // status, "ok" | "error"
"event": "0123456789abcdef...", // event the command is in response to, string
"data": { // response data
"preimage": "0123456789abcdef..." // command-related data
}
}
```
The data field SHOULD contain a `message` field with a human readable error message if the status is `error`.
## Nostr Wallet Connect URI
**client** discovers **wallet service** by scanning a QR code, handling a deeplink or pasting in a URI.
The **wallet service** generates this connection URI with protocol `nostr+walletconnect:` and base path it's hex-encoded `pubkey` with the following query string parameters:
- `relay` Required. URL of the relay where the **wallet service** is connected and will be listening for events. May be more than one.
- `secret` Required. 32-byte randomly generated hex encoded string. The **client** should use this to sign events when communicating with the **wallet service**.
- Authorization does not require passing keys back and forth.
- The user can have different keys for different applications. Keys can be revoked and created at will and have arbitrary constraints (eg. budgets).
- The key is harder to leak since it is not shown to the user and backed up.
- It improves privacy because the user's main key would not be linked to their payments.
The **client** should then store this connection and use it when the user wants to perform actions like paying an invoice. Optionally it can display metadata about the connected **wallet service** from it's profile (name, image, url).
### Example connection string
```sh
2023-03-29 22:23:04 +00:00
nostr+walletconnect:b889ff5b1513b641e2a139f661a661364979c5beee91842f8f0ef42ab558e9d4?relay=wss%3A%2F%2Frelay.damus.io&secret=71a8c14c1407c113601079c4302dab36460f0ccd0ad506f1f2dc73b5100e4f3c
2023-03-29 21:35:13 +00:00
```
## Commands
### `pay_invoice`
Description: Requests payment of an invoice.
Request:
```jsonc
{
"invoice": "lnbc50n1..." // BOLT11 invoice, string
}
```
Response:
```jsonc
{
"preimage": "0123456789abcdef..." // preimage after payment, string
}
```
### `balance`
Description: Requests the balance of the wallet.
Request: an empty JSON object.
Response:
```jsonc
{
"balance": 100000 // balance in msat, int
}
```
## Example pay invoice flow
2023-03-29 22:23:04 +00:00
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.
2023-03-29 21:35:13 +00:00
1. **client** sends an event to with **wallet service** service with kind `23194`. The content is a `pay_invoice` request. The private key is the secret from the connection string above.
2023-03-29 22:23:04 +00:00
2. **wallet service** verifies that the author's key is authorized to perform the payment, decrypts the payload and sends the payment.
3. **wallet service** responds to the event by sending an event with kind `23195` and content being a response either containing an error message or a preimage.
2023-03-29 21:35:13 +00:00
## 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.