Skip to main content

Network

Overview​

This document provides an overview of the networking component of Calimero Network, which is implemented using the libp2p library. The network consists of two types of peers: client nodes and boot nodes, each serving distinct roles and utilizing specific protocols to facilitate peer-to-peer communication. Client node is the component which hosts and runs client applications, communicates and shares data between other client nodes. Boot node is the component used for the initial discovery of the peers in the network.

Node Types​

Client Node​

  • Deployment: Can run on any machine

  • Protocols Utilized:

  • Behavior:

    • Configuration: A client node can be configured to use zero boot nodes.
    • External Address:
      • Direct Public External Address: Nodes with a direct public external address do not require reservation at the relay server. These nodes publish their public external address to the Kademlia DHT, making them directly accessible to other peers.
      • Relayed External Address: Nodes that do not have a direct public external address, typically those behind a NAT or firewall, can obtain a relayed external address by requesting a reservation at a relay server. Once the reservation is accepted, the node publishes its new external address to the rendezvous server. This allows other nodes to discover relayed addresses of a peers in a certain rendezvous namespace. The relay server can be used for the coordination of the hole punching between two nodes. If the hole punching attempt fails, the relay server will bridge the traffic.
    • Discovery Protocols: mDNS, rendezvous and Kademlia
    • Connection Management: A peer, identified via PeerId, can be discovered either via mDNS, rendezvous or Kademlia. mDNS discovery provides local network addresses, rendezvous discovery provides relayed addresses, and Kademlia discovery provides direct public external addresses. The node maintains information about its connections to peers, including the discovery source. For a discovered external address, either relayed or direct public, the node will only attempt to dial the peer if the same peer is not already connected via a discovered local address. This ensures that local connections have higher priority and that there are no unnecessary hole punching attempts.
    • Message Relaying: The node participates in the gossipsub protocol, relaying messages to all connected peers that support it. This enables efficient and scalable message dissemination across the network.

Boot Node​

  • Deployment: Must run on a publicly available machine with a static IP address.

  • Protocols Utilized:

  • Behavior:

    • Characteristics: Boot nodes are publicly available, long-running nodes that provide stable entry points to the network.
    • Functions:
      • Bootstrap Node: Acts as a well-known peer for the Kademlia protocol, facilitating peer discovery and network join operations.
      • Circuit Relay Server: Serves as a generic relay that provides the medium that facilitates the hole punching, enabling peers to establish direct connections even when they are behind NAT or firewalls. The relay server is used for the coordination of the hole punching between two nodes, and briding traffic if the hole punching attempt fails.
      • Rendezvous Server: Facilitates peer discovery by allowing nodes to register their presence and query for other peers within a shared rendezvous namespace. This enables dynamic and efficient peer-to-peer connections without relying on a static list of peers.

P2P protocols and techniques​

Protocol Descriptions​

DCUtR (Direct Connection Upgrade through Relay)​

  • DCUtR is used to upgrade connections through relay nodes, allowing peers to establish direct connections even if they are behind NATs or firewalls. Peers initially connect via a relay node, then use the DCUtR protocol to attempt a direct connection, which reduces latency and bandwidth usage.
  • Reference: libp2p DCUtR Documentation

Gossipsub​

  • Gossipsub is a scalable and efficient pub-sub protocol for message dissemination. It combines the best aspects of gossip protocols and topic-based pub-sub systems. It minimizes bandwidth usage by only gossiping metadata and ensuring that messages are only sent once per peer.
  • Reference: libp2p Gossipsub Documentation

Identify​

  • The Identify protocol allows peers to identify themselves and share their capabilities with other peers. Peers exchange identification information such as supported protocols, listen addresses, and public keys. This helps peers make informed decisions about connecting and interacting.
  • Reference: libp2p Identify Documentation

Kademlia (Kad)​

  • Kademlia is a distributed hash table (DHT) protocol used for peer discovery and data routing. It uses an XOR metric to ensure efficient and scalable peer lookup. Each node maintains a routing table with information about other nodes, facilitating quick lookups and robust network operation.
  • Reference: libp2p Kademlia DHT Documentation

mDNS (Multicast DNS)​

  • mDNS enables local network peer discovery without the need for a central server. It uses multicast DNS to allow peers to find each other on the same local network by broadcasting their presence and listening for broadcasts from other peers.
  • Reference: libp2p mDNS Documentation

Ping​

  • The Ping protocol measures the round-trip time (latency) between peers. It regularly pings connected peers and measures the time it takes for a response. This helps in maintaining healthy connections and understanding network latency.
  • Reference: libp2p Ping Documentation

Relay​

  • The Relay protocol supports relay-based communication, allowing peers to communicate through intermediary nodes when direct connections are not possible. Nodes can use relay nodes to forward their traffic, which is especially useful for nodes behind NATs or firewalls. The protocol includes mechanisms for reserving relay slots and managing relay connections.
  • Reference: libp2p Relay Documentation

Rendezvous​

  • The Rendezvous protocol enables peers to discover each other by registering at and querying a shared rendezvous point. This is useful for dynamically finding peers without needing a central directory or pre-established list of peers. Peers register their presence at a rendezvous server and can also query the server to find other peers.
  • Reference: libp2p Rendezvous Documentation

NAT Traversal Techniques​

One of the common techniques used for NAT traversal in P2P networks is Hole Punching. This technique allows two peers, each behind a NAT, to establish a direct connection with each other. Here's a brief explanation:

  • Hole Punching: This technique involves three steps:
    • Step 1 - Connection to Public Server: Both peers initially connect to a public server (in this case, the relay server). This creates a NAT mapping (a "hole") for outgoing packets to the server.
    • Step 2 - Exchange of Address Information: The server shares the public address information of each peer with the other. This information includes the IP address and port number that the NAT has assigned for the connection to the server.
    • Step 3 - Direct Connection: Each peer sends a packet to the other peer's public address. Since a mapping for this address already exists in the NAT (from the connection to the server), the NAT forwards the packet to the appropriate internal address, and a direct connection is established.

This technique is particularly useful in P2P networks, as it allows peers to communicate directly, reducing the load on relay servers and improving network efficiency. However, it's worth noting that hole punching may not work with all types of NATs, and success can depend on the specific NAT implementation and configuration.

Was this page helpful?
Need some help? Check Support page