nips/10.md

65 lines
3.2 KiB
Markdown
Raw Normal View History

2022-05-04 16:14:49 -04:00
NIP-10
======
On "e" and "p" tags in Text Events (kind 1)
-------------------------------------------
2023-11-15 19:42:51 -05:00
`draft` `optional`
2022-05-24 19:07:09 -04:00
## Abstract
This NIP describes how to use "e" and "p" tags in text events, especially those that are replies to other text events. It helps clients thread the replies into a tree rooted at the original event.
2022-05-04 13:00:51 -04:00
## Positional "e" tags (DEPRECATED)
2022-05-24 19:07:09 -04:00
>This scheme is in common use; but should be considered deprecated.
2022-05-04 13:00:51 -04:00
2022-09-02 16:07:50 -04:00
`["e", <event-id>, <relay-url>]` as per NIP-01.
2022-05-04 13:00:51 -04:00
2022-05-24 19:07:09 -04:00
Where:
2022-05-04 13:00:51 -04:00
2022-05-24 19:07:09 -04:00
* `<event-id>` is the id of the event being referenced.
* `<relay-url>` is the URL of a recommended relay associated with the reference. Many clients treat this field as optional.
2023-08-17 07:17:24 -04:00
2022-05-24 19:07:09 -04:00
**The positions of the "e" tags within the event denote specific meanings as follows**:
2022-05-04 13:00:51 -04:00
2022-05-24 19:07:09 -04:00
* No "e" tag: <br>
This event is not a reply to, nor does it refer to, any other event.
2022-05-04 13:00:51 -04:00
2022-05-24 19:07:09 -04:00
* One "e" tag: <br>
2022-09-02 16:07:50 -04:00
`["e", <id>]`: The id of the event to which this event is a reply.
2022-05-04 13:00:51 -04:00
2022-09-02 16:07:50 -04:00
* Two "e" tags: `["e", <root-id>]`, `["e", <reply-id>]` <br>
2023-08-17 07:17:24 -04:00
`<root-id>` is the id of the event at the root of the reply chain. `<reply-id>` is the id of the article to which this event is a reply.
2022-05-24 19:07:09 -04:00
2022-09-02 16:07:50 -04:00
* Many "e" tags: `["e", <root-id>]` `["e", <mention-id>]`, ..., `["e", <reply-id>]`<br>
2023-08-17 07:17:24 -04:00
There may be any number of `<mention-ids>`. These are the ids of events which may, or may not be in the reply chain.
2023-12-04 03:07:45 -05:00
They are citing from this event. `root-id` and `reply-id` are as above.
2022-05-04 13:00:51 -04:00
2022-05-24 19:07:09 -04:00
>This scheme is deprecated because it creates ambiguities that are difficult, or impossible to resolve when an event references another but is not a reply.
## Marked "e" tags (PREFERRED)
2024-04-12 05:50:47 -04:00
`["e", <event-id>, <relay-url>, <marker>, <pubkey>]`
2023-08-17 07:17:24 -04:00
2022-05-24 19:07:09 -04:00
Where:
* `<event-id>` is the id of the event being referenced.
2024-09-10 16:07:36 -04:00
* `<relay-url>` is the URL of a recommended relay associated with the reference. Clients SHOULD add a valid `<relay-url>` field, but may instead leave it as `""`.
2023-02-23 14:20:10 -05:00
* `<marker>` is optional and if present is one of `"reply"`, `"root"`, or `"mention"`.
2024-04-12 05:50:47 -04:00
* `<pubkey>` is optional, SHOULD be the pubkey of the author of the referenced event
2022-05-24 19:07:09 -04:00
2024-11-18 09:41:28 -05:00
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 non-root/parent event id in the reply chain, *not* a quote.
2022-05-24 19:07:09 -04:00
2022-12-29 05:40:58 -05:00
A direct reply to the root of a thread should have a single marked "e" tag of type "root".
2023-08-17 07:17:24 -04:00
>This scheme is preferred because it allows events to mention others without confusing them with `<reply-id>` or `<root-id>`.
2022-05-24 19:07:09 -04:00
2024-04-12 05:50:47 -04:00
`<pubkey>` 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.
2022-05-24 19:07:09 -04:00
## The "p" tag
2022-05-04 13:00:51 -04:00
Used in a text event contains a list of pubkeys used to record who is involved in a reply thread.
2023-08-17 07:17:24 -04:00
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.
2022-05-04 13:00:51 -04:00
2023-08-17 07:17:24 -04:00
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`]
2022-05-04 13:08:19 -04:00
in no particular order.