--- name: nostr description: This skill should be used when working with the Nostr protocol, implementing Nostr clients or relays, handling Nostr events, or discussing Nostr Implementation Possibilities (NIPs). Provides comprehensive knowledge of Nostr's decentralized protocol, event structure, cryptographic operations, and all standard NIPs. --- # 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: ```json { "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": "", "kind": "", "tags": [ ["", "", "", "..."] ], "content": "", "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", "", "", ""]` - Reference to an event - `["p", "", ""]` - Reference to a user - `["a", "::", ""]` - Reference to a replaceable event - `["d", ""]` - Identifier for parameterized replaceable events - `["r", ""]` - Reference\/link to a web resource - `["t", ""]` - Hashtag - `["g", ""]` - Geolocation - `["nonce", "", ""]` - Proof of work - `["subject", ""]` - Subject\/title - `["client", ""]` - 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 (challenge) - Client responds with event kind `22242` signed auth event - Proves key ownership **CRITICAL: Clients MUST wait for OK response after AUTH** - Relays MUST respond to AUTH with an OK message (same as EVENT) - An OK with `true` confirms the relay has stored the authenticated pubkey - An OK with `false` indicates authentication failed: 1. **Alert the user** that authentication failed 2. **Assume the relay will reject** subsequent events requiring auth 3. Check the `reason` field for error details (e.g., "error: failed to parse auth event") - Do NOT send events requiring authentication until OK `true` is received - If no OK is received within timeout, assume connection issues and retry or alert user #### 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: ```json ["EVENT", ] ``` **REQ** - Request events (subscription): ```json ["REQ", , , , ...] ``` **CLOSE** - Stop a subscription: ```json ["CLOSE", ] ``` **AUTH** - Respond to auth challenge: ```json ["AUTH", ] ``` #### From Relay to Client **EVENT** - Send event to client: ```json ["EVENT", , ] ``` **OK** - Acceptance\/rejection notice: ```json ["OK", , , ] ``` **EOSE** - End of stored events: ```json ["EOSE", ] ``` **CLOSED** - Subscription closed: ```json ["CLOSED", , ] ``` **NOTICE** - Human-readable message: ```json ["NOTICE", ] ``` **AUTH** - Authentication challenge: ```json ["AUTH", ] ``` ### Filter Objects Filters select events in REQ messages: ```json { "ids": ["", ...], "authors": ["", ...], "kinds": [, ...], "#e": ["", ...], "#p": ["", ...], "#a": ["", ...], "#t": ["", ...], "since": , "until": , "limit": } ``` Filtering rules: - Arrays are ORed together - Different fields are ANDed - Tag filters: `#` 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: ```json [ 0, , , , , ] ``` ### 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 ```javascript 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 ```javascript const filter = { kinds: [1], authors: [followedPubkey1, followedPubkey2], limit: 50 } ws.send(JSON.stringify(["REQ", "my-sub", filter])) ``` ### Replying to a Note ```javascript const reply = { kind: 1, tags: [ ["e", originalEventId, relayUrl, "root"], ["p", originalAuthorPubkey] ], content: "Great post!", \/\/ ... other fields } ``` ### Reacting to a Note ```javascript 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