Acip

Files
file	client.c
	ACIP client-side protocol implementation.
file	server.c
	ACIP server-side protocol implementation.
file	acds.h
	ascii-chat Discovery Service (ACDS) Protocol Message Formats
file	acds_client.h
	ACIP client-side protocol library and ACDS client connection API.
file	acds_server.h
	ACIP server-side protocol library and ACDS server utilities.
file	client.h
	ACIP client-side protocol API.
file	server.h
	ACIP server-side protocol API.

Detailed Description

This module documents the complete ascii-chat binary network protocol, including:

• Universal packet header structure used by ALL packet types
• Core protocol negotiation and cryptographic handshake
• Session communication (messages, media, audio, control)
• ACIP discovery service protocol (6000-6199 range)

ASCII-CHAT BINARY PROTOCOL ARCHITECTURE

Complete Protocol Overview

• Transport: TCP (client-server) or custom transports (WebRTC, WebSocket)
• Packet Format: Binary, little-endian with fixed headers
• Magic Number: 0xA5C11C4A1 (validates all packet types)
• Authentication: Ed25519 digital signatures (handshake) or Diffie-Hellman
• Encryption: XSalsa20-Poly1305 AEAD (after handshake)
• Integrity: CRC32 checksum per packet payload
• Client Identification: 32-bit client ID (0 = server, >0 = client)

Universal Packet Structure

ALL packets in ascii-chat (regardless of type) use the same 22-byte header:

Offset  Size  Field          Description
------  ----  -----          -----------
0       8     magic          Magic number 0xA5C11C4A1 (spells "ASCIICHAT" in hex)
8       2     type           Packet type enum (packet_type_t) - see full range below
10      4     length         Payload length in bytes (0 = header-only, max ~2MB)
14      4     crc32          CRC32 checksum of payload (0 if length == 0)
18      4     client_id      Client identifier (0=server, 1-9=clients)
22      N     payload        Payload data (N = length)
------
Total: 22 + payload_length bytes

Complete Packet Type System

The ascii-chat binary protocol uses multiple packet type ranges for different purposes:

Type 1: Protocol Version Negotiation

• PACKET_TYPE_PROTOCOL_VERSION = 1 (version and capabilities exchange)

Types 1000-1203: Cryptographic Handshake & Rekeying

• 1000-1099: Client hello and crypto capability exchange
• 1100-1109: Handshake exchange (key exchange, authentication)
• 1200-1203: Session encryption and rekeying
• Note: All handshake packets are ALWAYS sent unencrypted (plaintext)

Types 2000-2004: Session Messages

• 2000: Terminal size updates (width/height changes)
• 2001: Audio message data
• 2002: Text message data
• 2003: Error packets with error codes and messages
• 2004: Remote logging (bidirectional log forwarding)

Types 3000-3002: Media Frames

• 3000: ASCII art frames (pre-rendered terminal representation)
• 3001: Raw RGB image frames
• 3002: H.265/HEVC encoded video frames

Types 4000-4001: Audio Packets

• 4000: Batched raw audio samples
• 4001: Batched Opus-encoded audio (pre-compressed)

Types 5000-5008: Control & State

• 5000: Client capabilities (color, features, etc.)
• 5001: Keepalive ping packet
• 5002: Keepalive pong response
• 5003: Client join notification
• 5004: Client leave notification
• 5005: Stream start request
• 5006: Stream stop request
• 5007: Clear console command
• 5008: Server state broadcast to clients

Types 6000-6199: ACIP Discovery Service Protocol

• 6000-6008: Session management (create, join, leave, lookup)
• 6009-6010: WebRTC signaling (SDP, ICE candidates)
• 6020-6023: String reservation (reserve, renew, release)
• 6050-6051: Ring consensus protocol (future host election)
• 6060-6068: Host negotiation & migration (dynamic host failover)
• 6070-6071: Bandwidth testing
• 6075: Broadcast acknowledgment
• 6100-6104: Ring consensus statistics and election
• 6190-6199: Discovery keepalive ping and error responses

Encryption & Handshake Flow

Unencrypted Phase (connection establishment):

1. Client sends CRYPTO_CLIENT_HELLO (type 1000)
2. Server sends CRYPTO_CAPABILITIES (type 1100)
3. Exchange keys via CRYPTO_KEY_EXCHANGE_INIT/RESP (1102, 1103)
4. Authentication via CRYPTO_AUTH_CHALLENGE/RESPONSE (1104, 1105)
5. Server sends CRYPTO_HANDSHAKE_COMPLETE (type 1108)

Encrypted Phase (after handshake):

• All non-handshake packets are encrypted with XSalsa20-Poly1305
• Handshake packets are NEVER encrypted (protocol compliance)
• Rekeying packets (types 1201-1203) use old keys, then switch to new keys

ACIP (ASCII-Chat IP) Discovery Service

ACIP is the discovery protocol layer that runs on top of the core binary protocol. It enables P2P session discovery without a central server (decentralized mode).

ACIP Use Cases:

• Creating sessions with unique string identifiers (e.g., "blue-mountain-tiger")
• Looking up and joining sessions by string
• WebRTC offer/answer exchange for peer negotiation
• Dynamic host election when original host disconnects
• Participant notification when others join/leave

ACIP Transport:

• Default TCP port: 27225 (configurable for ACDS - ASCII-Chat Discovery Service)
• Uses same packet_header_t structure as all other packets
• Supports Ed25519 identity signatures for authentication
• Optional password protection per session

Integration with Other Modules

• network/packet.h: Complete packet_type_t enum with all ranges
• network/packet/parsing.h: Packet parsing and serialization
• network/acip/acds.h: ACDS message payload structures
• network/acip/transport.h: Transport abstraction (TCP, WebSocket, WebRTC)
• network/acip/acds_client.h: ACDS client connection API
• crypto/crypto.h: Encryption/decryption operations
• lib/network/acip (send.c, handlers.c, etc.): Protocol implementation

Version Information

• Protocol Version: 1.0
• Release Date: January 2026
• Status: Production
• Packet Format Stability: Version-locked to 1.0 (no breaking changes)

Note

The packet_header_t structure is identical for ALL 200+ packet types. The only difference is the 'type' field and payload structure.

CRC32 is computed over payload bytes ONLY (not including the 22-byte header).

This file documents protocol architecture. Detailed packet definitions are in network/packet.h (packet_type_t enum). Detailed ACIP message structures are in network/acip/acds.h.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Version

1.0 (Complete Binary Protocol Documentation)