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

Merge branch 'master' into zap-plits

Browse Source
This commit is contained in:
Vitor Pamplona 2023-06-10 19:56:03 -04:00 committed by GitHub
commit 4d0929b278
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 150 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
01.md
View File

@ -99,7 +99,7 @@ This NIP defines no rules for how `NOTICE` messages should be sent or treated.
## Basic Event Kinds
- `0`: `set_metadata`: the `content` is set to a stringified JSON object `{name: <username>, about: <string>, picture: <url, string>}` describing the user who created the event. A relay may delete past `set_metadata` events once it gets a new one for the same pubkey.
- `1`: `text_note`: the `content` is set to the plaintext content of a note (anything the user wants to say). Do not use Markdown! Clients should not have to guess how to interpret content like `[]()`. Use different event kinds for parsable content.
- `1`: `text_note`: the `content` is set to the **plaintext** content of a note (anything the user wants to say). Content that must be parsed, such as Markdown and HTML, should not be used. Clients should also not parse content as those.
- `2`: `recommend_server`: the `content` is set to the URL (e.g., `wss://somerelay.com`) of a relay the event creator wants to recommend to its followers.
A relay may choose to treat different message kinds differently, and it may or may not choose to have a default way to handle kinds it doesn't know about.
@ -107,6 +107,6 @@ A relay may choose to treat different message kinds differently, and it may or m
## Other Notes:
- Clients should not open more than one websocket to each relay. One channel can support an unlimited number of subscriptions, so clients should do that.
- The `tags` array can store a tag identifier as the first element of each subarray, plus arbitrary information afterward (always as strings). This NIP defines `"p"` — meaning "pubkey", which points to a pubkey of someone that is referred to in the event —, and `"e"` — meaning "event", which points to the id of an event this event is quoting, replying to or referring to somehow. See [NIP-10](https://github.com/nostr-protocol/nips/blob/127d5518bfa9a4e4e7510490c0b8d95e342dfa4b/10.md) for a detailed description of "e" and "p" tags.
- The `tags` array can store a tag identifier as the first element of each subarray, plus arbitrary information afterward (always as strings). This NIP defines `"p"` — meaning "pubkey", which points to a pubkey of someone that is referred to in the event —, and `"e"` — meaning "event", which points to the id of an event this event is quoting, replying to or referring to somehow. See [NIP-10](10.md) for a detailed description of "e" and "p" tags.
- The `<recommended relay URL>` item present on the `"e"` and `"p"` tags is an optional (could be set to `""`) URL of a relay the client could attempt to connect to fetch the tagged event or other events from a tagged profile. It MAY be ignored, but it exists to increase censorship resistance and make the spread of relay addresses more seamless across clients.
- Clients should use the created_at field to judge the age of a metadata event and completely replace older metadata events with newer metadata events regardless of the order in which they arrive. Clients should not merge any filled fields within older metadata events into empty fields of newer metadata events.

3
07.md
View File

@ -26,9 +26,10 @@ async window.nostr.nip04.decrypt(pubkey, ciphertext): string // takes ciphertext
- [horse](https://github.com/fiatjaf/horse) (Chrome and derivatives)
- [nos2x](https://github.com/fiatjaf/nos2x) (Chrome and derivatives)
- [Alby](https://getalby.com) (Chrome and derivatives, Firefox, Safari)
- [Alby](https://getalby.com) (Chrome and derivatives, Firefox)
- [Blockcore](https://www.blockcore.net/wallet) (Chrome and derivatives)
- [nos2x-fox](https://diegogurpegui.com/nos2x-fox/) (Firefox)
- [Flamingo](https://www.getflamingo.org/) (Chrome and derivatives)
- [AKA Profiles](https://github.com/neilck/aka-extension) (Chrome, stores multiple keys)
- [TokenPocket](https://www.tokenpocket.pro/) (Android, IOS, Chrome and derivatives)
- [Nostrmo](https://github.com/haorendashu/nostrmo_faq#download) (Android, IOS)

2
09.md
View File

@ -20,7 +20,7 @@ For example:
"pubkey": <32-bytes hex-encoded public key of the event creator>,
"tags": [
["e", "dcd59..464a2"],
["e", "968c5..ad7a4"],
["e", "968c5..ad7a4"]
],
"content": "these posts were published by accident",
...other fields

2
16.md
View File

@ -20,6 +20,8 @@ Upon a replaceable event with a newer timestamp than the currently known latest
effectively replacing what gets returned when querying for
`author:kind` tuples.
If two events have the same timestamp, the event with the lowest id (first in lexical order) SHOULD be retained, and the other discarded.
Ephemeral Events
----------------
An *ephemeral event* is defined as an event with a kind `20000 <= n < 30000`.

6
26.md
View File

@ -52,7 +52,9 @@ For example, the following condition strings are valid:
- `kind=0&kind=1&created_at>1675721813`
- `kind=1&created_at>1674777689&created_at<1675721813`
For the vast majority of use-cases, it is advisable that 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.
For the vast majority of use-cases, it is advisable that:
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.
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.
#### Example
@ -105,4 +107,4 @@ Clients should display the delegated note as if it was published directly by the
Relays should answer requests such as `["REQ", "", {"authors": ["A"]}]` by querying both the `pubkey` and delegation tags `[1]` value.
Relays SHOULD allow the delegator (8e0d3d3e) to delete the events published by the delegatee (477318cf).
Relays SHOULD allow the delegator (8e0d3d3e) to delete the events published by the delegatee (477318cf).

15
31.md Normal file
View File

@ -0,0 +1,15 @@
NIP-31
======
Dealing with unknown event kinds
--------------------------------
`draft` `optional` `author:pablof7z` `author:fiatjaf`
When creating a new custom event kind that is part of a custom protocol and isn't meant to be read as text (like `kind:1`), clients should use an `alt` tag to write a short human-readable plaintext summary of what that event is about.
The intent is that social clients, used to display only `kind:1` notes, can still show something in case a custom event pops up in their timelines. The content of the `alt` tag should provide enough context for a user that doesn't know anything about this event kind to understand what it is.
These clients that only know `kind:1` are not expected to ask relays for events of different kinds, but users could still reference these weird events on their notes, and without proper context these could be nonsensical notes. Having the fallback text makes that situation much better -- even if only for making the user aware that they should try to view that custom event elsewhere.
`kind:1`-centric clients can make interacting with these event kinds more functional by supporting [NIP-89](https://github.com/nostr-protocol/nips/blob/master/89.md).

4
33.md
View File

@ -10,7 +10,7 @@ This NIP adds a new event range that allows for replacement of events that have
Implementation
--------------
The value of a tag is defined as the first parameter of a tag after the tag name.
The value of a tag can be any string and is defined as the first parameter of a tag after the tag name.
A *parameterized replaceable event* is defined as an event with a kind `30000 <= n < 40000`.
Upon a parameterized replaceable event with a newer timestamp than the currently known latest
@ -18,6 +18,8 @@ replaceable event with the same kind, author and first `d` tag value being recei
SHOULD be discarded, effectively replacing what gets returned when querying for
`author:kind:d-tag` tuples.
If two events have the same timestamp, the event with the lowest id (first in lexical order) SHOULD be retained, and the other discarded.
A missing or a `d` tag with no value should be interpreted equivalent to a `d` tag with the
value as an empty string. Events from the same author with any of the following `tags`
replace each other:

116
89.md Normal file
View File

@ -0,0 +1,116 @@
NIP-89
======
Recommended Application Handlers
--------------------------------
`draft` `optional` `author:pablof7z`
This NIP describes `kind:31989` and `kind:31990`: a way to discover applications that can handle unknown event-kinds.
## Rationale
Nostr's discoverability and transparent event interaction is one of its most interesting/novel mechanics.
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.
### Parties involved
There are three actors to this workflow:
* 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)
* Publishes `kind:31990`, detailing how apps should redirect to it
* user A, who recommends an app that handles a specific event kind
* Publishes `kind:31989`
* user B, who seeks a recommendation for an app that handles a specific event kind
* Queries for `kind:31989` and, based on results, queries for `kind:31990`
# Events
## Recommendation event
```json
{
"kind": 31989,
"pubkey": <recommender-user-pubkey>,
"tags": [
[ "d", <supported-event-kind> ],
[ "a", "31990:app1-pubkey:<d-identifier>", "wss://relay1", "ios" ],
[ "a", "31990:app2-pubkey:<d-identifier>", "wss://relay2", "web" ]
]
}
```
The `d` tag in `kind:31989` is the supported event kind this event is recommending.
Multiple `a` tags can appear on the same `kind:31989`.
The second value of the tag SHOULD be a relay hint.
The third value of the tag SHOULD be the platform where this recommendation might apply.
## Handler information
```json
{
"kind": 31990,
"pubkey": <pubkey>,
"content": "<optional-kind:0-style-metadata>",
"tags": [
[ "d", <random-id> ],
[ "k", <supported-event-kind> ],
[ "web", "https://..../a/<bech32>", "nevent" ],
[ "web", "https://..../p/<bech32>", "nprofile" ],
[ "web", "https://..../e/<bech32>" ],
[ "ios", ".../<bech32>" ]
]
}
```
* `content` is an optional `set_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.)
* `k` tags' value is the event kind that is supported by this `kind:31990`.
Using a `k` tag(s) (instead of having the kind onf the NIP-33 `d` tag) provides:
* 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.
* The same pubkey can have multiple events with different apps that handle the same event kind.
* `bech32` in a URL MUST be replaced by clients with the NIP-19-encoded entity that should be loaded by the application.
Multiple tags might be registered by the app, following NIP-19 nomenclature as the second value of the array.
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.
# User flow
A user A who uses a non-`kind:1`-centric nostr app could choose to announce/recommend a certain kind-handler application.
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).
The client MIGHT query for the user's and the user's follows handler.
# Example
## User A recommends a `kind:31337`-handler
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.
```json
{
"kind": 31989,
"tags": [
[ "d", "31337" ],
[ "a", "31990:1743058db7078661b94aaf4286429d97ee5257d14a86d6bfa54cb0482b876fb0:abcd", <relay-url>, "web" ]
]
}
```
## User B interacts with a `kind:31337`-handler
User B might see in their timeline an event referring to a `kind:31337` event
(e.g. a `kind:1` tagging a `kind:31337`).
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`:
`["REQ", <id>, '[{ "kinds": [31989], "#d": ["31337"], 'authors': [<user>, <users-contact-list>] }]']`
User B, who follows User A, sees that `kind:31989` event and fetches the `a`-tagged event for the app and handler information.
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.
## Alternative query bypassing `kind:31989`
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 to avoid directing users to malicious handlers.
`["REQ", <id>, '[{ "kinds": [31990], "#k": [<desired-event-kind>], 'authors': [...] }]']`

5
README.md
View File

@ -46,6 +46,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
- [NIP-27: Text Note References](27.md)
- [NIP-28: Public Chat](28.md)
- [NIP-30: Custom Emoji](30.md)
- [NIP-31: Dealing with Unknown Events](31.md)
- [NIP-33: Parameterized Replaceable Events](33.md)
- [NIP-36: Sensitive Content](36.md)
- [NIP-39: External Identities in Profiles](39.md)
@ -61,6 +62,7 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
- [NIP-58: Badges](58.md)
- [NIP-65: Relay List Metadata](65.md)
- [NIP-78: Application-specific data](78.md)
- [NIP-89: Recommended Application Handlers](89.md)
- [NIP-94: File Metadata](94.md)
## Event Kinds
@ -101,6 +103,8 @@ They exist to document what may be implemented by [Nostr](https://github.com/nos
| `30018` | Create or update a product | [15](15.md) |
| `30023` | Long-form Content | [23](23.md) |
| `30078` | Application-specific Data | [78](78.md) |
| `31989` | Handler recommendation | [89](89.md) |
| `31990` | Handler information | [89](89.md) |
### Event Kind Ranges
@ -143,6 +147,7 @@ When experimenting with kinds, keep in mind the classification introduced by [NI
| name | value | other parameters | NIP |
| ----------------- | ------------------------------------ | -------------------- | ------------------------ |
| `a` | coordinates to an event | relay URL | [33](33.md), [23](23.md) |
| `alt` | Alt tag | -- | [31](31.md) |
| `d` | identifier | -- | [33](33.md) |
| `e` | event id (hex) | relay URL, marker | [1](01.md), [10](10.md) |
| `g` | geohash | -- | [12](12.md) |