libp2p/specs

libp2p specification

Overview

This repository contains the specifications for libp2p, a framework and suite of protocols for building peer-to-peer network applications. libp2p has several implementations, with more in development.

The main goal of this repository is to provide accurate reference documentation for the aspects of libp2p that are independent of language or implementation. This includes wire protocols, addressing conventions, and other "network level" concerns.

For user-facing documentation, please see https://docs.libp2p.io

In addition to describing the current state of libp2p, the specs repository serves as a coordination point and a venue to drive future developments in libp2p. For the short and long term roadmap see ROADMAP.md. To participate in the evolution of libp2p via the specs process, please see the Contributions section.

Status

The specifications for libp2p are currently incomplete, and we are working to address this by revising existing specs to ensure correctness and writing new specifications to detail currently unspecified parts of libp2p.

This document replaces an earlier RFC, which still contains much useful information and is helpful for understanding the libp2p design philosophy. It is avaliable at _archive/README.md.

Specification Index

This index contains links to all the spec documents that are currently merged. If documents are moved to new locations within the repository, this index will be updated to reflect the new locations.

Specs Framework

These specs define processes for the specification framework itself, such as the expected lifecycle and document formatting.

• Spec Lifecycle - The process for introducing, revising and adopting specs.
• Document Header - A standard document header for libp2p specs.

Core Abstractions and Types

These specs define abstractions and data types that form the "core" of libp2p and are used throughout the system.

• Addressing - Working with addresses in libp2p.
• Connections and Upgrading - Establishing secure, multiplexed connections between peers, possibly over insecure, single stream transports.
• Peer Ids and Keys - Public key types & encodings, peer id calculation, and message signing semantics

Protocols

These specs define wire protocols that are used by libp2p for connectivity, security, multiplexing, and other purposes.

The protocols described below all use protocol buffers (aka protobuf) to define message schemas.

Existing protocols may use proto2, and continue to use them. proto3 is recommended for new protocols. proto3 is a simplification of proto2 and removes some footguns. For context and a discussion around proto3 vs proto2, see #465.

• ping - Ping protocol
• autonat - NAT detection
• identify - Exchange keys and addresses with other peers
• kademlia - The Kademlia Distributed Hash Table (DHT) subsystem
• mdns - Local peer discovery with zero configuration using multicast DNS
• mplex - The friendly stream multiplexer
• yamux - Yet Another Multiplexer
• noise - The libp2p Noise handshake
• plaintext - An insecure transport for non-production usage
• pnet - Private networking in libp2p using pre-shared keys
• pubsub - PubSub interface for libp2p
  • gossipsub - An extensible baseline PubSub protocol
    • episub - Proximity Aware Epidemic PubSub for libp2p
• relay - Circuit Switching for libp2p (similar to TURN)
  • dcutr - Direct Connection Upgrade through Relay protocol
• rendezvous - Rendezvous Protocol for generalized peer discovery
• secio - SECIO, a transport security protocol for libp2p
• tls - The libp2p TLS Handshake (TLS 1.3+)
• quic - The libp2p QUIC Handshake
• webrtc - The libp2p WebRTC transports
• WebTransport - Using WebTransport in libp2p

Contributions

Thanks for your interest in improving libp2p! We welcome contributions from all interested parties. Please take a look at the Spec Lifecycle document to get a feel for how the process works, and open an issue if there's work you'd like to discuss.

For discussions about libp2p that aren't specific to a particular spec, or if you feel an issue isn't the appropriate place for your topic, please join our discussion forum and post a new topic in the contributor's section.