client

A nostr web application framework built on NDK (Nostr Development Kit). Uses a SharedWorker architecture where a single NDK instance manages all relay connections, caching, and subscriptions across multiple browser tabs.

Architecture Overview

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  index.html  │  │  post.html   │  │  cashu.html  │  ... (any page)
│  init-ndk.mjs│  │  init-ndk.mjs│  │  init-ndk.mjs│
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │ postMessage      │                 │
       └─────────────┬────┘─────────────────┘
                     ▼
            ┌─────────────────┐
            │  ndk-worker.js   │  (SharedWorker — single instance)
            │  ┌─────────────┐ │
            │  │  NDK         │ │
            │  │  + Dexie     │ │  ← IndexedDB cache (ndk-shared)
            │  │  + Signer    │ │
            │  └──────┬──────┘ │
            └─────────┼────────┘
                      ▼
         ┌────────────────────────┐
         │    Nostr Relay Pool     │
         │  wss://relay1  relay2   │
         └────────────────────────┘

Event Management Strategy

This section defines when and how nostr events are fetched, cached, and subscribed to. It serves as the single source of truth for event lifecycle management.

Cache Behavior

All events flowing through NDK are automatically cached in IndexedDB via the Dexie adapter (database: ndk-shared). This means:

• Any ndk.fetchEvents() call caches results automatically
• Any subscription event received is cached via cacheAdapter.setEvent()
• Pages can query the cache directly via queryCache() without hitting relays
• NDK's CACHE_FIRST mode returns cached data immediately, then updates from relays

Startup Events (fetched by worker on init)

These events are fetched once during handleInit() when the first tab connects. They populate the Dexie cache and provide essential app-wide state.

Priority	Kind	NIP	Name	Filter	Subscription	Purpose
1	0	NIP-01	User Metadata	authors:[pubkey]	No — one-shot	Profile display (name, picture, about)
2	10002	NIP-65	Relay List	authors:[pubkey], limit:1	Yes — persistent closeOnEose:false	Configure relay pool; live updates
3	30078	NIP-78	App Settings	authors:[pubkey], #d:[user-settings]	No — one-shot	Encrypted user preferences (NIP-44)
4	17375	NIP-60	Cashu Wallet	authors:[pubkey]	Yes — startup fetch + persistent	Wallet metadata, mint list, and live wallet changes
5	7375	NIP-60	Cashu Tokens	authors:[pubkey]	Yes — startup fetch + persistent	Unspent proofs and live token changes
6	5	NIP-09	Event Deletion	authors:[pubkey], #k:[7375]	Yes — startup fetch + persistent	Track spent/deleted tokens

Startup sequence (current implementation):

handleInit(pubkey)
  ├── initNDK()                           // Create NDK, connect relays
  ├── hydrateUserSettingsForPubkey()      // kind 30078
  ├── fetchUserProfile()                  // kind 0
  ├── fetchUserRelays()                   // kind 10002 (one-shot)
  ├── subscribe kind 10002                // persistent relay list updates
  ├── fetchStartupEventDownloads()        // one-shot preload: kinds 3, 17375, 7375, 5(#k=7375)
  └── ensureStartupWalletSubscriptions()  // persistent wallet subscriptions: 17375, 7375, 5(#k=7375)

This means wallet information is not only prefetched at startup; it is now also continuously updated by long-lived worker subscriptions.

On-Demand Events (fetched by individual pages)

These events are fetched when a specific page loads. They benefit from the Dexie cache — if the same events were previously fetched, they're served from cache first.

