diff options
| -rw-r--r-- | 47.md | 100 |
1 files changed, 3 insertions, 97 deletions
| @@ -28,7 +28,7 @@ Fundamentally NWC is communication between a **client** and **wallet service** b | |||
| 28 | 28 | ||
| 29 | 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. | 29 | 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. |
| 30 | 30 | ||
| 31 | 5. The **wallet service** may send encrypted notifications (kind 23197 or 23196) of wallet events (such as a received payment) to the **client**. | 31 | 5. The **wallet service** may send encrypted notifications (kind 23197) of wallet events (such as a received payment) to the **client**. |
| 32 | 32 | ||
| 33 | ## Events | 33 | ## Events |
| 34 | 34 | ||
| @@ -134,8 +134,6 @@ The content of notifications is encrypted with [NIP44](44.md) (or NIP-04 for leg | |||
| 134 | } | 134 | } |
| 135 | ``` | 135 | ``` |
| 136 | 136 | ||
| 137 | _Note on backwards-compatibility:_ If a **wallet service** supports both nip44 and nip04 for legacy client apps, it should publish both notification events for each notification - kind 23196 encrypted with NIP-04, and kind 23197 encrypted with NIP-44. It is up to the **client** to decide which event to listen to based on its supported encryption and declared supported encryption schemes of the **wallet service** in the `info` event. | ||
| 138 | |||
| 139 | ### Error codes | 137 | ### Error codes |
| 140 | - `RATE_LIMITED`: The client is sending commands too fast. It should retry in a few seconds. | 138 | - `RATE_LIMITED`: The client is sending commands too fast. It should retry in a few seconds. |
| 141 | - `NOT_IMPLEMENTED`: The command is not known or is intentionally not implemented. | 139 | - `NOT_IMPLEMENTED`: The command is not known or is intentionally not implemented. |
| @@ -207,42 +205,6 @@ Response: | |||
| 207 | Errors: | 205 | Errors: |
| 208 | - `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar. | 206 | - `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar. |
| 209 | 207 | ||
| 210 | ### `multi_pay_invoice` | ||
| 211 | |||
| 212 | Description: Requests payment of multiple invoices. | ||
| 213 | |||
| 214 | Request: | ||
| 215 | ```jsonc | ||
| 216 | { | ||
| 217 | "method": "multi_pay_invoice", | ||
| 218 | "params": { | ||
| 219 | "invoices": [ | ||
| 220 | {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11 invoice and amount in msats, amount is optional | ||
| 221 | {"id":"3da52c32a1", "invoice": "lnbc50n1...", "metadata": {} }, // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc, optional | ||
| 222 | ], | ||
| 223 | } | ||
| 224 | } | ||
| 225 | ``` | ||
| 226 | |||
| 227 | Response: | ||
| 228 | |||
| 229 | For every invoice in the request, a separate response event is sent. To differentiate between the responses, each | ||
| 230 | response event contains a `d` tag with the id of the invoice it is responding to; if no id was given, then the | ||
| 231 | payment hash of the invoice should be used. | ||
| 232 | |||
| 233 | ```jsonc | ||
| 234 | { | ||
| 235 | "result_type": "multi_pay_invoice", | ||
| 236 | "result": { | ||
| 237 | "preimage": "0123456789abcdef...", // preimage of the payment | ||
| 238 | "fees_paid": 123, // value in msats, optional | ||
| 239 | } | ||
| 240 | } | ||
| 241 | ``` | ||
| 242 | |||
| 243 | Errors: | ||
| 244 | - `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar. | ||
| 245 | |||
| 246 | ### `pay_keysend` | 208 | ### `pay_keysend` |
| 247 | 209 | ||
| 248 | Request: | 210 | Request: |
| @@ -277,44 +239,6 @@ Response: | |||
| 277 | Errors: | 239 | Errors: |
| 278 | - `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar. | 240 | - `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar. |
| 279 | 241 | ||
| 280 | ### `multi_pay_keysend` | ||
| 281 | |||
| 282 | Description: Requests multiple keysend payments. | ||
| 283 | |||
| 284 | Has an array of keysends, these follow the same semantics as `pay_keysend`, just done in a batch | ||
| 285 | |||
| 286 | Request: | ||
| 287 | ```jsonc | ||
| 288 | { | ||
| 289 | "method": "multi_pay_keysend", | ||
| 290 | "params": { | ||
| 291 | "keysends": [ | ||
| 292 | {"id": "4c5b24a351", "pubkey": "03...", "amount": 123}, | ||
| 293 | {"id": "3da52c32a1", "pubkey": "02...", "amount": 567, "preimage": "abc123..", "tlv_records": [{"type": 696969, "value": "77616c5f6872444873305242454d353736"}]}, | ||
| 294 | ], | ||
| 295 | } | ||
| 296 | } | ||
| 297 | ``` | ||
| 298 | |||
| 299 | Response: | ||
| 300 | |||
| 301 | For every keysend in the request, a separate response event is sent. To differentiate between the responses, each | ||
| 302 | response event contains a `d` tag with the id of the keysend it is responding to; if no id was given, then the | ||
| 303 | pubkey should be used. | ||
| 304 | |||
| 305 | ```jsonc | ||
| 306 | { | ||
| 307 | "result_type": "multi_pay_keysend", | ||
| 308 | "result": { | ||
| 309 | "preimage": "0123456789abcdef...", // preimage of the payment | ||
| 310 | "fees_paid": 123, // value in msats, optional | ||
| 311 | } | ||
| 312 | } | ||
| 313 | ``` | ||
| 314 | |||
| 315 | Errors: | ||
| 316 | - `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar. | ||
| 317 | |||
| 318 | ### `make_invoice` | 242 | ### `make_invoice` |
| 319 | 243 | ||
| 320 | Request: | 244 | Request: |
| @@ -671,23 +595,6 @@ The negotiation works as follows. | |||
| 671 | 1. The **wallet service** includes an `encryption` tag in the `info` event. This tag contains a space-separated list of encryption schemes that the **wallet service** supports (eg. `nip44_v2 nip04`) | 595 | 1. The **wallet service** includes an `encryption` tag in the `info` event. This tag contains a space-separated list of encryption schemes that the **wallet service** supports (eg. `nip44_v2 nip04`) |
| 672 | 2. The **client application** includes an `encryption` tag in each request event. This tag contains the encryption scheme which should be used for the request. The **client application** should always prefer nip44 if supported by the **wallet service**. | 596 | 2. The **client application** includes an `encryption` tag in each request event. This tag contains the encryption scheme which should be used for the request. The **client application** should always prefer nip44 if supported by the **wallet service**. |
| 673 | 597 | ||
| 674 | ### Info event | ||
| 675 | |||
| 676 | First, the **wallet service** adds an `encryption` tag to its `info` event containing a space-separated list of encryption schemes it supports. For example, | ||
| 677 | if a wallet service supports nip44, but also allows backwards-compatibility to nip04 client applications, its `encryption` tag in the `info` event might look something like: | ||
| 678 | |||
| 679 | ```jsonc | ||
| 680 | { | ||
| 681 | "kind": 13194, | ||
| 682 | "tags": [ | ||
| 683 | ["encryption", "nip44_v2 nip04"], | ||
| 684 | // ... | ||
| 685 | ], | ||
| 686 | "content": "pay_invoice get_balance make_invoice lookup_invoice list_transactions get_info", | ||
| 687 | // ... | ||
| 688 | } | ||
| 689 | ``` | ||
| 690 | |||
| 691 | When a **client application** establishes a connection, it should read the info event and look for the `encryption` tag. | 598 | When a **client application** establishes a connection, it should read the info event and look for the `encryption` tag. |
| 692 | 599 | ||
| 693 | **Absence of this tag implies that the wallet only supports nip04.** | 600 | **Absence of this tag implies that the wallet only supports nip04.** |
| @@ -714,7 +621,7 @@ If the **wallet service** does not support the specified encryption scheme, it w | |||
| 714 | 621 | ||
| 715 | ### Notification events | 622 | ### Notification events |
| 716 | 623 | ||
| 717 | As described above in the [Notifications](#notifications) section, if a **wallet service** supports both nip04 and nip44, it should publish two notification events for each notification - kind 23196 encrypted with NIP-04, and kind 23197 encrypted with NIP-44. If the **wallet service** only supports nip44, it should only publish kind 23197 events. | 624 | If a **wallet service** supports both nip04 and nip44, it should publish two notification events for each notification - kind 23196 encrypted with NIP-04, and kind 23197 encrypted with NIP-44. If the **wallet service** only supports nip44, it should only publish kind 23197 events. |
| 718 | 625 | ||
| 719 | The **client** should check the `encryption` tag in the `info` event to determine which encryption schemes the **wallet service** supports, and listen to the appropriate notification event. | 626 | The **client** should check the `encryption` tag in the `info` event to determine which encryption schemes the **wallet service** supports, and listen to the appropriate notification event. |
| 720 | 627 | ||
| @@ -785,6 +692,7 @@ Here are some properties that are recognized by some NWC clients: | |||
| 785 | 692 | ||
| 786 | * Calls `settle_hold_invoice` with the original preimage to release funds, or | 693 | * Calls `settle_hold_invoice` with the original preimage to release funds, or |
| 787 | * Calls `cancel_hold_invoice` with payment hash to abort. | 694 | * Calls `cancel_hold_invoice` with payment hash to abort. |
| 695 | |||
| 788 | ### Deep-links | 696 | ### Deep-links |
| 789 | 697 | ||
| 790 | Wallet applications can register deeplinks in mobile systems to make it possible to create a linking UX that doesn't require the user scanning a QR code or pasting some code. | 698 | Wallet applications can register deeplinks in mobile systems to make it possible to create a linking UX that doesn't require the user scanning a QR code or pasting some code. |
| @@ -800,5 +708,3 @@ URI parameters: | |||
| 800 | 708 | ||
| 801 | Once a connection has been created by the wallet, it should be returned to the client by opening the callback with the following parameters | 709 | Once a connection has been created by the wallet, it should be returned to the client by opening the callback with the following parameters |
| 802 | * `value` -- NWC pairing code (e.g. `nostr+walletconnect://...`) | 710 | * `value` -- NWC pairing code (e.g. `nostr+walletconnect://...`) |
| 803 | |||
| 804 | |||