By vasa in Libp2p — Dec 2, 2019

Glossary

Here you can find the meanings of frequently used terms in p2p space.

Circuit Relay

A means of establishing communication between peers who are unable to communicate directly, with the assistance of a third peer willing and able to act as an intermediary.

In many real-world peer-to-peer networks, direct communication between all peers may be impossible for a variety of reasons. For example, one or more peers may be behind a firewall or have NAT traversal issues. Or maybe the peers don’t share any common transports.

In such cases, it’s possible to “bridge the gap” between peers, so long as each of them are capable of establishing a connection to a willing relay peer. If I only speak TCP and you only speak websockets, we can still hang out with the help of a bilingual pal.

Circuit relay is implemented in libp2p according to the relay spec, which defines a wire protocol and addressing scheme for relayed connections.

Client/Server

A network architecture defined by the presence of central “server” programs which provide services and resources to a (usually much larger) set of “client” programs. Typically clients do not communicate directly with one another, instead routing all communications through the server, which is inherently the most privileged member of the network.

DHT

A distributed hash table whose contents are spread throughout a network of participating peers. Much like an in-process hash table, values are associated with a key and can be retrieved by key. Most DHTs assign a portion of the addressable key space to nodes in a deterministic manner, which allows for efficient routing to the node responsible for a given key.

Since DHTs are a foundational primitive of many peer-to-peer systems, libp2p provides a Kademlia-based DHT implementation in Go and javascript.

libp2p uses the DHT as the foundation for one of its peer routing implementations, and systems built with libp2p often use the DHT to provide metadata about content, advertise service availability, and more.

Connection

A libp2p connection is a communication channel that allows peers to read and write data.

Connections between peers are established via transports, which can be thought of as “connection factories”. For example, the TCP transport allows you to create connections that use TCP/IP as their underlying substrate.

Dial

The process of opening a libp2p connection to another peer is known as “dialing”, and accepting connections is known as “listening”. Together, an implementation of dialing and listening forms a transport.

Listen

The process of accepting incoming libp2p connections is known as “listening”, and it allows other peers to “dial” up and open network connections to your peer.

mDNS

Multicast DNS is a protocol for service discovery on a local network. One of libp2p’s peer routing implementations leverages mDNS to discover local peers quickly and efficiently.

multiaddr

A multiaddress (often abbreviated multiaddr), is a convention for encoding multiple layers of addressing information into a single “future-proof” path structure.

For example: /ip4/127.0.0.1/udp/1234 encodes two protocols along with their essential addressing information. The /ip4/127.0.0.1 informs us that we want the 127.0.0.1 loopback address of the IPv4 protocol, and /udp/1234 tells us we want to send UDP packets to port 1234.

Multiaddresses can be composed to describe multiple “layers” of addresses.

For more detail, see Addressing, or the multiaddr spec, which has links to many implementations.

Multiaddress

See multiaddr

Multihash

Multihash is a convention for representing the output of many different cryptographic hash functions in a compact, deterministic encoding that is accommodating of future changes.

Hashes are central to many systems (git, for example), yet many systems store only the hash output itself, since the choice of hash function is an implicit design parameter of the system. This has the unfortunate effect of making it quite difficult to ever change your mind about what kind of hash function your system uses!

A multihash encodes the type of hash function used to produce the output, as well as the length of the output in bytes. This is added as a two-byte header to the original hash output, and in return for those two bytes, the header allows current and future systems to easily identify and validate many hash functions by leveraging common libraries. As new functions are added, you can much more easily extend your application or protocol to support them, since the old and new hash outputs will be easily distinguishable from one another.

The most prominent use of multihashes in libp2p is in the PeerId, which contains a hash of a peer’s public key. However, systems built with libp2p, most notably IPFS, use multihashes for other purposes. In the IPFS case, multihashes are used both to identify content and other peers, since IPFS uses libp2p and shares the same PeerId conventions.

In IPFS, multihashes are a key component of the CID, or content identifier, and the “v0” version of CID is a “raw” multihash of a piece of content. A “modern” CID combines a multihash of some content with some compact contextualizing metadata, allowing content-addressed systems like IPFS to create more meaningful links between hash-addressed data. For more on the subject of hash-linked data structures in p2p systems, see IPLD.

Multihashes are often represented as base58-encoded strings, for example, QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N. The first two characters Qm are the multihash header for the SHA-256 hash algorithm with a length of 256 bits, and are common to all base58-encoded multihashes using SHA-256.

Multiplexing

Multiplexing (or “muxing”), refers to the process of combining multiple streams of communication over a single logical “medium”. For example, we can maintain multiple independent data streams over a single TCP network connection, which is itself of course being multiplexed over a single physical connection (ethernet, wifi, etc).

