nostr-expert

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 (80+ NIP packages 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

@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

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

fun eventTemplate(
    kind: Kind,
    content: String,
    tags: TagArray = emptyArray()
): EventTemplate

Usage:

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

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:

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)

class TextNoteEvent : BaseThreadedEvent

Creating:

val note = eventTemplate(
    kind = 1,
    content = "Hello world!",
    tags = tagArray {
        add(arrayOf("subject", "First post"))
    }
)

Parsing:

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)

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)

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)

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):

add(arrayOf("e", eventId, relayHint, marker))
// marker: "reply", "root", "mention"

p-tag (pubkey reference):

add(arrayOf("p", pubkey, relayHint))

a-tag (addressable event):

add(arrayOf("a", "$kind:$pubkey:$dtag", relayHint))

d-tag (identifier for addressable events):

addUnique(arrayOf("d", "unique-slug"))

Tag Extensions

// 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)

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)

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)

// Modern encryption (ChaCha20-Poly1305) via the Nip44 facade
// (nip44Encryption/Nip44.kt — picks the current version, decrypts any)
object Nip44 {
    fun encrypt(msg: String, privateKey: ByteArray, pubKey: ByteArray): Nip44v2.EncryptedInfo
    fun decrypt(payload: String, privateKey: ByteArray, pubKey: ByteArray): String
}

// Usage
val encrypted = Nip44.encrypt("Secret message", myPrivateKey, recipientPubKey)
val payload = encrypted.encodePayload()  // base64 string for event content

val decrypted = Nip44.decrypt(payload, myPrivateKey, senderPubKey)

Most code should not call Nip44 directly — go through signer.nip44Encrypt(plaintext, toPublicKey) / signer.nip44Decrypt(ciphertext, fromPublicKey) so remote/external signers keep working.

Pattern: Elliptic curve Diffie-Hellman + ChaCha20-Poly1305 AEAD.

NIP-04 (Deprecated)

// 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 (Nip44) for new implementations. NIP-04 has security issues.

Bech32 Encoding (NIP-19)

Encoding uses extension functions on ByteArray (nip19Bech32/ByteArrayExt.kt); TLV entities carry relay hints via create() helpers on the entity classes in nip19Bech32/entities/. Decoding goes through Nip19Parser, whose uriToRoute() returns a ParseReturn? wrapping the parsed Entity.

// Encode simple entities: ByteArray extensions
val npub = pubkeyBytes.toNpub()   // "npub1..."
val nsec = privKeyBytes.toNsec()  // "nsec1..."
val note = eventIdBytes.toNote()  // "note1..."

// Encode TLV entities with relay hints (relays: List<NormalizedRelayUrl>)
val nevent = NEvent.create(eventIdHex, authorHex, kind, relays)
val nprofile = NProfile.create(pubkeyHex, relays)

Usage:

// Decode (also accepts nostr: URIs); entity types live in nip19Bech32.entities
when (val entity = Nip19Parser.uriToRoute(input)?.entity) {
    is NPub -> println("Pubkey: ${entity.hex}")
    is NEvent -> println("Event: ${entity.hex}, relays: ${entity.relay}")
    is NAddress -> println("Address: ${entity.aTag()}")
    null -> println("not a valid bech32 entity")
    else -> println("Other type")
}

Event Validation

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

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

// 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)

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)

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:

# 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
• references/nip19-bech32.md - Nip19Parser, Bech32Util, TlvBuilder, entity types (NPub, NSec, NEvent, NAddress, NProfile, NRelay, NEmbed)
• references/event-factory.md - EventFactory dispatch pattern and how to register a new kind
• references/crypto-and-encryption.md - Event signing/verification, secp256k1 abstraction, NIP-44 encryption, SharedKeyCache
• references/large-cache.md - LargeCache<K,V> expect/actual + ICacheOperations functional API
• scripts/nip-lookup.sh - Find NIP implementations by number or search term

Quick Reference

Common Event Kinds

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