Nostr Protocol Expert

Purpose

This skill provides expert-level assistance with the Nostr protocol, a simple, open protocol for global, decentralized, and censorship-resistant social networks. The protocol is built on relays and cryptographic keys, enabling direct peer-to-peer communication without central servers.

When to Use

Activate this skill when:

• •Implementing Nostr clients or relays
• •Working with Nostr events and messages
• •Handling cryptographic signatures and keys (schnorr signatures on secp256k1)
• •Implementing any Nostr Implementation Possibility (NIP)
• •Building social networking features on Nostr
• •Querying or filtering Nostr events
• •Discussing Nostr protocol architecture
• •Implementing WebSocket communication with relays

Core Concepts

The Protocol Foundation

Nostr operates on two main components:

1. •Clients - Applications users run to read/write data
2. •Relays - Servers that store and forward messages

Key principles:

• •Everyone runs a client
• •Anyone can run a relay
• •Users identified by public keys
• •Messages signed with private keys
• •No central authority or trusted servers

Events Structure

All data in Nostr is represented as events. An event is a JSON object with this structure:

{
  "id": "<32-bytes lowercase hex-encoded sha256 of the serialized event data>",
  "pubkey": "<32-bytes lowercase hex-encoded public key of the event creator>",
  "created_at": "<unix timestamp in seconds>",
  "kind": "<integer identifying event type>",
  "tags": [
    ["<tag name>", "<tag value>", "<optional third param>", "..."]
  ],
  "content": "<arbitrary string>",
  "sig": "<64-bytes lowercase hex of the schnorr signature of the sha256 hash of the serialized event data>"
}

Event Kinds

Standard event kinds (from various NIPs):

• •0 - Metadata (user profile)
• •1 - Text note (short post)
• •2 - Recommend relay
• •3 - Contacts (following list)
• •4 - Encrypted direct messages
• •5 - Event deletion
• •6 - Repost
• •7 - Reaction (like, emoji reaction)
• •40 - Channel creation
• •41 - Channel metadata
• •42 - Channel message
• •43 - Channel hide message
• •44 - Channel mute user
• •1000-9999 - Regular events
• •10000-19999 - Replaceable events
• •20000-29999 - Ephemeral events
• •30000-39999 - Parameterized replaceable events

Tags

Common tag types:

• •["e", "<event-id>", "<relay-url>", "<marker>"] - Reference to an event
• •["p", "<pubkey>", "<relay-url>"] - Reference to a user
• •["a", "<kind>:<pubkey>:<d-tag>", "<relay-url>"] - Reference to a replaceable event
• •["d", "<identifier>"] - Identifier for parameterized replaceable events
• •["r", "<url>"] - Reference/link to a web resource
• •["t", "<hashtag>"] - Hashtag
• •["g", "<geohash>"] - Geolocation
• •["nonce", "<number>", "<difficulty>"] - Proof of work
• •["subject", "<subject>"] - Subject/title
• •["client", "<client-name>"] - Client application used

Key NIPs Reference

For detailed specifications, refer to references/nips-overview.md.

Core Protocol NIPs

NIP-01: Basic Protocol Flow

The foundation of Nostr. Defines:

• •Event structure and validation
• •Event ID calculation (SHA256 of serialized event)
• •Signature verification (schnorr signatures)
• •Client-relay communication via WebSocket
• •Message types: EVENT, REQ, CLOSE, EOSE, OK, NOTICE

NIP-02: Contact List and Petnames

Event kind 3 for following lists:

• •Each p tag represents a followed user
• •Optional relay URL and petname in tag
• •Replaceable event (latest overwrites)

NIP-04: Encrypted Direct Messages

Event kind 4 for private messages:

• •Content encrypted with shared secret (ECDH)
• •p tag for recipient pubkey
• •Deprecated in favor of NIP-44

NIP-05: Mapping Nostr Keys to DNS

Internet identifier format: name@domain.com

• •.well-known/nostr.json endpoint
• •Maps names to pubkeys
• •Optional relay list

NIP-09: Event Deletion

Event kind 5 to request deletion:

