NIP-47: feedbacj

47.md

@@ -8,8 +8,7 @@ Nostr Wallet Connect
 
 ## 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 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 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
 
@@ -47,7 +46,17 @@ Response:
 }
 ```
 
-The data field SHOULD contain a `message` field with a human readable error message if the status is `error`.
+The data field SHOULD contain a `message` field with a human readable error message and a `code` field with the error code if the status is `error`.
+
+### 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.
+- `INSUFFICIENT_BALANCE`: The wallet does not have enough funds to cover a fee reserve or the payment amount.
+- `QUOTA_EXCEEDED`: The wallet has exceeded
+- `RESTRICTED`: This public key is not allowed to do this operation.
+- `UNAUTHORIZED`: This public key has no wallet connected.
+- `INTERNAL`: An internal error.
+- `OTHER`: Other error.
 
 ## Nostr Wallet Connect URI
 **client** discovers **wallet service** by scanning a QR code, handling a deeplink or pasting in a URI.
@@ -61,7 +70,7 @@ The **wallet service** generates this connection URI with protocol `nostr+wallet
     - 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).
+The **client** should then store this connection and use it when the user wants to perform actions like paying an invoice. Due to this NIP using ephemeral events, it is recommended to pick relays that do not close connections on inactivity to not drop events.
 
 ### Example connection string
 ```sh
@@ -70,6 +79,45 @@ nostr+walletconnect:b889ff5b1513b641e2a139f661a661364979c5beee91842f8f0ef42ab558
 
 ## Commands
 
+### `get_info`
+
+Description: Get information about the wallet and service.
+
+Request: Empty object.
+
+Response:
+```jsonc
+{
+    "balance": 100000, // balance in msat, int
+                       // this should be capped at the quota allowed for this client
+                       // to not report unspendable balance.
+    "implemented_commands": ["get_info", "pay_invoice"]  // commands supported, string array
+                            // extensions can be specified via command+extension:
+                            // get_info+node_info
+}
+```
+
+### `create_invoice`
+
+Description: Requests creation of an invoice.
+
+Request:
+```jsonc
+{
+    "amount": 1000, // amount in msat, int
+                    // must be a whole number of sats unless
+                    // create_invoice+msat_amount is implemented.
+    "description": "memo" // a description, string, optional
+}
+```
+
+Response:
+```jsonc
+{
+    "invoice": "lnbc50n1..." // BOLT11 invoice, string
+}
+```
+
 ### `pay_invoice`
 
 Description: Requests payment of an invoice.
@@ -88,19 +136,6 @@ Response:
 }
 ```
 
-### `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
 
 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.