Skip to main content

Carrier Wire Protocol

Carrier v2 Architecture (C++)​

Repo: Elastos.Carrier.Native Version: 2.0.4 (C++17) DHT Protocol: Custom Kademlia

┌──────────────────────────────────────────────────────────┐
│                    Application Layer                      │
│   (Hive Node, Essentials, dApps, Services)               │
└──────────────────┬───────────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────────┐
│                    Addons / Services                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │Active Proxy │  │ DHT Proxy   │  │ Future Addons   │  │
│  │(TCP relay)  │  │(HTTP bridge)│  │                 │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
└──────────────────┬───────────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────────┐
│                 Core DHT Layer (Kademlia)                 │
│  ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │
│  │ Routing   │ │ Value    │ │ Peer     │ │ Token     │  │
│  │ Table     │ │ Storage  │ │ Storage  │ │ Manager   │  │
│  └───────────┘ └──────────┘ └──────────┘ └───────────┘  │
│  ┌───────────┐ ┌──────────┐ ┌──────────────────────┐    │
│  │ RPC       │ │ Task     │ │ Bootstrap Manager    │    │
│  │ Server    │ │ Manager  │ │                      │    │
│  └───────────┘ └──────────┘ └──────────────────────┘    │
└──────────────────┬───────────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────────┐
│              Crypto / Transport                           │
│  Ed25519 (Identity) │ X25519 (Encryption) │ UDP (DHT)    │
│  SHA-256 (Tokens)   │ CryptoBox (NaCl)    │ TCP (Proxy)  │
└──────────────────────────────────────────────────────────┘

Node Identity​

Each Carrier v2 node generates an Ed25519 key pair:

  • Public key = Node ID (32 bytes)
  • Used for DHT routing decisions (XOR distance metric)
  • Persistent across sessions (stored in key file)

DHT Implementation​

Kademlia Parameters:

  • Bucket size (k): 8
  • Alpha (parallel lookups): 3
  • Replication factor: Same as k
  • ID space: 256-bit (Ed25519 public key)
  • Distance metric: XOR

DHT Operations:

  • PING: Liveness check
  • FIND_NODE: Locate nodes closest to a target ID
  • STORE: Store a value at a key
  • FIND_VALUE: Retrieve a stored value

Token System: Anti-spam tokens using SHA-256 with time windows. Nodes must present valid tokens for STORE operations.

Bootstrap: Hardcoded bootstrap nodes for initial network entry. Subsequent peer discovery via iterative FIND_NODE lookups.

Message Encryption​

  • Transport: UDP for DHT messages, TCP for Active Proxy relay
  • Encryption: X25519 key agreement → AES-256-GCM symmetric encryption
  • Authentication: Ed25519 signatures on messages
  • Library: libsodium crypto_box (NaCl CryptoBox)

Active Proxy (NAT Traversal)​

When direct peer-to-peer connections fail due to NAT:

  1. Node announces itself to a known "super node" (relay)
  2. Super node maintains a TCP connection to the NATted node
  3. When another node wants to communicate, it routes through the relay
  4. Relay forwards packets bidirectionally
  5. Connection is still encrypted end-to-end (relay cannot read content)

Carrier v1 (Deprecated)​

Repo: Elastos.CarrierClassic.Native Base: c-toxcore fork Model: Friend-based (add friend → accept → communicate)

  • DHT: Tox-specific DHT
  • Crypto: Curve25519 (via libsodium)
  • NAT traversal: ICE/STUN/TURN via PJSIP/PJNATH
  • Extensions: Session (PseudoTCP), File Transfer
  • Status: Deprecated in favor of v2

Carrier v2 Java​

Repo: Elastos.Carrier.Java Same DHT protocol as C++ version:

  • CBOR encoding for DHT messages
  • Ed25519 for node identity
  • X25519 for encryption
  • UDP transport for DHT
  • SQLite for local storage