From 0ce5e188a1633b95550e26c0757a2789afa78809 Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Sun, 8 Jan 2023 13:42:19 -0500 Subject: [PATCH 1/9] first --- 111.md | 169 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 111.md diff --git a/111.md b/111.md new file mode 100644 index 0000000000..3e8d3b5bab --- /dev/null +++ b/111.md @@ -0,0 +1,169 @@ +NIP-111 +======= + +Addition Relay Information for NIP-11 +------------------------------------- + +`draft` `optional` `author:doc-hex` + +Relays may provide addition 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 defined by [NIP-11](11.md). All are optional +and may be omitted. + +All numbers and values show in the examples here, are merely examples +and do not consituite a default value or expectation. 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: , +... +} +``` + +Server Limitiations +------------------- + +These are limitations imposed by the server on clients. Your client +should expect that requests which exceed these *practical* limitations +are rejected or fail immediately. + +```json +{ +... + limitation: { + max_raw_json: 16384, + max_subscriptions: 20, + max_filters: 100, + subid_length: 100, + } +... +} +``` + +- `max_raw_json`: this is the maximum number of bytes for incoming JSON that the server +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 +calulcated 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 conneciton to this relay. It's possible +that authenticated clients with a (paid) relationship to the server +may have higher limits. + +- `max_filters`: maximum number of filter values per each subscription. +Must be one or higher. + +- `subid_length`: maximum length of subscription id as a string. + +As Nostr expands and develops, expect to see additional items added here. + + +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 the `null` value indicating +infinity. If zero is provided, this means the event will not be +stored at all, and preferably and error would be provided when those +are received. + +```json +{ +... + retention: { + default: 3600, + by_kind: { 0: null, 2: null, 3: null, 4: 172800 }, + } +... +} +``` + +- the `default` is recommended, and indicated the retention time if not specified elsewhere. +- `by_kind` is a dictionary mapping KIND values to their retention time. The example given +indicates that per-pubkey metadata will be store forever, and private DM's will be saved +for two days. + +It is possible to effectively blacklist Nostr-based protocols that rely on +a specific KIND number, by using 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. + + +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. + +Remember that a relay may be hosted in a country which is not the +country of the legal entities who own the server, so it's very +likely a number of countries are involved. + + +Community Preferences +--------------------- + +For public text notes at least, a relay server may try to foster a +local community. This would encourge users to follow the global +feed on that relay, in addition to their usual individual follows. +To support this goal, relays MAY specific some of the following values. + +```json +{ +... + language_tags: [ 'en', 'en-419' ], + only_sfw: True, + 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. +- `only_swf` is an boolean that only "Safe For Work" content is encouraged on this + server. This is relies on assumptions of what the "work" "community" feels + "safe" talking about. +- `posting_policy` is a link to a human-readable page which specifies the + community policies for the server. In cases where `only_sfw` is True, it's + important to link to a page which gets into the specifics of your posting policy. + + From 53af4d302dc80572cda3701cb7fa1bc0c5defd97 Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Mon, 9 Jan 2023 14:42:17 -0500 Subject: [PATCH 2/9] more --- 111.md | 74 ++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 30 deletions(-) diff --git a/111.md b/111.md index 3e8d3b5bab..8e555e1f38 100644 --- a/111.md +++ b/111.md @@ -6,13 +6,13 @@ Addition Relay Information for NIP-11 `draft` `optional` `author:doc-hex` -Relays may provide addition 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 defined by [NIP-11](11.md). All are optional -and may be omitted. +Relays may provide addition 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 the examples here, are merely examples -and do not consituite a default value or expectation. The purpose +All numbers and values show in theses examples, are merely _examples_ +and do not constitute a default value or expectation. The purpose of this NIP is to allow clients to directly discover the actual values chosen by the relay operators. @@ -30,10 +30,10 @@ of the same response. } ``` -Server Limitiations -------------------- +Server Limitations +------------------ -These are limitations imposed by the server on clients. Your client +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. @@ -44,29 +44,38 @@ are rejected or fail immediately. max_raw_json: 16384, max_subscriptions: 20, max_filters: 100, + max_limit: 5000, subid_length: 100, + min_prefix: 4, } ... } ``` -- `max_raw_json`: this is the maximum number of bytes for incoming JSON that the server +- `max_raw_json`: 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 -calulcated from `[` to `]` and is after UTF-8 serialization (so some unicode characters +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 conneciton to this relay. It's possible -that authenticated clients with a (paid) relationship to the server +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 per each subscription. +- `max_filters`: maximum number of filter values in each subscription. Must be one or higher. - `subid_length`: maximum length of subscription id as a string. -As Nostr expands and develops, expect to see additional items added here. +- `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. Event Retention @@ -77,10 +86,9 @@ 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 the `null` value indicating -infinity. If zero is provided, this means the event will not be -stored at all, and preferably and error would be provided when those -are received. +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 { @@ -93,15 +101,18 @@ are received. } ``` -- the `default` is recommended, and indicated the retention time if not specified elsewhere. -- `by_kind` is a dictionary mapping KIND values to their retention time. The example given +- `default` is normal retention time for any event, if not overriden by other fields. +- `by_kind` is a dictionary mapping `kind` values to their retention time. The example given indicates that per-pubkey metadata will be store forever, and private DM's will be saved for two days. It is possible to effectively blacklist Nostr-based protocols that rely on -a specific KIND number, by using a retention time of zero for those KIND values. +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. +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 @@ -131,20 +142,20 @@ flexibility is up to the client software. ``` - `relay_countries`: a list of two-level ISO country codes (ISO 3166-1 alpha-2) whose - laws and policies may affect this relay. + 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 server, so it's very +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 server may try to foster a -local community. This would encourge users to follow the global +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 specific some of the following values. +To support this goal, relays MAY specify some of the following values. ```json { @@ -160,10 +171,13 @@ To support this goal, relays MAY specific some of the following values. of [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag) indicating the major languages spoken on the relay. - `only_swf` is an boolean that only "Safe For Work" content is encouraged on this - server. This is relies on assumptions of what the "work" "community" feels + relay. This relies on assumptions of what the "work" "community" feels "safe" talking about. - `posting_policy` is a link to a human-readable page which specifies the - community policies for the server. In cases where `only_sfw` is True, it's + community policies for the relay. In cases where `only_sfw` is True, it's important to link to a page which gets into the specifics of your posting policy. +The existing NIP-11 field `description`, should be used to describe +your community goals and values, in brief. The `posting_policy` is +for more additional detail. From 6b3038f4cf049324f075a117aa87a354afc62524 Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Fri, 20 Jan 2023 09:54:54 -0500 Subject: [PATCH 3/9] response to feedback --- 111.md | 66 ++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 43 insertions(+), 23 deletions(-) diff --git a/111.md b/111.md index 8e555e1f38..7fc6498106 100644 --- a/111.md +++ b/111.md @@ -1,18 +1,18 @@ NIP-111 ======= -Addition Relay Information for NIP-11 -------------------------------------- +Additional Relay Information for NIP-11 +--------------------------------------- `draft` `optional` `author:doc-hex` -Relays may provide addition metadata to clients to inform them of +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 a default value or expectation. The purpose +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. @@ -41,18 +41,20 @@ are rejected or fail immediately. { ... limitation: { - max_raw_json: 16384, + max_message_length: 16384, max_subscriptions: 20, max_filters: 100, max_limit: 5000, - subid_length: 100, + max_subid_length: 100, min_prefix: 4, + min_pow_difficulty: 30, + auth_required: True, } ... } ``` -- `max_raw_json`: this is the maximum number of bytes for incoming JSON that the relay +- `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 @@ -66,7 +68,7 @@ may have higher limits. - `max_filters`: maximum number of filter values in each subscription. Must be one or higher. -- `subid_length`: maximum length of subscription id as a string. +- `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. @@ -77,6 +79,13 @@ of events from a single subscription filter. This clamping is typically done sil 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. +- `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. + Event Retention --------------- @@ -93,18 +102,20 @@ all, and preferably an error will be provided when those are received. ```json { ... - retention: { - default: 3600, - by_kind: { 0: null, 2: null, 3: null, 4: 172800 }, - } + retention: [ + { kinds: [0, 1, [5, 7], [40, 49]], time: 3600 }, + { kinds: [[40000, 49999], time: 100 }, + { kinds: [[30000, 39999], count: 1000 }, + { time: 3600, count: 10000 } + ] ... } ``` -- `default` is normal retention time for any event, if not overriden by other fields. -- `by_kind` is a dictionary mapping `kind` values to their retention time. The example given -indicates that per-pubkey metadata will be store forever, and private DM's will be saved -for two days. +`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. @@ -161,7 +172,7 @@ To support this goal, relays MAY specify some of the following values. { ... language_tags: [ 'en', 'en-419' ], - only_sfw: True, + tags: [ 'sfw-only', 'bitcoin-only', 'anime' ], posting_policy: 'https://example.com/posting-policy.html', ... } @@ -170,14 +181,23 @@ To support this goal, relays MAY specify some of the following values. - `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. -- `only_swf` is an boolean that only "Safe For Work" content is encouraged on this - relay. This relies on assumptions of what the "work" "community" feels - "safe" talking about. + +- `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 `only_sfw` is True, it's important to link to a page which gets into the specifics of your posting policy. -The existing NIP-11 field `description`, should be used to describe -your community goals and values, in brief. The `posting_policy` is -for more additional detail. +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. From 27ba498d7da1f9b2b52de984e8e729ca5175ebee Mon Sep 17 00:00:00 2001 From: "Peter D. Gray" Date: Fri, 20 Jan 2023 10:09:30 -0500 Subject: [PATCH 4/9] two more limitations --- 111.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/111.md b/111.md index 7fc6498106..de82f7cb51 100644 --- a/111.md +++ b/111.md @@ -47,6 +47,8 @@ are rejected or fail immediately. 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, } @@ -79,6 +81,13 @@ of events from a single subscription filter. This clamping is typically done sil 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. From fa2e20a2d139f35eadf1d645f3946e15bc685848 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20Arturo=20Cabral=20Mej=C3=ADa?= Date: Sun, 12 Feb 2023 06:57:18 -0800 Subject: [PATCH 5/9] Update 111.md Co-authored-by: Semisol <45574030+Semisol@users.noreply.github.com> --- 111.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/111.md b/111.md index de82f7cb51..5de84cca52 100644 --- a/111.md +++ b/111.md @@ -1,10 +1,10 @@ -NIP-111 +NIP-11a ======= Additional Relay Information for NIP-11 --------------------------------------- -`draft` `optional` `author:doc-hex` +`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 From 0fddcd20a71c0ab93df0f8a1e0167dc810068b4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20Arturo=20Cabral=20Mej=C3=ADa?= Date: Sun, 12 Feb 2023 06:59:00 -0800 Subject: [PATCH 6/9] Update 111.md --- 111.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/111.md b/111.md index 5de84cca52..a2976aef08 100644 --- a/111.md +++ b/111.md @@ -50,7 +50,8 @@ are rejected or fail immediately. max_event_tags: 100, max_content_length: 8196, min_pow_difficulty: 30, - auth_required: True, + auth_required: true, + payment_required: true, } ... } From 5b7eef131df31813ef2eb046af75fc17901eb3a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20Arturo=20Cabral=20Mej=C3=ADa?= Date: Sun, 12 Feb 2023 06:59:41 -0800 Subject: [PATCH 7/9] Update 111.md --- 111.md | 1 + 1 file changed, 1 insertion(+) diff --git a/111.md b/111.md index a2976aef08..89719157b5 100644 --- a/111.md +++ b/111.md @@ -96,6 +96,7 @@ based on [NIP-13](13.md), or they will be rejected by this server. 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 --------------- From 5f9aa2fc147add793cd85b08ce9f3c2e50ff05bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20Arturo=20Cabral=20Mej=C3=ADa?= Date: Sun, 12 Feb 2023 07:00:29 -0800 Subject: [PATCH 8/9] Update 111.md --- 111.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/111.md b/111.md index 89719157b5..1fb9561c54 100644 --- a/111.md +++ b/111.md @@ -211,4 +211,19 @@ 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' }], + }, +... +} From c6b8e9c15bf6611d4648635797450607a4171205 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ricardo=20Arturo=20Cabral=20Mej=C3=ADa?= Date: Sun, 12 Feb 2023 07:00:44 -0800 Subject: [PATCH 9/9] Update 111.md --- 111.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/111.md b/111.md index 1fb9561c54..5d8f4eee35 100644 --- a/111.md +++ b/111.md @@ -203,7 +203,7 @@ To support this goal, relays MAY specify some of the following values. 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 `only_sfw` is True, it's + 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