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:
- Relays configures the local NIP-65 read/write list and shows connection status.
- Extra fetch sources manages fetch-only recovery URLs via + Recovery source.
- Fetch browses unique archived events by kind/year/month. Its source scope is configured NIP-65 write relays plus extra sources, deduplicated by URL. Fetch / Back up starts a background archive operation, retaining each original signed event and recording presence only on relays it was actually fetched from.
- Coverage shows source relay → saved range → kind/date and query attempts.
Each relay header offers Recheck history for that relay alone, creating a
fresh Beginning → now observation. Removed sources must be restored before rechecking.
Each range displays unique Found IDs, Fetched bodies, completion, strategy,
checked-at time, saved settings/cursor, and errors. The
⋮menu offers Refetch and unfinished-range Resume. Refetch creates a linked new observation; Resume keeps the range's original bounds and settings. - Sync groups confirmed missing copies as relay → kind → year → month. The same event missing on two write relays contributes two deliveries to the total.
- Operations shows fetch, sync, and NIP-65 publication outcomes. Sync outcomes are paged in batches of 50, including original selection evidence, acknowledgement/rejection, read-back details, and verification timestamps. Active Fetch/Sync operations have Stop (keep checkpoint). Stopping retains partial work; it cannot retract an event already sent.
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.
- Export downloads the entire selected account's archive, regardless of checkboxes.
- Export selected downloads only the selected archived events and is disabled until at least one event is selected.
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
/relays list [--account <npub>]— timeline manager; text account listing in DM/CLI./relays event <npub> <event-id>— read the original archived JSON; the row menu opens its web output in a modal./relays export <npub> [--selection '<rules-json>']— export original account events as JSONL; the web Export buttons download a file./relays add <npub>— add an account by public key./relays update <npub> --url <wss-url> --role <both|read|write|source>— add/change a relay./relays update <npub> --url <wss-url> --remove— remove a NIP-65 relay./relays update <npub> --url <wss-url> --role source --remove— remove an extra fetch source./relays update <npub> --data '<json>'— upsert validated account configuration./relays update <npub> --published— apply the last fetched NIP-65 snapshot locally./relays fetch <npub>— fetch profile and advertised relay snapshot./relays check <npub>— measure configured relay/source connection times./relays info <npub> --url <url>— refresh cached NIP-11 information for one configured relay or extra fetch source./relays backup <npub> [--limit 100]— start/resume background public-event Fetch./relays backup <npub> --history— Recheck history with a new run./relays backup <npub> --history --relay <url>— fresh history recheck for one configured write relay/extra fetch source; cannot combine with--rangeor--resume./relays backup <npub> --range <id> [--resume]— Refetch a saved range, or Resume its unfinished work./relays sync <npub> [--relay <url>] [--kind <n>] [--since <date|second>] [--until <date|second>]— publish eligible confirmed-missing copies; Recheck history afterward./relays sync <npub> --resume <operation-id>— continue pending copies and retry failures from the saved publication selection./relays cancel <npub> --operation <id>— stop an active Fetch/Sync operation, retaining checkpoints./relays list --account <npub> --operation <id> --page <n>— select a zero-based outcome page for a recent sync operation in the timeline./relays publish <npub> '<signed-event-json>'— publish a signed NIP-65 list matching current local settings; use the widget to sign it./relays delete <npub>— remove the account from the manager, retaining archived events.
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.