NIP-11 extension for Relay Limitations

111.md

@@ -0,0 +1,229 @@
+NIP-11a
+=======
+
+Additional Relay Information for NIP-11
+---------------------------------------
+
+`draft` `optional` `author:doc-hex` `extends:11`
+
+Relays may provide additional metadata to clients to inform them of
+more detailed limitations and policy choices. This is made available
+as additional fields in the a JSON document already defined by
+[NIP-11](11.md). All are optional and may be omitted.
+
+All numbers and values show in theses examples, are merely _examples_
+and do not constitute default values or expectations. The purpose
+of this NIP is to allow clients to directly discover the actual
+values chosen by the relay operators.
+
+Background
+----------
+
+Support for this NIP should be documented in the `supported_nips` list
+of the same response.
+
+```json
+{
+...
+  supported_nips: <a list of NIP numbers supported by the relay, including this one>,
+...
+}
+```
+
+Server Limitations
+------------------
+
+These are limitations imposed by the relay on clients. Your client
+should expect that requests which exceed these *practical* limitations
+are rejected or fail immediately.
+
+```json
+{
+...
+  limitation: {
+        max_message_length: 16384,
+        max_subscriptions: 20,
+        max_filters: 100,
+        max_limit: 5000,
+        max_subid_length: 100,
+        min_prefix: 4,
+        max_event_tags: 100,
+        max_content_length: 8196,
+        min_pow_difficulty: 30,
+        auth_required: true,
+        payment_required: true,
+  }
+...
+}
+```
+
+- `max_message_length`: this is the maximum number of bytes for incoming JSON that the relay
+will attempt to decode and act upon. When you send large subscriptions, you will be
+limited by this value. It also effectively limits the maximum size of any event. Value is
+calculated from `[` to `]` and is after UTF-8 serialization (so some unicode characters
+will cost 2-3 bytes). It is equal to the maximum size of the WebSocket message frame.
+
+- `max_subscriptions`: total number of subscriptions that may be
+active on a single websocket connection to this relay. It's possible
+that authenticated clients with a (paid) relationship to the relay
+may have higher limits.
+
+- `max_filters`: maximum number of filter values in each subscription.
+Must be one or higher.
+
+- `max_subid_length`: maximum length of subscription id as a string.
+
+- `min_prefix`: for `authors` and `ids` filters which are to match against
+a hex prefix, you must provide at least this many hex digits in the prefix.
+
+- `max_limit`: the relay server will clamp each filter's `limit` value to this number.
+This means the client won't be able to get more than this number
+of events from a single subscription filter. This clamping is typically done silently
+by the relay, but with this number, you can know that there are additional results
+if you narrowed your filter's time range or other parameters.
+
+- `max_event_tags`: in any event, this is the maximum number of elements in the `tags` list.
+
+- `max_content_length`: maximum number of characters in the `content`
+field of any event. This is a count of unicode characters. After
+serializing into JSON it may be larger (in bytes), and is still
+subject to the `max_message_length`, if defined.
+
+- `min_pow_difficulty`: new events will require at least this difficulty of PoW, 
+based on [NIP-13](13.md), or they will be rejected by this server.
+
+- `auth_required`: this relay requires [NIP-42](42.md) authentication
+to happen before a new connection may perform any other action.
+Even if set to False, authentication may be required for specific actions.
+
+- `payment_required`: this relay requires payment before a new connection may perform any action.
+
+Event Retention
+---------------
+
+There may be a cost associated with storing data forever, so relays 
+may wish to state retention times. The values stated here are defaults
+for unauthenticated users and visitors. Paid users would likely have
+other policies.
+
+Retention times are given in seconds, with `null` indicating infinity.
+If zero is provided, this means the event will not be stored at
+all, and preferably an error will be provided when those are received.
+
+```json
+{
+...
+  retention: [
+    { kinds: [0, 1, [5, 7], [40, 49]], time: 3600 },
+    { kinds: [[40000, 49999], time: 100 },
+    { kinds: [[30000, 39999], count: 1000 },
+    { time: 3600, count: 10000 }
+  ]
+...
+}
+```
+
+`retention` is a list of specifications: each will apply to either all kinds, or 
+a subset of kinds. Ranges may be specified for the kind field as a tuple of inclusive
+start and end values. Events of indicated kind (or all) are then limited to a `count`
+and or time period.
+
+It is possible to effectively blacklist Nostr-based protocols that rely on
+a specific `kind` number, by giving a retention time of zero for those `kind` values.
+While that is unfortunate, it does allow clients to discover servers that will
+support their protocol quickly via a single HTTP fetch.
+
+There is no need to specify retention times for _ephemeral events_ as defined
+in [NIP-16](16.md) since they are not retained.
+
+
+Content Limitations
+-------------------
+
+Some relays may be governed by the arbitrary laws of a nation state. This
+may limit what content can be stored in cleartext on those relays. All
+clients are encouraged to use encryption to work around this limitation.
+
+It is not possible to describe the limitations of each country's laws
+and policies which themselves are typically vague and constantly shifting.
+
+Therefore, this field allows the relay operator to indicate which
+country's' laws might end up being enforced on them, and then
+indirectly on their users's content.
+
+Users should be able to avoid relays in countries they don't like,
+and/or select relays in more favourable zones. Exposing this
+flexibility is up to the client software.
+
+```json
+{
+...
+  relay_countries: [ 'CA', 'US' ],
+...
+}
+```
+
+- `relay_countries`: a list of two-level ISO country codes (ISO 3166-1 alpha-2)  whose
+  laws and policies may affect this relay. `EU` may be used for European Union countries.
+
+Remember that a relay may be hosted in a country which is not the
+country of the legal entities who own the relay, so it's very
+likely a number of countries are involved.
+
+
+Community Preferences
+---------------------
+
+For public text notes at least, a relay may try to foster a
+local community. This would encourage users to follow the global
+feed on that relay, in addition to their usual individual follows.
+To support this goal, relays MAY specify some of the following values.
+
+```json
+{
+...
+  language_tags: [ 'en', 'en-419' ],
+  tags: [ 'sfw-only', 'bitcoin-only', 'anime' ],
+  posting_policy: 'https://example.com/posting-policy.html',
+...
+}
+```
+
+- `language_tags` is an ordered list
+  of [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag) indicating
+  the major languages spoken on the relay.
+
+- `tags` is a list of limitations on the topics to be discussed.
+  For example `sfw-only` indicates hat only "Safe For Work" content
+  is encouraged on this relay. This relies on assumptions of what the
+  "work" "community" feels "safe" talking about. In time, a common
+  set of tags may emerge that allow users to find relays that suit
+  their needs, and client software will be able to parse these tags easily.
+  The `bitcoin-only` tag indicates that any *altcoin*, *"crypto"* or *blockchain*
+  comments will be ridiculed without mercy.
+
+- `posting_policy` is a link to a human-readable page which specifies the
+  community policies for the relay. In cases where `sfw-only` is True, it's
+  important to link to a page which gets into the specifics of your posting policy.
+
+The `description` field should be used to describe your community
+goals and values, in brief. The `posting_policy` is for additional
+detail and legal terms. Use the `tags` field to signify limitations
+on content, or topics to be discussed, which could be machine
+processed by appropriate client software.
+Pay-To-Relay
+==========
+
+Relays that require payments may want to expose their fee schedules.
+
+```json
+{
+...
+  payments_url: "https://my-relay/payments",
+  fees: {
+    "admission": [{ amount: 1000000, unit: 'msats' }],
+    "subscription": [{ amount: 5000000, unit: 'msats', period: 2592000 }],
+    "publication": [{ kinds: [4], amount: 100, unit: 'msats' }],
+  },
+...
+}