• •Contains e tags for events to delete
• •Relays should delete referenced events
• •Only works for own events

NIP-10: Text Note References (Threads)

Conventions for e and p tags in replies:

• •Root event reference
• •Reply event reference
• •Mentions
• •Marker types: "root", "reply", "mention"

NIP-11: Relay Information Document

HTTP endpoint for relay metadata:

• •GET request to relay URL
• •Returns JSON with relay information
• •Supported NIPs, software, limitations

Social Features NIPs

NIP-25: Reactions

Event kind 7 for reactions:

• •Content usually "+" (like) or emoji
• •e tag for reacted event
• •p tag for event author

NIP-42: Authentication

Client authentication to relays:

• •AUTH message from relay
• •Client responds with event kind 22242
• •Proves key ownership

NIP-50: Search

Query filter extension for full-text search:

• •search field in REQ filters
• •Implementation-defined behavior

Advanced NIPs

NIP-19: bech32-encoded Entities

Human-readable identifiers:

• •npub: public key
• •nsec: private key (sensitive!)
• •note: note/event ID
• •nprofile: profile with relay hints
• •nevent: event with relay hints
• •naddr: replaceable event coordinate

NIP-44: Encrypted Payloads

Improved encryption for direct messages:

• •Versioned encryption scheme
• •Better security than NIP-04
• •ChaCha20-Poly1305 AEAD

NIP-65: Relay List Metadata

Event kind 10002 for relay lists:

• •Read/write relay preferences
• •Optimizes relay discovery
• •Replaceable event

Client-Relay Communication

WebSocket Messages

From Client to Relay

EVENT - Publish an event:

["EVENT", <event JSON>]

REQ - Request events (subscription):

["REQ", <subscription_id>, <filters JSON>, <filters JSON>, ...]

CLOSE - Stop a subscription:

["CLOSE", <subscription_id>]

AUTH - Respond to auth challenge:

["AUTH", <signed event kind 22242>]

From Relay to Client

EVENT - Send event to client:

["EVENT", <subscription_id>, <event JSON>]

OK - Acceptance/rejection notice:

["OK", <event_id>, <true|false>, <message>]

EOSE - End of stored events:

["EOSE", <subscription_id>]

CLOSED - Subscription closed:

["CLOSED", <subscription_id>, <message>]

NOTICE - Human-readable message:

["NOTICE", <message>]

AUTH - Authentication challenge:

["AUTH", <challenge>]

Filter Objects

Filters select events in REQ messages:

{
  "ids": ["<event-id>", ...],
  "authors": ["<pubkey>", ...],
  "kinds": [<kind number>, ...],
  "#e": ["<event-id>", ...],
  "#p": ["<pubkey>", ...],
  "#a": ["<coordinate>", ...],
  "#t": ["<hashtag>", ...],
  "since": <unix timestamp>,
  "until": <unix timestamp>,
  "limit": <max number of events>
}

Filtering rules:

• •Arrays are ORed together
• •Different fields are ANDed
• •Tag filters: #<single-letter> matches tag values
• •Prefix matching allowed for ids and authors

Cryptographic Operations

Key Management

• •Private Key: 32-byte random value, keep secure
• •Public Key: Derived via secp256k1
• •Encoding: Hex (lowercase) or bech32

Event Signing (schnorr)

Steps to create a signed event:

1. •Set all fields except id and sig
2. •Serialize event data to JSON (specific order)
3. •Calculate SHA256 hash → id
4. •Sign id with schnorr signature → sig

Serialization format for ID calculation:

[
  0,
  <pubkey>,
  <created_at>,
  <kind>,
  <tags>,
  <content>
]

Event Verification

Steps to verify an event:

1. •Verify ID matches SHA256 of serialized data
2. •Verify signature is valid schnorr signature
3. •Check created_at is reasonable (not far future)
4. •Validate event structure and required fields

Implementation Best Practices

For Clients

