amethyst/.claude/skills/nostr-expert/references/event-factory.md

EventFactory: Parsing JSON into Typed Events

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/utils/EventFactory.kt is the single dispatch point that turns a parsed (id, pubKey, createdAt, kind, tags, content, sig) tuple into the correct Event subclass.

What It Does

EventFactory is a giant when over kind that maps integer kind values to concrete event classes. If a kind isn't recognized, it falls back to the generic base Event (so unknown kinds still round-trip). Every NIP that defines a new kind registers its class here.

Typical shape:

object EventFactory {
    fun create(
        id: HexKey,
        pubKey: HexKey,
        createdAt: Long,
        kind: Int,
        tags: TagArray,
        content: String,
        sig: HexKey,
    ): Event = when (kind) {
        MetadataEvent.KIND        -> MetadataEvent(id, pubKey, createdAt, tags, content, sig)
        TextNoteEvent.KIND        -> TextNoteEvent(id, pubKey, createdAt, tags, content, sig)
        ContactListEvent.KIND     -> ContactListEvent(id, pubKey, createdAt, tags, content, sig)
        ReactionEvent.KIND        -> ReactionEvent(id, pubKey, createdAt, tags, content, sig)
        // …hundreds more…
        else                      -> Event(id, pubKey, createdAt, kind, tags, content, sig)
    }
}

Callers are normally upstream of this: Event.fromJson(...) / EventMapper.fromJson(...) / the relay client's message parser. You rarely call EventFactory directly — you consume typed events it produces.

Registering a New Event Kind

Adding a NIP is roughly:

1. Create the event class under quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nipXX…/ alongside the NIP package.
2. Subclass the right base:
   • Event — regular events (stored forever).
   • BaseReplaceableEvent — kinds 10000-19999, 0, 3.
   • BaseAddressableEvent — kinds 30000-39999 (identified by kind:pubkey:d-tag).
   • Ephemeral events extend Event but have kind 20000-29999.
3. Define companion object { const val KIND = <n> }.
4. If the event has tag builders, define a TagArrayBuilder<YourEvent> DSL in a TagArrayBuilder extension — see nostr-expert/references/tag-patterns.md.
5. Add a branch to EventFactory.create(...) so JSON parsing produces your typed class.
6. If the event is addressable, ensure it exposes a stable dTag() and address().
7. Add tests under quartz/src/commonTest/....

Why a Monolithic when?

• Zero overhead: compiled to a dense lookup. No reflection, no registry map.
• Exhaustive browsing: every known kind lives at one search location. grep KIND = 1234 quartz/... finds everything.
• Obvious migration path: adding a kind means adding a case; removing a kind is a grep-and-delete.

The tradeoff is the file is large and every new kind edits the same file — expect merge conflicts in PRs that touch it, and resolve by keeping both branches.

Supporting Utilities

• EventAssembler.kt (crypto/) — higher-level helper that takes a signer and a kind + tags + content and produces a fully signed event (id + sig populated).
• EventTemplate.kt (signers/) — unsigned-event holder, useful in signer flows.
• Event.fromJson(...) / Event.toJson() — JSON round-trip using OptimizedJsonMapper (Jackson on jvmAndroid).

Related References

• event-hierarchy.md — class hierarchy, Kind ranges
• nip-catalog.md — which kind maps to which NIP
• tag-patterns.md — TagArrayBuilder DSL for writing tags cleanly