Nostr Client Patterns

Overview

Implement robust Nostr client architecture. This skill covers the patterns agents miss: relay pool connection management, subscription state machines that correctly handle EOSE/CLOSED transitions, event deduplication across relays, optimistic UI with OK message error recovery, and reconnection with gap-free event delivery.

When to Use

• Building a Nostr client that connects to multiple relays
• Implementing relay pool management (connection lifecycle, backoff)
• Managing subscription state (loading vs live, EOSE transitions)
• Deduplicating events received from multiple relays
• Implementing optimistic UI for event publishing
• Handling OK/EOSE/CLOSED/NOTICE relay messages correctly
• Building reconnection logic that doesn't lose events
• Caching events locally for offline or fast-load scenarios

Do NOT use when:

• Constructing event JSON structures (use nostr-event-builder)
• Building relay server software (this is client-side patterns)
• Working with NIP-19 encoding/decoding (bech32 concerns)
• Designing subscription filters (use nostr-filter-designer)

Workflow

1. Design the Relay Pool

A relay pool manages WebSocket connections to multiple relays. Each relay connection has a lifecycle that must be tracked independently.

Connection states:

disconnected → connecting → connected → disconnecting → disconnected
                    ↓                        ↑
                  failed ──(backoff)──→ connecting

Key rules:

• One WebSocket per relay (NIP-01). Never open parallel connections to the same relay URL.
• Normalize relay URLs before comparing: lowercase scheme/host, remove trailing slash, default port 443 for wss.
• Track state per relay:

  { url, ws, state, retryCount, lastConnected, activeSubscriptions, pendingPublishes }

  .
• Implement connection limits (e.g., max 10 concurrent connections).
• Use NIP-65 relay lists (kind:10002) to determine which relays to connect to for each user. Write relays for fetching a user's events, read relays for fetching events that mention them.

interface RelayConnection {
  url: string;
  ws: WebSocket | null;
  state: "disconnected" | "connecting" | "connected" | "disconnecting";
  retryCount: number;
  lastConnectedAt: number | null;
  lastEoseTimestamps: Map<string, number>; // subId → timestamp
  authChallenge: string | null;
}

See references/relay-pool.md for full implementation patterns including backoff and NIP-42 auth.

2. Implement the Subscription Lifecycle

Subscriptions follow a state machine with distinct phases. Getting this wrong causes either missing events or infinite loading states.

Subscription states:

idle → loading → live → closed
                  ↑       ↓
                  └─ replacing (new REQ with same sub-id)

The lifecycle:

1. Open: Send

   ["REQ", "<sub-id>", <filters...>]

   to relay(s)
2. Loading (stored events): Receive

   ["EVENT", "<sub-id>", <event>]

   for historical matches. UI shows loading indicator.
3. EOSE received:

   ["EOSE", "<sub-id>"]

   — transition from "loading" to "live". Remove loading indicator, display stored events.
4. Live events: Continue receiving EVENTs. These are new, real-time events. Display immediately.
5. Close: Send

   ["CLOSE", "<sub-id>"]

   when the view unmounts or the subscription is no longer needed.

Critical transitions:

• EOSE is per-relay. If subscribed to 5 relays, you get 5 EOSE messages. Track EOSE per relay per subscription. Transition to "live" when ALL relays have sent EOSE (or timed out).
• Replacing: Send a new REQ with the same sub-id to change filters without closing. The relay replaces the old subscription. Reset EOSE tracking.
• CLOSED from relay:

  ["CLOSED", "<sub-id>", "<reason>"]

  means the relay terminated your subscription. Handle by reason prefix:

  • auth-required:

    → authenticate with NIP-42, then re-subscribe

  • error:

    → log error, maybe retry after backoff

  • restricted:

    → user lacks permission, don't retry
• Timeout: If a relay doesn't send EOSE within a reasonable time (e.g., 10s), treat it as EOSE for that relay to avoid infinite loading.

See references/subscription-patterns.md for state machine implementation and multi-relay coordination.

3. Deduplicate Events

The same event can arrive from multiple relays. Events have globally unique IDs (SHA-256 of serialized content), so deduplication is straightforward.

Regular events (kinds 1-9999 excluding replaceable):

const seen = new Set<string>();

function processEvent(event: NostrEvent): boolean {
  if (seen.has(event.id)) return false; // duplicate
  seen.add(event.id);
  // process event...
  return true;
}

Replaceable events (kinds 0, 3, 10000-19999):

Keep only the latest per

pubkey + kind

id

const replaceableKey = `${event.pubkey}:${event.kind}`;
const existing = replaceableStore.get(replaceableKey);
if (existing) {
  if (event.created_at < existing.created_at) return false;
  if (event.created_at === existing.created_at && event.id >= existing.id) {
    return false;
  }
}
replaceableStore.set(replaceableKey, event);

Addressable events (kinds 30000-39999):

Same as replaceable, but key includes the

d

const dTag = event.tags.find((t) => t[0] === "d")?.[1] ?? "";
const addressableKey = `${event.pubkey}:${event.kind}:${dTag}`;

Memory management: Use an LRU cache or periodic cleanup for the

seen

4. Implement Optimistic UI for Publishing

