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/rstate is the aggregation layer for the nostr-watch system. It ingests NIP-66 relay check events published by relaymon instances, computes aggregated scores and state across multiple independent monitors, and serves the results through a REST API. It is built on the ContextVM SDK for decentralized computation and exposes 21 MCP tools over a Nostr transport, allowing AI agents to query relay intelligence directly. OpenAPI documentation is available at /docs when the REST API is enabled.

​
Prerequisites

  • Node.js >=20
  • A config.yaml file (copy from config.sample.yaml)

​
Environment variables

Environment variables take precedence over their corresponding config.yaml values.
VariableRequiredDescriptionExample
CVM_RELAYSYes (if CVM enabled)Comma-separated relay URLs for ContextVM transportwss://relay.damus.io
INGEST_RELAYSYesComma-separated relay URLs for NIP-66 event ingestionwss://history.nostr.watch
CVM_SERVER_NSECYes (if CVM enabled)Server private key for signing ContextVM responsesnsec1...
REST_ENABLEDNoEnable the REST APItrue
REST_PORTNoREST API listen port3000
LOG_LEVELNoLogging verbosityinfo

​
Installation

1

Install dependencies

From the monorepo root, install all workspace dependencies:
pnpm install
Or install from the app directory directly:
cd apps/rstate
npm install
2

Copy the sample configuration

cp config.sample.yaml config.yaml
3

Edit config.yaml

Set your ingest.relays, cvm.relays, cvm.nsec, and server.port at minimum.
4

Build the application

npm run build
5

Start rstate

npm start
6

Access the OpenAPI docs

With REST_ENABLED=true, open http://localhost:3000/docs in your browser to explore the full endpoint reference.

​
Quick start

# Copy and edit configuration
cp config.sample.yaml config.yaml

# Build and start
npm run build
npm start
The REST API (if enabled) is available at http://localhost:3000. OpenAPI documentation is at http://localhost:3000/docs.

​
Configuration reference

Configuration uses YAML as the primary format with environment variable overrides. Set the config file path via the CONFIG_FILE environment variable or the --config CLI flag (defaults to config.yaml). 
server:
  host: 127.0.0.1
  port: 3000

cvm:
  relays:
    - wss://relay.damus.io
  nsec: 'nsec1...'

ingest:
  relays:
    - wss://history.nostr.watch

cache:
  maxSize: 10000
  ttlSeconds: 60

aggregation:
  lookbackSeconds: 21600  # 6 hours
  quorum: 0.5

logging:
  level: info

​
Configuration sections

SectionKeyDescription
serverhostBind address for the REST API server
serverportListen port for the REST API (also overridden by REST_PORT)
cvmrelaysRelay URLs used for the ContextVM Nostr transport
cvmnsecServer private key for signing ContextVM responses (use CVM_SERVER_NSEC env var in production)
ingestrelaysRelay URLs from which NIP-66 check events are ingested
cachemaxSizeMaximum number of relay entries to hold in memory
cachettlSecondsCache entry time-to-live in seconds
aggregationlookbackSecondsLookback window for aggregating check events (default: 21600 = 6 hours)
aggregationquorumFraction of monitors that must agree for a value to be included (default: 0.5)
logginglevelLogging verbosity: debug, info, warn, error

​
REST API endpoint groups

When REST_ENABLED=true, rstate exposes the following endpoints:
MethodEndpointDescription
GET/health/pingServer health check with cache statistics
GET/relaysList relays with pagination and sorting
GET/relays/stateGet aggregated state for a specific relay URL
POST/relays/searchFilter relays by network, NIPs, software, labels, or latency
GET/relays/nearbyFind relays near coordinates (lat/lon/radius)
GET/relays/by/softwareGroup relays by software family
GET/relays/by/networkGroup relays by network type (clearnet, Tor, I2P)
GET/relays/by/nipGroup relays by NIP support
GET/relays/by/countryGroup relays by country
POST/relays/compareSide-by-side comparison of multiple relays
GET/monitorsList known monitors with reliability scores
GET/policyGet the current aggregation policy
POST/subscriptionsCreate a relay state subscription
GET/subscriptions/eventsServer-Sent Events (SSE) stream for real-time updates
For the full request and response schema for each endpoint, see the interactive OpenAPI documentation at /docs.

​
MCP tools via ContextVM

When cvm.relays and cvm.nsec are configured, rstate registers 21 MCP tools accessible to AI agents over the Nostr transport. These tools expose the same relay intelligence as the REST API in a format consumable by MCP-compatible clients.
MCP tools are accessed via the ContextVM (CVM) Nostr transport, not via HTTP. See the CVM and MCP documentation for client setup details.

​
Known limitations

SDK stub dependencies: sdk-stubs.ts contains MockRelayPool and MockSigner implementations — MockSigner returns a hardcoded 'mock_signature' instead of real cryptographic output. Production deployments must replace these stubs with real ContextVM SDK classes (ApplesauceRelayPool and PrivateKeySigner).
Outdated development utilities: dev-tools.ts uses @ts-nocheck and references the old RelayState structure that no longer matches the current AggregatedValue shape. Dev utilities cannot be reliably used for debugging current data shapes.
Console.log in scoring: monitor-scoring.ts has unconditional console.log calls that fire on every computeAllScores() invocation. These will spam production logs at any log level. Replace with a gated logger before deploying to production.

Build docs developers (and LLMs) love

Get started for freeTalk to us