nostr/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2024-11-09 22:09:06 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

NIP-47: Implement feedback

Browse Source 
Co-authored-by: Semisol <hi@semisol.dev>
This commit is contained in:
kiwiidb 2023-04-27 16:21:15 +02:00 committed by GitHub
parent c232c9a46a
commit de095e4758
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 27 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
47.md
View File

@ -17,19 +17,22 @@ This NIP describes a way for clients to access a remote Lightning wallet through
## Events ## Events
There are two event kinds: There are three event kinds:
- `NIP-47 info event`: 13194
- `NIP-47 request`: 23194 - `NIP-47 request`: 23194
- `NIP-47 response`: 23195 - `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 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-seperated, eg. `pay_invoice get_balance`. Only the `pay_invoice` command is described in this NIP, but other commands might be defined in different NIPs.
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 **client** if this is a response. The response event SHOULD contain an `e` tag with the id of the request event it is responding to.
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. The content of requests and responses 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:
Request: Request:
```jsonc ```jsonc
{ {
"cmd": "pay_invoice", // command, string "method": "pay_invoice", // method, string
"data": { // data, object "params": { // params, object
"invoice": "lnbc50n1..." // command-related data "invoice": "lnbc50n1..." // command-related data
} }
} }
@ -38,21 +41,26 @@ Request:
Response: Response:
```jsonc ```jsonc
{ {
"status": "ok", // status, "ok" | "error" "result_type": "pay_invoice", //indicates the structure of the result field
"event": "0123456789abcdef...", // event the command is in response to, string "error": { //object, non-null in case of error
"data": { // response data "code": "UNAUTHORIZED", //string error code, see below
"message": "human readable error message"
},
"result": { // result, object. null in case of error.
"preimage": "0123456789abcdef..." // command-related data "preimage": "0123456789abcdef..." // command-related data
} }
} }
``` ```
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`. The `result_type` field MUST contain the name of the method that this event is responding to.
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 succesful.
If the command was succesful, the `error` field must be null.
### Error codes ### Error codes
- `RATE_LIMITED`: The client is sending commands too fast. It should retry in a few seconds. - `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. - `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. - `INSUFFICIENT_BALANCE`: The wallet does not have enough funds to cover a fee reserve or the payment amount.
- `QUOTA_EXCEEDED`: The wallet has exceeded - `QUOTA_EXCEEDED`: The wallet has exceeded its spending quota.
- `RESTRICTED`: This public key is not allowed to do this operation. - `RESTRICTED`: This public key is not allowed to do this operation.
- `UNAUTHORIZED`: This public key has no wallet connected. - `UNAUTHORIZED`: This public key has no wallet connected.
- `INTERNAL`: An internal error. - `INTERNAL`: An internal error.
@ -64,7 +72,7 @@ The data field SHOULD contain a `message` field with a human readable error mess
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: 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. - `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**. - `secret` Required. 32-byte randomly generated hex encoded string. The **client** MUST use this to sign events and encrypt payloads when communicating with the **wallet service**.
- Authorization does not require passing keys back and forth. - 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 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. - The key is harder to leak since it is not shown to the user and backed up.
@ -79,45 +87,6 @@ nostr+walletconnect:b889ff5b1513b641e2a139f661a661364979c5beee91842f8f0ef42ab558
## Commands ## 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` ### `pay_invoice`
Description: Requests payment of an invoice. Description: Requests payment of an invoice.
@ -125,14 +94,20 @@ Description: Requests payment of an invoice.
Request: Request:
```jsonc ```jsonc
{ {
"invoice": "lnbc50n1..." // BOLT11 invoice, string "method": "pay_invoice",
"params": {
"invoice": "lnbc50n1..." // bolt11 invoice
}
} }
``` ```
Response: Response:
```jsonc ```jsonc
{ {
"preimage": "0123456789abcdef..." // preimage after payment, string "result_type": "pay_invoice",
"result": {
"preimage": "0123456789abcdef..." // preimage of the payment
}
} }
``` ```