Carrier Architecture

Carrier v2 is a ground-up peer-to-peer communication framework built on a custom Kademlia DHT. The architecture is layered so that applications interact with high-level APIs while the network handles discovery, relay, encryption, and anti-spam internally.

Architectural Layers

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

Each layer has a well-defined responsibility:

• Application Layer: Your application consumes Carrier APIs. It never interacts with the DHT or transport directly.
• Addons/Services: Pluggable modules that extend core capabilities. Active Proxy and DHT Proxy are the two shipping addons; the architecture supports adding more without modifying the core.
• Core DHT Layer: The Kademlia engine that powers peer discovery, value storage, and service announcement.
• Crypto/Transport: Handles all wire-level concerns: identity keys, encryption, hashing, and the actual UDP/TCP sockets.

DHT: Kademlia in Depth

Carrier v2 uses a custom Kademlia distributed hash table as its discovery and storage backbone.

Key Space and Distance

• 256-bit key space: Every node ID and storage key occupies a position in a 256-bit address space (derived from Ed25519 public keys).
• XOR distance metric: The "distance" between two IDs is their bitwise XOR. This is symmetric (d(A,B) = d(B,A)) and satisfies the triangle inequality, which guarantees that iterative lookups converge.
• Node ID derivation: Each node's ID is derived from its Ed25519 public key, binding identity to network position.

K-Buckets

The routing table is organized into k-buckets where k = 8:

• Each bucket holds up to 8 contacts whose distance from the local node falls within a specific bit-range.
• Buckets closer to the node's own ID split as they fill, while distant buckets stay coarse; this naturally keeps more detail about the local neighborhood and less about distant regions.
• Stale entries are evicted only when a replacement is confirmed alive, which makes the routing table resistant to churn.

Iterative Lookups

Lookups proceed iteratively with a parallelism factor α = 3:

1. The initiating node selects the α closest known nodes to the target from its routing table.
2. It sends a FIND_NODE (or FIND_VALUE / FIND_PEER) request to those nodes in parallel.
3. Each responding node returns its own closest contacts to the target.
4. The initiator merges results, picks the next-closest unqueried nodes, and repeats.
5. The lookup terminates when the closest k nodes have all been queried and no closer node is discovered.

Core DHT Operations

Operation	Purpose
FIND_NODE	Locate the k nodes closest to a given ID: the fundamental routing primitive.
FIND_VALUE	Retrieve a small value stored under a key in the DHT.
FIND_PEER	Discover peers that have announced a particular service or capability.
STORE_VALUE	Publish a small record (≤ 2 KB, signed by owner) under a key.
ANNOUNCE_PEER	Advertise that this node offers a named service (discoverable via FIND_PEER).

Internal Components

• Routing Table: K-bucket structure maintaining known live contacts, ordered by XOR distance.
• Value Storage: Local store for DHT key-value records with expiration and replication.
• Peer Storage: Tracks announced peer/service advertisements from the network.
• Token Manager: Issues and validates anti-spam tokens (see below).
• RPC Server: Handles incoming DHT protocol messages over UDP.
• Task Manager: Schedules and executes asynchronous DHT operations (lookups, refreshes, replication).
• Bootstrap Manager: Manages initial network entry through known bootstrap nodes, then periodic routing table refresh.

Token System: Anti-Spam

To prevent DHT pollution, Carrier uses SHA-256-based anti-spam tokens:

• Before a node can execute a STORE_VALUE or ANNOUNCE_PEER operation, it must obtain a token from nodes in the target's neighborhood.
• Tokens are generated using SHA-256 over a combination of the requester's address and a rotating secret. They are time-windowed: valid only for a limited period.
• A difficulty-based mining requirement can be imposed, forcing the requester to perform proof-of-work before the token is accepted. This raises the computational cost of bulk spam while remaining negligible for legitimate single-store operations.
• Tokens are verified by the receiving node before accepting any write operation.

This design does not eliminate abuse entirely, but it makes flooding the DHT with garbage significantly more expensive than legitimate use.

Active Proxy: NAT Traversal

Most real-world devices sit behind NAT or restrictive firewalls. Active Proxy provides a TCP relay path so that nodes unreachable by direct UDP can still participate fully.

How It Works

┌──────────┐       TCP        ┌──────────────┐       TCP       ┌──────────┐
│  Node A  │◄────────────────►│ Active Proxy │◄───────────────►│  Node B  │
│ (behind  │  CryptoBox NaCl  │   (relay)    │  CryptoBox NaCl │ (public) │
│   NAT)   │                  │              │                 │          │
└──────────┘                  └──────────────┘                 └──────────┘

1. Upstream: A NATted node opens a persistent TCP connection to a known Active Proxy node and authenticates using its Ed25519 identity.
2. Downstream: When another node wants to reach the NATted node, it connects to the same proxy. The proxy relays traffic bidirectionally.
3. Encryption: All sessions between the end nodes use CryptoBox (NaCl) authenticated encryption. The proxy forwards ciphertext; it cannot read the payload.
4. Keepalive: The NATted node sends periodic pings to keep the TCP connection through NAT alive.

Upstream / Downstream Model

• Upstream connection: The NATted node → Active Proxy. This is the "always-on" link that makes the node reachable.
• Downstream connection: Any external node → Active Proxy → forwarded to the NATted node. The proxy matches incoming requests to the correct upstream connection by node ID.

Network Ports

Protocol	Port	Purpose
UDP	39001	DHT protocol messages (FIND_NODE, STORE_VALUE, etc.)
TCP	Configurable	Active Proxy relay connections

Firewall configuration

If you are running a node that must be directly reachable (not behind a proxy), ensure UDP 39001 is open for inbound DHT traffic. If you are running an Active Proxy relay, you also need the configured TCP port open for inbound relay connections.

Cryptographic Primitives Summary

Primitive	Usage
Ed25519	Node identity key pair: used for signing DHT messages and authenticating to relays.
X25519	Diffie-Hellman key agreement: derives shared secrets for encrypted sessions.
SHA-256	Token generation, content addressing, integrity checks.
CryptoBox (NaCl)	Authenticated public-key encryption for Active Proxy sessions and peer-to-peer payloads.
AES-256-GCM	Symmetric authenticated encryption for bulk data after key agreement.

All cryptographic operations use libsodium (C++ implementation) or TweetNaCl (Java implementation): well-audited, constant-time libraries with no custom primitives.

Note: Runtime Carrier Layer

The architecture described on this page covers classic Carrier v2 (Kademlia DHT, Active Proxy, libsodium/TweetNaCl crypto). In the ElastOS Runtime, "Carrier" also refers to the trust enforcement layer that uses Iroh/QUIC for transport and provides capability token enforcement across capsule boundaries. See Carrier P2P for more on how these two roles relate.