mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-12-22 08:25:53 -05:00
NIP-47: Implement feedback
Co-authored-by: Semisol <hi@semisol.dev>
This commit is contained in:
kiwiidb
GitHub
parent
c232c9a46a
commit
de095e4758
79
47.md
79
47.md
|
|
@ -17,19 +17,22 @@ This NIP describes a way for clients to access a remote Lightning wallet through
|
|||
|
||||
## Events
|
||||
|
||||
There are two event kinds:
|
||||
There are three event kinds:
|
||||
- `NIP-47 info event`: 13194
|
||||
- `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 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:
|
||||
```jsonc
|
||||
{
|
||||
"cmd": "pay_invoice", // command, string
|
||||
"data": { // data, object
|
||||
"method": "pay_invoice", // method, string
|
||||
"params": { // params, object
|
||||
"invoice": "lnbc50n1..." // command-related data
|
||||
}
|
||||
}
|
||||
|
|
@ -38,21 +41,26 @@ Request:
|
|||
Response:
|
||||
```jsonc
|
||||
{
|
||||
"status": "ok", // status, "ok" | "error"
|
||||
"event": "0123456789abcdef...", // event the command is in response to, string
|
||||
"data": { // response data
|
||||
"result_type": "pay_invoice", //indicates the structure of the result field
|
||||
"error": { //object, non-null in case of error
|
||||
"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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
- `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
|
||||
- `QUOTA_EXCEEDED`: The wallet has exceeded its spending quota.
|
||||
- `RESTRICTED`: This public key is not allowed to do this operation.
|
||||
- `UNAUTHORIZED`: This public key has no wallet connected.
|
||||
- `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:
|
||||
|
||||
- `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.
|
||||
- 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.
|
||||
|
|
@ -79,45 +87,6 @@ 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.
|
||||
|
|
@ -125,14 +94,20 @@ Description: Requests payment of an invoice.
|
|||
Request:
|
||||
```jsonc
|
||||
{
|
||||
"invoice": "lnbc50n1..." // BOLT11 invoice, string
|
||||
"method": "pay_invoice",
|
||||
"params": {
|
||||
"invoice": "lnbc50n1..." // bolt11 invoice
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```jsonc
|
||||
{
|
||||
"preimage": "0123456789abcdef..." // preimage after payment, string
|
||||
"result_type": "pay_invoice",
|
||||
"result": {
|
||||
"preimage": "0123456789abcdef..." // preimage of the payment
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user