# Buzz Custom Event Kinds: Complete Guide to Nostr Event Types

> Explore Buzz's extensive Nostr custom event kinds for reactions, messaging, AI jobs, and more. Discover our complete guide to event types and enhance your Nostr experience.

- Repository: [Block Open Source/buzz](https://github.com/block/buzz)
- Tags: deep-dive
- Published: 2026-08-27

---

**Buzz defines over 50 custom Nostr event kinds in [`crates/buzz-core/src/kind.rs`](https://github.com/block/buzz/blob/main/crates/buzz-core/src/kind.rs), covering reactions, stream messaging, AI agent jobs, moderation, and ephemeral presence updates.**

Buzz extends the Nostr protocol with a comprehensive registry of **custom event kinds** that power its social, streaming, and AI features. These kinds are defined as `u32` constants and used throughout the relay, database, and client code to drive feature-specific behavior. All constants follow Nostr's standard categorization—replaceable, parameterized replaceable, and ephemeral—while adding Buzz-specific functionality for modern chat, agent orchestration, and community moderation.

## Stream Messaging Event Kinds

Buzz implements an extended set of stream-chat event kinds that replace standard NIP-29 channel messages with richer functionality. The current production format uses **`KIND_STREAM_MESSAGE_V2`** (40002), defined in [`crates/buzz-core/src/kind.rs`](https://github.com/block/buzz/blob/main/crates/buzz-core/src/kind.rs) at lines 80-82, while the legacy **`KIND_STREAM_MESSAGE`** (9) at lines 77-79 is deprecated.

**Message lifecycle and metadata kinds include:**

- **`KIND_STREAM_MESSAGE_EDIT`** (40003) — Carries an updated content payload and references the original event via an `e` tag chain.
- **`KIND_STREAM_MESSAGE_PINNED`** (40004) — Marks content for surface-level display at the top of a channel.
- **`KIND_STREAM_MESSAGE_BOOKMARKED`** (40005) — Enables per-user saved lists without affecting the global message stream.
- **`KIND_STREAM_MESSAGE_SCHEDULED`** (40006) — Future-delivery messages held by the relay until the `created_at` timestamp is reached.
- **`KIND_STREAM_REMINDER`** (40007) — Attaches human-readable time hints to messages or stands alone as a reminder.
- **`KIND_STREAM_MESSAGE_DIFF`** (40008) — Stores unified-diff patches for file changes within stream conversations.

**System and collaborative kinds:**

- **`KIND_SYSTEM_MESSAGE`** (40099) — Signals channel state changes such as joins, leaves, or renames.
- **`KIND_CANVAS`** (40100) — Represents a collaborative document attached to a channel, with updates streamed as discrete events.

## AI Agent and Job Lifecycle Kinds

Buzz treats AI agents as first-class participants using a specialized job event protocol. The job lifecycle spans from request to completion through a consistent sequence of kinds in the 43001-43006 range.

**Job control flow:**

1. **`KIND_JOB_REQUEST`** (43001) — Initiates background processing for an AI agent (lines 518-19).
2. **`KIND_JOB_ACCEPTED`** (43002) — Confirmation that an agent has claimed the job (lines 20-21).
3. **`KIND_JOB_PROGRESS`** (43003) — Streaming updates including percentage completion or state transitions (lines 22-23).
4. **`KIND_JOB_RESULT`** (43004) — Final output payload of a completed job (lines 24-25).
5. **`KIND_JOB_CANCEL`** (43005) — Abort signal for in-flight jobs (lines 26-27).
6. **`KIND_JOB_ERROR`** (43006) — Failure reports generated when job execution fails (lines 28-29).

**Agent identity and memory:**

- **`KIND_AGENT_PROFILE`** (10100) — Replaceable profile metadata for an AI agent, owned by its creator (lines 86-88).
- **`KIND_AGENT_ENGRAM`** (30174) — NIP-AE encrypted, parameterized-replaceable memory records storing agent state (lines 89-94).
- **`KIND_PERSONA`** (30175) — Agent persona definitions containing system prompts, avatars, and model parameters; shared only when tagged `["shared","true"]` (lines 71-78).
- **`KIND_PRIVATE_MANAGED_AGENT`** (30179) — Owner-encrypted managed-agent definitions that remain private except via signed metadata (lines 111-118).
- **`KIND_MANAGED_AGENT`** (30177) — Public metadata for managed agents, excluding secrets (lines 84-91).

**Team coordination:**

- **`KIND_TEAM`** (30176) — Groups multiple personas into teams (lines 75-82).
- **`KIND_TEAM_CATALOG`** (30178) — Public projection of team definitions, gated by the `shared` tag (lines 93-101).

## Moderation and Community Management Kinds

Buzz implements community moderation through cryptographically signed commands and reporting structures.

**Moderation actions (mod-signed):**

- **`KIND_MODERATION_BAN`** (9040) — Permanent community-wide ban (lines 56-58).
- **`KIND_MODERATION_UNBAN`** (9041) — Revocation of a ban (lines 59-60).
- **`KIND_MODERATION_TIMEOUT`** (9042) — Temporary write-blocks for specific pubkeys (lines 61-63).
- **`KIND_MODERATION_UNTIMEOUT`** (9043) — Early termination of timeouts (lines 64-66).
- **`KIND_MODERATION_RESOLVE_REPORT`** (9044) — Dismissal or resolution of pending reports (lines 66-70).

**Reporting and feedback:**

- **`KIND_REPORT`** (1984) — NIP-56 moderation reports stored in a processing queue without fan-out (lines 22-27).
- **`KIND_PRODUCT_FEEDBACK`** (42000) — Internal feedback submissions accepted at ingest but never persisted as events (lines 29-31).

**NIP-29 group administration:**

The **`KIND_NIP29_*`** constants (9000-9022) cover NIP-29 group admin commands including user management, metadata edits, group creation/deletion, and invite handling defined at lines 334-352.

## Ephemeral and Real-Time Event Kinds

Ephemeral kinds (IDs 20000-29999) are never persisted to disk; they travel through Redis pub/sub only.

- **`KIND_PRESENCE_UPDATE`** (20001) — Online/away/offline status updates for users (lines 62-64).
- **`KIND_TYPING_INDICATOR`** (20002) — Channel-specific typing notifications (lines 66-68).
- **`KIND_HUDDLE_REACTION`** (24810) — Ephemeral emoji bursts for audio/video huddles (lines 70-72).
- **`KIND_AGENT_OBSERVER_FRAME`** (24200) — Encrypted telemetry and control frames for observing agents (lines 68-70).

**Huddle lifecycle (48100-48106):**

These kinds track audio/video session states including start, participant join/leave, session end, and guidelines documents.

## Direct Messaging and Privacy Kinds

Buzz extends NIP-17 private messaging with conversation management kinds.

- **`KIND_GIFT_WRAP`** (1059) — NIP-17 gift-wrap envelopes that hide sender, content, and timestamp (lines 59-61).
- **`KIND_DM_OPEN`** (41010) — Creates or opens a DM conversation with participant `p` tags (lines 6-8).
- **`KIND_DM_ADDED`** (41011) — Adds participants to group DMs (lines 9-10).
- **`KIND_DM_HIDE`** (41012) — Soft-deletes conversations from the sidebar (lines 11-12).
- **`KIND_DM_CREATED`** (41001) — Marker indicating conversation creation (lines 13-14).

**Encrypted utility kinds:**

- **`KIND_EVENT_REMINDER`** (30300) — NIP-ER author-only encrypted reminders with `not_before` tags (lines 96-102).
- **`KIND_PUSH_LEASE`** (30350) — NIP-PL encrypted push notification authorizations (lines 104-108).

## Development, Workflow, and Authentication Kinds

**Version control (NIP-34):**

The **`KIND_GIT_*`** range (30617-1633) covers repository announcements, state updates, patches, pull requests, issues, and status changes (lines 604-623). **`KIND_PROJECT`** (30621) groups multiple repositories into multi-repo projects (lines 126-131).

**Workflow automation:**

**`KIND_WORKFLOW_*`** kinds (46020-46012) drive the workflow engine with events for triggers, step completion, failures, approvals, and cancellations (lines 556-574).

**Authentication and pairing:**

- **`KIND_BLOSSOM_AUTH`** (24242) — Blossom media upload tokens (lines 78-80).
- **`KIND_PAIRING`** (24134) — NIP-AB device-pairing events (lines 64-66).
- **`KIND_HTTP_AUTH`** (27235) — NIP-98 HTTP authentication events (lines 82-84).

**Audit and internal kinds:**

- **`KIND_AUDIT_ENTRY`** (48001) — Administrative action logs (lines 88-90).
- **`KIND_MEDIA_UPLOAD`** (49001) — Internal media upload tracking (lines 100-102).

## Working with Buzz Event Kinds in Rust

The following Rust examples demonstrate creating common Buzz events using the `nostr` crate pattern:

```rust
use nostr::{Keys, EventBuilder, Tag, Kind};

// KIND_REACTION (7) - Emoji reaction to an event
fn create_reaction(keys: &Keys, target_id: &str, emoji: &str) -> EventBuilder {
    EventBuilder::new(
        Kind::Custom(7),
        "",
    )
    .tags(vec![
        Tag::event(target_id),
        Tag::custom(vec!["emoji", emoji]),
    ])
}

// KIND_STREAM_MESSAGE_V2 (40002) - Current chat format
fn create_stream_message(keys: &Keys, channel_id: &str, content: &str) -> EventBuilder {
    EventBuilder::new(
        Kind::Custom(40002),
        content,
    )
    .tags(vec![Tag::custom(vec!["h", channel_id])])
}

// KIND_JOB_REQUEST (43001) - Initiate AI agent job
fn create_job_request(keys: &Keys, job_id: &str, payload: &str) -> EventBuilder {
    EventBuilder::new(
        Kind::Custom(43001),
        payload,
    )
    .tags(vec![
        Tag::custom(vec!["d", job_id]),
        Tag::custom(vec!["p", &keys.public_key().to_string()]),
    ])
}

```

Builders are signed with `keys.sign_event()` and transmitted via WebSocket in `crates/buzz-relay/src/handlers/` or HTTP `POST /events`.

## Summary

- **Buzz defines 50+ custom event kinds** in [`crates/buzz-core/src/kind.rs`](https://github.com/block/buzz/blob/main/crates/buzz-core/src/kind.rs), organized into streaming, AI agent, moderation, and ephemeral categories.
- **Stream messaging** uses `KIND_STREAM_MESSAGE_V2` (40002) as the current format, with specialized kinds for edits, pins, bookmarks, and scheduled messages.
- **AI job lifecycle** follows a strict sequence from `KIND_JOB_REQUEST` (43001) through acceptance, progress, result, and error events.
- **Ephemeral kinds** (20000-29999) like presence updates and typing indicators never hit persistent storage.
- **Moderation** operates through mod-signed kinds (9040-9044) and NIP-29 group commands (9000-9022).

## Frequently Asked Questions

### What is the difference between KIND_STREAM_MESSAGE and KIND_STREAM_MESSAGE_V2?

`KIND_STREAM_MESSAGE` (9) is the legacy NIP-29 channel message format, while `KIND_STREAM_MESSAGE_V2` (40002) is Buzz's current production format that supports richer metadata and editing capabilities. New implementations should use the 40002 variant defined at lines 80-82 of [`crates/buzz-core/src/kind.rs`](https://github.com/block/buzz/blob/main/crates/buzz-core/src/kind.rs).

### Which Buzz event kinds are ephemeral and never persisted?

Kinds in the 20000-29999 range are **ephemeral**, including `KIND_PRESENCE_UPDATE` (20001), `KIND_TYPING_INDICATOR` (20002), and `KIND_HUDDLE_REACTION` (24810). These travel through Redis pub/sub only and are excluded from the database schema in [`crates/buzz-db/src/schema.sql`](https://github.com/block/buzz/blob/main/crates/buzz-db/src/schema.sql).

### How do the agent job event kinds work together?

The job protocol uses a state machine: `KIND_JOB_REQUEST` (43001) initiates work, `KIND_JOB_ACCEPTED` (43002) confirms acceptance, `KIND_JOB_PROGRESS` (43003) streams updates, and `KIND_JOB_RESULT` (43004) or `KIND_JOB_ERROR` (43006) terminates the flow. `KIND_JOB_CANCEL` (43005) allows aborting in-flight requests.

### What kind IDs does Buzz use for custom events?

Buzz uses several ranges: 40002-40100 for stream messaging, 43001-43006 for job management, 30174-30179 for agent metadata, 9040-9044 for moderation, and 46020-46012 for workflows, alongside standard Nostr kinds like 7 (reactions) and 1984 (reports).