Add Nostr Protocol Skill and Reference Materials

- Introduced a comprehensive skill for the Nostr protocol, covering client and relay implementation, event structure, cryptographic operations, and best practices. - Added detailed reference files including an overview of NIPs, event kinds, common mistakes, and a complete guide to the Nostr protocol. - Included quick start examples and a checklist for implementing Nostr features effectively. - Ensured documentation is aligned with the latest standards and practices for Nostr development.
2025-11-04 12:54:41 +00:00
parent f1c636db41
commit effb3fafc1
5 changed files with 2799 additions and 0 deletions
--- a/.claude/skills/nostr/references/event-kinds.md
+++ b/.claude/skills/nostr/references/event-kinds.md
@@ -0,0 +1,361 @@
+# Nostr Event Kinds - Complete Reference
+
+This document provides a comprehensive list of all standard and commonly-used Nostr event kinds.
+
+## Standard Event Kinds
+
+### Core Events (0-999)
+
+#### Metadata and Profile
+- **0**: `Metadata` - User profile information (name, about, picture, etc.)
+  - Replaceable
+  - Content: JSON with profile fields
+
+#### Text Content
+- **1**: `Text Note` - Short-form post (like a tweet)
+  - Regular event (not replaceable)
+  - Most common event type
+
+#### Relay Recommendations
+- **2**: `Recommend Relay` - Deprecated, use NIP-65 instead
+
+#### Contact Lists
+- **3**: `Contacts` - Following list with optional relay hints
+  - Replaceable
+  - Tags: `p` tags for each followed user
+
+#### Encrypted Messages
+- **4**: `Encrypted Direct Message` - Private message (NIP-04, deprecated)
+  - Regular event
+  - Use NIP-44 instead for better security
+
+#### Content Management
+- **5**: `Event Deletion` - Request to delete events
+  - Tags: `e` tags for events to delete
+  - Only works for own events
+
+#### Sharing
+- **6**: `Repost` - Share another event
+  - Tags: `e` for reposted event, `p` for original author
+  - May include original event in content
+
+#### Reactions
+- **7**: `Reaction` - Like, emoji reaction to event
+  - Content: "+" or emoji
+  - Tags: `e` for reacted event, `p` for author
+
+### Channel Events (40-49)
+
+- **40**: `Channel Creation` - Create a public chat channel
+- **41**: `Channel Metadata` - Set channel name, about, picture
+- **42**: `Channel Message` - Post message in channel
+- **43**: `Channel Hide Message` - Hide a message in channel
+- **44**: `Channel Mute User` - Mute a user in channel
+
+### Regular Events (1000-9999)
+
+Regular events are never deleted or replaced. All versions are kept.
+
+- **1000**: `Example regular event`
+- **1063**: `File Metadata` (NIP-94) - Metadata for shared files
+  - Tags: url, MIME type, hash, size, dimensions
+
+### Replaceable Events (10000-19999)
+
+Only the latest event of each kind is kept per pubkey.
+
+- **10000**: `Mute List` - List of muted users/content
+- **10001**: `Pin List` - Pinned events
+- **10002**: `Relay List Metadata` (NIP-65) - User's preferred relays
+  - Critical for routing
+  - Tags: `r` with relay URLs and read/write markers
+
+### Ephemeral Events (20000-29999)
+
+Not stored by relays, only forwarded once.
+
+- **20000**: `Example ephemeral event`
+- **21000**: `Typing Indicator` - User is typing
+- **22242**: `Client Authentication` (NIP-42) - Auth response to relay
+
+### Parameterized Replaceable Events (30000-39999)
+
+Replaced based on `d` tag value.
+
+#### Lists (30000-30009)
+- **30000**: `Categorized People List` - Custom people lists
+  - `d` tag: list identifier
+  - `p` tags: people in list
+
+- **30001**: `Categorized Bookmark List` - Bookmark collections
+  - `d` tag: list identifier
+  - `e` or `a` tags: bookmarked items
+
+- **30008**: `Badge Definition` (NIP-58) - Define a badge/achievement
+  - `d` tag: badge ID
+  - Tags: name, description, image
+
+- **30009**: `Profile Badges` (NIP-58) - Badges displayed on profile
+  - `d` tag: badge ID
+  - `e` or `a` tags: badge awards
+
+#### Long-form Content (30023)
+- **30023**: `Long-form Article` (NIP-23) - Blog post, article
+  - `d` tag: article identifier (slug)
+  - Tags: title, summary, published_at, image
+  - Content: Markdown
+
+#### Application Data (30078)
+- **30078**: `Application-specific Data` (NIP-78)
+  - `d` tag: app-name:data-key
+  - Content: app-specific data (may be encrypted)
+
+#### Other Parameterized Replaceables
+- **31989**: `Application Handler Information` (NIP-89)
+  - Declares app can handle certain event kinds
+
+- **31990**: `Handler Recommendation` (NIP-89)
+  - User's preferred apps for event kinds
+
+## Special Event Kinds
+
+### Authentication & Signing
+- **22242**: `Client Authentication` - Prove key ownership to relay
+- **24133**: `Nostr Connect` - Remote signer protocol (NIP-46)
+
+### Lightning & Payments
+- **9734**: `Zap Request` (NIP-57) - Request Lightning payment
+  - Not published to regular relays
+  - Sent to LNURL provider
+
+- **9735**: `Zap Receipt` (NIP-57) - Proof of Lightning payment
+  - Published by LNURL provider
+  - Proves zap was paid
+
+- **23194**: `Wallet Request` (NIP-47) - Request wallet operation
+- **23195**: `Wallet Response` (NIP-47) - Response to wallet request
+
+### Content & Annotations
+- **1984**: `Reporting` (NIP-56) - Report content/users
+  - Tags: reason (spam, illegal, etc.)
+
+- **9802**: `Highlights` (NIP-84) - Highlight text
+  - Content: highlighted text
+  - Tags: context, source event
+
+### Badges & Reputation
+- **8**: `Badge Award` (NIP-58) - Award a badge to someone
+  - Tags: `a` for badge definition, `p` for recipient
+
+### Generic Events
+- **16**: `Generic Repost` (NIP-18) - Repost any event kind
+  - More flexible than kind 6
+
+- **27235**: `HTTP Auth` (NIP-98) - Authenticate HTTP requests
+  - Tags: URL, method
+
+## Event Kind Ranges Summary
+
+| Range | Type | Behavior | Examples |
+|-------|------|----------|----------|
+| 0-999 | Core | Varies | Metadata, notes, reactions |
+| 1000-9999 | Regular | Immutable, all kept | File metadata |
+| 10000-19999 | Replaceable | Only latest kept | Mute list, relay list |
+| 20000-29999 | Ephemeral | Not stored | Typing, presence |
+| 30000-39999 | Parameterized Replaceable | Replaced by `d` tag | Articles, lists, badges |
+
+## Event Lifecycle
+
+### Regular Events (1000-9999)
+```
+Event A published → Stored
+Event A' published → Both A and A' stored
+```
+
+### Replaceable Events (10000-19999)
+```
+Event A published → Stored
+Event A' published (same kind, same pubkey) → A deleted, A' stored
+```
+
+### Parameterized Replaceable Events (30000-39999)
+```
+Event A (d="foo") published → Stored
+Event B (d="bar") published → Both stored (different d)
+Event A' (d="foo") published → A deleted, A' stored (same d)
+```
+
+### Ephemeral Events (20000-29999)
+```
+Event A published → Forwarded to subscribers, NOT stored
+```
+
+## Common Patterns
+
+### Metadata (Kind 0)
+```json
+{
+  "kind": 0,
+  "content": "{\"name\":\"Alice\",\"about\":\"Nostr user\",\"picture\":\"https://...\",\"nip05\":\"alice@example.com\"}",
+  "tags": []
+}
+```
+
+### Text Note (Kind 1)
+```json
+{
+  "kind": 1,
+  "content": "Hello Nostr!",
+  "tags": [
+    ["t", "nostr"],
+    ["t", "hello"]
+  ]
+}
+```
+
+### Reply (Kind 1 with thread tags)
+```json
+{
+  "kind": 1,
+  "content": "Great post!",
+  "tags": [
+    ["e", "<root-event-id>", "<relay>", "root"],
+    ["e", "<parent-event-id>", "<relay>", "reply"],
+    ["p", "<author-pubkey>"]
+  ]
+}
+```
+
+### Reaction (Kind 7)
+```json
+{
+  "kind": 7,
+  "content": "+",
+  "tags": [
+    ["e", "<reacted-event-id>"],
+    ["p", "<event-author-pubkey>"],
+    ["k", "1"]
+  ]
+}
+```
+
+### Long-form Article (Kind 30023)
+```json
+{
+  "kind": 30023,
+  "content": "# My Article\n\nContent here...",
+  "tags": [
+    ["d", "my-article-slug"],
+    ["title", "My Article"],
+    ["summary", "This is about..."],
+    ["published_at", "1234567890"],
+    ["t", "nostr"],
+    ["image", "https://..."]
+  ]
+}
+```
+
+### Relay List (Kind 10002)
+```json
+{
+  "kind": 10002,
+  "content": "",
+  "tags": [
+    ["r", "wss://relay1.com"],
+    ["r", "wss://relay2.com", "write"],
+    ["r", "wss://relay3.com", "read"]
+  ]
+}
+```
+
+### Zap Request (Kind 9734)
+```json
+{
+  "kind": 9734,
+  "content": "",
+  "tags": [
+    ["relays", "wss://relay1.com", "wss://relay2.com"],
+    ["amount", "21000"],
+    ["lnurl", "lnurl..."],
+    ["p", "<recipient-pubkey>"],
+    ["e", "<event-id>"]
+  ]
+}
+```
+
+### File Metadata (Kind 1063)
+```json
+{
+  "kind": 1063,
+  "content": "My photo from the trip",
+  "tags": [
+    ["url", "https://cdn.example.com/image.jpg"],
+    ["m", "image/jpeg"],
+    ["x", "abc123..."],
+    ["size", "524288"],
+    ["dim", "1920x1080"],
+    ["blurhash", "LEHV6n..."]
+  ]
+}
+```
+
+### Report (Kind 1984)
+```json
+{
+  "kind": 1984,
+  "content": "This is spam",
+  "tags": [
+    ["e", "<reported-event-id>", "<relay>"],
+    ["p", "<reported-pubkey>"],
+    ["report", "spam"]
+  ]
+}
+```
+
+## Future Event Kinds
+
+The event kind space is open-ended. New NIPs may define new event kinds.
+
+**Guidelines for new event kinds**:
+1. Use appropriate range for desired behavior
+2. Document in a NIP
+3. Implement in at least 2 clients and 1 relay
+4. Ensure backwards compatibility
+5. Don't overlap with existing kinds
+
+**Custom event kinds**:
+- Applications can use undefined event kinds
+- Document behavior for interoperability
+- Consider proposing as a NIP if useful broadly
+
+## Event Kind Selection Guide
+
+**Choose based on lifecycle needs**:
+
+- **Regular (1000-9999)**: When you need history
+  - User posts, comments, reactions
+  - Payment records, receipts
+  - Immutable records
+
+- **Replaceable (10000-19999)**: When you need latest state
+  - User settings, preferences
+  - Mute/block lists
+  - Current status
+
+- **Ephemeral (20000-29999)**: When you need real-time only
+  - Typing indicators
+  - Online presence
+  - Temporary notifications
+
+- **Parameterized Replaceable (30000-39999)**: When you need multiple latest states
+  - Articles (one per slug)
+  - Product listings (one per product ID)
+  - Configuration sets (one per setting name)
+
+## References
+
+- NIPs Repository: https://github.com/nostr-protocol/nips
+- NIP-16: Event Treatment
+- NIP-01: Event structure
+- Various feature NIPs for specific kinds
+