Nostr-expert: Скилл для реализации протокола Nostr

--- name: nostr-expert description: Nostr protocol implementation patterns in Quartz (AmethystMultiplatform's KMP Nostr library). Use when working with: (1) Nostr events (creating, parsing, signing), (2) Event kinds and tags, (3) NIP implementations (57 NIPs in quartz/), (4) Event builders and TagArrayBuilder DSL, (5) Nostr cryptography (secp256k1, NIP-44 encryption), (6) Relay communication patterns, (7) Bech32 encoding (npub, nsec, note, nevent). Complements nostr-protocol agent (NIP specs) - this skill provides Quartz codebase patterns and implementation details. --- # Nostr Protocol Expert (Quartz Implementation) Practical patterns for working with Nostr in Quartz, AmethystMultiplatform's KMP Nostr library. ## When to Use This Skill - Implementing Nostr event types (TextNote, Reaction, Zap, etc.) - Creating/parsing events with TagArrayBuilder DSL - Working with event kinds and tags - Finding NIP implementations in quartz/ codebase - Nostr cryptography (secp256k1 signing, NIP-44 encryption) - Bech32 encoding/decoding (npub, nsec, note formats) - Event validation and verification **For NIP specifications** → Use `nostr-protocol` agent **For Quartz implementation** → Use this skill ## Quartz Architecture Quartz organizes code by NIP number: ``` quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/ ├── nip01Core/ # Core protocol (Event, Kind, Tags) ├── nip04Dm/ # Legacy DMs (deprecated) ├── nip10Notes/ # Text notes with threading ├── nip17Dm/ # Private DMs (gift wrap) ├── nip19Bech32/ # Bech32 encoding ├── nip44Encryption/ # Modern encryption (ChaCha20) ├── nip57Zaps/ # Lightning zaps ├── ... (57 NIPs total) └── experimental/ # Draft NIPs ``` **Pattern**: `nip##<Name>/` directories contain event classes, tags, and utilities for that NIP. **Find implementations**: Use `scripts/nip-lookup.sh <nip-number>` or see `references/nip-catalog.md`. ## Event Anatomy ### Core Structure ```kotlin @Immutable open class Event( val id: HexKey, // SHA-256 hash of serialized event val pubKey: HexKey, // Author's public key (32 bytes hex) val createdAt: Long, // Unix timestamp val kind: Kind, // Event kind (Int typealias) val tags: TagArray, // Array of tag arrays val content: String, // Event content val sig: HexKey, // Schnorr signature (64 bytes hex) ) : IEvent ``` **Key insight**: `Event` is the base class. Specific event types (TextNoteEvent, ReactionEvent) extend it and add parsing/helper methods. ### Kind Classification ```kotlin typealias Kind = Int fun Kind.isEphemeral() = this in 20000..29999 // Not stored fun Kind.isReplaceable() = this == 0 || this == 3 || this in 10000..19999 fun Kind.isAddressable() = this in 30000..39999 // Replaceable + has d-tag fun Kind.isRegular() = this in 1000..9999 // Stored, not replaced ``` **Pattern**: Kind determines event lifecycle and replaceability. ## Creating Events ### EventTemplate Pattern ```kotlin fun eventTemplate( kind: Kind, content: String, tags: TagArray = emptyArray() ): EventTemplate ``` **Usage**: ```kotlin val template = eventTemplate( kind = 1, // Text note content = "Hello Nostr!", tags = tagArray { add(arrayOf("subject", "Greeting")) } ) // Sign with a signer val signedEvent = signer.sign(template) ``` **Why templates?** Separates event data from signing. Templates can be signed by different signers (local keys, remote signers, hardware wallets). ### TagArrayBuilder DSL ```kotlin fun <T : Event> tagArray( initializer: TagArrayBuilder<T>.() -> Unit ): TagArray ``` **Methods**: - `add(tag)` - Append tag - `addFirst(tag)` - Prepend tag (for ordering) - `addUnique(tag)` - Replace all tags with this name - `remove(tagName)` - Remove by name - `addAll(tags)` - Bulk add **Example**: ```kotlin val tags = tagArray<TextNoteEvent> { add(arrayOf("e", replyToEventId, "", "reply")) add(arrayOf("p", authorPubkey)) addUnique(arrayOf("subject", "Re: Hello")) add(arrayOf("content-warning", "spoilers")) } ``` **Pattern**: Fluent DSL for building tag arrays with validation and deduplication. ## Common Event Types ### TextNoteEvent (kind 1) ```kotlin class TextNoteEvent : BaseThreadedEvent ``` **Creating**: ```kotlin val note = eventTemplate( kind = 1, content = "Hello world!", tags = tagArray { add(arrayOf("subject", "First post")) } ) ``` **Parsing**: ```kotlin val event: TextNoteEvent = ... val subject = event.subject() // Extension from nip14Subject val mentions = event.mentions() // List of p-tags val quotedEvents = event.quotes() // List of q-tags ``` ### ReactionEvent (kind 7) ```kotlin fun createReaction( targetEvent: Event, emoji: String = "+" ): EventTemplate { return eventTemplate( kind = 7, content = emoji, tags = tagArray { add(arrayOf("e", targetEvent.id)) add(arrayOf("p", targetEvent.pubKey)) } ) } ``` ### MetadataEvent (kind 0) ```kotlin data class UserMetadata( val name: String?, val displayName: String?, val picture: String?, val banner: String?, val about: String?, // ... more fields ) fun createMetadata(metadata: UserMetadata): EventTemplate { return eventTemplate( kind = 0, content = metadata.toJson() // Serialize to JSON ) } ``` ### Addressable Events (kinds 30000-40000) ```kotlin fun createArticle( slug: String, title: String, content: String ): EventTemplate { return eventTemplate( kind = 30023, content = content, tags = tagArray { addUnique(arrayOf("d", slug)) // Unique identifier add(arrayOf("title", title)) add(arrayOf("published_at", "${TimeUtils.now()}")) } ) } ``` **Key**: `d-tag` makes it addressable. Events with same kind + pubkey + d-tag replace each other. ## Tag Patterns Tags are `Array<String>` with pattern `[name, value, ...optionalParams]`. ### Core Tags **e-tag** (event reference): ```kotlin add(arrayOf("e", eventId, relayHint, marker)) // marker: "reply", "root", "mention" ``` **p-tag** (pubkey reference): ```kotlin add(arrayOf("p", pubkey, relayHint)) ``` **a-tag** (addressable event): ```kotlin add(arrayOf("a", "$kind:$pubkey:$dtag", relayHint)) ``` **d-tag** (identifier for addressable events): ```kotlin addUnique(arrayOf("d", "unique-slug")) ``` ### Tag Extensions ```kotlin // Find tags event.tags.tagValue("subject") // First subject tag value event.tags.allTags("p") // All p-tags event.tags.tagValues("e") // All e-tag values // Parse structured tags event.tags.mapNotNull(ETag::parse) // Parse as ETag objects ``` For comprehensive tag patterns, see `references/tag-patterns.md`. ## Threading (NIP-10) ```kotlin fun createReply( original: TextNoteEvent, content: String ): EventTemplate { return eventTemplate( kind = 1, content = content, tags = tagArray { // Reply marker add(arrayOf("e", original.id, "", "reply")) // Root marker (original's root, or original itself) original.rootEvent()?.let { add(arrayOf("e", it.id, "", "root")) } ?: add(arrayOf("e", original.id, "", "root")) // Tag author add(arrayOf("p", original.pubKey)) // Tag all mentioned users original.mentions().forEach { add(arrayOf("p", it)) } } ) } ``` **Pattern**: `reply` and `root` markers establish thread hierarchy. ## Cryptography ### Signing (secp256k1) ```kotlin interface ISigner { suspend fun sign(template: EventTemplate): Event } // Local key signing class LocalSigner(private val privateKey: ByteArray) : ISigner { override suspend fun sign(template: EventTemplate): Event { val id = template.generateId() val sig = Secp256k1.sign(id, privateKey) return Event(id, pubKey, createdAt, kind, tags, content, sig) } } ``` **Pattern**: Signers abstract key management. Can be local, remote (NIP-46), or hardware. ### Encryption (NIP-44) ```kotlin // Modern encryption (ChaCha20-Poly1305) object Nip44v2 { fun encrypt(plaintext: String, privateKey: ByteArray, pubKey: HexKey): String fun decrypt(ciphertext: String, privateKey: ByteArray, pubKey: HexKey): String } // Usage val encrypted = Nip44v2.encrypt( plaintext = "Secret message", privateKey = myPrivateKey, pubKey = recipientPubKey ) val decrypted = Nip44v2.decrypt( ciphertext = encrypted, privateKey = myPrivateKey, pubKey = senderPubKey ) ``` **Pattern**: Elliptic curve Diffie-Hellman + ChaCha20-Poly1305 AEAD. ### NIP-04 (Deprecated) ```kotlin // Legacy encryption (NIP-04, deprecated for NIP-44) object Nip04 { fun encrypt(msg: String, privateKey: ByteArray, pubKey: HexKey): String fun decrypt(msg: String, privateKey: ByteArray, pubKey: HexKey): String } ``` **Note**: Use NIP-44 (Nip44v2) for new implementations. NIP-04 has security issues. ## Bech32 Encoding (NIP-19) ```kotlin object Nip19 { // Encode fun npubEncode(pubkey: HexKey): String // npub1... fun nsecEncode(privateKey: ByteArray): String // nsec1... fun noteEncode(eventId: HexKey): String // note1... fun neventEncode(eventId: HexKey, relays: List<String> = emptyList()): String fun nprofileEncode(pubkey: HexKey, relays: List<String> = emptyList()): String fun naddrEncode(kind: Int, pubkey: HexKey, dTag: String, relays: List<String> = emptyList()): String // Decode fun decode(bech32: String): Nip19Result } sealed class Nip19Result { data class NPub(val hex: HexKey) : Nip19Result() data class NSec(val hex: HexKey) : Nip19Result() data class Note(val hex: HexKey) : Nip19Result() data class NEvent(val hex: HexKey, val relays: List<String>) : Nip19Result() data class NProfile(val hex: HexKey, val relays: List<String>) : Nip19Result() data class NAddr(val kind: Int, val pubkey: HexKey, val dTag: String, val relays: List<String>) : Nip19Result() } ``` **Usage**: ```kotlin // Encode val npub = Nip19.npubEncode(pubkeyHex) // Output: "npub1..." // Decode when (val result = Nip19.decode(npub)) { is Nip19Result.NPub -> println("Pubkey: ${result.hex}") is Nip19Result.NEvent -> println("Event: ${result.hex}, relays: ${result.relays}") else -> println("Other type") } ``` ## Event Validation ```kotlin fun Event.verify(): Boolean { // 1. Verify ID matches content hash val computedId = generateId() if (id != computedId) return false // 2. Verify signature return Secp256k1.verify(id, sig, pubKey) } fun Event.generateId(): HexKey { val serialized = serializeForId() // JSON array format return sha256(serialized) } ``` **Pattern**: Always verify events from untrusted sources (relays). ## Common Workflows ### Publishing an Event ```kotlin suspend fun publishNote(content: String, signer: ISigner, relays: List<String>) { // 1. Create template val template = eventTemplate(kind = 1, content = content) // 2. Sign val event = signer.sign(template) // 3. Verify (optional but recommended) require(event.verify()) { "Signature verification failed" } // 4. Publish to relays relays.forEach { relay -> relayClient.send(relay, event) } } ``` ### Querying Events ```kotlin // Subscription filter data class Filter( val ids: List<HexKey>? = null, val authors: List<HexKey>? = null, val kinds: List<Kind>? = null, val since: Long? = null, val until: Long? = null, val limit: Int? = null, val tags: Map<String, List<String>>? = null // e.g., {"#e": [eventId], "#p": [pubkey]} ) // Usage val filter = Filter( authors = listOf(userPubkey), kinds = listOf(1), // Text notes only limit = 50 ) relayClient.subscribe(relay, filter) { event -> // Handle incoming events } ``` ### Creating a Zap (NIP-57) ```kotlin fun createZapRequest( targetEvent: Event, amountSats: Long, comment: String = "" ): EventTemplate { return eventTemplate( kind = 9734, // Zap request content = comment, tags = tagArray { add(arrayOf("e", targetEvent.id)) add(arrayOf("p", targetEvent.pubKey)) add(arrayOf("amount", "${amountSats * 1000}")) // millisats add(arrayOf("relays", "wss://relay1.com", "wss://relay2.com")) } ) } ``` ### Gift-Wrapped DMs (NIP-17) ```kotlin fun createGiftWrappedDM( recipientPubkey: HexKey, message: String, signer: ISigner ): Event { // 1. Create sealed gossip (kind 14) val sealedGossip = createSealedGossip(message, recipientPubkey, signer) // 2. Wrap in gift wrap (kind 1059) return createGiftWrap(sealedGossip, recipientPubkey, signer) } ``` **Pattern**: Double encryption + random ephemeral keys for metadata protection. ## Finding NIPs Use the bundled script: ```bash # Find by NIP number scripts/nip-lookup.sh 44 # Search by term scripts/nip-lookup.sh encryption scripts/nip-lookup.sh "gift wrap" ``` Or see `references/nip-catalog.md` for complete catalog. ## Bundled Resources - **references/nip-catalog.md** - All 57 NIPs with package locations and key files - **references/event-hierarchy.md** - Event class hierarchy, kind classifications, common types - **references/tag-patterns.md** - Tag structure, TagArrayBuilder DSL, common tag types, parsing patterns - **scripts/nip-lookup.sh** - Find NIP implementations by number or search term ## Quick Reference | Task | Pattern | Location | |------|---------|----------| | Create event | `eventTemplate(kind, content, tags)` | nip01Core/signers/ | | Build tags | `tagArray { add(...) }` | nip01Core/core/ | | Sign event | `signer.sign(template)` | nip01Core/signers/ | | Verify signature | `event.verify()` | nip01Core/core/ | | Encrypt (NIP-44) | `Nip44v2.encrypt(...)` | nip44Encryption/ | | Bech32 encode | `Nip19.npubEncode(...)` | nip19Bech32/ | | Find NIP | `scripts/nip-lookup.sh <number>` | - | ## Common Event Kinds | Kind | Type | NIP | Package | |------|------|-----|---------| | 0 | Metadata | 01 | nip01Core/ | | 1 | Text note | 01, 10 | nip10Notes/ | | 3 | Contact list | 02 | nip02FollowList/ | | 5 | Deletion | 09 | nip09Deletions/ | | 7 | Reaction | 25 | nip25Reactions/ | | 1059 | Gift wrap | 59 | nip59Giftwrap/ | | 9734 | Zap request | 57 | nip57Zaps/ | | 9735 | Zap receipt | 57 | nip57Zaps/ | | 10002 | Relay list | 65 | nip65RelayList/ | | 30023 | Long-form content | 23 | nip23LongContent/ | ## Related Skills - **nostr-protocol** - NIP specifications and protocol details - **kotlin-expert** - Kotlin patterns (@Immutable, sealed classes, DSLs) - **kotlin-coroutines** - Async patterns for relay communication - **kotlin-multiplatform** - KMP patterns, expect/actual in Quartz