Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sandwichfarm/nostr-watch/llms.txt

Use this file to discover all available pages before exploring further.

nostr-watch is a pnpm workspace containing 30+ packages organized into three layers. Packages in lower layers have no knowledge of packages above them — internal packages never import from libraries, and neither layer imports from apps. This one-way dependency rule keeps libraries clean for external consumers and prevents circular dependencies across the monorepo.

​
Directory structure

nostr-watch/
├── apps/        # Product applications (services, dashboards, CLI tools)
├── libraries/   # Reusable shared packages (independently installable via npm)
├── internal/    # Infrastructure shared across apps and libraries
└── docs/        # Documentation site

​
Dependency direction

internal  →  libraries  →  apps
  • internal packages have no dependencies on libraries or apps
  • libraries may depend on internal packages, but not on apps
  • apps consume both libraries and internal packages freely

​
Package layers

​
internal/

Infrastructure and utilities shared across the monorepo. These packages are not intended for external consumption.
PackagePurpose
@nostrwatch/publisherNostr event publishing with a pluggable adapter pattern
@nostrwatch/loggerStructured logging wrapper (Pino)
@nostrwatch/utilsShared utilities: key generation, array helpers, environment detection
@nostrwatch/announceNIP-66 monitor announcement event generation
@nostrwatch/controlflowBullMQ queue management and backoff control
@nostrwatch/seedRelay seeding from multiple discovery sources
@nostrwatch/redisBullMQ/Redis dashboard server
@nostrwatch/kindsNostr event kind constants

​
libraries/

Reusable packages published to npm under @nostrwatch/*. These are independently installable and designed for external use.
PackagePurposePlatform
@nostrwatch/nocapAdapter-based relay capability discoveryWeb · Node
@nostrwatch/route66NIP-66 relay aggregation and state managementWeb · Node
@nostrwatch/auditorRelay NIP conformance validationWeb · Node
@nostrwatch/nostringsRelay URL sanitization and normalizationIsomorphic
@nostrwatch/websocketIsomorphic WebSocket wrapperWeb · Node · Deno
@nostrwatch/relay-chronicleTime-series relay history from NIP-66 delta eventsWeb · Node
@nostrwatch/relay-chartsChart adapters for relay data visualizationWeb
@nostrwatch/memory-relayIn-memory Nostr relay for testing and embeddingWeb · Node
@nostrwatch/worker-relayNostr relay running in a Service WorkerWeb
@nostrwatch/schemata-js-ajvAJV wrappers for Nostr JSON schema validationWeb · Node
@nostrwatch/dbSQLite database layerNode

​
apps/

Product applications. These consume libraries and internal packages to build end-user-facing services and interfaces.
PackagePurposePlatform
@nostrwatch/guiNIP-66 Nostr relay dashboardWeb
@nostrwatch/relaymonRelay health monitor with NIP-66 event publishingNode · Deno
@nostrwatch/trawlerRelay crawler for the nostr-watch networkNode · Deno
@nostrwatch/rstateNIP-66 relay state machine with REST and MCP endpointsNode
@nostrwatch/puristBrowser-based relay scannerWeb
@nostrwatch/docker-stacksPre-configured Docker Compose stacksDocker

​
Adapter pattern

Three packages — nocap, route66, and publisher — use a pluggable adapter architecture to decouple check orchestration and event publishing from environment-specific implementations.

​
nocap adapters

nocap separates check orchestration (timeouts, result collection, ordering) from check implementation. Adapters supply the actual work: DNS lookups, TLS certificate retrieval, WebSocket connection management. Each adapter declares a static type property ('websocket', 'dns', 'ssl', 'geo', 'info') that tells nocap which check dimensions it handles. Five default adapters ship in libraries/nocap/adapters/default/:
AdapterTypeWhat it does
WebsocketAdapterDefaultwebsocketOpen/read/write WebSocket checks via @nostrwatch/websocket
DnsAdapterDefaultdnsDNS lookup via Cloudflare DNS-over-HTTPS
SslAdapterDefaultsslTLS certificate validation (Node.js only)
InfoAdapterDefaultinfoNIP-11 relay information document retrieval
GeoAdapterDefaultgeoGeographic IP lookup; depends on DNS result
Custom adapters extend AbstractAdapter and implement the interface for their type. See nocap for the full custom adapter guide.

​
route66 adapters

route66 has two independent adapter dimensions:
  • Cache adapters (ICacheAdapter) — store and query NIP-66 relay check events locally. The reference implementation, NostrSqliteAdapter, uses SQLite via @nostrwatch/worker-relay.
  • WebSocket adapters (IWebsocketAdapter) — connect to Nostr monitoring relays to receive incoming NIP-66 events. The reference implementation, NostrToolsAdapter, uses nostr-tools and nostr-fetch.
Both dimensions are swappable independently, so route66 works equally well in browser, Node.js, or worker thread environments.

​
publisher adapters

@nostrwatch/publisher abstracts Nostr event signing and broadcasting behind an adapter interface. This allows relaymon and other agents to swap signing libraries (e.g., nostr-tools, hardware signers) without changing event construction logic.

​
Cross-package imports

All packages within the monorepo reference each other using @nostrwatch/* scoped names. pnpm workspaces resolve these to local package directories during development: 
import { getLogger } from '@nostrwatch/logger'
import Nocap from '@nostrwatch/nocap'
import { Route66 } from '@nostrwatch/route66'
The same import paths work unchanged when consuming packages from npm.

​
Deprecated packages

Several packages are maintained as stubs with migration guidance:
PackageStatusMigration
apps/nocapdDeprecatedReplaced by apps/relaymon
internal/nwcacheDeprecatedCaching inlined into consumers
libraries/schemataDeprecatedMoved to @nostrability/schemata
libraries/sanitizeDeprecatedReplaced by @nostrwatch/nostrings
libraries/nocap-route66DeprecatedSee package README
See each package’s README for migration instructions.

​
Further reading

Core libraries

nocap, route66, auditor, and nostrings API references.

Running services

relaymon, trawler, rstate, and docker-stacks deployment guides.

Build docs developers (and LLMs) love

Get started for freeTalk to us