How Nodes Connect

How OctoMY™ 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

OctoMY™'s communication system provides:

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

Session Roles

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

Trust Integration

The communication system enforces trust levels:

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

Troubleshooting

Session Not Establishing

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

High Latency

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

Connection Drops

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

See Also

• Couriers and Sessions - Detailed courier documentation
• Discovery and Pairing - How nodes find each other
• Trust Levels - Security and permissions