Crate libp2p

Expand description

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::YamuxConfig::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.