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

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

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

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:

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

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

nostr-expert

Install Skill

SKILL.md