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:

[
  "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 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:

[
  "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:

[
  "PN-OK",
  "example.com/example-protocol",
  {...}
]

[
  "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:

[
  "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.

3.1 KiB Raw Blame History