"], 56 | ["thumb", "<thumbnail image for video>"], 57 | ["published_at", "<unix timestamp>"], 58 | ["alt", <description>], 59 | 60 | // Video Data 61 | ["url",<string with URI of file>], 62 | ["m", <MIME type>], 63 | ["x",<Hash SHA-256>], 64 | ["size", <size of file in bytes>], 65 | ["duration", <duration of video in seconds>], 66 | ["dim", <size of file in pixels>], 67 | ["magnet",<magnet URI> ], 68 | ["i",<torrent infohash>], 69 | ["text-track", "<encoded `kind 6000` event>", "<recommended relay urls>"], 70 | ["content-warning", "<reason>"], 71 | ["segment", <start>, <end>, "<title>", "<thumbnail URL>"], 72 | 73 | // Participants 74 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"], 75 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"], 76 | 77 | // Hashtags 78 | ["t", "<tag>"], 79 | ["t", "<tag>"], 80 | 81 | // Reference links 82 | ["r", "<url>"], 83 | ["r", "<url>"] 84 | ] 85 | } 86 | ``` 87 | 88 | ## Video View 89 | 90 | A video event view is a response to a video event to track a user's view or progress viewing the video. 91 | 92 | ### Format 93 | 94 | The format uses a parameterized replaceable event kind `34237`. 95 | 96 | The `.content` of these events is optional and could be a free-form note that acts like a bookmark for the user. 97 | 98 | The list of tags are as follows: 99 | * `a` (required) reference tag to kind `34235` or `34236` video event being viewed 100 | * `d` (required) same as `a` reference tag value 101 | * `viewed` (optional, repeated) timestamp of the user's start time in seconds, timestamp of the user's end time in seconds 102 | 103 | 104 | ```json 105 | { 106 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 107 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 108 | "created_at": <Unix timestamp in seconds>, 109 | "kind": 34237, 110 | "content": "<note>", 111 | "tags": [ 112 | ["a", "<34235 | 34236>:<video event author pubkey>:<d-identifier of video event>", "<optional relay url>"], 113 | ["e", "<event-id", "<relay-url>"] 114 | ["d", "<34235 | 34236>:<video event author pubkey>:<d-identifier of video event>"], 115 | ["viewed", <start>, <end>], 116 | ] 117 | } 118 | ``` 119 | -------------------------------------------------------------------------------- /05.md: -------------------------------------------------------------------------------- 1 | NIP-05 2 | ====== 3 | 4 | Mapping Nostr keys to DNS-based internet identifiers 5 | ---------------------------------------------------- 6 | 7 | `final` `optional` 8 | 9 | On events of kind `0` (`user metadata`) one can specify the key `"nip05"` with an [internet identifier](https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1) (an email-like address) as the value. Although there is a link to a very liberal "internet identifier" specification above, NIP-05 assumes the `<local-part>` part will be restricted to the characters `a-z0-9-_.`, case-insensitive. 10 | 11 | Upon seeing that, the client splits the identifier into `<local-part>` and `<domain>` and use these values to make a GET request to `https://<domain>/.well-known/nostr.json?name=<local-part>`. 12 | 13 | The result should be a JSON document object with a key `"names"` that should then be a mapping of names to hex formatted public keys. If the public key for the given `<name>` matches the `pubkey` from the `user's metadata` event, the client then concludes that the given pubkey can indeed be referenced by its identifier. 14 | 15 | ### Example 16 | 17 | If a client sees an event like this: 18 | 19 | ```json 20 | { 21 | "pubkey": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9", 22 | "kind": 0, 23 | "content": "{\"name\": \"bob\", \"nip05\": \"bob@example.com\"}" 24 | ... 25 | } 26 | ``` 27 | 28 | It will make a GET request to `https://example.com/.well-known/nostr.json?name=bob` and get back a response that will look like 29 | 30 | ```json 31 | { 32 | "names": { 33 | "bob": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9" 34 | } 35 | } 36 | ```` 37 | 38 | or with the **recommended** `"relays"` attribute: 39 | 40 | ```json 41 | { 42 | "names": { 43 | "bob": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9" 44 | }, 45 | "relays": { 46 | "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9": [ "wss://relay.example.com", "wss://relay2.example.com" ] 47 | } 48 | } 49 | ```` 50 | 51 | If the pubkey matches the one given in `"names"` (as in the example above) that means the association is right and the `"nip05"` identifier is valid and can be displayed. 52 | 53 | The recommended `"relays"` attribute may contain an object with public keys as properties and arrays of relay URLs as values. When present, that can be used to help clients learn in which relays the specific user may be found. Web servers which serve `/.well-known/nostr.json` files dynamically based on the query string SHOULD also serve the relays data for any name they serve in the same reply when that is available. 54 | 55 | ## Finding users from their NIP-05 identifier 56 | 57 | A client may implement support for finding users' public keys from _internet identifiers_, the flow is the same as above, but reversed: first the client fetches the _well-known_ URL and from there it gets the public key of the user, then it tries to fetch the kind `0` event for that user and check if it has a matching `"nip05"`. 58 | 59 | ## Notes 60 | 61 | ### Clients must always follow public keys, not NIP-05 addresses 62 | 63 | For example, if after finding that `bob@bob.com` has the public key `abc...def`, the user clicks a button to follow that profile, the client must keep a primary reference to `abc...def`, not `bob@bob.com`. If, for any reason, the address `https://bob.com/.well-known/nostr.json?name=bob` starts returning the public key `1d2...e3f` at any time in the future, the client must not replace `abc...def` in his list of followed profiles for the user (but it should stop displaying "bob@bob.com" for that user, as that will have become an invalid `"nip05"` property). 64 | 65 | ### Public keys must be in hex format 66 | 67 | Keys must be returned in hex format. Keys in NIP-19 `npub` format are only meant to be used for display in client UIs, not in this NIP. 68 | 69 | ### User Discovery implementation suggestion 70 | 71 | A client can also use this to allow users to search other profiles. If a client has a search box or something like that, a user may be able to type "bob@example.com" there and the client would recognize that and do the proper queries to obtain a pubkey and suggest that to the user. 72 | 73 | ### Showing just the domain as an identifier 74 | 75 | Clients may treat the identifier `_@domain` as the "root" identifier, and choose to display it as just the `<domain>`. For example, if Bob owns `bob.com`, he may not want an identifier like `bob@bob.com` as that is redundant. Instead, Bob can use the identifier `_@bob.com` and expect Nostr clients to show and treat that as just `bob.com` for all purposes. 76 | 77 | ### Reasoning for the `/.well-known/nostr.json?name=<local-part>` format 78 | 79 | By adding the `<local-part>` as a query string instead of as part of the path, the protocol can support both dynamic servers that can generate JSON on-demand and static servers with a JSON file in it that may contain multiple names. 80 | 81 | ### Allowing access from JavaScript apps 82 | 83 | JavaScript Nostr apps may be restricted by browser [CORS][] policies that prevent them from accessing `/.well-known/nostr.json` on the user's domain. When CORS prevents JS from loading a resource, the JS program sees it as a network failure identical to the resource not existing, so it is not possible for a pure-JS app to tell the user for certain that the failure was caused by a CORS issue. JS Nostr apps that see network failures requesting `/.well-known/nostr.json` files may want to recommend to users that they check the CORS policy of their servers, e.g.: 84 | 85 | ```bash 86 | $ curl -sI https://example.com/.well-known/nostr.json?name=bob | grep -i ^Access-Control 87 | Access-Control-Allow-Origin: * 88 | ``` 89 | 90 | Users should ensure that their `/.well-known/nostr.json` is served with the HTTP header `Access-Control-Allow-Origin: *` to ensure it can be validated by pure JS apps running in modern browsers. 91 | 92 | [CORS]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS 93 | 94 | ### Security Constraints 95 | 96 | The `/.well-known/nostr.json` endpoint MUST NOT return any HTTP redirects. 97 | 98 | Fetchers MUST ignore any HTTP redirects given by the `/.well-known/nostr.json` endpoint. 99 | -------------------------------------------------------------------------------- /BREAKING.md: -------------------------------------------------------------------------------- 1 | # Breaking Changes 2 | 3 | This is a history of NIP changes that potentially break pre-existing implementations, in 4 | reverse chronological order. 5 | 6 | | Date | Commit | NIP | Change | 7 | | ----------- | --------- | -------- | ------ | 8 | | 2024-06-06 | [58e94b20](https://github.com/nostr-protocol/nips/commit/58e94b20) | [NIP-25](25.md) | [8073c848](https://github.com/nostr-protocol/nips/commit/8073c848) was reverted | 9 | | 2024-06-06 | [a6dfc7b5](https://github.com/nostr-protocol/nips/commit/a6dfc7b5) | [NIP-55](55.md) | NIP number was changed | 10 | | 2024-05-25 | [5d1d1c17](https://github.com/nostr-protocol/nips/commit/5d1d1c17) | [NIP-71](71.md) | 'aes-256-gcm' tag was removed | 11 | | 2024-05-07 | [8073c848](https://github.com/nostr-protocol/nips/commit/8073c848) | [NIP-25](25.md) | e-tags were changed to not include entire thread | 12 | | 2024-04-30 | [bad88262](https://github.com/nostr-protocol/nips/commit/bad88262) | [NIP-34](34.md) | 'earliest-unique-commit' tag was removed (use 'r' tag instead) | 13 | | 2024-02-25 | [4a171cb0](https://github.com/nostr-protocol/nips/commit/4a171cb0) | [NIP-18](18.md) | quote repost should use `q` tag | 14 | | 2024-02-21 | [c6cd655c](https://github.com/nostr-protocol/nips/commit/c6cd655c) | [NIP-46](46.md) | Params were stringified | 15 | | 2024-02-16 | [cbec02ab](https://github.com/nostr-protocol/nips/commit/cbec02ab) | [NIP-49](49.md) | Password first normalized to NFKC | 16 | | 2024-02-15 | [afbb8dd0](https://github.com/nostr-protocol/nips/commit/afbb8dd0) | [NIP-39](39.md) | PGP identity was removed | 17 | | 2024-02-07 | [d3dad114](https://github.com/nostr-protocol/nips/commit/d3dad114) | [NIP-46](46.md) | Connection token format was changed | 18 | | 2024-01-30 | [1a2b21b6](https://github.com/nostr-protocol/nips/commit/1a2b21b6) | [NIP-59](59.md) | 'p' tag became optional | 19 | | 2023-01-27 | [c2f34817](https://github.com/nostr-protocol/nips/commit/c2f34817) | [NIP-47](47.md) | optional expiration tag should be honored | 20 | | 2024-01-10 | [3d8652ea](https://github.com/nostr-protocol/nips/commit/3d8652ea) | [NIP-02](02.md) | list entries should be chronological | 21 | | 2024-01-10 | [3d8652ea](https://github.com/nostr-protocol/nips/commit/3d8652ea) | [NIP-51](51.md) | list entries should be chronological | 22 | | 2023-12-30 | [29869821](https://github.com/nostr-protocol/nips/commit/29869821) | [NIP-52](52.md) | 'name' tag was removed (use 'title' tag instead) | 23 | | 2023-12-27 | [17c67ef5](https://github.com/nostr-protocol/nips/commit/17c67ef5) | [NIP-94](94.md) | 'aes-256-gcm' tag was removed | 24 | | 2023-12-03 | [0ba45895](https://github.com/nostr-protocol/nips/commit/0ba45895) | [NIP-01](01.md) | WebSocket status code `4000` was replaced by 'CLOSED' message | 25 | | 2023-11-28 | [6de35f9e](https://github.com/nostr-protocol/nips/commit/6de35f9e) | [NIP-89](89.md) | 'client' tag value was changed | 26 | | 2023-11-20 | [7822a8b1](https://github.com/nostr-protocol/nips/commit/7822a8b1) | [NIP-51](51.md) | `kind: 30000` and `kind: 30001` were deprecated | 27 | | 2023-11-11 | [cbdca1e9](https://github.com/nostr-protocol/nips/commit/cbdca1e9) | [NIP-84](84.md) | 'range' tag was removed | 28 | | 2023-11-10 | [c945d8bd](https://github.com/nostr-protocol/nips/commit/c945d8bd) | [NIP-32](32.md) | 'l' tag annotations was removed | 29 | | 2023-11-07 | [108b7f16](https://github.com/nostr-protocol/nips/commit/108b7f16) | [NIP-01](01.md) | 'OK' message must have 4 items | 30 | | 2023-10-17 | [cf672b76](https://github.com/nostr-protocol/nips/commit/cf672b76) | [NIP-03](03.md) | 'block' tag was removed | 31 | | 2023-09-29 | [7dc6385f](https://github.com/nostr-protocol/nips/commit/7dc6385f) | [NIP-57](57.md) | optional 'a' tag was included in `zap receipt` | 32 | | 2023-08-21 | [89915e02](https://github.com/nostr-protocol/nips/commit/89915e02) | [NIP-11](11.md) | 'min_prefix' was removed | 33 | | 2023-08-20 | [37c4375e](https://github.com/nostr-protocol/nips/commit/37c4375e) | [NIP-01](01.md) | replaceable events with same timestamp should be retained event with lowest id | 34 | | 2023-08-15 | [88ee873c](https://github.com/nostr-protocol/nips/commit/88ee873c) | [NIP-15](15.md) | 'countries' tag was renamed to 'regions' | 35 | | 2023-08-14 | [72bb8a12](https://github.com/nostr-protocol/nips/commit/72bb8a12) | [NIP-12](12.md) | NIP-12, 16, 20 and 33 were merged into NIP-01 | 36 | | 2023-08-14 | [72bb8a12](https://github.com/nostr-protocol/nips/commit/72bb8a12) | [NIP-16](16.md) | NIP-12, 16, 20 and 33 were merged into NIP-01 | 37 | | 2023-08-14 | [72bb8a12](https://github.com/nostr-protocol/nips/commit/72bb8a12) | [NIP-20](20.md) | NIP-12, 16, 20 and 33 were merged into NIP-01 | 38 | | 2023-08-14 | [72bb8a12](https://github.com/nostr-protocol/nips/commit/72bb8a12) | [NIP-33](33.md) | NIP-12, 16, 20 and 33 were merged into NIP-01 | 39 | | 2023-08-11 | [d87f8617](https://github.com/nostr-protocol/nips/commit/d87f8617) | [NIP-25](25.md) | empty `content` should be considered as "+" | 40 | | 2023-08-01 | [5d63b157](https://github.com/nostr-protocol/nips/commit/5d63b157) | [NIP-57](57.md) | 'zap' tag was changed | 41 | | 2023-07-15 | [d1814405](https://github.com/nostr-protocol/nips/commit/d1814405) | [NIP-01](01.md) | `since` and `until` filters should be `since <= created_at <= until` | 42 | | 2023-07-12 | [a1cd2bd8](https://github.com/nostr-protocol/nips/commit/a1cd2bd8) | [NIP-25](25.md) | custom emoji was supported | 43 | | 2023-06-18 | [83cbd3e1](https://github.com/nostr-protocol/nips/commit/83cbd3e1) | [NIP-11](11.md) | 'image' was renamed to 'icon' | 44 | | 2023-04-13 | [bf0a0da6](https://github.com/nostr-protocol/nips/commit/bf0a0da6) | [NIP-15](15.md) | different NIP was re-added as NIP-15 | 45 | | 2023-04-09 | [fb5b7c73](https://github.com/nostr-protocol/nips/commit/fb5b7c73) | [NIP-15](15.md) | NIP-15 was merged into NIP-01 | 46 | | 2023-03-15 | [e1004d3d](https://github.com/nostr-protocol/nips/commit/e1004d3d) | [NIP-19](19.md) | `1: relay` was changed to optionally | 47 | 48 | Breaking changes prior to 2023-03-01 are not yet documented. 49 | 50 | ## NOTES 51 | 52 | - If it isn't clear that a change is breaking or not, we list it. 53 | - The date is the date it was merged, not necessarily the date of the commit. 54 | 55 | -------------------------------------------------------------------------------- /89.md: -------------------------------------------------------------------------------- 1 | NIP-89 2 | ====== 3 | 4 | Recommended Application Handlers 5 | -------------------------------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP describes `kind:31989` and `kind:31990`: a way to discover applications that can handle unknown event-kinds. 10 | 11 | ## Rationale 12 | 13 | Nostr's discoverability and transparent event interaction is one of its most interesting/novel mechanics. 14 | This NIP provides a simple way for clients to discover applications that handle events of a specific kind to ensure smooth cross-client and cross-kind interactions. 15 | 16 | ### Parties involved 17 | 18 | There are three actors to this workflow: 19 | 20 | * application that handles a specific event kind (note that an application doesn't necessarily need to be a distinct entity and it could just be the same pubkey as user A) 21 | * Publishes `kind:31990`, detailing how apps should redirect to it 22 | * user A, who recommends an app that handles a specific event kind 23 | * Publishes `kind:31989` 24 | * user B, who seeks a recommendation for an app that handles a specific event kind 25 | * Queries for `kind:31989` and, based on results, queries for `kind:31990` 26 | 27 | ## Events 28 | 29 | ### Recommendation event 30 | ```json 31 | { 32 | "kind": 31989, 33 | "pubkey": <recommender-user-pubkey>, 34 | "tags": [ 35 | ["d", <supported-event-kind>], 36 | ["a", "31990:app1-pubkey:<d-identifier>", "wss://relay1", "ios"], 37 | ["a", "31990:app2-pubkey:<d-identifier>", "wss://relay2", "web"] 38 | ] 39 | } 40 | ``` 41 | 42 | The `d` tag in `kind:31989` is the supported event kind this event is recommending. 43 | 44 | Multiple `a` tags can appear on the same `kind:31989`. 45 | 46 | The second value of the tag SHOULD be a relay hint. 47 | The third value of the tag SHOULD be the platform where this recommendation might apply. 48 | 49 | ## Handler information 50 | ```json 51 | { 52 | "kind": 31990, 53 | "pubkey": "<application-pubkey>", 54 | "content": "<optional-kind:0-style-metadata>", 55 | "tags": [ 56 | ["d", <random-id>], 57 | ["k", <supported-event-kind>], 58 | ["web", "https://..../a/<bech32>", "nevent"], 59 | ["web", "https://..../p/<bech32>", "nprofile"], 60 | ["web", "https://..../e/<bech32>"], 61 | ["ios", ".../<bech32>"] 62 | ] 63 | } 64 | ``` 65 | 66 | * `content` is an optional `metadata`-like stringified JSON object, as described in NIP-01. This content is useful when the pubkey creating the `kind:31990` is not an application. If `content` is empty, the `kind:0` of the pubkey should be used to display application information (e.g. name, picture, web, LUD16, etc.) 67 | * `k` tags' value is the event kind that is supported by this `kind:31990`. 68 | Using a `k` tag(s) (instead of having the kind of the `d` tag) provides: 69 | * Multiple `k` tags can exist in the same event if the application supports more than one event kind and their handler URLs are the same. 70 | * The same pubkey can have multiple events with different apps that handle the same event kind. 71 | * `bech32` in a URL MUST be replaced by clients with the NIP-19-encoded entity that should be loaded by the application. 72 | 73 | Multiple tags might be registered by the app, following NIP-19 nomenclature as the second value of the array. 74 | 75 | A tag without a second value in the array SHOULD be considered a generic handler for any NIP-19 entity that is not handled by a different tag. 76 | 77 | # Client tag 78 | When publishing events, clients MAY include a `client` tag. Identifying the client that published the note. This tag is a tuple of `name`, `address` identifying a handler event and, a relay `hint` for finding the handler event. This has privacy implications for users, so clients SHOULD allow users to opt-out of using this tag. 79 | 80 | ```json 81 | { 82 | "kind": 1, 83 | "tags": [ 84 | ["client", "My Client", "31990:app1-pubkey:<d-identifier>", "wss://relay1"] 85 | ] 86 | ... 87 | } 88 | ``` 89 | 90 | ## User flow 91 | A user A who uses a non-`kind:1`-centric nostr app could choose to announce/recommend a certain kind-handler application. 92 | 93 | When user B sees an unknown event kind, e.g. in a social-media centric nostr client, the client would allow user B to interact with the unknown-kind event (e.g. tapping on it). 94 | 95 | The client MIGHT query for the user's and the user's follows handler. 96 | 97 | ## Example 98 | 99 | ### User A recommends a `kind:31337`-handler 100 | User A might be a user of Zapstr, a `kind:31337`-centric client (tracks). Using Zapstr, user A publishes an event recommending Zapstr as a `kind:31337`-handler. 101 | 102 | ```json 103 | { 104 | "kind": 31989, 105 | "tags": [ 106 | ["d", "31337"], 107 | ["a", "31990:1743058db7078661b94aaf4286429d97ee5257d14a86d6bfa54cb0482b876fb0:abcd", <relay-url>, "web"] 108 | ], 109 | ... 110 | } 111 | ``` 112 | 113 | ### User B interacts with a `kind:31337`-handler 114 | User B might see in their timeline an event referring to a `kind:31337` event (e.g. a `kind:1` tagging a `kind:31337`). 115 | 116 | User B's client, not knowing how to handle a `kind:31337` might display the event using its `alt` tag (as described in NIP-31). When the user clicks on the event, the application queries for a handler for this `kind`: 117 | 118 | ```json 119 | ["REQ", <id>, { "kinds": [31989], "#d": ["31337"], "authors": [<user>, <users-contact-list>] }] 120 | ``` 121 | 122 | User B, who follows User A, sees that `kind:31989` event and fetches the `a`-tagged event for the app and handler information. 123 | 124 | User B's client sees the application's `kind:31990` which includes the information to redirect the user to the relevant URL with the desired entity replaced in the URL. 125 | 126 | ### Alternative query bypassing `kind:31989` 127 | Alternatively, users might choose to query directly for `kind:31990` for an event kind. Clients SHOULD be careful doing this and use spam-prevention mechanisms or querying high-quality restricted relays to avoid directing users to malicious handlers. 128 | 129 | ```json 130 | ["REQ", <id>, { "kinds": [31990], "#k": [<desired-event-kind>], "authors": [...] }] 131 | ``` 132 | -------------------------------------------------------------------------------- /34.md: -------------------------------------------------------------------------------- 1 | NIP-34 2 | ====== 3 | 4 | `git` stuff 5 | ----------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines all the ways code collaboration using and adjacent to [`git`](https://git-scm.com/) can be done using Nostr. 10 | 11 | ## Repository announcements 12 | 13 | Git repositories are hosted in Git-enabled servers, but their existence can be announced using Nostr events, as well as their willingness to receive patches, bug reports and comments in general. 14 | 15 | ```jsonc 16 | { 17 | "kind": 30617, 18 | "content": "", 19 | "tags": [ 20 | ["d", "<repo-id>"], // usually kebab-case short name 21 | ["name", "<human-readable project name>"], 22 | ["description", "brief human-readable project description>"], 23 | ["web", "<url for browsing>", ...], // a webpage url, if the git server being used provides such a thing 24 | ["clone", "<url for git-cloning>", ...], // a url to be given to `git clone` so anyone can clone it 25 | ["relays", "<relay-url>", ...] // relays that this repository will monitor for patches and issues 26 | ["r", "<earliest-unique-commit-id>", "euc"] 27 | ["maintainers", "<other-recognized-maintainer>", ...] 28 | ] 29 | } 30 | ``` 31 | 32 | The tags `web`, `clone`, `relays`, `maintainers` can have multiple values. 33 | 34 | The `r` tag annotated with the `"euc"` marker should be the commit ID of the earliest unique commit of this repo, made to identify it among forks and group it with other repositories hosted elsewhere that may represent essentially the same project. In most cases it will be the root commit of a repository. In case of a permanent fork between two projects, then the first commit after the fork should be used. 35 | 36 | Except `d`, all tags are optional. 37 | 38 | ## Patches 39 | 40 | Patches can be sent by anyone to any repository. Patches to a specific repository SHOULD be sent to the relays specified in that repository's announcement event's `"relays"` tag. Patch events SHOULD include an `a` tag pointing to that repository's announcement address. 41 | 42 | Patches in a patch set SHOULD include a NIP-10 `e` `reply` tag pointing to the previous patch. 43 | 44 | The first patch revision in a patch revision SHOULD include a NIP-10 `e` `reply` to the original root patch. 45 | 46 | ```jsonc 47 | { 48 | "kind": 1617, 49 | "content": "<patch>", // contents of <git format-patch> 50 | "tags": [ 51 | ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"], 52 | ["r", "<earliest-unique-commit-id-of-repo>"] // so clients can subscribe to all patches sent to a local git repo 53 | ["p", "<repository-owner>"], 54 | ["p", "<other-user>"], // optionally send the patch to another user to bring it to their attention 55 | 56 | ["t", "root"], // ommited for additional patches in a series 57 | // for the first patch in a revision 58 | ["t", "root-revision"], 59 | 60 | // optional tags for when it is desirable that the merged patch has a stable commit id 61 | // these fields are necessary for ensuring that the commit resulting from applying a patch 62 | // has the same id as it had in the proposer's machine -- all these tags can be omitted 63 | // if the maintainer doesn't care about these things 64 | ["commit", "<current-commit-id>"], 65 | ["r", "<current-commit-id>"] // so clients can find existing patches for a specific commit 66 | ["parent-commit", "<parent-commit-id>"], 67 | ["commit-pgp-sig", "-----BEGIN PGP SIGNATURE-----..."], // empty string for unsigned commit 68 | ["committer", "<name>", "<email>", "<timestamp>", "<timezone offset in minutes>"], 69 | ] 70 | } 71 | ``` 72 | 73 | The first patch in a series MAY be a cover letter in the format produced by `git format-patch`. 74 | 75 | ## Issues 76 | 77 | Issues are Markdown text that is just human-readable conversational threads related to the repository: bug reports, feature requests, questions or comments of any kind. Like patches, these SHOULD be sent to the relays specified in that repository's announcement event's `"relays"` tag. 78 | 79 | ```jsonc 80 | { 81 | "kind": 1621, 82 | "content": "<markdown text>", 83 | "tags": [ 84 | ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"], 85 | ["p", "<repository-owner>"] 86 | ] 87 | } 88 | ``` 89 | 90 | ## Replies 91 | 92 | Replies are also Markdown text. The difference is that they MUST be issued as replies to either a `kind:1621` _issue_ or a `kind:1617` _patch_ event. The threading of replies and patches should follow NIP-10 rules. 93 | 94 | ```jsonc 95 | { 96 | "kind": 1622, 97 | "content": "<markdown text>", 98 | "tags": [ 99 | ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"], 100 | ["e", "<issue-or-patch-id-hex>", "", "root"], 101 | 102 | // other "e" and "p" tags should be applied here when necessary, following the threading rules of NIP-10 103 | ["p", "<patch-author-pubkey-hex>", "", "mention"], 104 | ["e", "<previous-reply-id-hex>", "", "reply"], 105 | // ... 106 | ] 107 | } 108 | ``` 109 | 110 | ## Status 111 | 112 | Root Patches and Issues have a Status that defaults to 'Open' and can be set by issuing Status events. 113 | 114 | ```jsonc 115 | { 116 | "kind": 1630, // Open 117 | "kind": 1631, // Applied / Merged for Patches; Resolved for Issues 118 | "kind": 1632, // Closed 119 | "kind": 1633, // Draft 120 | "content": "<markdown text>", 121 | "tags": [ 122 | ["e", "<issue-or-original-root-patch-id-hex>", "", "root"], 123 | ["e", "<accepted-revision-root-id-hex>", "", "reply"], // for when revisions applied 124 | ["p", "<repository-owner>"], 125 | ["p", "<root-event-author>"], 126 | ["p", "<revision-author>"], 127 | 128 | // optional for improved subscription filter efficiency 129 | ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"], 130 | ["r", "<earliest-unique-commit-id-of-repo>"] 131 | 132 | // optional for `1631` status 133 | ["e", "<applied-or-merged-patch-event-id>", "", "mention"], // for each 134 | // when merged 135 | ["merge-commit", "<merge-commit-id>"] 136 | ["r", "<merge-commit-id>"] 137 | // when applied 138 | ["applied-as-commits", "<commit-id-in-master-branch>", ...] 139 | ["r", "<applied-commit-id>"] // for each 140 | ] 141 | } 142 | ``` 143 | 144 | The Status event with the largest created_at date is valid. 145 | 146 | The Status of a patch-revision defaults to either that of the root-patch, or `1632` (Closed) if the root-patch's Status is `1631` and the patch-revision isn't tagged in the `1631` event. 147 | 148 | 149 | ## Possible things to be added later 150 | 151 | - "branch merge" kind (specifying a URL from where to fetch the branch to be merged) 152 | - inline file comments kind (we probably need one for patches and a different one for merged files) 153 | -------------------------------------------------------------------------------- /54.md: -------------------------------------------------------------------------------- 1 | NIP-54 2 | ====== 3 | 4 | Wiki 5 | ---- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines `kind:30818` (a _parameterized replaceable event_) for long-form text content similar to [NIP-23](23.md), but with one important difference: articles are meant to be descriptions, or encyclopedia entries, of particular subjects, and it's expected that multiple people will write articles about the exact same subjects, with either small variations or completely independent content. 10 | 11 | Articles are identified by lowercase, normalized ascii `d` tags. 12 | 13 | ### Articles 14 | ```jsonc 15 | { 16 | "content": "A wiki is a hypertext publication collaboratively edited and managed by its own audience.", 17 | "tags": [ 18 | ["d", "wiki"], 19 | ["title", "Wiki"], 20 | ] 21 | } 22 | ``` 23 | 24 | ### `d` tag normalization rules 25 | 26 | - Any non-letter character MUST be converted to a `-`. 27 | - All letters MUST be converted to lowercase. 28 | 29 | ### Content rules 30 | 31 | The content should be Markdown, following the same rules as of [NIP-23](23.md), although it takes some extra (optional) metadata tags: 32 | 33 | - `title`: for when the display title should be different from the `d` tag. 34 | - `summary`: for display in lists. 35 | - `a` and `e`: for referencing the original event a wiki article was forked from. 36 | 37 | One extra functionality is added: **wikilinks**. Unlike normal Markdown links `[]()` that link to webpages, wikilinks `[[]]` link to other articles in the wiki. In this case, the wiki is the entirety of Nostr. Clicking on a wikilink should cause the client to ask relays for events with `d` tags equal to the target of that wikilink. 38 | 39 | Wikilinks can take these two forms: 40 | 41 | 1. `[[Target Page]]` -- in this case it will link to the page `target-page` (according to `d` tag normalization rules above) and be displayed as `Target Page`; 42 | 2. `[[target page|see this]]` -- in this case it will link to the page `target-page`, but will be displayed as `see this`. 43 | 44 | ### Merge Requests 45 | 46 | Event `kind:818` represents a request to merge from a forked article into the source. It is directed to a pubkey and references the original article and the modified event. 47 | 48 | [INSERT EVENT EXAMPLE] 49 | 50 | ### Redirects 51 | 52 | Event `kind:30819` is also defined to stand for "wiki redirects", i.e. if one thinks `Shell structure` should redirect to `Thin-shell structure` they can issue one of these events instead of replicating the content. These events can be used for automatically redirecting between articles on a client, but also for generating crowdsourced "disambiguation" pages ([common in Wikipedia](https://en.wikipedia.org/wiki/Help:Disambiguation)). 53 | 54 | [INSERT EVENT EXAMPLE] 55 | 56 | How to decide what article to display 57 | ------------------------------------- 58 | 59 | As there could be many articles for each given name, some kind of prioritization must be done by clients. Criteria for this should vary between users and clients, but some means that can be used are described below: 60 | 61 | ### Reactions 62 | 63 | [NIP-25](25.md) reactions are very simple and can be used to create a simple web-of-trust between wiki article writers and their content. While just counting a raw number of "likes" is unproductive, reacting to any wiki article event with a `+` can be interpreted as a recommendation for that article specifically and a partial recommendation of the author of that article. When 2 or 3-level deep recommendations are followed, suddenly a big part of all the articles may have some form of tagging. 64 | 65 | ### Relays 66 | 67 | [NIP-51](51.md) lists of relays can be created with the kind 10102 and then used by wiki clients in order to determine where to query articles first and to rank these differently in relation to other events fetched from other relays. 68 | 69 | ### Contact lists 70 | 71 | [NIP-02](02.md) contact lists can form the basis of a recommendation system that is then expanded with relay lists and reaction lists through nested queries. These lists form a good starting point only because they are so widespread. 72 | 73 | ### Wiki-related contact lists 74 | 75 | [NIP-51](51.md) lists can also be used to create a list of users that are trusted only in the context of wiki authorship or wiki curationship. 76 | 77 | Forks 78 | --------- 79 | Wiki-events can tag other wiki-events with a `fork` marker to specify that this event came from a different version. Both `a` and `e` tags SHOULD be used and have the `fork` marker applied, to identify the exact version it was forked from. 80 | 81 | Deference 82 | --------- 83 | Wiki-events can tag other wiki-events with a `defer` marker to indicate that it considers someone else's entry as a "better" version of itself. If using a `defer` marker both `a` and `e` tags SHOULD be used. 84 | 85 | This is a stronger signal of trust than a `+` reaction. 86 | 87 | This marker is useful when a user edits someone else's entry; if the original author includes the editor's changes and the editor doesn't want to keep/maintain an independent version, the `link` tag could effectively be a considered a "deletion" of the editor's version and putting that pubkey's WoT weight behind the original author's version. 88 | 89 | Why Markdown? 90 | ------------- 91 | 92 | If the idea is to make a wiki then the most obvious text format to use is probably the mediawiki/wikitext format used by Wikipedia since it's widely deployed in all mediawiki installations and used for decades with great success. However, it turns out that format is very bloated and convoluted, has way too many features and probably because of that it doesn't have many alternative implementations out there, and the ones that exist are not complete and don't look very trustworthy. Also it is very much a centralized format that can probably be changed at the whims of the Wikipedia owners. 93 | 94 | On the other hand, Markdown has proven to work well for small scale wikis and one of the biggest wikis in the planet (which is not very often thought of as a wiki), [StackOverflow](https://stackoverflow.com) and its child sites, and also one of the biggest "personal wiki" software, [Obsidian](https://obsidian.md/). Markdown can probably deliver 95% of the functionality of wikitext. When augmented with tables, diagram generators and MathJax (which are common extensions that exist in the wild and can be included in this NIP) that rate probably goes to 99%, and its simplicity is a huge benefit that can't be overlooked. Wikitext format can also be transpíled into Markdown using Pandoc. Given all that, I think it's a reasonable suspicion that mediawiki is not inherently better than Markdown, the success of Wikipedia probably cannot be predicated on the syntax language choice. 95 | 96 | # Appendix 1: Merge requests 97 | Users can request other users to get their entries merged into someone else's entry by creating a `kind:818` event. 98 | 99 | ```jsonc 100 | { 101 | "content": "I added information about how to make hot ice-creams", 102 | "kind": 818, 103 | "tags": [ 104 | [ "a", "30818:<destination-pubkey>:hot-ice-creams", "<relay-url>" ], 105 | [ "e", "<version-against-which-the-modification-was-made>", "<relay-url>' ], 106 | [ "p", "<destination-pubkey>" ], 107 | [ "e", "<version-to-be-merged>", "<relay-url>", "source" ] 108 | ] 109 | } 110 | ``` 111 | 112 | `.content`: an optional explanation detailing why this merge is being requested. 113 | `a` tag: tag of the article which should be modified (i.e. the target of this merge request). 114 | `e` tag: optional version of the article in which this modifications is based 115 | `e` tag with `source` marker: the ID of the event that should be merged. This event id MUST be of a `kind:30818` as defined in this NIP. 116 | 117 | The destination-pubkey (the pubkey being requested to merge something into their article can create [[NIP-25]] reactions that tag the `kind:818` event with `+` or `-` 118 | -------------------------------------------------------------------------------- /29.md: -------------------------------------------------------------------------------- 1 | NIP-29 2 | ====== 3 | 4 | Relay-based Groups 5 | ------------------ 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines a standard for groups that are only writable by a closed set of users. They can be public for reading by external users or not. 10 | 11 | Groups are identified by a random string of any length that serves as an _id_. 12 | 13 | There is no way to create a group, what happens is just that relays (most likely when asked by users) will create rules around some specific ids so these ids can serve as an actual group, henceforth messages sent to that group will be subject to these rules. 14 | 15 | Normally a group will originally belong to one specific relay, but the community may choose to move the group to other relays or even fork the group so it exists in different forms -- still using the same _id_ -- across different relays. 16 | 17 | ## Relay-generated events 18 | 19 | Relays are supposed to generate the events that describe group metadata and group admins. These are parameterized replaceable events signed by the relay keypair directly, with the group _id_ as the `d` tag. 20 | 21 | ## Group identifier 22 | 23 | A group may be identified by a string in the format `<host>'<group-id>`. For example, a group with _id_ `abcdef` hosted at the relay `wss://groups.nostr.com` would be identified by the string `groups.nostr.com'abcdef`. 24 | 25 | ## The `h` tag 26 | 27 | Events sent by users to groups (chat messages, text notes, moderation events etc) must have an `h` tag with the value set to the group _id_. 28 | 29 | ## Timeline references 30 | 31 | In order to not be used out of context, events sent to these groups may contain references to previous events seen from the same relay in the `previous` tag. The choice of which previous events to pick belongs to the clients. The references are to be made using the first 8 characters (4 bytes) of any event in the last 50 events seen by the user in the relay, excluding events by themselves. There can be any number of references (including zero), but it's recommended that clients include at least 3 and that relays enforce this. 32 | 33 | This is a hack to prevent messages from being broadcasted to external relays that have forks of one group out of context. Relays are expected to reject any events that contain timeline references to events not found in their own database. Clients should also check these to keep relays honest about them. 34 | 35 | ## Late publication 36 | 37 | Relays should prevent late publication (messages published now with a timestamp from days or even hours ago) unless they are open to receive a group forked or moved from another relay. 38 | 39 | ## Event definitions 40 | 41 | - *text root note* (`kind:11`) 42 | 43 | This is the basic unit of a "microblog" root text note sent to a group. 44 | 45 | ```js 46 | "kind": 11, 47 | "content": "hello my friends lovers of pizza", 48 | "tags": [ 49 | ["h", "<group-id>"], 50 | ["previous", "<event-id-first-chars>", "<event-id-first-chars>", ...] 51 | ] 52 | ... 53 | ``` 54 | 55 | - *threaded text reply* (`kind:12`) 56 | 57 | This is the basic unit of a "microblog" reply note sent to a group. It's the same as `kind:11`, except for the fact that it must be used whenever it's in reply to some other note (either in reply to a `kind:11` or a `kind:12`). `kind:12` events SHOULD use NIP-10 markers, leaving an empty relay url: 58 | 59 | * `["e", "<kind-11-root-id>", "", "root"]` 60 | * `["e", "<kind-12-event-id>", "", "reply"]` 61 | 62 | - *chat message* (`kind:9`) 63 | 64 | This is the basic unit of a _chat message_ sent to a group. 65 | 66 | ```js 67 | "kind": 9, 68 | "content": "hello my friends lovers of pizza", 69 | "tags": [ 70 | ["h", "<group-id>"], 71 | ["previous", "<event-id-first-chars>", "<event-id-first-chars>", ...] 72 | ] 73 | ... 74 | ``` 75 | 76 | - *chat message threaded reply* (`kind:10`) 77 | 78 | Similar to `kind:12`, this is the basic unit of a chat message sent to a group. This is intended for in-chat threads that may be hidden by default. Not all in-chat replies MUST use `kind:10`, only when the intention is to create a hidden thread that isn't part of the normal flow of the chat (although clients are free to display those by default too). 79 | 80 | `kind:10` SHOULD use NIP-10 markers, just like `kind:12`. 81 | 82 | - *join request* (`kind:9021`) 83 | 84 | Any user can send one of these events to the relay in order to be automatically or manually added to the group. If the group is `open` the relay will automatically issue a `kind:9000` in response adding this user. Otherwise group admins may choose to query for these requests and act upon them. 85 | 86 | ```js 87 | { 88 | "kind": 9021, 89 | "content": "optional reason", 90 | "tags": [ 91 | ["h", "<group-id>"] 92 | ] 93 | } 94 | ``` 95 | 96 | - *moderation events* (`kinds:9000-9020`) (optional) 97 | 98 | Clients can send these events to a relay in order to accomplish a moderation action. Relays must check if the pubkey sending the event is capable of performing the given action. The relay may discard the event after taking action or keep it as a moderation log. 99 | 100 | ```js 101 | { 102 | "kind": 90xx, 103 | "content": "optional reason", 104 | "tags": [ 105 | ["h", "<group-id>"], 106 | ["previous", ...] 107 | ] 108 | } 109 | ``` 110 | 111 | Each moderation action uses a different kind and requires different arguments, which are given as tags. These are defined in the following table: 112 | 113 | | kind | name | tags | 114 | | --- | --- | --- | 115 | | 9000 | `add-user` | `p` (pubkey hex) | 116 | | 9001 | `remove-user` | `p` (pubkey hex) | 117 | | 9002 | `edit-metadata` | `name`, `about`, `picture` (string) | 118 | | 9003 | `add-permission` | `p` (pubkey), `permission` (name) | 119 | | 9004 | `remove-permission` | `p` (pubkey), `permission` (name) | 120 | | 9005 | `delete-event` | `e` (id hex) | 121 | | 9006 | `edit-group-status` | `public` or `private`, `open` or `closed` | 122 | | 9007 | `create-group` | | 123 | 124 | - *group metadata* (`kind:39000`) (optional) 125 | 126 | This event defines the metadata for the group -- basically how clients should display it. It must be generated and signed by the relay in which is found. Relays shouldn't accept these events if they're signed by anyone else. 127 | 128 | If the group is forked and hosted in multiple relays, there will be multiple versions of this event in each different relay and so on. 129 | 130 | ```js 131 | { 132 | "kind": 39000, 133 | "content": "", 134 | "tags": [ 135 | ["d", "<group-id>"], 136 | ["name", "Pizza Lovers"], 137 | ["picture", "https://pizza.com/pizza.png"], 138 | ["about", "a group for people who love pizza"], 139 | ["public"], // or ["private"] 140 | ["open"] // or ["closed"] 141 | ] 142 | ... 143 | } 144 | ``` 145 | 146 | `name`, `picture` and `about` are basic metadata for the group for display purposes. `public` signals the group can be _read_ by anyone, while `private` signals that only AUTHed users can read. `open` signals that anyone can request to join and the request will be automatically granted, while `closed` signals that members must be pre-approved or that requests to join will be manually handled. 147 | 148 | - *group admins* (`kind:39001`) (optional) 149 | 150 | Similar to the group metadata, this event is supposed to be generated by relays that host the group. 151 | 152 | Each admin gets a label that is only used for display purposes, and a list of permissions it has are listed afterwards. These permissions can inform client building UI, but ultimately are evaluated by the relay in order to become effective. 153 | 154 | The list of capabilities, as defined by this NIP, for now, is the following: 155 | 156 | - `add-user` 157 | - `edit-metadata` 158 | - `delete-event` 159 | - `remove-user` 160 | - `add-permission` 161 | - `remove-permission` 162 | - `edit-group-status` 163 | 164 | ```js 165 | { 166 | "kind": 39001, 167 | "content": "list of admins for the pizza lovers group", 168 | "tags": [ 169 | ["d", "<group-id>"], 170 | ["p", "<pubkey1-as-hex>", "ceo", "add-user", "edit-metadata", "delete-event", "remove-user"], 171 | ["p", "<pubkey2-as-hex>", "secretary", "add-user", "delete-event"] 172 | ] 173 | ... 174 | } 175 | ``` 176 | 177 | - *group members* (`kind:39002`) (optional) 178 | 179 | Similar to *group admins*, this event is supposed to be generated by relays that host the group. 180 | 181 | It's a NIP-51-like list of pubkeys that are members of the group. Relays might choose to not to publish this information or to restrict what pubkeys can fetch it. 182 | 183 | ```json 184 | { 185 | "kind": 39002, 186 | "content": "list of members for the pizza lovers group", 187 | "tags": [ 188 | ["d", "<group-id>"], 189 | ["p", "<admin1>"], 190 | ["p", "<member-pubkey1>"], 191 | ["p", "<member-pubkey2>"], 192 | ] 193 | } 194 | ``` 195 | 196 | ## Storing the list of groups a user belongs to 197 | 198 | A definition for kind `10009` was included in [NIP-51](51.md) that allows clients to store the list of groups a user wants to remember being in. 199 | -------------------------------------------------------------------------------- /17.md: -------------------------------------------------------------------------------- 1 | NIP-17 2 | ====== 3 | 4 | Private Direct Messages 5 | ----------------------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines an encrypted direct messaging scheme using [NIP-44](44.md) encryption and [NIP-59](59.md) seals and gift wraps. 10 | 11 | ## Direct Message Kind 12 | 13 | Kind `14` is a chat message. `p` tags identify one or more receivers of the message. 14 | 15 | ```js 16 | { 17 | "id": "<usual hash>", 18 | "pubkey": "<sender-pubkey>", 19 | "created_at": now(), 20 | "kind": 14, 21 | "tags": [ 22 | ["p", "<receiver-1-pubkey>", "<relay-url>"], 23 | ["p", "<receiver-2-pubkey>", "<relay-url>"], 24 | ["e", "<kind-14-id>", "<relay-url>", "reply"] // if this is a reply 25 | ["subject", "<conversation-title>"], 26 | ... 27 | ], 28 | "content": "<message-in-plain-text>", 29 | } 30 | ``` 31 | 32 | `.content` MUST be plain text. Fields `id` and `created_at` are required. 33 | 34 | Tags that mention, quote and assemble threading structures MUST follow [NIP-10](10.md). 35 | 36 | Kind `14`s MUST never be signed. If it is signed, the message might leak to relays and become **fully public**. 37 | 38 | ## Chat Rooms 39 | 40 | The set of `pubkey` + `p` tags defines a chat room. If a new `p` tag is added or a current one is removed, a new room is created with clean message history. 41 | 42 | Clients SHOULD render messages of the same room in a continuous thread. 43 | 44 | An optional `subject` tag defines the current name/topic of the conversation. Any member can change the topic by simply submitting a new `subject` to an existing `pubkey` + `p`-tags room. There is no need to send `subject` in every message. The newest `subject` in the thread is the subject of the conversation. 45 | 46 | ## Encrypting 47 | 48 | Following [NIP-59](59.md), the **unsigned** `kind:14` chat message must be sealed (`kind:13`) and then gift-wrapped (`kind:1059`) to each receiver and the sender individually. 49 | 50 | ```js 51 | { 52 | "id": "<usual hash>", 53 | "pubkey": randomPublicKey, 54 | "created_at": randomTimeUpTo2DaysInThePast(), 55 | "kind": 1059, // gift wrap 56 | "tags": [ 57 | ["p", receiverPublicKey, "<relay-url>"] // receiver 58 | ], 59 | "content": nip44Encrypt( 60 | { 61 | "id": "<usual hash>", 62 | "pubkey": senderPublicKey, 63 | "created_at": randomTimeUpTo2DaysInThePast(), 64 | "kind": 13, // seal 65 | "tags": [], // no tags 66 | "content": nip44Encrypt(unsignedKind14, senderPrivateKey, receiverPublicKey), 67 | "sig": "<signed by senderPrivateKey>" 68 | }, 69 | randomPrivateKey, receiverPublicKey 70 | ), 71 | "sig": "<signed by randomPrivateKey>" 72 | } 73 | ``` 74 | 75 | The encryption algorithm MUST use the latest version of [NIP-44](44.md). 76 | 77 | Clients MUST verify if pubkey of the `kind:13` is the same pubkey on the `kind:14`, otherwise any sender can impersonate others by simply changing the pubkey on `kind:14`. 78 | 79 | Clients SHOULD randomize `created_at` in up to two days in the past in both the seal and the gift wrap to make sure grouping by `created_at` doesn't reveal any metadata. 80 | 81 | The gift wrap's `p`-tag can be the receiver's main pubkey or an alias key created to receive DMs without exposing the receiver's identity. 82 | 83 | Clients CAN offer disappearing messages by setting an `expiration` tag in the gift wrap of each receiver or by not generating a gift wrap to the sender's public key 84 | 85 | ## Publishing 86 | 87 | Kind `10050` indicates the user's preferred relays to receive DMs. The event MUST include a list of `relay` tags with relay URIs. 88 | 89 | ```js 90 | { 91 | "kind": 10050, 92 | "tags": [ 93 | ["relay", "wss://inbox.nostr.wine"], 94 | ["relay", "wss://myrelay.nostr1.com"], 95 | ], 96 | "content": "", 97 | //...other fields 98 | } 99 | ``` 100 | 101 | Clients SHOULD publish kind `14` events to the `10050`-listed relays. If that is not found that indicates the user is not ready to receive messages under this NIP and clients shouldn't try. 102 | 103 | ## Relays 104 | 105 | It's advisable that relays do not serve `kind:14` to clients other than the ones tagged in them. 106 | 107 | It's advisable that users choose relays that conform to these practices. 108 | 109 | Clients SHOULD guide users to keep `kind:10050` lists small (1-3 relays) and SHOULD spread it to as many relays as viable. 110 | 111 | ## Benefits & Limitations 112 | 113 | This NIP offers the following privacy and security features: 114 | 115 | 1. **No Metadata Leak**: Participant identities, each message's real date and time, event kinds, and other event tags are all hidden from the public. Senders and receivers cannot be linked with public information alone. 116 | 2. **No Public Group Identifiers**: There is no public central queue, channel or otherwise converging identifier to correlate or count all messages in the same group. 117 | 3. **No Moderation**: There are no group admins: no invitations or bans. 118 | 4. **No Shared Secrets**: No secret must be known to all members that can leak or be mistakenly shared 119 | 5. **Fully Recoverable**: Messages can be fully recoverable by any client with the user's private key 120 | 6. **Optional Forward Secrecy**: Users and clients can opt-in for "disappearing messages". 121 | 7. **Uses Public Relays**: Messages can flow through public relays without loss of privacy. Private relays can increase privacy further, but they are not required. 122 | 8. **Cold Storage**: Users can unilaterally opt-in to sharing their messages with a separate key that is exclusive for DM backup and recovery. 123 | 124 | The main limitation of this approach is having to send a separate encrypted event to each receiver. Group chats with more than 100 participants should find a more suitable messaging scheme. 125 | 126 | ## Implementation 127 | 128 | Clients implementing this NIP should by default only connect to the set of relays found in their `kind:10050` list. From that they should be able to load all messages both sent and received as well as get new live updates, making it for a very simple and lightweight implementation that should be fast. 129 | 130 | When sending a message to anyone, clients must then connect to the relays in the receiver's `kind:10050` and send the events there, but can disconnect right after unless more messages are expected to be sent (e.g. the chat tab is still selected). Clients should also send a copy of their outgoing messages to their own `kind:10050` relay set. 131 | 132 | ## Examples 133 | 134 | This example sends the message `Hola, que tal?` from `nsec1w8udu59ydjvedgs3yv5qccshcj8k05fh3l60k9x57asjrqdpa00qkmr89m` to `nsec12ywtkplvyq5t6twdqwwygavp5lm4fhuang89c943nf2z92eez43szvn4dt`. 135 | 136 | The two final GiftWraps, one to the receiver and the other to the sender, are: 137 | 138 | ```json 139 | { 140 | "id":"2886780f7349afc1344047524540ee716f7bdc1b64191699855662330bf235d8", 141 | "pubkey":"8f8a7ec43b77d25799281207e1a47f7a654755055788f7482653f9c9661c6d51", 142 | "created_at":1703128320, 143 | "kind":1059, 144 | "tags":[ 145 | [ "p", "918e2da906df4ccd12c8ac672d8335add131a4cf9d27ce42b3bb3625755f0788"] 146 | ], 147 | "content":"AsqzdlMsG304G8h08bE67dhAR1gFTzTckUUyuvndZ8LrGCvwI4pgC3d6hyAK0Wo9gtkLqSr2rT2RyHlE5wRqbCOlQ8WvJEKwqwIJwT5PO3l2RxvGCHDbd1b1o40ZgIVwwLCfOWJ86I5upXe8K5AgpxYTOM1BD+SbgI5jOMA8tgpRoitJedVSvBZsmwAxXM7o7sbOON4MXHzOqOZpALpS2zgBDXSAaYAsTdEM4qqFeik+zTk3+L6NYuftGidqVluicwSGS2viYWr5OiJ1zrj1ERhYSGLpQnPKrqDaDi7R1KrHGFGyLgkJveY/45y0rv9aVIw9IWF11u53cf2CP7akACel2WvZdl1htEwFu/v9cFXD06fNVZjfx3OssKM/uHPE9XvZttQboAvP5UoK6lv9o3d+0GM4/3zP+yO3C0NExz1ZgFmbGFz703YJzM+zpKCOXaZyzPjADXp8qBBeVc5lmJqiCL4solZpxA1865yPigPAZcc9acSUlg23J1dptFK4n3Tl5HfSHP+oZ/QS/SHWbVFCtq7ZMQSRxLgEitfglTNz9P1CnpMwmW/Y4Gm5zdkv0JrdUVrn2UO9ARdHlPsW5ARgDmzaxnJypkfoHXNfxGGXWRk0sKLbz/ipnaQP/eFJv/ibNuSfqL6E4BnN/tHJSHYEaTQ/PdrA2i9laG3vJti3kAl5Ih87ct0w/tzYfp4SRPhEF1zzue9G/16eJEMzwmhQ5Ec7jJVcVGa4RltqnuF8unUu3iSRTQ+/MNNUkK6Mk+YuaJJs6Fjw6tRHuWi57SdKKv7GGkr0zlBUU2Dyo1MwpAqzsCcCTeQSv+8qt4wLf4uhU9Br7F/L0ZY9bFgh6iLDCdB+4iABXyZwT7Ufn762195hrSHcU4Okt0Zns9EeiBOFxnmpXEslYkYBpXw70GmymQfJlFOfoEp93QKCMS2DAEVeI51dJV1e+6t3pCSsQN69Vg6jUCsm1TMxSs2VX4BRbq562+VffchvW2BB4gMjsvHVUSRl8i5/ZSDlfzSPXcSGALLHBRzy+gn0oXXJ/447VHYZJDL3Ig8+QW5oFMgnWYhuwI5QSLEyflUrfSz+Pdwn/5eyjybXKJftePBD9Q+8NQ8zulU5sqvsMeIx/bBUx0fmOXsS3vjqCXW5IjkmSUV7q54GewZqTQBlcx+90xh/LSUxXex7UwZwRnifvyCbZ+zwNTHNb12chYeNjMV7kAIr3cGQv8vlOMM8ajyaZ5KVy7HpSXQjz4PGT2/nXbL5jKt8Lx0erGXsSsazkdoYDG3U", 148 | "sig":"a3c6ce632b145c0869423c1afaff4a6d764a9b64dedaf15f170b944ead67227518a72e455567ca1c2a0d187832cecbde7ed478395ec4c95dd3e71749ed66c480" 149 | } 150 | ``` 151 | 152 | ```json 153 | { 154 | "id":"162b0611a1911cfcb30f8a5502792b346e535a45658b3a31ae5c178465509721", 155 | "pubkey":"626be2af274b29ea4816ad672ee452b7cf96bbb4836815a55699ae402183f512", 156 | "created_at":1702711587, 157 | "kind":1059, 158 | "tags":[ 159 | [ "p", "44900586091b284416a0c001f677f9c49f7639a55c3f1e2ec130a8e1a7998e1b"] 160 | ], 161 | "content":"AsTClTzr0gzXXji7uye5UB6LYrx3HDjWGdkNaBS6BAX9CpHa+Vvtt5oI2xJrmWLen+Fo2NBOFazvl285Gb3HSM82gVycrzx1HUAaQDUG6HI7XBEGqBhQMUNwNMiN2dnilBMFC3Yc8ehCJT/gkbiNKOpwd2rFibMFRMDKai2mq2lBtPJF18oszKOjA+XlOJV8JRbmcAanTbEK5nA/GnG3eGUiUzhiYBoHomj3vztYYxc0QYHOx0WxiHY8dsC6jPsXC7f6k4P+Hv5ZiyTfzvjkSJOckel1lZuE5SfeZ0nduqTlxREGeBJ8amOykgEIKdH2VZBZB+qtOMc7ez9dz4wffGwBDA7912NFS2dPBr6txHNxBUkDZKFbuD5wijvonZDvfWq43tZspO4NutSokZB99uEiRH8NAUdGTiNb25m9JcDhVfdmABqTg5fIwwTwlem5aXIy8b66lmqqz2LBzJtnJDu36bDwkILph3kmvaKPD8qJXmPQ4yGpxIbYSTCohgt2/I0TKJNmqNvSN+IVoUuC7ZOfUV9lOV8Ri0AMfSr2YsdZ9ofV5o82ClZWlWiSWZwy6ypa7CuT1PEGHzywB4CZ5ucpO60Z7hnBQxHLiAQIO/QhiBp1rmrdQZFN6PUEjFDloykoeHe345Yqy9Ke95HIKUCS9yJurD+nZjjgOxZjoFCsB1hQAwINTIS3FbYOibZnQwv8PXvcSOqVZxC9U0+WuagK7IwxzhGZY3vLRrX01oujiRrevB4xbW7Oxi/Agp7CQGlJXCgmRE8Rhm+Vj2s+wc/4VLNZRHDcwtfejogjrjdi8p6nfUyqoQRRPARzRGUnnCbh+LqhigT6gQf3sVilnydMRScEc0/YYNLWnaw9nbyBa7wFBAiGbJwO40k39wj+xT6HTSbSUgFZzopxroO3f/o4+ubx2+IL3fkev22mEN38+dFmYF3zE+hpE7jVxrJpC3EP9PLoFgFPKCuctMnjXmeHoiGs756N5r1Mm1ffZu4H19MSuALJlxQR7VXE/LzxRXDuaB2u9days/6muP6gbGX1ASxbJd/ou8+viHmSC/ioHzNjItVCPaJjDyc6bv+gs1NPCt0qZ69G+JmgHW/PsMMeL4n5bh74g0fJSHqiI9ewEmOG/8bedSREv2XXtKV39STxPweceIOh0k23s3N6+wvuSUAJE7u1LkDo14cobtZ/MCw/QhimYPd1u5HnEJvRhPxz0nVPz0QqL/YQeOkAYk7uzgeb2yPzJ6DBtnTnGDkglekhVzQBFRJdk740LEj6swkJ", 162 | "sig":"c94e74533b482aa8eeeb54ae72a5303e0b21f62909ca43c8ef06b0357412d6f8a92f96e1a205102753777fd25321a58fba3fb384eee114bd53ce6c06a1c22bab" 163 | } 164 | ``` 165 | -------------------------------------------------------------------------------- /52.md: -------------------------------------------------------------------------------- 1 | NIP-52 2 | ====== 3 | 4 | Calendar Events 5 | --------------- 6 | 7 | `draft` `optional` 8 | 9 | This specification defines calendar events representing an occurrence at a specific moment or between moments. These calendar events are _parameterized replaceable_ and deletable per [NIP-09](09.md). 10 | 11 | Unlike the term `calendar event` specific to this NIP, the term `event` is used broadly in all the NIPs to describe any Nostr event. The distinction is being made here to discern between the two terms. 12 | 13 | ## Calendar Events 14 | 15 | There are two types of calendar events represented by different kinds: date-based and time-based calendar events. Calendar events are not required to be part of a [calendar](#calendar). 16 | 17 | ### Date-Based Calendar Event 18 | 19 | This kind of calendar event starts on a date and ends before a different date in the future. Its use is appropriate for all-day or multi-day events where time and time zone hold no significance. e.g., anniversary, public holidays, vacation days. 20 | 21 | #### Format 22 | 23 | The format uses a parameterized replaceable event kind `31922`. 24 | 25 | The `.content` of these events should be a detailed description of the calendar event. It is required but can be an empty string. 26 | 27 | The list of tags are as follows: 28 | * `d` (required) universally unique identifier (UUID). Generated by the client creating the calendar event. 29 | * `title` (required) title of the calendar event 30 | * `start` (required) inclusive start date in ISO 8601 format (YYYY-MM-DD). Must be less than `end`, if it exists. 31 | * `end` (optional) exclusive end date in ISO 8601 format (YYYY-MM-DD). If omitted, the calendar event ends on the same date as `start`. 32 | * `location` (optional, repeated) location of the calendar event. e.g. address, GPS coordinates, meeting room name, link to video call 33 | * `g` (optional) [geohash](https://en.wikipedia.org/wiki/Geohash) to associate calendar event with a searchable physical location 34 | * `p` (optional, repeated) 32-bytes hex pubkey of a participant, optional recommended relay URL, and participant's role in the meeting 35 | * `t` (optional, repeated) hashtag to categorize calendar event 36 | * `r` (optional, repeated) references / links to web pages, documents, video calls, recorded videos, etc. 37 | 38 | The following tags are deprecated: 39 | * `name` name of the calendar event. Use only if `title` is not available. 40 | 41 | ```jsonc 42 | { 43 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 44 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 45 | "created_at": <Unix timestamp in seconds>, 46 | "kind": 31922, 47 | "content": "<description of calendar event>", 48 | "tags": [ 49 | ["d", "<UUID>"], 50 | 51 | ["title", "<title of calendar event>"], 52 | 53 | // Dates 54 | ["start", "<YYYY-MM-DD>"], 55 | ["end", "<YYYY-MM-DD>"], 56 | 57 | // Location 58 | ["location", "<location>"], 59 | ["g", "<geohash>"], 60 | 61 | // Participants 62 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"], 63 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"], 64 | 65 | // Hashtags 66 | ["t", "<tag>"], 67 | ["t", "<tag>"], 68 | 69 | // Reference links 70 | ["r", "<url>"], 71 | ["r", "<url>"] 72 | ] 73 | } 74 | ``` 75 | 76 | ### Time-Based Calendar Event 77 | 78 | This kind of calendar event spans between a start time and end time. 79 | 80 | #### Format 81 | 82 | The format uses a parameterized replaceable event kind `31923`. 83 | 84 | The `.content` of these events should be a detailed description of the calendar event. It is required but can be an empty string. 85 | 86 | The list of tags are as follows: 87 | * `d` (required) universally unique identifier (UUID). Generated by the client creating the calendar event. 88 | * `title` (required) title of the calendar event 89 | * `start` (required) inclusive start Unix timestamp in seconds. Must be less than `end`, if it exists. 90 | * `end` (optional) exclusive end Unix timestamp in seconds. If omitted, the calendar event ends instantaneously. 91 | * `start_tzid` (optional) time zone of the start timestamp, as defined by the IANA Time Zone Database. e.g., `America/Costa_Rica` 92 | * `end_tzid` (optional) time zone of the end timestamp, as defined by the IANA Time Zone Database. e.g., `America/Costa_Rica`. If omitted and `start_tzid` is provided, the time zone of the end timestamp is the same as the start timestamp. 93 | * `location` (optional, repeated) location of the calendar event. e.g. address, GPS coordinates, meeting room name, link to video call 94 | * `g` (optional) [geohash](https://en.wikipedia.org/wiki/Geohash) to associate calendar event with a searchable physical location 95 | * `p` (optional, repeated) 32-bytes hex pubkey of a participant, optional recommended relay URL, and participant's role in the meeting 96 | * `t` (optional, repeated) hashtag to categorize calendar event 97 | * `r` (optional, repeated) references / links to web pages, documents, video calls, recorded videos, etc. 98 | 99 | The following tags are deprecated: 100 | * `name` name of the calendar event. Use only if `title` is not available. 101 | 102 | ```jsonc 103 | { 104 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 105 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 106 | "created_at": <Unix timestamp in seconds>, 107 | "kind": 31923, 108 | "content": "<description of calendar event>", 109 | "tags": [ 110 | ["d", "<UUID>"], 111 | 112 | ["title", "<title of calendar event>"], 113 | 114 | // Timestamps 115 | ["start", "<Unix timestamp in seconds>"], 116 | ["end", "<Unix timestamp in seconds>"], 117 | 118 | ["start_tzid", "<IANA Time Zone Database identifier>"], 119 | ["end_tzid", "<IANA Time Zone Database identifier>"], 120 | 121 | // Location 122 | ["location", "<location>"], 123 | ["g", "<geohash>"], 124 | 125 | // Participants 126 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"], 127 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"], 128 | 129 | // Hashtags 130 | ["t", "<tag>"], 131 | ["t", "<tag>"], 132 | 133 | // Reference links 134 | ["r", "<url>"], 135 | ["r", "<url>"] 136 | ] 137 | } 138 | ``` 139 | 140 | ## Calendar 141 | 142 | A calendar is a collection of calendar events, represented as a custom replaceable list event using kind `31924`. A user can have multiple calendars. One may create a calendar to segment calendar events for specific purposes. e.g., personal, work, travel, meetups, and conferences. 143 | 144 | ### Format 145 | 146 | The `.content` of these events should be a detailed description of the calendar. It is required but can be an empty string. 147 | 148 | The format uses a custom replaceable list of kind `31924` with a list of tags as described below: 149 | * `d` (required) universally unique identifier. Generated by the client creating the calendar. 150 | * `title` (required) calendar title 151 | * `a` (repeated) reference tag to kind `31922` or `31923` calendar event being responded to 152 | 153 | ```json 154 | { 155 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 156 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 157 | "created_at": <Unix timestamp in seconds>, 158 | "kind": 31924, 159 | "content": "<description of calendar>", 160 | "tags": [ 161 | ["d", "<UUID>"], 162 | ["title", "<calendar title>"], 163 | ["a", "<31922 or 31923>:<calendar event author pubkey>:<d-identifier of calendar event>", "<optional relay url>"], 164 | ["a", "<31922 or 31923>:<calendar event author pubkey>:<d-identifier of calendar event>", "<optional relay url>"] 165 | ] 166 | } 167 | ``` 168 | 169 | ## Calendar Event RSVP 170 | 171 | A calendar event RSVP is a response to a calendar event to indicate a user's attendance intention. 172 | 173 | If a calendar event tags a pubkey, that can be interpreted as the calendar event creator inviting that user to attend. Clients MAY choose to prompt the user to RSVP for the calendar event. 174 | 175 | Any user may RSVP, even if they were not tagged on the calendar event. Clients MAY choose to prompt the calendar event creator to invite the user who RSVP'd. Clients also MAY choose to ignore these RSVPs. 176 | 177 | This NIP is intentionally not defining who is authorized to attend a calendar event if the user who RSVP'd has not been tagged. It is up to the calendar event creator to determine the semantics. 178 | 179 | This NIP is also intentionally not defining what happens if a calendar event changes after an RSVP is submitted. 180 | 181 | ### Format 182 | 183 | The format uses a parameterized replaceable event kind `31925`. 184 | 185 | The `.content` of these events is optional and should be a free-form note that adds more context to this calendar event response. 186 | 187 | The list of tags are as follows: 188 | * `a` (required) reference tag to kind `31922` or `31923` calendar event being responded to. 189 | * `d` (required) universally unique identifier. Generated by the client creating the calendar event RSVP. 190 | * `status` (required) `accepted`, `declined`, or `tentative`. Determines attendance status to the referenced calendar event. 191 | * `fb` (optional) `free` or `busy`. Determines if the user would be free or busy for the duration of the calendar event. This tag must be omitted or ignored if the `status` label is set to `declined`. 192 | 193 | ```json 194 | { 195 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 196 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 197 | "created_at": <Unix timestamp in seconds>, 198 | "kind": 31925, 199 | "content": "<note>", 200 | "tags": [ 201 | ["a", "<31922 or 31923>:<calendar event author pubkey>:<d-identifier of calendar event>", "<optional relay url>"], 202 | ["d", "<UUID>"], 203 | ["status", "<accepted/declined/tentative>"], 204 | ["fb", "<free/busy>"], 205 | ] 206 | } 207 | ``` 208 | 209 | ## Unsolved Limitations 210 | 211 | * No private events 212 | 213 | ## Intentionally Unsupported Scenarios 214 | 215 | ### Recurring Calendar Events 216 | 217 | Recurring calendar events come with a lot of complexity, making it difficult for software and humans to deal with. This complexity includes time zone differences between invitees, daylight savings, leap years, multiple calendar systems, one-off changes in schedule or other metadata, etc. 218 | 219 | This NIP intentionally omits support for recurring calendar events and pushes that complexity up to clients to manually implement if they desire. i.e., individual calendar events with duplicated metadata represent recurring calendar events. 220 | -------------------------------------------------------------------------------- /51.md: -------------------------------------------------------------------------------- 1 | NIP-51 2 | ====== 3 | 4 | Lists 5 | ----- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines lists of things that users can create. Lists can contain references to anything, and these references can be **public** or **private**. 10 | 11 | Public items in a list are specified in the event `tags` array, while private items are specified in a JSON array that mimics the structure of the event `tags` array, but stringified and encrypted using the same scheme from [NIP-04](04.md) (the shared key is computed using the author's public and private key) and stored in the `.content`. 12 | 13 | When new items are added to an existing list, clients SHOULD append them to the end of the list, so they are stored in chronological order. 14 | 15 | ## Types of lists 16 | 17 | ## Standard lists 18 | 19 | Standard lists use non-parameterized replaceable events, meaning users may only have a single list of each kind. They have special meaning and clients may rely on them to augment a user's profile or browsing experience. 20 | 21 | For example, _mute list_ can contain the public keys of spammers and bad actors users don't want to see in their feeds or receive annoying notifications from. 22 | 23 | | name | kind | description | expected tag items | 24 | |-------------------|-------|-------------------------------------------------------------|-----------------------------------------------------------------------------------| 25 | | Mute list | 10000 | things the user doesn't want to see in their feeds | `"p"` (pubkeys), `"t"` (hashtags), `"word"` (lowercase string), `"e"` (threads) | 26 | | Pinned notes | 10001 | events the user intends to showcase in their profile page | `"e"` (kind:1 notes) | 27 | | Bookmarks | 10003 | uncategorized, "global" list of things a user wants to save | `"e"` (kind:1 notes), `"a"` (kind:30023 articles), `"t"` (hashtags), `"r"` (URLs) | 28 | | Communities | 10004 | [NIP-72](72.md) communities the user belongs to | `"a"` (kind:34550 community definitions) | 29 | | Public chats | 10005 | [NIP-28](28.md) chat channels the user is in | `"e"` (kind:40 channel definitions) | 30 | | Blocked relays | 10006 | relays clients should never connect to | `"relay"` (relay URLs) | 31 | | Search relays | 10007 | relays clients should use when performing search queries | `"relay"` (relay URLs) | 32 | | Simple groups | 10009 | [NIP-29](29.md) groups the user is in | `"group"` ([NIP-29](29.md) group ids + mandatory relay URL) | 33 | | Profile Gallery | 10011 | Profile Media Gallery | `"url"` + (url to media file) + (kind:1 note) + (relay hint) | 34 | | Interests | 10015 | topics a user may be interested in and pointers | `"t"` (hashtags) and `"a"` (kind:30015 interest set) | 35 | | Emojis | 10030 | user preferred emojis and pointers to emoji sets | `"emoji"` (see [NIP-30](30.md)) and `"a"` (kind:30030 emoji set) | 36 | | Good wiki authors | 10101 | [NIP-54](54.md) user recommended wiki authors | `"p"` (pubkeys) | 37 | | Good wiki relays | 10102 | [NIP-54](54.md) relays deemed to only host useful articles | `"relay"` (relay URLs) | 38 | 39 | ## Sets 40 | 41 | Sets are lists with well-defined meaning that can enhance the functionality and the UI of clients that rely on them. Unlike standard lists, users are expected to have more than one set of each kind, therefore each of them must be assigned a different `"d"` identifier. 42 | 43 | For example, _relay sets_ can be displayed in a dropdown UI to give users the option to switch to which relays they will publish an event or from which relays they will read the replies to an event; _curation sets_ can be used by apps to showcase curations made by others tagged to different topics. 44 | 45 | Aside from their main identifier, the `"d"` tag, sets can optionally have a `"title"`, an `"image"` and a `"description"` tags that can be used to enhance their UI. 46 | 47 | | name | kind | description | expected tag items | 48 | | --- | --- | --- | --- | 49 | | Follow sets | 30000 | categorized groups of users a client may choose to check out in different circumstances | `"p"` (pubkeys) | 50 | | Relay sets | 30002 | user-defined relay groups the user can easily pick and choose from during various operations | `"relay"` (relay URLs) | 51 | | Bookmark sets | 30003 | user-defined bookmarks categories , for when bookmarks must be in labeled separate groups | `"e"` (kind:1 notes), `"a"` (kind:30023 articles), `"t"` (hashtags), `"r"` (URLs) | 52 | | Curation sets | 30004 | groups of articles picked by users as interesting and/or belonging to the same category | `"a"` (kind:30023 articles), `"e"` (kind:1 notes) | 53 | | Curation sets | 30005 | groups of videos picked by users as interesting and/or belonging to the same category | `"a"` (kind:34235 videos) | 54 | | Interest sets | 30015 | interest topics represented by a bunch of "hashtags" | `"t"` (hashtags) | 55 | | Emoji sets | 30030 | categorized emoji groups | `"emoji"` (see [NIP-30](30.md)) | 56 | | Release artifact sets | 30063 | groups of files of a software release | `"e"` (kind:1063 [file metadata](94.md) events), `"i"` (application identifier, typically reverse domain notation), `"version"` | 57 | 58 | ## Deprecated standard lists 59 | 60 | Some clients have used these lists in the past, but they should work on transitioning to the [standard formats](#standard-lists) above. 61 | 62 | | kind | "d" tag | use instead | 63 | | --- | --- | --- | 64 | | 30000 | `"mute"` | kind 10000 _mute list_ | 65 | | 30001 | `"pin"` | kind 10001 _pin list_ | 66 | | 30001 | `"bookmark"` | kind 10003 _bookmarks list_ | 67 | | 30001 | `"communities"` | kind 10004 _communities list_ | 68 | 69 | ## Examples 70 | 71 | ### A _mute list_ with some public items and some encrypted items 72 | 73 | ```json 74 | { 75 | "id": "a92a316b75e44cfdc19986c634049158d4206fcc0b7b9c7ccbcdabe28beebcd0", 76 | "pubkey": "854043ae8f1f97430ca8c1f1a090bdde6488bd5115c7a45307a2a212750ae4cb", 77 | "created_at": 1699597889, 78 | "kind": 10000, 79 | "tags": [ 80 | ["p", "07caba282f76441955b695551c3c5c742e5b9202a3784780f8086fdcdc1da3a9"], 81 | ["p", "a55c15f5e41d5aebd236eca5e0142789c5385703f1a7485aa4b38d94fd18dcc4"] 82 | ], 83 | "content": "TJob1dQrf2ndsmdbeGU+05HT5GMnBSx3fx8QdDY/g3NvCa7klfzgaQCmRZuo1d3WQjHDOjzSY1+MgTK5WjewFFumCcOZniWtOMSga9tJk1ky00tLoUUzyLnb1v9x95h/iT/KpkICJyAwUZ+LoJBUzLrK52wNTMt8M5jSLvCkRx8C0BmEwA/00pjOp4eRndy19H4WUUehhjfV2/VV/k4hMAjJ7Bb5Hp9xdmzmCLX9+64+MyeIQQjQAHPj8dkSsRahP7KS3MgMpjaF8nL48Bg5suZMxJayXGVp3BLtgRZx5z5nOk9xyrYk+71e2tnP9IDvSMkiSe76BcMct+m7kGVrRcavDI4n62goNNh25IpghT+a1OjjkpXt9me5wmaL7fxffV1pchdm+A7KJKIUU3kLC7QbUifF22EucRA9xiEyxETusNludBXN24O3llTbOy4vYFsq35BeZl4v1Cse7n2htZicVkItMz3wjzj1q1I1VqbnorNXFgllkRZn4/YXfTG/RMnoK/bDogRapOV+XToZ+IvsN0BqwKSUDx+ydKpci6htDRF2WDRkU+VQMqwM0CoLzy2H6A2cqyMMMD9SLRRzBg==?iv=S3rFeFr1gsYqmQA7bNnNTQ==", 84 | "sig": "1173822c53261f8cffe7efbf43ba4a97a9198b3e402c2a1df130f42a8985a2d0d3430f4de350db184141e45ca844ab4e5364ea80f11d720e36357e1853dba6ca" 85 | } 86 | ``` 87 | 88 | ### A _curation set_ of articles and notes about yaks 89 | 90 | ```json 91 | { 92 | "id": "567b41fc9060c758c4216fe5f8d3df7c57daad7ae757fa4606f0c39d4dd220ef", 93 | "pubkey": "d6dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c", 94 | "created_at": 1695327657, 95 | "kind": 30004, 96 | "tags": [ 97 | ["d", "jvdy9i4"], 98 | ["name", "Yaks"], 99 | ["picture", "https://cdn.britannica.com/40/188540-050-9AC748DE/Yak-Himalayas-Nepal.jpg"], 100 | ["about", "The domestic yak, also known as the Tartary ox, grunting ox, or hairy cattle, is a species of long-haired domesticated cattle found throughout the Himalayan region of the Indian subcontinent, the Tibetan Plateau, Gilgit-Baltistan, Tajikistan and as far north as Mongolia and Siberia."], 101 | ["a", "30023:26dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:95ODQzw3ajNoZ8SyMDOzQ"], 102 | ["a", "30023:54af95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:1-MYP8dAhramH9J5gJWKx"], 103 | ["a", "30023:f8fe95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:D2Tbd38bGrFvU0bIbvSMt"], 104 | ["e", "d78ba0d5dce22bfff9db0a9e996c9ef27e2c91051de0c4e1da340e0326b4941e"] 105 | ], 106 | "content": "", 107 | "sig": "a9a4e2192eede77e6c9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad001cb039cb8de91d83ce30e9a94f82ac3c5a2372aa1294a96bd" 108 | } 109 | ``` 110 | 111 | ### A _release artifact set_ of an Example App 112 | 113 | ```json 114 | { 115 | "id": "567b41fc9060c758c4216fe5f8d3df7c57daad7ae757fa4606f0c39d4dd220ef", 116 | "pubkey": "d6dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c", 117 | "created_at": 1695327657, 118 | "kind": 30063, 119 | "tags": [ 120 | ["d", "ak8dy3v7"], 121 | ["i", "com.example.app"], 122 | ["version", "0.0.1"], 123 | ["title", "Example App"], 124 | ["image", "http://cdn.site/p/com.example.app/icon.png"], 125 | ["e", "d78ba0d5dce22bfff9db0a9e996c9ef27e2c91051de0c4e1da340e0326b4941e"], // Windows exe 126 | ["e", "f27e2c91051de0c4e1da0d5dce22bfff9db0a9340e0326b4941ed78bae996c9e"], // MacOS dmg 127 | ["e", "9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad02332"], // Linux AppImage 128 | ["e", "340e0326b340e0326b4941ed78ba340e0326b4941ed78ba340e0326b49ed78ba"] // PWA 129 | ], 130 | "content": "Example App is a decentralized marketplace for apps", 131 | "sig": "a9a4e2192eede77e6c9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad001cb039cb8de91d83ce30e9a94f82ac3c5a2372aa1294a96bd" 132 | } 133 | ``` 134 | 135 | ## Encryption process pseudocode 136 | 137 | ```scala 138 | val private_items = [ 139 | ["p", "07caba282f76441955b695551c3c5c742e5b9202a3784780f8086fdcdc1da3a9"], 140 | ["a", "a55c15f5e41d5aebd236eca5e0142789c5385703f1a7485aa4b38d94fd18dcc4"], 141 | ] 142 | val base64blob = nip04.encrypt(json.encode_to_string(private_items)) 143 | event.content = base64blob 144 | ``` 145 | -------------------------------------------------------------------------------- /59.md: -------------------------------------------------------------------------------- 1 | NIP-59 2 | ====== 3 | 4 | Gift Wrap 5 | --------- 6 | 7 | `optional` 8 | 9 | This NIP defines a protocol for encapsulating any nostr event. This makes it possible to obscure most metadata 10 | for a given event, perform collaborative signing, and more. 11 | 12 | This NIP *does not* define any messaging protocol. Applications of this NIP should be defined separately. 13 | 14 | This NIP relies on [NIP-44](./44.md)'s versioned encryption algorithms. 15 | 16 | # Overview 17 | 18 | This protocol uses three main concepts to protect the transmission of a target event: `rumor`s, `seal`s, and `gift wrap`s. 19 | 20 | - A `rumor` is a regular nostr event, but is **not signed**. This means that if it is leaked, it cannot be verified. 21 | - A `rumor` is serialized to JSON, encrypted, and placed in the `content` field of a `seal`. The `seal` is then 22 | signed by the author of the note. The only information publicly available on a `seal` is who signed it, but not what was said. 23 | - A `seal` is serialized to JSON, encrypted, and placed in the `content` field of a `gift wrap`. 24 | 25 | This allows the isolation of concerns across layers: 26 | 27 | - A rumor carries the content but is unsigned, which means if leaked it will be rejected by relays and clients, 28 | and can't be authenticated. This provides a measure of deniability. 29 | - A seal identifies the author without revealing the content or the recipient. 30 | - A gift wrap can add metadata (recipient, tags, a different author) without revealing the true author. 31 | 32 | # Protocol Description 33 | 34 | ## 1. The Rumor Event Kind 35 | 36 | A `rumor` is the same thing as an unsigned event. Any event kind can be made a `rumor` by removing the signature. 37 | 38 | ## 2. The Seal Event Kind 39 | 40 | A `seal` is a `kind:13` event that wraps a `rumor` with the sender's regular key. The `seal` is **always** encrypted 41 | to a receiver's pubkey but there is no `p` tag pointing to the receiver. There is no way to know who the rumor is for 42 | without the receiver's or the sender's private key. The only public information in this event is who is signing it. 43 | 44 | ```js 45 | { 46 | "id": "<id>", 47 | "pubkey": "<real author's pubkey>", 48 | "content": "<encrypted rumor>", 49 | "kind": 13, 50 | "created_at": 1686840217, 51 | "tags": [], 52 | "sig": "<real author's pubkey signature>" 53 | } 54 | ``` 55 | 56 | Tags MUST must always be empty in a `kind:13`. The inner event MUST always be unsigned. 57 | 58 | ## 3. Gift Wrap Event Kind 59 | 60 | A `gift wrap` event is a `kind:1059` event that wraps any other event. `tags` SHOULD include any information 61 | needed to route the event to its intended recipient, including the recipient's `p` tag or [NIP-13](13.md) proof of work. 62 | 63 | ```js 64 | { 65 | "id": "<id>", 66 | "pubkey": "<random, one-time-use pubkey>", 67 | "content": "<encrypted kind 13>", 68 | "kind": 1059, 69 | "created_at": 1686840217, 70 | "tags": [["p", "<recipient pubkey>"]], 71 | "sig": "<random, one-time-use pubkey signature>" 72 | } 73 | ``` 74 | 75 | # Encrypting Payloads 76 | 77 | Encryption is done following [NIP-44](44.md) on the JSON-encoded event. Place the encryption payload in the `.content` 78 | of the wrapper event (either a `seal` or a `gift wrap`). 79 | 80 | # Other Considerations 81 | 82 | If a `rumor` is intended for more than one party, or if the author wants to retain an encrypted copy, a single 83 | `rumor` may be wrapped and addressed for each recipient individually. 84 | 85 | The canonical `created_at` time belongs to the `rumor`. All other timestamps SHOULD be tweaked to thwart 86 | time-analysis attacks. Note that some relays don't serve events dated in the future, so all timestamps 87 | SHOULD be in the past. 88 | 89 | Relays may choose not to store gift wrapped events due to them not being publicly useful. Clients MAY choose 90 | to attach a certain amount of proof-of-work to the wrapper event per [NIP-13](13.md) in a bid to demonstrate that 91 | the event is not spam or a denial-of-service attack. 92 | 93 | To protect recipient metadata, relays SHOULD guard access to `kind 1059` events based on user AUTH. When 94 | possible, clients should only send wrapped events to relays that offer this protection. 95 | 96 | To protect recipient metadata, relays SHOULD only serve `kind 1059` events intended for the marked recipient. 97 | When possible, clients should only send wrapped events to `read` relays for the recipient that implement 98 | AUTH, and refuse to serve wrapped events to non-recipients. 99 | 100 | # An Example 101 | 102 | Let's send a wrapped `kind 1` message between two parties asking "Are you going to the party tonight?" 103 | 104 | - Author private key: `0beebd062ec8735f4243466049d7747ef5d6594ee838de147f8aab842b15e273` 105 | - Recipient private key: `e108399bd8424357a710b606ae0c13166d853d327e47a6e5e038197346bdbf45` 106 | - Ephemeral wrapper key: `4f02eac59266002db5801adc5270700ca69d5b8f761d8732fab2fbf233c90cbd` 107 | 108 | Note that this messaging protocol should not be used in practice, this is just an example. Refer to other 109 | NIPs for concrete messaging protocols that depend on gift wraps. 110 | 111 | ## 1. Create an event 112 | 113 | Create a `kind 1` event with the message, the receivers, and any other tags you want, signed by the author. 114 | Do not sign the event. 115 | 116 | ```json 117 | { 118 | "created_at": 1691518405, 119 | "content": "Are you going to the party tonight?", 120 | "tags": [], 121 | "kind": 1, 122 | "pubkey": "611df01bfcf85c26ae65453b772d8f1dfd25c264621c0277e1fc1518686faef9", 123 | "id": "9dd003c6d3b73b74a85a9ab099469ce251653a7af76f523671ab828acd2a0ef9" 124 | } 125 | ``` 126 | 127 | ## 2. Seal the rumor 128 | 129 | Encrypt the JSON-encoded `rumor` with a conversation key derived using the author's private key and 130 | the recipient's public key. Place the result in the `content` field of a `kind 13` `seal` event. Sign 131 | it with the author's key. 132 | 133 | ```json 134 | { 135 | "content": "AqBCdwoS7/tPK+QGkPCadJTn8FxGkd24iApo3BR9/M0uw6n4RFAFSPAKKMgkzVMoRyR3ZS/aqATDFvoZJOkE9cPG/TAzmyZvr/WUIS8kLmuI1dCA+itFF6+ULZqbkWS0YcVU0j6UDvMBvVlGTzHz+UHzWYJLUq2LnlynJtFap5k8560+tBGtxi9Gx2NIycKgbOUv0gEqhfVzAwvg1IhTltfSwOeZXvDvd40rozONRxwq8hjKy+4DbfrO0iRtlT7G/eVEO9aJJnqagomFSkqCscttf/o6VeT2+A9JhcSxLmjcKFG3FEK3Try/WkarJa1jM3lMRQqVOZrzHAaLFW/5sXano6DqqC5ERD6CcVVsrny0tYN4iHHB8BHJ9zvjff0NjLGG/v5Wsy31+BwZA8cUlfAZ0f5EYRo9/vKSd8TV0wRb9DQ=", 136 | "kind": 13, 137 | "created_at": 1703015180, 138 | "pubkey": "611df01bfcf85c26ae65453b772d8f1dfd25c264621c0277e1fc1518686faef9", 139 | "tags": [], 140 | "id": "28a87d7c074d94a58e9e89bb3e9e4e813e2189f285d797b1c56069d36f59eaa7", 141 | "sig": "02fc3facf6621196c32912b1ef53bac8f8bfe9db51c0e7102c073103586b0d29c3f39bdaa1e62856c20e90b6c7cc5dc34ca8bb6a528872cf6e65e6284519ad73" 142 | } 143 | ``` 144 | 145 | ## 3. Wrap the seal 146 | 147 | Encrypt the JSON-encoded `kind 13` event with your ephemeral, single-use random key. Place the result 148 | in the `content` field of a `kind 1059`. Add a single `p` tag containing the recipient's public key. 149 | Sign the `gift wrap` using the random key generated in the previous step. 150 | 151 | ```json 152 | { 153 | "content": "AhC3Qj/QsKJFWuf6xroiYip+2yK95qPwJjVvFujhzSguJWb/6TlPpBW0CGFwfufCs2Zyb0JeuLmZhNlnqecAAalC4ZCugB+I9ViA5pxLyFfQjs1lcE6KdX3euCHBLAnE9GL/+IzdV9vZnfJH6atVjvBkNPNzxU+OLCHO/DAPmzmMVx0SR63frRTCz6Cuth40D+VzluKu1/Fg2Q1LSst65DE7o2efTtZ4Z9j15rQAOZfE9jwMCQZt27rBBK3yVwqVEriFpg2mHXc1DDwHhDADO8eiyOTWF1ghDds/DxhMcjkIi/o+FS3gG1dG7gJHu3KkGK5UXpmgyFKt+421m5o++RMD/BylS3iazS1S93IzTLeGfMCk+7IKxuSCO06k1+DaasJJe8RE4/rmismUvwrHu/HDutZWkvOAhd4z4khZo7bJLtiCzZCZ74lZcjOB4CYtuAX2ZGpc4I1iOKkvwTuQy9BWYpkzGg3ZoSWRD6ty7U+KN+fTTmIS4CelhBTT15QVqD02JxfLF7nA6sg3UlYgtiGw61oH68lSbx16P3vwSeQQpEB5JbhofW7t9TLZIbIW/ODnI4hpwj8didtk7IMBI3Ra3uUP7ya6vptkd9TwQkd/7cOFaSJmU+BIsLpOXbirJACMn+URoDXhuEtiO6xirNtrPN8jYqpwvMUm5lMMVzGT3kMMVNBqgbj8Ln8VmqouK0DR+gRyNb8fHT0BFPwsHxDskFk5yhe5c/2VUUoKCGe0kfCcX/EsHbJLUUtlHXmTqaOJpmQnW1tZ/siPwKRl6oEsIJWTUYxPQmrM2fUpYZCuAo/29lTLHiHMlTbarFOd6J/ybIbICy2gRRH/LFSryty3Cnf6aae+A9uizFBUdCwTwffc3vCBae802+R92OL78bbqHKPbSZOXNC+6ybqziezwG+OPWHx1Qk39RYaF0aFsM4uZWrFic97WwVrH5i+/Nsf/OtwWiuH0gV/SqvN1hnkxCTF/+XNn/laWKmS3e7wFzBsG8+qwqwmO9aVbDVMhOmeUXRMkxcj4QreQkHxLkCx97euZpC7xhvYnCHarHTDeD6nVK+xzbPNtzeGzNpYoiMqxZ9bBJwMaHnEoI944Vxoodf51cMIIwpTmmRvAzI1QgrfnOLOUS7uUjQ/IZ1Qa3lY08Nqm9MAGxZ2Ou6R0/Z5z30ha/Q71q6meAs3uHQcpSuRaQeV29IASmye2A2Nif+lmbhV7w8hjFYoaLCRsdchiVyNjOEM4VmxUhX4VEvw6KoCAZ/XvO2eBF/SyNU3Of4SO", 154 | "kind": 1059, 155 | "created_at": 1703021488, 156 | "pubkey": "18b1a75918f1f2c90c23da616bce317d36e348bcf5f7ba55e75949319210c87c", 157 | "id": "5c005f3ccf01950aa8d131203248544fb1e41a0d698e846bd419cec3890903ac", 158 | "sig": "35fabdae4634eb630880a1896a886e40fd6ea8a60958e30b89b33a93e6235df750097b04f9e13053764251b8bc5dd7e8e0794a3426a90b6bcc7e5ff660f54259", 159 | "tags": [["p", "166bf3765ebd1fc55decfe395beff2ea3b2a4e0a8946e7eb578512b555737c99"]], 160 | } 161 | ``` 162 | 163 | ## 4. Broadcast Selectively 164 | 165 | Broadcast the `kind 1059` event to the recipient's relays only. Delete all the other events. 166 | 167 | # Code Samples 168 | 169 | ## JavaScript 170 | 171 | ```javascript 172 | import {bytesToHex} from "@noble/hashes/utils" 173 | import type {EventTemplate, UnsignedEvent, Event} from "nostr-tools" 174 | import {getPublicKey, getEventHash, nip19, nip44, finalizeEvent, generateSecretKey} from "nostr-tools" 175 | 176 | type Rumor = UnsignedEvent & {id: string} 177 | 178 | const TWO_DAYS = 2 * 24 * 60 * 60 179 | 180 | const now = () => Math.round(Date.now() / 1000) 181 | const randomNow = () => Math.round(now() - (Math.random() * TWO_DAYS)) 182 | 183 | const nip44ConversationKey = (privateKey: Uint8Array, publicKey: string) => 184 | nip44.v2.utils.getConversationKey(bytesToHex(privateKey), publicKey) 185 | 186 | const nip44Encrypt = (data: EventTemplate, privateKey: Uint8Array, publicKey: string) => 187 | nip44.v2.encrypt(JSON.stringify(data), nip44ConversationKey(privateKey, publicKey)) 188 | 189 | const nip44Decrypt = (data: Event, privateKey: Uint8Array) => 190 | JSON.parse(nip44.v2.decrypt(data.content, nip44ConversationKey(privateKey, data.pubkey))) 191 | 192 | const createRumor = (event: Partial<UnsignedEvent>, privateKey: Uint8Array) => { 193 | const rumor = { 194 | created_at: now(), 195 | content: "", 196 | tags: [], 197 | ...event, 198 | pubkey: getPublicKey(privateKey), 199 | } as any 200 | 201 | rumor.id = getEventHash(rumor) 202 | 203 | return rumor as Rumor 204 | } 205 | 206 | const createSeal = (rumor: Rumor, privateKey: Uint8Array, recipientPublicKey: string) => { 207 | return finalizeEvent( 208 | { 209 | kind: 13, 210 | content: nip44Encrypt(rumor, privateKey, recipientPublicKey), 211 | created_at: randomNow(), 212 | tags: [], 213 | }, 214 | privateKey 215 | ) as Event 216 | } 217 | 218 | const createWrap = (event: Event, recipientPublicKey: string) => { 219 | const randomKey = generateSecretKey() 220 | 221 | return finalizeEvent( 222 | { 223 | kind: 1059, 224 | content: nip44Encrypt(event, randomKey, recipientPublicKey), 225 | created_at: randomNow(), 226 | tags: [["p", recipientPublicKey]], 227 | }, 228 | randomKey 229 | ) as Event 230 | } 231 | 232 | // Test case using the above example 233 | const senderPrivateKey = nip19.decode(`nsec1p0ht6p3wepe47sjrgesyn4m50m6avk2waqudu9rl324cg2c4ufesyp6rdg`).data 234 | const recipientPrivateKey = nip19.decode(`nsec1uyyrnx7cgfp40fcskcr2urqnzekc20fj0er6de0q8qvhx34ahazsvs9p36`).data 235 | const recipientPublicKey = getPublicKey(recipientPrivateKey) 236 | 237 | const rumor = createRumor( 238 | { 239 | kind: 1, 240 | content: "Are you going to the party tonight?", 241 | }, 242 | senderPrivateKey 243 | ) 244 | 245 | const seal = createSeal(rumor, senderPrivateKey, recipientPublicKey) 246 | const wrap = createWrap(seal, recipientPublicKey) 247 | 248 | // Recipient unwraps with his/her private key. 249 | 250 | const unwrappedSeal = nip44Decrypt(wrap, recipientPrivateKey) 251 | const unsealedRumor = nip44Decrypt(unwrappedSeal, recipientPrivateKey) 252 | ``` 253 | --------------------------------------------------------------------------------

