coracle-rust/book/research/events.md

Research: Events

Topic Summary

The events chapter covers the core nostr Event data structure: fields (id, pubkey, created_at, kind, tags, content, sig), JSON serialization, canonical form, event ID computation (sha256 of canonical JSON), unsigned vs signed event representations, and structural validation. Signing is addressed by adding a sign method to PrivateKey that signs an arbitrary string (not an event). The chapter includes an illustrative example of event signing using this primitive, but does not tangle a sign method on events themselves.

Philosophy

From ref/building-nostr/content/book.md and summary.md:

Events as referentially transparent facts. An event's ID is the hash of its content (NIP-01), making events content-addressable and immutable. If you have an event ID, you know the exact content forever. This is the foundation of nostr's break from server-centric architectures. Regular, non-replaceable events should be the default because replaceable events break referential transparency.

Permissionless validity through signatures. Events gain legitimacy through secp256k1 Schnorr signatures. Any event that is signed is valid simply by virtue of existing — validation is limited to hash and signature verification plus a few structural checks. The protocol explicitly rejects schema enforcement in favor of social/reputational filtering.

Minimal kernel. Events are the entire nostr substrate. All application semantics emerge from event kinds and tagged references. The protocol itself is "a very humble protocol — it is little more than an empty shell which users can then fill with content types that solve their use cases."

Four-part structure.

• Cryptographic core: id, pubkey, sig
• Metadata: created_at, kind
• Structured data: tags (array of string arrays)
• Human-readable: content

Content should hold human-readable payloads. Encoding JSON or encrypted data in content is considered an antipattern (though encrypted DMs necessarily do this).

Weak timestamps. created_at is a second-granularity Unix timestamp supplied unilaterally by the author. Ordering is delegated to the social layer; nostr refuses to solve distributed clock problems.

Fault-tolerant validation. "Liberal in what you accept" applied conservatively: tolerate malformed data but always verify signatures. Never repair data that contradicts conventions.

Reference Implementation Analysis

applesauce

Re-exports core types (NostrEvent, EventTemplate, UnsignedEvent, VerifiedEvent) from nostr-tools/pure rather than defining its own. Adds kind-narrowing wrappers KnownEvent<K> etc. for type safety. Delegates serialization, hashing, and signature verification entirely to nostr-tools.

The notable contribution is EventFactory (packages/core/src/factories/event.ts), a fluent builder extending Promise<T> with chainable operations: fromKind(1).content("hello").stamp(signer).sign(signer). Three lifecycle states: EventTemplate → UnsignedEvent (has pubkey) → NostrEvent (signed).

Structural validation (isEvent) checks string/number types and 64-char hex lengths for id/pubkey but does NOT verify signatures. Signature verification is pluggable on the AsyncEventStore via a verifyEvent callback, cached after first verification via a symbol property. Attaches metadata via symbols to avoid polluting the event object.

ndk

Uses class-based design: NDKEvent extends EventEmitter with mutable public fields. Provides inheritance hierarchy for kind-specific subclasses (NDKArticle, NDKZap, etc.).

Canonical serialization in core/src/events/serializer.ts produces the NIP-01 JSON array [0, pubkey, created_at, kind, tags, content]. Hash computed via @noble/hashes sha256 plus hex encoding. Validation uses regex /^[a-f0-9]{64}$/ for pubkey format, and throws detailed errors with event snapshots on structural failure.

Signature verification supports two modes: synchronous (blocking, via @noble/curves schnorr) or Web-Worker offloaded for non-blocking verification in browsers. Results cached in a 1000-entry LRU with 60s TTL. Type-safe signed vs unsigned via discriminated unions (NDKSignedEvent, NDKUnsignedEvent) with guard functions.

toNostrEvent() finalizes by computing id hash before signing; sign() delegates to pluggable NDKSigner. Notable: in-place mutation is pervasive (setters on all fields), trading safety for ergonomics.

nostr-gadgets

Treats events as plain TS objects imported from @nostr/tools/pure; does not define its own Event type. Consumes already-finalized events — ID computation, signing, and verification are all delegated to nostr-tools.

