diff --git a/01.md b/01.md index ae138246..70218ccd 100644 --- a/01.md +++ b/01.md @@ -1,8 +1,6 @@ -NIP-01 -====== +# NIP-01 -Basic protocol flow description -------------------------------- +## Basic protocol flow description `draft` `mandatory` `author:fiatjaf` `author:distbit` `author:scsibug` `author:kukks` `author:jb55` `author:semisol` @@ -51,9 +49,9 @@ Relays expose a websocket endpoint to which clients can connect. Clients can send 3 types of messages, which must be JSON arrays, according to the following patterns: - * `["EVENT", ]`, used to publish events. - * `["REQ", , ...]`, used to request events and subscribe to new updates. - * `["CLOSE", ]`, used to stop previous subscriptions. +- `["EVENT", ]`, used to publish events. +- `["REQ", , ...]`, used to request events and subscribe to new updates. +- `["CLOSE", ]`, used to stop previous subscriptions. `` is an arbitrary, non-empty string of max length 64 chars, that should be used to represent a subscription. @@ -88,9 +86,9 @@ The `limit` property of a filter is only valid for the initial query and can be Relays can send 3 types of messages, which must also be JSON arrays, according to the following patterns: - * `["EVENT", , ]`, used to send events requested by clients. - * `["EOSE", ]`, used to indicate the _end of stored events_ and the beginning of events newly received in real-time. - * `["NOTICE", ]`, used to send human-readable error messages or other things to clients. +- `["EVENT", , ]`, used to send events requested by clients. +- `["EOSE", ]`, used to indicate the _end of stored events_ and the beginning of events newly received in real-time. +- `["NOTICE", ]`, used to send human-readable error messages or other things to clients. This NIP defines no rules for how `NOTICE` messages should be sent or treated. @@ -98,14 +96,14 @@ This NIP defines no rules for how `NOTICE` messages should be sent or treated. ## Basic Event Kinds - - `0`: `set_metadata`: the `content` is set to a stringified JSON object `{name: , about: , picture: }` describing the user who created the event. A relay may delete past `set_metadata` events once it gets a new one for the same pubkey. - - `1`: `text_note`: the `content` is set to the plaintext content of a note (anything the user wants to say). Markdown links (`[]()` stuff) are not plaintext. - - `2`: `recommend_server`: the `content` is set to the URL (e.g., `wss://somerelay.com`) of a relay the event creator wants to recommend to its followers. +- `0`: `set_metadata`: the `content` is set to a stringified JSON object `{name: , about: , picture: }` describing the user who created the event. A relay may delete past `set_metadata` events once it gets a new one for the same pubkey. +- `1`: `text_note`: the `content` is set to the plaintext content of a note (anything the user wants to say). Markdown links (`[]()` stuff) are not plaintext. +- `2`: `recommend_server`: the `content` is set to the URL (e.g., `wss://somerelay.com`) of a relay the event creator wants to recommend to its followers. A relay may choose to treat different message kinds differently, and it may or may not choose to have a default way to handle kinds it doesn't know about. -## Other Notes: +## Other Notes - Clients should not open more than one websocket to each relay. One channel can support an unlimited number of subscriptions, so clients should do that. -- The `tags` array can store a tag identifier as the first element of each subarray, plus arbitrary information afterward (always as strings). This NIP defines `"p"` — meaning "pubkey", which points to a pubkey of someone that is referred to in the event —, and `"e"` — meaning "event", which points to the id of an event this event is quoting, replying to or referring to somehow. +- The `tags` array can store a tag identifier as the first element of each subarray, plus arbitrary information afterward (always as strings). This NIP defines `"p"` --- meaning "pubkey", which points to a pubkey of someone that is referred to in the event ---, and `"e"` --- meaning "event", which points to the id of an event this event is quoting, replying to or referring to somehow. - The `` item present on the `"e"` and `"p"` tags is an optional (could be set to `""`) URL of a relay the client could attempt to connect to fetch the tagged event or other events from a tagged profile. It MAY be ignored, but it exists to increase censorship resistance and make the spread of relay addresses more seamless across clients. diff --git a/02.md b/02.md index 2f199080..9f305eaf 100644 --- a/02.md +++ b/02.md @@ -1,8 +1,6 @@ -NIP-02 -====== +# NIP-02 -Contact List and Petnames -------------------------- +## Contact List and Petnames `final` `optional` `author:fiatjaf` `author:arcbtc` diff --git a/03.md b/03.md index 3c5d764e..f9249002 100644 --- a/03.md +++ b/03.md @@ -1,14 +1,12 @@ -NIP-03 -====== +# NIP-03 -OpenTimestamps Attestations for Events --------------------------------------- +## OpenTimestamps Attestations for Events `draft` `optional` `author:fiatjaf` When there is an OTS available it MAY be included in the existing event body under the `ots` key: -``` +```json { "id": ..., "kind": ..., @@ -18,6 +16,6 @@ When there is an OTS available it MAY be included in the existing event body und } ``` -The _event id_ MUST be used as the raw hash to be included in the OpenTimestamps merkle tree. +The _event id_ MUST be used as the raw hash to be included in the OpenTimestamps Merkle tree. -The attestation can be either provided by relays automatically (and the OTS binary contents just appended to the events it receives) or by clients themselves when they first upload the event to relays — and used by clients to show that an event is really "at least as old as [OTS date]". +The attestation can be either provided by relays automatically (and the OTS binary contents just appended to the events it receives) or by clients themselves when they first upload the event to relays --- and used by clients to show that an event is really "at least as old as [OTS date]". diff --git a/04.md b/04.md index 6e45b74b..fc89fa83 100644 --- a/04.md +++ b/04.md @@ -1,8 +1,6 @@ -NIP-04 -====== +# NIP-04 -Encrypted Direct Message ------------------------- +## Encrypted Direct Message `final` `optional` `author:arcbtc` diff --git a/05.md b/05.md index a7b42b06..37a67ec0 100644 --- a/05.md +++ b/05.md @@ -1,8 +1,6 @@ -NIP-05 -====== +# NIP-05 -Mapping Nostr keys to DNS-based internet identifiers ----------------------------------------------------- +## Mapping Nostr keys to DNS-based internet identifiers `final` `optional` `author:fiatjaf` `author:mikedilger` diff --git a/06.md b/06.md index 4ae571f7..7c9347d5 100644 --- a/06.md +++ b/06.md @@ -1,8 +1,6 @@ -NIP-06 -====== +# NIP-06 -Basic key derivation from mnemonic seed phrase ----------------------------------------------- +## Basic key derivation from mnemonic seed phrase `draft` `optional` `author:fiatjaf` diff --git a/07.md b/07.md index 3b7a1d29..d836b384 100644 --- a/07.md +++ b/07.md @@ -1,8 +1,6 @@ -NIP-07 -====== +# NIP-07 -`window.nostr` capability for web browsers ------------------------------------------- +## `window.nostr` capability for web browsers `draft` `optional` `author:fiatjaf` @@ -10,13 +8,14 @@ The `window.nostr` object may be made available by web browsers or extensions an That object must define the following methods: -``` +```javascript async window.nostr.getPublicKey(): string // returns a public key as hex async window.nostr.signEvent(event: Event): Event // takes an event object, adds `id`, `pubkey` and `sig` and returns it ``` Aside from these two basic above, the following functions can also be implemented optionally: -``` + +```javascript async window.nostr.getRelays(): { [url: string]: {read: boolean, write: boolean} } // returns a basic map of relay urls to relay policies async window.nostr.nip04.encrypt(pubkey, plaintext): string // returns ciphertext and iv as specified in nip-04 async window.nostr.nip04.decrypt(pubkey, ciphertext): string // takes ciphertext and iv as specified in nip-04 diff --git a/08.md b/08.md index fb87b536..a9412013 100644 --- a/08.md +++ b/08.md @@ -1,10 +1,8 @@ +# NIP-08 + > __Warning__ `unrecommended`: deprecated in favor of NIP-27 -NIP-08 -====== - -Handling Mentions ------------------ +## Handling Mentions `final` `unrecommended` `optional` `author:fiatjaf` `author:scsibug` diff --git a/09.md b/09.md index 89781fbf..e35d9daa 100644 --- a/09.md +++ b/09.md @@ -1,8 +1,6 @@ -NIP-09 -====== +# NIP-09 -Event Deletion --------------- +## Event Deletion `draft` `optional` `author:scsibug` @@ -14,7 +12,7 @@ The event's `content` field MAY contain a text note describing the reason for th For example: -``` +```json { "kind": 5, "pubkey": <32-bytes hex-encoded public key of the event creator>, diff --git a/10.md b/10.md index 64947967..1e665870 100644 --- a/10.md +++ b/10.md @@ -1,62 +1,66 @@ -NIP-10 -====== +# NIP-10 - -On "e" and "p" tags in Text Events (kind 1). --------------------------------------------- +## On "e" and "p" tags in Text Events (kind 1) `draft` `optional` `author:unclebobmartin` ## Abstract + This NIP describes how to use "e" and "p" tags in text events, especially those that are replies to other text events. It helps clients thread the replies into a tree rooted at the original event. ## Positional "e" tags (DEPRECATED) ->This scheme is in common use; but should be considered deprecated. + +> This scheme is in common use; but should be considered deprecated. `["e", , ]` as per NIP-01. Where: - * `` is the id of the event being referenced. - * `` is the URL of a recommended relay associated with the reference. Many clients treat this field as optional. - +- `` is the id of the event being referenced. +- `` is the URL of a recommended relay associated with the reference. Many clients treat this field as optional. + **The positions of the "e" tags within the event denote specific meanings as follows**: - * No "e" tag:
- This event is not a reply to, nor does it refer to, any other event. +- No "e" tag: - * One "e" tag:
- `["e", ]`: The id of the event to which this event is a reply. + This event is not a reply to, nor does it refer to, any other event. - * Two "e" tags: `["e", ]`, `["e", ]`
- `` is the id of the event at the root of the reply chain. `` is the id of the article to which this event is a reply. +- One "e" tag: - * Many "e" tags: `["e", ]` `["e", ]`, ..., `["e", ]`
-There may be any number of ``. These are the ids of events which may, or may not be in the reply chain. -They are citings from this event. `root-id` and `reply-id` are as above. + `["e", ]`: The id of the event to which this event is a reply. ->This scheme is deprecated because it creates ambiguities that are difficult, or impossible to resolve when an event references another but is not a reply. +- Two "e" tags: `["e", ]`, `["e", ]` + + `` is the id of the event at the root of the reply chain. `` is the id of the article to which this event is a reply. + +- Many "e" tags: `["e", ]` `["e", ]`, ..., `["e", ]` + + There may be any number of ``. These are the ids of events which may, or may not be in the reply chain. + They are citings from this event. `root-id` and `reply-id` are as above. + +> This scheme is deprecated because it creates ambiguities that are difficult, or impossible to resolve when an event references another but is not a reply. ## Marked "e" tags (PREFERRED) -`["e", , , ]` - + +`["e", , , ]` + Where: - * `` is the id of the event being referenced. - * `` is the URL of a recommended relay associated with the reference. Clients SHOULD add a valid `` field, but may instead leave it as `""`. - * `` is optional and if present is one of `"reply"`, `"root"`, or `"mention"`. +- `` is the id of the event being referenced. +- `` is the URL of a recommended relay associated with the reference. Clients SHOULD add a valid `` field, but may instead leave it as `""`. +- `` is optional and if present is one of `"reply"`, `"root"`, or `"mention"`. **The order of marked "e" tags is not relevant.** Those marked with `"reply"` denote the id of the reply event being responded to. Those marked with `"root"` denote the root id of the reply thread being responded to. For top level replies (those replying directly to the root event), only the `"root"` marker should be used. Those marked with `"mention"` denote a quoted or reposted event id. A direct reply to the root of a thread should have a single marked "e" tag of type "root". ->This scheme is preferred because it allows events to mention others without confusing them with `` or ``. - +> This scheme is preferred because it allows events to mention others without confusing them with `` or ``. ## The "p" tag + Used in a text event contains a list of pubkeys used to record who is involved in a reply thread. -When replying to a text event E the reply event's "p" tags should contain all of E's "p" tags as well as the `"pubkey"` of the event being replied to. +When replying to a text event E the reply event's "p" tags should contain all of E's "p" tags as well as the `"pubkey"` of the event being replied to. -Example: Given a text event authored by `a1` with "p" tags [`p1`, `p2`, `p3`] then the "p" tags of the reply should be [`a1`, `p1`, `p2`, `p3`] +Example: Given a text event authored by `a1` with "p" tags [`p1`, `p2`, `p3`] then the "p" tags of the reply should be [`a1`, `p1`, `p2`, `p3`] in no particular order. diff --git a/11.md b/11.md index a3773642..62ca2ae3 100644 --- a/11.md +++ b/11.md @@ -1,8 +1,6 @@ -NIP-11 -====== +# NIP-11 -Relay Information Document ---------------------------- +## Relay Information Document `draft` `optional` `author:scsibug` `author:doc-hex` `author:cameri` @@ -24,43 +22,41 @@ When a relay receives an HTTP(s) request with an `Accept` header of `application Any field may be omitted, and clients MUST ignore any additional fields they do not understand. Relays MUST accept CORS requests by sending `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers`, and `Access-Control-Allow-Methods` headers. -Field Descriptions ------------------ +## Field Descriptions -### Name ### +### Name A relay may select a `name` for use in client software. This is a string, and SHOULD be less than 30 characters to avoid client truncation. -### Description ### +### Description Detailed plain-text information about the relay may be contained in the `description` string. It is recommended that this contain no markup, formatting or line breaks for word wrapping, and simply use double newline characters to separate paragraphs. There are no limitations on length. -### Pubkey ### +### Pubkey An administrative contact may be listed with a `pubkey`, in the same format as Nostr events (32-byte hex for a `secp256k1` public key). If a contact is listed, this provides clients with a recommended address to send encrypted direct messages (See `NIP-04`) to a system administrator. Expected uses of this address are to report abuse or illegal content, file bug reports, or request other technical assistance. Relay operators have no obligation to respond to direct messages. -### Contact ### +### Contact An alternative contact may be listed under the `contact` field as well, with the same purpose as `pubkey`. Use of a Nostr public key and direct message SHOULD be preferred over this. Contents of this field SHOULD be a URI, using schemes such as `mailto` or `https` to provide users with a means of contact. -### Supported NIPs ### +### Supported NIPs As the Nostr protocol evolves, some functionality may only be available by relays that implement a specific `NIP`. This field is an array of the integer identifiers of `NIP`s that are implemented in the relay. Examples would include `1`, for `"NIP-01"` and `9`, for `"NIP-09"`. Client-side `NIPs` SHOULD NOT be advertised, and can be ignored by clients. -### Software ### +### Software The relay server implementation MAY be provided in the `software` attribute. If present, this MUST be a URL to the project's homepage. -### Version ### +### Version The relay MAY choose to publish its software version as a string attribute. The string format is defined by the relay implementation. It is recommended this be a version number or commit identifier. -Extra Fields ------------------ +## Extra Fields -### Server Limitations ### +### Server Limitations These are limitations imposed by the relay on clients. Your client should expect that requests which exceed these *practical* limitations @@ -127,9 +123,9 @@ 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 ### +### Event Retention -There may be a cost associated with storing data forever, so relays +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. @@ -151,7 +147,7 @@ all, and preferably an error will be provided when those are received. } ``` -`retention` is a list of specifications: each will apply to either all kinds, or +`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. @@ -161,11 +157,10 @@ a specific `kind` number, by giving a retention time of zero for those `kind` va 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 +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 ### +### 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 @@ -197,8 +192,7 @@ 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 ### +### 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 @@ -238,7 +232,7 @@ 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 ### +### Pay-To-Relay Relays that require payments may want to expose their fee schedules. diff --git a/12.md b/12.md index 74c9d81a..78bc3678 100644 --- a/12.md +++ b/12.md @@ -1,8 +1,6 @@ -NIP-12 -====== +# NIP-12 -Generic Tag Queries -------------------- +## Generic Tag Queries `draft` `optional` `author:scsibug` `author:fiatjaf` @@ -10,30 +8,26 @@ Relays may support subscriptions over arbitrary tags. `NIP-01` requires relays The `` object described in `NIP-01` is expanded to contain arbitrary keys with a `#` prefix. Any single-letter key in a filter beginning with `#` is a tag query, and MUST have a value of an array of strings. The filter condition matches if the event has a tag with the same name, and there is at least one tag value in common with the filter and event. The tag name is the letter without the `#`, and the tag value is the second element. Subsequent elements are ignored for the purposes of tag queries. -Example Subscription Filter ---------------------------- +## Example Subscription Filter The following provides an example of a filter that matches events of kind `1` with an `r` tag set to either `foo` or `bar`. -``` +```json { "kinds": [1], "#r": ["foo", "bar"] } ``` -Client Behavior ---------------- +## Client Behavior Clients SHOULD use the `supported_nips` field to learn if a relay supports generic tag queries. Clients MAY send generic tag queries to any relay, if they are prepared to filter out extraneous responses from relays that do not support this NIP. -Rationale ---------- +## Rationale The decision to reserve only single-letter tags to be usable in queries allow applications to make use of tags for all sorts of metadata, as it is their main purpose, without worrying that they might be bloating relay indexes. That also makes relays more lightweight, of course. And if some application or user is abusing single-letter tags with the intention of bloating relays that becomes easier to detect as single-letter tags will hardly be confused with some actually meaningful metadata some application really wanted to attach to the event with no spammy intentions. -Suggested Use Cases -------------------- +## Suggested Use Cases Motivating examples for generic tag queries are provided below. This NIP does not promote or standardize the use of any specific tag for any purpose. diff --git a/13.md b/13.md index e3662a57..091266ba 100644 --- a/13.md +++ b/13.md @@ -1,8 +1,6 @@ -NIP-13 -====== +# NIP-13 -Proof of Work -------------- +## Proof of Work `draft` `optional` `author:jb55` `author:cameri` @@ -10,8 +8,7 @@ This NIP defines a way to generate and interpret Proof of Work for nostr notes. `difficulty` is defined to be the number of leading zero bits in the `NIP-01` id. For example, an id of `000000000e9d97a1ab09fc381030b346cdd7a142ad57e6df0b46dc9bef6c7e2d` has a difficulty of `36` with `36` leading 0 bits. -Mining ------- +## Mining To generate PoW for a `NIP-01` note, a `nonce` tag is used: @@ -23,8 +20,7 @@ When mining, the second entry to the nonce tag is updated, and then the id is re The third entry to the nonce tag `SHOULD` contain the target difficulty. This allows clients to protect against situations where bulk spammers targeting a lower difficulty get lucky and match a higher difficulty. For example, if you require 40 bits to reply to your thread and see a committed target of 30, you can safely reject it even if the note has 40 bits difficulty. Without a committed target difficulty you could not reject it. Committing to a target difficulty is something all honest miners should be ok with, and clients `MAY` reject a note matching a target difficulty if it is missing a difficulty commitment. -Example mined note ------------------- +## Example mined note ```json { @@ -44,8 +40,7 @@ Example mined note } ``` -Validating ----------- +## Validating Here is some reference C code for calculating the difficulty (aka number of leading zero bits) in a nostr note id: @@ -77,17 +72,15 @@ int count_leading_zero_bits(unsigned char *hash) } ``` -Querying relays for PoW notes ------------------------------ +## Querying relays for PoW notes Since relays allow searching on prefixes, you can use this as a way to filter notes of a certain difficulty: -``` +```sh $ echo '["REQ", "subid", {"ids": ["000000000"]}]' | websocat wss://some-relay.com | jq -c '.[2]' {"id":"000000000121637feeb68a06c8fa7abd25774bdedfa9b6ef648386fb3b70c387", ...} ``` -Delegated Proof of Work ------------------------ +## Delegated Proof of Work Since the `NIP-01` note id does not commit to any signature, PoW can be outsourced to PoW providers, perhaps for a fee. This provides a way for clients to get their messages out to PoW-restricted relays without having to do any work themselves, which is useful for energy-constrained devices like mobile phones. diff --git a/14.md b/14.md index 0b37e8aa..ee859c83 100644 --- a/14.md +++ b/14.md @@ -1,8 +1,6 @@ -NIP-14 -====== +# NIP-14 -Subject tag in Text events. ---------------------------- +## Subject tag in Text events `draft` `optional` `author:unclebobmartin` @@ -14,6 +12,6 @@ This NIP defines the use of the "subject" tag in text (kind: 1) events. Browsers often display threaded lists of messages. The contents of the subject tag can be used in such lists, instead of the more ad hoc approach of using the first few words of the message. This is very similar to the way email browsers display lists of incoming emails by subject rather than by contents. When replying to a message with a subject, clients SHOULD replicate the subject tag. Clients MAY adorn the subject to denote -that it is a reply. e.g. by prepending "Re:". +that it is a reply. e.g. by prepending "Re:". Subjects should generally be shorter than 80 chars. Long subjects will likely be trimmed by clients. diff --git a/15.md b/15.md index 617c0115..c08d1003 100644 --- a/15.md +++ b/15.md @@ -1,14 +1,12 @@ -NIP-15 -====== +# NIP-15 -Nostr Marketplace (for resilient marketplaces) ------------------------------------ +## Nostr Marketplace (for resilient marketplaces) -`draft` `optional` `author:fiatjaf` `author:benarc` `author:motorina0` `author:talvasconcelos` +`draft` `optional` `author:fiatjaf` `author:benarc` `author:motorina0` `author:talvasconcelos` -> Based on https://github.com/lnbits/Diagon-Alley - -> Implemented here https://github.com/lnbits/nostrmarket +> Based on +> +> Implemented here ## Terms @@ -35,15 +33,16 @@ The `merchant` admin software can be purely clientside, but for `convenience` an A merchant can publish these events: | Kind | | Description | NIP | |---------|------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------| -| `0 ` | `set_meta` | The merchant description (similar with any `nostr` public key). | [NIP01 ](https://github.com/nostr-protocol/nips/blob/master/01.md) | +| `0` | `set_meta` | The merchant description (similar with any `nostr` public key). | [NIP01](https://github.com/nostr-protocol/nips/blob/master/01.md) | | `30017` | `set_stall` | Create or update a stall. | [NIP33](https://github.com/nostr-protocol/nips/blob/master/33.md) (Parameterized Replaceable Event) | | `30018` | `set_product` | Create or update a product. | [NIP33](https://github.com/nostr-protocol/nips/blob/master/33.md) (Parameterized Replaceable Event) | -| `4 ` | `direct_message` | Communicate with the customer. The messages can be plain-text or JSON. | [NIP09](https://github.com/nostr-protocol/nips/blob/master/09.md) | -| `5 ` | `delete` | Delete a product or a stall. | [NIP05](https://github.com/nostr-protocol/nips/blob/master/05.md) | +| `4` | `direct_message` | Communicate with the customer. The messages can be plain-text or JSON. | [NIP09](https://github.com/nostr-protocol/nips/blob/master/09.md) | +| `5` | `delete` | Delete a product or a stall. | [NIP05](https://github.com/nostr-protocol/nips/blob/master/05.md) | -### Event `30017`: Create or update a stall. +### Event `30017`: Create or update a stall **Event Content**: + ```json { "id": , @@ -62,20 +61,24 @@ A merchant can publish these events: ``` Fields that are not self-explanatory: - - `shipping`: - - an array with possible shipping zones for this stall. The customer MUST choose exactly one shipping zone. - - shipping to different zones can have different costs. For some goods (digital for example) the cost can be zero. - - the `id` is an internal value used by the merchant. This value must be sent back as the customer selection. + +- `shipping`: + - an array with possible shipping zones for this stall. The customer MUST choose exactly one shipping zone. + - shipping to different zones can have different costs. For some goods (digital for example) the cost can be zero. + - the `id` is an internal value used by the merchant. This value must be sent back as the customer selection. **Event Tags**: + ```json "tags": [["d", , @@ -93,13 +96,15 @@ Fields that are not self-explanatory: ``` Fields that are not self-explanatory: - - `specs`: - - an array of key pair values. It allows for the Customer UI to present present product specifications in a structure mode. It also allows comparison between products - - eg: `[["operating_system", "Android 12.0"], ["screen_size", "6.4 inches"], ["connector_type", "USB Type C"]]` + +- `specs`: + - an array of key pair values. It allows for the Customer UI to present present product specifications in a structure mode. It also allows comparison between products + - eg: `[["operating_system", "Android 12.0"], ["screen_size", "6.4 inches"], ["connector_type", "USB Type C"]]` _Open_: better to move `spec` in the `tags` section of the event? **Event Tags**: + ```json "tags": [ ["d", . ## Additional diff --git a/16.md b/16.md index 4d9481d4..23f28ef7 100644 --- a/16.md +++ b/16.md @@ -1,37 +1,33 @@ -NIP-16 -====== +# NIP-16 -Event Treatment ---------------- +## Event Treatment `draft` `optional` `author:Semisol` Relays may decide to allow replaceable and/or ephemeral events. -Regular Events ------------------- +## Regular Events + A *regular event* is defined as an event with a kind `1000 <= n < 10000`. Upon a regular event being received, the relay SHOULD send it to all clients with a matching filter, and SHOULD store it. New events of the same kind do not affect previous events in any way. -Replaceable Events ------------------- +## Replaceable Events + A *replaceable event* is defined as an event with a kind `10000 <= n < 20000`. Upon a replaceable event with a newer timestamp than the currently known latest replaceable event with the same kind and author being received, the old event SHOULD be discarded, effectively replacing what gets returned when querying for `author:kind` tuples. -Ephemeral Events ----------------- +## Ephemeral Events + An *ephemeral event* is defined as an event with a kind `20000 <= n < 30000`. Upon an ephemeral event being received, the relay SHOULD send it to all clients with a matching filter, and MUST NOT store it. -Client Behavior ---------------- +## Client Behavior -Clients SHOULD use the `supported_nips` field to learn if a relay supports this NIP. Clients SHOULD NOT send ephemeral events to relays that do not support this NIP; they will most likely be persisted. Clients MAY send replaceable events to relays that may not support this NIP, and clients querying SHOULD be prepared for the relay to send multiple events and should use the latest one. +Clients SHOULD use the `supported_nips` field to learn if a relay supports this NIP. Clients SHOULD NOT send ephemeral events to relays that do not support this NIP; they will most likely be persisted. Clients MAY send replaceable events to relays that may not support this NIP, and clients querying SHOULD be prepared for the relay to send multiple events and should use the latest one. -Suggested Use Cases -------------------- +## Suggested Use Cases * States: An application may create a state event that is replaced every time a new state is set (such as statuses) * Typing indicators: A chat application may use ephemeral events as a typing indicator. diff --git a/18.md b/18.md index 422ad9ca..67b6541b 100644 --- a/18.md +++ b/18.md @@ -1,8 +1,6 @@ -NIP-18 -====== +# NIP-18 -Reposts -------- +## Reposts `draft` `optional` `author:jb55` `author:fiatjaf` `author:arthurfranca` diff --git a/19.md b/19.md index 6fc4523e..365482c6 100644 --- a/19.md +++ b/19.md @@ -1,8 +1,6 @@ -NIP-19 -====== +# NIP-19 -bech32-encoded entities ------------------------ +## bech32-encoded entities `draft` `optional` `author:jb55` `author:fiatjaf` `author:Semisol` @@ -16,9 +14,9 @@ To prevent confusion and mixing between private keys, public keys and event ids, These are the possible bech32 prefixes: - - `npub`: public keys - - `nsec`: private keys - - `note`: note ids +- `npub`: public keys +- `nsec`: private keys +- `note`: note ids Example: the hex public key `3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d` translates to `npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6`. @@ -32,10 +30,10 @@ For these events, the contents are a binary-encoded list of `TLV` (type-length-v These are the possible bech32 prefixes with `TLV`: - - `nprofile`: a nostr profile - - `nevent`: a nostr event - - `nrelay`: a nostr relay - - `naddr`: a nostr parameterized replaceable event coordinate (NIP-33) +- `nprofile`: a nostr profile +- `nevent`: a nostr event +- `nrelay`: a nostr relay +- `naddr`: a nostr parameterized replaceable event coordinate (NIP-33) These possible standardized `TLV` types are indicated here: diff --git a/20.md b/20.md index 7e97dd91..5b938678 100644 --- a/20.md +++ b/20.md @@ -1,9 +1,6 @@ -NIP-20 -====== +# NIP-20 - -Command Results ---------------- +## Command Results `draft` `optional` `author:jb55` @@ -33,9 +30,7 @@ Ephemeral events are not acknowledged with OK responses, unless there is a failu If the event or `EVENT` command is malformed and could not be parsed, a NOTICE message SHOULD be used instead of a command result. This NIP only applies to non-malformed EVENT commands. - -Examples --------- +## Examples Event successfully written to the database: @@ -69,14 +64,11 @@ Event rejected, insufficient proof-of-work difficulty ["OK", "b1a649ebe8...", false, "pow: difficulty 26 is less than 30"] -Event failed to save, +Event failed to save, ["OK", "b1a649ebe8...", false, "error: could not connect to the database"] - - -Client Handling ---------------- +## Client Handling `messages` are meant for humans, with `reason:` prefixes so that clients can be slightly more intelligent with what to do with them. For example, with a `rate-limited:` reason the client may not show anything and simply try again with a longer timeout. @@ -86,8 +78,6 @@ For the `invalid:` and `blocked:` prefix the client may wish to show these as st The prefixes include a colon so that the message can be cleanly separated from the prefix by taking everything after `:` and trimming it. - -Future Extensions ------------------ +## Future Extensions This proposal SHOULD be extended to support further commands in the future, such as REQ and AUTH. They are left out of this initial version to keep things simpler. diff --git a/21.md b/21.md index 2525bf10..1b46f3e1 100644 --- a/21.md +++ b/21.md @@ -1,8 +1,6 @@ -NIP-21 -====== +# NIP-21 -`nostr:` URL scheme -------------------- +## `nostr:` URL scheme `draft` `optional` `author:fiatjaf` diff --git a/22.md b/22.md index 2172519e..bb81484f 100644 --- a/22.md +++ b/22.md @@ -1,8 +1,6 @@ -NIP-22 -====== +# NIP-22 -Event `created_at` Limits ---------------------------- +## Event `created_at` Limits `draft` `optional` `author:jeffthibault` `author:Giszmo` @@ -10,13 +8,11 @@ Relays may define both upper and lower limits within which they will consider an If a relay supports this NIP, the relay SHOULD send the client a [NIP-20](20.md) command result saying the event was not stored for the `created_at` timestamp not being within the permitted limits. -Client Behavior ---------------- +## Client Behavior Clients SHOULD use the [NIP-11](11.md) `supported_nips` field to learn if a relay uses event `created_at` time limits as defined by this NIP. -Motivation ----------- +## Motivation This NIP formalizes restrictions on event timestamps as accepted by a relay and allows clients to be aware of relays that have these restrictions. @@ -28,9 +24,7 @@ A wide adoption of this NIP could create a better user experience as it would de Keep in mind that there is a use case where a user migrates their old posts onto a new relay. If a relay rejects events that were not recently created, it cannot serve this use case. - -Python (pseudocode) Example ---------------------------- +## Python (pseudocode) Example ```python import time @@ -42,4 +36,5 @@ UPPER_LIMIT = TIME + (60 * 15) # Define upper limit as 15 minutes into the if event.created_at not in range(LOWER_LIMIT, UPPER_LIMIT): ws.send('["OK", event.id, False, "invalid: the event created_at field is out of the acceptable range (-24h, +15min) for this relay"]') ``` + Note: These are just example limits, the relay operator can choose whatever limits they want. diff --git a/23.md b/23.md index 151a31b5..e0bc036f 100644 --- a/23.md +++ b/23.md @@ -1,8 +1,6 @@ -NIP-23 -====== +# NIP-23 -Long-form Content ------------------ +## Long-form Content `draft` `optional` `author:fiatjaf` diff --git a/25.md b/25.md index f74bcc08..f0ba7dfb 100644 --- a/25.md +++ b/25.md @@ -1,9 +1,6 @@ +# NIP-25 -NIP-25 -====== - -Reactions ---------- +## Reactions `draft` `optional` `author:jb55` @@ -21,15 +18,14 @@ separate tallies. The `content` MAY be an emoji, in this case it MAY be interpreted as a "like" or "dislike", or the client MAY display this emoji reaction on the post. -Tags ----- +## Tags The reaction event SHOULD include `e` and `p` tags from the note the user is reacting to. This allows users to be notified of reactions to posts they were mentioned in. Including the `e` tags enables clients to pull all the reactions associated with individual posts or all the posts in a thread. -The last `e` tag MUST be the `id` of the note that is being reacted to. +The last `e` tag MUST be the `id` of the note that is being reacted to. The last `p` tag MUST be the `pubkey` of the event being reacted to. @@ -38,7 +34,7 @@ Example code ```swift func make_like_event(pubkey: String, privkey: String, liked: NostrEvent) -> NostrEvent { var tags: [[String]] = liked.tags.filter { - tag in tag.count >= 2 && (tag[0] == "e" || tag[0] == "p") + tag in tag.count >= 2 && (tag[0] == "e" || tag[0] == "p") } tags.append(["e", liked.id]) tags.append(["p", liked.pubkey]) diff --git a/26.md b/26.md index b8fa9028..09bd4d0b 100644 --- a/26.md +++ b/26.md @@ -1,16 +1,14 @@ -NIP: 26 -======= +# NIP: 26 -Delegated Event Signing ------ +## Delegated Event Signing `draft` `optional` `author:markharding` `author:minds` This NIP defines how events can be delegated so that they can be signed by other keypairs. -Another application of this proposal is to abstract away the use of the 'root' keypairs when interacting with clients. For example, a user could generate new keypairs for each client they wish to use and authorize those keypairs to generate events on behalf of their root pubkey, where the root keypair is stored in cold storage. +Another application of this proposal is to abstract away the use of the 'root' keypairs when interacting with clients. For example, a user could generate new keypairs for each client they wish to use and authorize those keypairs to generate events on behalf of their root pubkey, where the root keypair is stored in cold storage. -#### Introducing the 'delegation' tag +### Introducing the 'delegation' tag This NIP introduces a new tag: `delegation` which is formatted as follows: @@ -23,26 +21,30 @@ This NIP introduces a new tag: `delegation` which is formatted as follows: ] ``` -##### Delegation Token +#### Delegation Token The **delegation token** should be a 64-byte Schnorr signature of the sha256 hash of the following string: -``` +```text nostr:delegation:: ``` -##### Conditions Query String +#### Conditions Query String The following fields and operators are supported in the above query string: *Fields*: + 1. `kind` - - *Operators*: - - `=${KIND_NUMBER}` - delegatee may only sign events of this kind -2. `created_at` - - *Operators*: - - `<${TIMESTAMP}` - delegatee may only sign events created ***before*** the specified timestamp - - `>${TIMESTAMP}` - delegatee may only sign events created ***after*** the specified timestamp + +- *Operators*: + - `=${KIND_NUMBER}` - delegatee may only sign events of this kind + +1. `created_at` + +- *Operators*: + - `<${TIMESTAMP}` - delegatee may only sign events created ***before*** the specified timestamp + - `>${TIMESTAMP}` - delegatee may only sign events created ***after*** the specified timestamp In order to create a single condition, you must use a supported field and operator. Multiple conditions can be used in a single query string, including on the same field. Conditions must be combined with `&`. @@ -56,7 +58,7 @@ For the vast majority of use-cases, it is advisable that query strings should in #### Example -``` +```yaml # Delegator: privkey: ee35e8bb71131c02c1d7e73231daa48e9953d329a4b701f7133c8f46dd21139c pubkey: 8e0d3d3eb2881ec137a11debe736a9086715a8c8beeeda615780064d68bc25dd @@ -67,16 +69,19 @@ pubkey: 477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396 ``` Delegation string to grant note publishing authorization to the delegatee (477318cf) from now, for the next 30 days, given the current timestamp is `1674834236`. + ```json nostr:delegation:477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396:kind=1&created_at>1674834236&created_at<1677426236 ``` The delegator (8e0d3d3e) then signs a SHA256 hash of the above delegation string, the result of which is the delegation token: -``` + +```text 6f44d7fe4f1c09f3954640fb58bd12bae8bb8ff4120853c4693106c82e920e2b898f1f9ba9bd65449a987c39c0423426ab7b53910c0c6abfb41b30bc16e5f524 ``` The delegatee (477318cf) can now construct an event on behalf of the delegator (8e0d3d3e). The delegatee then signs the event with its own private key and publishes. + ```json { "id": "e93c6095c3db1c31d15ac771f8fc5fb672f6e52cd25505099f62cd055523224f", @@ -100,9 +105,8 @@ The event should be considered a valid delegation if the conditions are satisfie Clients should display the delegated note as if it was published directly by the delegator (8e0d3d3e). - #### Relay & Client Support Relays should answer requests such as `["REQ", "", {"authors": ["A"]}]` by querying both the `pubkey` and delegation tags `[1]` value. -Relays SHOULD allow the delegator (8e0d3d3e) to delete the events published by the delegatee (477318cf). \ No newline at end of file +Relays SHOULD allow the delegator (8e0d3d3e) to delete the events published by the delegatee (477318cf). diff --git a/27.md b/27.md index 6d761206..898319cf 100644 --- a/27.md +++ b/27.md @@ -1,8 +1,6 @@ -NIP-27 -====== +# NIP-27 -Text Note References --------------------- +## Text Note References `draft` `optional` `author:arthurfranca` `author:hodlbod` `author:fiatjaf` diff --git a/28.md b/28.md index 169ae4f4..c286b299 100644 --- a/28.md +++ b/28.md @@ -1,9 +1,6 @@ +# NIP-28 -NIP-28 -====== - -Public Chat ------------ +## Public Chat `draft` `optional` `author:ChristopherDavid` `author:fiatjaf` `author:jb55` `author:Cameri` @@ -32,7 +29,6 @@ In the channel creation `content` field, Client SHOULD include basic channel met } ``` - ## Kind 41: Set channel metadata Update a channel's public metadata. @@ -59,7 +55,6 @@ Clients SHOULD use [NIP-10](10.md) marked "e" tags to recommend a relay. } ``` - ## Kind 42: Create channel message Send a text message to a channel. @@ -93,7 +88,6 @@ Reply to another message: } ``` - ## Kind 43: Hide message User no longer wants to see a certain message. @@ -138,16 +132,13 @@ For [NIP-10](10.md) relay recommendations, clients generally SHOULD use the rela Clients MAY recommend any relay URL. For example, if a relay hosting the original kind 40 event for a channel goes offline, clients could instead fetch channel data from a backup relay, or a relay that clients trust more than the original relay. +## Motivation -Motivation ----------- If we're solving censorship-resistant communication for social media, we may as well solve it also for Telegram-style messaging. We can bring the global conversation out from walled gardens into a true public square open to all. - -Additional info ---------------- +## Additional info - [Chat demo PR with fiatjaf+jb55 comments](https://github.com/ArcadeCity/arcade/pull/28) - [Conversation about NIP16](https://t.me/nostr_protocol/29566) diff --git a/33.md b/33.md index 10681fac..67f34d95 100644 --- a/33.md +++ b/33.md @@ -1,15 +1,13 @@ -NIP-33 -====== +# NIP-33 -Parameterized Replaceable Events --------------------------------- +## Parameterized Replaceable Events `draft` `optional` `author:Semisol` `author:Kukks` `author:Cameri` `author:Giszmo` This NIP adds a new event range that allows for replacement of events that have the same `d` tag and kind unlike NIP-16 which only replaced by kind. -Implementation --------------- +## Implementation + The value of a tag is defined as the first parameter of a tag after the tag name. A *parameterized replaceable event* is defined as an event with a kind `30000 <= n < 40000`. @@ -32,8 +30,7 @@ replace each other: Clients SHOULD NOT use `d` tags with multiple values and SHOULD include the `d` tag even if it has no value to allow querying using the `#d` filter. -Referencing and tagging ------------------------ +## Referencing and tagging Normally (as per NIP-01, NIP-12) the `"p"` tag is used for referencing public keys and the `"e"` tag for referencing event ids and the `note`, `npub`, `nprofile` or `nevent` are their @@ -46,8 +43,7 @@ the referenced combination of public key and `d` tag can be found. The equivalent in `tags` to the `naddr` code is the tag `"a"`, comprised of `["a", "::", ""]`. -Client Behavior ---------------- +## Client Behavior Clients SHOULD use the `supported_nips` field to learn if a relay supports this NIP. Clients MAY send parameterized replaceable events to relays that may not support this NIP, and clients querying SHOULD be prepared for the relay to send multiple events and should use the latest one and are recommended to send a `#d` tag filter. Clients should account for the fact that missing `d` tags or ones with no value are not returned in tag filters, and are recommended to always include a `d` tag with a value. diff --git a/36.md b/36.md index 1223e53c..5b747876 100644 --- a/36.md +++ b/36.md @@ -1,23 +1,21 @@ -NIP-36 -====== +# NIP-36 -Sensitive Content / Content Warning ------------------------------------ +## Sensitive Content / Content Warning `draft` `optional` `author:fernandolguevara` The `content-warning` tag enables users to specify if the event's content needs to be approved by readers to be shown. Clients can hide the content until the user acts on it. -#### Spec +### Spec -``` +```yaml tag: content-warning options: - [reason]: optional ``` -#### Example +### Example ```json { diff --git a/39.md b/39.md index b84603c9..6bdb6153 100644 --- a/39.md +++ b/39.md @@ -1,8 +1,6 @@ -NIP-39 -====== +# NIP-39 -External Identities in Profiles -------------------------------- +## External Identities in Profiles `draft` `optional` `author:pseudozach` `author:Semisol` @@ -13,6 +11,7 @@ Nostr protocol users may have other online identities such as usernames, profile ## `i` tag on a metadata event A new optional `i` tag is introduced for `kind 0` metadata event contents in addition to name, about, picture fields as included in [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md): + ```json { "id": , @@ -28,12 +27,13 @@ A new optional `i` tag is introduced for `kind 0` metadata event contents in add ``` An `i` tag will have two parameters, which are defined as the following: + 1. `platform:identity`: This is the platform name (for example `github`) and the identity on that platform (for example `semisol`) joined together with `:`. 2. `proof`: String or object that points to the proof of owning this identity. Clients SHOULD process any `i` tags with more than 2 values for future extensibility. Identity provider names SHOULD only include `a-z`, `0-9` and the characters `._-/` and MUST NOT include `:`. -Identity names SHOULD be normalized if possible by replacing uppercase letters with lowercase letters, and if there are multiple aliases for an entity the primary one should be used. +Identity names SHOULD be normalized if possible by replacing uppercase letters with lowercase letters, and if there are multiple aliases for an entity the primary one should be used. ## Claim types diff --git a/40.md b/40.md index 32680db8..c5c4a08b 100644 --- a/40.md +++ b/40.md @@ -1,22 +1,20 @@ -NIP-40 -====== +# NIP-40 -Expiration Timestamp ------------------------------------ +## Expiration Timestamp `draft` `optional` `author:0xtlt` The `expiration` tag enables users to specify a unix timestamp at which the message SHOULD be considered expired (by relays and clients) and SHOULD be deleted by relays. -#### Spec +### Spec -``` +```yaml tag: expiration values: - [UNIX timestamp in seconds]: required ``` -#### Example +### Example ```json { @@ -33,27 +31,25 @@ values: Note: The timestamp should be in the same format as the created_at timestamp and should be interpreted as the time at which the message should be deleted by relays. -Client Behavior ---------------- +## Client Behavior Clients SHOULD use the `supported_nips` field to learn if a relay supports this NIP. Clients SHOULD NOT send expiration events to relays that do not support this NIP. Clients SHOULD ignore events that have expired. -Relay Behavior --------------- +## Relay Behavior Relays MAY NOT delete expired messages immediately on expiration and MAY persist them indefinitely. Relays SHOULD NOT send expired events to clients, even if they are stored. Relays SHOULD drop any events that are published to them if they are expired. An expiration timestamp does not affect storage of ephemeral events. -Suggested Use Cases -------------------- +## Suggested Use Cases * Temporary announcements - This tag can be used to make temporary announcements. For example, an event organizer could use this tag to post announcements about an upcoming event. * Limited-time offers - This tag can be used by businesses to make limited-time offers that expire after a certain amount of time. For example, a business could use this tag to make a special offer that is only available for a limited time. -#### Warning +### Warning + The events could be downloaded by third parties as they are publicly accessible all the time on the relays. So don't consider expiring messages as a security feature for your conversations or other uses. diff --git a/42.md b/42.md index 9b0c45b4..57c5e0f8 100644 --- a/42.md +++ b/42.md @@ -1,8 +1,6 @@ -NIP-42 -====== +# NIP-42 -Authentication of clients to relays ------------------------------------ +## Authentication of clients to relays `draft` `optional` `author:Semisol` `author:fiatjaf` @@ -12,25 +10,25 @@ This NIP defines a way for clients to authenticate to relays by signing an ephem A relay may want to require clients to authenticate to access restricted resources. For example, - - A relay may request payment or other forms of whitelisting to publish events -- this can naïvely be achieved by limiting publication - to events signed by the whitelisted key, but with this NIP they may choose to accept any events as long as they are published from an - authenticated user; - - A relay may limit access to `kind: 4` DMs to only the parties involved in the chat exchange, and for that it may require authentication - before clients can query for that kind. - - A relay may limit subscriptions of any kind to paying users or users whitelisted through any other means, and require authentication. +- A relay may request payment or other forms of whitelisting to publish events -- this can naïvely be achieved by limiting publication + to events signed by the whitelisted key, but with this NIP they may choose to accept any events as long as they are published from an + authenticated user; +- A relay may limit access to `kind: 4` DMs to only the parties involved in the chat exchange, and for that it may require authentication + before clients can query for that kind. +- A relay may limit subscriptions of any kind to paying users or users whitelisted through any other means, and require authentication. ## Definitions This NIP defines a new message, `AUTH`, which relays can send when they support authentication and clients can send to relays when they want to authenticate. When sent by relays, the message is of the following form: -``` +```json ["AUTH", ] ``` And, when sent by clients, of the following form: -``` +```json ["AUTH", ] ``` @@ -67,13 +65,13 @@ is expected to last for the duration of the WebSocket connection. Upon receiving a message from an unauthenticated user it can't fulfill without authentication, a relay may choose to notify the client. For that it can use a `NOTICE` or `OK` message with a standard prefix `"restricted: "` that is readable both by humans and machines, for example: -``` +```json ["NOTICE", "restricted: we can't serve DMs to unauthenticated users, does your client implement NIP-42?"] ``` or it can return an `OK` message noting the reason an event was not written using the same prefix: -``` +```json ["OK", , false, "restricted: we do not accept events from unauthenticated users, please sign up at https://example.com/"] ``` @@ -81,8 +79,8 @@ or it can return an `OK` message noting the reason an event was not written usin To verify `AUTH` messages, relays must ensure: - - that the `kind` is `22242`; - - that the event `created_at` is close (e.g. within ~10 minutes) of the current time; - - that the `"challenge"` tag matches the challenge sent before; - - that the `"relay"` tag matches the relay URL: - - URL normalization techniques can be applied. For most cases just checking if the domain name is correct should be enough. +- that the `kind` is `22242`; +- that the event `created_at` is close (e.g. within ~10 minutes) of the current time; +- that the `"challenge"` tag matches the challenge sent before; +- that the `"relay"` tag matches the relay URL: + - URL normalization techniques can be applied. For most cases just checking if the domain name is correct should be enough. diff --git a/45.md b/45.md index 87e80002..e59c5686 100644 --- a/45.md +++ b/45.md @@ -1,8 +1,6 @@ -NIP-45 -====== +# NIP-45 -Event Counts --------------- +## Event Counts `draft` `optional` `author:staab` @@ -16,19 +14,19 @@ Some queries a client may want to execute against connected relays are prohibiti This NIP defines a verb called `COUNT`, which accepts a subscription id and filters as specified in [NIP 01](01.md). -``` +```json ["COUNT", , ...] ``` Counts are returned using a `COUNT` response in the form `{count: }`. Relays may use probabilistic counts to reduce compute requirements. -``` +```json ["COUNT", , {"count": }] ``` Examples: -``` +```json # Followers count ["COUNT", , {"kinds": [3], "#p": []}] ["COUNT", , {"count": 238}] diff --git a/46.md b/46.md index 90fa1a06..a88def88 100644 --- a/46.md +++ b/46.md @@ -1,8 +1,6 @@ -NIP-46 -====== +# NIP-46 -Nostr Connect ------------------------- +## Nostr Connect `draft` `optional` `author:tiero` `author:giowe` `author:vforvalerio87` @@ -12,17 +10,14 @@ Private keys should be exposed to as few systems - apps, operating systems, devi Entering private keys can also be annoying and requires exposing them to even more systems such as the operating system's clipboard that might be monitored by malicious apps. - ## Terms -* **App**: Nostr app on any platform that *requires* to act on behalf of a nostr account. -* **Signer**: Nostr app that holds the private key of a nostr account and *can sign* on its behalf. - +- **App**: Nostr app on any platform that *requires* to act on behalf of a nostr account. +- **Signer**: Nostr app that holds the private key of a nostr account and *can sign* on its behalf. ## `TL;DR` - -**App** and **Signer** sends ephemeral encrypted messages to each other using kind `24133`, using a relay of choice. +**App** and **Signer** sends ephemeral encrypted messages to each other using kind `24133`, using a relay of choice. App prompts the Signer to do things such as fetching the public key or signing events. @@ -54,8 +49,7 @@ The `content` field must be an encrypted JSONRPC-ish **request** or **response** ### Methods - -#### Mandatory +#### Mandatory These are mandatory methods the remote signer app MUST implement: @@ -71,7 +65,6 @@ These are mandatory methods the remote signer app MUST implement: #### optional - - **connect** - params [`pubkey`] - **disconnect** @@ -89,10 +82,8 @@ These are mandatory methods the remote signer app MUST implement: - params [`pubkey`, `nip4 ciphertext`] - result [`plaintext`] - NOTICE: `pubkey` and `signature` are hex-encoded strings. - ### Nostr Connect URI **Signer** discovers **App** by scanning a QR code, clicking on a deep link or copy-pasting an URI. @@ -101,10 +92,10 @@ The **App** generates a special URI with prefix `nostrconnect://` and base path - `relay` URL of the relay of choice where the **App** is connected and the **Signer** must send and listen for messages. - `metadata` metadata JSON of the **App** - - `name` human-readable name of the **App** - - `url` (optional) URL of the website requesting the connection - - `description` (optional) description of the **App** - - `icons` (optional) array of URLs for icons of the **App**. + - `name` human-readable name of the **App** + - `url` (optional) URL of the website requesting the connection + - `description` (optional) description of the **App** + - `icons` (optional) array of URLs for icons of the **App**. #### JavaScript @@ -113,12 +104,11 @@ const uri = `nostrconnect://?relay=${encodeURIComponent("wss://relay.dam ``` #### Example + ```sh nostrconnect://b889ff5b1513b641e2a139f661a661364979c5beee91842f8f0ef42ab558e9d4?relay=wss%3A%2F%2Frelay.damus.io&metadata=%7B%22name%22%3A%22Example%22%7D ``` - - ## Flows The `content` field contains encrypted message as specified by [NIP04](https://github.com/nostr-protocol/nips/blob/master/04.md). The `kind` chosen is `24133`. @@ -141,22 +131,19 @@ The `content` field contains encrypted message as specified by [NIP04](https://g 1. User clicks on **"Disconnect"** button on the **Signer** 2. The **Signer** will send a message to the **App** with a `disconnect` request - ### Get Public Key 1. The **App** will send a message to the **Signer** with a `get_public_key` request -3. The **Signer** will send back a message with the public key as a response to the `get_public_key` request +2. The **Signer** will send back a message with the public key as a response to the `get_public_key` request ### Sign Event 1. The **App** will send a message to the **Signer** with a `sign_event` request along with the **event** to be signed 2. The **Signer** will show a popup to the user to inspect the event and sign it -3. The **Signer** will send back a message with the event including the `id` and the schnorr `signature` as a response to the `sign_event` request +3. The **Signer** will send back a message with the event including the `id` and the Schnorr `signature` as a response to the `sign_event` request ### Delegate 1. The **App** will send a message with metadata to the **Signer** with a `delegate` request along with the **conditions** query string and the **pubkey** of the **App** to be delegated. 2. The **Signer** will show a popup to the user to delegate the **App** to sign on his behalf 3. The **Signer** will send back a message with the signed [NIP-26 delegation token](https://github.com/nostr-protocol/nips/blob/master/26.md) or reject it - - diff --git a/50.md b/50.md index 5bda3559..ccbf6a11 100644 --- a/50.md +++ b/50.md @@ -1,41 +1,41 @@ -NIP-50 -====== +# NIP-50 -Search Capability ------------------ +## Search Capability `draft` `optional` `author:brugeman` `author:mikedilger` `author:fiatjaf` ## Abstract -Many Nostr use cases require some form of general search feature, in addition to structured queries by tags or ids. -Specifics of the search algorithms will differ between event kinds, this NIP only describes a general +Many Nostr use cases require some form of general search feature, in addition to structured queries by tags or ids. +Specifics of the search algorithms will differ between event kinds, this NIP only describes a general extensible framework for performing such queries. -## `search` filter field +## `search` filter field A new `search` field is introduced for `REQ` messages from clients: + ```json { ... "search": } ``` -`search` field is a string describing a query in a human-readable form, i.e. "best nostr apps". -Relays SHOULD interpret the query to the best of their ability and return events that match it. -Relays SHOULD perform matching against `content` event field, and MAY perform -matching against other fields if that makes sense in the context of a specific kind. -A query string may contain `key:value` pairs (two words separated by colon), these are extensions, relays SHOULD ignore +`search` field is a string describing a query in a human-readable form, i.e. "best nostr apps". +Relays SHOULD interpret the query to the best of their ability and return events that match it. +Relays SHOULD perform matching against `content` event field, and MAY perform +matching against other fields if that makes sense in the context of a specific kind. + +A query string may contain `key:value` pairs (two words separated by colon), these are extensions, relays SHOULD ignore extensions they don't support. -Clients may specify several search filters, i.e. `["REQ", "", { "search": "orange" }, { "kinds": [1, 2], "search": "purple" }]`. Clients may +Clients may specify several search filters, i.e. `["REQ", "", { "search": "orange" }, { "kinds": [1, 2], "search": "purple" }]`. Clients may include `kinds`, `ids` and other filter field to restrict the search results to particular event kinds. -Clients SHOULD use the supported_nips field to learn if a relay supports `search` filter. Clients MAY send `search` +Clients SHOULD use the supported_nips field to learn if a relay supports `search` filter. Clients MAY send `search` filter queries to any relay, if they are prepared to filter out extraneous responses from relays that do not support this NIP. -Clients SHOULD query several relays supporting this NIP to compensate for potentially different +Clients SHOULD query several relays supporting this NIP to compensate for potentially different implementation details between relays. Clients MAY verify that events returned by a relay match the specified query in a way that suits the @@ -46,4 +46,5 @@ Relays SHOULD exclude spam from search results by default if they supports some ## Extensions Relay MAY support these extensions: + - `include:spam` - turn off spam filtering, if it was enabled by default diff --git a/51.md b/51.md index 80cc09ef..31da7d89 100644 --- a/51.md +++ b/51.md @@ -1,8 +1,6 @@ -NIP-51 -====== +# NIP-51 -Lists -------------------------- +## Lists `draft` `optional` `author:fiatjaf` `author:arcbtc` `author:monlovesmango` `author:eskema` `depends:33` @@ -15,16 +13,19 @@ Otherwise, the list type's events should follow the specification for [NIP-33 - ## Replaceable List Event Example Lets say a user wants to create a 'Mute' list and has keys: -``` + +```yaml priv: fb505c65d4df950f5d28c9e4d285ee12ffaf315deef1fc24e3c7cd1e7e35f2b1 pub: b1a5c93edcc8d586566fde53a20bdb50049a97b15483cb763854e57016e0fa3d ``` + The user wants to publicly include these users: ```json ["p", "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"], ["p", "32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245"] ``` + and privately include these users (below is the JSON that would be encrypted and placed in the event content): ```json @@ -48,20 +49,22 @@ Then the user would create a 'Mute' list event like below: } ``` - ## Parameterized Replaceable List Event Example Lets say a user wants to create a 'Categorized People' list of `nostr` people and has keys: -``` + +```yaml priv: fb505c65d4df950f5d28c9e4d285ee12ffaf315deef1fc24e3c7cd1e7e35f2b1 pub: b1a5c93edcc8d586566fde53a20bdb50049a97b15483cb763854e57016e0fa3d ``` + The user wants to publicly include these users: ```json ["p", "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d"], ["p", "32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245"] ``` + and privately include these users (below is the JSON that would be encrypted and placed in the event content): ```json diff --git a/56.md b/56.md index 55ee1a2e..54c8759c 100644 --- a/56.md +++ b/56.md @@ -1,9 +1,6 @@ +# NIP-56 -NIP-56 -====== - -Reporting ---------- +## Reporting `draft` `optional` `author:jb55` @@ -13,8 +10,7 @@ illegal and explicit content. The content MAY contain additional information submitted by the entity reporting the content. -Tags ----- +## Tags The report event MUST include a `p` tag referencing the pubkey of the user you are reporting. @@ -32,8 +28,7 @@ being reported, which consists of the following report types: Some report tags only make sense for profile reports, such as `impersonation` -Example events --------------- +## Example events ```json { @@ -66,16 +61,13 @@ Example events } ``` -Client behavior ---------------- +## Client behavior Clients can use reports from friends to make moderation decisions if they choose to. For instance, if 3+ of your friends report a profile as explicit, clients can have an option to automatically blur photos from said account. - -Relay behavior --------------- +## Relay behavior It is not recommended that relays perform automatic moderation using reports, as they can be easily gamed. Admins could use reports from trusted moderators to diff --git a/57.md b/57.md index 17042ea4..abdaaa2e 100644 --- a/57.md +++ b/57.md @@ -1,8 +1,6 @@ -NIP-57 -====== +# NIP-57 -Lightning Zaps --------------- +## Lightning Zaps `draft` `optional` `author:jb55` `author:kieran` diff --git a/58.md b/58.md index 2fa44066..1a84c084 100644 --- a/58.md +++ b/58.md @@ -1,8 +1,6 @@ -NIP-58 -====== +# NIP-58 -Badges ------- +## Badges `draft` `optional` `author:cameri` @@ -116,6 +114,7 @@ Clients SHOULD attempt to render the most appropriate badge thumbnail according ### Example of a Profile Badges event Honorable Bob The Brave: + ```json { "kind": 30008, diff --git a/65.md b/65.md index 4c7a6a53..7a008b48 100644 --- a/65.md +++ b/65.md @@ -1,8 +1,6 @@ -NIP-65 -====== +# NIP-65 -Relay List Metadata -------------------- +## Relay List Metadata `draft` `optional` `author:mikedilger` @@ -36,9 +34,9 @@ There is a common nostr use case where users wish to follow the content produced Because users don't often share the same sets of relays, ad-hoc solutions have arisen to get that content, but these solutions negatively impact scalability and decentralization: - - Most people are sending their posts to the same most popular relays in order to be more widely seen - - Many people are pulling from a large number of relays (including many duplicate events) in order to get more data - - Events are being copied between relays, oftentimes to many different relays +- Most people are sending their posts to the same most popular relays in order to be more widely seen +- Many people are pulling from a large number of relays (including many duplicate events) in order to get more data +- Events are being copied between relays, oftentimes to many different relays ### Purposes @@ -52,9 +50,9 @@ Authors may post events outside of the feed that they wish their followers to fo It is suggested that relays allow any user to write their own kind `10002` event (optionally with AUTH to verify it is their own) even if they are not otherwise subscribed to the relay because - - finding where someone posts is rather important - - these events do not have content that needs management - - relays only need to store one replaceable event per pubkey to offer this service +- finding where someone posts is rather important +- these events do not have content that needs management +- relays only need to store one replaceable event per pubkey to offer this service ### Why not in kind `0` Metadata diff --git a/78.md b/78.md index 10ff5358..fb1dc45e 100644 --- a/78.md +++ b/78.md @@ -1,8 +1,6 @@ -NIP-78 -====== +# NIP-78 -Arbitrary custom app data -------------------------- +## Arbitrary custom app data `draft` `optional` `author:sandwich` `author:fiatjaf` @@ -16,6 +14,6 @@ This NIP specifies the use of event kind `30078` (parameterized replaceable even ## Some use cases - - User personal settings on Nostr clients (and other apps unrelated to Nostr) - - A way for client developers to propagate dynamic parameters to users without these having to update - - Personal private data generated by apps that have nothing to do with Nostr, but allow users to use Nostr relays as their personal database +- User personal settings on Nostr clients (and other apps unrelated to Nostr) +- A way for client developers to propagate dynamic parameters to users without these having to update +- Personal private data generated by apps that have nothing to do with Nostr, but allow users to use Nostr relays as their personal database