davenov:cc:expert-build-nostr

<essential_principles>

How Nostr Works

Nostr is a decentralized protocol for real-time data exchange. Understanding these fundamentals is critical for every implementation.

1. Events Are Everything

The entire protocol has ONE data type: the Event. Every piece of data - messages, profiles, reactions, custom app data - is an Event with this structure:

interface Event {
  id: string        // SHA256 hash of serialized event
  pubkey: string    // 32-byte hex public key of creator
  created_at: number // Unix timestamp (seconds)
  kind: number      // Event type (0-65535)
  tags: string[][]  // Array of tag arrays
  content: string   // Payload (often JSON stringified)
  sig: string       // Schnorr signature
}

Every event is cryptographically signed. Authenticity is verified by signature, not by the relay.

2. Kind Numbers Define Behavior

Kind numbers determine how relays store events and how clients interpret them:

For data exchange between apps: Use ephemeral kinds (20000-29999) for transient messages, addressable kinds (30000+) for stateful data.

3. Relays Are Dumb Pipes

Relays are WebSocket servers that store and forward events. They:

• •Accept events via ["EVENT", <event>]
• •Return events via subscriptions ["REQ", <sub_id>, <filter>...]
• •Do NOT communicate with each other
• •Do NOT guarantee delivery or storage

Your app must handle: Multiple relay connections, deduplication, retry logic, and failure scenarios.

4. Subscriptions Are Filters

Clients subscribe to events using filter objects:

interface Filter {
  ids?: string[]      // Specific event IDs
  authors?: string[]  // Pubkeys to match
  kinds?: number[]    // Event kinds
  since?: number      // Events after timestamp
  until?: number      // Events before timestamp
  limit?: number      // Max events to return
  "#e"?: string[]     // Events with these e-tags
  "#p"?: string[]     // Events mentioning these pubkeys
  "#<letter>"?: string[] // Any single-letter tag
}

5. Use nostr-tools for JavaScript/TypeScript

The canonical library is nostr-tools. Key imports:

// Key generation and signing
import { generateSecretKey, getPublicKey, finalizeEvent, verifyEvent } from 'nostr-tools/pure'

// Relay pool management
import { SimplePool } from 'nostr-tools/pool'

// NIP-19 encoding (npub, nsec, etc.)
import * as nip19 from 'nostr-tools/nip19'

// NIP-44 encryption
import * as nip44 from 'nostr-tools/nip44'

6. Security Is Non-Negotiable

• •NEVER expose secret keys in client-side code or logs
• •ALWAYS verify event signatures before trusting data
• •Use NIP-44 (not NIP-04) for encryption - NIP-04 is deprecated and insecure
• •Store keys securely (use NIP-46 remote signing for web apps) </essential_principles>

1. •Set up a new Nostr client/application
2. •Implement pub/sub messaging between apps
3. •Create custom event kinds for app data
4. •Add encrypted communication (DMs, private data)
5. •Connect to and manage relays
6. •Debug relay/event issues
7. •Something else

Wait for response, then read the matching workflow. </intake>

<verification_loop>

After Every Change

# 1. TypeScript compiles?
npx tsc --noEmit

# 2. Can connect to relays?
# Test with a known relay like wss://relay.damus.io

# 3. Events properly signed?
# Use verifyEvent() on created events

# 4. Subscriptions receiving data?
# Check EOSE message received

Report:

• •"Build: OK" / "Build: X errors"
• •"Relay connection: OK to X relays"
• •"Event signing: Valid"
• •"Subscription: Receiving events" </verification_loop>

<reference_index>

Domain Knowledge

All in references/:

Protocol: protocol-fundamentals.md, event-kinds.md, nips-overview.md Implementation: nostr-tools-api.md, relay-management.md Patterns: pubsub-patterns.md, data-exchange-patterns.md Security: encryption-nip44.md, key-management.md Advanced: custom-protocols.md, scaling-considerations.md </reference_index>

<workflows_index>

Workflows

All in workflows/:

<templates_index>

Templates

All in templates/: