py-libp2p Documentation

The libp2p package is organized into several specialized subpackages that handle different aspects of the libp2p protocol stack. Key functional areas include:

• Core Networking: libp2p.host, libp2p.network, libp2p.transport, and libp2p.peer.
• Security & Identity: libp2p.crypto, libp2p.identity, and libp2p.security.
• Routing & Discovery: libp2p.discovery, libp2p.kad_dht, libp2p.relay, and libp2p.peer_routing (via libp2p.peer).
• Communication Patterns: libp2p.pubsub, libp2p.request_response, and libp2p.stream_muxer.
• Data & Storage: libp2p.bitswap, libp2p.records, and libp2p.filecoin.
• Observability: libp2p.observability, libp2p.metrics, and libp2p.perf.

Py-libp2p is a Python implementation of the modular libp2p networking stack. It is designed for building decentralized applications, protocol research, and rapid prototyping within the Python ecosystem.

Supported Core Features

• Transports: TCP, QUIC (currently in final testing phase).
• Protocols: Gossipsub v1.1 and v1.2, Identify, Ping.
• Security: Noise protocol framework.
• Connection Management: Connection multiplexing.

Roadmap (Features in Development)

• NAT Traversal: AutoNAT and relay-based hole punching.
• WebSocket Transport: Currently in design/scoping phase.
• Peer Discovery: mDNS (planned) and a modular Bootstrap system (planned after mDNS).

The libp2p.pubsub package provides implementations for peer-to-peer Publish/Subscribe messaging. It supports two primary protocols:

1. GossipSub: A highly efficient protocol supporting the latest GossipSub 1.2 specification (including IDONTWANT control messages for bandwidth efficiency) and GossipSub 1.3 extensions (including Topic Observation).
2. FloodSub: A simpler broadcast-based protocol.

To use PubSub, you will typically interact with the libp2p.pubsub.pubsub module to manage topics and subscriptions.

The libp2p.security package provides various implementations for securing peer-to-peer connections. Depending on your requirements for encryption and authentication, you can use one of the following subpackages:

• libp2p.security.noise: The Noise protocol framework.
• libp2p.security.tls: Transport Layer Security (TLS).
• libp2p.security.secio: Secio protocol.
• libp2p.security.pnet: Pnet protocol.
• libp2p.security.insecure: An insecure implementation (not for production use, typically used for testing or local development).

The py-libp2p package provides a Filecoin-focused Developer Experience (DX) layer. It includes protocol IDs, topic formats, and bootstrap presets designed to interoperate at the libp2p layer with the Filecoin network.

Key Capabilities:

• Protocol/Topic Constants: Implemented in libp2p.filecoin (pinned from upstream snapshots).
• Bootstrap Address Handling: Includes canonical and runtime helpers (e.g., get_runtime_bootstrap_addresses).
• Read-only Gossip Observation: Supported via observer workflows.
• Peer Diagnostics: Examples provided for connect, ping, and identify to check interoperability.

The libp2p.transport package provides various transport implementations for establishing network connections. Depending on your requirements for reliability, speed, or browser compatibility, you can use one of the following subpackages:

• TCP: Standard Transmission Control Protocol transport (libp2p.transport.tcp).
• QUIC: A modern, multiplexed, and encrypted transport protocol (libp2p.transport.quic).
• WebSocket: Transport for environments requiring WebSocket support, often used for web compatibility (libp2p.transport.websocket).
• WebRTC: Transport for peer-to-peer communication in web browsers or via WebRTC-capable nodes (libp2p.transport.webrtc).

The libp2p.perf package implements the libp2p performance measurement protocol. It allows you to measure the throughput between two libp2p nodes by sending and receiving configurable amounts of data.

The package is organized into several submodules:

• libp2p.perf.perf_service: The primary service module for managing performance measurements.
• libp2p.perf.constants: Contains protocol-specific constants.
• libp2p.perf.types: Defines the data types used within the performance measurement protocol.

The Random Walk discovery functionality is composed of several submodules that you can interact with to implement peer discovery:

• libp2p.discovery.random_walk.random_walk: The core module containing the logic for performing the random walk.
• libp2p.discovery.random_walk.config: Used to define and manage configuration settings for the discovery process.
• libp2p.discovery.random_walk.rt_refresh_manager: Manages the periodic refreshing of the routing table (RT) to ensure network health.
• libp2p.discovery.random_walk.exceptions: Contains specific exception types raised during the discovery process.

The libp2p.utils package provides a collection of utility modules for common libp2p tasks. Key submodules include:

• libp2p.utils.logging: Utilities for configuring and managing logs.
• libp2p.utils.multiaddr_utils: Helpers for working with multiaddr formats.
• libp2p.utils.varint: Implementation of variable-length integer encoding/decoding.
• libp2p.utils.version: Utilities for handling and checking versions.
• libp2p.utils.paths: Helpers for managing file system paths.
• libp2p.utils.address_validation: Tools for validating network addresses.
• libp2p.utils.dns_utils: Utilities for DNS-related operations.

The libp2p.network package is the core networking layer of the library. It is organized into several subpackages and modules that handle different aspects of peer-to-peer connectivity:

• libp2p.network.connection: Manages low-level connection logic.
• libp2p.network.stream: Handles multiplexed streams over connections.
• libp2p.network.swarm: Provides the Swarm abstraction, which manages multiple connections, security, and multiplexing to provide a unified interface for peer communication.
• libp2p.network.exceptions: Contains the exception hierarchy for networking-related errors.