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. The removal of a protocol from a `PN-OFFER` does not affect existing active protocols, a `PN-SHUTDOWN` must be sent if that is required. 

## 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.