From 8b158e92279c08af812307ed7294378ddb8abbdd Mon Sep 17 00:00:00 2001 From: arthurfranca Date: Tue, 21 Mar 2023 15:24:05 -0300 Subject: Add alternative mention handling NIP --- 27.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 27.md (limited to '27.md') diff --git a/27.md b/27.md new file mode 100644 index 0000000..b2d1e5a --- /dev/null +++ b/27.md @@ -0,0 +1,17 @@ +NIP-27 +====== + +Handling Mentions +----------------- + +`draft` `optional` `author:fiatjaf` `author:scsibug` `author:arthurfranca` + +This document standardizes the treatment given by clients of inline mentions of other events and pubkeys inside the content of `text_note`s. + +Clients that want to allow inline mentions they MUST show an autocomplete component or something analogous to that whenever the user starts typing a special key (for example, "@") or presses some button to include a mention etc -- or these clients can come up with other ways to unambiguously differentiate between mentions and normal text. + +Once a mention is identified, for example, the pubkey `27866e9d854c78ae625b867eefdfa9580434bc3e675be08d2acb526610d96fbe`, the client MUST replace its textual reference (inside `.content`) with the notation `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg` as per NIP-21. If client doesn't support NIP-21, it can instead use a regular http link to a nostr client such as `https://snort.social/p/nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`. The client MAY add that pubkey to the `.tags` with the tag `p` if it wishes to notify mentioned user. + +The same process applies for mentioning event IDs, except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading. + +A client that receives a `text_note` event with such `nostr:...` mentions in its `.content` CAN do any desired context augmentation (for example, linking to the pubkey or showing a preview of the mentioned event contents) it wants in the process. -- cgit v1.2.3 From a32ec25ecb5cb13754e435db01ef6bf2a749769c Mon Sep 17 00:00:00 2001 From: arthurfranca Date: Wed, 22 Mar 2023 10:13:04 -0300 Subject: Make it clear why e tags are discouraged --- 27.md | 11 ++++++----- README.md | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) (limited to '27.md') diff --git a/27.md b/27.md index b2d1e5a..237feaa 100644 --- a/27.md +++ b/27.md @@ -1,17 +1,18 @@ NIP-27 ====== -Handling Mentions ------------------ +Text Note References +-------------------- `draft` `optional` `author:fiatjaf` `author:scsibug` `author:arthurfranca` -This document standardizes the treatment given by clients of inline mentions of other events and pubkeys inside the content of `text_note`s. +This document standardizes the treatment given by clients of inline references of other events and pubkeys inside the content of `text notes` (currently kinds 1 and 30023). -Clients that want to allow inline mentions they MUST show an autocomplete component or something analogous to that whenever the user starts typing a special key (for example, "@") or presses some button to include a mention etc -- or these clients can come up with other ways to unambiguously differentiate between mentions and normal text. +Clients that want to allow inline mentions of profiles MUST show an autocomplete component or something analogous to that whenever the user starts typing a special key (for example, "@") or presses some button to include a mention etc -- or these clients can come up with other ways to unambiguously differentiate between mentions and normal text. Once a mention is identified, for example, the pubkey `27866e9d854c78ae625b867eefdfa9580434bc3e675be08d2acb526610d96fbe`, the client MUST replace its textual reference (inside `.content`) with the notation `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg` as per NIP-21. If client doesn't support NIP-21, it can instead use a regular http link to a nostr client such as `https://snort.social/p/nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`. The client MAY add that pubkey to the `.tags` with the tag `p` if it wishes to notify mentioned user. -The same process applies for mentioning event IDs, except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading. +The same process applies for referencing event IDs, except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading. +Because `e` tags on `text notes` are usually considered ancestor events used to build a conversarion thread (as per NIP-10), it is advised to use inline references when mentioning events and NOT adding corresponding `e` tag to the `.tags` event key. A client that receives a `text_note` event with such `nostr:...` mentions in its `.content` CAN do any desired context augmentation (for example, linking to the pubkey or showing a preview of the mentioned event contents) it wants in the process. diff --git a/README.md b/README.md index d93f5c2..6642e92 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh - [NIP-23: Long-form Content](23.md) - [NIP-25: Reactions](25.md) - [NIP-26: Delegated Event Signing](26.md) -- [NIP-27: Handling Mentions](27.md) +- [NIP-27: Text Note References](27.md) - [NIP-28: Public Chat](28.md) - [NIP-33: Parameterized Replaceable Events](33.md) - [NIP-36: Sensitive Content](36.md) -- cgit v1.2.3 From 61a158caec1f8cfb3ffa98792640f0df807f35a8 Mon Sep 17 00:00:00 2001 From: arthurfranca Date: Wed, 22 Mar 2023 19:48:07 -0300 Subject: Replace specific client url --- 27.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to '27.md') diff --git a/27.md b/27.md index 237feaa..26e29af 100644 --- a/27.md +++ b/27.md @@ -10,7 +10,7 @@ This document standardizes the treatment given by clients of inline references o Clients that want to allow inline mentions of profiles MUST show an autocomplete component or something analogous to that whenever the user starts typing a special key (for example, "@") or presses some button to include a mention etc -- or these clients can come up with other ways to unambiguously differentiate between mentions and normal text. -Once a mention is identified, for example, the pubkey `27866e9d854c78ae625b867eefdfa9580434bc3e675be08d2acb526610d96fbe`, the client MUST replace its textual reference (inside `.content`) with the notation `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg` as per NIP-21. If client doesn't support NIP-21, it can instead use a regular http link to a nostr client such as `https://snort.social/p/nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`. The client MAY add that pubkey to the `.tags` with the tag `p` if it wishes to notify mentioned user. +Once a mention is identified, for example, the pubkey `27866e9d854c78ae625b867eefdfa9580434bc3e675be08d2acb526610d96fbe`, the client MUST replace its textual reference (inside `.content`) with the notation `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg` as per NIP-21. If client doesn't support NIP-21, it can instead use a regular http link to a nostr client such as `https://a-nostr-client.com/nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`. The client MAY add that pubkey to the `.tags` with the tag `p` if it wishes to notify mentioned user. The same process applies for referencing event IDs, except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading. Because `e` tags on `text notes` are usually considered ancestor events used to build a conversarion thread (as per NIP-10), it is advised to use inline references when mentioning events and NOT adding corresponding `e` tag to the `.tags` event key. -- cgit v1.2.3 From 2b926f54cdc6eb779de27510b1be20336c933ef9 Mon Sep 17 00:00:00 2001 From: arthurfranca Date: Thu, 23 Mar 2023 10:11:18 -0300 Subject: Improve the text --- 27.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to '27.md') diff --git a/27.md b/27.md index 26e29af..235b4a5 100644 --- a/27.md +++ b/27.md @@ -6,13 +6,13 @@ Text Note References `draft` `optional` `author:fiatjaf` `author:scsibug` `author:arthurfranca` -This document standardizes the treatment given by clients of inline references of other events and pubkeys inside the content of `text notes` (currently kinds 1 and 30023). +This document standardizes the treatment given by clients of inline references of other events and profiles inside the content of `text notes` (currently kinds 1 and 30023). -Clients that want to allow inline mentions of profiles MUST show an autocomplete component or something analogous to that whenever the user starts typing a special key (for example, "@") or presses some button to include a mention etc -- or these clients can come up with other ways to unambiguously differentiate between mentions and normal text. +Once a mention is identified by a client, for example, when an user pastes a NIP-19 nostr profile string inside the event content input field (or optionally by any other means the client may wish to support, such as selecting an user from a context menu or autocompleter), the client MUST replace it with the notation `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg` as per NIP-21 before effectively creating the event. The client MAY add the corresponding pubkey to the `.tags` with the tag `p` if it wishes to notify mentioned user. -Once a mention is identified, for example, the pubkey `27866e9d854c78ae625b867eefdfa9580434bc3e675be08d2acb526610d96fbe`, the client MUST replace its textual reference (inside `.content`) with the notation `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg` as per NIP-21. If client doesn't support NIP-21, it can instead use a regular http link to a nostr client such as `https://a-nostr-client.com/nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`. The client MAY add that pubkey to the `.tags` with the tag `p` if it wishes to notify mentioned user. - -The same process applies for referencing event IDs, except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading. +The same process applies for referencing event IDs (using `nostr:nevent1...`), except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading. Because `e` tags on `text notes` are usually considered ancestor events used to build a conversarion thread (as per NIP-10), it is advised to use inline references when mentioning events and NOT adding corresponding `e` tag to the `.tags` event key. -A client that receives a `text_note` event with such `nostr:...` mentions in its `.content` CAN do any desired context augmentation (for example, linking to the pubkey or showing a preview of the mentioned event contents) it wants in the process. +Note that the usage of `nostr:npub1...` for profile mentions or `nostr:note1...` for event mentions is discouraged due to their lack of embedded relay recommendation. + +A reader client that receives a `text_note` 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 links or direct links to web clients that will handle these references. -- cgit v1.2.3 From 45b1860b52025182d6400fd804a5d376a183ee40 Mon Sep 17 00:00:00 2001 From: arthurfranca Date: Thu, 23 Mar 2023 19:37:10 -0300 Subject: Mention other nostr identifiers --- 27.md | 2 ++ 1 file changed, 2 insertions(+) (limited to '27.md') diff --git a/27.md b/27.md index 235b4a5..f4e4629 100644 --- a/27.md +++ b/27.md @@ -13,6 +13,8 @@ Once a mention is identified by a client, for example, when an user pastes a NIP The same process applies for referencing event IDs (using `nostr:nevent1...`), except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading. Because `e` tags on `text notes` are usually considered ancestor events used to build a conversarion thread (as per NIP-10), it is advised to use inline references when mentioning events and NOT adding corresponding `e` tag to the `.tags` event key. +Other nostr identifiers should be referenced similarly using NIP-21 URLs inside event content (e.g. `nostr:naddr1...` for parameterized replaceable events). + Note that the usage of `nostr:npub1...` for profile mentions or `nostr:note1...` for event mentions is discouraged due to their lack of embedded relay recommendation. A reader client that receives a `text_note` 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 links or direct links to web clients that will handle these references. -- cgit v1.2.3 From 9b575b151467b9eba055585820a4fa56822c6d64 Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Sat, 25 Mar 2023 21:59:01 -0300 Subject: refactor NIP-27 for simplicity -- but also include very verbose considerations and an example. --- 08.md | 2 +- 27.md | 50 ++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 43 insertions(+), 9 deletions(-) (limited to '27.md') diff --git a/08.md b/08.md index 2ab2b8f..fb87b53 100644 --- a/08.md +++ b/08.md @@ -6,7 +6,7 @@ NIP-08 Handling Mentions ----------------- -`final` `optional` `author:fiatjaf` `author:scsibug` +`final` `unrecommended` `optional` `author:fiatjaf` `author:scsibug` This document standardizes the treatment given by clients of inline mentions of other events and pubkeys inside the content of `text_note`s. diff --git a/27.md b/27.md index f4e4629..e78058a 100644 --- a/27.md +++ b/27.md @@ -4,17 +4,51 @@ NIP-27 Text Note References -------------------- -`draft` `optional` `author:fiatjaf` `author:scsibug` `author:arthurfranca` +`draft` `optional` `author:arthurfranca` `author:hodlbod` `author:fiatjaf` -This document standardizes the treatment given by clients of inline references of other events and profiles inside the content of `text notes` (currently kinds 1 and 30023). +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). -Once a mention is identified by a client, for example, when an user pastes a NIP-19 nostr profile string inside the event content input field (or optionally by any other means the client may wish to support, such as selecting an user from a context menu or autocompleter), the client MUST replace it with the notation `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg` as per NIP-21 before effectively creating the event. The client MAY add the corresponding pubkey to the `.tags` with the tag `p` if it wishes to notify mentioned user. +When creating an event, clients should include mentions to other profiles and to other events in the middle of the `.content` using NIP-21 codes, such as `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`. -The same process applies for referencing event IDs (using `nostr:nevent1...`), except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading. -Because `e` tags on `text notes` are usually considered ancestor events used to build a conversarion thread (as per NIP-10), it is advised to use inline references when mentioning events and NOT adding corresponding `e` tag to the `.tags` event key. +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. -Other nostr identifiers should be referenced similarly using NIP-21 URLs inside event content (e.g. `nostr:naddr1...` for parameterized replaceable events). +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 links or direct links to web clients that will handle these references. -Note that the usage of `nostr:npub1...` for profile mentions or `nostr:note1...` for event mentions is discouraged due to their lack of embedded relay recommendation. +--- -A reader client that receives a `text_note` 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 links or direct links to web clients that will handle these references. +## Example of a profile mention process + +Suppose a Bob is writing a note in a client that has search-and-autocomplete functionality for users that is triggered when they write the character `@`. + +As Bob types `"hello @mat"` the client will prompt him to autocomplete with [mattn's profile](https://gateway.nostr.com/p/2c7cc62a697ea3a7826521f3fd34f0cb273693cbe5e9310f35449f43622a5cdc), showing a picture and name. + +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: + +```json +{ + "content": "hello nostr:nprofile1qqszclxx9f5haga8sfjjrulaxncvkfekj097t6f3pu65f86rvg49ehqj6f9dh", + "created_at": 1679790774, + "id": "f39e9b451a73d62abc5016cffdd294b1a904e2f34536a208874fe5e22bbd47cf", + "kind": 1, + "pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798", + "sig": "f8c8bab1b90cc3d2ae1ad999e6af8af449ad8bb4edf64807386493163e29162b5852a796a8f474d6b1001cddbaac0de4392838574f5366f03cc94cf5dfb43f4d", + "tags": [ + [ + "e", + "2c7cc62a697ea3a7826521f3fd34f0cb273693cbe5e9310f35449f43622a5cdc" + ] + ] +} +``` + +(Alternatively, the mention could have been a `nostr:npub1...` URL.) + +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. + +## Verbose and probably unnecessary considerations + +- 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. +- 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. +- 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. +- 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. +- 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. -- cgit v1.2.3 From 133faa07636fff9f8e91c69cb9e3a5cce459b241 Mon Sep 17 00:00:00 2001 From: arthurfranca Date: Sun, 26 Mar 2023 14:48:54 -0300 Subject: Fix typo in NIP-27 --- 27.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to '27.md') diff --git a/27.md b/27.md index e78058a..028ee5e 100644 --- a/27.md +++ b/27.md @@ -18,7 +18,7 @@ A reader client that receives an event with such `nostr:...` mentions in its `.c ## Example of a profile mention process -Suppose a Bob is writing a note in a client that has search-and-autocomplete functionality for users that is triggered when they write the character `@`. +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 `@`. As Bob types `"hello @mat"` the client will prompt him to autocomplete with [mattn's profile](https://gateway.nostr.com/p/2c7cc62a697ea3a7826521f3fd34f0cb273693cbe5e9310f35449f43622a5cdc), showing a picture and name. @@ -34,7 +34,7 @@ Bob presses "enter" and now he sees his typed note as `"hello @mattn"`, `@mattn` "sig": "f8c8bab1b90cc3d2ae1ad999e6af8af449ad8bb4edf64807386493163e29162b5852a796a8f474d6b1001cddbaac0de4392838574f5366f03cc94cf5dfb43f4d", "tags": [ [ - "e", + "p", "2c7cc62a697ea3a7826521f3fd34f0cb273693cbe5e9310f35449f43622a5cdc" ] ] -- cgit v1.2.3 From 9d1d701285b7f6051160e8cd6890f8fe5239be70 Mon Sep 17 00:00:00 2001 From: Martin Dutra Date: Mon, 10 Apr 2023 23:40:06 -0300 Subject: Add links to NIP-21 --- 27.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to '27.md') diff --git a/27.md b/27.md index 028ee5e..6d76120 100644 --- a/27.md +++ b/27.md @@ -8,11 +8,11 @@ Text Note References 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). -When creating an event, clients should include mentions to other profiles and to other events in the middle of the `.content` using NIP-21 codes, such as `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg`. +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`. 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. -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 links or direct links to web clients that will handle these references. +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. --- -- cgit v1.2.3