Relay Shadow DVM

A Nostr Data Vending Machine (DVM) that recommends relays based on privacy, reliability, performance, and social-graph signals derived from the BigBrotr relay dataset. Originally built for the Bitcoin++ Privacy Edition hackathon (2025).

The DVM listens for job requests on Nostr, evaluates candidate relays against a scoring model backed by a PostgreSQL copy of the BigBrotr data, and publishes ranked recommendations back to the requester.

How it works

1. start-dvm.js boots the DVM, connects to a configured set of Nostr relays over WebSocket, and subscribes to incoming job requests.
2. Requests are received as Nostr events of kind 5600. Each request carries parameters (threat level, use case, current relay list, max results, etc.) in its tags.
3. RelayShadowDVM queries the PostgreSQL database and ranks relays using a weighted score combining social-graph, privacy, reliability, and performance factors.
4. Results are signed and published back as kind 5601 events; 7000 is used for job feedback/status.

Supported request types: recommend, analyze (evaluate a current relay set), discover (expand coverage), and health. Threat levels range over low, medium, high, and nation-state.

Project layout

src/
  dvm/            RelayShadowDVM core logic and runtime config
  scripts/        start-dvm, database setup, data analysis, and a CLI test client
  api/            Express server exposing /health and /api/dvm/info to the web client
  constants/      Shared DVM event-kind definitions
  client/         React + Vite + Tailwind demo UI (with Alby wallet integration)
database/         SQL for schema init, preprocessing, and query functions
cache/            Precomputed responses for the demo

Scoring model

Relay ranking is a weighted combination configured in src/dvm/config.js:

Factor	Weight
Social graph	0.40
Privacy	0.25
Reliability	0.20
Performance	0.15

Recommendations are capped at 10 results and filtered by a minimum relay score of 5.0.

Requirements

• Node.js >= 18
• A PostgreSQL database populated with the BigBrotr dataset
• A Nostr private key for the DVM identity

Setup

npm install
cp .env.example .env   # fill in DB_* credentials, DVM_PRIVATE_KEY, DVM_RELAYS

npm run setup          # initialize the database
npm run comprehensive-setup   # build analytics tables and functions

Key environment variables (see .env.example): DB_HOST, DB_NAME, DB_USER, DB_PASSWORD, DB_PORT, DVM_PRIVATE_KEY, and DVM_RELAYS (comma-separated relay URLs; defaults to wss://relay.damus.io, wss://relay.snort.social, wss://nos.lol).

Running

npm start              # start the DVM listener
npm run web            # start the React demo client (src/client)
npm run analyze        # (re)build analytics from the dataset

The included CLI test client can issue requests against a running DVM:

npm run test:recommend   # requires DVM_PUBKEY in the environment
npm run test:analyze
npm run test:health

Tech stack

Node.js (ESM), nostr-tools and nostr-relaypool for Nostr, ws for WebSocket relay connections, pg for PostgreSQL, and Express for the local API. The demo client is built with React, Vite, and Tailwind CSS.

License

MIT. See LICENSE.