Show events immediately in the UI before relay confirmation. Handle failures gracefully.

The flow:

User action → Create event → Show in UI (optimistic) → Sign → Publish
                                                                  ↓
                                                          Wait for OK
                                                         ↙          ↘
                                                   OK:true        OK:false
                                                   Confirm        Show error
                                                                  Allow retry

Implementation:

1. Create the unsigned event from user input
2. Add to local state with status

   "pending"

3. Sign the event (NIP-07 browser extension or local key)
4. Send

   ["EVENT", <signed-event>]

   to connected relays
5. Track OK responses per relay:

   • ["OK", "<id>", true, ""]

     → mark relay as confirmed

   • ["OK", "<id>", true, "duplicate:"]

     → also success (relay already had it)

   • ["OK", "<id>", false, "reason"]

     → track failure reason
6. Update UI status:
   • At least one

     true

     → status

     "confirmed"

   • All relays responded

     false

     → status

     "failed"

     , show error, allow retry
   • Timeout (e.g., 10s) with no OK → status

     "timeout"

     , allow retry

OK message reason prefixes:

duplicate:

pow:

blocked:

rate-limited:

invalid:

restricted:

auth-required:

error:

5. Handle Reconnection

When a relay disconnects, reconnect without losing events or duplicating subscriptions.

Reconnection strategy:

1. Detect disconnect (WebSocket

   close

   or

   error

   event)
2. Set relay state to

   disconnected

3. Calculate backoff:

   min(baseDelay * 2^retryCount + jitter, maxDelay)

   • Recommended: base=1s, max=60s, jitter=0-1s random
4. After backoff, set state to

   connecting

   , open new WebSocket
5. On successful connect:
   • Reset

     retryCount

     to 0
   • Re-authenticate if relay previously required NIP-42 auth
   • Re-send all active subscriptions with

     since

     parameter set to the last EOSE timestamp for that relay + subscription
6. On failed connect: increment

   retryCount

   , go to step 3

Gap-free event delivery:

The key insight: track the

created_at

since: lastTimestamp

function reconnectSubscription(
  relay: RelayConnection,
  subId: string,
  originalFilter: Filter,
) {
  const lastSeen = relay.lastEoseTimestamps.get(subId);
  const reconnectFilter = lastSeen
    ? { ...originalFilter, since: lastSeen }
    : originalFilter;
  relay.ws.send(JSON.stringify(["REQ", subId, reconnectFilter]));
}

6. Cache Events Locally

Reduce bandwidth and improve load times by caching events.

Cache strategies:

• IndexedDB (browser): Store events by id, index by kind, pubkey, created_at. Good for offline-first clients.
• SQLite (desktop/mobile): Same schema, better query performance.
• In-memory LRU (ephemeral): For deduplication and short-term caching.

Cache-first loading pattern:

1. Load cached events matching the filter → display immediately
2. Open subscription with

   since: latestCachedTimestamp

3. Merge new events into cache and UI
4. On EOSE, cache is now up-to-date

For replaceable events: Only cache the latest version. When a newer version arrives, replace the cached entry.

Checklist

• Relay pool tracks per-relay connection state with proper lifecycle
• One WebSocket per relay URL (normalized)
• Exponential backoff with jitter on reconnection
• Subscriptions track EOSE per relay, transition loading → live correctly
• CLOSED messages handled by reason prefix (auth, error, restricted)
• Events deduplicated by id before processing
• Replaceable events keep only latest (by created_at, then lowest id)
• Optimistic UI shows events before relay confirmation
• OK messages parsed with reason prefix for error handling
• Reconnection re-subscribes with

  since

  to avoid gaps
• Event cache used for faster initial loads

Common Mistakes

event.id

created_at

id

created_at

id

duplicate:

min(base * 2^n + jitter, max)

since

since

Quick Reference

REQ

["REQ", subId, ...filters]

EVENT

["EVENT", event]

CLOSE

["CLOSE", subId]

AUTH

["AUTH", signedEvent]

EVENT

["EVENT", subId, event]

OK

["OK", eventId, bool, msg]

EOSE

["EOSE", subId]

CLOSED

["CLOSED", subId, msg]

NOTICE

["NOTICE", msg]

AUTH

["AUTH", challenge]

Key Principles

1. One connection per relay — Normalize URLs and enforce a single WebSocket per relay. Multiple connections cause duplicate events, wasted bandwidth, and violate NIP-01.

2. EOSE is the loading/live boundary — Before EOSE, you're receiving stored history. After EOSE, you're receiving live events. This distinction drives UI state (loading spinners, "new event" indicators).

3. Deduplicate before processing — Events have globally unique IDs. Check the dedup set before any processing, state updates, or UI rendering. For replaceable events, also compare

   created_at

   and

   id

   for tie-breaking.

4. Optimistic with recovery — Show events immediately, confirm via OK. Parse OK reason prefixes to distinguish retriable errors (rate-limited, auth) from permanent failures (blocked, restricted).

5. Reconnect without gaps — Track the last-seen timestamp per relay per subscription. On reconnect, use

   since

   to fetch only missed events. Always re-authenticate and re-subscribe after reconnection.