nostr/nips
1
0
Fork 0
mirror of https://github.com/nostr-protocol/nips.git synced 2024-12-23 00:45:53 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

dec-23 update

Browse Source
This commit is contained in:
dskvr 2023-12-27 13:55:16 +01:00
parent 71bd3a0a8f
commit 956f8251ac
1 changed files with 133 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

247
66.md
View File

@ -2,7 +2,7 @@
`draft` `optional` `draft` `optional`
This NIP defines two event kinds, `30066` and `10066`. This NIP defines three event kinds, `10066`, `30066` and `1066`.
## `10066`: "Relay Monitor" Events ## `10066`: "Relay Monitor" Events
@ -17,31 +17,42 @@ To provide a directory of monitors, their intent to publish, their criteria and
- `"url" == tagUrl[0]` A URL with human readable information about the monitor's activities. If not included, it is assumed these details are included in the monitor's kind 0 for the pubkey that signed the `10066` event. - `"url" == tagUrl[0]` A URL with human readable information about the monitor's activities. If not included, it is assumed these details are included in the monitor's kind 0 for the pubkey that signed the `10066` event.
- `"timeout" == tagTimeout[0]` The timeout values for various tests. `tagTimeout[1]` is the monitor's timeout in milliseconds. `tagTimeout[2]` describes what test the timeout is used for, for example `open`, `read`, `write`, `info`, etc. If no `tagTimeout[2]` is provided, it is assumed the timeout provided applies to all tests. - `"timeout" == tagTimeout[0]` The timeout values for various tests. `tagTimeout[1]` is the monitor's timeout in milliseconds. `tagTimeout[2]` describes what test the timeout is used for, for example `open`, `read`, `write`, `info`, etc. If no `tagTimeout[2]` is provided, it is inferred that the timeout provided applies to all tests.
```
[ "timeout", "2000", "open" ]
[ "timeout", "2000", "read" ]
[ "timeout", "3000", "write" ]
[ "timeout", "2000", "info" ]
```
- `"frequency" == tagFrequency[0]` The frequency at which the monitor publishes 30066 events. - `"kind === tagKind[0]"` The kind(s) this monitor publishes.
```
[ "kind", "30066" ]
[ "kind", "1066" ]
```
- `"frequency" == tagFrequency[0]` The frequency at which the monitor publishes events. A string-integer at `tagFrequency[1]` represents the frequency a event kind is published. The string-integer at `tagFrequency[2]` represents the kind bound to the frequency. If `tagFrequency[2]` is undefined, it is inferred the timeout applies to all events published by the monitor. A frequency **should not** be created for this kind [`1006`]. If a kind is referenced in `tagFrequency` that is not set in `tagKind` it should be disregarded.
```
[ "frequency", "3600", "30066" ]
[ "frequency", "3600", "1066" ]
```
#### Label Tags <sup>NIP-32</sup> #### Label Tags <sup>NIP-32</sup>
- `role`, for example: `checker` or `aggregator` - `checks` **should** be a lowercase string describing the check(s) conducted by a monitor. Some examples are: `websocket`, `nip11`, `ssl`, `dns`, `geo`
_Checks but doesn't aggregate relay lists_
```
[ 'L', 'role' ]
[ 'l', 'checker', 'role' ]
```
- `checks`, should be a lowercase string describing the individual check if role is `checker`. Some examples are: `websocket`, `nip11`, `ssl`, `dns`, `geo`
``` ```
[ 'L', 'checks' ] [ "L", "checks" ]
[ 'l', 'websocket', 'checks' ] [ "l", "websocket", "checks" ]
[ 'l', 'nip11', 'checks' ] [ "l", "nip11", "checks" ]
[ 'l', 'ssl', 'checks' ] [ "l", "ssl", "checks" ]
[ 'l', 'dns', 'checks' ] [ "l", "dns", "checks" ]
[ 'l', 'geo', 'checks' ] [ "l", "geo", "checks" ]
``` ```
#### Geo tags <sup>NIP-YAGT</sup>
- `NIP-66` leverages a draft NIP for geo tags, see [YAGT](https://github.com/nostr-protocol/nips/pull/952)
### Other Requirements ### Other Requirements
- Monitors **should** have a published `10002` event that defines the relays the monitor publishes to. - Monitors **should** have a published `10002` event that defines the relays the monitor publishes to.
@ -49,16 +60,15 @@ To provide a directory of monitors, their intent to publish, their criteria and
### Summary ### Summary
`30066` is a parameterized replaceable event [NIP-33], referred to as a "Relay" event. These events store the existence and optionally some data relating to the relay. `30066` is a parameterized replaceable event [NIP-33], referred to as a "Relay" event. These events store the existence and optionally some data relating to the relay.
a
### Purpose
To store useful, computationally expensive relay meta-data about relays.
### Purpose
To store useful, computationally expensive relay meta-data about relays. `30066` should be used to give a canonical reference to the last known functional state of a relay, to be evaluated subjectively by a client and/or user to derive conclusions from.
### NIPs Used ### NIPs Used
- `NIP-32` Labels - `NIP-32` Labels
- `NIP-33` Parameterized Replacable Events - `NIP-33` Parameterized Replacable Events
- `NIP-40` Expirable Events - `NIP-40` Expirable Events
- "Yet Another Geo Tag" NIP (Draft) - [YAGT](https://github.com/nostr-protocol/nips/pull/952) _draft_
### Schema ### Schema
@ -68,22 +78,36 @@ To store useful, computationally expensive relay meta-data about relays.
#### `event.tags` #### `event.tags`
Relay status events have **one** (1) required tag. Relay status events have **one** (1) required tag.
Relay status events have **two** (2) non-standard, NIP-66 specific indexable tags.
Tags should be used to represent the Relay's abilities and meta at any given point in time. The "tags schema" is expressed using pseudo-types for reasons of communication and brevity, for example `tagDescriptor[]`. This NIP utilizes `NIP-32` to expose indexable values. Tags should be used to represent the Relay's abilities and meta at any given point in time. The "tags schema" is expressed using pseudo-types for reasons of communication and brevity, for example `tagDescriptor[]`. This NIP utilizes `NIP-32` to expose indexable values.
#### Tags #### Tags
- `"d" == tagId[0]` The relay URL. The `#d` tag **must** be included in the `event.tags[]` array. `tagId[1]` **must** be the relay websocket URL. The URL **should** be normalized. - `"d" == tagId[0]` The relay URL. The `#d` tag **must** be included in the `event.tags[]` array. `tagId[1]` **must** be the relay websocket URL. The URL **should** be [normalized](https://datatracker.ietf.org/doc/html/rfc3986#section-6)
``` ```
["d", "wss://history.nostr.watch/"] //tagId[] ["d", "wss://history.nostr.watch/"] //tagId[]
``` ```
- `"rtt-*" == tagRtt[0]` Round-trip time of websocket ping/pong in milliseconds. Example values for `tagRtt[1]` are `open`, `read` and `write`. Where `open` represents the round-trip time forWebsocket to open, `read` represents the round-trip time of a Websocket `REQ` (subscription) message's response, and `write` represents the round-trip time of a Websocket `EVENT` (publish) message and subsequent `ok` message. `tagRtt[2...]` are strings with the millisecond values. At a minimum `tagRtt[2]` **should** be set. When more than one value is provided, values **may** be treated as an array to find `min`, `max`, `average` and `median` values. There **may** be zero `rtt` tags. - `n`: Such as `clearnet`, `tor`, `i2p`, `cjdns`, etc _in the context of **NIP-66 only**_
```
[ "n", "clearnet" ]
```
- `N`: Supported NIPs _in the context of **NIP-66 only**_
```
[ "N", "1" ]
[ "N", "11" ]
[ "N", "33" ]
```
- `"rtt" == tagRtt[0]` Round-trip time of websocket ping/pong in milliseconds. Example values for `tagRtt[1]` are `open`, `read` and `write`. Where `open` represents the round-trip time forWebsocket to open, `read` represents the round-trip time of a Websocket `REQ` (subscription) message's response, and `write` represents the round-trip time of a Websocket `EVENT` (publish) message and subsequent `ok` message. `tagRtt[2...]` are strings with the millisecond values. At a minimum `tagRtt[2]` **should** be set. When more than one value is provided, values **may** be treated as an array to find `min`, `max`, `average` and `median` values. There **may** be zero `rtt` tags.
``` ```
["rtt", "open", "201", "190", "540"], ["rtt", "open", "201", "190", "540"],
["rtt", "read", "35", "60", "46"], ["rtt", "read", "35", "60", "46"],
["rtt", "write", "701", "497", "508"] ["rtt", "write", "701", "497", "508"]
``` ```
- `"count" == tagCount[0]` Meta values for arbitrary counts related to a relay. `tagCount[1]` is the value expressed as the string representation of an integer or float. `tagCount[2]` is the key and describes the count, such as `total_users` or `total_events`. Counts **should** only be included when representing unique or computationally expensive counts, not ones that can be easily achieved via NIP-XX counts, via NIP-XX searches or other filters. There **may** be zero (0) to many count tags.
- `"count" == tagCount[0]` Meta values for arbitrary counts related to a relay. `tagCount[1]` is the value expressed as the string representation of an integer or float. `tagCount[2]` is the key and describes the count, such as `total_users` or `total_events`. Counts **should** only be included when representing unique or computationally expensive counts, not ones that can be easily achieved via NIP-XX counts, via NIP-XX searches or other filters. There **may** be **0** to **many** count tags.
``` ```
["count", "total_events", "502341"], ["count", "total_events", "502341"],
["count", "total_users", "52000"], ["count", "total_users", "52000"],
@ -92,80 +116,98 @@ Tags should be used to represent the Relay's abilities and meta at any given poi
``` ```
- `"infohash" == tagInfohash[0]` A SHA256 hash of the deterministically stringified `NIP-11` "Info Document" JSON at `tagInfohash[1]` - `"infohash" == tagInfohash[0]` A SHA256 hash of the deterministically stringified `NIP-11` "Info Document" JSON at `tagInfohash[1]`
```
[ "infohash", "fj89as0n3inmcd89nefkdlsky2mfkdlsfds" ]
```
- `"notice" == tagNotice[0]` Special tag to display information about a relay. `tagNotice[1]` is a key to describe the notice. `tagNotice[2...]` **should** be the value(s) of the notice. There **may** be **0** to **many** notice tags. - `"e" === tagE[0]` An association to another standard nostr event (`0/1/2/4-9999` kind-range). An example would be an event containing the most recent check log or an archival event representing the check. Such a reference may contain duplicate or ommitted tags from a `30066` event.
- `"expiration" === tagE[0]` An expiration timestamp to forcefully limit retention of relay events [`NIP-40`] - `"a" === tagE[0]` An association to another replaceable nostr event. An example would be an event containing the most recent check log or an archival event representing the check. Such a reference may contain duplicate or ommitted tags from a `30066` event.
- `"e" === tagE[0]` An association to another standard nostr event (`1000-9999` kind-range). An example would be an event containing the most recent check log or an archival event representing the check. Such a reference may contain duplicate or ommitted tags from a `30066` event. The event referenced here **should** at a minimum be described in a draft NIP.
#### Label Tags <sup>NIP-32</sup> #### Label Tags <sup>NIP-32</sup>
- `relay_type`, for example `proxy`, `bridge` and `public` for example. There **may** be more than one type. There have not been efforts to atomize relay types at the time of writing this NIPs, so these values cannot be enumerated at this time.
- `network`: Such as `clearnet`, `tor`, `i2p`, `cjdns`, etc.
``` ```
[ 'L', 'network' ] [ "L", "relay_type" ]
[ 'l', 'clearnet', 'network' ] [ "l", "proxy", "relay_type" ]
[ "l", "public", "relay_type" ]
``` ```
- `relay_type`, for example `proxy`, `bridge` and `public` for example. There **may** be more than one type. - `ipv4`/`ipv6`, relay ips.
``` ```
[ 'L', 'relay_type' ] [ "L", "ipv4" ]
[ 'l', 'proxy', 'relay_type' ] [ "l", "1.1.1.1", "ipv4" ]
[ 'l', 'public', 'relay_type' ] [ "L", "ipv6" ]
[ "l", "2001:db8:3333:4444:5555:6666:7777:8888"", "ipv6" ]
``` ```
- `ipv4` and `ipv6`, relay ips. - `as`/`asn` the relay ISPs "Autonomous System (Number)"
``` ```
[ 'L', 'ipv4' ] [ "as", "QUAD9-AS-1, CH" ]
[ 'l', '1.1.1.1', 'ipv4' ] [ "asn", "19281" ]
[ 'L', 'ipv6' ]
[ 'l', '2001:db8:3333:4444:5555:6666:7777:8888"', 'ipv6' ]
``` ```
- Data from `NIP-11` using dot notation, for example - String values from `NIP-11` using dot notation, for example
``` ```
[ 'L', 'nip11.tags' ] [ "L", "nip11.tags" ]
[ 'l', 'sfw-only' ] [ "l", "sfw-only" ]
[ 'l', 'bitcoin-only' ] [ "l", "bitcoin-only" ]
[ 'L', 'nip11.language_tags' ] [ "L", "nip11.language_tags" ]
[ 'l', 'en', 'nip11.language_tags' ] [ "l", "en", "nip11.language_tags" ]
[ 'l', 'en-419', 'nip11.language_tags' ] [ "l", "en-419", "nip11.language_tags" ]
[ "L", "nip11.limitations" ]
```
- Boolean values from `NIP-11`, for example
```
[ "L", "nip11.limitations" ]
[ "l", "payment_required", "nip11.limitations" ] //nip11.limitations.payment_required==true
[ "l", "auth_required", "nip11.limitations" ] //nip11.limitations.auth_required==true
```
#### Geo tags <sup>NIP-YAGT</sup>
- `NIP-66` leverages a draft NIP for geo tags, see [YAGT](https://github.com/nostr-protocol/nips/pull/952)
```
[ 'G', 'countryCode' ]
[ 'g', 'US', 'countryCode', 'alpha-2' ]
[ 'g', 'USA', 'countryCode', 'alpha-3' ]
[ 'g', '840', 'countryCode', 'numeric' ]
[ 'G', 'regionCode' ]
[ 'g', 'US-CA', 'regionCode']
[ 'g', '9r1652whz' ]
[ 'g', '9r1652wh' ]
[ 'g', '9r1652w' ]
[ 'g', '9r1652' ]
[ 'g', '9r165' ]
[ 'g', '9r16' ]
[ 'g', '9r1' ]
[ 'g', '9r' ]
[ 'g', '9' ]
``` ```
#### Topic Tags #### Topic Tags
`NIP-66` leverages topics [`t` tags] for enumeration of nip support and NIP-11 boolean values - `NIP-66` leverages topics [`t` tags] and optionally adds values at positions `tag[2]` and `tag[3]`. If `tag[2]` is set, it **should** be a string-integer representing the number of tags on the relay. If `tag[2]` is set, `tag[3]` **should** be set and be a string-integer representing the timeframe for the value set as `tag[2]`. This tag is used to indicate topics relevant to the relay through event analysis (as oppossed to 'tags' from `NIP-11` document)
- `supported_nips` from `NIP-11`, no leading zero.
``` ```
[ 't', 'nip-1' ] //69 events with "meme" topic in the last hour
[ 't', 'nip-2' ] ["t", "meme", "69", "3600"]
[ 't', 'nip-9' ]
[ 't', 'nip-11' ]
```
- For example `payment_required` and `auth_required` from `NIP-11.limitations`
```
[ 't', 'payment_required' ]
[ 't', 'auth_required' ]
``` ```
#### Methodology #### Methodology
A Checking Monitor publishes 30066 events exclusively when a relay is operational. This approach ensures that the last known state of the relay is maintained and recorded. Based on this data, several inferences can be drawn about the relay's status and characteristics A Checking Monitor publishes 30066 events exclusively when a relay is operational. This approach ensures that the last known active state of the relay is maintained and recorded. Based on this data, several inferences can be drawn about the relay's status and characteristics
1. Clients and/or users can set a custom threshold to establish a cutoff timestamp for filtering events. This timestamp helps in identifying which relays are currently online. Selecting a lower threshold value results in a stricter criterion for relay uptime, making the filter more sensitive to brief downtimes. Conversely, choosing a higher threshold value creates a more lenient filter, allowing relays with longer downtimes to still be considered as online. 1. Clients and/or users can set a custom threshold to establish a cutoff timestamp for filtering events using `since`. This timestamp helps in identifying which relays are currently online. Selecting a lower threshold value results in a stricter criterion for relay uptime, making the filter more sensitive to brief downtimes. Conversely, choosing a higher threshold value creates a more lenient filter, allowing relays with longer downtimes to still be considered as online.
2. In determining whether a relay is 'dead,' the decision is solely at the discretion of the client or user. They are responsible for setting and applying arbitrary thresholds to make this determination. This approach underscores that the classification of a relay as 'dead' is a subjective decision, varying according to each client's or user's assessment criteria, rather than a fixed status provided by the monitor. 2. In determining whether a relay is 'dead,' the decision is solely at the discretion of the client or user. The are responsible for setting and applying arbitrary thresholds using `until` filters to make this determination. This approach underscores that the classification of a relay as 'dead' is a subjective decision, varying according to each client's or user's assessment criteria, rather than a fixed status provided by the monitor.
3. For relay status events that have become outdated, the retained data points remain valuable. They offer insights and information about the relay's characteristics and performance, which might not be currently accessible due to the relay being offline. 3. For relay status events that have become outdated, the retained data points remain valuable. They offer insights and information about the relay's characteristics and performance, which might not be currently accessible due to the relay being offline.
#### Important Notes #### Important Notes
- `NIP-11` values are provided as means to filter and discover relays, however **should not** be used as a replacement to `NIP-11`. - `NIP-11` values are provided as means to filter and discover relays, however **should not** be used as a replacement to `NIP-11`.
- A relay's retention policy could conflict with subjective thresholds used in determination of "online" or "dead" relays. - A particular relay's retention policy could conflict with subjective thresholds used in determination of "online" or "dead" relays and so care should be taken with regards to chosen relays by both monitors and consumers.
#### Examples #### Examples
##### Minimum Requirements, "Relay was on a relay list" ##### Minimum Requirements, "Relay was online at `Date(created_at)`"
```json ```json
{ {
"id": "<eventid>", "id": "<eventid>",
@ -179,21 +221,6 @@ A Checking Monitor publishes 30066 events exclusively when a relay is operationa
} }
``` ```
##### Minimum Requirements, "Relay was on a list but it might be a typo"
```json
{
"id": "<eventid>",
"pubkey": "<pubkey>",
"created_at": "<created_at>",
"signature": "<signature>",
"content": "",
"tags": [
["d","wdd://some.relay/"]
["notice", "typo", "wss://some.relay/"]
]
}
```
##### Relay is checked and online example, "Relay is online and here's some meta-data this monitor believes is accurate" ##### Relay is checked and online example, "Relay is online and here's some meta-data this monitor believes is accurate"
```json ```json
{ {
@ -212,44 +239,23 @@ A Checking Monitor publishes 30066 events exclusively when a relay is operationa
["count", "21.4", "events_per_minute"], ["count", "21.4", "events_per_minute"],
["L", "network"] ["L", "network"]
["l", "clearnet", "network"] ["l", "clearnet", "network"]
["g", "ww8p1r4t8","geohash"], ["g", "ww8p1r4t8"],
["g","NL","countryCode"], ["g", "NL", "countryCode", "alpha-2"],
["g","EU","continent"], ["L", "ipv4"],
["g","Earth","planet"], ["l", "1.1.1.1""ipv4" ],
["L","ipv4"], ["L", "ipv6"],
["l","1.1.1.1""ipv4" ], ["l", "2001:db8:3333:4444:5555:6666:7777:8888","ipv6"],
["L","ipv6"],
["l","2001:db8:3333:4444:5555:6666:7777:8888","ipv6"],
["t", "nip-1"], ["t", "nip-1"],
["t", "nip-7"] ["t", "nip-7"]
] ]
} }
``` ```
##### Relay was checked and has been online, "Relay was online at _some_ point..."
```json
{
"id": "<eventid>",
"pubkey": "<monitor's pubkey>",
"created_at": "<created_at [some date in the distant past...]>",
"signature": "<signature>",
"content": "",
"tags": [
["d","wss://some.relay/"],
["rtt", "open", "201", "190", "540"],
["rtt", "read", "35", "60", "46"],
["rtt", "write", "701", "497", "508"],
...
]
}
```
#### Testing Criteria #### Testing Criteria
The testing criteria to determine conditions defined in event's tags **may** be subjective and **may** vary between monitors. The testing criteria to determine conditions defined in event's tags **may** be subjective and **may** vary between monitors.
#### Limitations #### Limitations
The data in `30066` **may** be erroneous, intentionally or otherwise. Where accuracy is required, the data in `30066` events **should** be subscribed to by populating the `authors` filter array with the pubkeys of trusted **monitors** and where security is a concern any republished values (such as NIP-11 values) should be attained from the source. All data is for informational purposes and to make finding and filtering through relays through nostr a possiblity. The data in `30066` **may** be erroneous, intentionally or otherwise. Where accuracy is required, the data in `30066` events **should** be subscribed to by populating the `authors` filter array with the pubkeys of trusted **monitors** and where security or privacy is a concern any republished values (such as NIP-11 values) should instead be attained from the source. All data is for informational purposes and to make finding and filtering through relays through nostr a possiblity.
#### Appending NIP-66 #### Appending NIP-66
Any test results that cannot be expressed through `NIP-66` **should** be ammended to the nip following discussion and general consensus Any test results that cannot be expressed through `NIP-66` **should** be ammended to the nip following discussion and general consensus
@ -273,9 +279,22 @@ Any test results that cannot be expressed through `NIP-66` **should** be ammende
9. **Language and Content Filtering**: Identify relays catering to specific languages or content types, enabling users to engage in a more targeted and relevant social networking experience. 9. **Language and Content Filtering**: Identify relays catering to specific languages or content types, enabling users to engage in a more targeted and relevant social networking experience.
10. **Data-Driven Relay Selection**: Make informed choices about which relays to connect to, based on comprehensive metadata including user counts, event frequencies, and network types. 10. **Data-Driven Relay Selection**: Make informed choices about which relays to connect to, based on comprehensive metadata including user counts, event frequencies, network types and more.
## `1066`: "Relay Status History" Events
# Glossary ### Summary
- `aggregate` the act of aggregating, qualifying, sanitizing and normalizing relays from relay lists to build a subjectively complete dataset of known relays. `1066` is a standard nostr event, referred to as a "Relay Status History" event. These events store the history of a relay at a periodic interval (defined in `10066`).
- `check` the act of running tests on one or many attributes of a relay.
#### Schema
Relay History events can contain any of the tags defined for kind `30066` (Including the `d` tag which is used to filter these events by relay). There is one new indexable tag
#### Special Considerations
- These events can potentially store a lot of data.
#### Guidelines
Tags containd with this event should only be included when their values have changed compared to the last event. If there have been no changes, then the event should not be published.
##### Use Cases
- Generate a time series from one or many data-point(s) for a specific relay.
- Generate network-wide aggregated statistics