1 of 45

CORE COURSE B

SOLVING DISTRIBUTED NETWORKING PROBLEMS WITH LIBP2P

Jacob Heun

@jacobheun

Cole Brown

@bigs

Alex Potsides

@achingbrain

2 of 45

JS: libp2p/js-libp2p-examples

./chat/browser
./chat/nodejs

GO: libp2p/go-libp2p-examples

./ipfs-camp-2019

GETTING THE STARTER CODE

Setup

Duration: 1 minute. Endtime: 01:30

In this Workshop we’re going to be covering 3 different setups for libp2p. Node.js, the Browser, and Go. Unless you are very familiar with libp2p and these languages, you should select the platform you’re most comfortable with, as this will benefit you the most here.

Everything is going to be posted publicly, including these slides and the general dialogue that goes along with them, so if you want to check out another platform later, you’ll have everything you need.

If you haven’t already done so, we’ve got some base code you can clone or download from these github repos, depending on your language of choice.

The code consists of multiple chapters. Since we’ll be covering a lot of content today, if you’re having trouble with a certain chapter when we need to move on, the code for the next chapter will have what you need to continue.
Once you’ve pulled the code down, go ahead and run the install instructions in the readme for your platform.
While you’re doing that, we’ll do a quick overview of what libp2p is and what we’re building today

3 of 45

The networking stack IPFS uses to communicate
A modular system of protocols that can be used to solve specific, distributed networking problems.

WHAT IS LIBP2P?

Duration: 1min. Endtime: 02:30

The World Wide Web became publicly available in August 1991. That’s 28 years ago. That’s a long time for tech. 28 years after the internet, adding a networking layer to your project still kind of sucks... If you want to network peer 2 peer, it really sucks.

Why can’t we have a nice set of tools that we can just grab what we need and add it to our project? Just configure networking and focus on building cool stuff. This is what Libp2p is built to do.

Libp2p is the networking layer IPFS uses.
Libp2p is a composable, modular networking library that can be used to solve specific peer to peer networking problems. We’re going to walk through some of those problems today, and demonstrate some of the ways libp2p can solve them, so developers can go back to focusing on the applications themselves.

4 of 45

WHAT ARE WE BUILDING?

5 of 45

Chat App

Connecting to the network
Encrypting connections
Creating our own protocol
Reusing connections
Discovering Peers

Connecting to NAT’d nodes
Handling more complex data on our protocol
Broadcasting data with Pubsub
Finding peers with the DHT

WHY A CHAT APP?

Duration: 60s. Endtime: 04:00

Why are we building a chat app?

Even a basic chat application is going to let us explore a lot of the problem space of peer 2 peer applications.

How do we create a node and connect it to the network?
How do we encrypt our connections to keep our messages and data private?
How do we create our own chat protocol to run on top of libp2p?
How do we maximize any single connection and transmit any number of different protocols, including our custom chat protocol, so we avoid multiple connections to peers?
How do we discover peers across the network?
How do we connect to peers that are behind NATs, such as browser or home network peers?
How do we configure our protocol to handle complex data, such as chat / (slash) commands?
How can we use Pubsub to more effectively transmit data across the network?
How can we use the DHT to find peers that have the content/protocols we need?

6 of 45

Connecting to Peers:

Libp2p uses Transports to connect to peers
Transports include dialing and listening components
Not all Transports will be able to listen (browsers)

TRANSPORTS

19

PEERS

90

PEERS

93

PEERS

77

PEERS

33

PEERS

87

PEERS

17

PEERS

Duration: 90s. Endtime: 05:30

We’ve got the skeleton of our libp2p code, now let’s talk about our first problem, how do we connect to other peers. We’re building a distributed app, it doesn’t do us much good if we can’t connect to other nodes.
The first thing we’re going to need are Transports.

