nostr-mock-relay

In-memory Nostr mock relay for deterministic JavaScript and TypeScript tests.

Use it when your app or package needs to test Nostr relay behavior over WebSocket without depending on an online relay, network state, remote data, moderation policy, rate limits, or persistence.

Features

• WebSocket relay interface compatible with Nostr clients.
• In-memory storage per relay instance.
• Strict event validation with nostr-tools.
• NIP-01 client messages: EVENT, REQ, CLOSE.
• NIP-01 relay messages: EVENT, OK, EOSE, CLOSED, NOTICE.
• Filter support for ids, authors, kinds, tag filters like #e and #p, since, until, and limit.
• Replaceable, addressable, and ephemeral event behavior.
• No persistence, no external service, no CLI.

Requirements

Node.js >=24.

Install

npm install nostr-mock-relay

Usage

import { createMockRelay } from "nostr-mock-relay";

const relay = createMockRelay();

await relay.start();

try {
  console.log(relay.url); // ws://127.0.0.1:<port>/

  // Connect your Nostr client or test code to relay.url.
} finally {
  await relay.stop();
}

Test Example

import { finalizeEvent, generateSecretKey } from "nostr-tools";
import WebSocket from "ws";
import { createMockRelay } from "nostr-mock-relay";

const relay = createMockRelay();
await relay.start();

const socket = new WebSocket(relay.url!);
await new Promise((resolve) => socket.once("open", resolve));

const secretKey = generateSecretKey();
const event = finalizeEvent(
  {
    kind: 1,
    created_at: Math.floor(Date.now() / 1000),
    tags: [],
    content: "hello mock relay"
  },
  secretKey
);

socket.send(JSON.stringify(["EVENT", event]));

socket.on("message", (data) => {
  console.log(JSON.parse(data.toString()));
  // ["OK", "<event-id>", true, ""]
});

API

createMockRelay(options?)

Creates an isolated in-memory relay instance.

const relay = createMockRelay({
  host: "127.0.0.1",
  port: 0,
  path: "/"
});

Options:

• host?: string defaults to "127.0.0.1"
• port?: number defaults to 0
• path?: string defaults to "/"

Relay methods:

• await relay.start() starts the WebSocket server.
• await relay.stop() closes the server and connected clients.
• relay.url is the WebSocket URL after start().
• relay.seed(events) inserts strictly valid signed events.
• relay.getEvents() returns stored events.
• relay.reset() clears stored events and active subscriptions.

Protocol Scope

This package implements a focused NIP-01 subset for tests.

Supported client messages:

• ["EVENT", event]
• ["REQ", subscriptionId, filter]
• ["CLOSE", subscriptionId]

Only one filter per REQ is supported. Requests with multiple filters are rejected:

["CLOSED", "sub", "invalid: multiple filters are not supported"]

Events are validated strictly. Unsigned events, invalid IDs, invalid signatures, malformed tags, or malformed fields are rejected.

License

MIT