Interesting only for its storage strategy: RedEventStore constructs JSON manually ('{"pubkey":"${event.pubkey}","id":"${event.id}",...}') to control field order and append custom metadata like seen_on. Validation is limited to structural bounds: created_at > 0xffffffff || kind > 0xffff. No signature verification at the storage layer — that's assumed to happen upstream at the relay/pool boundary.

Uses Symbol properties (isLocalSymbol, seenOnSymbol) to attach metadata without mutating events. No builder pattern — callers use finalizeEvent from nostr-tools directly.

nostr-tools

The de facto reference for TypeScript nostr. Defines the canonical NostrEvent type as a plain object (not a class). Uses a verifiedSymbol for type discrimination of verified events without wrapping them.

Three type variants via Pick<>:

• EventTemplate: kind, tags, content, created_at
• UnsignedEvent: adds pubkey
• Event / VerifiedEvent: complete with id, sig

Canonical serialization in pure.ts:

function serializeEvent(evt: UnsignedEvent): string {
  return JSON.stringify([0, evt.pubkey, evt.created_at, evt.kind, evt.tags, evt.content])
}

getEventHash() is sha256 over UTF-8 encoded canonical JSON, returned as hex. finalizeEvent(template, secretKey) bridges template → signed event, mutating the template in-place for efficiency.

Validation (validateEvent) checks field types, regex-validates pubkey format, and verifies tag shape. verifyEvent performs both ID recomputation (catches tampering) and Schnorr signature verification via @noble/curves/secp256k1. Result cached via verifiedSymbol.

Dual backend: pure.ts uses pure-JS @noble; wasm.ts provides a WASM alternative with identical API.

rust-nostr

The most relevant reference, being Rust. Defines three event representations:

Event (event/mod.rs): #[non_exhaustive] struct with public immutable fields. Implements Clone, Eq, Ord (by created_at desc, then id), Hash. Construction only via Event::new(), protecting against future additive changes.

UnsignedEvent (event/unsigned.rs): Same fields minus sig, with id as Option<EventId> — lazily computed on first access via interior mutability.

EventBorrow<'a> (event/borrow.rs): Zero-copy view for serialization and validation without allocating; holds &[u8; 32] for id/pubkey/sig.

Supporting types: EventId is a newtype around [u8; 32], serialized as hex; Kind is an enum with named variants plus Custom(u16); Tag wraps Vec<String> with lazy standardization parsing via OnceCell.

Serialization: Uses an EventIntermediate<'a> struct with Cow<'a, T> fields for zero-copy serialize and owned deserialize. Custom hex encoding for signatures via serialize_with. Silently ignores unknown JSON fields (lenient for relay compat).

ID computation: EventId::new() uses serde_json::json!() to build the canonical [0, pubkey, created_at, kind, tags, content] array, serializes to string, hashes with bitcoin_hashes::sha256::Hash, returns as 32-byte newtype.

Validation:

• Event::verify_id(): recompute and compare
• Event::verify_signature(): Schnorr via secp256k1::verify_schnorr
• Event::verify(): both, returning Result<(), Error>

EventBuilder (event/builder.rs): fluent builder that produces UnsignedEvent via .build(pubkey). Includes POW mining (optional multi-threaded via Arc<AtomicBool>), self-tag filtering, tag deduplication, and custom timestamps. Signing via NostrSigner trait (async) or Keys directly (sync).

no_std support: Conditional core::cell::OnceCell vs std::sync::OnceLock.

Dependencies: secp256k1 0.29, serde/serde_json, bitcoin_hashes, faster-hex. Event module is self-contained aside from tight coupling to Tag/Kind submodules.

welshman

Data-oriented, composition-first design. Defines a layered type hierarchy:

EventTemplate → StampedEvent → OwnedEvent → HashedEvent → SignedEvent
     (content)    (+ created_at)   (+ pubkey)   (+ id)      (+ sig)

Each is a structural type. Construction is a pipeline of pure functions: stamp(event, created_at) → own(event, pubkey) → hash(event) → sign(event, secret). No builder class; composition via function calls.

Delegates crypto to nostr-tools and @noble/curves. getHash is a one-liner wrapping getEventHash. Signature verification upgrades from pure-JS to WASM asynchronously if available, caches results via the verifiedSymbol.

