Crate libp2p[−][src]

Libp2p is a peer-to-peer framework.

Major libp2p concepts

Here is a list of all the major concepts of libp2p.

Multiaddr

A Multiaddr is a self-describing network address and protocol stack that is used to establish connections to peers. Some examples:

/ip4/80.123.90.4/tcp/5432
/ip6/[::1]/udp/10560/quic
/unix//path/to/socket

Transport is a trait for types that provide connection-oriented communication channels based on dialing to or listening on a Multiaddr. To that end a transport produces as output a type of data stream that varies depending on the concrete type of transport.

An implementation of transport typically supports only certain multi-addresses. For example, the TcpConfig only supports multi-addresses of the format /ip4/.../tcp/....

Example (Dialing a TCP/IP multi-address):

use libp2p::{Multiaddr, Transport, tcp::TcpConfig};
let tcp = TcpConfig::new();
let addr: Multiaddr = "/ip4/98.97.96.95/tcp/20500".parse().expect("invalid multiaddr");
let _conn = tcp.dial(addr);

In the above example, _conn is a Future that needs to be polled in order for the dialing to take place and eventually resolve to a connection. Polling futures is typically done through a tokio runtime.

The easiest way to create a transport is to use build_development_transport. This function provides support for the most common protocols but it is also subject to change over time and should thus not be used in production configurations.

Example (Creating a development transport):

let keypair = libp2p::identity::Keypair::generate_ed25519();
let _transport = libp2p::build_development_transport(keypair);
// _transport.dial(...);

The keypair that is passed as an argument in the above example is used to set up transport-layer encryption using a newly generated long-term identity keypair. The public key of this keypair uniquely identifies the node in the network in the form of a PeerId.

See the documentation of the Transport trait for more details.

Connection Upgrades

Once a connection has been established with a remote through a Transport, it can be upgraded. Upgrading a transport is the process of negotiating an additional protocol with the remote, mediated through a negotiation protocol called multistream-select.

Example (noise + yamux Protocol Upgrade):

use libp2p::{Transport, core::upgrade, tcp::TcpConfig, noise, identity::Keypair, yamux};
let tcp = TcpConfig::new();
let id_keys = Keypair::generate_ed25519();
let noise_keys = noise::Keypair::<noise::X25519Spec>::new().into_authentic(&id_keys).unwrap();
let noise = noise::NoiseConfig::xx(noise_keys).into_authenticated();
let yamux = yamux::Config::default();
let transport = tcp.upgrade(upgrade::Version::V1).authenticate(noise).multiplex(yamux);

In this example, transport is a new Transport that negotiates the noise and yamux protocols on all connections.

Network Behaviour

The NetworkBehaviour trait is implemented on types that provide some capability to the network. Examples of network behaviours include:

Periodically pinging other nodes on established connections.
Periodically asking for information from other nodes.
Querying information from a DHT and propagating it to other nodes.

Swarm

A Swarm manages a pool of connections established through a Transport and drives a NetworkBehaviour through emitting events triggered by activity on the managed connections. Creating a Swarm thus involves combining a Transport with a NetworkBehaviour.

See the documentation of the core module for more details about swarms.

Using libp2p

The easiest way to get started with libp2p involves the following steps:

Creating an identity Keypair for the local node, obtaining the local PeerId from the PublicKey.
Creating an instance of a base Transport, e.g. TcpConfig, upgrading it with all the desired protocols, such as for transport security and multiplexing. In order to be usable with a Swarm later, the Output of the final transport must be a tuple of a PeerId and a value whose type implements StreamMuxer (e.g. Yamux). The peer ID must be the identity of the remote peer of the established connection, which is usually obtained through a transport encryption protocol such as noise that authenticates the peer. See the implementation of build_development_transport for an example.
Creating a struct that implements the NetworkBehaviour trait and combines all the desired network behaviours, implementing the event handlers as per the desired application’s networking logic.
Instantiating a Swarm with the transport, the network behaviour and the local peer ID from the previous steps.

The swarm instance can then be polled e.g. with the tokio library, in order to continuously drive the network activity of the program.

Re-exports

pub use bytes;

pub use futures;

pub use self::simple::SimpleProtocol;

Modules

bandwidth
core	Transports, upgrades, multiplexing and node handling of libp2p.
deflate
dns	libp2p-dns
floodsub	Implements the floodsub protocol, see also the: spec.
gossipsub	Gossipsub is a P2P pubsub (publish/subscription) routing layer designed to extend upon flooodsub and meshsub routing protocols.
identify	Implementation of the Identify protocol.
identity	A node’s network identity keys.
kad	Implementation of the libp2p-specific Kademlia protocol.
mdns	mDNS is a protocol defined by RFC 6762 that allows querying nodes that correspond to a certain domain name.
mplex
multiaddr
multihash	Multihash
noise	Noise protocol framework support for libp2p.
ping	This module implements the `/ipfs/ping/1.0.0` protocol.
plaintext
pnet	The `pnet` protocol implements Pre-shared Key Based Private Networks in libp2p, as specified in the spec
request_response	Generic request/response protocols.
simple
swarm	High level manager of the network.
tcp	Implementation of the libp2p `Transport` trait for TCP/IP.
uds	Implementation of the libp2p `Transport` trait for Unix domain sockets.
wasm_ext	Implementation of the libp2p `Transport` trait for external transports.
websocket	Implementation of the libp2p `Transport` trait for Websockets.
yamux	Implements the Yamux multiplexing protocol for libp2p, see also the specification.

Macros

build_multiaddr

Easy way for a user to create a Multiaddr.

Structs

Multiaddr	Representation of a Multiaddr.
PeerId	Identifier of a peer of the network.

Enums

TransportError

An error during dialing or listening on a Transport.

Traits

InboundUpgrade	Possible upgrade on an inbound connection or substream.
InboundUpgradeExt	Extension trait for `InboundUpgrade`. Automatically implemented on all types that implement `InboundUpgrade`.
OutboundUpgrade	Possible upgrade on an outbound connection or substream.
OutboundUpgradeExt	Extention trait for `OutboundUpgrade`. Automatically implemented on all types that implement `OutboundUpgrade`.
Transport	A transport provides connection-oriented communication between two peers through ordered streams of data (i.e. connections).
TransportExt	Trait automatically implemented on all objects that implement `Transport`. Provides some additional utilities.

Functions

build_development_transport	Builds a `Transport` that supports the most commonly-used protocols that libp2p supports.
build_tcp_ws_noise_mplex_yamux	Builds an implementation of `Transport` that is suitable for usage with the `Swarm`.
build_tcp_ws_pnet_noise_mplex_yamux	Builds an implementation of `Transport` that is suitable for usage with the `Swarm`.

Type Definitions

Swarm

Contains the state of the network, plus the way it should behave.

Derive Macros

NetworkBehaviour

Generates a delegating NetworkBehaviour implementation for the struct this is used for. See the trait documentation for better description.