bitvid/docs/relay-trust-bootstrap.md

Relay trust bootstrap

This document describes how js/services/trustBootstrap.js seeds trusted relays/actors for moderation, how it waits for relay availability, and how the relay list and admin lists are refreshed.

Overview

bootstrapTrustedSeeds() is a lightweight bootstrapping step that:

1. Waits briefly for admin list hydration and relay readiness.
2. Builds a trusted seed set from admin configuration and defaults.
3. Hands that trusted seed set to moderationService so trusted reports, mutes, and summary stats are computed consistently.
4. Re-runs when admin/editor lists change.

Configuration inputs

Trusted seed inputs are pulled from configuration and feature flags:

• FEATURE_TRUST_SEEDS (flag in js/constants.js): gates whether bootstrapping runs at all.
• ADMIN_SUPER_NPUB (from config/instance-config.js via js/config.js): always included when set.
• accessControl.getEditors() (from js/accessControl.js): editor list sourced from admin lists or defaults.
• DEFAULT_TRUST_SEED_NPUBS (from config/instance-config.js via js/constants.js): used only if there are no super/admin seeds.

Seed selection and trust computation

buildTrustedSeeds() composes a Set of Nostr npub identifiers in this order:

1. Add the super admin (ADMIN_SUPER_NPUB).
2. Add editor npubs (accessControl.getEditors()).
3. If no seeds exist yet, fall back to DEFAULT_TRUST_SEED_NPUBS.

The resulting Set is passed to moderationService.setTrustedSeeds(seeds). moderationService uses these seeds as the baseline for trusted contacts and downstream trust calculations (trusted report counts, trusted mute lists, etc.), and recomputeAllSummaries() is called immediately after applying seeds so moderation views reflect the updated trust graph.

Relay readiness and fallback behavior

Bootstrapping is intentionally defensive so the UI can initialize quickly:

• Access control hydration: waitForAccessControl() races accessControl.ensureReady() against a 3.5s timeout. If hydration times out, bootstrapping logs a dev warning and falls back to defaults.
• Immediate apply: Seeds are applied immediately after the first hydration attempt, even if the admin list hydration failed, so moderation does not block on relay availability.
• Retry when relays are ready: If hydration failed, bootstrapTrustedSeeds() checks for relay readiness via nostrService.nostrClient.relays (and pool existence). If relays become available within 3.5s, it retries admin list hydration once. If relays never become ready, it logs a dev warning and re-applies the current seeds to keep moderation functional.
• Change listeners: accessControl.onWhitelistChange() and accessControl.onEditorsChange() are registered so any subsequent admin/editor updates re-run seed application and recompute moderation summaries.

Relay list persistence and refresh

trustBootstrap does not persist or update relay lists itself. Instead it relies on the shared Nostr client state maintained by the relay manager and access control:

• Relay list loading: js/relayManager.js loads a profile’s relay list from NIP-65 (kind 10002) events, normalizes relay URLs, and falls back to DEFAULT_RELAY_URLS if nothing is found or the pool is unavailable. The relay manager updates the active nostrClient relay list in memory via nostrClient.applyRelayPreferences() (or by assigning to nostrClient.relays).
• Relay list refresh: Relay list changes are published to relays via relayManager.publishRelayList() and reloaded during profile refresh flows, which updates nostrClient.relays that trustBootstrap later observes.
• Admin list persistence: js/accessControl.js hydrates admin/editor lists from cached state in js/adminListStore.js (local storage). It then refreshes from relay-backed admin lists when ensureReady() is called. The cache ensures bootstrapTrustedSeeds() can use stored admin lists before relays are available.

Data flow summary

config/instance-config.js
  └─> js/config.js -> js/constants.js (FEATURE_TRUST_SEEDS, DEFAULT_TRUST_SEED_NPUBS)
                         └─> js/services/trustBootstrap.js
                                ├─> accessControl.ensureReady() (admin lists + cache)
                                ├─> nostrService.nostrClient.relays (relay readiness)
                                └─> moderationService.setTrustedSeeds() + recomputeAllSummaries()

When the relay list or admin lists change, accessControl refreshes from cache/relays and the trust bootstrapper re-applies seeds so moderation stays up to date.