Adds TrustedEvent: an event accepted without verification (e.g., from canonical relay storage). Represents the distinction between "cryptographically verified" and "contextually trusted."

Structural type guards (isEventTemplate, isSignedEvent) check field types and formats.

Common Patterns

Canonical serialization. All implementations use NIP-01's JSON array form [0, pubkey, created_at, kind, tags, content]. Order matters (deterministic output).

Event ID = sha256(canonical JSON). Universal. Implementations differ only in which sha256 library they use.

Layered types for lifecycle states. Everyone distinguishes template / unsigned / signed, though the exact type names vary (welshman has the most granular hierarchy with five stages).

Delegation. Every TypeScript library delegates the hashing and signature primitives to @noble/curves + @noble/hashes (via nostr-tools or directly). Only rust-nostr and nostr-tools actually implement canonical serialization themselves.

Structural validation is cheap and separate from signature verification. Libraries uniformly distinguish "is this the right shape?" from "is the signature valid?" — and often verify signatures lazily, cached, or on-demand.

Tags are string[][]. Every implementation represents tags as arrays of string arrays. None impose a richer schema at the Event level.

Plain data over classes. TypeScript libraries mostly use plain objects (nostr-tools, nostr-gadgets, welshman, applesauce). NDK is the outlier with a class hierarchy. rust-nostr uses immutable structs with public fields.

Divergence: mutability. NDK mutates freely; nostr-tools mutates templates in finalizeEvent; welshman and applesauce build new objects. rust-nostr is strictly immutable after construction.

Divergence: builder vs function composition. rust-nostr and applesauce have fluent builders. nostr-tools, welshman, and nostr-gadgets expose plain functions.

Considerations for Our Implementation

Use serde. serde + serde_json is the obvious choice for a Rust implementation. The canonical form [0, pubkey, created_at, kind, tags, content] can be produced via serde_json::json! or a custom Serialize impl.

Event struct. A plain struct with public fields matches rust-nostr and the philosophy of "events are data." Fields: id, pubkey, created_at, kind, tags, content, sig.

Field types.

• id: [u8; 32] or a EventId newtype (rust-nostr uses newtype; keeps the API clean and enforces length). Start simple — String of hex or [u8; 32].
• pubkey: reuse the PublicKey already defined in the keys chapter.
• created_at: u64 (Unix timestamp seconds).
• kind: u16 (nostr kinds fit in 16 bits).
• tags: Vec<Vec<String>> — simple and correct.
• content: String.
• sig: a Signature type or [u8; 64] or hex string.

Unsigned vs signed. Two approaches:

1. Separate UnsignedEvent struct (no id, no sig), with a method to compute the id and convert into a signed Event. Clean but verbose.
2. Single struct with Option<String> for id/sig. Mirrors welshman's approach but loses compile-time guarantees.

Given the teaching context, option 1 is clearer: it makes the lifecycle visible in the type system.

Canonical serialization via serde_json::json!. rust-nostr's approach is compact and readable:

let canonical = json!([0, pubkey, created_at, kind, tags, content]).to_string();
let id = sha256(canonical.as_bytes());

ID computation as a method on UnsignedEvent. fn id(&self) -> [u8; 32].

Signing primitive on PrivateKey. Per user's guidance: add PrivateKey::sign(&self, message: &[u8]) -> Signature (or &str), signing an arbitrary byte string via Schnorr. The chapter shows an example of combining unsigned.id() with private_key.sign(&id) to produce a complete Event, but this orchestration is illustrative prose, not tangled source.

Verification. Event::verify_id() recomputes and compares; Event::verify() also verifies the Schnorr signature via the existing PublicKey-based primitive (or we add PublicKey::verify(message, signature) as a companion to PrivateKey::sign).

Dependencies already in tree. From chapter 02 and 03, secp256k1 (or k256), sha2, and hex crates should already be available. Need to confirm and reuse. Add serde, serde_json if not yet in coracle-lib.

Structural validation. Keep minimal: lengths of id and sig, format of pubkey (already enforced if PublicKey is a typed wrapper), non-negative timestamp (enforced by u64).

Kinds chapter is separate. Don't enumerate kinds; just expose u16. A later chapter adds an enum or constants.

Tags chapter is separate. Don't build tag helpers; just Vec<Vec<String>>.