Transports are the interfaces libp2p uses to do the actual transmission of data
Libp2p allows you to use the Transports you need for your specific use cases. As technology changes over time, new Transports will be needed, but since libp2p is modular, we will be able to easily plug them in.

Transports consist of a dialing and listening components. Dialing for establishing outbound connections, and listening for handling inbound connections.

Not all Transports will be able to listen, such as certain browser transports. However, there are some transports that are designed to be able to listen via other nodes, which we’ll talk about shortly.

7 of 45

Transport	Browser	Node	Go	Rust
TCP
Websockets
WebRTC
QUIC

SELECTING TRANSPORTS

8 of 45

Connecting to Peers:

Let’s add

TCP
Websockets
WebRTC ( JS only )

Direct browser to browser dialing and discovery
Ability to listen via an intermediary node

CONFIGURING TRANSPORTS

9 of 45

< Configure the Transports >

01 Transports

02 Multiaddrs

03 Muxing & Encryption

04 Protocol

01

10 of 45

Connecting to Peers:

Most commonly the first peer will be a Bootstrap peer

A well known peer used to join the network

We need an address for the peer!

THE FIRST CONNECTION

11 of 45

Connecting to Peers:

Allow us to compose flexible addresses in a path structure
Phone numbers, domains, postal addresses all have �different formats
multiaddrs can tell us a lot about the peer we want to contact

MULTIADDRESS

(MULTIADDRS)

12 of 45

Connecting to Peers:

/ip4/127.0.0.1/tcp/4001

IP(v4): 127.0.0.1, Port: 4001, Transport: TCP

/ip4/127.0.0.1/tcp/4002/ws

IP(v4): 127.0.0.1, Port: 4002, Transport: Websocket over a TCP connection

MULTIADDRS

13 of 45

Connecting to Peers:

/ip4/0.0.0.0/tcp/15555/ws/p2p-webrtc-star

A websocket address at 0.0.0.0, port 15555
/p2p-webrtc-star indicates a webRTC rendezvous/signaling server
Our target peer is available at that signaling server

/ip4/127.0.0.1/udp/4001/quic/p2p/QmRelay/p2p-circuit

A Quic address running over UDP at 127.0.0.1, port 4001
/p2p-circuit indicates our target peer is available over a relay
Our target peer is available over the relay QmRelay at that Quic address

MULTIADDRS

Duration: 90s Endtime: 15:00

Now the addresses get a bit more complex:
The third is a WebRTCStar address. Let’s break this down by starting at the right hand side and working our way left.

We first have /p2p-webrtc-star. This is the webrtc signaling server codec. This indicates the target peer is dialable at the preceding peer with a transport that supports the /p2p-webrtc-star address type.
The preceding peer

And the fourth. Again, we need to start at the right hand side to better digest what’s going on.

The first thing we see is /p2p-circuit. This indicates that we need to contact the node over a Circuit Relay peer. We’ll get more into Circuit Relays later. It signifies that in order to dial our target peer, we need to first connect to this relay, and it will relay our connection to the target peer.
Immediately before that, we see /p2p/Qm…. This is the Relay peers’ id.
The rest of the address, /ip4/.../quic, indicates we need to use the Quic Transport to dial the relay, and that is over a udp connection on port 4001.

14 of 45

Connecting to Peers:

Setup multiaddrs for us to listen on (if possible)
Connect to our destination peer via its multiaddr

ADDING THE MULTIADDR

15 of 45

< Add the multiaddrs >

01 Transports

02 Multiaddrs

03 Muxing & Encryption

04 Protocol

02

Duration: 5min Endtime: 21:00

We’re going to keep things simple right now and all dial to a single peer, our local Bootstrap node.
First, let’s give the Bootstrap node multiaddrs to listen on