Multiplexing allows peers to offer many protocols over a single connection, which reduces network overhead and makes NAT traversal more efficient and effective.

Libp2p supports several implementations of stream multiplexing. The mplex specification defines a simple protocol with implementations in several languages. Other supported multiplexing protocols include yamux and spdy.

See Stream Muxer Implementations for status of multiplexing across libp2p language implementations.

multistream

Multistream is a lightweight convention for “tagging” streams of binary data with a short header that identifies the content of the stream.

Libp2p uses multistream to identify the protocols used for communication between peers, and a related project multistream-select is used for protocol negotiation.

NAT

Network address translation in general is the mapping of addresses from one address space to another, as often happens at the boundary of private networks with the global internet. It is especially essential in IPv4 networks (which are still the vast majority), as the address space of IPv4 is quite limited. Using NAT, a local, private network can have a vast range of addresses within the internal network, while only consuming one public IP address from the global pool.

An unfortunate effect of NAT in practice is that it’s much easier to make outgoing connections from the private network to the public one than it is to call from outside in. This is because machines listening for connections on the internal network need to explicitly tell the router in charge of NAT that it should forward traffic for a given port (the multiplexing abstraction for the OS networking layer) to the listening machine.

This is less of an issue in a client / server model, because outgoing connections to the server give the router enough information to route the response back to the client where it needs to go.

In the peer-to-peer model, accepting connections from other peers is often just as important as initiating them, which means that we often need our peers to be publicly reachable from the global internet. There are many viable approaches to NAT Traversal, several of which are implemented in libp2p.

NAT Traversal

NAT traversal refers to the process of establishing connections with other machines across a NAT boundary. When crossing the boundary between IP networks (e.g. from a local network to the global internet), a Network Address Translation process occurs which maps addresses from one space to another.

For example, my home network has an internal range of IP addresses (10.0.1.x), which is part of a range of addresses that are reserved for private networks. If I start a program on my computer that listens for connections on its internal address, a user from the public internet has no way of reaching me, even if they know my public IP address. This is because I haven’t made my router aware of my program yet. When a connection comes in from the internet to my public IP address, the router needs to figure out which internal IP to route the request to, and to which port.

There are many ways to inform one’s router about services you want to expose. For consumer routers, there’s likely an admin interface that can setup mappings for any range of TCP or UDP ports. In many cases, routers will allow automatic registration of ports using a protocol called upnp, which libp2p supports. If enabled, libp2p will try to register your service with the router for automatic NAT traversal.

In some cases, automatic NAT traversal is impossible, often because multiple layers of NAT are involved. In such cases, we still want to be able to communicate, and we especially want to be reachable and allow other peers to dial in and use our services. This is the one of the motivations for Circuit Relay, which is a protocol involving a “relay” peer that is publicly reachable and can route traffic on behalf of others. Once a relay circuit is established, a peer behind an especially intractable NAT can advertise the relay circuit’s multiaddr, and the relay will accept incoming connections on our behalf and send us traffic via the relay.

Node

The word “node” is quite overloaded in general programming contexts, and this is especially the case in peer-to-peer networking circles.

One common usage is when “node” refers to a single instance of a peer-to-peer software system, running at some time and place in the universe. For example, I'm running an orbit-db node in AWS. I think it's on version 3.2.0. In this usage, “node” refers to the whole software program (the daemon in unix-speak) which participates in the network. In this documentation, we’ll often use “peer” for this purpose instead, and the two terms are often used interchangeably in various p2p software discussions.

Another quite different meaning is the node.js javascript runtime environment, which is one of the supported runtimes for the javscript libp2p implementation. In general it should be pretty clear from context when “node” is referring to node.js.

Many members of our community are excited about graphs in many contexts, so the graph terminology of “nodes and edges” is often used when discussing various subjects. Some common contexts for graph-related discussions:

When discussing the topology or structure of a peer-to-peer network, “node” is often used in the context of a graph of connected peers. Efficient construction and traversal of this graph is key to effective peer routing.
When discussing data structures, “node” is often useful for referring to key elements of the structure. For example, a linked list consists of many “nodes” containing both a value and a link (or, in graph terms, an “edge”) connecting it to the next node. Since many useful and interesting data structures can be described as graphs, much of the terminology of graph theory applies when discussing their properties. In particular, IPFS is naturally well-suited to storing and manipulating data structures which form a Directed Acyclic Graph, or DAG.
An especially interesting data structure for many in our community is IPLD, or Interplanetary Linked Data. Similar to libp2p, IPLD grew out of the real-world needs of IPFS, but is broadly useful and interesting in many contexts outside of IPFS. IPLD discussions often involve “nodes” of all the types discussed here.

