The binary wire protocol for node-to-node communication. 18 message types, byte layouts, and design philosophy for minimal gossip overhead.
The binary wire protocol defines how nodes communicate at the lowest level. Every WebSocket frame between peers uses this compact binary format. The design prioritizes minimal overhead -- gossip-heavy networks cannot afford JSON bloat on every hop.
All 18 message types, their hex codes, and byte layouts:
| Code | Name | Payload Size | Description |
|---|---|---|---|
0x01 | HEARTBEAT | 0 bytes | Keepalive ping. No payload. Sent every 30s. |
0x02 | MESH_RTT | 2 bytes | Round-trip-time measurement. Payload: uint16 RTT in milliseconds. |
0x03 | PRESENCE_UPDATE | variable | Node presence state change (online, idle, busy). Includes node ID and status byte. |
0x04 | EVENT_NOTIFY | 32 bytes | Notification that a new event exists. Payload: SHA-256 hash of the event. Triggers pull if unknown. |
0x05 | EVENT_REQUEST | 32 bytes | Request full event data by hash. Payload: SHA-256 hash of the desired event. |
0x06 | EVENT_DATA | variable (gzipped) | Full event payload, gzip-compressed. Response to EVENT_REQUEST. |
0x07 | SYNC_CURSOR | 8 bytes | Sync position announcement. Payload: uint64 timestamp cursor (Unix ms). |
0x08 | SYNC_HASHES | variable | Batch of event hashes for sync comparison. Array of 32-byte hashes. |
0x09 | AUTH | variable | Authentication handshake. Contains Ed25519 public key + signed challenge. |
0x0A | AUTH_ACK | 1 byte | Authentication acknowledgment. Payload: 0x01 (success) or 0x00 (failure). |
0x0B | PEER_EXCHANGE_REQ | 0 bytes | Request the neighbor's known peer list. |
0x0C | PEER_EXCHANGE_RES | variable | Response with known peers. Array of (pubkey, endpoint) pairs. |
0x0D | COHORT_ASSIGN | variable | Cohort membership assignment from coordinator. |
0x0E | COHORT_ACK | 1 byte | Acknowledgment of cohort assignment. |
0x10 | HEARTBEAT_PROPAGATE | 25 bytes | Propagated heartbeat from a non-neighbor. 1-byte hop count + 24-byte node fingerprint + timestamp. |
0x11 | NODE_OFFLINE | 32 bytes | Notification that a node has gone offline. Payload: pubkey hash of the departed node. |
0x12 | NEIGHBOR_ADOPT_REQ | 32 bytes | Request to adopt a peer as a direct neighbor. Payload: pubkey hash. |
When a node creates a new protocol event, the propagation follows this sequence:
0x04 EVENT_NOTIFY (33 bytes total) to all direct neighbors.0x05 EVENT_REQUEST (33 bytes) back.0x06 EVENT_DATA (gzipped full payload).0x04 EVENT_NOTIFY to its own neighbors (excluding the sender).This push-notify-then-pull pattern means that a single event propagating through a 100-node network generates approximately 100 x 33 = 3.3 KB of notification traffic, plus N full-payload transfers (where N is the number of unique nodes that actually need the event, typically all of them exactly once).
When two nodes first connect via WebSocket:
0x09 AUTH with its Ed25519 public key and a signed timestamp challenge.0x0A AUTH_ACK with 0x01 (success) or 0x00 (rejection).0x09 AUTH for mutual authentication.0x0A AUTH_ACK.Unauthenticated connections cannot send or receive any message type except AUTH and AUTH_ACK.
When a node reconnects after downtime, it uses the cursor-based sync protocol:
0x07 SYNC_CURSOR with its last-known timestamp.0x08 SYNC_HASHES -- a batch of event hashes since that cursor.0x05 EVENT_REQUEST for each missing hash.0x06 EVENT_DATA for each.This is the WebSocket equivalent of the HTTP /api/gossip/sync endpoint, but operates over the persistent binary channel for lower latency.