How nodes connect

Secure peer-to-peer communication in Korall Engineering™

How Korall Engineering™ nodes establish and maintain secure peer-to-peer connections.

Key Achievement

The communication system enables direct, encrypted communication between nodes without requiring a central server. Once paired, nodes can exchange data in real-time with sub-second latency.

Overview

Korall Engineering™'s communication system provides:

Feature	Description
Direct P2P	Nodes communicate directly, no relay server required
Secure	Traffic encrypted (when enabled) with per-session AEAD keys derived during handshake
Reliable	Per-courier reliability (e.g., BlobCourier has chunk-level acks)
Efficient	UDP-based for low latency, minimal overhead

Architecture

The communication stack has three layers:

┌─────────────────────────────────────┐
│          Couriers                   │  ← Application data (sensors, state, files)
├─────────────────────────────────────┤
│      CommsChannel / Comms           │  ← Session management, multiplexing
├─────────────────────────────────────┤
│      CommsCarrierUDP                │  ← Network transport (UDP)
└─────────────────────────────────────┘

CommsCarrierUDP

The transport layer handles:

UDP socket management
Port binding with fallback ranges
Packet transmission and reception
Connection maintenance timers

CommsChannel / Comms

The session layer handles:

Three-way handshake protocol
Session lifecycle management
Courier scheduling and dispatch
Reliability system integration

Couriers

The application layer provides:

Typed message handlers
Priority-based scheduling
Application-specific protocols

Session Establishment

Sessions are established using a three-way handshake:

    Node A                    Node B
       │                         │
       │──────── SYN ───────────>│  (encrypted with B's public key)
       │                         │  (includes key material for session key derivation)
       │<─────── SYN-ACK ────────│  (encrypted with A's public key)
       │                         │
       │──────── ACK ───────────>│  (encrypted with B's public key)
       │                         │
       │     Session Active      │
       │  (session key derived,  │
       │   AEAD encryption of    │
       │   courier data begins)  │

Handshake States

State	Description
`SYN_SENT`	SYN sent, awaiting SYN-ACK
`SYN_RECEIVED`	SYN received, SYN-ACK sent, awaiting ACK
`ESTABLISHED`	Handshake complete, session active
`FAILED`	Handshake failed or timed out

Session Roles

Role	Description
INITIATOR	Node that sends first SYN
ADHERENT	Node that responds to SYN

When both nodes initiate simultaneously, a "duel" is resolved deterministically using ID comparison.

Reliability System

Reliability is per-courier, not per-packet. The transport layer does not add reliability headers; instead, individual couriers manage their own acknowledgment and retransmission as needed. RTT is measured via SessionCourier heartbeat echo timestamps and fed to FlowControl for send rate adjustment.

ReliabilitySystem is available as a utility class for couriers that need it.

Courier Reliability Strategies

Courier Type	Reliability	Strategy
AgentStateCourier	None	Fresh data preferred over old retransmits
SensorsCourier	None	Time-sensitive, staleness worse than loss
BlobCourier	Chunk-level	Internal ack system (`BlobCourier::Ack`) for per-chunk tracking
SessionCourier	None	Heartbeat — loss is harmless
CommandCourier	None	User will retry if needed

Trust Integration

The communication system enforces trust levels:

Trust Level	Communication
TRUSTED	Full communication allowed
UNSET	Limited discovery only
IGNORED	Silently dropped
BLOCKED	Actively rejected

Sessions are only established with TRUSTED peers.

Connection Flow

The complete flow from discovery to active communication:

1. Discovery
   └── LANDiscovery broadcasts presence
   └── Peer responds with identity

2. Pairing
   └── QR code or PIN verification
   └── User sets trust level to TRUSTED
   └── Keys exchanged and stored

3. Session Establishment
   └── Courier registered (triggers need for connection)
   └── Handshake initiated (SYN → SYN-ACK → ACK)
   └── Session becomes ESTABLISHED

4. Active Communication
   └── Couriers send data on their mandates
   └── Reliability system tracks delivery
   └── Keep-alive maintains session

Configuration

Port Configuration

Default ports:

Main port: 8126
Fallback range: 8426-8475
LAN Discovery: 8473 (broadcast)

Timing Configuration

Parameter	Default	Description
Handshake timeout	5s	Time to complete handshake
Session timeout	30s	Inactivity before session expires
Keep-alive interval	10s	Ping frequency for idle sessions
Honeymoon duration	20s	Aggressive connection period

Troubleshooting

Session Not Establishing

Check trust level - Peer must be TRUSTED
Verify network - Nodes must be reachable (same LAN or NAT traversed)
Check logs - Look for SYN/SYN-ACK/ACK messages
Verify couriers - At least one courier must be registered

High Latency

Check network conditions - Packet loss, congestion
Review courier priorities - High-priority couriers may starve others
Check reliability overhead - Retransmissions add latency

Connection Drops

Check keep-alive - Ensure packets are being sent
Verify timeout settings - May need adjustment for network conditions
Check for NAT issues - UDP hole-punching may expire