Mirror/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2025-01-18 04:01:33 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update NIP-91

Browse Source 
The NIP has been renamed to represent the goals of the NIP more accurately.

The x/ extension namespace has been removed, and any features meant to be standardized as a NIP should create a preliminary PR and use the `nip/` namespace. Any extensions that are meant to be standardized externally should use their own namespace.
This commit is contained in:
Semisol 2025-01-03 15:29:20 +03:00 committed by GitHub
parent 8231c8e1e9
commit fc323706fa
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 38 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
91.md
View File

@ -1,89 +1,88 @@
NIP-91
======
Protocol Negotiation
--------------------
Extension Negotiation
---------------------
`draft` `optional`
This NIP defines a method for clients to negotiate extension protocols with relays.
This NIP defines a method for clients to negotiate new features with relays.
## Protocol Names
## Extension 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.
Each extension has a **extension name** that can uniquely identify the extension. Currently the following formats are recommended:
- `nip/XX-<description>`: For extensions that are standardized in NIPs. Experimental extensions are recommended to have a unique description to not conflict.
- `<namespace>/<extension>`: For extensions standardized by an independent body. The namespace should uniquely identify the standardizing body for this extension with a DNS name. (example: `example.com/example-extension`)
Any protocol name outside this list MUST NOT be used.
Any extension name outside this list MUST NOT be used.
## Protocol Offers
## Extension Offers
The relay may send a protocol offer as a `PN-OFFER` message:
The relay may send a extension offer as a `EN-OFFER` message. The client SHOULD NOT send any messages relating to extension negotiation until it receives an `EN-OFFER`.
```jsonc
[
"PN-OFFER",
"EN-OFFER",
{
"example.com/example-protocol": {...},
"nip-XX-example-protocol": {...}
"example.com/example-extension": {...},
"nip-XX-example-extension": {...}
}
]
```
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.
The first entry MUST be an object, with the keys being extension names, and the values being objects. The format of the object is left to the specification of the specific extension.
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.
A extension 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.
Clients SHOULD be able to handle extension offers being able to be withdrawn, and should treat them as if it was a `EN-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.
Certain extensions, such as extensions to REQs, may not need negotiation. This is up to the extension specification.
## Protocol Requests
## Extension Requests
A client may request a protocol offered by the relay be enabled with the `PN-REQUEST` message:
A client may request a extension offered by the relay be enabled with the `EN-REQUEST` message:
```jsonc
[
"PN-REQUEST",
"example.com/example-protocol",
"EN-REQUEST",
"example.com/example-extension",
{...}
]
```
The first entry MUST be the protocol name, and the second entry MUST be a protocol-dependent object for the protocol enable request.
The first entry MUST be the extension name, and the second entry MUST be a extension-dependent object for the extension enable request.
The relay SHOULD respond with a `PN-OK` or `PN-ERROR` message:
The relay SHOULD respond with a `EN-OK` or `EN-ERROR` message:
```jsonc
[
"PN-OK",
"example.com/example-protocol",
"EN-OK",
"example.com/example-extension",
{...}
]
```
```jsonc
[
"PN-ERROR",
"example.com/example-protocol",
"improper protocol request data"
"EN-ERROR",
"example.com/example-extension",
"improper extension 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.
In both messages, the first entry MUST be the extension name. The second entry depends on the type:
- `EN-OK`: Response data for the extension negotiation. After this message, the extension can be used.
- `EN-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.
- `not-offered`: The extension was not offered. This may happen due to a `EN-REQUEST` being sent at the same time as a new `EN-OFFER`.
- `bad-data`: The client has sent improper extension negotiation data.
## Protocol Shutdown
## Extension Cancel
The relay or client may shut down the usage of the protocol any time with a `PN-SHUTDOWN` message:
The relay or client may stop the usage of the extension any time with a `EN-CANCEL` message:
```jsonc
[
"PN-SHUTDOWN",
"example.com/example-protocol"
"EN-CANCEL",
"example.com/example-extension"
]
```
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.
After this message, the sending party will no longer accept and send new extension messages, and the receiver should not continue attempting to use the extension functionality.