mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2026-10-27 07:52:24 +00:00
63 lines
4.6 KiB
Markdown
63 lines
4.6 KiB
Markdown
# 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.onEditorsChange()` and `accessControl.onBlacklistChange()` are registered so changes affecting the moderator roster or eligibility re-run seed application and recompute moderation summaries. Creator-whitelist changes do not affect trust seeds.
|
||
|
||
## 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.
|