nips/31.md

49 lines
2.8 KiB
Markdown
Raw Permalink Normal View History

NIP-31
======
Dealing with unknown event kinds
--------------------------------
2023-11-15 21:42:51 -03:00
`draft` `optional`
When faced with an event of an unknown or unsupported kind, clients still have to display _something_ to the user.
Besides indicating that the event kind is not supported and suggesting other clients to handle it (possibly using [NIP-89](89.md)) clients may try these two alternatives:
1. Display text generated from a hardcoded or dynamic template;
2. Display the value of the event's `alt` tag;
2023-06-08 22:27:00 +02:00
(Of course if both are unavailable then the client has to decide on something else, like displaying a generic error message or the raw JSON contents or something else.)
### Templates
Templates can be either hardcoded by application developers or downloaded at runtime (or downloaded at compile-time) from a trusted provider or from a library, anything.
They consist of a [Mustache](https://mustache.github.io/)-compatible template (with no loops or partials) that takes the following parameters:
- `kind`
- `created_at`
- `pubkey`
- `content`
- `tags`
In which each of these values corresponds to the attribute of the event with the same name, except for `tags`, which is treated as an object with key-value access given by the first two items of each tag (and in the case of multiple tags with the same key only one, presumably the first, should be used).
**For example,**
- a reasonable template for a `kind:1111` event (comment) would be: `{{content}}`
- a reasonable template for a `kind:14` event (direct message) would be: `encrypted message to {{tags.p}}`
- a reasonable template for a `kind:7` event (reaction) would be: `{{pubkey}} reacts to {{tags.e}} by {{tags.p}}{{#content}} with {{.}}{{/content}}`
- a reasonable template for a `kind:30617` event (repository announcement) would be: `git repository {{tags.name}}{{#tags.web}}hosted at {{.}}{{/tags.web}} by {{pubkey}}`
- a reasonable template for a `kind:10002` event (relay list) would be: `canonical relays list for {{pubkey}}`
- a reasonable template for a `kind:31922` event (calendar) would be: `{{tags.title}} happening at {{tags.start}}`
To be easily exchangeable and reusable, trusted providers that want to do it SHOULD serve these templates through HTTP at `https://<domain-name>/.well-known/nip31/<kind-number>`, returning just the raw text.
Clients MAY format `{{pubkey}}` into a clickable `nostr:npub1...` link, or print `created_at` as a human-friendly date instead of as a timestamp, or anything like that.
### `alt` tags
When creating a new custom event kind that is part of a custom protocol and isn't meant to be read as text, clients SHOULD write an `alt` tag to include a short human-readable plaintext summary of what that event is about.
This is recommended for a while, until clients and providers have been given enough time to update their templates, then clients should stop doing it.