bitvid/docs/nostr-client-overview.md

NostrClient Overview

NostrClient (js/nostr/client.js) is the central controller for all Nostr network interactions and state management in the application. It acts as a facade over nostr-tools, managing connections to multiple relays, signing events, and maintaining the local application state.

Responsibilities

1. Connection Management: Maintains a pool of connections to configured Nostr relays. It handles initialization, reconnection, and error logging.
2. Event Publishing: Handles the creation, signing, and broadcasting of various Nostr event kinds (Video Post: 30078, Reaction: 7, Comment: 1, etc.). It supports NIP-07 (Extension), NIP-46 (Remote/Bunker), and NIP-01 (Local nsec) signers.
3. State Management:
   • allEvents: A raw map of all fetched video events (Kind 30078), preserving history.
   • activeMap: A derived map containing only the latest version of each video, deduplicated by videoRootId or d tag. This is the source of truth for the UI.
   • rawEvents: A cache of the exact raw JSON events from relays, used for signature verification and republishing.
   • tombstones: Tracks deletion timestamps to prevent deleted events from reappearing.
4. Caching: Implements a dual-layer cache (IndexedDB + localStorage) to persist activeMap, allEvents, and tombstones. This allows the app to restore its state instantly on load ("stale-while-revalidate").
5. Video Lifecycle: Manages the full lifecycle of a video post: Publish -> Edit (new event with same d tag) -> Revert (new event, same d, deleted flag) -> Delete (Kind 5).

Key Concepts

Active Video Logic

Nostr is an append-only protocol. Edits are new events. NostrClient implements "latest-wins" logic to present a coherent view:

• Identifier: Videos are identified by a videoRootId (in the content) or a NIP-33 d tag.
• Resolution: When a new event arrives, the client checks if it's newer than the current active version in activeMap. If so, it replaces the entry.
• Deletions: If an event has deleted: true or is a Kind 5 deletion, it is removed from activeMap, and a tombstone is recorded.

Buffering & Debouncing

To handle high volumes of events (e.g., during initial relay dump), subscribeVideos uses a buffering strategy:

1. Incoming events are pushed to eventBuffer.
2. A flush is scheduled with a short debounce (e.g., 75ms).
3. On flush, the batch is processed: validation, state updates, and UI notification. This prevents UI thrashing.

Tombstones

Because relays are eventually consistent, a deleted event might arrive after a deletion command.

• tombstones map activeKey -> timestamp.
• If an incoming event is older than the tombstone for its key, it is ignored (applyTombstoneGuard).

Example Flow: subscribeVideos

sequenceDiagram
    participant UI
    participant Client as NostrClient
    participant Buffer as EventBuffer
    participant State as activeMap
    participant Relays

    UI->>Client: subscribeVideos(onVideo)
    Client->>Relays: REQ Kind 30078
    Relays-->>Client: EVENT (Video A, v1)
    Client->>Buffer: Push Event
    Client->>Buffer: Schedule Flush (75ms)
    Relays-->>Client: EVENT (Video B, v1)
    Client->>Buffer: Push Event

    Note over Client, Buffer: 75ms passes...

    Client->>Buffer: Flush()
    loop For each event
        Buffer->>State: Is newer?
        alt Yes
            State->>State: Update Entry
            State->>UI: onVideo(Video)
        else No
            State->>State: Ignore
        end
    end

When to Modify

• Adding a new Event Kind: If the app needs to support a new type of interaction (e.g., playlists), add the handling logic here and in js/nostrEventSchemas.js.
• Changing Caching Strategy: Modify EventsCacheStore or persistLocalData if the caching requirements change.
• Updating Signing Logic: Changes to NIP-07 or NIP-46 integration should be carefully reviewed here.

Related Files

• js/nostrEventSchemas.js: Definitions of event structures.
• js/nostr/nip71.js: Helper logic for video categorization (NIP-71).
• js/nostr/watchHistory.js: Manages user watch history state.