Overlay

An “overlay network” or just “overlay” refers to the logical structure of a peer-to-peer network, which is “overlaid” on top of the underlying transport mechanisms used for lower-level network communication.

Peer-to-peer systems are generally composed of one or more overlay networks, which determine how peers are identified and located, how messages are propagated throughout the system, and other key properties.

Examples of overlay networks used in libp2p are the DHT implementation, which is based on Kademlia, and the networks formed by participants in the various pubsub implementations.

Peer

A single participant in a peer-to-peer network. While a given peer may support many protocols, it has a single PeerId which it uses to identify itself to other peers. Often used synonymously with node.

PeerId

A unique, verifiable identifier for a peer that is impossible for another peer to forge or impersonate without trivial detection. In libp2p, peers are identified by their PeerId, which is both globally unique and allows other peers to obtain the peer’s cryptographic public key.

The most common form of PeerId is a multihash of a peer’s public key, which can be used to fetch the entire public key from the DHT for encryption or signature verification. There is also experimental support for embedding or “inlining” small public keys directly into the PeerId, however, this is an area of ongoing discussion and should be treated with caution in production systems until finalized.

An important property of cryptographic peer identities is that they are decoupled from transport, allowing peers to verify the identity of other peers regardless of what underlying network they might use to communicate. This also gives them a much longer “shelf life” than location-based identifiers (for example, IP addresses), since identities remain stable across address changes.

Peer store

A data structure that stores PeerIds for known peers, along with known multiaddresses that can be used to communicate with them.

Peer routing

Peer routing is the process of discovering the network “route” or address for a peer in the network, given the peer’s id.

It may also include “ambient” discovery of local peers, for example via multicast DNS.

The primary peer routing mechanism in libp2p uses a distributed hash table to locate peers, taking advantage of the Kademlia routing algorithm to efficiently locate peers.

Peer-to-peer (p2p)

A peer-to-peer (p2p) network is one in which the participants (referred to as peers or nodes) communicate with one another directly, on more or less “equal footing”. This does not necessarily mean that all peers are identical; some may have different roles in the overall network. However, one of the defining characteristics of a peer-to-peer network is that they do not require a privileged set of “servers” which behave completely differently from their “clients”, as is the case in the the predominant client / server model.

Pubsub

In general, refers to “publish / subscribe”, a communication pattern in which participants “subscribe” for updates “published” by other participants, often on a named “topic”.

Libp2p defines a pubsub spec, with links to several implementations in supported languages. Pubsub is an area of ongoing research and development, with multiple implementations optimized for different use cases and environments.

Protocol

In general, a set of rules and data structures used for network communication.

Libp2p is comprised of many protocols and makes use of many others provided by the operating system or runtime environment.

Most core libp2p functionality is defined in terms of protocols, and libp2p protocols are identified using multistream headers.

Protocol Negotiation

The process of reaching agreement on what protocol to use for a given stream of communication.

In libp2p, protocols are identified using a convention called multistream, which adds a small header to the beginning of a stream containing a unique name, including a version identifier.

When two peers first connect, they exchange a handshake to agree upon what protocols to use.

The implementation of the libp2p handshake is called multistream-select.

For details, see the protocol negotiation article.

Stream

TODO: Distinguish between the various types of “stream”. Could refer to

raw tcp connection
one component of a multistream connection
node.js streams / pull-streams

Swarm

Can refer to a collection of interconnected peers.

In the libp2p codebase, “swarm” may refer to a module that allows a peer to interact with its peers, although this component was later renamed “switch”.

See the discussion about the name change for context.

Switch

A libp2p component responsible for composing multiple transports into a single interface, allowing application code to dial peers without having to specify what transport to use.

In addition to managing transports, the switch also coordinates the “connection upgrade” process, which promotes a “raw” connection from the transport layer into one that supports protocol negotiation, stream multiplexing, and secure communications.

Sometimes called “swarm” for historical reasons.

Topology

In a peer-to-peer context, usually refers to the shape or structure of the overlay network formed by peers as they communicate with each other.

Transport

In libp2p, transport refers to the technology that lets us move bits from one machine to another. This may be a TCP network provided by the operating system, a websocket connection in a browser, or anything else capable of implementing the transport interface.

Note that in some environments such as javascript running in the browser, not all transports will be available. In such cases, it may be possible to establish a Circuit Relay with the help of a peer that can support many common transports. Such a relay can act as a “transport adapter” of sorts, allowing peers that can’t communicate with each other directly to interact. For example, a peer in the browser that can only make websocket connections could relay through a peer able to make TCP connections, which would enable communication with a wider variety of peers.