Relay Manager (relays)

Back up, compare, sync, and migrate your Nostr events. The timeline manager includes local account/relay settings, a signature-verified archive, resumable fetching, range Coverage, and explicit missing-copy publication followed by history rechecking.

The app icon is stored in icon.svg, referenced by appweaver.icon in package metadata.

Fetch / Coverage / Sync design

The Fetch / Coverage / Sync design records the agreed Q&A decisions: NIP-77 first with ordinary paging fallback, incremental fetching with ten-second overlap, per-fetch range Coverage with ⋮ Refetch/Resume, non-expiring evidence and compare-before-sync. The approved follow-up makes Sync publish-only; Recheck history subsequently updates relay storage observations. Fallback page size defaults to 100 and is configurable per run. The implementation uses the existing nostr-tools root nip77 export (2.24.1 or later); no extra Negentropy dependency is needed. Specialized relay handling remains postponed.

Progress and exit criteria: implementation plan.

Timeline UI

Run /relays list. The command output contains the manager; it is not registered in the Widgets dock. Add an npub/hex public key, add relay URLs, and toggle read/write roles. + Account lets you select the authenticated browser account or a saved bunker connection (by its account owner's public key), or enter an npub manually. The account dropdown and its add button share a row, as do manual npub entry and its add button. + Account toggles the add-account section open/closed. Saved connections load automatically when the picker opens. Adding only copies the public key; it does not switch accounts, request event signing, or store bunker credentials. Changes save locally immediately. Event counts reflect the local archive; there is no sample-data or design-preview mode.

Account removal sits beside + Account and retains archived events. Account names use fetched kind-0 display_name, then name, then shortened npub. The identity line shows the npub without a fixed watch-only classification. Account form rows vertically center inputs and buttons, keeping the Open button at its normal height rather than stretching it to the dropdown height. Opening a selected account automatically starts background profile/NIP-65 discovery, relay connection checks and NIP-11 information fetching. Results are cached for five minutes; changing relay/source URLs starts a fresh refresh. Concurrent views share one in-flight refresh. The widget polls every two seconds only while refresh is pending. DM/CLI list remains a local read without automatic networking.

Relay information (NIP-11)

Relays and Extra fetch sources each include a compact, initially collapsed Relay info disclosure on its own full-width row below the controls, so expanding information does not move the read/write/status controls. Its summary shows the relay-advertised name/version, description, linked software, advertised NIPs and authentication/payment requirements. Full NIP-11 JSON opens a nested disclosure with the complete, pretty-printed cached document, including limits, retention, fees and unknown fields. Missing requirements/retention are labeled Not advertised. Advertised capabilities remain separate from observed protocol outcomes and do not establish storage or retention guarantees.

Information is cached locally per normalized relay URL, shared across accounts and loaded in the automatic account refresh. Requests use the HTTP(S) equivalent of the WebSocket URL with Accept: application/nostr+json, a five-second timeout and a 256 KiB response cap. Account refresh processes up to five URLs concurrently; in-flight requests for the same URL are coalesced. Successful and failed attempts are cached for five minutes. Refresh relay info forces a fresh attempt for that configured URL. Failed refreshes retain the last successful document and show the error/attempt time separately from Last fetched. The JSON panel scrolls for large documents without truncating the cached content.

Discovery queries configured relays, extra recovery sources, and BOT_RELAYS (up to 12 unique sources, five-second collection window). Fetching preserves local settings; Reset to published relays replaces the local read/write list with the fetched NIP-65 snapshot. Reset does not publish; Edit JSON remains an account-level control.

Publish NIP-65 opens AppWeaver's normal signer picker restricted to the selected account. Use its authenticated signer or a saved bunker with the same account public key. The server verifies the signature, author, kind, and exact current relay settings before sending to configured relays, previous published relays, and BOT_RELAYS. Operations reports acceptance/rejection for each destination. Acceptance is not a guarantee of indefinite storage. Older discovery responses cannot overwrite a newer published snapshot.

Fetch / coverage / sync flow

The timeline is organized as Relays → Extra fetch sources → Fetch → Coverage → Sync → Operations. Relay settings remain independent of event operations:

Individual events and raw JSON

Expand a kind → year → month branch to load its event rows, newest first, in pages of 50. Kind labels explicitly distinguish kind number from count, for example Metadata · Kind 0 · 1 event. Month grouping uses UTC; event timestamps use the shared browser-local timestamp display. Up to 32 loaded branches/pages are retained in view state across refreshes, with stable identities for tree expansion.

Rows show a timestamp and shortened ID. Clicking the row/ID has no action, and no full-ID hover is added. Each row's ⋮ menu contains Copy ID, Copy JSON, and Open JSON. Open JSON uses the shared modal to show the pretty-printed original signed event, without a separate full-ID heading. The JSON itself retains all fields.

Archive branches list unique local events; Coverage branches list that range's observed bodies; Sync branches list only current eligible confirmed-missing copies. Coverage also has a lazy Not fetched branch for IDs without archived bodies. Their kind/timestamp is not invented: Copy ID works, while Copy JSON/Open JSON are disabled. Browsing and JSON inspection are local read-only operations.

Selection and JSONL export

Fetch checkboxes select individual archived events or entire kind/year/month branches. Parent checkboxes show partial selection; selecting a parent includes matching events on collapsed branches and unloaded pages. Later child selections can exclude/include individual events. Select all selects the account archive; Clear selection clears it. Selection stays in this account view through paging and refreshes, and resets when switching accounts or opening a new default list.

Downloads use relays_backup_${timestamp}.jsonl, for example relays_backup_2026-10-15T12-00-00-000Z.jsonl. The timestamp is UTC and filename-safe. The browser creates the file directly from the command result; no server-side temporary file is created. JSONL contains one original event per line, with a final newline, in newest-first/ID order. Original IDs, signatures, tags, content and timestamps are preserved. Archive history, including superseded or expired events, is exported; Sync replay-eligibility rules do not limit a backup.

Selection uses ordered scope rules rather than only the visible row IDs. Matching events are resolved at download time from a consistent local database snapshot, so newly archived events within selected scopes are included. Overlapping selections never duplicate events. Coverage/Sync trees remain observation/delivery views; export selection belongs to Fetch. JSONL import remains deferred.

Backup excludes direct-message/seal/gift-wrap kinds 4, 13, 14, 1059, 1060 and ephemeral kinds 20000–29999. It validates event signatures and author identity, deduplicates by event ID, and preserves replaceable/deletion/expired events in the archive. Replay excludes expired/deleted events and superseded replaceable or addressable versions; deletion requests remain replayable. Attached media URLs are stored inside the event; media files are not downloaded.

Fetch prefers bounded NIP-77 reconciliation (60 kB binary payloads, hex-encoded on wire, 100 rounds, 250,000 local/difference IDs, 15-second timeout). Reconciliation compares IDs; ordinary REQ downloads remote-only bodies, validates them, and archives them. Common bodies are reused locally. Unsupported/failed negotiation is logged and falls back to ordinary paging; a failed negotiation never proves absence.

Ordinary paging uses a fixed run-start until, defaults to 100 events per page, and follows the earliest returned timestamp inclusively, deduplicating IDs. Advertised NIP-11 max_limit caps reduce the effective request size, which is saved. Only literal EOSE plus a short, unrestricted response completes paging under the relay's query/retention semantics. Invalid responses and saturated same-second pages remain partial rather than skipping a timestamp bucket. REQ timeout is eight seconds; each invocation allows 100 pages per source, then preserves its checkpoint.

After history completes, each relay independently fetches since = last successful forward boundary - 10 seconds through the new run-start time. The boundary advances only when the interval finishes. Default Fetch resumes the latest compatible unfinished full-source run; the range menu resumes only the selected unfinished range. Recheck history starts a fresh historical comparison to discover old events imported later with unchanged created_at. Fetch settings sets page size for new runs; Resume always retains the saved size and bounds. The global button checks all configured fetch sources; the Coverage relay-header button checks only that source. Both create fresh history ranges through now, whereas a range's Refetch preserves that saved range's original bounds. Fetch remains a unique local archive grouped by kind/year/month, not by relay.

Historical observations do not expire into Undetermined merely with age. Failed queries preserve earlier evidence; unrelated recent intervals cannot establish absence in older history. Completed applicable inventories establish missing-copy candidates, including events archived later from other sources. Evidence timestamps remain visible, and malformed/future observation metadata is reported separately. Connection status is separate from event presence.

Sync missing events snapshots all eligible confirmed-missing copies by default; Narrow scope accepts relay, kind, and inclusive UTC dates/Unix seconds. Collapsed branches remain in scope. Original signed events are sent unchanged, only to current write destinations. Sync records Accepted, Rejected, or Unverified (inconclusive acknowledgement). It does not issue read-back requests. Accepted is publication completion, not proof that the relay retained the event.

The runner automatically continues in 200-copy internal chunks until the pass is finished or stopped. Each eligible copy is attempted at most once per invocation; pending copies precede retries. Stop retains unfinished work; Resume processes pending/rejected/uncertain copies without resending accepted or previously verified deliveries. Older Accepted-but-Unverified records keep their positive acknowledgement. Operations shows compact processed/accepted/rejected progress, with details collapsed.

Run Recheck history after Sync. Accepted copies with only older missing evidence are shown as awaiting recheck, not Present or ordinary missing candidates. They are not selected again by a new Sync until a later applicable comparison confirms absence. A completed recheck updates Coverage to Present or Missing; failure leaves earlier evidence intact. Ordinary recent Fetch may not revisit older synced events. Historical delivery acknowledgements remain in Operations; storage evidence lives in Coverage rather than being inferred from acknowledgement alone. Finished single-destination Sync passes offer Recheck history — relay beside their progress, including when an all-destinations selection produced copies for just one relay. The destination is determined from the complete saved delivery snapshot, not the currently visible outcome page. The shortcut starts the same relay-scoped recheck as Coverage. It is disabled during account Fetch/Sync work or when that relay is no longer a configured fetch source. Rejected/uncertain retry guidance is shown only when those outcomes exist; multi-relay passes retain global history-recheck guidance.

Only the current NIP-77/paging implementation is supported. The old 500-event split-window runner, its Resume action, and legacy presence migration were removed when the user requested a complete fresh start. Normal Resume still continues unfinished current Fetch/Sync operations.

The local relay configuration can differ from its published NIP-65 snapshot while preparing a migration. Preserve old relays as extra sources, archive their history, sync to configured new write relays, Recheck history, then publish the new NIP-65 list.

Connection checks measure WebSocket establishment in milliseconds (five-second timeout, batches of five). Connected does not imply relay read/write permission. Last check timestamps and results persist. Extra sources are recovery locations, not advertised read/write relays.

Commands

Configuration JSON:

{
  "relays": [{ "url": "wss://relay.example.com", "read": true, "write": true }],
  "extraSources": ["wss://old-relay.example.com"]
}

These local configuration mutations execute immediately without drafts. They do not delete Nostr events. No signer credentials are stored in this iteration.

Storage and remaining work

db.sqlite holds independent account JSON documents, profile/snapshot metadata, relay connection observations, and presentation-independent archive/operation tables. Initialization creates only the current manager schema; old scaffold CRUD, presence tables, and migration snapshots are no longer part of the plugin. Fetch cursors, ranges, query attempts, inventory membership, policy-excluded bodies, and sync deliveries are stored independently of settings and connection checks. The current comparison is rebuilt from query/range provenance. Changing a source URL does not remove it from NIP-65 settings, or vice versa.

JSONL import, relay authentication, specialized relay filters, and creation of deletion requests remain deferred. Coverage and sync trees render persisted evidence only. Live relay and authenticated browser review are tracked separately in the implementation plan.

See architecture and the durable implementation plan for the next iterations. Shared contracts: plugin author guide.