If you are running go, or nodejs, you should do this as well. Browser folks, we can’t listen yet, but maybe someday soon.
We’ll add 3 addresses, 1 for our TCP, Wbsocket and WebRTC
We can specify wildcard IPs on TCP and Websocket to keep things simple. WebRTC will require the specific address of the signaling server
Our TCP address will be, /ip4/0.0.0.0/tcp/4001. Now, if you are running something else on port 4001, like IPFS, and you don’t want to kill it, just change the port to something else, or to 0 to automatically select an open port.
For our Websocket address we will use /ip4/0.0.0.0/tcp/4002/ws. Again, if that’s a conflict, go ahead and select another port, or simply port 0.
For WebRTC, we need the specific address of the signaling server. Aside from the IP, the address should be /ip4/127.0.0.1/tcp/15555/ws/p2p-webrtc-star.

Okay, now that we have our listening addresses set, let’s get a connection going.
Once our node has started, we can have immediately try and connect to our target peer. We’ll use our Bootstrap multiaddr to connect, < INSERT Bootstrap multiaddr >
Now if we start our nodes, we should see a connection start but error. This error is due to the fact that the Bootstrap node requires us to have an encrypted connection.

16 of 45

17 of 45

We’re connected to a node and we can send it data
How do we reuse a connection to handle more complex communication?

Pubsub messages
DHT queries
Circuit relaying
Direct communication
Our Chat protocol
All future protocols

REUSING CONNECTIONS

18 of 45

REUSING CONNECTIONS

19 of 45

REUSING CONNECTIONS

20 of 45

Reusing Connections

Isolate communication to individual streams

A TCP connection multiplexes over many ports
Telephone line connections multiplex via different frequencies
Mplex multiplexes by prepending data with stream identified headers

Muxers

Mplex, Yamux, Spdy, QUIC (built in), muxado

STREAM MULTIPLEXING (MUXING)

Duration: 90s Endtime: 24:00

This is where Stream Multiplexing comes in, often referred to simply as muxing.
Stream multiplexers allow us to leverage a single connection to have multiplex conversations.

Multiplexing isn’t new. It was used in Telegraphy in the 1870s.

TCP connections multiplex by using ports.
Telephone lines historically multiplexed by using different frequencies.

In libp2p, multiplexers achieve the same goal by different means. This will depend somewhat on the multiplexer being used

For example, Mplex, our most widely supported multiplexer across language implementations, prepends data with stream identifying headers.

As data comes in, we determine what stream it belongs to and send the message along to that stream to be consumed.

Libp2p currently has several muxers you can use.

Mplex, currently the most adopted (go, js, rust)
Yamux, supported in go and rust
Spdy, supported in go and js
The Quic Transport has a build in stream multiplexer, so it is automatically used with the Quic Transport. Supported in go
And muxado, supported in go.

21 of 45

< Configure the Muxers >

04 Protocol

03 Muxing & Encryption

02 Multiaddrs

01 Transports

03

Duration: 5min Endtime: 28:30

Let’s add the some multiplexers to our code base. We have the ability to add any number of multiplexers, as libp2p will negotiate the “best” common multiplexer for us. For today, we’ll just add a single multiplexer, Mplex.
Now that we’ve added the multiplexer, once we restart our node, or refresh our browser we’ll connect and mux the connection.
Let’s look at the network traffic for this. There’s a lot more going on than when we didn’t have a multiplexer.

This is because there are other protocols libp2p ideally wants to run on a connection. Without a multiplexer we can’t reasonably do this.
But since we have one, you can see traffic for thinks like determining relay status, and the Identify protocol being run to find our more information about our peer.

22 of 45

23 of 45

Encrypt all data aside from the initial encryption protocol selection
Supported protocols
Secio, TLS1.3, Noise, Quic Transport

ENCRYPTING DATA

24 of 45

< Configure encryption >

01 Transports

02 Multiaddrs

03 Muxing & Encryption

04 Protocol

03

25 of 45

26 of 45

What are they?

/multistream/1.0.0
/ipfs/ping/1.0.0
/libp2p/circuit/relay/0.1.0
...

