npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl
23f75dac90
Fill all 31 stub pages scaffolded in Phase 1 with content migrated and verified from the root docs, crate READMEs, and source code: - getting-started/ (3): installation, quickstart, local relay (TESTING.md) - architecture/ (8): ARCHITECTURE.md §1–§8, one page per section - guides/ (9): development, testing, agents, workflows, self-hosting, nostr-clients (operational half of NOSTR.md), adding-event-kinds, adding-api-endpoints, releasing - reference/ (5): CLI reference verified against buzz --help and crates/buzz-cli/src (18 groups / 87 subcommands; README drift noted), configuration, known-limitations (ARCHITECTURE §9 + conformance LIMITS.md + doc-debt list), NIPs index (13, NIP-CW canonical), design-docs index - vision/ (6): VISION.md + 5 VISION_*.md migrated with aspirational banners and rewritten links Root originals (ARCHITECTURE, NOSTR, TESTING, RELEASING, VISION*) get pointer notes marking docs/ as canonical; deletion is a follow-up. All relative links in the new tree verified to resolve. Known limitations are documented honestly, never papered over: rate limiting unenforced, WF-07/WF-08 workflow stubs, buzz-cli README drift, one-line GOVERNANCE.md. Note: pre-commit sadscan findings reviewed as false positives (dev-default postgres URI and NIP-OA test vectors, both already on origin/main). Co-authored-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co> Signed-off-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co>
4.1 KiB
Protocol
Buzz speaks Nostr NIP-01 on the wire. This page covers protocol semantics:
the event shape, kind ranges, Buzz custom kinds, and the wire messages. For
connecting third-party Nostr clients (setup, allowlisting, nak recipes), see
Using Third-Party Nostr Clients. Buzz-specific
protocol extensions are specified as NIPs — see the Buzz NIPs Index.
Buzz uses Nostr NIP-01 on the wire. Every action is a JSON event with six fields:
{
"id": "<sha256 of canonical serialization>",
"pubkey": "<secp256k1 public key, hex>",
"kind": <unsigned integer>,
"tags": [["e", "<event-id>"], ["p", "<pubkey>"], ...],
"content": "<JSON payload or plain text>",
"sig": "<Schnorr signature over id>"
}
The kind integer is the only dispatch switch. The relay routes, stores, and fans out events based on kind. Clients filter subscriptions by kind. New feature = new kind number = zero breaking changes to existing clients.
Kind Ranges
| Range | Meaning |
|---|---|
| 0–9999 | Standard Nostr kinds (NIP-01 through NIP-XX) |
| 10000–19999 | Replaceable events (NIP-16) |
| 20000–29999 | Ephemeral events — not stored, not audited |
| 30000–39999 | Parameterized replaceable events |
| 40000–49999 | Buzz custom kinds |
Buzz Custom Kinds (selected)
| Kind | Name | Description |
|---|---|---|
| 7 | KIND_REACTION | Emoji reaction (standard NIP-25) |
| 9 | KIND_STREAM_MESSAGE | Chat message in a Stream channel (NIP-29 group chat) |
| 40002 | KIND_STREAM_MESSAGE_V2 | Stream message v2 format |
| 40003 | KIND_STREAM_MESSAGE_EDIT | Edit of a stream message |
| 43001 | KIND_JOB_REQUEST | Agent job request |
| 45001 | KIND_FORUM_POST | Forum thread root |
| 45003 | KIND_FORUM_COMMENT | Forum thread reply |
| 46001–46012 | KIND_WORKFLOW_* | Workflow execution events |
| 20001 | KIND_PRESENCE_UPDATE | Ephemeral presence heartbeat |
buzz-core defines all 81 kinds as pub const KIND_*: u32 and exports ALL_KINDS: &[u32]. Kinds are u32 (NIP-01 specifies unsigned integer; u32 covers the full range). Buzz uses both standard Nostr kinds (e.g., kind 7 for reactions) and custom ranges (40000+).
Note: KIND_AUTH (22242) is pub const KIND_AUTH: u32 in buzz-core/src/kind.rs and imported by buzz-relay/src/handlers/event.rs. KIND_CANVAS (40100) is likewise pub const KIND_CANVAS: u32 in buzz-core/src/kind.rs.
Wire Protocol (NIP-01 messages)
| Direction | Message | Purpose |
|---|---|---|
| Client → Relay | ["EVENT", <event>] |
Submit a signed event |
| Client → Relay | ["REQ", <sub_id>, <filter>, ...] |
Subscribe to events |
| Client → Relay | ["CLOSE", <sub_id>] |
Cancel a subscription |
| Client → Relay | ["AUTH", <event>] |
Authenticate (NIP-42) |
| Relay → Client | ["EVENT", <sub_id>, <event>] |
Deliver a matching event |
| Relay → Client | ["EOSE", <sub_id>] |
End of stored events |
| Relay → Client | ["OK", <event_id>, true/false, ""] |
Event acceptance result |
| Relay → Client | ["CLOSED", <sub_id>, "reason"] |
Subscription closed |
| Relay → Client | ["NOTICE", "message"] |
Informational message |
| Relay → Client | ["AUTH", <challenge>] |
Authentication challenge |
Max frame size: 65,536 bytes. Max subscriptions per connection: 1024. Max historical results per filter: 500.
Buzz NIP extensions
Buzz extends standard Nostr with the 13 NIPs in docs/nips/ —
agent auth (NIP-AA), agent engrams/memory (NIP-AE), personas (NIP-AP),
channel window (NIP-CW, normative for timeline paging), owner attestation
(NIP-OA), workspace profile (NIP-WP), and more. See the
index for one-line summaries.
Authentication kinds
Authentication uses NIP-42 (WebSocket challenge/response), NIP-98 (signed HTTP requests), and optionally NIP-43 relay membership and NIP-OA owner attestation. Details in the Security Model and Self-Hosting guide.
The authoritative registry of all kind numbers is
crates/buzz-core/src/kind.rs.