Skip to content

Relay ​

The Relay module validates, normalizes, and classifies Nostr relay URLs.

NIP-11 relay information documents are modeled by the Relay class in @welshman/domain, which owns the profile display (relay.display()) and capability checks (relay.hasNegentropy(), relay.hasNip(), relay.isPaid()). relay.displayUrl() delegates to displayRelayUrl below.

relay.isPaid() is true when the document sets limitation.payment_required and a payments_url, which together mean the relay charges and says where to pay. relay.fees holds the schedule as RelayFee entries: amount with a unit of msats or an ISO 4217 currency code, in which case the amount is in that currency's minor unit, plus an optional period in seconds. Entries in one category are alternatives rather than a sum.

API ​

URL Validation ​

typescript
// Check if URL is a valid relay URL
export declare const isRelayUrl: (url: string) => boolean;

// Check if URL is an onion (Tor) address
export declare const isOnionUrl: (url: string) => boolean;

// Check if URL is a local address
export declare const isLocalUrl: (url: string) => boolean;

// Check if URL contains an IP address
export declare const isIPAddress: (url: string) => boolean;

// Check if URL is safe to share publicly
export declare const isShareableRelayUrl: (url: string) => boolean;

URL Normalization ​

typescript
// Normalize relay URL to standard format
export declare const normalizeRelayUrl: (url: string) => string;

// Format URL for display (strip protocol + trailing slash)
export declare const displayRelayUrl: (url: string) => string;

Relay Selection DSL ​

A RelaySelection describes which relays an operation wants by naming a source, such as "the author's outbox", "this pubkey's inbox", or "the relays this event was seen on". Turning a source into urls needs relay lists, the tracker, or the network. Domain code produces selections from an event, and a Resolver turns them into urls.

Route types ​

typescript
// Routes relative to an event take an `IEventRef` (see Event References).

export type RelayRoute =
  // The current user's inbox (read), outbox (write), or messaging relays.
  | {type: "userInbox"}
  | {type: "userOutbox"}
  | {type: "userMessaging"}
  // A specific pubkey's inbox (read), outbox (write), or messaging relays.
  | {type: "pubkeyInbox"; pubkey: string}
  | {type: "pubkeyOutbox"; pubkey: string}
  | {type: "pubkeyMessaging"; pubkey: string}
  // The author of a referenced event — the resolver finds the event first.
  | {type: "eventInbox"; ref: IEventRef}
  | {type: "eventOutbox"; ref: IEventRef}
  // The relays a given event was found on.
  | {type: "seen"; ref: IEventRef}
  // A literal relay url (e.g. a hint embedded in a tag, or a group relay).
  | {type: "relay"; url: string}
  // Relays that index profiles/relay-lists.
  | {type: "index"}
  // Relays configured for full-text search.
  | {type: "search"};

export type RelaySelection = {
  route: RelayRoute;
  weight: number;
};

DSL constructors ​

Each constructor returns a RelaySelection (default weight = 1), except relays and inboxes, which return RelaySelection[] (spread them with ... into a route list).

typescript
export declare const inbox: (pubkey: string, weight?: number) => RelaySelection;
export declare const outbox: (pubkey: string, weight?: number) => RelaySelection;
export declare const messaging: (pubkey: string, weight?: number) => RelaySelection;

export declare const userInbox: (weight?: number) => RelaySelection;
export declare const userOutbox: (weight?: number) => RelaySelection;
export declare const userMessaging: (weight?: number) => RelaySelection;

export declare const eventInbox: (ref: IEventRef, weight?: number) => RelaySelection;
export declare const eventOutbox: (ref: IEventRef, weight?: number) => RelaySelection;

// Relays the given event was found on (its tracker relays plus any ref hints).
export declare const seen: (ref: IEventRef, weight?: number) => RelaySelection;

// A literal relay url.
export declare const relay: (url: string, weight?: number) => RelaySelection;