PROTOCOLS IN LIBP2P

Duration: 1min Endtime: 35:30

Alright, so we’ve got a connection to another peer, it’s muxed and encrypted. We’ve got the basics we need to start building our app.
So… how do we do that?
We’ve brought up the term protocol several times already. Remember, libp2p is a “A modular system of protocols”, but what does that mean?

If you think about a RESTful api, you typically have paths or endpoints. Each of those endpoints has a particular handler that is built to understand the data that goes into and out of that endpoint. If you try to send data designed for 1 endpoint to another, it’s most likely going to fail. And vice versa, if the endpoint returns the wrong type of data to you, your application is likely not going to handle that well
Libp2p protocols operate under the same concept.
Remember the protocol we kept seeing in the network traffic, /multistream/1.0.0? That’s multistream-select and it behaves like a router for our protocols (endpoints). And yes, multistream-select is a protocol itself. Eventually multistream 2 or some other variant is going to come out to handle the routing of protocols, and we’ll need to be able to gracefully upgrade the network.

27 of 45

Protocols

We’re building a chat app
Let’s create a chat protocol
/libp2p/chat/1.0.0

CREATING A PROTOCOL

28 of 45

< Create the Protocol >

04

05 Discovery

04 Protocol

03 Muxing & Encryption

02 Multiaddrs

Duration: 5min Endtime: 41:30

Walk through the handler code.

So, we’re on Chapter 04 Protocol in the example code base. If you open those directories you will be able to look over the Protocol files.

For Go, you’ll see a protocol.go file.
For JS, there will be a chat-protocol.js file.

The handlers are pretty simple. Whenever we get some data over the chat protocol, we’ll just print it to console so we have a basic display of our incoming chats. The Browser nodes are the exception, they will update messages on the React component to be displayed.

Our bootstrap node is going to auto reply when we chat with it so we can get some responses back

Let’s take a few minutes to configure this. If you get stuck, we’ll be walking around the room to help, and remember, the next Chapter will have a completed version of the code for you to reference.

29 of 45

5 minutes

TIME FOR BREAK!

30 of 45

Chatting with a Robot, how fun!

31 of 45

Bootstrap
MDNS
DHT
Rendezvous Servers
Bluetooth?
NFC?
...

PEER DISCOVERY

Duration: 90s Endtime: 43:30

Libp2p has support and the potential to support an ever growing list of peer discovery modules. Just like Transports, we need to be able to use new technologies as they develop.

So, let’s look at the first few of these.
Bootstrap

Bootstrap is a simple “discovery” mechanism. We take a list of known addresses, such as the node we’ve been dialing so far, and it is immediately “discovered” in our network. While this is a somewhat centralized approach, it helps us bridge the gap until p2p network discoverability technologies improve.

MDNS

MulticastDNS or MDNS, is a local network discovery protocol. This is how you find services on your network, such as printers. Nodes can query the local network on the libp2p namespace, and any other libp2p node that supports MDNS will respond back. The node making the query will also respond to the query. This allows every node on the network to immediately know about every other node when 1 joins. Us all being on the same wifi makes this a great discovery option. However, it’s TCP only, sorry browsers.

Rendezvous Servers

These are servers like the WebRTC signaling server and the Websocket Star rendezvous servers.
They are another option for boosting peer discovery, especially for nodes that run in the Browser.

32 of 45

Peer Discovery

Find a Random ID

“Brandon"

Ask our “closest” known peers
Continue until we find no closer peers

DHT RANDOM WALK

Bob

Me

Alice

Brenda

Duration: 90s Endtime: 45:00

We’ll dive more into what a DHT is later, if you’re not familiar with them, but right now we’re going to focus on its discovery mechanism, the Random Walk.