Kind	NIP	Name	Pages	Pattern
0	NIP-01	User Metadata	profile, msg, post, npub	fetchEventsFromAllRelays or subscribe
1	NIP-01	Short Text Notes	post, index, links, strudel, template	subscribe with CACHE_FIRST
3	NIP-02	Contact List	post, profile, cashu	subscribe + queryCache + fetchEventsFromAllRelays
4	NIP-04	Encrypted DMs	msg	subscribe with CACHE_FIRST
1059	NIP-44	Gift Wrap (DMs)	msg	subscribe with CACHE_FIRST
5	NIP-09	Event Deletion	(via startup sub)	Persistent subscription
7	NIP-25	Reactions	post (via interactions)	fetchEventsFromAllRelays
6	NIP-18	Reposts	post (via interactions)	fetchEventsFromAllRelays
9735	NIP-57	Zap Receipts	post (via interactions)	fetchEventsFromAllRelays
10019	NIP-60	Mint List	cashu (mint discovery)	fetchEventsFromAllRelays
10063	NIP-96	Blossom Server List	blobs	subscribe with CACHE_FIRST
17375	NIP-60	Cashu Wallet	cashu (full wallet ops)	Via NDKCashuWallet
7375	NIP-60	Cashu Tokens	cashu (full wallet ops)	Via NDKCashuWallet (cache-first)
7376	NIP-60	Spending History	cashu (transaction list)	Via NDKCashuWallet
30023	NIP-23	Long-form Content	note	subscribe with CACHE_FIRST
30024	NIP-23	Draft Long-form	note	subscribe with CACHE_FIRST
30078	NIP-78	App-specific Data	todo, cal, links, post (viewed)	subscribe or fetchEvents
38000	NIP-89	Recommendations	cashu (mint discovery)	fetchEventsFromAllRelays
38421	—	AI Service Announcements	ai	subscribe with CACHE_FIRST

Subscription Patterns

The app uses three distinct patterns for fetching events:

1. One-shot Fetch

// Fetch once, cache result, done
const events = await ndk.fetchEvents(filter);

Used for: startup profile, relay list, wallet definition, user settings

2. Subscribe with CACHE_FIRST

// Returns cached events immediately, then live events from relays
subscribe(filter, { closeOnEose: false, cacheUsage: 'CACHE_FIRST' });

Used for: most page-level subscriptions (posts, contacts, notes, DMs)

3. Persistent Worker Subscription

// Long-lived subscription in the worker, survives page navigation
ndk.subscribe(filter, { closeOnEose: false });

Used for: relay list updates (kind 10002), wallet metadata (kind 17375), token events (kind 7375), and token deletions (kind 5 with #k=7375)

Cache-First Advantage

Because startup events are fetched early and cached in Dexie, subsequent page loads benefit:

• post.html subscribes to kind 3 (contacts) → if profile.html already fetched it, cache hit
• cashu.html starts NDKCashuWallet → kind 7375 tokens already in cache from startup → instant optimistic balance
• Any page fetching kind 0 (profile) → already cached from startup

Modifying Event Timing

To change when an event kind is fetched:

1. Move to startup: Add the fetch to fetchStartupWalletState() or create a new startup function in handleInit(). This pre-populates the cache for all pages.

2. Move to on-demand: Remove from startup, let individual pages fetch as needed. First load will be slower but startup will be faster.

3. Add a subscription: For events that change frequently, add a persistent subscription in the worker. This keeps the cache fresh without page-level polling.

Trade-offs:

• More startup events = slower initial load, faster page navigation
• Fewer startup events = faster initial load, slower first page that needs the data
• Persistent subscriptions = always fresh data, more relay bandwidth

Project Structure

www/
├── ndk-worker.js          # SharedWorker — NDK instance, cache, subscriptions
├── js/
│   ├── init-ndk.mjs       # Client-side NDK API (shared by all pages)
│   ├── relay-ui.mjs       # Footer relay status + balance display
│   ├── cashu-wallet.mjs   # Cashu wallet controller (cashu.html only)
│   ├── post-interactions.mjs  # Social interactions (reactions, reposts, zaps)
│   └── utilities.mjs      # Shared utilities
├── css/client.css          # Shared styles
├── *.html                  # Individual pages
└── ndk-core.bundle.js      # Bundled NDK library

build/
├── ndk-entry.js            # Bundle entry point
└── ndk-core.bundle.js      # Built bundle

ndk/                        # NDK source (submodule/clone)
├── core/                   # Core NDK library
├── wallet/                 # Cashu wallet implementation
├── cache-browser/          # Browser cache adapter
├── cache-dexie/            # Dexie (IndexedDB) cache
└── ...

plans/                      # Architecture and implementation plans

Building

# Build the NDK bundle
node build-ndk-bundle.js

# Serve locally
python serve_local.py