[][src]Crate susyp2p

Libp2p is a peer-to-peer framework.

Major susyp2p concepts

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


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

  • /ip4/
  • /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 susyp2p::{Multiaddr, Transport, tcp::TcpConfig};
let tcp = TcpConfig::new();
let addr: Multiaddr = "/ip4/".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 = susyp2p::identity::Keypair::generate_ed25519();
let _transport = susyp2p::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 (secio Protocol Upgrade):

use susyp2p::{Transport, tcp::TcpConfig, secio::SecioConfig, identity::Keypair};
let tcp = TcpConfig::new();
let secio_upgrade = SecioConfig::new(Keypair::generate_ed25519());
let tcp_secio = tcp.with_upgrade(secio_upgrade);
// let _ = tcp_secio.dial(...);

In this example, tcp_secio is a new Transport that negotiates the secio protocol 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.


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 susyp2p

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

  1. Creating an identity Keypair for the local node, obtaining the local PeerId from the PublicKey.
  2. 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 secio that authenticates the peer. See the implementation of build_development_transport for an example.
  3. 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.
  4. 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 with the tokio library, in order to continuously drive the network activity of the program.


pub use bytes;
pub use futures;
pub use tokio_io;
pub use tokio_codec;
pub use susyp2p_core_derive::NetworkBehaviour;
pub use self::simple::SimpleProtocol;



Transport, protocol upgrade and swarm systems of susyp2p.




Implements the floodsub protocol, see also the: spec.


Implementation of the /ipfs/id/1.0.0 protocol. Allows a node A to query another node B which information B knows about A. Also includes the addresses B is listening on.


A node's network identity keys.


Kademlia protocol. Allows peer discovery, records store and records fetch.


mDNS is a protocol defined by RFC 6762 that allows querying nodes that correspond to a certain domain name.




Noise protocol framework support for susyp2p.


This module implements the /ipfs/ping/1.0.0 protocol.


The secio protocol is a middleware that will encrypt and decrypt communications going through a socket (or anything that implements AsyncRead + AsyncWrite).


Implementation of the susyp2p Transport trait for TCP/IP.


Implementation of the susyp2p Transport trait for Unix domain sockets.


Implementation of the susyp2p Transport trait for Websockets.


Implements the Yamux multiplexing protocol for susyp2p, see also the specification.



Easy way for a user to create a Multiaddr.



Representation of a Multiaddr.


Identifier of a peer of the network.



An error during dialing or listening on a Transport.



Possible upgrade on an inbound connection or substream.


Extension trait for InboundUpgrade. Automatically implemented on all types that implement InboundUpgrade.


Possible upgrade on an outbound connection or substream.


Extention trait for OutboundUpgrade. Automatically implemented on all types that implement OutboundUpgrade.


A transport provides connection-oriented communication between two peers through ordered streams of data (i.e. connections).


Trait automatically implemented on all objects that implement Transport. Provides some additional utilities.



Builds a Transport that supports the most commonly-used protocols that susyp2p supports.


Builds an implementation of Transport that is suitable for usage with the Swarm.

Type Definitions


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