From 5c20921c06146516a367913e20b7540b139f7537 Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Thu, 23 Oct 2025 16:56:32 -0400 Subject: [PATCH] Document comment tagging requirements --- ...nced_Video_Comment_System_Specification.md | 45 ++++++++++++------- 1 file changed, 30 insertions(+), 15 deletions(-) diff --git a/content/roadmap/06_bitvid_Enhanced_Video_Comment_System_Specification.md b/content/roadmap/06_bitvid_Enhanced_Video_Comment_System_Specification.md index ffac7dd5..0e6cd22f 100644 --- a/content/roadmap/06_bitvid_Enhanced_Video_Comment_System_Specification.md +++ b/content/roadmap/06_bitvid_Enhanced_Video_Comment_System_Specification.md @@ -40,15 +40,18 @@ To implement a decentralized comment system for videos shared on a Nostr-based p Each component (comments, reactions, live chat) is represented as a Nostr event. ##### **Comment Event**: +bitvid uses standard kind `1` text note replies so they interoperate with the moderation flows documented in [`docs/moderation/nips.md`](../../docs/moderation/nips.md). Each reply keeps both the video event ID and the root video definition tag so downstream services can resolve lineage. + ```json { - "kind": 1311, + "kind": 1, "pubkey": "abcdef1234567890...", "created_at": 1675000000, "tags": [ - ["e", "video-event-id"], // Reference to the video - ["e", "parent-comment-id"], // Reference to the parent comment (optional, for replies) - ["p", "commenter-pubkey"] // Optional: commenter pubkey + ["e", "video-event-id"], // Reference to the specific video event + ["a", "30078:video-author-pubkey:video-root-id"], // Reference to the video definition (kind 30078) + ["e", "parent-comment-id"], // Optional: reference to the parent comment for replies + ["p", "commenter-pubkey"] // Optional: commenter or video author pubkey for threading UX ], "content": "This is a great video!" } @@ -86,13 +89,14 @@ Each component (comments, reactions, live chat) is represented as a Nostr event. Metadata tags are added to comments or live chat events as needed: ```json { - "kind": 1311, + "kind": 1, "pubkey": "abcdef1234567890...", "created_at": 1675000000, "tags": [ ["e", "video-event-id"], + ["a", "30078:video-author-pubkey:video-root-id"], ["m", "featured-comment"], // Example metadata tag - ["a", "admin-tag"] // Administrative tag + ["m", "admin-tag"] // Administrative tag ], "content": "Highlighted comment for this video." } @@ -104,19 +108,24 @@ Metadata tags are added to comments or live chat events as needed: #### **1. Posting a Comment** To post a comment: -1. The client constructs a comment event using NIP-22 for `created_at` validation. -2. The event includes references to the video (mandatory) and parent comments (optional). +1. The client constructs a kind `1` comment event using NIP-22 for `created_at` validation. +2. The event includes both the `['e', ]` and `['a', <30078:pubkey:videoRootId>]` tags (mandatory) plus parent comment references when replying. This mirrors the implementation in `js/services/discussionCountService.js` so reply counts and moderation filters remain aligned. 3. The event is signed and published to relays. ##### API Example: ```javascript -async function postComment(videoId, commentText, parentCommentId = null) { +async function postComment( + { videoEventId, videoAuthorPubkey, videoRootId }, + commentText, + parentCommentId = null +) { const event = { - kind: 1311, + kind: 1, pubkey: userPubkey, created_at: Math.floor(Date.now() / 1000), tags: [ - ['e', videoId], + ['e', videoEventId], + ['a', `30078:${videoAuthorPubkey}:${videoRootId}`], ...(parentCommentId ? [['e', parentCommentId]] : []), ], content: commentText @@ -151,10 +160,11 @@ Comments are retrieved using `REQ` messages filtered by the `e` tag for the vide ##### API Example: ```javascript -async function fetchComments(videoId) { +async function fetchComments({ videoEventId, videoAuthorPubkey, videoRootId }) { const filter = { - kinds: [1311], - '#e': [videoId], + kinds: [1], + '#e': [videoEventId], + '#a': [`30078:${videoAuthorPubkey}:${videoRootId}`], limit: 100 }; @@ -192,7 +202,7 @@ Use NIP-24 to attach metadata to events for administrative or user-specific tags - User creates a comment event. - Client signs and publishes the event to relays. 2. **Fetching Comments**: - - Client requests comments for a video by filtering events with the `e` tag. + - Client requests comments for a video by filtering events with the combined `#e` and `#a` tags so both the specific video event and its root definition are represented. 3. **Reacting to Comments**: - Users react to comments by posting reaction events. 4. **Live Discussions**: @@ -200,6 +210,8 @@ Use NIP-24 to attach metadata to events for administrative or user-specific tags 5. **Metadata Management**: - Metadata is attached during event creation or editing. +> **Tagging Requirement:** Clients must keep the combined `#e`/`#a` tagging pattern shown above. `discussionCountService.buildDiscussionCountFilters` depends on those tags when querying relays so UI components can surface accurate comment totals. + --- ### **UI/UX Considerations** @@ -220,6 +232,9 @@ Use NIP-24 to attach metadata to events for administrative or user-specific tags 4. **Nested Threading**: - Indent replies to show comment hierarchy. +5. **Comment Gate**: + - UI components such as `VideoCard.buildDiscussionCount` already hide comment affordances when `enableComments` is false. Future enhancements must honor the same feature flag so comment entry points remain consistent with existing gating. + --- ### **Testing and Validation**