bennc/BENNC_PROTOCOL_SPEC.md

BENNC Protocol Implementation Guide

BENNCv1 (Butlersaurus Ephemeral No NONCEnse Chat) - Complete implementation documentation for a binary pub/sub messaging protocol with encryption and compression.

Quick Implementation Checklist

1. Connect to server (TCP or WebSocket)
2. Subscribe to message types you want to receive
3. Encrypt data with Romulus-M (except subscribe/unsubscribe)
4. Send keepalive every 30 seconds when idle
5. Handle incoming messages and sender IDs

Connection Endpoints

Protocol	Endpoint
TCP	chat.3t.network:10009
WebSocket (TLS)	wss://chat.3t.network:443/BENNC
WebSocket	ws://chat.3t.network:80/BENNC

Core Requirements

• Encoding: Big-endian integers, UTF-8 strings
• Encryption: Romulus-M with 16-byte nonce + message type as additional data (big-endian uint16)
• Compression: ZSTD (when specified per message type)
• Max Data Size: 1000 bytes per message (including nonce for encrypted messages)
• Keepalive: Send every 30 seconds when idle
• Reserved IDs: 0xFFFFFF00-0xFFFFFFFF for client internal use (256 IDs for local messages, system notifications, etc.)

Message Structure

Client → Server:

┌─────────────┬─────────────┬─────────────────────────┐
│ Message Type│ Length      │ Data                    │
│ (2 bytes)   │ (2 bytes)   │ (0-1000 bytes)          │
└─────────────┴─────────────┴─────────────────────────┘

Server → Client:

┌─────────────┬─────────────┬─────────────┬─────────────────────┐
│ Message Type│ Sender ID   │ Length      │ Data                │
│ (2 bytes)   │ (4 bytes)   │ (2 bytes)   │ (0-1000 bytes)      │
└─────────────┴─────────────┴─────────────┴─────────────────────┘

Sender ID is randomly generated per connection to identify message source.

Encryption Implementation

For encrypted messages (types 0x0001, 0x0002, 0x0003, 0x0006, 0x0007):

1. Generate random 16-byte nonce
2. Prepare additional data: message type as big-endian uint16
3. Encrypt plaintext using Romulus-M AEAD
4. Prepend nonce to ciphertext
5. Total data = nonce (16 bytes) + ciphertext ≤ 1000 bytes

Compression Implementation

• Algorithm: ZSTD (Zstandard) at default compression level
• Application: Per message type (all messages of type or none)
• Order: Compression applied before encryption
• Scope: Only the data portion, headers remain uncompressed
• Currently used by: Advanced Text Messages (0x0006, 0x0007)

Message Types Reference

ID	Name	Subscribable	Encrypted	Compressed	Purpose
0x0000	Subscribe	❌	❌	❌	Subscribe to message type
0x0001	Basic Message	✅	✅	❌	Chat messages
0x0002	Request User Data	✅	✅	❌	Request user info
0x0003	User Data Response	✅	✅	❌	Respond with user info
0x0005	Keepalive	❌	❌	❌	Prevent connection timeout
0x0006	Advanced Text	✅	✅	✅	Long/rich text messages
0x0007	Edit Advanced Text	✅	✅	✅	Edit/delete advanced text
0xFFFF	Unsubscribe	❌	❌	❌	Unsubscribe from message type

---

Message Type Specifications

Subscribe (0x0000)

Subscribe to receive messages of specified type. Must resubscribe after disconnect.

Data: Message type to subscribe to (2 bytes, big-endian)

---

Basic Message (0x0001)

UTF-8 chat messages. 16-byte nonce + encrypted data ≤ 1000 bytes total.

Data: Encrypted UTF-8 string

---

Request User Data (0x0002)

Request user information from all users. Clients should respond with User Data Response (0x0003).

Data Structure:

• Username length (2 bytes, big-endian)
• Username (up to 32 bytes, UTF-8)
• Color RGB (3 bytes: R, G, B values)
• Client identifier length (2 bytes, big-endian)
• Client identifier (up to 32 bytes, UTF-8)

---

User Data Response (0x0003)

Send user information in response to Request User Data (0x0002).

Data Structure: Same as Request User Data

• Username length (2 bytes, big-endian)
• Username (up to 32 bytes, UTF-8)
• Color RGB (3 bytes: R, G, B values)
• Client identifier length (2 bytes, big-endian)
• Client identifier (up to 32 bytes, UTF-8)

---

Keepalive (0x0005)

Prevent connection timeout when idle. Send every 30 seconds when no other traffic. Not forwarded to other clients and cannot be subscribed to.

Data: None - empty message

---

Unsubscribe (0xFFFF)

Stop receiving messages of specified type.

Data: Message type to unsubscribe from (2 bytes, big-endian)

---

Advanced Text (0x0006)

Multi-packet messages for long text with markdown formatting and ZSTD compression.

Implementation Notes:

• Text is compressed before splitting into packets
• Header is not compressed
• Packets may arrive out of order - use packet numbers to reconstruct
• Message ID identifies the complete message, not individual packets
• Warn users before displaying very large messages

Data Structure:

• Message ID (4 bytes, big-endian)
• Packet number (2 bytes, big-endian, 0-indexed)
• Final packet number (2 bytes, big-endian, 0-indexed)
• Compressed markdown text (remaining bytes, ZSTD)

Edit Advanced Text (0x0007)

Edit or delete existing Advanced Text messages. Use same Message ID to replace existing message. Empty compressed text deletes the message. Client replaces original when final packet received.

Data Structure: Same as Advanced Text (0x0006)

---

Implementation Guidelines

Validation Requirements

• All length fields must not exceed their specified maximums
• Username/Client ID lengths must match actual string lengths
• Message data must not exceed 1000 bytes (including nonce)
• Packet numbers must be sequential and within final packet range

Connection Lifecycle

1. Connect to server (TCP/WebSocket)
2. Subscribe to required message types
3. Send keepalive every 30 seconds when idle
4. Resubscribe after any disconnection
5. Handle out-of-order packets for Advanced Text

Common Issues

• Encryption fails: Ensure message type in additional data matches packet header
• Messages dropped: Check total size ≤ 1000 bytes including nonce
• Connection timeout: Verify keepalive frequency
• Advanced Text garbled: Reconstruct packets in correct order before decompression

---

Protocol Features

• Binary pub/sub messaging with server-side routing
• End-to-end encryption using Romulus-M AEAD
• ZSTD compression for large text messages
• Multi-packet support for long messages
• TCP and WebSocket transport options

This is a documentation-only repository. The protocol specification is final and changes are not permitted.