nostr-expert

# 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