Carrier Developer Guide

Carrier is Elastos's decentralized peer-to-peer communication network. Version 2 is based on a Kademlia DHT with modern cryptography.

Carrier v2 Architecture

┌──────────┐     Kademlia DHT     ┌──────────┐
│  Node A   │ ◄──────────────────► │  Node B   │
│           │    Ed25519 IDs       │           │
│  Ed25519  │    X25519 encrypt    │  Ed25519  │
│  key pair │                      │  key pair │
└──────────┘                      └──────────┘
      │                                  │
      │         ┌──────────┐             │
      └────────►│ Bootstrap │◄───────────┘
                │  Nodes    │
                └──────────┘

Key properties:

• Node identity: Ed25519 public key (32 bytes)
• Transport encryption: X25519 key exchange + symmetric encryption
• Discovery: Kademlia DHT for peer lookup
• NAT traversal: Active Proxy TCP relay (CryptoBox encrypted)

Carrier v2 Concepts

Concept	Description
Node	A participant in the network, identified by Ed25519 public key
Value	Data stored in the DHT (max 2KB, signed by owner)
Peer	A directly connected node
Service	A named capability announced by a node
Relay	A proxy node that forwards traffic for NAT-traversed nodes

Java SDK (Server-Side)

import org.elastos.carrier.Node;
import org.elastos.carrier.Configuration;
import org.elastos.carrier.PeerInfo;

public class CarrierServer {
    public static void main(String[] args) throws Exception {
        Configuration config = Configuration.builder()
            .setListeningPort(39001)
            .addBootstrapNode("router.elastos.io", 39001)
            .setStoragePath("/data/carrier")
            .build();

        Node node = new Node(config);
        node.start();

        System.out.println("Node ID: " + node.getId().toString());

        // Announce a service
        node.announceService("my-chat-service", 8080);

        // Find peers offering a service
        List<PeerInfo> peers = node.findService("my-chat-service");
        for (PeerInfo peer : peers) {
            System.out.println("Found peer: " + peer.getId() + " at " + peer.getAddress());
        }

        // Store a value in the DHT
        node.storeValue("my-key", "my-value".getBytes());

        // Retrieve a value from the DHT
        byte[] value = node.findValue("my-key");
        System.out.println("Value: " + new String(value));

        // Listen for incoming connections
        node.setConnectionHandler((connection) -> {
            byte[] data = connection.receive();
            System.out.println("Received: " + new String(data));
            connection.send("ACK".getBytes());
        });
    }
}

Carrier Use Cases

Use Case	How Carrier Helps
Messaging	Direct encrypted P2P messages between DIDs
File sharing	Stream files between peers without a central server
IoT	Device-to-device communication
Service discovery	Find nodes offering specific services via DHT
Relay/proxy	Route traffic for NAT-traversed devices

Carrier v1 (Deprecated)

caution

Carrier v1 was based on c-toxcore. If you see references to elastos_carrier_new() or ElaCarrier in legacy code, that is v1 and should not be used for new development. Migrate to v2.