, ]`. 12 | 13 | The `.content` is not used. 14 | 15 | For example: 16 | 17 | ```json 18 | { 19 | "kind": 3, 20 | "tags": [ 21 | ["p", "91cf9..4e5ca", "wss://alicerelay.com/", "alice"], 22 | ["p", "14aeb..8dad4", "wss://bobrelay.com/nostr", "bob"], 23 | ["p", "612ae..e610f", "ws://carolrelay.com/ws", "carol"] 24 | ], 25 | "content": "", 26 | ...other fields 27 | } 28 | ``` 29 | 30 | Every new following list that gets published overwrites the past ones, so it should contain all entries. Relays and clients SHOULD delete past following lists as soon as they receive a new one. 31 | 32 | Whenever new follows are added to an existing list, clients SHOULD append them to the end of the list, so they are stored in chronological order. 33 | 34 | ## Uses 35 | 36 | ### Follow list backup 37 | 38 | If one believes a relay will store their events for sufficient time, they can use this kind-3 event to backup their following list and recover on a different device. 39 | 40 | ### Profile discovery and context augmentation 41 | 42 | A client may rely on the kind-3 event to display a list of followed people by profiles one is browsing; make lists of suggestions on who to follow based on the follow lists of other people one might be following or browsing; or show the data in other contexts. 43 | 44 | ### Relay sharing 45 | 46 | A client may publish a follow list with good relays for each of their follows so other clients may use these to update their internal relay lists if needed, increasing censorship-resistance. 47 | 48 | ### Petname scheme 49 | 50 | The data from these follow lists can be used by clients to construct local ["petname"](http://www.skyhunter.com/marcs/petnames/IntroPetNames.html) tables derived from other people's follow lists. This alleviates the need for global human-readable names. For example: 51 | 52 | A user has an internal follow list that says 53 | 54 | ```json 55 | [ 56 | ["p", "21df6d143fb96c2ec9d63726bf9edc71", "", "erin"] 57 | ] 58 | ``` 59 | 60 | And receives two follow lists, one from `21df6d143fb96c2ec9d63726bf9edc71` that says 61 | 62 | ```json 63 | [ 64 | ["p", "a8bb3d884d5d90b413d9891fe4c4e46d", "", "david"] 65 | ] 66 | ``` 67 | 68 | and another from `a8bb3d884d5d90b413d9891fe4c4e46d` that says 69 | 70 | ```json 71 | [ 72 | ["p", "f57f54057d2a7af0efecc8b0b66f5708", "", "frank"] 73 | ] 74 | ``` 75 | 76 | When the user sees `21df6d143fb96c2ec9d63726bf9edc71` the client can show _erin_ instead; 77 | When the user sees `a8bb3d884d5d90b413d9891fe4c4e46d` the client can show _david.erin_ instead; 78 | When the user sees `f57f54057d2a7af0efecc8b0b66f5708` the client can show _frank.david.erin_ instead. 79 | -------------------------------------------------------------------------------- /04.md: -------------------------------------------------------------------------------- 1 | > __Warning__ `unrecommended`: deprecated in favor of [NIP-17](17.md) 2 | 3 | NIP-04 4 | ====== 5 | 6 | Encrypted Direct Message 7 | ------------------------ 8 | 9 | `final` `unrecommended` `optional` 10 | 11 | A special event with kind `4`, meaning "encrypted direct message". It is supposed to have the following attributes: 12 | 13 | **`content`** MUST be equal to the base64-encoded, aes-256-cbc encrypted string of anything a user wants to write, encrypted using a shared cipher generated by combining the recipient's public-key with the sender's private-key; this appended by the base64-encoded initialization vector as if it was a querystring parameter named "iv". The format is the following: `"content": "?iv="`. 14 | 15 | **`tags`** MUST contain an entry identifying the receiver of the message (such that relays may naturally forward this event to them), in the form `["p", ""]`. 16 | 17 | **`tags`** MAY contain an entry identifying the previous message in a conversation or a message we are explicitly replying to (such that contextual, more organized conversations may happen), in the form `["e", ""]`. 18 | 19 | **Note**: By default in the [libsecp256k1](https://github.com/bitcoin-core/secp256k1) ECDH implementation, the secret is the SHA256 hash of the shared point (both X and Y coordinates). In Nostr, only the X coordinate of the shared point is used as the secret and it is NOT hashed. If using libsecp256k1, a custom function that copies the X coordinate must be passed as the `hashfp` argument in `secp256k1_ecdh`. See [here](https://github.com/bitcoin-core/secp256k1/blob/master/src/modules/ecdh/main_impl.h#L29). 20 | 21 | Code sample for generating such an event in JavaScript: 22 | 23 | ```js 24 | import crypto from 'crypto' 25 | import * as secp from '@noble/secp256k1' 26 | 27 | let sharedPoint = secp.getSharedSecret(ourPrivateKey, '02' + theirPublicKey) 28 | let sharedX = sharedPoint.slice(1, 33) 29 | 30 | let iv = crypto.randomFillSync(new Uint8Array(16)) 31 | var cipher = crypto.createCipheriv( 32 | 'aes-256-cbc', 33 | Buffer.from(sharedX), 34 | iv 35 | ) 36 | let encryptedMessage = cipher.update(text, 'utf8', 'base64') 37 | encryptedMessage += cipher.final('base64') 38 | let ivBase64 = Buffer.from(iv.buffer).toString('base64') 39 | 40 | let event = { 41 | pubkey: ourPubKey, 42 | created_at: Math.floor(Date.now() / 1000), 43 | kind: 4, 44 | tags: [['p', theirPublicKey]], 45 | content: encryptedMessage + '?iv=' + ivBase64 46 | } 47 | ``` 48 | 49 | ## Security Warning 50 | 51 | This standard does not go anywhere near what is considered the state-of-the-art in encrypted communication between peers, and it leaks metadata in the events, therefore it must not be used for anything you really need to keep secret, and only with relays that use `AUTH` to restrict who can fetch your `kind:4` events. 52 | 53 | ## Client Implementation Warning 54 | 55 | Clients *should not* search and replace public key or note references from the `.content`. If processed like a regular text note (where `@npub...` is replaced with `#[0]` with a `["p", "..."]` tag) the tags are leaked and the mentioned user will receive the message in their inbox. 56 | -------------------------------------------------------------------------------- /10.md: -------------------------------------------------------------------------------- 1 | NIP-10 2 | ====== 3 | 4 | 5 | On "e" and "p" tags in Text Events (kind 1). 6 | -------------------------------------------- 7 | 8 | `draft` `optional` 9 | 10 | ## Abstract 11 | 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. 12 | 13 | ## Positional "e" tags (DEPRECATED) 14 | >This scheme is in common use; but should be considered deprecated. 15 | 16 | `["e", , ]` as per NIP-01. 17 | 18 | Where: 19 | 20 | * `` is the id of the event being referenced. 21 | * `` is the URL of a recommended relay associated with the reference. Many clients treat this field as optional. 22 | 23 | **The positions of the "e" tags within the event denote specific meanings as follows**: 24 | 25 | * No "e" tag:
26 | This event is not a reply to, nor does it refer to, any other event. 27 | 28 | * One "e" tag:
29 | `["e", ]`: The id of the event to which this event is a reply. 30 | 31 | * Two "e" tags: `["e", ]`, `["e", ]`
32 | `` 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. 33 | 34 | * Many "e" tags: `["e", ]` `["e", ]`, ..., `["e", ]`
35 | There may be any number of ``. These are the ids of events which may, or may not be in the reply chain. 36 | They are citing from this event. `root-id` and `reply-id` are as above. 37 | 38 | >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. 39 | 40 | ## Marked "e" tags (PREFERRED) 41 | `["e", , , , ]` 42 | 43 | Where: 44 | 45 | * `` is the id of the event being referenced. 46 | * `` is the URL of a recommended relay associated with the reference. Clients SHOULD add a valid `` field, but may instead leave it as `""`. 47 | * `` is optional and if present is one of `"reply"`, `"root"`, or `"mention"`. 48 | * `` is optional, SHOULD be the pubkey of the author of the referenced event 49 | 50 | 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. 51 | 52 | A direct reply to the root of a thread should have a single marked "e" tag of type "root". 53 | 54 | >This scheme is preferred because it allows events to mention others without confusing them with `` or ``. 55 | 56 | `` SHOULD be the pubkey of the author of the `e` tagged event, this is used in the outbox model to search for that event from the authors write relays where relay hints did not resolve the event. 57 | 58 | ## The "p" tag 59 | Used in a text event contains a list of pubkeys used to record who is involved in a reply thread. 60 | 61 | 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. 62 | 63 | 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`] 64 | in no particular order. 65 | -------------------------------------------------------------------------------- /23.md: -------------------------------------------------------------------------------- 1 | NIP-23 2 | ====== 3 | 4 | Long-form Content 5 | ----------------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines `kind:30023` (a _parameterized replaceable event_) for long-form text content, generally referred to as "articles" or "blog posts". `kind:30024` has the same structure as `kind:30023` and is used to save long form drafts. 10 | 11 | "Social" clients that deal primarily with `kind:1` notes should not be expected to implement this NIP. 12 | 13 | ### Format 14 | 15 | The `.content` of these events should be a string text in Markdown syntax. To maximize compatibility and readability between different clients and devices, any client that is creating long form notes: 16 | 17 | - MUST NOT hard line-break paragraphs of text, such as arbitrary line breaks at 80 column boundaries. 18 | 19 | - MUST NOT support adding HTML to Markdown. 20 | 21 | ### Metadata 22 | 23 | For the date of the last update the `.created_at` field should be used, for "tags"/"hashtags" (i.e. topics about which the event might be of relevance) the `t` tag should be used, as per NIP-12. 24 | 25 | Other metadata fields can be added as tags to the event as necessary. Here we standardize 4 that may be useful, although they remain strictly optional: 26 | 27 | - `"title"`, for the article title 28 | - `"image"`, for a URL pointing to an image to be shown along with the title 29 | - `"summary"`, for the article summary 30 | - `"published_at"`, for the timestamp in unix seconds (stringified) of the first time the article was published 31 | 32 | ### Editability 33 | 34 | These articles are meant to be editable, so they should make use of the parameterized replaceability feature and include a `d` tag with an identifier for the article. Clients should take care to only publish and read these events from relays that implement that. If they don't do that they should also take care to hide old versions of the same article they may receive. 35 | 36 | ### Linking 37 | 38 | The article may be linked to using the [NIP-19](19.md) `naddr` code along with the `a` tag. 39 | 40 | ### References 41 | 42 | References to other Nostr notes, articles or profiles must be made according to [NIP-27](27.md), i.e. by using [NIP-21](21.md) `nostr:...` links and optionally adding tags for these (see example below). 43 | 44 | ## Example Event 45 | 46 | ```json 47 | { 48 | "kind": 30023, 49 | "created_at": 1675642635, 50 | "content": "Lorem [ipsum][nostr:nevent1qqst8cujky046negxgwwm5ynqwn53t8aqjr6afd8g59nfqwxpdhylpcpzamhxue69uhhyetvv9ujuetcv9khqmr99e3k7mg8arnc9] dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n\nRead more at nostr:naddr1qqzkjurnw4ksz9thwden5te0wfjkccte9ehx7um5wghx7un8qgs2d90kkcq3nk2jry62dyf50k0h36rhpdtd594my40w9pkal876jxgrqsqqqa28pccpzu.", 51 | "tags": [ 52 | ["d", "lorem-ipsum"], 53 | ["title", "Lorem Ipsum"], 54 | ["published_at", "1296962229"], 55 | ["t", "placeholder"], 56 | ["e", "b3e392b11f5d4f28321cedd09303a748acfd0487aea5a7450b3481c60b6e4f87", "wss://relay.example.com"], 57 | ["a", "30023:a695f6b60119d9521934a691347d9f78e8770b56da16bb255ee286ddf9fda919:ipsum", "wss://relay.nostr.org"] 58 | ], 59 | "pubkey": "...", 60 | "id": "..." 61 | } 62 | ``` 63 | -------------------------------------------------------------------------------- /19.md: -------------------------------------------------------------------------------- 1 | NIP-19 2 | ====== 3 | 4 | bech32-encoded entities 5 | ----------------------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP standardizes bech32-formatted strings that can be used to display keys, ids and other information in clients. These formats are not meant to be used anywhere in the core protocol, they are only meant for displaying to users, copy-pasting, sharing, rendering QR codes and inputting data. 10 | 11 | It is recommended that ids and keys are stored in either hex or binary format, since these formats are closer to what must actually be used the core protocol. 12 | 13 | ## Bare keys and ids 14 | 15 | To prevent confusion and mixing between private keys, public keys and event ids, which are all 32 byte strings. bech32-(not-m) encoding with different prefixes can be used for each of these entities. 16 | 17 | These are the possible bech32 prefixes: 18 | 19 | - `npub`: public keys 20 | - `nsec`: private keys 21 | - `note`: note ids 22 | 23 | Example: the hex public key `3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d` translates to `npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6`. 24 | 25 | The bech32 encodings of keys and ids are not meant to be used inside the standard NIP-01 event formats or inside the filters, they're meant for human-friendlier display and input only. Clients should still accept keys in both hex and npub format for now, and convert internally. 26 | 27 | ## Shareable identifiers with extra metadata 28 | 29 | When sharing a profile or an event, an app may decide to include relay information and other metadata such that other apps can locate and display these entities more easily. 30 | 31 | For these events, the contents are a binary-encoded list of `TLV` (type-length-value), with `T` and `L` being 1 byte each (`uint8`, i.e. a number in the range of 0-255), and `V` being a sequence of bytes of the size indicated by `L`. 32 | 33 | These are the possible bech32 prefixes with `TLV`: 34 | 35 | - `nprofile`: a nostr profile 36 | - `nevent`: a nostr event 37 | - `nrelay`: a nostr relay 38 | - `naddr`: a nostr _replaceable event_ coordinate 39 | 40 | These possible standardized `TLV` types are indicated here: 41 | 42 | - `0`: `special` 43 | - depends on the bech32 prefix: 44 | - for `nprofile` it will be the 32 bytes of the profile public key 45 | - for `nevent` it will be the 32 bytes of the event id 46 | - for `nrelay`, this is the relay URL 47 | - for `naddr`, it is the identifier (the `"d"` tag) of the event being referenced. For non-parameterized replaceable events, use an empty string. 48 | - `1`: `relay` 49 | - for `nprofile`, `nevent` and `naddr`, _optionally_, a relay in which the entity (profile or event) is more likely to be found, encoded as ascii 50 | - this may be included multiple times 51 | - `2`: `author` 52 | - for `naddr`, the 32 bytes of the pubkey of the event 53 | - for `nevent`, _optionally_, the 32 bytes of the pubkey of the event 54 | - `3`: `kind` 55 | - for `naddr`, the 32-bit unsigned integer of the kind, big-endian 56 | - for `nevent`, _optionally_, the 32-bit unsigned integer of the kind, big-endian 57 | 58 | ## Examples 59 | 60 | - `npub10elfcs4fr0l0r8af98jlmgdh9c8tcxjvz9qkw038js35mp4dma8qzvjptg` should decode into the public key hex `7e7e9c42a91bfef19fa929e5fda1b72e0ebc1a4c1141673e2794234d86addf4e` and vice-versa 61 | - `nsec1vl029mgpspedva04g90vltkh6fvh240zqtv9k0t9af8935ke9laqsnlfe5` should decode into the private key hex `67dea2ed018072d675f5415ecfaed7d2597555e202d85b3d65ea4e58d2d92ffa` and vice-versa 62 | - `nprofile1qqsrhuxx8l9ex335q7he0f09aej04zpazpl0ne2cgukyawd24mayt8gpp4mhxue69uhhytnc9e3k7mgpz4mhxue69uhkg6nzv9ejuumpv34kytnrdaksjlyr9p` should decode into a profile with the following TLV items: 63 | - pubkey: `3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d` 64 | - relay: `wss://r.x.com` 65 | - relay: `wss://djbas.sadkb.com` 66 | 67 | ## Notes 68 | 69 | - `npub` keys MUST NOT be used in NIP-01 events or in NIP-05 JSON responses, only the hex format is supported there. 70 | - When decoding a bech32-formatted string, TLVs that are not recognized or supported should be ignored, rather than causing an error. 71 | -------------------------------------------------------------------------------- /99.md: -------------------------------------------------------------------------------- 1 | NIP-99 2 | ====== 3 | 4 | Classified Listings 5 | ------------------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines `kind:30402`: a parameterized replaceable event to describe classified listings that list any arbitrary product, service, or other thing for sale or offer and includes enough structured metadata to make them useful. 10 | 11 | The category of classifieds includes a very broad range of physical goods, services, work opportunities, rentals, free giveaways, personals, etc. and is distinct from the more strictly structured marketplaces defined in [NIP-15](https://github.com/nostr-protocol/nips/blob/master/15.md) that often sell many units of specific products through very specific channels. 12 | 13 | The structure of these events is very similar to [NIP-23](https://github.com/nostr-protocol/nips/blob/master/23.md) long-form content events. 14 | 15 | ### Draft / Inactive Listings 16 | 17 | `kind:30403` has the same structure as `kind:30402` and is used to save draft or inactive classified listings. 18 | 19 | ### Content 20 | 21 | The `.content` field should be a description of what is being offered and by whom. These events should be a string in Markdown syntax. 22 | 23 | ### Author 24 | 25 | The `.pubkey` field of these events are treated as the party creating the listing. 26 | 27 | ### Metadata 28 | 29 | - For "tags"/"hashtags" (i.e. categories or keywords of relevance for the listing) the `"t"` event tag should be used, as per [NIP-12](https://github.com/nostr-protocol/nips/blob/master/12.md). 30 | - For images, whether included in the markdown content or not, clients SHOULD use `image` tags as described in [NIP-58](https://github.com/nostr-protocol/nips/blob/master/58.md). This allows clients to display images in carousel format more easily. 31 | 32 | The following tags, used for structured metadata, are standardized and SHOULD be included. Other tags may be added as necessary. 33 | 34 | - `"title"`, a title for the listing 35 | - `"summary"`, for short tagline or summary for the listing 36 | - `"published_at"`, for the timestamp (in unix seconds – converted to string) of the first time the listing was published. 37 | - `"location"`, for the location. 38 | - `"price"`, for the price of the thing being listed. This is an array in the format `[ "price", "", "", "" ]`. 39 | - `"price"` is the name of the tag 40 | - `""` is the amount in numeric format (but included in the tag as a string) 41 | - `""` is the currency unit in 3-character ISO 4217 format or ISO 4217-like currency code (e.g. `"btc"`, `"eth"`). 42 | - `""` is optional and can be used to describe recurring payments. SHOULD be in noun format (hour, day, week, month, year, etc.) 43 | - - `"status"` (optional), the status of the listing. SHOULD be either "active" or "sold". 44 | 45 | #### `price` examples 46 | 47 | - $50 one-time payment `["price", "50", "USD"]` 48 | - €15 per month `["price", "15", "EUR", "month"]` 49 | - £50,000 per year `["price", "50000", "GBP", "year"]` 50 | 51 | Other standard tags that might be useful. 52 | 53 | - `"g"`, a geohash for more precise location 54 | 55 | ## Example Event 56 | 57 | ```json 58 | { 59 | "kind": 30402, 60 | "created_at": 1675642635, 61 | // Markdown content 62 | "content": "Lorem [ipsum][nostr:nevent1qqst8cujky046negxgwwm5ynqwn53t8aqjr6afd8g59nfqwxpdhylpcpzamhxue69uhhyetvv9ujuetcv9khqmr99e3k7mg8arnc9] dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n\nRead more at nostr:naddr1qqzkjurnw4ksz9thwden5te0wfjkccte9ehx7um5wghx7un8qgs2d90kkcq3nk2jry62dyf50k0h36rhpdtd594my40w9pkal876jxgrqsqqqa28pccpzu.", 63 | "tags": [ 64 | ["d", "lorem-ipsum"], 65 | ["title", "Lorem Ipsum"], 66 | ["published_at", "1296962229"], 67 | ["t", "electronics"], 68 | ["image", "https://url.to.img", "256x256"], 69 | ["summary", "More lorem ipsum that is a little more than the title"], 70 | ["location", "NYC"], 71 | ["price", "100", "USD"], 72 | [ 73 | "e", 74 | "b3e392b11f5d4f28321cedd09303a748acfd0487aea5a7450b3481c60b6e4f87", 75 | "wss://relay.example.com" 76 | ], 77 | [ 78 | "a", 79 | "30023:a695f6b60119d9521934a691347d9f78e8770b56da16bb255ee286ddf9fda919:ipsum", 80 | "wss://relay.nostr.org" 81 | ] 82 | ], 83 | "pubkey": "...", 84 | "id": "..." 85 | } 86 | ``` 87 | -------------------------------------------------------------------------------- /27.md: -------------------------------------------------------------------------------- 1 | NIP-27 2 | ====== 3 | 4 | Text Note References 5 | -------------------- 6 | 7 | `draft` `optional` 8 | 9 | This document standardizes the treatment given by clients of inline references of other events and profiles inside the `.content` of any event that has readable text in its `.content` (such as kinds 1 and 30023). 10 | 11 | When creating an event, clients should include mentions to other profiles and to other events in the middle of the `.content` using [NIP-21](21.md) codes, such as `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`. 12 | 13 | Including [NIP-10](10.md)-style tags (`["e", , , ]`) for each reference is optional, clients should do it whenever they want the profile being mentioned to be notified of the mention, or when they want the referenced event to recognize their mention as a reply. 14 | 15 | A reader client that receives an event with such `nostr:...` mentions in its `.content` can do any desired context augmentation (for example, linking to the profile or showing a preview of the mentioned event contents) it wants in the process. If turning such mentions into links, they could become internal links, [NIP-21](21.md) links or direct links to web clients that will handle these references. 16 | 17 | --- 18 | 19 | ## Example of a profile mention process 20 | 21 | Suppose Bob is writing a note in a client that has search-and-autocomplete functionality for users that is triggered when they write the character `@`. 22 | 23 | As Bob types `"hello @mat"` the client will prompt him to autocomplete with [mattn's profile](https://njump.me/npub1937vv2nf06360qn9y8el6d8sevnndy7tuh5nzre4gj05xc32tnwqauhaj6), showing a picture and name. 24 | 25 | Bob presses "enter" and now he sees his typed note as `"hello @mattn"`, `@mattn` is highlighted, indicating that it is a mention. Internally, however, the event looks like this: 26 | 27 | ```json 28 | { 29 | "content": "hello nostr:nprofile1qqszclxx9f5haga8sfjjrulaxncvkfekj097t6f3pu65f86rvg49ehqj6f9dh", 30 | "created_at": 1679790774, 31 | "id": "f39e9b451a73d62abc5016cffdd294b1a904e2f34536a208874fe5e22bbd47cf", 32 | "kind": 1, 33 | "pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798", 34 | "sig": "f8c8bab1b90cc3d2ae1ad999e6af8af449ad8bb4edf64807386493163e29162b5852a796a8f474d6b1001cddbaac0de4392838574f5366f03cc94cf5dfb43f4d", 35 | "tags": [ 36 | [ 37 | "p", 38 | "2c7cc62a697ea3a7826521f3fd34f0cb273693cbe5e9310f35449f43622a5cdc" 39 | ] 40 | ] 41 | } 42 | ``` 43 | 44 | (Alternatively, the mention could have been a `nostr:npub1...` URL.) 45 | 46 | After Bob publishes this event and Carol sees it, her client will initially display the `.content` as it is, but later it will parse the `.content` and see that there is a `nostr:` URL in there, decode it, extract the public key from it (and possibly relay hints), fetch that profile from its internal database or relays, then replace the full URL with the name `@mattn`, with a link to the internal page view for that profile. 47 | 48 | ## Verbose and probably unnecessary considerations 49 | 50 | - The example above was very concrete, but it doesn't mean all clients have to implement the same flow. There could be clients that do not support autocomplete at all, so they just allow users to paste raw [NIP-19](19.md) codes into the body of text, then prefix these with `nostr:` before publishing the event. 51 | - The flow for referencing other events is similar: a user could paste a `note1...` or `nevent1...` code and the client will turn that into a `nostr:note1...` or `nostr:nevent1...` URL. Then upon reading such references the client may show the referenced note in a preview box or something like that -- or nothing at all. 52 | - Other display procedures can be employed: for example, if a client that is designed for dealing with only `kind:1` text notes sees, for example, a [`kind:30023`](23.md) `nostr:naddr1...` URL reference in the `.content`, it can, for example, decide to turn that into a link to some hardcoded webapp capable of displaying such events. 53 | - Clients may give the user the option to include or not include tags for mentioned events or profiles. If someone wants to mention `mattn` without notifying them, but still have a nice augmentable/clickable link to their profile inside their note, they can instruct their client to _not_ create a `["p", ...]` tag for that specific mention. 54 | - In the same way, if someone wants to reference another note but their reference is not meant to show up along other replies to that same note, their client can choose to not include a corresponding `["e", ...]` tag for any given `nostr:nevent1...` URL inside `.content`. Clients may decide to expose these advanced functionalities to users or be more opinionated about things. 55 | -------------------------------------------------------------------------------- /13.md: -------------------------------------------------------------------------------- 1 | NIP-13 2 | ====== 3 | 4 | Proof of Work 5 | ------------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines a way to generate and interpret Proof of Work for nostr notes. Proof of Work (PoW) is a way to add a proof of computational work to a note. This is a bearer proof that all relays and clients can universally validate with a small amount of code. This proof can be used as a means of spam deterrence. 10 | 11 | `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. 12 | 13 | `002f...` is `0000 0000 0010 1111...` in binary, which has 10 leading zeroes. Do not forget to count leading zeroes for hex digits <= `7`. 14 | 15 | Mining 16 | ------ 17 | 18 | To generate PoW for a `NIP-01` note, a `nonce` tag is used: 19 | 20 | ```json 21 | {"content": "It's just me mining my own business", "tags": [["nonce", "1", "21"]]} 22 | ``` 23 | 24 | When mining, the second entry to the nonce tag is updated, and then the id is recalculated (see [NIP-01](./01.md)). If the id has the desired number of leading zero bits, the note has been mined. It is recommended to update the `created_at` as well during this process. 25 | 26 | 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. 27 | 28 | Example mined note 29 | ------------------ 30 | 31 | ```json 32 | { 33 | "id": "000006d8c378af1779d2feebc7603a125d99eca0ccf1085959b307f64e5dd358", 34 | "pubkey": "a48380f4cfcc1ad5378294fcac36439770f9c878dd880ffa94bb74ea54a6f243", 35 | "created_at": 1651794653, 36 | "kind": 1, 37 | "tags": [ 38 | ["nonce", "776797", "20"] 39 | ], 40 | "content": "It's just me mining my own business", 41 | "sig": "284622fc0a3f4f1303455d5175f7ba962a3300d136085b9566801bc2e0699de0c7e31e44c81fb40ad9049173742e904713c3594a1da0fc5d2382a25c11aba977" 42 | } 43 | ``` 44 | 45 | Validating 46 | ---------- 47 | 48 | Here is some reference C code for calculating the difficulty (aka number of leading zero bits) in a nostr event id: 49 | 50 | ```c 51 | #include 52 | #include 53 | #include 54 | 55 | int countLeadingZeroes(const char *hex) { 56 | int count = 0; 57 | 58 | for (int i = 0; i < strlen(hex); i++) { 59 | int nibble = (int)strtol((char[]){hex[i], '\0'}, NULL, 16); 60 | if (nibble == 0) { 61 | count += 4; 62 | } else { 63 | count += __builtin_clz(nibble) - 28; 64 | break; 65 | } 66 | } 67 | 68 | return count; 69 | } 70 | 71 | int main(int argc, char *argv[]) { 72 | if (argc != 2) { 73 | fprintf(stderr, "Usage: %s \n", argv[0]); 74 | return 1; 75 | } 76 | 77 | const char *hex_string = argv[1]; 78 | int result = countLeadingZeroes(hex_string); 79 | printf("Leading zeroes in hex string %s: %d\n", hex_string, result); 80 | 81 | return 0; 82 | } 83 | ``` 84 | 85 | Here is some JavaScript code for doing the same thing: 86 | 87 | ```javascript 88 | // hex should be a hexadecimal string (with no 0x prefix) 89 | function countLeadingZeroes(hex) { 90 | let count = 0; 91 | 92 | for (let i = 0; i < hex.length; i++) { 93 | const nibble = parseInt(hex[i], 16); 94 | if (nibble === 0) { 95 | count += 4; 96 | } else { 97 | count += Math.clz32(nibble) - 28; 98 | break; 99 | } 100 | } 101 | 102 | return count; 103 | } 104 | ``` 105 | 106 | Querying relays for PoW notes 107 | ----------------------------- 108 | 109 | If relays allow searching on prefixes, you can use this as a way to filter notes of a certain difficulty: 110 | 111 | ``` 112 | $ echo '["REQ", "subid", {"ids": ["000000000"]}]' | websocat wss://some-relay.com | jq -c '.[2]' 113 | {"id":"000000000121637feeb68a06c8fa7abd25774bdedfa9b6ef648386fb3b70c387", ...} 114 | ``` 115 | 116 | Delegated Proof of Work 117 | ----------------------- 118 | 119 | 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. 120 | -------------------------------------------------------------------------------- /28.md: -------------------------------------------------------------------------------- 1 | 2 | NIP-28 3 | ====== 4 | 5 | Public Chat 6 | ----------- 7 | 8 | `draft` `optional` 9 | 10 | This NIP defines new event kinds for public chat channels, channel messages, and basic client-side moderation. 11 | 12 | It reserves five event kinds (40-44) for immediate use: 13 | 14 | - `40 - channel create` 15 | - `41 - channel metadata` 16 | - `42 - channel message` 17 | - `43 - hide message` 18 | - `44 - mute user` 19 | 20 | Client-centric moderation gives client developers discretion over what types of content they want included in their apps, while imposing no additional requirements on relays. 21 | 22 | ## Kind 40: Create channel 23 | 24 | Create a public chat channel. 25 | 26 | In the channel creation `content` field, Client SHOULD include basic channel metadata (`name`, `about`, `picture` and `relays` as specified in kind 41). 27 | 28 | ```json 29 | { 30 | "content": "{\"name\": \"Demo Channel\", \"about\": \"A test channel.\", \"picture\": \"https://placekitten.com/200/200\", \"relays\": [\"wss://nos.lol\", \"wss://nostr.mom\"]}", 31 | ... 32 | } 33 | ``` 34 | 35 | 36 | ## Kind 41: Set channel metadata 37 | 38 | Update a channel's public metadata. 39 | 40 | Kind 41 is used to update the metadata without modifying the event id for the channel. Only the most recent kind 41 per `e` tag value MAY be available. 41 | 42 | Clients SHOULD ignore kind 41s from pubkeys other than the kind 40 pubkey. 43 | 44 | Clients SHOULD support basic metadata fields: 45 | 46 | - `name` - string - Channel name 47 | - `about` - string - Channel description 48 | - `picture` - string - URL of channel picture 49 | - `relays` - array - List of relays to download and broadcast events to 50 | 51 | Clients MAY add additional metadata fields. 52 | 53 | Clients SHOULD use [NIP-10](10.md) marked "e" tags to recommend a relay. 54 | 55 | ```json 56 | { 57 | "content": "{\"name\": \"Updated Demo Channel\", \"about\": \"Updating a test channel.\", \"picture\": \"https://placekitten.com/201/201\", \"relays\": [\"wss://nos.lol\", \"wss://nostr.mom\"]}", 58 | "tags": [["e", , ]], 59 | ... 60 | } 61 | ``` 62 | 63 | 64 | ## Kind 42: Create channel message 65 | 66 | Send a text message to a channel. 67 | 68 | Clients SHOULD use [NIP-10](10.md) marked "e" tags to recommend a relay and specify whether it is a reply or root message. 69 | 70 | Clients SHOULD append [NIP-10](10.md) "p" tags to replies. 71 | 72 | Root message: 73 | 74 | ```json 75 | { 76 | "content": , 77 | "tags": [["e", , , "root"]], 78 | ... 79 | } 80 | ``` 81 | 82 | Reply to another message: 83 | 84 | ```json 85 | { 86 | "content": , 87 | "tags": [ 88 | ["e", , , "root"], 89 | ["e", , , "reply"], 90 | ["p", , ], 91 | ... 92 | ], 93 | ... 94 | } 95 | ``` 96 | 97 | 98 | ## Kind 43: Hide message 99 | 100 | User no longer wants to see a certain message. 101 | 102 | The `content` may optionally include metadata such as a `reason`. 103 | 104 | Clients SHOULD hide event 42s shown to a given user, if there is an event 43 from that user matching the event 42 `id`. 105 | 106 | Clients MAY hide event 42s for other users other than the user who sent the event 43. 107 | 108 | (For example, if three users 'hide' an event giving a reason that includes the word 'pornography', a Nostr client that is an iOS app may choose to hide that message for all iOS clients.) 109 | 110 | ```json 111 | { 112 | "content": "{\"reason\": \"Dick pic\"}", 113 | "tags": [["e", ]], 114 | ... 115 | } 116 | ``` 117 | 118 | ## Kind 44: Mute user 119 | 120 | User no longer wants to see messages from another user. 121 | 122 | The `content` may optionally include metadata such as a `reason`. 123 | 124 | Clients SHOULD hide event 42s shown to a given user, if there is an event 44 from that user matching the event 42 `pubkey`. 125 | 126 | Clients MAY hide event 42s for users other than the user who sent the event 44. 127 | 128 | ```json 129 | { 130 | "content": "{\"reason\": \"Posting dick pics\"}", 131 | "tags": [["p", ]], 132 | ... 133 | } 134 | ``` 135 | 136 | ## Relay recommendations 137 | 138 | Clients SHOULD use the relay URLs of the metadata events. 139 | 140 | Clients MAY use 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. 141 | 142 | Motivation 143 | ---------- 144 | If we're solving censorship-resistant communication for social media, we may as well solve it also for Telegram-style messaging. 145 | 146 | We can bring the global conversation out from walled gardens into a true public square open to all. 147 | 148 | 149 | Additional info 150 | --------------- 151 | 152 | - [Chat demo PR with fiatjaf+jb55 comments](https://github.com/ArcadeCity/arcade/pull/28) 153 | - [Conversation about NIP16](https://t.me/nostr_protocol/29566) 154 | -------------------------------------------------------------------------------- /58.md: -------------------------------------------------------------------------------- 1 | NIP-58 2 | ====== 3 | 4 | Badges 5 | ------ 6 | 7 | `draft` `optional` 8 | 9 | Three special events are used to define, award and display badges in 10 | user profiles: 11 | 12 | 1. A "Badge Definition" event is defined as a parameterized replaceable event with kind `30009` having a `d` tag with a value that uniquely identifies the badge (e.g. `bravery`) published by the badge issuer. Badge definitions can be updated. 13 | 14 | 2. A "Badge Award" event is a kind `8` event with a single `a` tag referencing a "Badge Definition" event and one or more `p` tags, one for each pubkey the badge issuer wishes to award. Awarded badges are immutable and non-transferrable. 15 | 16 | 3. A "Profile Badges" event is defined as a parameterized replaceable event 17 | with kind `30008` with a `d` tag with the value `profile_badges`. 18 | Profile badges contain an ordered list of pairs of `a` and `e` tags referencing a `Badge Definition` and a `Badge Award` for each badge to be displayed. 19 | 20 | ### Badge Definition event 21 | 22 | The following tags MUST be present: 23 | 24 | - `d` tag with the unique name of the badge. 25 | 26 | The following tags MAY be present: 27 | 28 | - A `name` tag with a short name for the badge. 29 | - `image` tag whose value is the URL of a high-resolution image representing the badge. The second value optionally specifies the dimensions of the image as `width`x`height` in pixels. Badge recommended dimensions is 1024x1024 pixels. 30 | - A `description` tag whose value MAY contain a textual representation of the 31 | image, the meaning behind the badge, or the reason of its issuance. 32 | - One or more `thumb` tags whose first value is an URL pointing to a thumbnail version of the image referenced in the `image` tag. The second value optionally specifies the dimensions of the thumbnail as `width`x`height` in pixels. 33 | 34 | ### Badge Award event 35 | 36 | The following tags MUST be present: 37 | 38 | - An `a` tag referencing a kind `30009` Badge Definition event. 39 | - One or more `p` tags referencing each pubkey awarded. 40 | 41 | ### Profile Badges Event 42 | 43 | The number of badges a pubkey can be awarded is unbounded. The Profile Badge 44 | event allows individual users to accept or reject awarded badges, as well 45 | as choose the display order of badges on their profiles. 46 | 47 | The following tags MUST be present: 48 | 49 | - A `d` tag with the unique identifier `profile_badges` 50 | 51 | The following tags MAY be present: 52 | 53 | - Zero or more ordered consecutive pairs of `a` and `e` tags referencing a kind `30009` Badge Definition and kind `8` Badge Award, respectively. Clients SHOULD 54 | ignore `a` without corresponding `e` tag and viceversa. Badge Awards referenced 55 | by the `e` tags should contain the same `a` tag. 56 | 57 | ### Motivation 58 | 59 | Users MAY be awarded badges (but not limited to) in recognition, in gratitude, for participation, or in appreciation of a certain goal, task or cause. 60 | 61 | Users MAY choose to decorate their profiles with badges for fame, notoriety, recognition, support, etc., from badge issuers they deem reputable. 62 | 63 | ### Recommendations 64 | 65 | Clients MAY whitelist badge issuers (pubkeys) for the purpose of ensuring they retain a valuable/special factor for their users. 66 | 67 | Badge image recommended aspect ratio is 1:1 with a high-res size of 1024x1024 pixels. 68 | 69 | Badge thumbnail image recommended dimensions are: 512x512 (xl), 256x256 (l), 64x64 (m), 32x32 (s) and 16x16 (xs). 70 | 71 | Clients MAY choose to render less badges than those specified by users in the Profile Badges event or replace the badge image and thumbnails with ones that fits the theme of the client. 72 | 73 | Clients SHOULD attempt to render the most appropriate badge thumbnail according to the number of badges chosen by the user and space available. Clients SHOULD attempt render the high-res version on user action (click, tap, hover). 74 | 75 | ### Example of a Badge Definition event 76 | 77 | ```json 78 | { 79 | "pubkey": "alice", 80 | "kind": 30009, 81 | "tags": [ 82 | ["d", "bravery"], 83 | ["name", "Medal of Bravery"], 84 | ["description", "Awarded to users demonstrating bravery"], 85 | ["image", "https://nostr.academy/awards/bravery.png", "1024x1024"], 86 | ["thumb", "https://nostr.academy/awards/bravery_256x256.png", "256x256"] 87 | ], 88 | ... 89 | } 90 | ``` 91 | 92 | ### Example of Badge Award event 93 | 94 | ```json 95 | { 96 | "id": "", 97 | "kind": 8, 98 | "pubkey": "alice", 99 | "tags": [ 100 | ["a", "30009:alice:bravery"], 101 | ["p", "bob", "wss://relay"], 102 | ["p", "charlie", "wss://relay"] 103 | ], 104 | ... 105 | } 106 | ``` 107 | 108 | ### Example of a Profile Badges event 109 | 110 | Honorable Bob The Brave: 111 | ```json 112 | { 113 | "kind": 30008, 114 | "pubkey": "bob", 115 | "tags": [ 116 | ["d", "profile_badges"], 117 | ["a", "30009:alice:bravery"], 118 | ["e", "", "wss://nostr.academy"], 119 | ["a", "30009:alice:honor"], 120 | ["e", "", "wss://nostr.academy"] 121 | ], 122 | ... 123 | } 124 | ``` 125 | -------------------------------------------------------------------------------- /42.md: -------------------------------------------------------------------------------- 1 | NIP-42 2 | ====== 3 | 4 | Authentication of clients to relays 5 | ----------------------------------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines a way for clients to authenticate to relays by signing an ephemeral event. 10 | 11 | ## Motivation 12 | 13 | A relay may want to require clients to authenticate to access restricted resources. For example, 14 | 15 | - 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; 16 | - 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. 17 | - A relay may limit subscriptions of any kind to paying users or users whitelisted through any other means, and require authentication. 18 | 19 | ## Definitions 20 | 21 | ### New client-relay protocol messages 22 | 23 | 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 has the following form: 24 | 25 | ```json 26 | ["AUTH", ] 27 | ``` 28 | 29 | And, when sent by clients, the following form: 30 | 31 | ```json 32 | ["AUTH", ] 33 | ``` 34 | 35 | `AUTH` messages sent by clients MUST be answered with an `OK` message, like any `EVENT` message. 36 | 37 | ### Canonical authentication event 38 | 39 | The signed event is an ephemeral event not meant to be published or queried, it must be of `kind: 22242` and it should have at least two tags, one for the relay URL and one for the challenge string as received from the relay. Relays MUST exclude `kind: 22242` events from being broadcasted to any client. `created_at` should be the current time. Example: 40 | 41 | ```json 42 | { 43 | "kind": 22242, 44 | "tags": [ 45 | ["relay", "wss://relay.example.com/"], 46 | ["challenge", "challengestringhere"] 47 | ], 48 | ... 49 | } 50 | ``` 51 | 52 | ### `OK` and `CLOSED` machine-readable prefixes 53 | 54 | This NIP defines two new prefixes that can be used in `OK` (in response to event writes by clients) and `CLOSED` (in response to rejected subscriptions by clients): 55 | 56 | - `"auth-required: "` - for when a client has not performed `AUTH` and the relay requires that to fulfill the query or write the event. 57 | - `"restricted: "` - for when a client has already performed `AUTH` but the key used to perform it is still not allowed by the relay or is exceeding its authorization. 58 | 59 | ## Protocol flow 60 | 61 | At any moment the relay may send an `AUTH` message to the client containing a challenge. The challenge is valid for the duration of the connection or until another challenge is sent by the relay. The client MAY decide to send its `AUTH` event at any point and the authenticated session is valid afterwards for the duration of the connection. 62 | 63 | ### `auth-required` in response to a `REQ` message 64 | 65 | Given that a relay is likely to require clients to perform authentication only for certain jobs, like answering a `REQ` or accepting an `EVENT` write, these are some expected common flows: 66 | 67 | ``` 68 | relay: ["AUTH", ""] 69 | client: ["REQ", "sub_1", {"kinds": [4]}] 70 | relay: ["CLOSED", "sub_1", "auth-required: we can't serve DMs to unauthenticated users"] 71 | client: ["AUTH", {"id": "abcdef...", ...}] 72 | relay: ["OK", "abcdef...", true, ""] 73 | client: ["REQ", "sub_1", {"kinds": [4]}] 74 | relay: ["EVENT", "sub_1", {...}] 75 | relay: ["EVENT", "sub_1", {...}] 76 | relay: ["EVENT", "sub_1", {...}] 77 | relay: ["EVENT", "sub_1", {...}] 78 | ... 79 | ``` 80 | 81 | In this case, the `AUTH` message from the relay could be sent right as the client connects or it can be sent immediately before the `CLOSED` is sent. The only requirement is that _the client must have a stored challenge associated with that relay_ so it can act upon that in response to the `auth-required` `CLOSED` message. 82 | 83 | ### `auth-required` in response to an `EVENT` message 84 | 85 | The same flow is valid for when a client wants to write an `EVENT` to the relay, except now the relay sends back an `OK` message instead of a `CLOSED` message: 86 | 87 | ``` 88 | relay: ["AUTH", ""] 89 | client: ["EVENT", {"id": "012345...", ...}] 90 | relay: ["OK", "012345...", false, "auth-required: we only accept events from registered users"] 91 | client: ["AUTH", {"id": "abcdef...", ...}] 92 | relay: ["OK", "abcdef...", true, ""] 93 | client: ["EVENT", {"id": "012345...", ...}] 94 | relay: ["OK", "012345...", true, ""] 95 | ``` 96 | 97 | ## Signed Event Verification 98 | 99 | To verify `AUTH` messages, relays must ensure: 100 | 101 | - that the `kind` is `22242`; 102 | - that the event `created_at` is close (e.g. within ~10 minutes) of the current time; 103 | - that the `"challenge"` tag matches the challenge sent before; 104 | - that the `"relay"` tag matches the relay URL: 105 | - URL normalization techniques can be applied. For most cases just checking if the domain name is correct should be enough. 106 | -------------------------------------------------------------------------------- /26.md: -------------------------------------------------------------------------------- 1 | NIP-26 2 | ======= 3 | 4 | Delegated Event Signing 5 | ----- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines how events can be delegated so that they can be signed by other keypairs. 10 | 11 | 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. 12 | 13 | #### Introducing the 'delegation' tag 14 | 15 | This NIP introduces a new tag: `delegation` which is formatted as follows: 16 | 17 | ```json 18 | [ 19 | "delegation", 20 | , 21 | , 22 | 23 | ] 24 | ``` 25 | 26 | ##### Delegation Token 27 | 28 | The **delegation token** should be a 64-byte Schnorr signature of the sha256 hash of the following string: 29 | 30 | ``` 31 | nostr:delegation:: 32 | ``` 33 | 34 | ##### Conditions Query String 35 | 36 | The following fields and operators are supported in the above query string: 37 | 38 | *Fields*: 39 | 1. `kind` 40 | - *Operators*: 41 | - `=${KIND_NUMBER}` - delegatee may only sign events of this kind 42 | 2. `created_at` 43 | - *Operators*: 44 | - `<${TIMESTAMP}` - delegatee may only sign events created ***before*** the specified timestamp 45 | - `>${TIMESTAMP}` - delegatee may only sign events created ***after*** the specified timestamp 46 | 47 | 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 `&`. 48 | 49 | For example, the following condition strings are valid: 50 | 51 | - `kind=1&created_at<1675721813` 52 | - `kind=0&kind=1&created_at>1675721813` 53 | - `kind=1&created_at>1674777689&created_at<1675721813` 54 | 55 | For the vast majority of use-cases, it is advisable that: 56 | 1. Query strings should include a `created_at` ***after*** condition reflecting the current time, to prevent the delegatee from publishing historic notes on the delegator's behalf. 57 | 2. Query strings should include a `created_at` ***before*** condition that is not empty and is not some extremely distant time in the future. If delegations are not limited in time scope, they expose similar security risks to simply using the root key for authentication. 58 | 59 | #### Example 60 | 61 | ``` 62 | # Delegator: 63 | privkey: ee35e8bb71131c02c1d7e73231daa48e9953d329a4b701f7133c8f46dd21139c 64 | pubkey: 8e0d3d3eb2881ec137a11debe736a9086715a8c8beeeda615780064d68bc25dd 65 | 66 | # Delegatee: 67 | privkey: 777e4f60b4aa87937e13acc84f7abcc3c93cc035cb4c1e9f7a9086dd78fffce1 68 | pubkey: 477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396 69 | ``` 70 | 71 | Delegation string to grant note publishing authorization to the delegatee (477318cf) from now, for the next 30 days, given the current timestamp is `1674834236`. 72 | ```json 73 | nostr:delegation:477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396:kind=1&created_at>1674834236&created_at<1677426236 74 | ``` 75 | 76 | The delegator (8e0d3d3e) then signs a SHA256 hash of the above delegation string, the result of which is the delegation token: 77 | ``` 78 | 6f44d7fe4f1c09f3954640fb58bd12bae8bb8ff4120853c4693106c82e920e2b898f1f9ba9bd65449a987c39c0423426ab7b53910c0c6abfb41b30bc16e5f524 79 | ``` 80 | 81 | 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. 82 | ```json 83 | { 84 | "id": "e93c6095c3db1c31d15ac771f8fc5fb672f6e52cd25505099f62cd055523224f", 85 | "pubkey": "477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396", 86 | "created_at": 1677426298, 87 | "kind": 1, 88 | "tags": [ 89 | [ 90 | "delegation", 91 | "8e0d3d3eb2881ec137a11debe736a9086715a8c8beeeda615780064d68bc25dd", 92 | "kind=1&created_at>1674834236&created_at<1677426236", 93 | "6f44d7fe4f1c09f3954640fb58bd12bae8bb8ff4120853c4693106c82e920e2b898f1f9ba9bd65449a987c39c0423426ab7b53910c0c6abfb41b30bc16e5f524" 94 | ] 95 | ], 96 | "content": "Hello, world!", 97 | "sig": "633db60e2e7082c13a47a6b19d663d45b2a2ebdeaf0b4c35ef83be2738030c54fc7fd56d139652937cdca875ee61b51904a1d0d0588a6acd6168d7be2909d693" 98 | } 99 | ``` 100 | 101 | The event should be considered a valid delegation if the conditions are satisfied (`kind=1`, `created_at>1674834236` and `created_at<1677426236` in this example) and, upon validation of the delegation token, are found to be unchanged from the conditions in the original delegation string. 102 | 103 | Clients should display the delegated note as if it was published directly by the delegator (8e0d3d3e). 104 | 105 | 106 | #### Relay & Client Support 107 | 108 | Relays should answer requests such as `["REQ", "", {"authors": ["A"]}]` by querying both the `pubkey` and delegation tags `[1]` value. 109 | 110 | Relays SHOULD allow the delegator (8e0d3d3e) to delete the events published by the delegatee (477318cf). 111 | -------------------------------------------------------------------------------- /49.md: -------------------------------------------------------------------------------- 1 | 2 | NIP-49 3 | ====== 4 | 5 | Private Key Encryption 6 | ---------------------- 7 | 8 | `draft` `optional` 9 | 10 | This NIP defines a method by which clients can encrypt (and decrypt) a user's private key with a password. 11 | 12 | Symmetric Encryption Key derivation 13 | ----------------------------------- 14 | 15 | PASSWORD = Read from the user. The password should be unicode normalized to NFKC format to ensure that the password can be entered identically on other computers/clients. 16 | 17 | LOG\_N = Let the user or implementer choose one byte representing a power of 2 (e.g. 18 represents 262,144) which is used as the number of rounds for scrypt. Larger numbers take more time and more memory, and offer better protection: 18 | 19 | | LOG_N | MEMORY REQUIRED | APPROX TIME ON FAST COMPUTER | 20 | |-------|-----------------|----------------------------- | 21 | | 16 | 64 MiB | 100 ms | 22 | | 18 | 256 MiB | | 23 | | 20 | 1 GiB | 2 seconds | 24 | | 21 | 2 GiB | | 25 | | 22 | 4 GiB | | 26 | 27 | SALT = 16 random bytes 28 | 29 | SYMMETRIC_KEY = scrypt(password=PASSWORD, salt=SALT, log\_n=LOG\_N, r=8, p=1) 30 | 31 | The symmetric key should be 32 bytes long. 32 | 33 | This symmetric encryption key is temporary and should be zeroed and discarded after use and not stored or reused for any other purpose. 34 | 35 | 36 | Encrypting a private key 37 | ------------------------ 38 | 39 | The private key encryption process is as follows: 40 | 41 | PRIVATE\_KEY = User's private (secret) secp256k1 key as 32 raw bytes (not hex or bech32 encoded!) 42 | 43 | KEY\_SECURITY\_BYTE = one of: 44 | 45 | * 0x00 - if the key has been known to have been handled insecurely (stored unencrypted, cut and paste unencrypted, etc) 46 | * 0x01 - if the key has NOT been known to have been handled insecurely (stored unencrypted, cut and paste unencrypted, etc) 47 | * 0x02 - if the client does not track this data 48 | 49 | ASSOCIATED\_DATA = KEY\_SECURITY\_BYTE 50 | 51 | NONCE = 24 byte random nonce 52 | 53 | CIPHERTEXT = XChaCha20-Poly1305( 54 | plaintext=PRIVATE\_KEY, 55 | associated_data=ASSOCIATED\_DATA, 56 | nonce=NONCE, 57 | key=SYMMETRIC\_KEY 58 | ) 59 | 60 | VERSION\_NUMBER = 0x02 61 | 62 | CIPHERTEXT_CONCATENATION = concat( 63 | VERSION\_NUMBER, 64 | LOG\_N, 65 | SALT, 66 | NONCE, 67 | ASSOCIATED\_DATA, 68 | CIPHERTEXT 69 | ) 70 | 71 | ENCRYPTED\_PRIVATE\_KEY = bech32_encode('ncryptsec', CIPHERTEXT\_CONCATENATION) 72 | 73 | The output prior to bech32 encoding should be 91 bytes long. 74 | 75 | The decryption process operates in the reverse. 76 | 77 | 78 | Test Data 79 | --------- 80 | 81 | ## Password Unicode Normalization 82 | 83 | The following password input: "ÅΩẛ̣" 84 | - Unicode Codepoints: U+212B U+2126 U+1E9B U+0323 85 | - UTF-8 bytes: [0xE2, 0x84, 0xAB, 0xE2, 0x84, 0xA6, 0xE1, 0xBA, 0x9B, 0xCC, 0xA3] 86 | 87 | Should be converted into the unicode normalized NFKC format prior to use in scrypt: "ÅΩẛ̣" 88 | - Unicode Codepoints: U+00C5 U+03A9 U+1E69 89 | - UTF-8 bytes: [0xC3, 0x85, 0xCE, 0xA9, 0xE1, 0xB9, 0xA9] 90 | 91 | ## Encryption 92 | 93 | The encryption process is non-deterministic due to the random nonce. 94 | 95 | ## Decryption 96 | 97 | The following encrypted private key: 98 | 99 | `ncryptsec1qgg9947rlpvqu76pj5ecreduf9jxhselq2nae2kghhvd5g7dgjtcxfqtd67p9m0w57lspw8gsq6yphnm8623nsl8xn9j4jdzz84zm3frztj3z7s35vpzmqf6ksu8r89qk5z2zxfmu5gv8th8wclt0h4p` 100 | 101 | When decrypted with password='nostr' and log_n=16 yields the following hex-encoded private key: 102 | 103 | `3501454135014541350145413501453fefb02227e449e57cf4d3a3ce05378683` 104 | 105 | Discussion 106 | ---------- 107 | 108 | ### On Key Derivation 109 | 110 | Passwords make poor cryptographic keys. Prior to use as a cryptographic key, two things need to happen: 111 | 112 | 1. An encryption key needs to be deterministically created from the password such that is has a uniform functionally random distribution of bits, such that the symmetric encryption algorithm's assumptions are valid, and 113 | 2. A slow irreversible algorithm should be injected into the process, so that brute-force attempts to decrypt by trying many passwords are severely hampered. 114 | 115 | These are achieved using a password-based key derivation function. We use scrypt, which has been proven to be maximally memory hard and which several cryptographers have indicated to the author is better than argon2 even though argon2 won a competition in 2015. 116 | 117 | ### On the symmetric encryption algorithm 118 | 119 | XChaCha20-Poly1305 is typically favored by cryptographers over AES and is less associated with the U.S. government. It (or it's earlier variant without the 'X') is gaining wide usage, is used in TLS and OpenSSH, and is available in most modern crypto libraries. 120 | 121 | Recommendations 122 | --------- 123 | 124 | It is not recommended that users publish these encrypted private keys to nostr, as cracking a key may become easier when an attacker can amass many encrypted private keys. 125 | 126 | It is recommended that clients zero out the memory of passwords and private keys before freeing that memory. 127 | -------------------------------------------------------------------------------- /72.md: -------------------------------------------------------------------------------- 1 | NIP-72 2 | ====== 3 | 4 | Moderated Communities (Reddit Style) 5 | ------------------------------------ 6 | 7 | `draft` `optional` 8 | 9 | The goal of this NIP is to create moderator-approved public communities around a topic. It defines the replaceable event `kind:34550` to define the community and the current list of moderators/administrators. Users that want to post into the community, simply tag any Nostr event with the community's `a` tag. Moderators issue an approval event `kind:4550` that links the community with the new post. 10 | 11 | # Community Definition 12 | 13 | `kind:34550` SHOULD include any field that helps define the community and the set of moderators. `relay` tags MAY be used to describe the preferred relay to download requests and approvals. 14 | 15 | ```jsonc 16 | { 17 | "created_at": , 18 | "kind": 34550, 19 | "tags": [ 20 | ["d", ""], 21 | ["description", ""], 22 | ["image", "", "x"], 23 | 24 | //.. other tags relevant to defining the community 25 | 26 | // moderators 27 | ["p", "<32-bytes hex of a pubkey1>", "", "moderator"], 28 | ["p", "<32-bytes hex of a pubkey2>", "", "moderator"], 29 | ["p", "<32-bytes hex of a pubkey3>", "", "moderator"], 30 | 31 | // relays used by the community (w/optional marker) 32 | ["relay", "", "author"], 33 | ["relay", "", "requests"], 34 | ["relay", "", "approvals"], 35 | ["relay", ""] 36 | ], 37 | ... 38 | } 39 | ``` 40 | 41 | # New Post Request 42 | 43 | Any Nostr event can be submitted to a community by anyone for approval. Clients MUST add the community's `a` tag to the new post event in order to be presented for the moderator's approval. 44 | 45 | ```jsonc 46 | { 47 | "kind": 1, 48 | "tags": [ 49 | ["a", "34550::", ""], 50 | ], 51 | "content": "hello world", 52 | // ... 53 | } 54 | ``` 55 | 56 | Community management clients MAY filter all mentions to a given `kind:34550` event and request moderators to approve each submission. Moderators MAY delete his/her approval of a post at any time using event deletions (See [NIP-09](09.md)). 57 | 58 | # Post Approval by moderators 59 | 60 | The post-approval event MUST include `a` tags of the communities the moderator is posting into (one or more), the `e` tag of the post and `p` tag of the author of the post (for approval notifications). The event SHOULD also include the stringified `post request` event inside the `.content` ([NIP-18-style](18.md)) and a `k` tag with the original post's event kind to allow filtering of approved posts by kind. 61 | 62 | ```jsonc 63 | { 64 | "pubkey": "<32-bytes lowercase hex-encoded public key of the event creator>", 65 | "kind": 4550, 66 | "tags": [ 67 | ["a", "34550::", ""], 68 | ["e", "", ""], 69 | ["p", "", ""], 70 | ["k", ""] 71 | ], 72 | "content": "", 73 | // ... 74 | } 75 | ``` 76 | 77 | It's recommended that multiple moderators approve posts to avoid deleting them from the community when a moderator is removed from the owner's list. In case the full list of moderators must be rotated, the new moderator set must sign new approvals for posts in the past or the community will restart. The owner can also periodically copy and re-sign of each moderator's approval events to make sure posts don't disappear with moderators. 78 | 79 | Post Approvals of replaceable events can be created in three ways: (i) by tagging the replaceable event as an `e` tag if moderators want to approve each individual change to the replaceable event; (ii) by tagging the replaceable event as an `a` tag if the moderator authorizes the replaceable event author to make changes without additional approvals and (iii) by tagging the replaceable event with both its `e` and `a` tag which empowers clients to display the original and updated versions of the event, with appropriate remarks in the UI. Since relays are instructed to delete old versions of a replaceable event, the `.content` of an `e`-approval MUST have the specific version of the event or Clients might not be able to find that version of the content anywhere. 80 | 81 | Clients SHOULD evaluate any non-`34550:*` `a` tag as posts to be included in all `34550:*` `a` tags. 82 | 83 | # Displaying 84 | 85 | Community clients SHOULD display posts that have been approved by at least 1 moderator or by the community owner. 86 | 87 | The following filter displays the approved posts. 88 | 89 | ```json 90 | [ 91 | "REQ", 92 | "_", 93 | { 94 | "authors": ["", "", "", "", ...], 95 | "kinds": [4550], 96 | "#a": ["34550::"], 97 | } 98 | ] 99 | ``` 100 | 101 | Clients MAY hide approvals by blocked moderators at the user's request. 102 | -------------------------------------------------------------------------------- /32.md: -------------------------------------------------------------------------------- 1 | NIP-32 2 | ====== 3 | 4 | Labeling 5 | --------- 6 | 7 | `draft` `optional` 8 | 9 | A label is a `kind 1985` event that is used to label other entities. This supports a number of use cases, 10 | including distributed moderation, collection management, license assignment, and content classification. 11 | 12 | This NIP introduces two new tags: 13 | 14 | - `L` denotes a label namespace 15 | - `l` denotes a label 16 | 17 | Label Namespace Tag 18 | ---- 19 | 20 | An `L` tag can be any string, but publishers SHOULD ensure they are unambiguous by using a well-defined namespace 21 | (such as an ISO standard) or reverse domain name notation. 22 | 23 | `L` tags are RECOMMENDED in order to support searching by namespace rather than by a specific tag. The special `ugc` 24 | ("user generated content") namespace MAY be used when the label content is provided by an end user. 25 | 26 | `L` tags starting with `#` indicate that the label target should be associated with the label's value. 27 | This is a way of attaching standard nostr tags to events, pubkeys, relays, urls, etc. 28 | 29 | Label Tag 30 | ---- 31 | 32 | An `l` tag's value can be any string. If using an `L` tag, `l` tags MUST include a mark matching an `L` 33 | tag value in the same event. If no `L` tag is included, a mark SHOULD still be included. If none is 34 | included, `ugc` is implied. 35 | 36 | Label Target 37 | ---- 38 | 39 | The label event MUST include one or more tags representing the object or objects being 40 | labeled: `e`, `p`, `a`, `r`, or `t` tags. This allows for labeling of events, people, relays, 41 | or topics respectively. As with NIP-01, a relay hint SHOULD be included when using `e` and 42 | `p` tags. 43 | 44 | Content 45 | ------- 46 | 47 | Labels should be short, meaningful strings. Longer discussions, such as for an 48 | explanation of why something was labeled the way it was, should go in the event's `content` field. 49 | 50 | Self-Reporting 51 | ------- 52 | 53 | `l` and `L` tags MAY be added to other event kinds to support self-reporting. For events 54 | with a kind other than 1985, labels refer to the event itself. 55 | 56 | Example events 57 | -------------- 58 | 59 | A suggestion that multiple pubkeys be associated with the `permies` topic. 60 | 61 | ```json 62 | { 63 | "kind": 1985, 64 | "tags": [ 65 | ["L", "#t"], 66 | ["l", "permies", "#t"], 67 | ["p", , ], 68 | ["p", , ] 69 | ], 70 | ... 71 | } 72 | ``` 73 | 74 | A report flagging violence toward a human being as defined by ontology.example.com. 75 | 76 | ```json 77 | { 78 | "kind": 1985, 79 | "tags": [ 80 | ["L", "com.example.ontology"], 81 | ["l", "VI-hum", "com.example.ontology"], 82 | ["p", , ], 83 | ["p", , ] 84 | ], 85 | ... 86 | } 87 | ``` 88 | 89 | A moderation suggestion for a chat event. 90 | 91 | ```json 92 | { 93 | "kind": 1985, 94 | "tags": [ 95 | ["L", "nip28.moderation"], 96 | ["l", "approve", "nip28.moderation"], 97 | ["e", , ] 98 | ], 99 | ... 100 | } 101 | ``` 102 | 103 | Assignment of a license to an event. 104 | 105 | ```json 106 | { 107 | "kind": 1985, 108 | "tags": [ 109 | ["L", "license"], 110 | ["l", "MIT", "license"], 111 | ["e", , ] 112 | ], 113 | ... 114 | } 115 | ``` 116 | 117 | Publishers can self-label by adding `l` tags to their own non-1985 events. In this case, the kind 1 event's author 118 | is labeling their note as being related to Milan, Italy using ISO 3166-2. 119 | 120 | ```json 121 | { 122 | "kind": 1, 123 | "tags": [ 124 | ["L", "ISO-3166-2"], 125 | ["l", "IT-MI", "ISO-3166-2"] 126 | ], 127 | "content": "It's beautiful here in Milan!", 128 | ... 129 | } 130 | ``` 131 | 132 | Other Notes 133 | ----------- 134 | 135 | When using this NIP to bulk-label many targets at once, events may be deleted and a replacement 136 | may be published. We have opted not to use parameterizable/replaceable events for this due to the 137 | complexity in coming up with a standard `d` tag. In order to avoid ambiguity when querying, 138 | publishers SHOULD limit labeling events to a single namespace. 139 | 140 | Before creating a vocabulary, explore how your use case may have already been designed and 141 | imitate that design if possible. Reverse domain name notation is encouraged to avoid 142 | namespace clashes, but for the sake of interoperability all namespaces should be 143 | considered open for public use, and not proprietary. In other words, if there is a 144 | namespace that fits your use case, use it even if it points to someone else's domain name. 145 | 146 | Vocabularies MAY choose to fully qualify all labels within a namespace (for example, 147 | `["l", "com.example.vocabulary:my-label"]`. This may be preferred when defining more 148 | formal vocabularies that should not be confused with another namespace when querying 149 | without an `L` tag. For these vocabularies, all labels SHOULD include the namespace 150 | (rather than mixing qualified and unqualified labels). 151 | 152 | A good heuristic for whether a use case fits this NIP is whether labels would ever be unique. 153 | For example, many events might be labeled with a particular place, topic, or pubkey, but labels 154 | with specific values like "John Doe" or "3.18743" are not labels, they are values, and should 155 | be handled in some other way. 156 | 157 | 158 | Appendix: Known Ontologies 159 | ------------------------- 160 | 161 | Below is a non-exhaustive list of ontologies currently in widespread use. 162 | 163 | - [social.ontolo.categories](https://ontolo.social/) 164 | -------------------------------------------------------------------------------- /53.md: -------------------------------------------------------------------------------- 1 | NIP-53 2 | ====== 3 | 4 | Live Activities 5 | --------------- 6 | 7 | `draft` `optional` 8 | 9 | Service providers want to offer live activities to the Nostr network in such a way that participants can easily log and query by clients. This NIP describes a general framework to advertise the involvement of pubkeys in such live activities. 10 | 11 | ## Concepts 12 | 13 | ### Live Event 14 | 15 | A special event with `kind:30311` "Live Event" is defined as a _parameterized replaceable event_ of public `p` tags. Each `p` tag SHOULD have a **displayable** marker name for the current role (e.g. `Host`, `Speaker`, `Participant`) of the user in the event and the relay information MAY be empty. This event will be constantly updated as participants join and leave the activity. 16 | 17 | For example: 18 | 19 | ```json 20 | { 21 | "kind": 30311, 22 | "tags": [ 23 | ["d", ""], 24 | ["title", ""], 25 | ["summary", ""], 26 | ["image", ""], 27 | ["t", "hashtag"] 28 | ["streaming", ""], 29 | ["recording", ""], // used to place the edited video once the activity is over 30 | ["starts", ""], 31 | ["ends", ""], 32 | ["status", ""], 33 | ["current_participants", ""], 34 | ["total_participants", ""], 35 | ["p", "91cf9..4e5ca", "wss://provider1.com/", "Host", ""], 36 | ["p", "14aeb..8dad4", "wss://provider2.com/nostr", "Speaker"], 37 | ["p", "612ae..e610f", "ws://provider3.com/ws", "Participant"], 38 | ["relays", "wss://one.com", "wss://two.com", ...] 39 | ], 40 | "content": "", 41 | ... 42 | } 43 | ``` 44 | 45 | A distinct `d` tag should be used for each activity. All other tags are optional. 46 | 47 | Providers SHOULD keep the participant list small (e.g. under 1000 users) and, when limits are reached, Providers SHOULD select which participants get named in the event. Clients should not expect a comprehensive list. Once the activity ends, the event can be deleted or updated to summarize the activity and provide async content (e.g. recording of the event). 48 | 49 | Clients are expected to subscribe to `kind:30311` events in general or for given follow lists and statuses. Clients MAY display participants' roles in activities as well as access points to join the activity. 50 | 51 | Live Activity management clients are expected to constantly update `kind:30311` during the event. Clients MAY choose to consider `status=live` events after 1hr without any update as `ended`. The `starts` and `ends` timestamp SHOULD be updated when the status changes to and from `live` 52 | 53 | The activity MUST be linked to using the [NIP-19](19.md) `naddr` code along with the `a` tag. 54 | 55 | ### Proof of Agreement to Participate 56 | 57 | Event owners can add proof as the 5th term in each `p` tag to clarify the participant's agreement in joining the event. The proof is a signed SHA256 of the complete `a` Tag of the event (`kind:pubkey:dTag`) by each `p`'s private key, encoded in hex. 58 | 59 | Clients MAY only display participants if the proof is available or MAY display participants as "invited" if the proof is not available. 60 | 61 | This feature is important to avoid malicious event owners adding large account holders to the event, without their knowledge, to lure their followers into the malicious owner's trap. 62 | 63 | ### Live Chat Message 64 | 65 | Event `kind:1311` is live chat's channel message. Clients MUST include the `a` tag of the activity with a `root` marker. Other Kind-1 tags such as `reply` and `mention` can also be used. 66 | 67 | ```json 68 | { 69 | "kind": 1311, 70 | "tags": [ 71 | ["a", "30311::", "", "root"], 72 | ], 73 | "content": "Zaps to live streams is beautiful.", 74 | ... 75 | } 76 | ``` 77 | 78 | ## Use Cases 79 | 80 | Common use cases include meeting rooms/workshops, watch-together activities, or event spaces, such as [zap.stream](https://zap.stream). 81 | 82 | ## Example 83 | 84 | ### Live Streaming 85 | 86 | ```json 87 | { 88 | "id": "57f28dbc264990e2c61e80a883862f7c114019804208b14da0bff81371e484d2", 89 | "pubkey": "1597246ac22f7d1375041054f2a4986bd971d8d196d7997e48973263ac9879ec", 90 | "created_at": 1687182672, 91 | "kind": 30311, 92 | "tags": [ 93 | ["d", "demo-cf-stream"], 94 | ["title", "Adult Swim Metalocalypse"], 95 | ["summary", "Live stream from IPTV-ORG collection"], 96 | ["streaming", "https://adultswim-vodlive.cdn.turner.com/live/metalocalypse/stream.m3u8"], 97 | ["starts", "1687182672"], 98 | ["status", "live"], 99 | ["t", "animation"], 100 | ["t", "iptv"], 101 | ["image", "https://i.imgur.com/CaKq6Mt.png"] 102 | ], 103 | "content": "", 104 | "sig": "5bc7a60f5688effa5287244a24768cbe0dcd854436090abc3bef172f7f5db1410af4277508dbafc4f70a754a891c90ce3b966a7bc47e7c1eb71ff57640f3d389" 105 | } 106 | ``` 107 | 108 | ### Live Streaming chat message 109 | 110 | ```json 111 | { 112 | "id": "97aa81798ee6c5637f7b21a411f89e10244e195aa91cb341bf49f718e36c8188", 113 | "pubkey": "3f770d65d3a764a9c5cb503ae123e62ec7598ad035d836e2a810f3877a745b24", 114 | "created_at": 1687286726, 115 | "kind": 1311, 116 | "tags": [ 117 | ["a", "30311:1597246ac22f7d1375041054f2a4986bd971d8d196d7997e48973263ac9879ec:demo-cf-stream", "", "root"] 118 | ], 119 | "content": "Zaps to live streams is beautiful.", 120 | "sig": "997f62ddfc0827c121043074d50cfce7a528e978c575722748629a4137c45b75bdbc84170bedc723ef0a5a4c3daebf1fef2e93f5e2ddb98e5d685d022c30b622" 121 | } 122 | ```` 123 | -------------------------------------------------------------------------------- /71.md: -------------------------------------------------------------------------------- 1 | NIP-71 2 | ====== 3 | 4 | Video Events 5 | --------------- 6 | 7 | `draft` `optional` 8 | 9 | This specification defines video events representing a dedicated post of externally hosted content. These video events are _parameterized replaceable_ and deletable per [NIP-09](09.md). 10 | 11 | Unlike a `kind 1` event with a video attached, Video Events are meant to contain all additional metadata concerning the subject media and to be surfaced in video-specific clients rather than general micro-blogging clients. The thought is for events of this kind to be referenced in a Netflix, YouTube, or TikTok like nostr client where the video itself is at the center of the experience. 12 | 13 | ## Video Events 14 | 15 | There are two types of video events represented by different kinds: horizontal and vertical video events. This is meant to allow clients to cater to each as the viewing experience for horizontal (landscape) videos is often different than that of vertical (portrait) videos (Stories, Reels, Shorts, etc). 16 | 17 | #### Format 18 | 19 | The format uses a parameterized replaceable event kind `34235` for horizontal videos and `34236` for vertical videos. 20 | 21 | The `.content` of these events is a summary or description on the video content. 22 | 23 | The list of tags are as follows: 24 | * `d` (required) universally unique identifier (UUID). Generated by the client creating the video event. 25 | * `url` (required) the url to the video file 26 | * `m` a string indicating the data type of the file. The [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) format must be used, and they should be lowercase. 27 | * `title` (required) title of the video 28 | * `"published_at"`, for the timestamp in unix seconds (stringified) of the first time the video was published 29 | * `x` containing the SHA-256 hexencoded string of the file. 30 | * `size` (optional) size of file in bytes 31 | * `dim` (optional) size of file in pixels in the form `x` 32 | * `duration` (optional) video duration in seconds 33 | * `magnet` (optional) URI to magnet file 34 | * `i` (optional) torrent infohash 35 | * `text-track` (optional, repeated) link to WebVTT file for video, type of supplementary information (captions/subtitles/chapters/metadata), optional language code 36 | * `thumb` (optional) url of thumbnail with same aspect ratio 37 | * `image` (optional) url of preview image with same dimensions 38 | * `content-warning` (optional) warning about content of NSFW video 39 | * `alt` (optional) description for accessibility 40 | * `segment` (optional, repeated) start timestamp in format `HH:MM:SS.sss`, end timestamp in format `HH:MM:SS.sss`, chapter/segment title, chapter thumbnail-url 41 | * `t` (optional, repeated) hashtag to categorize video 42 | * `p` (optional, repeated) 32-bytes hex pubkey of a participant in the video, optional recommended relay URL 43 | * `r` (optional, repeated) references / links to web pages 44 | 45 | ```json 46 | { 47 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 48 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 49 | "created_at": , 50 | "kind": 34235 | 34236, 51 | "content": "