// One `relay` selection per url.
export declare const relays: (urls: string[], weight?: number) => RelaySelection[];

// Inbox selections for a set of pubkeys (mentions/recipients); dedupes pubkeys.
export declare const inboxes: (pubkeys: string[], weight?: number) => RelaySelection[];

export declare const indexers: (weight?: number) => RelaySelection;
export declare const searchRelays: (weight?: number) => RelaySelection;

Example — deliver the user's note to their own outbox plus every mentioned pubkey's inbox at half weight:

typescript
const selections = [userOutbox(), ...inboxes(mentionedPubkeys, 0.5)];

RelayScenario ​

A RelayScenario scores a set of resolved, weighted relay sets and picks the best concrete urls, optionally topping up with fallback (default) relays.

typescript
// A concrete, resolved weighted relay set.
export type Selection = {
  weight: number;
  relays: string[];
};

// Filters to valid relay urls and normalizes them.
export declare const makeSelection: (relays: string[], weight?: number) => Selection;

// Fallback policies decide how many default relays to add.
export type FallbackPolicy = (count: number, limit: number) => number;
export declare const addNoFallbacks: FallbackPolicy;      // never add fallbacks
export declare const addMinimalFallbacks: FallbackPolicy; // add 1 only if none found
export declare const addMaximalFallbacks: FallbackPolicy; // fill up to the limit

export type RelayScenarioOptions = {
  policy?: FallbackPolicy;
  limit?: number;
  allowLocal?: boolean;
  allowOnion?: boolean;
  allowInsecure?: boolean;
  getRelayQuality?: (url: string) => number;
  getDefaultRelays?: () => string[];
};

export declare class RelayScenario {
  constructor(selections: Selection[], options?: RelayScenarioOptions);

  // Chainable — each returns a new scenario with merged options.
  clone(options: RelayScenarioOptions): RelayScenario;
  limit(limit: number): RelayScenario;
  policy(policy: FallbackPolicy): RelayScenario;
  allowLocal(allowLocal: boolean): RelayScenario;
  allowOnion(allowOnion: boolean): RelayScenario;
  allowInsecure(allowInsecure: boolean): RelayScenario;

  getLimit(): number;   // options.limit || 3
  getPolicy(): FallbackPolicy;  // options.policy || addNoFallbacks

  // Accumulates weight per relay across selections (filtering onion/local/insecure
  // ws:// unless allowed), scores by quality and weight with some randomness, takes
  // the best `limit`, then tops up with shuffled default relays per the policy.
  getUrls(): string[];
  getUrl(): string | undefined;  // first of getUrls()
}

Resolver ​

A Resolver combines a single route-resolver function with bound scenario options. It dereferences each route to urls and builds scenarios from selections.

typescript
export type ResolveRoute = (route: RelayRoute) => MaybeAsync<string[]>;

export declare class Resolver {
  constructor(routeResolver: ResolveRoute, options?: RelayScenarioOptions);

  // Resolve each route and build a scenario bound to this resolver's options.
  scenario(selections: RelaySelection[]): Promise<RelayScenario>;

  // Convenience wrappers.
  relays(selections: RelaySelection[]): Promise<string[]>;       // scenario(...).getUrls()
  relay(selections: RelaySelection[]): Promise<string | undefined>; // scenario(...).getUrl()
}

Example — build a resolver and route to a set of selections:

typescript
const resolver = new Resolver(resolveRoute, {
  getRelayQuality,
  getDefaultRelays,
});

const scenario = await resolver.scenario([userOutbox(), ...inboxes(pubkeys, 0.5)]);
const urls = scenario.limit(5).getUrls();

// Or skip the scenario for the common cases:
const urls2 = await resolver.relays([outbox(pubkey)]);
const url = await resolver.relay([relay(hintUrl), outbox(pubkey)]);

In @welshman/app, the Router plugin exposes a Resolver (app.use(Router).resolver) built with getRelayQuality/getDefaultRelays from app config. Domain.configure injects it into every domain kind.