Very simply, a DHT or Distributed Hash Table, is a key value lookup service. One of the things it does is keep a record of peers on the network, including their known multiaddrs.
The Random Walk is a query on this network, with the caveat that we’re querying to find a peer who’s ID we just made up. This query causes us to ask the peers we know if they know that peer. If they don’t they’ll suggest peers that might, based on how close their IDs are to the one we want. This closeness is the XOR distance of those IDs. Note: This query should fail to find that ID. The odds of us randomly generating an existing peerid are very low. The goal is not to find them though, the goal is to meet new peers.

For example, let’s say I randomly create a peer id, “Brandon”. I am going to look at my peer records for Brandon. Since we made him up, he won’t be there, so I am going to find the peers I know with the closest names (IDs). The DHT looks for data by closeness (XOR Distance) of the keys, as this provides us with a defined target of where to look. So, I check my records and see I know Alice and Bob. Since Bob has a closer ID to Brandon, I will ask Bob if they know Brandon. Bob checks their table and says “No, but I know Brenda, who might, because their ID is closer to Brandon”.
We just discovered Brenda. Random Walk will query significantly more peers, but this is how it works.
It does have the caveat of needing to be connected to other DHT enabled nodes for it to work. So we still need to leverage other discovery mechanisms to join the network.

33 of 45

Peer Discovery

Bootstrap
MDNS
DHT Random Walk
Rendezvous Server (WebRTC Signaling)

MULTIPLE DISCOVERY SERVICES

34 of 45

< Configure discovery >

03 Muxing & Encryption

04 Protocol

05 Discovery

06 Pubsub

05

35 of 45

Recap

We can connect to peers
We can discover peers
We can chat with connected peers
Chatting is done over a direct connection

So, how can we make this better?

WELCOME BACK!

36 of 45

Pubsub

Floodsub
Gossipsub

BROADCASTING MESSAGES

Duration: 90s Endtime: 63:00

Pubsub allows us to broadcast messages to all peers who are connected to us on the pubsub protocol. There are multiple Pubsub protocols we can use to accomplish this, with different algorithms for broadcasting messages.

Floodsub is the basic, least efficient method of doing this. We simply broadcast every message we create to every pubsub peer we’re connected to. We will also forward any messages we receive to the other peers we’re connected to. Messages we’ve already seen are cached for a short period to avoid rebroadcasting.
Gossipsub does 2 things to improve performance.

1, it creates a mesh overlay of its pubsub peers. So instead of broadcasting to all of our pubsub peers, we broadcast to a specific subset of peers. That subset is our mesh. When we join a topic, we randomly select peers to create our mesh. In turn, we also notify the peers we have done this, so that we are added to their mesh. These overlays work to create a more efficient pubsub network, by lowering the number of messages we send. The downside is we risk peers missing messages.
This is where part 2 comes in, the gossip. In addition to broadcasting messages to our mesh overlay, we also gossip to a random set of pubsub peers. This gossip will contain metadata about recent messages we’ve sent. This allows peers that may have missed messages, to explicitly request them from us, which will ultimately result in them broadcasting to their mesh overlay.

37 of 45

Pubsub

GOSSIPSUB OR FLOODSUB?

Transport	JS	Go	Rust
Gossipsub
Floodsub

38 of 45

< Code chat over Pubsub >

04 Protocol

05 Discovery

06 Pubsub

07 Messaging

06

Duration: 10min Endtime: 73:30

Let’s switch our terribly inefficient, direct message chat app to use Pubsub so we can actually all chat together.
The first thing we need to do is configure Pubsub, so let’s do that now.
Now that our node has pubsub support, we can integrate the Chat module we’ve prebuilt to save some time. We’ll get into the details of this in a second, but for now, let’s focus on the pubsub integration.

Here, we’ve created a handler for any messages we’re going to send. This takes our message, a timestamp of when it was created, encodes that as a protobuf (we’ll talk about this shortly) and publishes. The resulting publish will be broadcasted to our network, and as long as we’re connected to at least 1 other peer in the pubsub network, we should get the messages.
For the subscribe, we are decoding the incoming messages and logging/rendering them out, along with the id of the peer who sent it. This is our crude user “handle”. “Ah Qmxy5b28… long time no chat!”

