Buzz Custom Event Kinds: Complete Guide to Nostr Event Types

Buzz defines over 50 custom Nostr event kinds in 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 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:

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

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.

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}