", 52 | "tags": [ 53 | ["d", ""], 54 | 55 | ["title", ""], 56 | ["thumb", "<thumbnail image for video>"], 57 | ["published_at", "<unix timestamp>"], 58 | ["alt", <description>], 59 | 60 | // Video Data 61 | ["url",<string with URI of file>], 62 | ["m", <MIME type>], 63 | ["x",<Hash SHA-256>], 64 | ["size", <size of file in bytes>], 65 | ["duration", <duration of video in seconds>], 66 | ["dim", <size of file in pixels>], 67 | ["magnet",<magnet URI> ], 68 | ["i",<torrent infohash>], 69 | ["text-track", "<encoded `kind 6000` event>", "<recommended relay urls>"], 70 | ["content-warning", "<reason>"], 71 | ["segment", <start>, <end>, "<title>", "<thumbnail URL>"], 72 | 73 | // Participants 74 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"], 75 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>"], 76 | 77 | // Hashtags 78 | ["t", "<tag>"], 79 | ["t", "<tag>"], 80 | 81 | // Reference links 82 | ["r", "<url>"], 83 | ["r", "<url>"] 84 | ] 85 | } 86 | ``` 87 | 88 | ## Video View 89 | 90 | A video event view is a response to a video event to track a user's view or progress viewing the video. 91 | 92 | ### Format 93 | 94 | The format uses a parameterized replaceable event kind `34237`. 95 | 96 | The `.content` of these events is optional and could be a free-form note that acts like a bookmark for the user. 97 | 98 | The list of tags are as follows: 99 | * `a` (required) reference tag to kind `34235` or `34236` video event being viewed 100 | * `d` (required) same as `a` reference tag value 101 | * `viewed` (optional, repeated) timestamp of the user's start time in seconds, timestamp of the user's end time in seconds 102 | 103 | 104 | ```json 105 | { 106 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 107 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 108 | "created_at": <Unix timestamp in seconds>, 109 | "kind": 34237, 110 | "content": "<note>", 111 | "tags": [ 112 | ["a", "<34235 | 34236>:<video event author pubkey>:<d-identifier of video event>", "<optional relay url>"], 113 | ["e", "<event-id", "<relay-url>"] 114 | ["d", "<34235 | 34236>:<video event author pubkey>:<d-identifier of video event>"], 115 | ["viewed", <start>, <end>], 116 | ] 117 | } 118 | ``` 119 | -------------------------------------------------------------------------------- /05.md: -------------------------------------------------------------------------------- 1 | NIP-05 2 | ====== 3 | 4 | Mapping Nostr keys to DNS-based internet identifiers 5 | ---------------------------------------------------- 6 | 7 | `final` `optional` 8 | 9 | On events of kind `0` (`user metadata`) one can specify the key `"nip05"` with an [internet identifier](https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1) (an email-like address) as the value. Although there is a link to a very liberal "internet identifier" specification above, NIP-05 assumes the `<local-part>` part will be restricted to the characters `a-z0-9-_.`, case-insensitive. 10 | 11 | Upon seeing that, the client splits the identifier into `<local-part>` and `<domain>` and use these values to make a GET request to `https://<domain>/.well-known/nostr.json?name=<local-part>`. 12 | 13 | The result should be a JSON document object with a key `"names"` that should then be a mapping of names to hex formatted public keys. If the public key for the given `<name>` matches the `pubkey` from the `user's metadata` event, the client then concludes that the given pubkey can indeed be referenced by its identifier. 14 | 15 | ### Example 16 | 17 | If a client sees an event like this: 18 | 19 | ```json 20 | { 21 | "pubkey": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9", 22 | "kind": 0, 23 | "content": "{\"name\": \"bob\", \"nip05\": \"bob@example.com\"}" 24 | ... 25 | } 26 | ``` 27 | 28 | It will make a GET request to `https://example.com/.well-known/nostr.json?name=bob` and get back a response that will look like 29 | 30 | ```json 31 | { 32 | "names": { 33 | "bob": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9" 34 | } 35 | } 36 | ```` 37 | 38 | or with the **recommended** `"relays"` attribute: 39 | 40 | ```json 41 | { 42 | "names": { 43 | "bob": "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9" 44 | }, 45 | "relays": { 46 | "b0635d6a9851d3aed0cd6c495b282167acf761729078d975fc341b22650b07b9": [ "wss://relay.example.com", "wss://relay2.example.com" ] 47 | } 48 | } 49 | ```` 50 | 51 | If the pubkey matches the one given in `"names"` (as in the example above) that means the association is right and the `"nip05"` identifier is valid and can be displayed. 52 | 53 | The recommended `"relays"` attribute may contain an object with public keys as properties and arrays of relay URLs as values. When present, that can be used to help clients learn in which relays the specific user may be found. Web servers which serve `/.well-known/nostr.json` files dynamically based on the query string SHOULD also serve the relays data for any name they serve in the same reply when that is available. 54 | 55 | ## Finding users from their NIP-05 identifier 56 | 57 | A client may implement support for finding users' public keys from _internet identifiers_, the flow is the same as above, but reversed: first the client fetches the _well-known_ URL and from there it gets the public key of the user, then it tries to fetch the kind `0` event for that user and check if it has a matching `"nip05"`. 58 | 59 | ## Notes 60 | 61 | ### Clients must always follow public keys, not NIP-05 addresses 62 | 63 | For example, if after finding that `bob@bob.com` has the public key `abc...def`, the user clicks a button to follow that profile, the client must keep a primary reference to `abc...def`, not `bob@bob.com`. If, for any reason, the address `https://bob.com/.well-known/nostr.json?name=bob` starts returning the public key `1d2...e3f` at any time in the future, the client must not replace `abc...def` in his list of followed profiles for the user (but it should stop displaying "bob@bob.com" for that user, as that will have become an invalid `"nip05"` property). 64 | 65 | ### Public keys must be in hex format 66 | 67 | Keys must be returned in hex format. Keys in NIP-19 `npub` format are only meant to be used for display in client UIs, not in this NIP. 68 | 69 | ### User Discovery implementation suggestion 70 | 71 | A client can also use this to allow users to search other profiles. If a client has a search box or something like that, a user may be able to type "bob@example.com" there and the client would recognize that and do the proper queries to obtain a pubkey and suggest that to the user. 72 | 73 | ### Showing just the domain as an identifier 74 | 75 | Clients may treat the identifier `_@domain` as the "root" identifier, and choose to display it as just the `<domain>`. For example, if Bob owns `bob.com`, he may not want an identifier like `bob@bob.com` as that is redundant. Instead, Bob can use the identifier `_@bob.com` and expect Nostr clients to show and treat that as just `bob.com` for all purposes. 76 | 77 | ### Reasoning for the `/.well-known/nostr.json?name=<local-part>` format 78 | 79 | By adding the `<local-part>` as a query string instead of as part of the path, the protocol can support both dynamic servers that can generate JSON on-demand and static servers with a JSON file in it that may contain multiple names. 80 | 81 | ### Allowing access from JavaScript apps 82 | 83 | JavaScript Nostr apps may be restricted by browser [CORS][] policies that prevent them from accessing `/.well-known/nostr.json` on the user's domain. When CORS prevents JS from loading a resource, the JS program sees it as a network failure identical to the resource not existing, so it is not possible for a pure-JS app to tell the user for certain that the failure was caused by a CORS issue. JS Nostr apps that see network failures requesting `/.well-known/nostr.json` files may want to recommend to users that they check the CORS policy of their servers, e.g.: 84 | 85 | ```bash 86 | $ curl -sI https://example.com/.well-known/nostr.json?name=bob | grep -i ^Access-Control 87 | Access-Control-Allow-Origin: * 88 | ``` 89 | 90 | Users should ensure that their `/.well-known/nostr.json` is served with the HTTP header `Access-Control-Allow-Origin: *` to ensure it can be validated by pure JS apps running in modern browsers. 91 | 92 | [CORS]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS 93 | 94 | ### Security Constraints 95 | 96 | The `/.well-known/nostr.json` endpoint MUST NOT return any HTTP redirects. 97 | 98 | Fetchers MUST ignore any HTTP redirects given by the `/.well-known/nostr.json` endpoint. 99 | -------------------------------------------------------------------------------- /BREAKING.md: -------------------------------------------------------------------------------- 1 | # Breaking Changes 2 | 3 | This is a history of NIP changes that potentially break pre-existing implementations, in 4 | reverse chronological order. 5 | 6 | | Date | Commit | NIP | Change | 7 | | ----------- | --------- | -------- | ------ | 8 | | 2024-06-06 | [58e94b20](https://github.com/nostr-protocol/nips/commit/58e94b20) | [NIP-25](25.md) | [8073c848](https://github.com/nostr-protocol/nips/commit/8073c848) was reverted | 9 | | 2024-06-06 | [a6dfc7b5](https://github.com/nostr-protocol/nips/commit/a6dfc7b5) | [NIP-55](55.md) | NIP number was changed | 10 | | 2024-05-25 | [5d1d1c17](https://github.com/nostr-protocol/nips/commit/5d1d1c17) | [NIP-71](71.md) | 'aes-256-gcm' tag was removed | 11 | | 2024-05-07 | [8073c848](https://github.com/nostr-protocol/nips/commit/8073c848) | [NIP-25](25.md) | e-tags were changed to not include entire thread | 12 | | 2024-04-30 | [bad88262](https://github.com/nostr-protocol/nips/commit/bad88262) | [NIP-34](34.md) | 'earliest-unique-commit' tag was removed (use 'r' tag instead) | 13 | | 2024-02-25 | [4a171cb0](https://github.com/nostr-protocol/nips/commit/4a171cb0) | [NIP-18](18.md) | quote repost should use `q` tag | 14 | | 2024-02-21 | [c6cd655c](https://github.com/nostr-protocol/nips/commit/c6cd655c) | [NIP-46](46.md) | Params were stringified | 15 | | 2024-02-16 | [cbec02ab](https://github.com/nostr-protocol/nips/commit/cbec02ab) | [NIP-49](49.md) | Password first normalized to NFKC | 16 | | 2024-02-15 | [afbb8dd0](https://github.com/nostr-protocol/nips/commit/afbb8dd0) | [NIP-39](39.md) | PGP identity was removed | 17 | | 2024-02-07 | [d3dad114](https://github.com/nostr-protocol/nips/commit/d3dad114) | [NIP-46](46.md) | Connection token format was changed | 18 | | 2024-01-30 | [1a2b21b6](https://github.com/nostr-protocol/nips/commit/1a2b21b6) | [NIP-59](59.md) | 'p' tag became optional | 19 | | 2023-01-27 | [c2f34817](https://github.com/nostr-protocol/nips/commit/c2f34817) | [NIP-47](47.md) | optional expiration tag should be honored | 20 | | 2024-01-10 | [3d8652ea](https://github.com/nostr-protocol/nips/commit/3d8652ea) | [NIP-02](02.md) | list entries should be chronological | 21 | | 2024-01-10 | [3d8652ea](https://github.com/nostr-protocol/nips/commit/3d8652ea) | [NIP-51](51.md) | list entries should be chronological | 22 | | 2023-12-30 | [29869821](https://github.com/nostr-protocol/nips/commit/29869821) | [NIP-52](52.md) | 'name' tag was removed (use 'title' tag instead) | 23 | | 2023-12-27 | [17c67ef5](https://github.com/nostr-protocol/nips/commit/17c67ef5) | [NIP-94](94.md) | 'aes-256-gcm' tag was removed | 24 | | 2023-12-03 | [0ba45895](https://github.com/nostr-protocol/nips/commit/0ba45895) | [NIP-01](01.md) | WebSocket status code `4000` was replaced by 'CLOSED' message | 25 | | 2023-11-28 | [6de35f9e](https://github.com/nostr-protocol/nips/commit/6de35f9e) | [NIP-89](89.md) | 'client' tag value was changed | 26 | | 2023-11-20 | [7822a8b1](https://github.com/nostr-protocol/nips/commit/7822a8b1) | [NIP-51](51.md) | `kind: 30000` and `kind: 30001` were deprecated | 27 | | 2023-11-11 | [cbdca1e9](https://github.com/nostr-protocol/nips/commit/cbdca1e9) | [NIP-84](84.md) | 'range' tag was removed | 28 | | 2023-11-10 | [c945d8bd](https://github.com/nostr-protocol/nips/commit/c945d8bd) | [NIP-32](32.md) | 'l' tag annotations was removed | 29 | | 2023-11-07 | [108b7f16](https://github.com/nostr-protocol/nips/commit/108b7f16) | [NIP-01](01.md) | 'OK' message must have 4 items | 30 | | 2023-10-17 | [cf672b76](https://github.com/nostr-protocol/nips/commit/cf672b76) | [NIP-03](03.md) | 'block' tag was removed | 31 | | 2023-09-29 | [7dc6385f](https://github.com/nostr-protocol/nips/commit/7dc6385f) | [NIP-57](57.md) | optional 'a' tag was included in `zap receipt` | 32 | | 2023-08-21 | [89915e02](https://github.com/nostr-protocol/nips/commit/89915e02) | [NIP-11](11.md) | 'min_prefix' was removed | 33 | | 2023-08-20 | [37c4375e](https://github.com/nostr-protocol/nips/commit/37c4375e) | [NIP-01](01.md) | replaceable events with same timestamp should be retained event with lowest id | 34 | | 2023-08-15 | [88ee873c](https://github.com/nostr-protocol/nips/commit/88ee873c) | [NIP-15](15.md) | 'countries' tag was renamed to 'regions' | 35 | | 2023-08-14 | [72bb8a12](https://github.com/nostr-protocol/nips/commit/72bb8a12) | [NIP-12](12.md) | NIP-12, 16, 20 and 33 were merged into NIP-01 | 36 | | 2023-08-14 | [72bb8a12](https://github.com/nostr-protocol/nips/commit/72bb8a12) | [NIP-16](16.md) | NIP-12, 16, 20 and 33 were merged into NIP-01 | 37 | | 2023-08-14 | [72bb8a12](https://github.com/nostr-protocol/nips/commit/72bb8a12) | [NIP-20](20.md) | NIP-12, 16, 20 and 33 were merged into NIP-01 | 38 | | 2023-08-14 | [72bb8a12](https://github.com/nostr-protocol/nips/commit/72bb8a12) | [NIP-33](33.md) | NIP-12, 16, 20 and 33 were merged into NIP-01 | 39 | | 2023-08-11 | [d87f8617](https://github.com/nostr-protocol/nips/commit/d87f8617) | [NIP-25](25.md) | empty `content` should be considered as "+" | 40 | | 2023-08-01 | [5d63b157](https://github.com/nostr-protocol/nips/commit/5d63b157) | [NIP-57](57.md) | 'zap' tag was changed | 41 | | 2023-07-15 | [d1814405](https://github.com/nostr-protocol/nips/commit/d1814405) | [NIP-01](01.md) | `since` and `until` filters should be `since <= created_at <= until` | 42 | | 2023-07-12 | [a1cd2bd8](https://github.com/nostr-protocol/nips/commit/a1cd2bd8) | [NIP-25](25.md) | custom emoji was supported | 43 | | 2023-06-18 | [83cbd3e1](https://github.com/nostr-protocol/nips/commit/83cbd3e1) | [NIP-11](11.md) | 'image' was renamed to 'icon' | 44 | | 2023-04-13 | [bf0a0da6](https://github.com/nostr-protocol/nips/commit/bf0a0da6) | [NIP-15](15.md) | different NIP was re-added as NIP-15 | 45 | | 2023-04-09 | [fb5b7c73](https://github.com/nostr-protocol/nips/commit/fb5b7c73) | [NIP-15](15.md) | NIP-15 was merged into NIP-01 | 46 | | 2023-03-15 | [e1004d3d](https://github.com/nostr-protocol/nips/commit/e1004d3d) | [NIP-19](19.md) | `1: relay` was changed to optionally | 47 | 48 | Breaking changes prior to 2023-03-01 are not yet documented. 49 | 50 | ## NOTES 51 | 52 | - If it isn't clear that a change is breaking or not, we list it. 53 | - The date is the date it was merged, not necessarily the date of the commit. 54 | 55 | -------------------------------------------------------------------------------- /89.md: -------------------------------------------------------------------------------- 1 | NIP-89 2 | ====== 3 | 4 | Recommended Application Handlers 5 | -------------------------------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP describes `kind:31989` and `kind:31990`: a way to discover applications that can handle unknown event-kinds. 10 | 11 | ## Rationale 12 | 13 | Nostr's discoverability and transparent event interaction is one of its most interesting/novel mechanics. 14 | This NIP provides a simple way for clients to discover applications that handle events of a specific kind to ensure smooth cross-client and cross-kind interactions. 15 | 16 | ### Parties involved 17 | 18 | There are three actors to this workflow: 19 | 20 | * application that handles a specific event kind (note that an application doesn't necessarily need to be a distinct entity and it could just be the same pubkey as user A) 21 | * Publishes `kind:31990`, detailing how apps should redirect to it 22 | * user A, who recommends an app that handles a specific event kind 23 | * Publishes `kind:31989` 24 | * user B, who seeks a recommendation for an app that handles a specific event kind 25 | * Queries for `kind:31989` and, based on results, queries for `kind:31990` 26 | 27 | ## Events 28 | 29 | ### Recommendation event 30 | ```json 31 | { 32 | "kind": 31989, 33 | "pubkey": <recommender-user-pubkey>, 34 | "tags": [ 35 | ["d", <supported-event-kind>], 36 | ["a", "31990:app1-pubkey:<d-identifier>", "wss://relay1", "ios"], 37 | ["a", "31990:app2-pubkey:<d-identifier>", "wss://relay2", "web"] 38 | ] 39 | } 40 | ``` 41 | 42 | The `d` tag in `kind:31989` is the supported event kind this event is recommending. 43 | 44 | Multiple `a` tags can appear on the same `kind:31989`. 45 | 46 | The second value of the tag SHOULD be a relay hint. 47 | The third value of the tag SHOULD be the platform where this recommendation might apply. 48 | 49 | ## Handler information 50 | ```json 51 | { 52 | "kind": 31990, 53 | "pubkey": "<application-pubkey>", 54 | "content": "<optional-kind:0-style-metadata>", 55 | "tags": [ 56 | ["d", <random-id>], 57 | ["k", <supported-event-kind>], 58 | ["web", "https://..../a/<bech32>", "nevent"], 59 | ["web", "https://..../p/<bech32>", "nprofile"], 60 | ["web", "https://..../e/<bech32>"], 61 | ["ios", ".../<bech32>"] 62 | ] 63 | } 64 | ``` 65 | 66 | * `content` is an optional `metadata`-like stringified JSON object, as described in NIP-01. This content is useful when the pubkey creating the `kind:31990` is not an application. If `content` is empty, the `kind:0` of the pubkey should be used to display application information (e.g. name, picture, web, LUD16, etc.) 67 | * `k` tags' value is the event kind that is supported by this `kind:31990`. 68 | Using a `k` tag(s) (instead of having the kind of the `d` tag) provides: 69 | * Multiple `k` tags can exist in the same event if the application supports more than one event kind and their handler URLs are the same. 70 | * The same pubkey can have multiple events with different apps that handle the same event kind. 71 | * `bech32` in a URL MUST be replaced by clients with the NIP-19-encoded entity that should be loaded by the application. 72 | 73 | Multiple tags might be registered by the app, following NIP-19 nomenclature as the second value of the array. 74 | 75 | A tag without a second value in the array SHOULD be considered a generic handler for any NIP-19 entity that is not handled by a different tag. 76 | 77 | # Client tag 78 | When publishing events, clients MAY include a `client` tag. Identifying the client that published the note. This tag is a tuple of `name`, `address` identifying a handler event and, a relay `hint` for finding the handler event. This has privacy implications for users, so clients SHOULD allow users to opt-out of using this tag. 79 | 80 | ```json 81 | { 82 | "kind": 1, 83 | "tags": [ 84 | ["client", "My Client", "31990:app1-pubkey:<d-identifier>", "wss://relay1"] 85 | ] 86 | ... 87 | } 88 | ``` 89 | 90 | ## User flow 91 | A user A who uses a non-`kind:1`-centric nostr app could choose to announce/recommend a certain kind-handler application. 92 | 93 | When user B sees an unknown event kind, e.g. in a social-media centric nostr client, the client would allow user B to interact with the unknown-kind event (e.g. tapping on it). 94 | 95 | The client MIGHT query for the user's and the user's follows handler. 96 | 97 | ## Example 98 | 99 | ### User A recommends a `kind:31337`-handler 100 | User A might be a user of Zapstr, a `kind:31337`-centric client (tracks). Using Zapstr, user A publishes an event recommending Zapstr as a `kind:31337`-handler. 101 | 102 | ```json 103 | { 104 | "kind": 31989, 105 | "tags": [ 106 | ["d", "31337"], 107 | ["a", "31990:1743058db7078661b94aaf4286429d97ee5257d14a86d6bfa54cb0482b876fb0:abcd", <relay-url>, "web"] 108 | ], 109 | ... 110 | } 111 | ``` 112 | 113 | ### User B interacts with a `kind:31337`-handler 114 | User B might see in their timeline an event referring to a `kind:31337` event (e.g. a `kind:1` tagging a `kind:31337`). 115 | 116 | User B's client, not knowing how to handle a `kind:31337` might display the event using its `alt` tag (as described in NIP-31). When the user clicks on the event, the application queries for a handler for this `kind`: 117 | 118 | ```json 119 | ["REQ", <id>, { "kinds": [31989], "#d": ["31337"], "authors": [<user>, <users-contact-list>] }] 120 | ``` 121 | 122 | User B, who follows User A, sees that `kind:31989` event and fetches the `a`-tagged event for the app and handler information. 123 | 124 | User B's client sees the application's `kind:31990` which includes the information to redirect the user to the relevant URL with the desired entity replaced in the URL. 125 | 126 | ### Alternative query bypassing `kind:31989` 127 | Alternatively, users might choose to query directly for `kind:31990` for an event kind. Clients SHOULD be careful doing this and use spam-prevention mechanisms or querying high-quality restricted relays to avoid directing users to malicious handlers. 128 | 129 | ```json 130 | ["REQ", <id>, { "kinds": [31990], "#k": [<desired-event-kind>], "authors": [...] }] 131 | ``` 132 | -------------------------------------------------------------------------------- /34.md: -------------------------------------------------------------------------------- 1 | NIP-34 2 | ====== 3 | 4 | `git` stuff 5 | ----------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines all the ways code collaboration using and adjacent to [`git`](https://git-scm.com/) can be done using Nostr. 10 | 11 | ## Repository announcements 12 | 13 | Git repositories are hosted in Git-enabled servers, but their existence can be announced using Nostr events, as well as their willingness to receive patches, bug reports and comments in general. 14 | 15 | ```jsonc 16 | { 17 | "kind": 30617, 18 | "content": "", 19 | "tags": [ 20 | ["d", "<repo-id>"], // usually kebab-case short name 21 | ["name", "<human-readable project name>"], 22 | ["description", "brief human-readable project description>"], 23 | ["web", "<url for browsing>", ...], // a webpage url, if the git server being used provides such a thing 24 | ["clone", "<url for git-cloning>", ...], // a url to be given to `git clone` so anyone can clone it 25 | ["relays", "<relay-url>", ...] // relays that this repository will monitor for patches and issues 26 | ["r", "<earliest-unique-commit-id>", "euc"] 27 | ["maintainers", "<other-recognized-maintainer>", ...] 28 | ] 29 | } 30 | ``` 31 | 32 | The tags `web`, `clone`, `relays`, `maintainers` can have multiple values. 33 | 34 | The `r` tag annotated with the `"euc"` marker should be the commit ID of the earliest unique commit of this repo, made to identify it among forks and group it with other repositories hosted elsewhere that may represent essentially the same project. In most cases it will be the root commit of a repository. In case of a permanent fork between two projects, then the first commit after the fork should be used. 35 | 36 | Except `d`, all tags are optional. 37 | 38 | ## Patches 39 | 40 | Patches can be sent by anyone to any repository. Patches to a specific repository SHOULD be sent to the relays specified in that repository's announcement event's `"relays"` tag. Patch events SHOULD include an `a` tag pointing to that repository's announcement address. 41 | 42 | Patches in a patch set SHOULD include a NIP-10 `e` `reply` tag pointing to the previous patch. 43 | 44 | The first patch revision in a patch revision SHOULD include a NIP-10 `e` `reply` to the original root patch. 45 | 46 | ```jsonc 47 | { 48 | "kind": 1617, 49 | "content": "<patch>", // contents of <git format-patch> 50 | "tags": [ 51 | ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"], 52 | ["r", "<earliest-unique-commit-id-of-repo>"] // so clients can subscribe to all patches sent to a local git repo 53 | ["p", "<repository-owner>"], 54 | ["p", "<other-user>"], // optionally send the patch to another user to bring it to their attention 55 | 56 | ["t", "root"], // ommited for additional patches in a series 57 | // for the first patch in a revision 58 | ["t", "root-revision"], 59 | 60 | // optional tags for when it is desirable that the merged patch has a stable commit id 61 | // these fields are necessary for ensuring that the commit resulting from applying a patch 62 | // has the same id as it had in the proposer's machine -- all these tags can be omitted 63 | // if the maintainer doesn't care about these things 64 | ["commit", "<current-commit-id>"], 65 | ["r", "<current-commit-id>"] // so clients can find existing patches for a specific commit 66 | ["parent-commit", "<parent-commit-id>"], 67 | ["commit-pgp-sig", "-----BEGIN PGP SIGNATURE-----..."], // empty string for unsigned commit 68 | ["committer", "<name>", "<email>", "<timestamp>", "<timezone offset in minutes>"], 69 | ] 70 | } 71 | ``` 72 | 73 | The first patch in a series MAY be a cover letter in the format produced by `git format-patch`. 74 | 75 | ## Issues 76 | 77 | Issues are Markdown text that is just human-readable conversational threads related to the repository: bug reports, feature requests, questions or comments of any kind. Like patches, these SHOULD be sent to the relays specified in that repository's announcement event's `"relays"` tag. 78 | 79 | ```jsonc 80 | { 81 | "kind": 1621, 82 | "content": "<markdown text>", 83 | "tags": [ 84 | ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"], 85 | ["p", "<repository-owner>"] 86 | ] 87 | } 88 | ``` 89 | 90 | ## Replies 91 | 92 | Replies are also Markdown text. The difference is that they MUST be issued as replies to either a `kind:1621` _issue_ or a `kind:1617` _patch_ event. The threading of replies and patches should follow NIP-10 rules. 93 | 94 | ```jsonc 95 | { 96 | "kind": 1622, 97 | "content": "<markdown text>", 98 | "tags": [ 99 | ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"], 100 | ["e", "<issue-or-patch-id-hex>", "", "root"], 101 | 102 | // other "e" and "p" tags should be applied here when necessary, following the threading rules of NIP-10 103 | ["p", "<patch-author-pubkey-hex>", "", "mention"], 104 | ["e", "<previous-reply-id-hex>", "", "reply"], 105 | // ... 106 | ] 107 | } 108 | ``` 109 | 110 | ## Status 111 | 112 | Root Patches and Issues have a Status that defaults to 'Open' and can be set by issuing Status events. 113 | 114 | ```jsonc 115 | { 116 | "kind": 1630, // Open 117 | "kind": 1631, // Applied / Merged for Patches; Resolved for Issues 118 | "kind": 1632, // Closed 119 | "kind": 1633, // Draft 120 | "content": "<markdown text>", 121 | "tags": [ 122 | ["e", "<issue-or-original-root-patch-id-hex>", "", "root"], 123 | ["e", "<accepted-revision-root-id-hex>", "", "reply"], // for when revisions applied 124 | ["p", "<repository-owner>"], 125 | ["p", "<root-event-author>"], 126 | ["p", "<revision-author>"], 127 | 128 | // optional for improved subscription filter efficiency 129 | ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>", "<relay-url>"], 130 | ["r", "<earliest-unique-commit-id-of-repo>"] 131 | 132 | // optional for `1631` status 133 | ["e", "<applied-or-merged-patch-event-id>", "", "mention"], // for each 134 | // when merged 135 | ["merge-commit", "<merge-commit-id>"] 136 | ["r", "<merge-commit-id>"] 137 | // when applied 138 | ["applied-as-commits", "<commit-id-in-master-branch>", ...] 139 | ["r", "<applied-commit-id>"] // for each 140 | ] 141 | } 142 | ``` 143 | 144 | The Status event with the largest created_at date is valid. 145 | 146 | The Status of a patch-revision defaults to either that of the root-patch, or `1632` (Closed) if the root-patch's Status is `1631` and the patch-revision isn't tagged in the `1631` event. 147 | 148 | 149 | ## Possible things to be added later 150 | 151 | - "branch merge" kind (specifying a URL from where to fetch the branch to be merged) 152 | - inline file comments kind (we probably need one for patches and a different one for merged files) 153 | -------------------------------------------------------------------------------- /54.md: -------------------------------------------------------------------------------- 1 | NIP-54 2 | ====== 3 | 4 | Wiki 5 | ---- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines `kind:30818` (a _parameterized replaceable event_) for long-form text content similar to [NIP-23](23.md), but with one important difference: articles are meant to be descriptions, or encyclopedia entries, of particular subjects, and it's expected that multiple people will write articles about the exact same subjects, with either small variations or completely independent content. 10 | 11 | Articles are identified by lowercase, normalized ascii `d` tags. 12 | 13 | ### Articles 14 | ```jsonc 15 | { 16 | "content": "A wiki is a hypertext publication collaboratively edited and managed by its own audience.", 17 | "tags": [ 18 | ["d", "wiki"], 19 | ["title", "Wiki"], 20 | ] 21 | } 22 | ``` 23 | 24 | ### `d` tag normalization rules 25 | 26 | - Any non-letter character MUST be converted to a `-`. 27 | - All letters MUST be converted to lowercase. 28 | 29 | ### Content rules 30 | 31 | The content should be Markdown, following the same rules as of [NIP-23](23.md), although it takes some extra (optional) metadata tags: 32 | 33 | - `title`: for when the display title should be different from the `d` tag. 34 | - `summary`: for display in lists. 35 | - `a` and `e`: for referencing the original event a wiki article was forked from. 36 | 37 | One extra functionality is added: **wikilinks**. Unlike normal Markdown links `[]()` that link to webpages, wikilinks `[[]]` link to other articles in the wiki. In this case, the wiki is the entirety of Nostr. Clicking on a wikilink should cause the client to ask relays for events with `d` tags equal to the target of that wikilink. 38 | 39 | Wikilinks can take these two forms: 40 | 41 | 1. `[[Target Page]]` -- in this case it will link to the page `target-page` (according to `d` tag normalization rules above) and be displayed as `Target Page`; 42 | 2. `[[target page|see this]]` -- in this case it will link to the page `target-page`, but will be displayed as `see this`. 43 | 44 | ### Merge Requests 45 | 46 | Event `kind:818` represents a request to merge from a forked article into the source. It is directed to a pubkey and references the original article and the modified event. 47 | 48 | [INSERT EVENT EXAMPLE] 49 | 50 | ### Redirects 51 | 52 | Event `kind:30819` is also defined to stand for "wiki redirects", i.e. if one thinks `Shell structure` should redirect to `Thin-shell structure` they can issue one of these events instead of replicating the content. These events can be used for automatically redirecting between articles on a client, but also for generating crowdsourced "disambiguation" pages ([common in Wikipedia](https://en.wikipedia.org/wiki/Help:Disambiguation)). 53 | 54 | [INSERT EVENT EXAMPLE] 55 | 56 | How to decide what article to display 57 | ------------------------------------- 58 | 59 | As there could be many articles for each given name, some kind of prioritization must be done by clients. Criteria for this should vary between users and clients, but some means that can be used are described below: 60 | 61 | ### Reactions 62 | 63 | [NIP-25](25.md) reactions are very simple and can be used to create a simple web-of-trust between wiki article writers and their content. While just counting a raw number of "likes" is unproductive, reacting to any wiki article event with a `+` can be interpreted as a recommendation for that article specifically and a partial recommendation of the author of that article. When 2 or 3-level deep recommendations are followed, suddenly a big part of all the articles may have some form of tagging. 64 | 65 | ### Relays 66 | 67 | [NIP-51](51.md) lists of relays can be created with the kind 10102 and then used by wiki clients in order to determine where to query articles first and to rank these differently in relation to other events fetched from other relays. 68 | 69 | ### Contact lists 70 | 71 | [NIP-02](02.md) contact lists can form the basis of a recommendation system that is then expanded with relay lists and reaction lists through nested queries. These lists form a good starting point only because they are so widespread. 72 | 73 | ### Wiki-related contact lists 74 | 75 | [NIP-51](51.md) lists can also be used to create a list of users that are trusted only in the context of wiki authorship or wiki curationship. 76 | 77 | Forks 78 | --------- 79 | Wiki-events can tag other wiki-events with a `fork` marker to specify that this event came from a different version. Both `a` and `e` tags SHOULD be used and have the `fork` marker applied, to identify the exact version it was forked from. 80 | 81 | Deference 82 | --------- 83 | Wiki-events can tag other wiki-events with a `defer` marker to indicate that it considers someone else's entry as a "better" version of itself. If using a `defer` marker both `a` and `e` tags SHOULD be used. 84 | 85 | This is a stronger signal of trust than a `+` reaction. 86 | 87 | This marker is useful when a user edits someone else's entry; if the original author includes the editor's changes and the editor doesn't want to keep/maintain an independent version, the `link` tag could effectively be a considered a "deletion" of the editor's version and putting that pubkey's WoT weight behind the original author's version. 88 | 89 | Why Markdown? 90 | ------------- 91 | 92 | If the idea is to make a wiki then the most obvious text format to use is probably the mediawiki/wikitext format used by Wikipedia since it's widely deployed in all mediawiki installations and used for decades with great success. However, it turns out that format is very bloated and convoluted, has way too many features and probably because of that it doesn't have many alternative implementations out there, and the ones that exist are not complete and don't look very trustworthy. Also it is very much a centralized format that can probably be changed at the whims of the Wikipedia owners. 93 | 94 | On the other hand, Markdown has proven to work well for small scale wikis and one of the biggest wikis in the planet (which is not very often thought of as a wiki), [StackOverflow](https://stackoverflow.com) and its child sites, and also one of the biggest "personal wiki" software, [Obsidian](https://obsidian.md/). Markdown can probably deliver 95% of the functionality of wikitext. When augmented with tables, diagram generators and MathJax (which are common extensions that exist in the wild and can be included in this NIP) that rate probably goes to 99%, and its simplicity is a huge benefit that can't be overlooked. Wikitext format can also be transpíled into Markdown using Pandoc. Given all that, I think it's a reasonable suspicion that mediawiki is not inherently better than Markdown, the success of Wikipedia probably cannot be predicated on the syntax language choice. 95 | 96 | # Appendix 1: Merge requests 97 | Users can request other users to get their entries merged into someone else's entry by creating a `kind:818` event. 98 | 99 | ```jsonc 100 | { 101 | "content": "I added information about how to make hot ice-creams", 102 | "kind": 818, 103 | "tags": [ 104 | [ "a", "30818:<destination-pubkey>:hot-ice-creams", "<relay-url>" ], 105 | [ "e", "<version-against-which-the-modification-was-made>", "<relay-url>' ], 106 | [ "p", "<destination-pubkey>" ], 107 | [ "e", "<version-to-be-merged>", "<relay-url>", "source" ] 108 | ] 109 | } 110 | ``` 111 | 112 | `.content`: an optional explanation detailing why this merge is being requested. 113 | `a` tag: tag of the article which should be modified (i.e. the target of this merge request). 114 | `e` tag: optional version of the article in which this modifications is based 115 | `e` tag with `source` marker: the ID of the event that should be merged. This event id MUST be of a `kind:30818` as defined in this NIP. 116 | 117 | The destination-pubkey (the pubkey being requested to merge something into their article can create [[NIP-25]] reactions that tag the `kind:818` event with `+` or `-` 118 | -------------------------------------------------------------------------------- /29.md: -------------------------------------------------------------------------------- 1 | NIP-29 2 | ====== 3 | 4 | Relay-based Groups 5 | ------------------ 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines a standard for groups that are only writable by a closed set of users. They can be public for reading by external users or not. 10 | 11 | Groups are identified by a random string of any length that serves as an _id_. 12 | 13 | There is no way to create a group, what happens is just that relays (most likely when asked by users) will create rules around some specific ids so these ids can serve as an actual group, henceforth messages sent to that group will be subject to these rules. 14 | 15 | Normally a group will originally belong to one specific relay, but the community may choose to move the group to other relays or even fork the group so it exists in different forms -- still using the same _id_ -- across different relays. 16 | 17 | ## Relay-generated events 18 | 19 | Relays are supposed to generate the events that describe group metadata and group admins. These are parameterized replaceable events signed by the relay keypair directly, with the group _id_ as the `d` tag. 20 | 21 | ## Group identifier 22 | 23 | A group may be identified by a string in the format `<host>'<group-id>`. For example, a group with _id_ `abcdef` hosted at the relay `wss://groups.nostr.com` would be identified by the string `groups.nostr.com'abcdef`. 24 | 25 | ## The `h` tag 26 | 27 | Events sent by users to groups (chat messages, text notes, moderation events etc) must have an `h` tag with the value set to the group _id_. 28 | 29 | ## Timeline references 30 | 31 | In order to not be used out of context, events sent to these groups may contain references to previous events seen from the same relay in the `previous` tag. The choice of which previous events to pick belongs to the clients. The references are to be made using the first 8 characters (4 bytes) of any event in the last 50 events seen by the user in the relay, excluding events by themselves. There can be any number of references (including zero), but it's recommended that clients include at least 3 and that relays enforce this. 32 | 33 | This is a hack to prevent messages from being broadcasted to external relays that have forks of one group out of context. Relays are expected to reject any events that contain timeline references to events not found in their own database. Clients should also check these to keep relays honest about them. 34 | 35 | ## Late publication 36 | 37 | Relays should prevent late publication (messages published now with a timestamp from days or even hours ago) unless they are open to receive a group forked or moved from another relay. 38 | 39 | ## Event definitions 40 | 41 | - *text root note* (`kind:11`) 42 | 43 | This is the basic unit of a "microblog" root text note sent to a group. 44 | 45 | ```js 46 | "kind": 11, 47 | "content": "hello my friends lovers of pizza", 48 | "tags": [ 49 | ["h", "<group-id>"], 50 | ["previous", "<event-id-first-chars>", "<event-id-first-chars>", ...] 51 | ] 52 | ... 53 | ``` 54 | 55 | - *threaded text reply* (`kind:12`) 56 | 57 | This is the basic unit of a "microblog" reply note sent to a group. It's the same as `kind:11`, except for the fact that it must be used whenever it's in reply to some other note (either in reply to a `kind:11` or a `kind:12`). `kind:12` events SHOULD use NIP-10 markers, leaving an empty relay url: 58 | 59 | * `["e", "<kind-11-root-id>", "", "root"]` 60 | * `["e", "<kind-12-event-id>", "", "reply"]` 61 | 62 | - *chat message* (`kind:9`) 63 | 64 | This is the basic unit of a _chat message_ sent to a group. 65 | 66 | ```js 67 | "kind": 9, 68 | "content": "hello my friends lovers of pizza", 69 | "tags": [ 70 | ["h", "<group-id>"], 71 | ["previous", "<event-id-first-chars>", "<event-id-first-chars>", ...] 72 | ] 73 | ... 74 | ``` 75 | 76 | - *chat message threaded reply* (`kind:10`) 77 | 78 | Similar to `kind:12`, this is the basic unit of a chat message sent to a group. This is intended for in-chat threads that may be hidden by default. Not all in-chat replies MUST use `kind:10`, only when the intention is to create a hidden thread that isn't part of the normal flow of the chat (although clients are free to display those by default too). 79 | 80 | `kind:10` SHOULD use NIP-10 markers, just like `kind:12`. 81 | 82 | - *join request* (`kind:9021`) 83 | 84 | Any user can send one of these events to the relay in order to be automatically or manually added to the group. If the group is `open` the relay will automatically issue a `kind:9000` in response adding this user. Otherwise group admins may choose to query for these requests and act upon them. 85 | 86 | ```js 87 | { 88 | "kind": 9021, 89 | "content": "optional reason", 90 | "tags": [ 91 | ["h", "<group-id>"] 92 | ] 93 | } 94 | ``` 95 | 96 | - *moderation events* (`kinds:9000-9020`) (optional) 97 | 98 | Clients can send these events to a relay in order to accomplish a moderation action. Relays must check if the pubkey sending the event is capable of performing the given action. The relay may discard the event after taking action or keep it as a moderation log. 99 | 100 | ```js 101 | { 102 | "kind": 90xx, 103 | "content": "optional reason", 104 | "tags": [ 105 | ["h", "<group-id>"], 106 | ["previous", ...] 107 | ] 108 | } 109 | ``` 110 | 111 | Each moderation action uses a different kind and requires different arguments, which are given as tags. These are defined in the following table: 112 | 113 | | kind | name | tags | 114 | | --- | --- | --- | 115 | | 9000 | `add-user` | `p` (pubkey hex) | 116 | | 9001 | `remove-user` | `p` (pubkey hex) | 117 | | 9002 | `edit-metadata` | `name`, `about`, `picture` (string) | 118 | | 9003 | `add-permission` | `p` (pubkey), `permission` (name) | 119 | | 9004 | `remove-permission` | `p` (pubkey), `permission` (name) | 120 | | 9005 | `delete-event` | `e` (id hex) | 121 | | 9006 | `edit-group-status` | `public` or `private`, `open` or `closed` | 122 | | 9007 | `create-group` | | 123 | 124 | - *group metadata* (`kind:39000`) (optional) 125 | 126 | This event defines the metadata for the group -- basically how clients should display it. It must be generated and signed by the relay in which is found. Relays shouldn't accept these events if they're signed by anyone else. 127 | 128 | If the group is forked and hosted in multiple relays, there will be multiple versions of this event in each different relay and so on. 129 | 130 | ```js 131 | { 132 | "kind": 39000, 133 | "content": "", 134 | "tags": [ 135 | ["d", "<group-id>"], 136 | ["name", "Pizza Lovers"], 137 | ["picture", "https://pizza.com/pizza.png"], 138 | ["about", "a group for people who love pizza"], 139 | ["public"], // or ["private"] 140 | ["open"] // or ["closed"] 141 | ] 142 | ... 143 | } 144 | ``` 145 | 146 | `name`, `picture` and `about` are basic metadata for the group for display purposes. `public` signals the group can be _read_ by anyone, while `private` signals that only AUTHed users can read. `open` signals that anyone can request to join and the request will be automatically granted, while `closed` signals that members must be pre-approved or that requests to join will be manually handled. 147 | 148 | - *group admins* (`kind:39001`) (optional) 149 | 150 | Similar to the group metadata, this event is supposed to be generated by relays that host the group. 151 | 152 | Each admin gets a label that is only used for display purposes, and a list of permissions it has are listed afterwards. These permissions can inform client building UI, but ultimately are evaluated by the relay in order to become effective. 153 | 154 | The list of capabilities, as defined by this NIP, for now, is the following: 155 | 156 | - `add-user` 157 | - `edit-metadata` 158 | - `delete-event` 159 | - `remove-user` 160 | - `add-permission` 161 | - `remove-permission` 162 | - `edit-group-status` 163 | 164 | ```js 165 | { 166 | "kind": 39001, 167 | "content": "list of admins for the pizza lovers group", 168 | "tags": [ 169 | ["d", "<group-id>"], 170 | ["p", "<pubkey1-as-hex>", "ceo", "add-user", "edit-metadata", "delete-event", "remove-user"], 171 | ["p", "<pubkey2-as-hex>", "secretary", "add-user", "delete-event"] 172 | ] 173 | ... 174 | } 175 | ``` 176 | 177 | - *group members* (`kind:39002`) (optional) 178 | 179 | Similar to *group admins*, this event is supposed to be generated by relays that host the group. 180 | 181 | It's a NIP-51-like list of pubkeys that are members of the group. Relays might choose to not to publish this information or to restrict what pubkeys can fetch it. 182 | 183 | ```json 184 | { 185 | "kind": 39002, 186 | "content": "list of members for the pizza lovers group", 187 | "tags": [ 188 | ["d", "<group-id>"], 189 | ["p", "<admin1>"], 190 | ["p", "<member-pubkey1>"], 191 | ["p", "<member-pubkey2>"], 192 | ] 193 | } 194 | ``` 195 | 196 | ## Storing the list of groups a user belongs to 197 | 198 | A definition for kind `10009` was included in [NIP-51](51.md) that allows clients to store the list of groups a user wants to remember being in. 199 | -------------------------------------------------------------------------------- /17.md: -------------------------------------------------------------------------------- 1 | NIP-17 2 | ====== 3 | 4 | Private Direct Messages 5 | ----------------------- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines an encrypted direct messaging scheme using [NIP-44](44.md) encryption and [NIP-59](59.md) seals and gift wraps. 10 | 11 | ## Direct Message Kind 12 | 13 | Kind `14` is a chat message. `p` tags identify one or more receivers of the message. 14 | 15 | ```js 16 | { 17 | "id": "<usual hash>", 18 | "pubkey": "<sender-pubkey>", 19 | "created_at": now(), 20 | "kind": 14, 21 | "tags": [ 22 | ["p", "<receiver-1-pubkey>", "<relay-url>"], 23 | ["p", "<receiver-2-pubkey>", "<relay-url>"], 24 | ["e", "<kind-14-id>", "<relay-url>", "reply"] // if this is a reply 25 | ["subject", "<conversation-title>"], 26 | ... 27 | ], 28 | "content": "<message-in-plain-text>", 29 | } 30 | ``` 31 | 32 | `.content` MUST be plain text. Fields `id` and `created_at` are required. 33 | 34 | Tags that mention, quote and assemble threading structures MUST follow [NIP-10](10.md). 35 | 36 | Kind `14`s MUST never be signed. If it is signed, the message might leak to relays and become **fully public**. 37 | 38 | ## Chat Rooms 39 | 40 | The set of `pubkey` + `p` tags defines a chat room. If a new `p` tag is added or a current one is removed, a new room is created with clean message history. 41 | 42 | Clients SHOULD render messages of the same room in a continuous thread. 43 | 44 | An optional `subject` tag defines the current name/topic of the conversation. Any member can change the topic by simply submitting a new `subject` to an existing `pubkey` + `p`-tags room. There is no need to send `subject` in every message. The newest `subject` in the thread is the subject of the conversation. 45 | 46 | ## Encrypting 47 | 48 | Following [NIP-59](59.md), the **unsigned** `kind:14` chat message must be sealed (`kind:13`) and then gift-wrapped (`kind:1059`) to each receiver and the sender individually. 49 | 50 | ```js 51 | { 52 | "id": "<usual hash>", 53 | "pubkey": randomPublicKey, 54 | "created_at": randomTimeUpTo2DaysInThePast(), 55 | "kind": 1059, // gift wrap 56 | "tags": [ 57 | ["p", receiverPublicKey, "<relay-url>"] // receiver 58 | ], 59 | "content": nip44Encrypt( 60 | { 61 | "id": "<usual hash>", 62 | "pubkey": senderPublicKey, 63 | "created_at": randomTimeUpTo2DaysInThePast(), 64 | "kind": 13, // seal 65 | "tags": [], // no tags 66 | "content": nip44Encrypt(unsignedKind14, senderPrivateKey, receiverPublicKey), 67 | "sig": "<signed by senderPrivateKey>" 68 | }, 69 | randomPrivateKey, receiverPublicKey 70 | ), 71 | "sig": "<signed by randomPrivateKey>" 72 | } 73 | ``` 74 | 75 | The encryption algorithm MUST use the latest version of [NIP-44](44.md). 76 | 77 | Clients MUST verify if pubkey of the `kind:13` is the same pubkey on the `kind:14`, otherwise any sender can impersonate others by simply changing the pubkey on `kind:14`. 78 | 79 | Clients SHOULD randomize `created_at` in up to two days in the past in both the seal and the gift wrap to make sure grouping by `created_at` doesn't reveal any metadata. 80 | 81 | The gift wrap's `p`-tag can be the receiver's main pubkey or an alias key created to receive DMs without exposing the receiver's identity. 82 | 83 | Clients CAN offer disappearing messages by setting an `expiration` tag in the gift wrap of each receiver or by not generating a gift wrap to the sender's public key 84 | 85 | ## Publishing 86 | 87 | Kind `10050` indicates the user's preferred relays to receive DMs. The event MUST include a list of `relay` tags with relay URIs. 88 | 89 | ```js 90 | { 91 | "kind": 10050, 92 | "tags": [ 93 | ["relay", "wss://inbox.nostr.wine"], 94 | ["relay", "wss://myrelay.nostr1.com"], 95 | ], 96 | "content": "", 97 | //...other fields 98 | } 99 | ``` 100 | 101 | Clients SHOULD publish kind `14` events to the `10050`-listed relays. If that is not found that indicates the user is not ready to receive messages under this NIP and clients shouldn't try. 102 | 103 | ## Relays 104 | 105 | It's advisable that relays do not serve `kind:14` to clients other than the ones tagged in them. 106 | 107 | It's advisable that users choose relays that conform to these practices. 108 | 109 | Clients SHOULD guide users to keep `kind:10050` lists small (1-3 relays) and SHOULD spread it to as many relays as viable. 110 | 111 | ## Benefits & Limitations 112 | 113 | This NIP offers the following privacy and security features: 114 | 115 | 1. **No Metadata Leak**: Participant identities, each message's real date and time, event kinds, and other event tags are all hidden from the public. Senders and receivers cannot be linked with public information alone. 116 | 2. **No Public Group Identifiers**: There is no public central queue, channel or otherwise converging identifier to correlate or count all messages in the same group. 117 | 3. **No Moderation**: There are no group admins: no invitations or bans. 118 | 4. **No Shared Secrets**: No secret must be known to all members that can leak or be mistakenly shared 119 | 5. **Fully Recoverable**: Messages can be fully recoverable by any client with the user's private key 120 | 6. **Optional Forward Secrecy**: Users and clients can opt-in for "disappearing messages". 121 | 7. **Uses Public Relays**: Messages can flow through public relays without loss of privacy. Private relays can increase privacy further, but they are not required. 122 | 8. **Cold Storage**: Users can unilaterally opt-in to sharing their messages with a separate key that is exclusive for DM backup and recovery. 123 | 124 | The main limitation of this approach is having to send a separate encrypted event to each receiver. Group chats with more than 100 participants should find a more suitable messaging scheme. 125 | 126 | ## Implementation 127 | 128 | Clients implementing this NIP should by default only connect to the set of relays found in their `kind:10050` list. From that they should be able to load all messages both sent and received as well as get new live updates, making it for a very simple and lightweight implementation that should be fast. 129 | 130 | When sending a message to anyone, clients must then connect to the relays in the receiver's `kind:10050` and send the events there, but can disconnect right after unless more messages are expected to be sent (e.g. the chat tab is still selected). Clients should also send a copy of their outgoing messages to their own `kind:10050` relay set. 131 | 132 | ## Examples 133 | 134 | This example sends the message `Hola, que tal?` from `nsec1w8udu59ydjvedgs3yv5qccshcj8k05fh3l60k9x57asjrqdpa00qkmr89m` to `nsec12ywtkplvyq5t6twdqwwygavp5lm4fhuang89c943nf2z92eez43szvn4dt`. 135 | 136 | The two final GiftWraps, one to the receiver and the other to the sender, are: 137 | 138 | ```json 139 | { 140 | "id":"2886780f7349afc1344047524540ee716f7bdc1b64191699855662330bf235d8", 141 | "pubkey":"8f8a7ec43b77d25799281207e1a47f7a654755055788f7482653f9c9661c6d51", 142 | "created_at":1703128320, 143 | "kind":1059, 144 | "tags":[ 145 | [ "p", "918e2da906df4ccd12c8ac672d8335add131a4cf9d27ce42b3bb3625755f0788"] 146 | ], 147 | "content":"AsqzdlMsG304G8h08bE67dhAR1gFTzTckUUyuvndZ8LrGCvwI4pgC3d6hyAK0Wo9gtkLqSr2rT2RyHlE5wRqbCOlQ8WvJEKwqwIJwT5PO3l2RxvGCHDbd1b1o40ZgIVwwLCfOWJ86I5upXe8K5AgpxYTOM1BD+SbgI5jOMA8tgpRoitJedVSvBZsmwAxXM7o7sbOON4MXHzOqOZpALpS2zgBDXSAaYAsTdEM4qqFeik+zTk3+L6NYuftGidqVluicwSGS2viYWr5OiJ1zrj1ERhYSGLpQnPKrqDaDi7R1KrHGFGyLgkJveY/45y0rv9aVIw9IWF11u53cf2CP7akACel2WvZdl1htEwFu/v9cFXD06fNVZjfx3OssKM/uHPE9XvZttQboAvP5UoK6lv9o3d+0GM4/3zP+yO3C0NExz1ZgFmbGFz703YJzM+zpKCOXaZyzPjADXp8qBBeVc5lmJqiCL4solZpxA1865yPigPAZcc9acSUlg23J1dptFK4n3Tl5HfSHP+oZ/QS/SHWbVFCtq7ZMQSRxLgEitfglTNz9P1CnpMwmW/Y4Gm5zdkv0JrdUVrn2UO9ARdHlPsW5ARgDmzaxnJypkfoHXNfxGGXWRk0sKLbz/ipnaQP/eFJv/ibNuSfqL6E4BnN/tHJSHYEaTQ/PdrA2i9laG3vJti3kAl5Ih87ct0w/tzYfp4SRPhEF1zzue9G/16eJEMzwmhQ5Ec7jJVcVGa4RltqnuF8unUu3iSRTQ+/MNNUkK6Mk+YuaJJs6Fjw6tRHuWi57SdKKv7GGkr0zlBUU2Dyo1MwpAqzsCcCTeQSv+8qt4wLf4uhU9Br7F/L0ZY9bFgh6iLDCdB+4iABXyZwT7Ufn762195hrSHcU4Okt0Zns9EeiBOFxnmpXEslYkYBpXw70GmymQfJlFOfoEp93QKCMS2DAEVeI51dJV1e+6t3pCSsQN69Vg6jUCsm1TMxSs2VX4BRbq562+VffchvW2BB4gMjsvHVUSRl8i5/ZSDlfzSPXcSGALLHBRzy+gn0oXXJ/447VHYZJDL3Ig8+QW5oFMgnWYhuwI5QSLEyflUrfSz+Pdwn/5eyjybXKJftePBD9Q+8NQ8zulU5sqvsMeIx/bBUx0fmOXsS3vjqCXW5IjkmSUV7q54GewZqTQBlcx+90xh/LSUxXex7UwZwRnifvyCbZ+zwNTHNb12chYeNjMV7kAIr3cGQv8vlOMM8ajyaZ5KVy7HpSXQjz4PGT2/nXbL5jKt8Lx0erGXsSsazkdoYDG3U", 148 | "sig":"a3c6ce632b145c0869423c1afaff4a6d764a9b64dedaf15f170b944ead67227518a72e455567ca1c2a0d187832cecbde7ed478395ec4c95dd3e71749ed66c480" 149 | } 150 | ``` 151 | 152 | ```json 153 | { 154 | "id":"162b0611a1911cfcb30f8a5502792b346e535a45658b3a31ae5c178465509721", 155 | "pubkey":"626be2af274b29ea4816ad672ee452b7cf96bbb4836815a55699ae402183f512", 156 | "created_at":1702711587, 157 | "kind":1059, 158 | "tags":[ 159 | [ "p", "44900586091b284416a0c001f677f9c49f7639a55c3f1e2ec130a8e1a7998e1b"] 160 | ], 161 | "content":"AsTClTzr0gzXXji7uye5UB6LYrx3HDjWGdkNaBS6BAX9CpHa+Vvtt5oI2xJrmWLen+Fo2NBOFazvl285Gb3HSM82gVycrzx1HUAaQDUG6HI7XBEGqBhQMUNwNMiN2dnilBMFC3Yc8ehCJT/gkbiNKOpwd2rFibMFRMDKai2mq2lBtPJF18oszKOjA+XlOJV8JRbmcAanTbEK5nA/GnG3eGUiUzhiYBoHomj3vztYYxc0QYHOx0WxiHY8dsC6jPsXC7f6k4P+Hv5ZiyTfzvjkSJOckel1lZuE5SfeZ0nduqTlxREGeBJ8amOykgEIKdH2VZBZB+qtOMc7ez9dz4wffGwBDA7912NFS2dPBr6txHNxBUkDZKFbuD5wijvonZDvfWq43tZspO4NutSokZB99uEiRH8NAUdGTiNb25m9JcDhVfdmABqTg5fIwwTwlem5aXIy8b66lmqqz2LBzJtnJDu36bDwkILph3kmvaKPD8qJXmPQ4yGpxIbYSTCohgt2/I0TKJNmqNvSN+IVoUuC7ZOfUV9lOV8Ri0AMfSr2YsdZ9ofV5o82ClZWlWiSWZwy6ypa7CuT1PEGHzywB4CZ5ucpO60Z7hnBQxHLiAQIO/QhiBp1rmrdQZFN6PUEjFDloykoeHe345Yqy9Ke95HIKUCS9yJurD+nZjjgOxZjoFCsB1hQAwINTIS3FbYOibZnQwv8PXvcSOqVZxC9U0+WuagK7IwxzhGZY3vLRrX01oujiRrevB4xbW7Oxi/Agp7CQGlJXCgmRE8Rhm+Vj2s+wc/4VLNZRHDcwtfejogjrjdi8p6nfUyqoQRRPARzRGUnnCbh+LqhigT6gQf3sVilnydMRScEc0/YYNLWnaw9nbyBa7wFBAiGbJwO40k39wj+xT6HTSbSUgFZzopxroO3f/o4+ubx2+IL3fkev22mEN38+dFmYF3zE+hpE7jVxrJpC3EP9PLoFgFPKCuctMnjXmeHoiGs756N5r1Mm1ffZu4H19MSuALJlxQR7VXE/LzxRXDuaB2u9days/6muP6gbGX1ASxbJd/ou8+viHmSC/ioHzNjItVCPaJjDyc6bv+gs1NPCt0qZ69G+JmgHW/PsMMeL4n5bh74g0fJSHqiI9ewEmOG/8bedSREv2XXtKV39STxPweceIOh0k23s3N6+wvuSUAJE7u1LkDo14cobtZ/MCw/QhimYPd1u5HnEJvRhPxz0nVPz0QqL/YQeOkAYk7uzgeb2yPzJ6DBtnTnGDkglekhVzQBFRJdk740LEj6swkJ", 162 | "sig":"c94e74533b482aa8eeeb54ae72a5303e0b21f62909ca43c8ef06b0357412d6f8a92f96e1a205102753777fd25321a58fba3fb384eee114bd53ce6c06a1c22bab" 163 | } 164 | ``` 165 | -------------------------------------------------------------------------------- /52.md: -------------------------------------------------------------------------------- 1 | NIP-52 2 | ====== 3 | 4 | Calendar Events 5 | --------------- 6 | 7 | `draft` `optional` 8 | 9 | This specification defines calendar events representing an occurrence at a specific moment or between moments. These calendar events are _parameterized replaceable_ and deletable per [NIP-09](09.md). 10 | 11 | Unlike the term `calendar event` specific to this NIP, the term `event` is used broadly in all the NIPs to describe any Nostr event. The distinction is being made here to discern between the two terms. 12 | 13 | ## Calendar Events 14 | 15 | There are two types of calendar events represented by different kinds: date-based and time-based calendar events. Calendar events are not required to be part of a [calendar](#calendar). 16 | 17 | ### Date-Based Calendar Event 18 | 19 | This kind of calendar event starts on a date and ends before a different date in the future. Its use is appropriate for all-day or multi-day events where time and time zone hold no significance. e.g., anniversary, public holidays, vacation days. 20 | 21 | #### Format 22 | 23 | The format uses a parameterized replaceable event kind `31922`. 24 | 25 | The `.content` of these events should be a detailed description of the calendar event. It is required but can be an empty string. 26 | 27 | The list of tags are as follows: 28 | * `d` (required) universally unique identifier (UUID). Generated by the client creating the calendar event. 29 | * `title` (required) title of the calendar event 30 | * `start` (required) inclusive start date in ISO 8601 format (YYYY-MM-DD). Must be less than `end`, if it exists. 31 | * `end` (optional) exclusive end date in ISO 8601 format (YYYY-MM-DD). If omitted, the calendar event ends on the same date as `start`. 32 | * `location` (optional, repeated) location of the calendar event. e.g. address, GPS coordinates, meeting room name, link to video call 33 | * `g` (optional) [geohash](https://en.wikipedia.org/wiki/Geohash) to associate calendar event with a searchable physical location 34 | * `p` (optional, repeated) 32-bytes hex pubkey of a participant, optional recommended relay URL, and participant's role in the meeting 35 | * `t` (optional, repeated) hashtag to categorize calendar event 36 | * `r` (optional, repeated) references / links to web pages, documents, video calls, recorded videos, etc. 37 | 38 | The following tags are deprecated: 39 | * `name` name of the calendar event. Use only if `title` is not available. 40 | 41 | ```jsonc 42 | { 43 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 44 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 45 | "created_at": <Unix timestamp in seconds>, 46 | "kind": 31922, 47 | "content": "<description of calendar event>", 48 | "tags": [ 49 | ["d", "<UUID>"], 50 | 51 | ["title", "<title of calendar event>"], 52 | 53 | // Dates 54 | ["start", "<YYYY-MM-DD>"], 55 | ["end", "<YYYY-MM-DD>"], 56 | 57 | // Location 58 | ["location", "<location>"], 59 | ["g", "<geohash>"], 60 | 61 | // Participants 62 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"], 63 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"], 64 | 65 | // Hashtags 66 | ["t", "<tag>"], 67 | ["t", "<tag>"], 68 | 69 | // Reference links 70 | ["r", "<url>"], 71 | ["r", "<url>"] 72 | ] 73 | } 74 | ``` 75 | 76 | ### Time-Based Calendar Event 77 | 78 | This kind of calendar event spans between a start time and end time. 79 | 80 | #### Format 81 | 82 | The format uses a parameterized replaceable event kind `31923`. 83 | 84 | The `.content` of these events should be a detailed description of the calendar event. It is required but can be an empty string. 85 | 86 | The list of tags are as follows: 87 | * `d` (required) universally unique identifier (UUID). Generated by the client creating the calendar event. 88 | * `title` (required) title of the calendar event 89 | * `start` (required) inclusive start Unix timestamp in seconds. Must be less than `end`, if it exists. 90 | * `end` (optional) exclusive end Unix timestamp in seconds. If omitted, the calendar event ends instantaneously. 91 | * `start_tzid` (optional) time zone of the start timestamp, as defined by the IANA Time Zone Database. e.g., `America/Costa_Rica` 92 | * `end_tzid` (optional) time zone of the end timestamp, as defined by the IANA Time Zone Database. e.g., `America/Costa_Rica`. If omitted and `start_tzid` is provided, the time zone of the end timestamp is the same as the start timestamp. 93 | * `location` (optional, repeated) location of the calendar event. e.g. address, GPS coordinates, meeting room name, link to video call 94 | * `g` (optional) [geohash](https://en.wikipedia.org/wiki/Geohash) to associate calendar event with a searchable physical location 95 | * `p` (optional, repeated) 32-bytes hex pubkey of a participant, optional recommended relay URL, and participant's role in the meeting 96 | * `t` (optional, repeated) hashtag to categorize calendar event 97 | * `r` (optional, repeated) references / links to web pages, documents, video calls, recorded videos, etc. 98 | 99 | The following tags are deprecated: 100 | * `name` name of the calendar event. Use only if `title` is not available. 101 | 102 | ```jsonc 103 | { 104 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 105 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 106 | "created_at": <Unix timestamp in seconds>, 107 | "kind": 31923, 108 | "content": "<description of calendar event>", 109 | "tags": [ 110 | ["d", "<UUID>"], 111 | 112 | ["title", "<title of calendar event>"], 113 | 114 | // Timestamps 115 | ["start", "<Unix timestamp in seconds>"], 116 | ["end", "<Unix timestamp in seconds>"], 117 | 118 | ["start_tzid", "<IANA Time Zone Database identifier>"], 119 | ["end_tzid", "<IANA Time Zone Database identifier>"], 120 | 121 | // Location 122 | ["location", "<location>"], 123 | ["g", "<geohash>"], 124 | 125 | // Participants 126 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"], 127 | ["p", "<32-bytes hex of a pubkey>", "<optional recommended relay URL>", "<role>"], 128 | 129 | // Hashtags 130 | ["t", "<tag>"], 131 | ["t", "<tag>"], 132 | 133 | // Reference links 134 | ["r", "<url>"], 135 | ["r", "<url>"] 136 | ] 137 | } 138 | ``` 139 | 140 | ## Calendar 141 | 142 | A calendar is a collection of calendar events, represented as a custom replaceable list event using kind `31924`. A user can have multiple calendars. One may create a calendar to segment calendar events for specific purposes. e.g., personal, work, travel, meetups, and conferences. 143 | 144 | ### Format 145 | 146 | The `.content` of these events should be a detailed description of the calendar. It is required but can be an empty string. 147 | 148 | The format uses a custom replaceable list of kind `31924` with a list of tags as described below: 149 | * `d` (required) universally unique identifier. Generated by the client creating the calendar. 150 | * `title` (required) calendar title 151 | * `a` (repeated) reference tag to kind `31922` or `31923` calendar event being responded to 152 | 153 | ```json 154 | { 155 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 156 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 157 | "created_at": <Unix timestamp in seconds>, 158 | "kind": 31924, 159 | "content": "<description of calendar>", 160 | "tags": [ 161 | ["d", "<UUID>"], 162 | ["title", "<calendar title>"], 163 | ["a", "<31922 or 31923>:<calendar event author pubkey>:<d-identifier of calendar event>", "<optional relay url>"], 164 | ["a", "<31922 or 31923>:<calendar event author pubkey>:<d-identifier of calendar event>", "<optional relay url>"] 165 | ] 166 | } 167 | ``` 168 | 169 | ## Calendar Event RSVP 170 | 171 | A calendar event RSVP is a response to a calendar event to indicate a user's attendance intention. 172 | 173 | If a calendar event tags a pubkey, that can be interpreted as the calendar event creator inviting that user to attend. Clients MAY choose to prompt the user to RSVP for the calendar event. 174 | 175 | Any user may RSVP, even if they were not tagged on the calendar event. Clients MAY choose to prompt the calendar event creator to invite the user who RSVP'd. Clients also MAY choose to ignore these RSVPs. 176 | 177 | This NIP is intentionally not defining who is authorized to attend a calendar event if the user who RSVP'd has not been tagged. It is up to the calendar event creator to determine the semantics. 178 | 179 | This NIP is also intentionally not defining what happens if a calendar event changes after an RSVP is submitted. 180 | 181 | ### Format 182 | 183 | The format uses a parameterized replaceable event kind `31925`. 184 | 185 | The `.content` of these events is optional and should be a free-form note that adds more context to this calendar event response. 186 | 187 | The list of tags are as follows: 188 | * `a` (required) reference tag to kind `31922` or `31923` calendar event being responded to. 189 | * `d` (required) universally unique identifier. Generated by the client creating the calendar event RSVP. 190 | * `status` (required) `accepted`, `declined`, or `tentative`. Determines attendance status to the referenced calendar event. 191 | * `fb` (optional) `free` or `busy`. Determines if the user would be free or busy for the duration of the calendar event. This tag must be omitted or ignored if the `status` label is set to `declined`. 192 | 193 | ```json 194 | { 195 | "id": <32-bytes lowercase hex-encoded SHA-256 of the the serialized event data>, 196 | "pubkey": <32-bytes lowercase hex-encoded public key of the event creator>, 197 | "created_at": <Unix timestamp in seconds>, 198 | "kind": 31925, 199 | "content": "<note>", 200 | "tags": [ 201 | ["a", "<31922 or 31923>:<calendar event author pubkey>:<d-identifier of calendar event>", "<optional relay url>"], 202 | ["d", "<UUID>"], 203 | ["status", "<accepted/declined/tentative>"], 204 | ["fb", "<free/busy>"], 205 | ] 206 | } 207 | ``` 208 | 209 | ## Unsolved Limitations 210 | 211 | * No private events 212 | 213 | ## Intentionally Unsupported Scenarios 214 | 215 | ### Recurring Calendar Events 216 | 217 | Recurring calendar events come with a lot of complexity, making it difficult for software and humans to deal with. This complexity includes time zone differences between invitees, daylight savings, leap years, multiple calendar systems, one-off changes in schedule or other metadata, etc. 218 | 219 | This NIP intentionally omits support for recurring calendar events and pushes that complexity up to clients to manually implement if they desire. i.e., individual calendar events with duplicated metadata represent recurring calendar events. 220 | -------------------------------------------------------------------------------- /51.md: -------------------------------------------------------------------------------- 1 | NIP-51 2 | ====== 3 | 4 | Lists 5 | ----- 6 | 7 | `draft` `optional` 8 | 9 | This NIP defines lists of things that users can create. Lists can contain references to anything, and these references can be **public** or **private**. 10 | 11 | Public items in a list are specified in the event `tags` array, while private items are specified in a JSON array that mimics the structure of the event `tags` array, but stringified and encrypted using the same scheme from [NIP-04](04.md) (the shared key is computed using the author's public and private key) and stored in the `.content`. 12 | 13 | When new items are added to an existing list, clients SHOULD append them to the end of the list, so they are stored in chronological order. 14 | 15 | ## Types of lists 16 | 17 | ## Standard lists 18 | 19 | Standard lists use non-parameterized replaceable events, meaning users may only have a single list of each kind. They have special meaning and clients may rely on them to augment a user's profile or browsing experience. 20 | 21 | For example, _mute list_ can contain the public keys of spammers and bad actors users don't want to see in their feeds or receive annoying notifications from. 22 | 23 | | name | kind | description | expected tag items | 24 | |-------------------|-------|-------------------------------------------------------------|-----------------------------------------------------------------------------------| 25 | | Mute list | 10000 | things the user doesn't want to see in their feeds | `"p"` (pubkeys), `"t"` (hashtags), `"word"` (lowercase string), `"e"` (threads) | 26 | | Pinned notes | 10001 | events the user intends to showcase in their profile page | `"e"` (kind:1 notes) | 27 | | Bookmarks | 10003 | uncategorized, "global" list of things a user wants to save | `"e"` (kind:1 notes), `"a"` (kind:30023 articles), `"t"` (hashtags), `"r"` (URLs) | 28 | | Communities | 10004 | [NIP-72](72.md) communities the user belongs to | `"a"` (kind:34550 community definitions) | 29 | | Public chats | 10005 | [NIP-28](28.md) chat channels the user is in | `"e"` (kind:40 channel definitions) | 30 | | Blocked relays | 10006 | relays clients should never connect to | `"relay"` (relay URLs) | 31 | | Search relays | 10007 | relays clients should use when performing search queries | `"relay"` (relay URLs) | 32 | | Simple groups | 10009 | [NIP-29](29.md) groups the user is in | `"group"` ([NIP-29](29.md) group ids + mandatory relay URL) | 33 | | Profile Gallery | 10011 | Profile Media Gallery | `"url"` + (url to media file) + (kind:1 note) + (relay hint) | 34 | | Interests | 10015 | topics a user may be interested in and pointers | `"t"` (hashtags) and `"a"` (kind:30015 interest set) | 35 | | Emojis | 10030 | user preferred emojis and pointers to emoji sets | `"emoji"` (see [NIP-30](30.md)) and `"a"` (kind:30030 emoji set) | 36 | | Good wiki authors | 10101 | [NIP-54](54.md) user recommended wiki authors | `"p"` (pubkeys) | 37 | | Good wiki relays | 10102 | [NIP-54](54.md) relays deemed to only host useful articles | `"relay"` (relay URLs) | 38 | 39 | ## Sets 40 | 41 | Sets are lists with well-defined meaning that can enhance the functionality and the UI of clients that rely on them. Unlike standard lists, users are expected to have more than one set of each kind, therefore each of them must be assigned a different `"d"` identifier. 42 | 43 | For example, _relay sets_ can be displayed in a dropdown UI to give users the option to switch to which relays they will publish an event or from which relays they will read the replies to an event; _curation sets_ can be used by apps to showcase curations made by others tagged to different topics. 44 | 45 | Aside from their main identifier, the `"d"` tag, sets can optionally have a `"title"`, an `"image"` and a `"description"` tags that can be used to enhance their UI. 46 | 47 | | name | kind | description | expected tag items | 48 | | --- | --- | --- | --- | 49 | | Follow sets | 30000 | categorized groups of users a client may choose to check out in different circumstances | `"p"` (pubkeys) | 50 | | Relay sets | 30002 | user-defined relay groups the user can easily pick and choose from during various operations | `"relay"` (relay URLs) | 51 | | Bookmark sets | 30003 | user-defined bookmarks categories , for when bookmarks must be in labeled separate groups | `"e"` (kind:1 notes), `"a"` (kind:30023 articles), `"t"` (hashtags), `"r"` (URLs) | 52 | | Curation sets | 30004 | groups of articles picked by users as interesting and/or belonging to the same category | `"a"` (kind:30023 articles), `"e"` (kind:1 notes) | 53 | | Curation sets | 30005 | groups of videos picked by users as interesting and/or belonging to the same category | `"a"` (kind:34235 videos) | 54 | | Interest sets | 30015 | interest topics represented by a bunch of "hashtags" | `"t"` (hashtags) | 55 | | Emoji sets | 30030 | categorized emoji groups | `"emoji"` (see [NIP-30](30.md)) | 56 | | Release artifact sets | 30063 | groups of files of a software release | `"e"` (kind:1063 [file metadata](94.md) events), `"i"` (application identifier, typically reverse domain notation), `"version"` | 57 | 58 | ## Deprecated standard lists 59 | 60 | Some clients have used these lists in the past, but they should work on transitioning to the [standard formats](#standard-lists) above. 61 | 62 | | kind | "d" tag | use instead | 63 | | --- | --- | --- | 64 | | 30000 | `"mute"` | kind 10000 _mute list_ | 65 | | 30001 | `"pin"` | kind 10001 _pin list_ | 66 | | 30001 | `"bookmark"` | kind 10003 _bookmarks list_ | 67 | | 30001 | `"communities"` | kind 10004 _communities list_ | 68 | 69 | ## Examples 70 | 71 | ### A _mute list_ with some public items and some encrypted items 72 | 73 | ```json 74 | { 75 | "id": "a92a316b75e44cfdc19986c634049158d4206fcc0b7b9c7ccbcdabe28beebcd0", 76 | "pubkey": "854043ae8f1f97430ca8c1f1a090bdde6488bd5115c7a45307a2a212750ae4cb", 77 | "created_at": 1699597889, 78 | "kind": 10000, 79 | "tags": [ 80 | ["p", "07caba282f76441955b695551c3c5c742e5b9202a3784780f8086fdcdc1da3a9"], 81 | ["p", "a55c15f5e41d5aebd236eca5e0142789c5385703f1a7485aa4b38d94fd18dcc4"] 82 | ], 83 | "content": "TJob1dQrf2ndsmdbeGU+05HT5GMnBSx3fx8QdDY/g3NvCa7klfzgaQCmRZuo1d3WQjHDOjzSY1+MgTK5WjewFFumCcOZniWtOMSga9tJk1ky00tLoUUzyLnb1v9x95h/iT/KpkICJyAwUZ+LoJBUzLrK52wNTMt8M5jSLvCkRx8C0BmEwA/00pjOp4eRndy19H4WUUehhjfV2/VV/k4hMAjJ7Bb5Hp9xdmzmCLX9+64+MyeIQQjQAHPj8dkSsRahP7KS3MgMpjaF8nL48Bg5suZMxJayXGVp3BLtgRZx5z5nOk9xyrYk+71e2tnP9IDvSMkiSe76BcMct+m7kGVrRcavDI4n62goNNh25IpghT+a1OjjkpXt9me5wmaL7fxffV1pchdm+A7KJKIUU3kLC7QbUifF22EucRA9xiEyxETusNludBXN24O3llTbOy4vYFsq35BeZl4v1Cse7n2htZicVkItMz3wjzj1q1I1VqbnorNXFgllkRZn4/YXfTG/RMnoK/bDogRapOV+XToZ+IvsN0BqwKSUDx+ydKpci6htDRF2WDRkU+VQMqwM0CoLzy2H6A2cqyMMMD9SLRRzBg==?iv=S3rFeFr1gsYqmQA7bNnNTQ==", 84 | "sig": "1173822c53261f8cffe7efbf43ba4a97a9198b3e402c2a1df130f42a8985a2d0d3430f4de350db184141e45ca844ab4e5364ea80f11d720e36357e1853dba6ca" 85 | } 86 | ``` 87 | 88 | ### A _curation set_ of articles and notes about yaks 89 | 90 | ```json 91 | { 92 | "id": "567b41fc9060c758c4216fe5f8d3df7c57daad7ae757fa4606f0c39d4dd220ef", 93 | "pubkey": "d6dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c", 94 | "created_at": 1695327657, 95 | "kind": 30004, 96 | "tags": [ 97 | ["d", "jvdy9i4"], 98 | ["name", "Yaks"], 99 | ["picture", "https://cdn.britannica.com/40/188540-050-9AC748DE/Yak-Himalayas-Nepal.jpg"], 100 | ["about", "The domestic yak, also known as the Tartary ox, grunting ox, or hairy cattle, is a species of long-haired domesticated cattle found throughout the Himalayan region of the Indian subcontinent, the Tibetan Plateau, Gilgit-Baltistan, Tajikistan and as far north as Mongolia and Siberia."], 101 | ["a", "30023:26dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:95ODQzw3ajNoZ8SyMDOzQ"], 102 | ["a", "30023:54af95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:1-MYP8dAhramH9J5gJWKx"], 103 | ["a", "30023:f8fe95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c:D2Tbd38bGrFvU0bIbvSMt"], 104 | ["e", "d78ba0d5dce22bfff9db0a9e996c9ef27e2c91051de0c4e1da340e0326b4941e"] 105 | ], 106 | "content": "", 107 | "sig": "a9a4e2192eede77e6c9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad001cb039cb8de91d83ce30e9a94f82ac3c5a2372aa1294a96bd" 108 | } 109 | ``` 110 | 111 | ### A _release artifact set_ of an Example App 112 | 113 | ```json 114 | { 115 | "id": "567b41fc9060c758c4216fe5f8d3df7c57daad7ae757fa4606f0c39d4dd220ef", 116 | "pubkey": "d6dc95542e18b8b7aec2f14610f55c335abebec76f3db9e58c254661d0593a0c", 117 | "created_at": 1695327657, 118 | "kind": 30063, 119 | "tags": [ 120 | ["d", "ak8dy3v7"], 121 | ["i", "com.example.app"], 122 | ["version", "0.0.1"], 123 | ["title", "Example App"], 124 | ["image", "http://cdn.site/p/com.example.app/icon.png"], 125 | ["e", "d78ba0d5dce22bfff9db0a9e996c9ef27e2c91051de0c4e1da340e0326b4941e"], // Windows exe 126 | ["e", "f27e2c91051de0c4e1da0d5dce22bfff9db0a9340e0326b4941ed78bae996c9e"], // MacOS dmg 127 | ["e", "9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad02332"], // Linux AppImage 128 | ["e", "340e0326b340e0326b4941ed78ba340e0326b4941ed78ba340e0326b49ed78ba"] // PWA 129 | ], 130 | "content": "Example App is a decentralized marketplace for apps", 131 | "sig": "a9a4e2192eede77e6c9d24ddfab95ba3ff7c03fbd07ad011fff245abea431fb4d3787c2d04aad001cb039cb8de91d83ce30e9a94f82ac3c5a2372aa1294a96bd" 132 | } 133 | ``` 134 | 135 | ## Encryption process pseudocode 136 | 137 | ```scala 138 | val private_items = [ 139 | ["p", "07caba282f76441955b695551c3c5c742e5b9202a3784780f8086fdcdc1da3a9"], 140 | ["a", "a55c15f5e41d5aebd236eca5e0142789c5385703f1a7485aa4b38d94fd18dcc4"], 141 | ] 142 | val base64blob = nip04.encrypt(json.encode_to_string(private_items)) 143 | event.content = base64blob 144 | ``` 145 | -------------------------------------------------------------------------------- /59.md: -------------------------------------------------------------------------------- 1 | NIP-59 2 | ====== 3 | 4 | Gift Wrap 5 | --------- 6 | 7 | `optional` 8 | 9 | This NIP defines a protocol for encapsulating any nostr event. This makes it possible to obscure most metadata 10 | for a given event, perform collaborative signing, and more. 11 | 12 | This NIP *does not* define any messaging protocol. Applications of this NIP should be defined separately. 13 | 14 | This NIP relies on [NIP-44](./44.md)'s versioned encryption algorithms. 15 | 16 | # Overview 17 | 18 | This protocol uses three main concepts to protect the transmission of a target event: `rumor`s, `seal`s, and `gift wrap`s. 19 | 20 | - A `rumor` is a regular nostr event, but is **not signed**. This means that if it is leaked, it cannot be verified. 21 | - A `rumor` is serialized to JSON, encrypted, and placed in the `content` field of a `seal`. The `seal` is then 22 | signed by the author of the note. The only information publicly available on a `seal` is who signed it, but not what was said. 23 | - A `seal` is serialized to JSON, encrypted, and placed in the `content` field of a `gift wrap`. 24 | 25 | This allows the isolation of concerns across layers: 26 | 27 | - A rumor carries the content but is unsigned, which means if leaked it will be rejected by relays and clients, 28 | and can't be authenticated. This provides a measure of deniability. 29 | - A seal identifies the author without revealing the content or the recipient. 30 | - A gift wrap can add metadata (recipient, tags, a different author) without revealing the true author. 31 | 32 | # Protocol Description 33 | 34 | ## 1. The Rumor Event Kind 35 | 36 | A `rumor` is the same thing as an unsigned event. Any event kind can be made a `rumor` by removing the signature. 37 | 38 | ## 2. The Seal Event Kind 39 | 40 | A `seal` is a `kind:13` event that wraps a `rumor` with the sender's regular key. The `seal` is **always** encrypted 41 | to a receiver's pubkey but there is no `p` tag pointing to the receiver. There is no way to know who the rumor is for 42 | without the receiver's or the sender's private key. The only public information in this event is who is signing it. 43 | 44 | ```js 45 | { 46 | "id": "<id>", 47 | "pubkey": "<real author's pubkey>", 48 | "content": "<encrypted rumor>", 49 | "kind": 13, 50 | "created_at": 1686840217, 51 | "tags": [], 52 | "sig": "<real author's pubkey signature>" 53 | } 54 | ``` 55 | 56 | Tags MUST must always be empty in a `kind:13`. The inner event MUST always be unsigned. 57 | 58 | ## 3. Gift Wrap Event Kind 59 | 60 | A `gift wrap` event is a `kind:1059` event that wraps any other event. `tags` SHOULD include any information 61 | needed to route the event to its intended recipient, including the recipient's `p` tag or [NIP-13](13.md) proof of work. 62 | 63 | ```js 64 | { 65 | "id": "<id>", 66 | "pubkey": "<random, one-time-use pubkey>", 67 | "content": "<encrypted kind 13>", 68 | "kind": 1059, 69 | "created_at": 1686840217, 70 | "tags": [["p", "<recipient pubkey>"]], 71 | "sig": "<random, one-time-use pubkey signature>" 72 | } 73 | ``` 74 | 75 | # Encrypting Payloads 76 | 77 | Encryption is done following [NIP-44](44.md) on the JSON-encoded event. Place the encryption payload in the `.content` 78 | of the wrapper event (either a `seal` or a `gift wrap`). 79 | 80 | # Other Considerations 81 | 82 | If a `rumor` is intended for more than one party, or if the author wants to retain an encrypted copy, a single 83 | `rumor` may be wrapped and addressed for each recipient individually. 84 | 85 | The canonical `created_at` time belongs to the `rumor`. All other timestamps SHOULD be tweaked to thwart 86 | time-analysis attacks. Note that some relays don't serve events dated in the future, so all timestamps 87 | SHOULD be in the past. 88 | 89 | Relays may choose not to store gift wrapped events due to them not being publicly useful. Clients MAY choose 90 | to attach a certain amount of proof-of-work to the wrapper event per [NIP-13](13.md) in a bid to demonstrate that 91 | the event is not spam or a denial-of-service attack. 92 | 93 | To protect recipient metadata, relays SHOULD guard access to `kind 1059` events based on user AUTH. When 94 | possible, clients should only send wrapped events to relays that offer this protection. 95 | 96 | To protect recipient metadata, relays SHOULD only serve `kind 1059` events intended for the marked recipient. 97 | When possible, clients should only send wrapped events to `read` relays for the recipient that implement 98 | AUTH, and refuse to serve wrapped events to non-recipients. 99 | 100 | # An Example 101 | 102 | Let's send a wrapped `kind 1` message between two parties asking "Are you going to the party tonight?" 103 | 104 | - Author private key: `0beebd062ec8735f4243466049d7747ef5d6594ee838de147f8aab842b15e273` 105 | - Recipient private key: `e108399bd8424357a710b606ae0c13166d853d327e47a6e5e038197346bdbf45` 106 | - Ephemeral wrapper key: `4f02eac59266002db5801adc5270700ca69d5b8f761d8732fab2fbf233c90cbd` 107 | 108 | Note that this messaging protocol should not be used in practice, this is just an example. Refer to other 109 | NIPs for concrete messaging protocols that depend on gift wraps. 110 | 111 | ## 1. Create an event 112 | 113 | Create a `kind 1` event with the message, the receivers, and any other tags you want, signed by the author. 114 | Do not sign the event. 115 | 116 | ```json 117 | { 118 | "created_at": 1691518405, 119 | "content": "Are you going to the party tonight?", 120 | "tags": [], 121 | "kind": 1, 122 | "pubkey": "611df01bfcf85c26ae65453b772d8f1dfd25c264621c0277e1fc1518686faef9", 123 | "id": "9dd003c6d3b73b74a85a9ab099469ce251653a7af76f523671ab828acd2a0ef9" 124 | } 125 | ``` 126 | 127 | ## 2. Seal the rumor 128 | 129 | Encrypt the JSON-encoded `rumor` with a conversation key derived using the author's private key and 130 | the recipient's public key. Place the result in the `content` field of a `kind 13` `seal` event. Sign 131 | it with the author's key. 132 | 133 | ```json 134 | { 135 | "content": "AqBCdwoS7/tPK+QGkPCadJTn8FxGkd24iApo3BR9/M0uw6n4RFAFSPAKKMgkzVMoRyR3ZS/aqATDFvoZJOkE9cPG/TAzmyZvr/WUIS8kLmuI1dCA+itFF6+ULZqbkWS0YcVU0j6UDvMBvVlGTzHz+UHzWYJLUq2LnlynJtFap5k8560+tBGtxi9Gx2NIycKgbOUv0gEqhfVzAwvg1IhTltfSwOeZXvDvd40rozONRxwq8hjKy+4DbfrO0iRtlT7G/eVEO9aJJnqagomFSkqCscttf/o6VeT2+A9JhcSxLmjcKFG3FEK3Try/WkarJa1jM3lMRQqVOZrzHAaLFW/5sXano6DqqC5ERD6CcVVsrny0tYN4iHHB8BHJ9zvjff0NjLGG/v5Wsy31+BwZA8cUlfAZ0f5EYRo9/vKSd8TV0wRb9DQ=", 136 | "kind": 13, 137 | "created_at": 1703015180, 138 | "pubkey": "611df01bfcf85c26ae65453b772d8f1dfd25c264621c0277e1fc1518686faef9", 139 | "tags": [], 140 | "id": "28a87d7c074d94a58e9e89bb3e9e4e813e2189f285d797b1c56069d36f59eaa7", 141 | "sig": "02fc3facf6621196c32912b1ef53bac8f8bfe9db51c0e7102c073103586b0d29c3f39bdaa1e62856c20e90b6c7cc5dc34ca8bb6a528872cf6e65e6284519ad73" 142 | } 143 | ``` 144 | 145 | ## 3. Wrap the seal 146 | 147 | Encrypt the JSON-encoded `kind 13` event with your ephemeral, single-use random key. Place the result 148 | in the `content` field of a `kind 1059`. Add a single `p` tag containing the recipient's public key. 149 | Sign the `gift wrap` using the random key generated in the previous step. 150 | 151 | ```json 152 | { 153 | "content": "AhC3Qj/QsKJFWuf6xroiYip+2yK95qPwJjVvFujhzSguJWb/6TlPpBW0CGFwfufCs2Zyb0JeuLmZhNlnqecAAalC4ZCugB+I9ViA5pxLyFfQjs1lcE6KdX3euCHBLAnE9GL/+IzdV9vZnfJH6atVjvBkNPNzxU+OLCHO/DAPmzmMVx0SR63frRTCz6Cuth40D+VzluKu1/Fg2Q1LSst65DE7o2efTtZ4Z9j15rQAOZfE9jwMCQZt27rBBK3yVwqVEriFpg2mHXc1DDwHhDADO8eiyOTWF1ghDds/DxhMcjkIi/o+FS3gG1dG7gJHu3KkGK5UXpmgyFKt+421m5o++RMD/BylS3iazS1S93IzTLeGfMCk+7IKxuSCO06k1+DaasJJe8RE4/rmismUvwrHu/HDutZWkvOAhd4z4khZo7bJLtiCzZCZ74lZcjOB4CYtuAX2ZGpc4I1iOKkvwTuQy9BWYpkzGg3ZoSWRD6ty7U+KN+fTTmIS4CelhBTT15QVqD02JxfLF7nA6sg3UlYgtiGw61oH68lSbx16P3vwSeQQpEB5JbhofW7t9TLZIbIW/ODnI4hpwj8didtk7IMBI3Ra3uUP7ya6vptkd9TwQkd/7cOFaSJmU+BIsLpOXbirJACMn+URoDXhuEtiO6xirNtrPN8jYqpwvMUm5lMMVzGT3kMMVNBqgbj8Ln8VmqouK0DR+gRyNb8fHT0BFPwsHxDskFk5yhe5c/2VUUoKCGe0kfCcX/EsHbJLUUtlHXmTqaOJpmQnW1tZ/siPwKRl6oEsIJWTUYxPQmrM2fUpYZCuAo/29lTLHiHMlTbarFOd6J/ybIbICy2gRRH/LFSryty3Cnf6aae+A9uizFBUdCwTwffc3vCBae802+R92OL78bbqHKPbSZOXNC+6ybqziezwG+OPWHx1Qk39RYaF0aFsM4uZWrFic97WwVrH5i+/Nsf/OtwWiuH0gV/SqvN1hnkxCTF/+XNn/laWKmS3e7wFzBsG8+qwqwmO9aVbDVMhOmeUXRMkxcj4QreQkHxLkCx97euZpC7xhvYnCHarHTDeD6nVK+xzbPNtzeGzNpYoiMqxZ9bBJwMaHnEoI944Vxoodf51cMIIwpTmmRvAzI1QgrfnOLOUS7uUjQ/IZ1Qa3lY08Nqm9MAGxZ2Ou6R0/Z5z30ha/Q71q6meAs3uHQcpSuRaQeV29IASmye2A2Nif+lmbhV7w8hjFYoaLCRsdchiVyNjOEM4VmxUhX4VEvw6KoCAZ/XvO2eBF/SyNU3Of4SO", 154 | "kind": 1059, 155 | "created_at": 1703021488, 156 | "pubkey": "18b1a75918f1f2c90c23da616bce317d36e348bcf5f7ba55e75949319210c87c", 157 | "id": "5c005f3ccf01950aa8d131203248544fb1e41a0d698e846bd419cec3890903ac", 158 | "sig": "35fabdae4634eb630880a1896a886e40fd6ea8a60958e30b89b33a93e6235df750097b04f9e13053764251b8bc5dd7e8e0794a3426a90b6bcc7e5ff660f54259", 159 | "tags": [["p", "166bf3765ebd1fc55decfe395beff2ea3b2a4e0a8946e7eb578512b555737c99"]], 160 | } 161 | ``` 162 | 163 | ## 4. Broadcast Selectively 164 | 165 | Broadcast the `kind 1059` event to the recipient's relays only. Delete all the other events. 166 | 167 | # Code Samples 168 | 169 | ## JavaScript 170 | 171 | ```javascript 172 | import {bytesToHex} from "@noble/hashes/utils" 173 | import type {EventTemplate, UnsignedEvent, Event} from "nostr-tools" 174 | import {getPublicKey, getEventHash, nip19, nip44, finalizeEvent, generateSecretKey} from "nostr-tools" 175 | 176 | type Rumor = UnsignedEvent & {id: string} 177 | 178 | const TWO_DAYS = 2 * 24 * 60 * 60 179 | 180 | const now = () => Math.round(Date.now() / 1000) 181 | const randomNow = () => Math.round(now() - (Math.random() * TWO_DAYS)) 182 | 183 | const nip44ConversationKey = (privateKey: Uint8Array, publicKey: string) => 184 | nip44.v2.utils.getConversationKey(bytesToHex(privateKey), publicKey) 185 | 186 | const nip44Encrypt = (data: EventTemplate, privateKey: Uint8Array, publicKey: string) => 187 | nip44.v2.encrypt(JSON.stringify(data), nip44ConversationKey(privateKey, publicKey)) 188 | 189 | const nip44Decrypt = (data: Event, privateKey: Uint8Array) => 190 | JSON.parse(nip44.v2.decrypt(data.content, nip44ConversationKey(privateKey, data.pubkey))) 191 | 192 | const createRumor = (event: Partial<UnsignedEvent>, privateKey: Uint8Array) => { 193 | const rumor = { 194 | created_at: now(), 195 | content: "", 196 | tags: [], 197 | ...event, 198 | pubkey: getPublicKey(privateKey), 199 | } as any 200 | 201 | rumor.id = getEventHash(rumor) 202 | 203 | return rumor as Rumor 204 | } 205 | 206 | const createSeal = (rumor: Rumor, privateKey: Uint8Array, recipientPublicKey: string) => { 207 | return finalizeEvent( 208 | { 209 | kind: 13, 210 | content: nip44Encrypt(rumor, privateKey, recipientPublicKey), 211 | created_at: randomNow(), 212 | tags: [], 213 | }, 214 | privateKey 215 | ) as Event 216 | } 217 | 218 | const createWrap = (event: Event, recipientPublicKey: string) => { 219 | const randomKey = generateSecretKey() 220 | 221 | return finalizeEvent( 222 | { 223 | kind: 1059, 224 | content: nip44Encrypt(event, randomKey, recipientPublicKey), 225 | created_at: randomNow(), 226 | tags: [["p", recipientPublicKey]], 227 | }, 228 | randomKey 229 | ) as Event 230 | } 231 | 232 | // Test case using the above example 233 | const senderPrivateKey = nip19.decode(`nsec1p0ht6p3wepe47sjrgesyn4m50m6avk2waqudu9rl324cg2c4ufesyp6rdg`).data 234 | const recipientPrivateKey = nip19.decode(`nsec1uyyrnx7cgfp40fcskcr2urqnzekc20fj0er6de0q8qvhx34ahazsvs9p36`).data 235 | const recipientPublicKey = getPublicKey(recipientPrivateKey) 236 | 237 | const rumor = createRumor( 238 | { 239 | kind: 1, 240 | content: "Are you going to the party tonight?", 241 | }, 242 | senderPrivateKey 243 | ) 244 | 245 | const seal = createSeal(rumor, senderPrivateKey, recipientPublicKey) 246 | const wrap = createWrap(seal, recipientPublicKey) 247 | 248 | // Recipient unwraps with his/her private key. 249 | 250 | const unwrappedSeal = nip44Decrypt(wrap, recipientPrivateKey) 251 | const unsealedRumor = nip44Decrypt(unwrappedSeal, recipientPrivateKey) 252 | ``` 253 | --------------------------------------------------------------------------------