A useful thing to know here is that in pubsub, we sign messages, and the network will soon be strict about verifying the signatures. What this means is that when we are about to publish a message, Pubsub will use our private key to sign the contents of the message. This signature gets passed along with the message on the broadcast. This allows any peer who receives the message to verify that we did indeed generate the message. Any message that fails this validation can be immediately dropped. No forwarding, just throw it away. By doing this signature verification, we can have confidence in our the integrity of our super cool user handles! “Right QmWjz6xb8…?!”

With that, let’s restart our nodes and refresh our browsers and see what happens.

39 of 45

Protobuf

We’re chatting over Pubsub, hooray!

Messages are being exchanged using Protobuf
The Protobuf declaration also has other request types, such as UpdatePeer

Complex Messaging

Duration: 30min Endtime: 74:00

We’re actually all chatting in a room… in a room, this is great!
Now, how can we leverage this same setup to send requests other than just a chat message.

For example, maybe we want to broadcast a name change, or some stats about peers we’

Already included in the code is a Protobuf declaration that includes additional request types.

If you’re not familiar with Protobuf, it’s just a way to serialize structured data. We can take a complex object, serialize it into a buffer to send over the wire, and deserialize it back into an object for any libp2p implementation to process, while maintaining types.
Today, this is how we typically transmit complex data structures over libp2p. If you look at the more complex protocols libp2p supports, Protobuf is backing the serialization of those communications.
What this does is gives us the ability to send different types of messages over the network for a single protocol.
Let’s take a look at this

40 of 45

message Request {

enum Type {

SEND_MESSAGE = 0;

UPDATE_PEER = 1;

}

required Type type = 1;

optional SendMessage sendMessage = 2;

optional UpdatePeer updatePeer = 3;

}

message SendMessage {

required bytes data = 1;

required int64 created = 2;

required bytes id = 3;

}

message UpdatePeer {

optional bytes userHandle = 1;

}

41 of 45

< Complex Messaging >

07

07 Messaging

06 Pubsub

05 Discovery

04 Protocol

42 of 45

Subnets

How do we broadcast to a small set of peers in a network of millions?

ONE OF MANY

43 of 45

Subnets

Provider Records
Query similar to Random Walk

BACK TO THE DHT

QmBob

QmMe

QmAlice

QmBrenda

Duration: 90s Endtime: 86:00

We talked about the DHT earlier. It’s our key value record sharing mechanism.
Maybe it can help.

From earlier we know that the DHT keeps a record of peers it encounters. This is not limitless, but with a good portion of DHT nodes in the network, we’ll have a pretty solid overlay of peers.
Another thing the DHT does, is it keeps Provider Records. When you want the network to know you have something, you make a query to the network to register as a Provider. If you are providing something long term, you should be performing this query on an interval, as these records will eventually expire (24h by default).
Let’s talk more about this query. Remember us asking Bob about Brandon and he pointed us to Brenda? It’s like that. Except, we’re not looking for Brandon, we’re looking for peers in the network who have id’s most similar to the key we want to provide.

This query will end up executing down multiple paths, called Disjoint Paths, to improve the integrity and resilience of our queries.
When these paths finish, we will have a number of peers, 20 by default, but this will vary based on the bucket size of the DHT.
We will tell those peers, that we are a provider of that key.

44 of 45

Subnets

/libp2p/chat/1.0.0
Register as a provider in the DHT on subscribe
Find providers on subscribe to connect to other topic peers

APPLYING THE DHT TO OUR CHAT

45 of 45

CLOSING THOUGHTS

The End!

https://github.com/js-libp2p-examples

JS EXAMPLE

discuss.libp2p.io

FORUM

https://github.com/go-libp2p-examples

GO EXAMPLE