Relays architecture
This document describes current code. The approved Fetch / Coverage / Sync design and active implementation milestones record the implemented direction and verification status. Live relay and authenticated timeline review remain pending.
Entrypoints
init.tsinitializes plugin SQLite and exposes command metadata.adapter.tsparses structured JSON arguments/options when supplied, otherwise CLI text tokens, and routes to account commands orlist.init.tsforwards the invocation's JSON payload so download commands retain their account/selection.commands/manager.tsdefines account editing, discovery/checks, backup modes, explicit sync, cancellation, and NIP-65 publication; validates range/scope inputs.commands/list/adapter.tsresolves the selected account, archive groups, relay scopes, persisted coverage/missing groups, and requested lazy event pages. Loaded missing-destination branches are discarded when relay-role edits remove them.selection.tsparses bounded ordered scope rules and resolves selection/tri-state counts against the account's archive index. Selection is read-only view state, retained inlist --selectionacross lazy page/refresh actions, with no new table. Parent selections cover unloaded descendants; later matching rules override them.commands/export.tssnapshots all or selected original account events, serializes one compact JSON event per line and generatesrelays_backup_${timestamp}.jsonl. It exports archive history independently of replay eligibility and returns raw JSONL outside web or the generic text-download envelope for web. It creates no disk file.browsing.tsvalidates bounded loaded-branch state, performs read-only month/range/ missing-copy queries, pages 50 rows with timestamp/ID tie ordering, and scopes raw event JSON lookup to the selected author. Body-less range IDs are paged separately without invented kind/date metadata. No new tables or networking are needed.commands/event.tsprovides read-only JSON output; menu actions use the sharedsurface: 'modal'command contract. The modal contains original pretty-printed JSON without a separate full-ID heading. Clipboard actions reuseclipboard.writeText.commands/list/renderers/web.tsbuilds generic WebNodes with scoped styles. Archive, Coverage and Sync share lazy month branches with explicit Kind/count labels and stable render keys. Rows have no action/full-ID tooltip; their overflow menus own Copy ID/Copy JSON/Open JSON. Missing bodies disable the JSON actions. Fetch adds selectable kind/year/month/event checkboxes, parent indeterminate state, Select all/Clear selection, and full/selected export throughweb.downloadCommand. Coverage relay headers and finished single-destination Sync summaries exposebackup --history --relayactions. Source membership and the account work lock control availability; the archive browser keeps its kind/year/month grouping. Download mechanics use the reusable Web renderer contract. All forms/actions operate in the timeline; no dock registration or core UI branches. Add-account uses the reusableselectsourcenostrAccountsto submit only the browser account or saved bunker account owner's public key. Manual npub entry submits through a separate form to the sameaddcommand. Each form puts the input and submit button on one row. Relay header/body cells use element nodes, including connection times, to maintain identical grid tracks (adjacent raw text nodes otherwise share an anonymous grid item).store.tsvalidates configuration/public keys and implements account/archive reads.coverage.tsowns source/destination derivation and eligible per-destination missing-kind/date aggregation.evidence.tsowns current range/query/cursor/delivery schemas, inventory membership, and provenance-backed presence projection.eligibility.tsseparates signed public-event archival from replay selection; handles expiration, deletion references, and latest replaceable/addressable versions. Integer event timestamps/kinds are required. A bounded cache reuses signature validation only for unchanged original JSON bodies, avoiding repeated cryptography during UI polling while invalidating changed bodies.network.tsperforms bounded kind-0/NIP-65 discovery and WebSocket checks.relay-info.tsfetches relay-advertised NIP-11 documents using HTTP(S), five-second deadlines and a 256 KiB streamed response cap. It persists per-URL information inrelay_information, caches attempts for five minutes, coalesces concurrent requests, and preserves successful data/timestamps when later attempts fail. Account refresh batches up to five URLs;info --urlforces an attempt for a configured URL.commands/list/renderers/relay-info.tsbuilds compact native disclosures in Relays and Extra fetch sources, including safe HTTP(S) software links, advertised fields, missing-value labels, fetch/error timestamps and a refresh action. Its text/JSON output does not interpret advertised NIPs as verified support or storage evidence. A nested Full NIP-11 JSON disclosure shows the complete pretty-printed document. Relay disclosures span a separate grid row below all six control columns; extra sources similarly put the disclosure below their URL/remove controls.operations.tsowns operation persistence/recovery, shared per-account Fetch/Sync exclusion/cancellation, and signature-verified archival. Query evidence is committed separately by the fetch caller in the same transaction as archive insertion.event-network.tsowns bounded REQ, raw NIP-77 negotiation using the existingnostr-tools.nip77engine, publication acknowledgement, and optional NIP-11 caps. It preserves literal EOSE, NOTICE, rejection, disconnect, timeout, cancellation, and actual wire-send/completion times independently of operation completion.fetch.tsowns immutable source/range/settings snapshots, preferred reconciliation, inclusive timestamp paging, incremental overlap, Refetch/Recheck history, and Resume. Optional relay scope applies only to fresh history rechecks and is validated against current configured fetch sources before creating work. Saved-range Refetch/Resume remain separate and preserve their original bounds.sync.tssnapshots eligible confirmed-missing deliveries, checks destination roles and eligibility, and publishes unchanged events without read-back requests. It also provides bounded paged delivery/outcome views for the timeline. Delivery views include all distinct operation destination URLs independently of pagination. Completion notices use that full destination scope and actual retry outcomes; older saved notices are rendered with the same current guidance.publication.tsvalidates the browser-signed NIP-65 event against current account configuration and publishes to new/old/bootstrap relays with per-relay outcomes.automatic-refresh.tscoalesces background refreshes per database/account, caches completion for five minutes, and invalidates on source URL changes. It coordinates profile/NIP-65 discovery, connection checks and cached NIP-11 retrieval. Webliststarts refresh without waiting and opts into two-second polling only while pending. DM/CLI list does not start network work. Errors are displayed in Relays without discarding previously fetched metadata or local relay settings.db.tsopens plugin SQLite in WAL mode with foreign keys and initializes the manager schema.
Persistence
accounts: public-key identity, validated JSON relay configuration, profile JSON, observed published relay snapshot, and update timestamp.relay_checks: URL, last connection outcome, handshake duration, checked timestamp.relay_information: normalized URL, bounded NIP-11 JSON document, last attempt, last successful fetch and current error; shared by accounts using the same URL.events: original signed JSON and indexed ID/author/kind/time;operations.tsinserts verified public-event bodies idempotently during backup.relay_fetch_state: history completion and successful forward boundary per account/source URL, independent of current settings and unfinished range cursors.fetch_ranges: operation/account/source identity, inclusive bounds (nullable Beginning), mode, previous Refetch link, requested/effective limit checkpoint, cursor/boundary IDs, strategy, status, comparison completion/query ID/time/basis.relay_queries: append-only attempt identities with exact filter, method, outcome, counts and details.sent_atrecords attempt start;details.sentAtrecords the actual wire send, or null if it never sent.completed_atis the transport outcome time, not the parent operation's completion. Interrupted attempts retain unknown completion times rather than fabricating a relay response.query_evidence: query/event positive/negative facts with no required archive-body foreign key. Negative NIP-77 differences are committed only after full negotiation.range_events: unique remote inventory IDs per range. Completed inventories can compare bodies archived later from another source.range_excluded_bodiesrecords private/ephemeral bodies that archive policy deliberately excludes.sync_deliveries: original signed bodies and selected evidence per event/relay/run, acknowledgement, publication attempts, processing-pass marker, status and reason. Earlier verification fields remain readable. No signer credentials or re-signing.operations: fetch/sync/publication status and summary JSON. Init marks running operations/ranges/queries interrupted. Resume fills new query attempts around saved checkpoints; verified deliveries are skipped. Running operations are included before recent finished ones.relay_list_versions: newest published/discovered NIP-65 timestamp/event ID, preventing slower metadata refresh from restoring an older published snapshot.
Initialization uses CREATE TABLE IF NOT EXISTS for the current schema. The approved
complete development-data reset removed old tables and migration code; there is no
legacy importer or split-window runner. Normal account removal leaves archive facts intact. Tree
kind/year/month grouping is derived in UTC; it is not stored as a UI hierarchy.
Event operations boundary
list renders persisted accounts, relay observations, and archive groups.
Design-preview mode and sample data have been removed. Fetch, comparison, Sync,
NIP-65 publication, archive selection and JSONL export are active; import remains deferred.
The header owns account removal and JSON editing. Relays owns NIP-65 read/write
configuration, connection status, and published-list application. Extra fetch
sources is independent. Fetch browses the unique archive, Coverage displays
per-source ranges, and Sync groups eligible missing deliveries by relay/kind/date.
accountRelayScope derives fetch sources from configured write relays plus extras;
sync destinations are configured write relays only. A URL may exist in both lists;
editing either list does not silently edit the other. The source union is deduplicated.
Comparison is rebuilt from query observations and completed applicable range inventories, ordered by query completion time and query sequence for ties. An unrelated/failed recent scope cannot overwrite older evidence. Age alone does not erase observations; invalid/future observation metadata is distinct from undetermined coverage. Only applicable completed absence enters the eligible Sync tree. Per-range Found counts are not summed as unique account totals. Socket checks and publication acknowledgements never establish verified event storage.
An Accepted EVENT query newer than old missing evidence yields an Awaiting recheck
publication overlay, not a positive query_evidence row. Its query ID breaks
equal-timestamp ties. Coverage/Sync expose the pending-recheck count separately and
exclude it from missing candidates. A later applicable completed comparison can
establish absence again; actual positive observations establish presence. Unrelated
recent scopes, failed queries and acknowledgements do not erase stored-presence facts.
Network boundary
fetch queries configured and environment bootstrap relays using nostr-tools
signature-verified event subscriptions and selects the newest replaceable events.
The published NIP-65 snapshot is separate from local configuration. check
measures socket establishment only; NIP-42 authentication/relay permissions are
future work. No account private keys or bunker secrets are persisted.
backup uses configured write relays plus extras, not discovery bootstrap relays.
NIP-77 negotiates a complete timestamp/ID comparison, then REQ downloads bodies.
It is bounded to 60 kB outgoing binary payloads (hex-encoded on wire), 128 kB
incoming JSON frames, 100 rounds, 250,000 IDs and 15 seconds.
Failures are logged before independent ordinary fallback; partial NEG fragments
never establish absence. The root nip77 export is used because this nostr-tools
version has no exported nostr-tools/nip77 package subpath.
Fallback pages backward from a fixed run-start bound, inclusively retaining the earliest timestamp and deduplicating boundary IDs. Requested size defaults to 100; advertised NIP-11 caps lower the saved effective size. REQ is bounded to eight seconds and 100 pages per source/invocation. Literal EOSE plus a short unrestricted response completes under relay semantics; invalid responses and saturated seconds remain partial. Resume preserves strategy, cursors, limits, and original scope.
Completed initial history enables per-source recent intervals with a ten-second overlap and fixed new upper bound. Only a finished interval advances the forward boundary. Recheck history starts a new full historical observation; Refetch repeats exact old bounds. Range Resume resumes that range; default Fetch resumes the latest compatible unfinished full-source operation.
Sync snapshots eligible missing-copy evidence and original bodies, with optional
relay/kind/date narrowing. It drains 200-copy chunks continuously and prioritizes
Pending deliveries. processing_attempts is now a last-pass marker: selecting a row
marks it with the invocation's marker, preventing repeated retries in later chunks.
Stop/Resume retains the snapshot and skips Accepted/historical Verified deliveries.
Older accepted-but-unverified rows are normalized on Resume without losing query
history. Role/eligibility checks still prevent invalid uploads. Rejected/uncertain
copies can be retried explicitly on Resume; neither path performs read-back.
Accepted counts as publication completion, not retained storage. The user invokes Recheck history afterward to update Coverage. Existing runs/signed bodies are preserved; no schema reset is needed. Compact operation progress is visible while delivery details stay collapsed, and Stop remains available in the summary.
Publishing uses generic nostr.signEvent immediate signing with allowedPubkeys.
The selected account's author/signature and exact current tags are revalidated by
the plugin before publication. Client signing alone never counts as publishing.
The renderer polls only while metadata refresh or an operation is running.
Progress: implementation plan. Core contracts: plugin system and Web renderer.