libp2p Specifications

noise-libp2p is a security handshake for libp2p channels built using the Noise Protocol Framework. It is used by a transport upgrader to layer security over raw connections (like TCP sockets).

Key characteristics:

• Handshake Process: A dialer (initiator) and listener (responder) exchange public keys and perform Diffie-Hellman exchanges to derive symmetric encryption keys.
• Authentication: The static DH key used for the Noise handshake is authenticated using the libp2p identity keypair.
• Post-Handshake: Once the handshake completes, peers use the derived symmetric keys to encrypt traffic using a specific wire format.
• Maturity: Currently at lifecycle stage 3A (Recommendation) and is an active specification.

Gossipsub v1.1 is an evolution of the Gossipsub v1.0 protocol designed to improve bootstrapping and increase resistance to protocol attacks. It introduces several security extensions that modify local peer behavior.

Key features include:

• Explicit Peering Agreements
• PRUNE Backoff and Peer Exchange
• Flood Publishing
• Adaptive Gossip Dissemination
• Outbound Mesh Quotas
• Peer Scoring

Compatibility: Gossipsub v1.1 is fully backwards compatible with v1.0. Nodes implementing these extensions must advertise their support using the protocol string /meshsub/1.1.0.

Gossipsub is an extensible baseline publish-subscribe (pubsub) protocol designed for general-purpose use. It utilizes randomized topic meshes and gossip mechanisms to achieve moderate amplification factors and strong scaling properties.

Key characteristics:

• Extensibility: The protocol is designed to be extended by specialized routers that can add specific protocol messages and gossip patterns optimized for particular application profiles.
• Scalability: It is built to handle large-scale networks through efficient message propagation.

Before implementing Gossipsub, it is recommended to understand general PubSub concepts via the libp2p Publish/Subscribe guide.

The Rendezvous Protocol is a lightweight mechanism for generalized peer discovery in libp2p. It allows nodes to act as 'rendezvous points' where peers can register their presence within specific application-defined namespaces.

Key capabilities:

• Bootstrapping: Discovering critical services like circuit relays.
• Initialization: Finding peers within a specific pubsub topic.
• Real-time Discovery: Polling rendezvous points to find new peers as they join.
• Application-specific Routing: Discovering peers that host specific content shards or answer specific queries.

The protocol runs over libp2p streams using the protocol ID /rendezvous/1.0.0.

The libp2p specification aims to provide a flexible environment for peer-to-peer applications by supporting the following capabilities:

• Diverse Transports: Support for various protocols including TCP, UDP, SCTP, UDT, uTP, QUIC, and SSH.
• Authenticated Transports: Support for secure layers like TLS, DTLS, CurveCP, and SSH.
• Connection Efficiency: Efficient socket use through connection reuse and multiplexing multiple communications over a single socket to avoid handshake overhead.
• Protocol Negotiation: Support for multiple protocols and versions via a negotiation process.
• Network Resilience: Support for NAT traversal and connection relaying.
• Security: Support for encrypted channels.
• Optimization: Efficient use of underlying transports (e.g., native stream muxing or native authentication).

Yamux is a stream multiplexing protocol that allows multiple logical streams to be shared over a single underlying streaming connection. It uses a message framing mechanism to distinguish between different streams and control signals.

Key characteristics:

• Protocol String: /yamux/1.0.0 (used with multistream-select).
• Framing Overhead: Each frame has a 12-byte header.
• Stream IDs: Clients use odd IDs; servers use even IDs to prevent collisions. The ID 0 is reserved for session-level messages (Ping, Go Away).
• Flow Control: Each stream starts with a 256KiB window size. Window updates are used to manage per-stream flow control.

The libp2p Kademlia DHT is a distributed hash table subsystem based on the Kademlia whitepaper, with augmentations from S/Kademlia, Coral, and the BitTorrent DHT. It focuses on providing peer routing, value storage/retrieval, and content provider discovery.

Key characteristics include:

• Distance Metric: Calculated as XOR(sha256(key1), sha256(key2)).
• Replication: Controlled by the parameter k (recommended value: 20).
• Concurrency: Lookups are limited by the parameter α (default value: 10), meaning no more than 10 inflight requests per lookup process.
• Routing Table: Implementations must maintain k peers for every shared key prefix length L from 0 to 255 (for a 256-bit keyspace).

libp2p uses NAT Discovery to detect if a node is behind a Network Address Translation (NAT) device. This is critical for determining connectivity capabilities and peer reachability. There are two primary versions of the specification available:

• autonat v1: The initial version of the protocol.
• autonat v2: The updated version of the protocol.

Developers should refer to the specific version documentation to understand the protocol handshake, message formats, and state transitions for implementing or using NAT discovery in their libp2p implementation.

Gossipsub v1.0 is an extensible baseline pubsub protocol based on randomized topic meshes and gossip. It is designed for general-purpose use with moderate amplification factors and good scaling properties. It is intended to be extensible by specialized routers that can add protocol messages and gossip to optimize behavior for specific application profiles.

IMPORTANT: This is the original specification. For the current version, please refer to the gossipsub-v1.0 specification.