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