1. •Connect to Multiple Relays: Don't rely on single relay
2. •Cache Events: Reduce redundant relay queries
3. •Verify Signatures: Always verify event signatures
4. •Handle Replaceable Events: Keep only latest version
5. •Respect User Privacy: Careful with sensitive data
6. •Implement NIP-65: Use user's preferred relays
7. •Proper Error Handling: Handle relay disconnections
8. •Pagination: Use limit, since, until for queries

For Relays

1. •Validate Events: Check signatures, IDs, structure
2. •Rate Limiting: Prevent spam and abuse
3. •Storage Management: Ephemeral events, retention policies
4. •Implement NIP-11: Provide relay information
5. •WebSocket Optimization: Handle many connections
6. •Filter Optimization: Efficient event querying
7. •Consider NIP-42: Authentication for write access
8. •Performance: Index by pubkey, kind, tags, timestamp

Security Considerations

1. •Never Expose Private Keys: Handle nsec carefully
2. •Validate All Input: Prevent injection attacks
3. •Use NIP-44: For encrypted messages (not NIP-04)
4. •Check Event Timestamps: Reject far-future events
5. •Implement Proof of Work: NIP-13 for spam prevention
6. •Sanitize Content: XSS prevention in displayed content
7. •Relay Trust: Don't trust single relay for critical data

Common Patterns

Publishing a Note

const event = {
  pubkey: userPublicKey,
  created_at: Math.floor(Date.now() / 1000),
  kind: 1,
  tags: [],
  content: "Hello Nostr!",
}
// Calculate ID and sign
event.id = calculateId(event)
event.sig = signEvent(event, privateKey)
// Publish to relay
ws.send(JSON.stringify(["EVENT", event]))

Subscribing to Notes

const filter = {
  kinds: [1],
  authors: [followedPubkey1, followedPubkey2],
  limit: 50
}
ws.send(JSON.stringify(["REQ", "my-sub", filter]))

Replying to a Note

const reply = {
  kind: 1,
  tags: [
    ["e", originalEventId, relayUrl, "root"],
    ["p", originalAuthorPubkey]
  ],
  content: "Great post!",
  // ... other fields
}

Reacting to a Note

const reaction = {
  kind: 7,
  tags: [
    ["e", eventId],
    ["p", eventAuthorPubkey]
  ],
  content: "+", // or emoji
  // ... other fields
}

Development Resources

Essential NIPs for Beginners

Start with these NIPs in order:

1. •NIP-01 - Basic protocol (MUST read)
2. •NIP-19 - Bech32 identifiers
3. •NIP-02 - Following lists
4. •NIP-10 - Threaded conversations
5. •NIP-25 - Reactions
6. •NIP-65 - Relay lists

Testing and Development

• •Relay Implementations: nostream, strfry, relay.py
• •Test Relays: wss://relay.damus.io, wss://nos.lol
• •Libraries: nostr-tools (JS), rust-nostr (Rust), python-nostr (Python)
• •Development Tools: NostrDebug, Nostr Army Knife, nostril
• •Reference Clients: Damus (iOS), Amethyst (Android), Snort (Web)

Key Repositories

• •NIPs Repository: https://github.com/nostr-protocol/nips
• •Awesome Nostr: https://github.com/aljazceru/awesome-nostr
• •Nostr Resources: https://nostr.how

Reference Files

For comprehensive NIP details, see:

• •references/nips-overview.md - Detailed descriptions of all standard NIPs
• •references/event-kinds.md - Complete event kinds reference
• •references/common-mistakes.md - Pitfalls and how to avoid them

Quick Checklist

When implementing Nostr:

• • Events have all required fields (id, pubkey, created_at, kind, tags, content, sig)
• • Event IDs calculated correctly (SHA256 of serialization)
• • Signatures verified (schnorr on secp256k1)
• • WebSocket messages properly formatted
• • Filter queries optimized with appropriate limits
• • Handling replaceable events correctly
• • Connected to multiple relays for redundancy
• • Following relevant NIPs for features implemented
• • Private keys never exposed or transmitted
• • Event timestamps validated

Official Resources

• •NIPs Repository: https://github.com/nostr-protocol/nips
• •Nostr Website: https://nostr.com
• •Nostr Documentation: https://nostr.how
• •NIP Status: https://nostr-nips.com