mirror of
https://github.com/nostr-protocol/nips.git
synced 2025-01-31 10:31:34 +00:00
90 lines
3.1 KiB
Markdown
90 lines
3.1 KiB
Markdown
NIP-91
|
|
======
|
|
|
|
Protocol Negotiation
|
|
--------------------
|
|
|
|
`draft` `optional`
|
|
|
|
This NIP defines a method for clients to negotiate extension protocols with relays.
|
|
|
|
## Protocol Names
|
|
|
|
Each protocol has a **protocol name** that can uniquely identify the protocol. Currently the following formats are recommended:
|
|
- `nip-XX-<description>`: For protocols standardized in NIPs. Experimental protocols are recommended to have a unique description to not conflict.
|
|
- `<namespace>/<protocol>`: For custom protocols. The namespace should uniquely identify the standardizing body for this protocol with a DNS name. (example: `example.com/example-protocol`)
|
|
- `x/<protocol>`: For custom protocols without a namespace.
|
|
|
|
Any protocol name outside this list MUST NOT be used.
|
|
|
|
## Protocol Offers
|
|
|
|
The relay may send a protocol offer as a `PN-OFFER` message:
|
|
```jsonc
|
|
[
|
|
"PN-OFFER",
|
|
{
|
|
"example.com/example-protocol": {...},
|
|
"nip-XX-example-protocol": {...}
|
|
}
|
|
]
|
|
```
|
|
|
|
The first entry MUST be an object, with the keys being protocol names, and the values being objects. The format of the object is up to the protocol to define.
|
|
|
|
A protocol offer can be sent multiple times in a connection, such as to update availability based off of their [NIP-42](./42.md) authentication status.
|
|
|
|
Clients SHOULD be able to handle protocol offers being able to be withdrawn, and should treat them as if it was a `PN-SHUTDOWN` if they were in use.
|
|
|
|
Certain protocols, such as extensions to REQs, may not need negotiation. This is up to the specification of the specific protocol.
|
|
|
|
## Protocol Requests
|
|
|
|
A client may request a protocol offered by the relay be enabled with the `PN-REQUEST` message:
|
|
```jsonc
|
|
[
|
|
"PN-REQUEST",
|
|
"example.com/example-protocol",
|
|
{...}
|
|
]
|
|
```
|
|
|
|
The first entry MUST be the protocol name, and the second entry MUST be a protocol-dependent object for the protocol enable request.
|
|
|
|
The relay SHOULD respond with a `PN-OK` or `PN-ERROR` message:
|
|
```jsonc
|
|
[
|
|
"PN-OK",
|
|
"example.com/example-protocol",
|
|
{...}
|
|
]
|
|
```
|
|
```jsonc
|
|
[
|
|
"PN-ERROR",
|
|
"example.com/example-protocol",
|
|
"improper protocol request data"
|
|
]
|
|
```
|
|
|
|
In both messages, the first entry MUST be the protocol name. The second entry depends on the type:
|
|
- `PN-OK`: Response data for the protocol negotiation. After this message, the protocol can be used.
|
|
- `PN-ERROR`: An error message.
|
|
|
|
An error message SHOULD start with a single-word prefix, followed by a colon (:) and space character, and a human readable message. The following types are defined:
|
|
- `error`: An internal error has occurred in the relay.
|
|
- `not-offered`: The protocol was not offered. This may happen due to a `PN-REQUEST` being sent at the same time as a new `PN-OFFER`.
|
|
- `bad-data`: The client has sent improper protocol negotiation data.
|
|
|
|
## Protocol Shutdown
|
|
|
|
The relay or client may shut down the usage of the protocol any time with a `PN-SHUTDOWN` message:
|
|
```jsonc
|
|
[
|
|
"PN-SHUTDOWN",
|
|
"example.com/example-protocol"
|
|
]
|
|
```
|
|
|
|
After this message, the sending party will no longer accept and send new protocol messages, and the receiver should not continue attempting to use the protocol functionality.
|