P2P Networking

The aleph-network crate provides peer discovery, gossip-based message propagation, and topic-based subscriptions using an abstraction over libp2p.

Overview

The networking layer handles all node-to-node communication outside of on-chain transactions. It provides:

• Peer Discovery — Find and connect to other nodes in the mesh
• Gossip Pub/Sub — Broadcast messages to topic subscribers
• Topic Subscriptions — Filter messages by topic (jobs, storage, heartbeats)

Modules

Module	Key Types	Purpose
service	NetworkService	Main networking service managing connections and message routing
discovery	DiscoveryService	Peer discovery via Kademlia DHT and bootstrap nodes
types	PeerId, PeerInfo, GossipTopic, NetworkMessage	Core networking types

NetworkService

pub struct NetworkService {
    peer_id: PeerId,
    peers: HashMap<PeerId, PeerInfo>,
    subscriptions: HashMap<GossipTopic, Vec<Sender>>,
}

impl NetworkService {
    /// Publish a message to all subscribers of a topic
    pub async fn publish(
        &self,
        topic: GossipTopic,
        message: NetworkMessage,
    ) -> Result<()>;

    /// Subscribe to messages on a topic
    pub fn subscribe(
        &mut self,
        topic: GossipTopic,
    ) -> Receiver<NetworkMessage>;

    /// Get connected peer count
    pub fn peer_count(&self) -> usize;
}

Gossip Topics

pub enum GossipTopic {
    Jobs,           // Job creation, assignment, status updates
    Storage,        // Storage commitments, proofs, challenges
    Heartbeats,     // Node heartbeat broadcasts
    Scheduling,     // Scheduler coordination (coordinator only)
    Sync,           // State synchronization between nodes
}

Peer Discovery

Discovery happens through multiple mechanisms:

1. Bootstrap nodes — Hard-coded initial peers in config
2. On-chain registry — Active nodes from NodeRegistry contain connection metadata
3. Kademlia DHT — Distributed hash table for decentralized peer discovery

pub struct DiscoveryService {
    bootstrap_peers: Vec<Multiaddr>,
    known_peers: HashSet<PeerId>,
    discovery_interval: Duration,
}

impl DiscoveryService {
    /// Discover new peers and return their info
    pub async fn discover(&mut self) -> Vec<PeerInfo>;

    /// Add a bootstrap peer
    pub fn add_bootstrap(&mut self, addr: Multiaddr);
}

Transport Stack

The libp2p transport stack uses:

• QUIC — Primary transport (UDP-based, built-in TLS)
• Noise — Encryption protocol for TCP fallback
• Yamux — Stream multiplexing over a single connection
• GossipSub — Pub/sub protocol for topic-based messaging

# Network configuration
[network]
listen_addr = "/ip4/0.0.0.0/udp/4001/quic-v1"
external_addr = "/ip4/YOUR_IP/udp/4001/quic-v1"
max_connections = 256
idle_timeout_secs = 300
bootstrap_peers = [
    "/ip4/boot1.aleph.cloud/udp/4001/quic-v1/p2p/12D3KooW...",
    "/ip4/boot2.aleph.cloud/udp/4001/quic-v1/p2p/12D3KooW..."
]

Message Types

pub struct NetworkMessage {
    pub id: MessageId,
    pub sender: PeerId,
    pub topic: GossipTopic,
    pub payload: Vec<u8>,
    pub timestamp: u64,
    pub signature: Signature,
}