## 1. Project Overview & Quickstart (libp2p/examples)

# examples

TensorFlow examples

### Repository Details
- **Repository:** [libp2p/examples](https://github.com/libp2p/examples)
- **GitHub Stars:** ⭐ 8,264
- **Primary Language:** Jupyter Notebook

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (libp2p/docs)

## File: README.md

- [Overview](#overview)
- [Contributing content](#contributing-content)
- [Running locally](#running-locally)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
- [Configuration guide](#configuration-guide)
  - [Static site generator](#static-site-generator)
  - [Automated deployments](#automated-deployments)
  - [Translation](#translation)
- [Primary maintainers](#primary-maintainers)
- [License](#license)


---

## Overview

libp2p is a modular framework that encapsulates an evolving set of specifications for peer-to-peer networking. What started as the networking component that enables IPFS turned into a general-purpose framework to deliver a modular, peer-to-peer networking stack of protocols that are transport agnostic, flexible, reusable, and easy to upgrade.

libp2p enables interoperability between applications, resilient applications, and advanced networking features like decentralized publish-subscribe or advanced data structures like distributed hash tables.

## Contributing content

The documentation site contains several different kinds of content. We’d love ❤️ your help with any of it:

1. **Introductory overviews**: If you spot a problem or have improvements, please post an issue or PR.

2. **Concept guides**: Concept guides are intended to present a brief overview of libp2p-related concepts.
   They strive to answer:

    - **What** is this?
    - How does it **relate** to the rest of libp2p?
    - How can (or should?) you **use** it? (This can often vary by implementation
    - **Where** do you go to learn more?
    - What is the **current state** of affairs?

    See a list of concepts we need help with by [checking the issues](https://github.com/libp2p/docs/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Acontent+concept).

3. **Guides**: Most examples currently live in other repositories, like [js-libp2p examples](https://github.com/libp2p/js-libp2p/tree/master/examples). If you have thoughts on integrating them better, please file an issue. If you have feedback on individual examples or want to add a new one, please file an issue or pull request on the relevant repository. If you have ideas for guides or tutorials, they belong here! Please propose them in an issue here before creating a pull request.

3. **Reference material**: The navbar includes all the reference material available for libp2p. Please see the issues in this repository for current activity around reference/API documentation.

4. **Community**: If there are missing community links, feel free to file an issue or pull request,

This repository is also a website; we could use your help with design and technical features (interactive examples, better syntax highlighting, scripts to pull in content from other repositories, etc.) in addition to writing. To get a sense of what we could use help on, check the [issues](https://github.com/libp2p/docs/issues). If you decide to work on one, please post to the issue to let us know!

Before posting a pull request with your changes, please check [our style guide](https://github.com/ipfs/community/blob/master/DOCS_STYLEGUIDE.md) and [contributing guide](https://github.com/libp2p/community/blob/master/CONTRIBUTE.md).

Finally, let’s work together to keep this a respectful and friendly space. Please make sure to follow our [official code of conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).

## Running locally

### Prerequisites

To run the libp2p documentation site locally, you must have
[NPM installed](https://www.npmjs.com/).
If you already have NPM installed, make sure you are running the latest version:

```shell
npm install npm@latest -g
```

### Installation

Follow these steps to run a copy of this site on your local machine.

1. Clone this repository:

    ```shell
    git clone https://github.com/libp2p/docs
    ```

1. Navigate into the new folder and download the dependencies by running:

    ```shell
    cd docs
    npm install
    ```

2. Build the project and serve the static files to Hugo with:

    ```shell
    npm run build
    ```

3. Start the local Hugo's development server with:

    ```shell
    npm start
    ```

4. Visit [localhost:1313](http://localhost:1313) to view the site.
5. Press `CTRL` + `c` in the terminal to stop the local server.

## Configuration guide

### Static site generator

The libp2p documentation site uses [Hugo](https://gohugo.io/) as a static site generator,
making it easy to serve and host the static files on IPFS. In particular, the site uses
the [Hugo Doks theme](https://github.com/h-enk/doks) to present the libp2p documentation.

### Automated deployments

When opening a pull request, CI scripts will run against your feature branch to test your changes.

The CI/CD production workflow builds on the `master` branch and deploys the documentation site on [fleek](https://fleek.co/). It reflects the latest commit on `master` and publishes at [https://docs.libp2p.io](https://docs.libp2p.io).

### Translation

Please stay tuned for the steps to translate the documentation.

## Primary maintainers

- [@DannyS03](https://github.com/DannyS03): primary contact, project organization & technical writing
- [@mxinden](https://github.com/mxinden): libp2p steward, primarily rust-libp2p
- [@marten-seemann](https://github.com/marten-seemann): libp2p steward, primarily go-libp2p
- [@MarcoPolo](https://github.com/MarcoPolo): libp2p steward, primarily go-libp2p
- [@jennijuju](https://github.com/jennijuju): documentation management
- [@p-shahi](https://github.com/p-shahi): libp2p project management
- [@BigLep](https://github.com/BigLep): interplanetary management and supervision

## License

All software code is copyright (c) Protocol Labs, Inc. under the **MIT/Apache-2 dual license**.
Other written documentation and content are copyright (c) Protocol Labs, Inc. under the
[**Creative Commons Attribution-Share-Alike License**](https://creativecommons.org/licenses/by/4.0/).

---

## File: content/guides/getting-started/_index.md

---
title: "Get Started"
weight: 1
---

---

## File: content/guides/getting-started/go.md

---
title: "Run a go-libp2p node"
weight: 2
aliases:
    - "/tutorials/go"
    - "/guides"
    - "/guides/go"
---

The getting started tutorial covers setting up a development environment, getting familiar
with libp2p basics, and implementing a simple node that can send and receive "ping" messages
in go-libp2p.

The [Protocol Labs Launchpad curriculum](https://curriculum.pl-launchpad.io/) also includes
a tutorial on spinning up a libp2p node using a go-libp2p boilerplate. Check it out
[here](https://pl-launchpad.io/tutorials/libp2p/creating-simple-node/).

This is the first in a series of tutorials on working with libp2p’s Go implementation,
[go-libp2p](https://github.com/libp2p/go-libp2p). We’ll cover installing Go, setting up
a new Go module, starting libp2p nodes, and sending ping messages between them.

### Install Go

- Ensure your Go version is at least 1.20.
- You can install a recent version of Go by following the [official installation instructions](https://golang.org/doc/install).
- Once installed, you should be able to run `go version` and see a version >= 1.20, for example:

```bash
$ go version
go version go1.20 darwin/arm64
```

### Create a Go module

We're going to create a Go module that can be run from the command line.

Let's create a new directory and use `go mod` to initialize it as a module. We'll create it in
`/tmp`, but you can equally create it anywhere on your filesystem. We'll also initialize it with the
module name `github.com/user/go-libp2p-tutorial`, but you may want to replace this with a name that
corresponds to a repository name you have the rights to push to if you want to publish your version
of the code.

```bash
mkdir -p /tmp/go-libp2p-tutorial
cd /tmp/go-libp2p-tutorial
go mod init github.com/user/go-libp2p-tutorial
```

You should now have a `go.mod` file in the current directory containing the name of the module you
initialized and the version of Go you're using, for example:

```bash
$ cat go.mod
module github.com/user/go-libp2p-tutorial

go 1.20
```

### Start a libp2p node

We'll now add some code to our module to start a libp2p node.
Let's start by creating a `main.go` file that simply starts a libp2p node with default settings,
prints the node's listening addresses, then shuts the node down:

```go
package main

import (
    "fmt"
    "github.com/libp2p/go-libp2p"
)

func main() {
    // start a libp2p node with default settings
    node, err := libp2p.New()
    if err != nil {
        panic(err)
    }

    // print the node's listening addresses
    fmt.Println("Listen addresses:", node.Addrs())

    // shut the node down
    if err := node.Close(); err != nil {
        panic(err)
    }
}
```

Import the `libp2p/go-libp2p` module:

```bash
go get github.com/libp2p/go-libp2p
```

We can now compile this into an executable using `go build` and run it from the command line:

```bash
$ go build -o libp2p-node

$ ./libp2p-node
Listen addresses: [/ip6/::1/tcp/57666 /ip4/192.0.2.0/tcp/57665 /ip4/198.51.100.0/tcp/57665]
```

The listening addresses are formatted using the [multiaddr](https://github.com/multiformats/multiaddr)
format, and there is typically more than one printed because go-libp2p will listen on all available
IPv4 and IPv6 network interfaces by default.

#### Configure the node

A node's default settings can be overridden by passing extra arguments to `libp2p.New`. Let's use
`libp2p.ListenAddrStrings` to configure the node to listen on TCP port 2000 on the IPv4 loopback
interface:

```go
func main() {
        ...

        // start a libp2p node that listens on TCP port 2000 on the IPv4
        // loopback interface
        node, err := libp2p.New(
                libp2p.ListenAddrStrings("/ip4/192.0.2.0/tcp/2000"),
        )
    if err != nil {
        panic(err)
    }

        ...
}
```

Re-building and running the executable again now prints the explicit listen address we've configured:

```bash
$ go build -o libp2p-node

$ ./libp2p-node
Listening addresses: [/ip4/192.0.2.0/tcp/2000]
```

`libp2p.New` accepts a variety of arguments to configure most aspects of the node. See
[options.go](https://github.com/libp2p/go-libp2p/blob/master/options.go) for a full list of those
options.

#### Wait for a signal

A node that immediately exits is not all that useful. Let's add the following towards the end of the
`main` function that blocks waiting for an OS signal before shutting down the node:

```go
func main() {
        ...

        // wait for a SIGINT or SIGTERM signal
        ch := make(chan os.Signal, 1)
        signal.Notify(ch, syscall.SIGINT, syscall.SIGTERM)
        <-ch
        fmt.Println("Received signal, shutting down...")

        // shut the node down
        if err := node.Close(); err != nil {
                panic(err)
        }
}
```

We also need to update the list of imports at the top of the file to include the `os`, `os/signal`
and `syscall` packages we're now using:

```go
import (
    "fmt"
    "os"
    "os/signal"
    "syscall"

    "github.com/libp2p/go-libp2p"
)
```

Running the node now waits until it receives a SIGINT (i.e. a `ctrl-c` key press) or a SIGTERM signal
before shutting down:

```bash
$ ./libp2p-node
Listening addresses: [/ip4/192.0.2.0/tcp/2000]
^CReceived signal, shutting down...
```

### Run the ping protocol

Now that we have the ability to configure and start libp2p nodes, we can start communicating!

#### Set a stream handler

A node started with go-libp2p will run its own ping protocol by default, but let's disable it and
set it up manually to demonstrate the process of running protocols by registering stream handlers.

The object returned from `libp2p.New` implements the [Host interface](https://pkg.go.dev/github.com/libp2p/go-libp2p/core/host#Host),
and we'll use the `SetStreamHandler` method to set a handler for our ping protocol.

First, let's add the `github.com/libp2p/go-libp2p/p2p/protocol/ping` package to our list of
imported packages:

```go
import (
    ...

    "github.com/libp2p/go-libp2p"
    "github.com/libp2p/go-libp2p/p2p/protocol/ping"
)
```

Now we'll pass an argument to `libp2p.New` to disable the built-in ping protocol, and then use the
`PingService` type from the ping package to set a stream handler manually (note that we're also
configuring the node to listen on a random local TCP port rather than a hard coded one, which means
we'll be able to run multiple nodes on the same machine without them trying to listen on the same
port):

```go
func main() {
    ...

    // start a libp2p node that listens on a random local TCP port,
    // but without running the built-in ping protocol
    node, err := libp2p.New(
        libp2p.ListenAddrStrings("/ip4/192.0.2.0/tcp/0"),
        libp2p.Ping(false),
    )
    if err != nil {
        panic(err)
    }

    // configure our own ping protocol
    pingService := &ping.PingService{Host: node}
    node.SetStreamHandler(ping.ID, pingService.PingHandler)

    ...
}
```

#### Connect to a peer

With the ping protocol configured, we need a way to instruct the node to connect to another node and
send it ping messages.

We'll first expand the log message that we've been printing after starting the node to include
its `PeerId` value, as we'll need that to instruct other nodes to connect to it. Let's import the
`github.com/libp2p/go-libp2p/core/peer` package and use it to replace the "Listen addresses" log
message with something that prints both the listen address and the `PeerId` as a multiaddr string:

```go
import (
    ...

    "github.com/libp2p/go-libp2p"
    peerstore "github.com/libp2p/go-libp2p/core/peer"
    "github.com/libp2p/go-libp2p/p2p/protocol/ping"
)

func main() {
    ...

    // print the node's PeerInfo in multiaddr format
    peerInfo := peerstore.AddrInfo{
        ID:    node.ID(),
        Addrs: node.Addrs(),
    }
    addrs, err := peerstore.AddrInfoToP2pAddrs(&peerInfo)
    fmt.Println("libp2p node address:", addrs[0])

    ...
}
```

Running the node now prints the node's address that can be used to connect to it:

```bash
$ ./libp2p-node
libp2p node address: /ip4/192.0.2.0/tcp/62268/ipfs/QmfQzWnLu4UX1cW7upgyuFLyuBXqze7nrPB4qWYqQiTHwt
```

Let's also accept a command line argument that is the address of a peer to send ping messages to,
allowing us to either just run a listening node that waits for a signal, or run a node that connects
to another node and pings it a few times before shutting down (we'll use the `github.com/multiformats/go-multiaddr`
package to parse the peer's address from the command line argument):

```go
import (
    ...

    "github.com/libp2p/go-libp2p"
    peerstore "github.com/libp2p/go-libp2p/core/peer"
    "github.com/libp2p/go-libp2p/p2p/protocol/ping"
    multiaddr "github.com/multiformats/go-multiaddr"
)

func main() {
    ...
    fmt.Println("libp2p node address:", addrs[0])

    // if a remote peer has been passed on the command line, connect to it
    // and send it 5 ping messages, otherwise wait for a signal to stop
    if len(os.Args) > 1 {
        addr, err := multiaddr.NewMultiaddr(os.Args[1])
        if err != nil {
            panic(err)
        }
        peer, err := peerstore.AddrInfoFromP2pAddr(addr)
        if err != nil {
            panic(err)
        }
        if err := node.Connect(context.Background(), *peer); err != nil {
            panic(err)
        }
        fmt.Println("sending 5 ping messages to", addr)
        ch := pingService.Ping(context.Background(), peer.ID)
        for i := 0; i < 5; i++ {
            res := <-ch
            fmt.Println("got ping response!", "RTT:", res.RTT)
        }
    } else {
        // wait for a SIGINT or SIGTERM signal
        ch := make(chan os.Signal, 1)
        signal.Notify(ch, syscall.SIGINT, syscall.SIGTERM)
        <-ch
        fmt.Println("Received signal, shutting down...")
    }

    // shut the node down
    if err := node.Close(); err != nil {
        panic(err)
    }
}
```

### Let's play ping pong!

We are finally in a position to run two libp2p nodes, have one connect to the other and for
them to run a protocol!

To recap, here is the full program we have written:

```
/* Detailed source-code truncated for AI context efficiency. */
```

In one terminal window, let's start a listening node (i.e. don't pass any command line arguments):

```bash
$ ./libp2p-node
libp2p node address: /ip4/192.0.2.0/tcp/61790/ipfs/QmZKjsGJ6ukXVRXVEcExx9GhiyWoJC97onYpzBwCHPWqpL
```

In another terminal window, let's run a second node but pass the address of the first node, and we
should see some ping responses logged:

```bash
$ ./libp2p-node /ip4/192.0.2.0/tcp/61790/ipfs/QmZKjsGJ6ukXVRXVEcExx9GhiyWoJC97onYpzBwCHPWqpL
libp2p node address: /ip4/192.0.2.0/tcp/61846/ipfs/QmVyKLTLswap3VYbpBATsgNpi6JdwSwsZALPxEnEbEndup
sending 5 ping messages to /ip4/192.0.2.0/tcp/61790/ipfs/QmZKjsGJ6ukXVRXVEcExx9GhiyWoJC97onYpzBwCHPWqpL
pinged /ip4/192.0.2.0/tcp/61790/ipfs/QmZKjsGJ6ukXVRXVEcExx9GhiyWoJC97onYpzBwCHPWqpL in 431.231µs
pinged /ip4/192.0.2.0/tcp/61790/ipfs/QmZKjsGJ6ukXVRXVEcExx9GhiyWoJC97onYpzBwCHPWqpL in 164.94µs
pinged /ip4/192.0.2.0/tcp/61790/ipfs/QmZKjsGJ6ukXVRXVEcExx9GhiyWoJC97onYpzBwCHPWqpL in 220.544µs
pinged /ip4/192.0.2.0/tcp/61790/ipfs/QmZKjsGJ6ukXVRXVEcExx9GhiyWoJC97onYpzBwCHPWqpL in 208.761µs
pinged /ip4/192.0.2.0/tcp/61790/ipfs/QmZKjsGJ6ukXVRXVEcExx9GhiyWoJC97onYpzBwCHPWqpL in 201.37µs
```

Success! Our two peers are now communicating using go-libp2p! Sure, they can only say “ping”, but it’s a start!

---

## File: content/guides/getting-started/javascript.md

---
title: "Run a js-libp2p node"
weight: 3
aliases:
    - "/tutorials/javascript"
    - "/guides"
    - "/guides/javascript"
---

This is the first in a series of tutorials on working with libp2p's javascript implementation,
[js-libp2p](https://github.com/libp2p/js-libp2p).
We will walk you through setting up a fully functional libp2p node with some basic functionality,
and finally we'll send ping messages back and forth between two peers.

### Install node.js

Working with js-libp2p requires [node.js](https://nodejs.org) >= v16 for development. If you haven't already, install
node using whatever package manager you prefer or [using the official installer](https://nodejs.org/en/download/).
We recommend using the latest stable version of node, but anything fairly recent should work fine. If you want to see how low you can go, the current version requirements can always be found at the [js-libp2p project page](https://github.com/libp2p/js-libp2p).

### Create an empty project

We need a place to put our work, so open a terminal to make a new directory for your project somewhere and set it up as an npm project:

```shell
# create a directory for the project and `cd` into it
> mkdir hello-libp2p
> mkdir hello-libp2p/src
> cd hello-libp2p

# make it a git repository
> git init .

# make it an npm project. fill in the prompts with info for your project
# when asked for your project's entry point, enter "src/index.js"
> npm init es6
```

Side note: throughout this tutorial, we use the `>` character to indicate your terminal's shell prompt. When following along, don't type the `>` character, or you'll get some weird errors.

### Configure libp2p

libp2p is a very modular framework, which allows javascript devs to target different runtime environments and opt-in to various features by including a custom selection of modules.

Because every application is different, we recommend configuring your libp2p node with just the modules you need. You can even make more than one configuration, if you want to target multiple javascript runtimes with different features.

> In a production application, it may make sense to create a separate npm module for your libp2p node, which will give you one place to manage the libp2p dependencies for all your javascript projects. In that case, you should not depend on `libp2p` directly in your application. Instead you'd depend on your libp2p configuration module, which would in turn depend on `libp2p` and whatever modules (transports, etc) you might need.

If you're new to libp2p, we recommend configuring your node in stages, as this can make troubleshooting configuration issues much easier. In this tutorial, we'll do just that. If you're more experienced with libp2p, you may wish to jump to the [Configuration readme](https://github.com/libp2p/js-libp2p/blob/master/doc/CONFIGURATION.md).

As an initial step, you should install libp2p module.

```shell
npm install libp2p
```

#### Basic setup

Now that we have libp2p installed, let's configure the minimum needed to get your node running. The only modules libp2p requires are a **Transport** and **Crypto** module. However, we recommend that a basic setup should also have a **Stream Multiplexer** configured, which we will explain shortly. Let's start by setting up a Transport.

#### Transports

Libp2p uses Transports to establish connections between peers over the network. You can configure any number of Transports, but you only need 1 to start with.

You should select Transports according to the runtime of your application; Node.js or the browser. You can see a list of some of the available Transports in the [configuration readme](https://github.com/libp2p/js-libp2p/blob/master/doc/CONFIGURATION.md#transport). For this guide let's install `@libp2p/tcp`.

```sh
npm install @libp2p/tcp
```

Now that we have the module installed, let's configure libp2p to use the Transport. We'll use the `createLibp2p` method, which takes a single configuration object as its only parameter. We can add the Transport by passing it into the `transports` array. Create a `src/index.js` file and have the following code in it:

```js
import { createLibp2p } from 'libp2p'
import { tcp } from '@libp2p/tcp'

const node = await createLibp2p({
  transports: [tcp()]
})

```

You can add as many transports as you like to `transports` in order to establish connections with as many peers as possible.

#### Connection Encryption

Every connection must be encrypted to help ensure security for everyone. As such, Connection Encryption (Crypto) is a required component of libp2p.

There are a growing number of Crypto modules being developed for libp2p. As those are released they will be tracked in the [Connection Encryption section of the configuration readme](https://github.com/libp2p/js-libp2p/blob/master/doc/CONFIGURATION.md#connection-encryption). For now, we are going to configure our node to use the `@chainsafe/libp2p-noise` module.

```sh
npm install @chainsafe/libp2p-noise
```

```js
import { createLibp2p } from 'libp2p'
import { tcp } from '@libp2p/tcp'
import { noise } from '@chainsafe/libp2p-noise'

const node = await createLibp2p({
  transports: [tcp()],
  connectionEncrypters: [noise()]
})

```

#### Multiplexing

While multiplexers are not strictly required, they are highly recommended as they improve the effectiveness and efficiency of connections for the various protocols libp2p runs.

Looking at the [available stream multiplexing](https://github.com/libp2p/js-libp2p/blob/master/doc/CONFIGURATION.md#stream-multiplexing) modules, js-libp2p supports `@chainsafe/libp2p-yamux` and `@libp2p/mplex`, but [mplex](https://docs.libp2p.io/concepts/multiplex/mplex/) is [deprecated](https://github.com/libp2p/specs/issues/553) so we will use [Yamux]([https://github.com/hashicorp/yamux/blob/master/spec.md](https://docs.libp2p.io/concepts/multiplex/yamux/)) here. You can install `@chainsafe/libp2p-yamux` and add it to your libp2p node as follows in the next example.

```sh
npm install @chainsafe/libp2p-yamux
```

```js
import { createLibp2p } from 'libp2p'
import { tcp } from '@libp2p/tcp'
import { noise } from '@chainsafe/libp2p-noise'
import { yamux } from '@chainsafe/libp2p-yamux'

const node = await createLibp2p({
  transports: [tcp()],
  connectionEncrypters: [noise()],
  streamMuxers: [yamux()]
})

```

#### Running libp2p

Now that you have configured a **Transport**, **Crypto** and **Stream Multiplexer** module, you can start your libp2p node. We can start and stop libp2p using the [`libp2p.start()`](https://github.com/libp2p/js-libp2p/blob/master/doc/API.md#start) and [`libp2p.stop()`](https://github.com/libp2p/js-libp2p/blob/master/doc/API.md#stop) methods.

```js
import { createLibp2p } from 'libp2p'
import { tcp } from '@libp2p/tcp'
import { noise } from '@chainsafe/libp2p-noise'
import { yamux } from '@chainsafe/libp2p-yamux'

const main = async () => {
  const node = await createLibp2p({
    addresses: {
      // add a listen address (localhost) to accept TCP connections on a random port
      listen: ['/ip4/127.0.0.1/tcp/0']
    },
    transports: [tcp()],
    connectionEncrypters: [noise()],
    streamMuxers: [yamux()]
  })

  // start libp2p
  await node.start()
  console.log('libp2p has started')

  // print out listening addresses
  console.log('listening on addresses:')
  node.getMultiaddrs().forEach((addr) => {
    console.log(addr.toString())
  })

  // stop libp2p
  await node.stop()
  console.log('libp2p has stopped')
}

main().then().catch(console.error)

```

Try running the code with `node src/index.js`. You should see something like:

```shell
libp2p has started
listening on addresses:
/ip4/192.0.2.0/tcp/50626/p2p/QmYoqzFj5rhzFy7thCPPGbDkDkLMbQzanxCNwefZd3qTkz
libp2p has stopped
```

### Lets play ping pong!

Now that we have the basic building blocks of transport, multiplexing, and security in place, we can start communicating!

We can configure and use [`pingService`](https://libp2p.github.io/js-libp2p/modules/ping.html) to dial and send ping messages to another peer. That peer will send back a "pong" message, so that we know that it is still alive. This also enables us to measure the latency between peers.

We can have our application accepting a peer multiaddress via command line argument and try to ping it. To do so, we'll need to add a couple things. First, require the `process` module so that we can get the command line arguments. Then we'll need to parse the multiaddress from the command line and try to ping it:

```sh
npm install multiaddr @libp2p/ping
```

```javascript
import process from 'node:process'
import { createLibp2p } from 'libp2p'
import { tcp } from '@libp2p/tcp'
import { noise } from '@chainsafe/libp2p-noise'
import { yamux } from '@chainsafe/libp2p-yamux'
import { multiaddr } from 'multiaddr'
import { ping } from '@libp2p/ping'

const node = await createLibp2p({
  addresses: {
    // add a listen address (localhost) to accept TCP connections on a random port
    listen: ['/ip4/127.0.0.1/tcp/0']
  },
  transports: [tcp()],
  connectionEncrypters: [noise()],
  streamMuxers: [yamux()],
  services: {
    ping: ping({
      protocolPrefix: 'ipfs', // default
    }),
  },
})

// start libp2p
await node.start()
console.log('libp2p has started')

// print out listening addresses
console.log('listening on addresses:')
node.getMultiaddrs().forEach((addr) => {
  console.log(addr.toString())
})

// ping peer if received multiaddr
if (process.argv.length >= 3) {
  const ma = multiaddr(process.argv[2])
  console.log(`pinging remote peer at ${process.argv[2]}`)
  const latency = await node.services.ping.ping(ma)
  console.log(`pinged ${process.argv[2]} in ${latency}ms`)
} else {
  console.log('no remote peer address given, skipping ping')
}

const stop = async () => {
  // stop libp2p
  await node.stop()
  console.log('libp2p has stopped')
  process.exit(0)
}

process.on('SIGTERM', stop)
process.on('SIGINT', stop)

```

Now we can start one instance with no arguments:

```shell
> node src/index.js
libp2p has started
listening on addresses:
/ip4/192.0.2.0/tcp/50775/p2p/QmcafwJSsCsnjMo2fyf1doMjin8nrMawfwZiPftBDpahzN
no remote peer address given, skipping ping
```

Grab the `/ip4/...` address printed above and use it as an argument to another instance.  In a new terminal:

```shell
> node src/index.js /ip4/192.0.2.0/tcp/50775/p2p/QmcafwJSsCsnjMo2fyf1doMjin8nrMawfwZiPftBDpahzN
libp2p has started
listening on addresses:
/ip4/192.0.2.0/tcp/50777/p2p/QmYZirEPREz9vSRFznxhQbWNya2LXPz5VCahRCT7caTLGm
pinging remote peer at /ip4/192.0.2.0/tcp/50775/p2p/QmcafwJSsCsnjMo2fyf1doMjin8nrMawfwZiPftBDpahzN
pinged /ip4/192.0.2.0/tcp/50775/p2p/QmcafwJSsCsnjMo2fyf1doMjin8nrMawfwZiPftBDpahzN in 3ms
```

Success! Our two peers are now communicating over a multiplexed, secure channel.  Sure, they can only say "ping", but it's a start!

### What's next?

After finishing this tutorial, you should have a look into the [js-libp2p getting started](https://github.com/libp2p/js-libp2p/blob/master/doc/GETTING_STARTED.md) document, which goes from a base configuration like this one, to more custom ones.

A range of examples are available in the [js-libp2p-examples repo](https://github.com/libp2p/js-libp2p-examples) for you to learn how to use `js-libp2p` for several different use cases and runtimes.

[definition_multiaddress]: /reference/glossary/#multiaddr
[definition_multiplexer]: /reference/glossary/#multiplexer
[definition_peerid]: /reference/glossary/#peerid

---

## File: content/guides/getting-started/nim.md

---
title: "Run a nim-libp2p node"
weight: 5
aliases:
    - "/tutorials/nim"
    - "/guides/nim"
---

Check out [tutorials of the Nim libp2p implementation](https://vacp2p.github.io/nim-libp2p/docs/).

---

## File: content/guides/getting-started/rust.md

---
title: "Run a rust-libp2p node"
weight: 4
aliases:
    - "/tutorials/rust"
    - "/guides"
    - "/guides/rust"
---

Check out [tutorials of the Rust libp2p implementation](https://docs.rs/libp2p/newest/libp2p/tutorials/index.html).

---

## File: content/guides/getting-started/webrtc.md

---
title: "WebRTC with js-libp2p"
weight: 3
aliases:
  - "/tutorials/webrtc-js-libp2p"
  - "/guides/js-libp2p-webrtc"
---

## Introduction

In this guide, you will learn how to establish direct peer-to-peer (p2p) connections between browsers using [js-libp2p](https://github.com/libp2p/js-libp2p) and WebRTC.

Browser-to-browser connectivity is the foundation for distributed apps. When combined with GossipSub, like in the [universal connectivity](https://github.com/libp2p/universal-connectivity) chat app, it gives you the building blocks for peer-to-peer event-based apps with mesh topologies.

By the end of the guide, you will be familiar with the requisite libp2p and WebRTC protocols and concepts and how to use them to establish libp2p connections between browsers. You can find [the associated code for this guide on GitHub](https://github.com/libp2p/libp2p-webrtc-guide).

Since js-libp2p runs both in the browser and Node.js with WebRTC being supported in both, what's covered in this guide also applies to using the WebRTC transport to dial browsers _from_ Node.js.

WebRTC is a set of open standards and Web APIs that enable Web apps to establish direct connectivity for audio/video conferencing and exchanging arbitrary data. Today, WebRTC is [supported by most browsers](https://caniuse.com/?search=webrtc) and powers a lot of popular web conferencing apps.

Both js-libp2p and WebRTC are quite complicated technologies due to the complex nature of peer-to-peer networking, browser standards, and security. In favor of brevity, this guide will skim over some details while linking out to relevant resources.

## Why WebRTC & libp2p

WebRTC and libp2p can be used independently of each other. This begs the question, why use the two together? The **TL;DR is that they complement each other.**

WebRTC's goal is to enable applications to establish direct connections between their users in the browser, i.e. _peer-to-peer "browser-to-browser" connectivity_.

Libp2p gives you the tools to build interoperable cross-platform peer-to-peer applications with mesh topologies that work both on the web and as stand-alone binaries.

Direct connections are especially useful for video and audio calling, because they allow traffic, i.e. the packets, to flow directly from one peer to another without an additional network hop to a server that may be geographically far (network latency is still bound to distances and the speed of light).

However, the reality of public internet networking—given routers, NAT layers, VPNs, and firewalls—is such that p2p connectivity is riddled with challenges. These are commonly overcome by running additional infrastructure such as signaling, [STUN](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Protocols), and [TURN](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Protocols) servers, some of which are standardized as part of WebRTC.

While WebRTC is a solution to peer-to-peer connectivity in the context of browsers. Libp2p encompasses a wider scope with building blocks for constructing peer-to-peer apps that support WebRTC in addition to [other transports, such as QUIC, TCP, WebSocket, WebTransport](https://connectivity.libp2p.io/), and essentially form a mesh topology:



Another benefit of WebRTC and libp2p is that it allows you to dial a js-libp2p peer in the browser from a js-libp2p in Node.js.

The diagram above illustrates a mesh topology with libp2p, whereby each peer is identified by a [Peer ID](https://docs.libp2p.io/concepts/fundamentals/peers/) that is derived from a public key. When you create a new peer libp2p will first create a new public-private key pair, unless you provide one. Each Peer can have multiple addresses depending on the transport protocols it can be dialed with, e.g. WebRTC in the browser, which can also change.

## Peer-to-peer connections: when two aren't enough to tango

Perhaps the most important thing to note about WebRTC and the connection flow is that you need additional server(s) to establish a direct connection between two browsers.
The role of these servers is to assist the two browsers in discovering their public IP address so that they can set up a direct connection.

Specifically, these include:

- **STUN** server: helps the browser discover its observed public address and is necessary in almost all cases, due to NAT making it hard for a browser to know its observed public IP. There are many [free public STUN servers](https://gist.github.com/mondain/b0ec1cf5f60ae726202e) that you can use.
- **TURN** (Relay) server: relays traffic if the browsers fail to establish a direct connection and is defined as part of the WebRTC specification. Unlike signaling and STUN servers, TURN servers can be costly to run because they route all traffic between peers. This guide does not use TURN servers. Instead, it leans on GossipSub to ensure delivery of messages when direct connections cannot be established.
- **Signaling**: helps the browsers exchange [SDP (Session Description Protocol)](https://developer.mozilla.org/en-US/docs/Glossary/SDP) messages: the metadata necessary to establish a connection. Most importantly, signaling is not part of the WebRTC specification. This means that applications are free to implement signaling as they see fit. In this guide, you will use Libp2p's [protocol for signaling](https://github.com/libp2p/specs/blob/master/webrtc/webrtc.md#signaling-protocol) over Circuit Relay v2 connections.
- **Libp2p relay**: The libp2p peer serves two roles:
  - **Circuit Relay V2**: A publicly reachable libp2p peer that can serve as a relay between browser nodes that have yet to establish a direct connection between each other. Unlike TURN servers, which are WebRTC-specific and can be costly to run, Circuit Relay V2 is a libp2p protocol that is resource-constrained by design. It's also decentralized and trustless, in the sense that any publicly reachable libp2p peer supporting the protocol can help browser-based libp2p nodes by serving as a (time and bandwidth-constrained) relay.
  - **PubSub Peer Discovery**: For browser peers to discover each other, they require a mechanism to announce their multiaddresses to other libp2p peers, including browsers. GossipSub is a PubSub implementation that helps by relaying those peer discovery messages between browsers, kicking off the direct connection establishment. Note that this approach to peer discovery is not very scalable and probably not fit for production use cases.

In summary, as part of this guide, you will learn how to run a publicly reachable, long-running libp2p peer that serves as both a circuit relay and a GossipSub message relay. This guide refer to that libp2p peer as the **"relay"** or **"bootstrapper"** peer depending on the context.

## Connection flow diagram

The following diagrams visualize the connection flow between two browsers using js-libp2p and WebRTC.

The first diagram illustrates the peer discovery and establishment of a relayed connection between the two browsers:



The second diagram, which continues from the first, illustrates the SDP handshake via the Circuit Relay:



The connection flow seems complex, but thankfully, libp2p abstracts away some of that complexity and the rest is explained in this guide.

Either way, there are several noteworthy things about the connection flow:

1. There's no prescribed mechanism in libp2p for how the two peers discover each other's multiaddress; this is also known as **"peer discovery"**. This guide uses a [dedicated GossipSub channel for the application where you publish your multiaddrs (periodically) similar to mdns](https://github.com/libp2p/js-libp2p-pubsub-peer-discovery/). PubSub peer discovery works well for demos and guides, but its current design is not battle-tested for production use cases at scale.
2. Other approaches to Peer routing and discovery include [DHT FIND_NODE query](https://github.com/libp2p/specs/blob/master/kad-dht/README.md#dht-operations), [HTTP Delegated Routing](https://specs.ipfs.tech/routing/http-routing-v1/), and [GossipSub Peer Exchange](https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md), though browser peers don't tend to be long-lived enough to appear in the results of the first two.
3. Since this guide uses a GossipSub channel for peer discovery, the relay node listens to the discovery topic too so that it relays messages between browsers who've yet to establish a direct connection.

## Prerequisites

- [Node.js](https://nodejs.org/en) installed to build the frontend and to run the relay
- Chrome or Firefox, for WebTransport connectivity to the relay ([Safari does not support WebTransport](https://caniuse.com/webtransport))

This guide assumes a basic understanding of libp2p concepts such as:

- [Peer ID]({{< relref "/concepts/fundamentals/peers#peer-id" >}})
- [Multiaddresses (often abbreviated multiaddr)]({{< relref "/concepts/fundamentals/addressing" >}})
- [Libp2p transports]({{< relref "/concepts/transports/overview" >}})
- [GossipSub]({{< relref "/concepts/pubsub/overview" >}})

Besides that, most of this guide focuses on js-libp2p, i.e. JavaScript.

## Step 1: Clone the repository and install dependencies

Clone the repository:

```bash
git clone https://github.com/libp2p/libp2p-webrtc-guide
```

Once the repository is cloned, enter the `libp2p-webrtc-guide` folder, and install the npm dependencies

```bash
cd libp2p-webrtc-guide
npm install
```

## Step 2: Start the js-libp2p node.js relay

In this step, you start the node.js relay.

Run the following command:

```bash
npm run start:relay
```

It also outputs the PeerID and the multiaddrs it's listening on and should look similar to:

```bash
PeerID:  12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ
Multiaddrs:  [
  Multiaddr(/ip4/127.0.0.1/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ),
  Multiaddr(/ip4/192.168.3.174/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ),
  Multiaddr(/ip4/127.0.0.1/tcp/9002/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ),
  Multiaddr(/ip4/192.168.3.174/tcp/9002/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ)
]
```

## Step 3: Start js-libp2p in the browser

In this step, you start the js-libp2p peer in the browser/

In a new terminal window, open the repository cloned in the previous step:

```bash
cd libp2p-webrtc-guide
```

Run the following command to start the frontend development server:

```bash
npm run start
```

The output contains the address of the local development server:

```bash
 > Local:   http://127.0.0.1:8000/
```

Next, open the `src/index.js` file in your code editor and find the call to `createLibp2p`:

```js
const libp2p = await createLibp2p({
  transports: [
    webSockets(),
    webTransport(),
    webRTC(),
  ],
  connectionEncrypters: [noise()],
  streamMuxers: [yamux()],
  connectionGater: {
    // Allow private addresses for local testing
    denyDialMultiaddr: async () => false,
  },
  services: {
    identify: identify(),
  },
});
```

The `createLibp2p` invocation creates a libp2p peer which has its associated key pair and [Peer ID]({{< relref "/concepts/fundamentals/peers#peer-id" >}}) with support for the WebSocket , WebTransport and WebRTC transports, as well as the [identify protocol]({{< relref "/concepts/fundamentals/protocols#identify" >}}). It also uses noise to ensure all connections are encrypted, and yamux as the stream multiplexer for the relayed connection.

{{< alert icon="💡" context="note">}}
**Why is yamux needed?**

You may notice that the above js-libp2p configuration adds yamux as the stream multiplexer. While both WebRTC and WebTransport come with native [stream multiplexing]({{< relref "/concepts/multiplex/overview" >}}), yamux is still required for WebSockets to multiplex streams on the circuit relay connection.



When a browser initiates the connection to another browser over a circuit relay, the underlying WebSocket stream to the relay is multiplexed by yamux and encrypted by Noise. In the case of WebTransport it is multiplexed and encrypted natively. Either way, the relayed connection between the two browsers must be encrypted by noise otherwise the relay could eavesdrop on the traffic. Once the relayed connection between the browsers is encrypted, it also requires yamux to create a stream for the signaling protocol.

{{< /alert >}}

This is the minimal configuration needed to establish a connection to the local
relay.

Finally, open `http://127.0.0.1:8000/` in your browser and you will see your Peer ID. This Peer ID is created automatically and persists in memory. Reloading the page results in a new PeerID

## Step 4: Connect to the relay from the browser

In this step, you connect the browser js-libp2p peer to the node.js relay peer.

Open the frontend in your browser (or use the one open from the previous step) and enter the loopback WebSocket multiaddr of the relay, i.e. `/ip4/127.0.0.1/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ`



Now click Connect and the peer should appear in the peer List:



Congratulations, you have now established a WebSocket connection to the relay.

{{< alert icon="💡" context="info">}}
In a production application that is deployed and served with TLS, the relay peer needs a stable hostname and a TLS certificate due to [Secure Contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts). This requires you to use a reverse proxy, e.g. Nginx or Caddy, to handle [TLS termination](https://en.wikipedia.org/wiki/TLS_termination_proxy).
{{< /alert >}}

## Step 5: Make the browser dialable with Circuit Relay

In this step, you enable the circuit relay transport to make the browser dialable via the relay peer (that is already configured as a circuit relay server).

In the `src/index.js` file, update the call to `createLibp2p` as follows:

```diff
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2'

const libp2p = await createLibp2p({
+  addresses: {
+    listen: [
+      // 👇 Required to create circuit relay reservations in order to respond to incoming WebRTC connections
+      '/p2p-circuit',
+    ],
+  },
  transports: [
    webSockets(),
    webTransport(),
    webRTC(),
+    circuitRelayTransport(),
  ],
  connectionEncrypters: [noise()],
  streamMuxers: [yamux()],
  connectionGater: {
    // Allow private addresses for local testing
    denyDialMultiaddr: async () => false,
  },
  services: {
    identify: identify(),
  },
})
```

If you reload the page and connect to the relay multiaddr (by copying the multiaddr of the relay from the terminal) notice that the browser peer now shows (depending on your network setup) four multiaddrs addresses (or two if you don't have a private network IP) that look as follows:

```bash
/ip4/127.0.0.1/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ/p2p-circuit/p2p/12D3KooWQny42bDJfqPoBfpd9qNw2HrqtUTStUmCgBktnDXhisW7
/ip4/192.168.3.174/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ/p2p-circuit/p2p/12D3KooWQny42bDJfqPoBfpd9qNw2HrqtUTStUmCgBktnDXhisW7
/ip4/127.0.0.1/tcp/9002/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ/p2p-circuit/p2p/12D3KooWQny42bDJfqPoBfpd9qNw2HrqtUTStUmCgBktnDXhisW7
/ip4/192.168.3.174/tcp/9002/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ/p2p-circuit/p2p/12D3KooWQny42bDJfqPoBfpd9qNw2HrqtUTStUmCgBktnDXhisW7
```

For each network interface the relay binds to, there are two addresses: **one TCP multiaddr and one WebSocket (denoted by `ws` in the multiaddr).** This means that the browser is now dialable via both the localhost, private network over two transports: WebSockets and TCP.

Observe that the beginning of the multiaddr is the same as the relay, followed by `/p2p-circuit/p2p/BROWSER_PEER_ID`. This multiaddr can be used by other browser peers (capable of WebTransport) to connect to the first browser window using the relay:



By adding a `circuitRelayTransport` and configuring a `/p2p-circuit` listen address, js-libp2p was able to create circuit relay reservation (time and bandwidth-constrained) on the relay.

### Testing circuit relay

To test dialing the browser with circuit relay:

1. Copy the local WebSocket multiaddr (`127.0.0.1` with `ws`) relay address from the browser tab.
2. Open a second browser tab, paste the multiaddr and click **Connect**.

The second browser tab should connect to two peers, i.e. the relay and the browser. You should also see two Peer IDs appear in the list of peers.

## Step 6: Set the relay in the browser app as a bootstrap peer

In this step you configure js-libp2p to automatically connect to the relay peer. In libp2p, peers that you automatically connect to are commonly bootstrap peers, hence the name of the module.

Update the `src/index.js` file as follows, making sure to replace the multiaddr with the one from your relay:

```diff
+import { bootstrap } from '@libp2p/bootstrap'

const libp2p = await createLibp2p({
  addresses: {
    listen: [
      '/p2p-circuit',
    ],
  },
  transports: [
    webSockets(),
    webTransport(),
    webRTC(),
    circuitRelayTransport(),
  ],
  connectionEncrypters: [noise()],
  streamMuxers: [yamux()],
  connectionGater: {
    // Allow private addresses for local testing
    denyDialMultiaddr: async () => false,
  },
+  peerDiscovery: [
+      bootstrap({
+        // replace with your relay multiaddr
+        list: ['/ip4/127.0.0.1/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ'],
+      }),
+  ]
  services: {
    identify: identify(),
  },
})
```

Reload the page, and the peer automatically reconnects to the relay.

## Step 7: Listen on WebRTC and establish a direct connection

In this step, the js-libp2p configuration is updated to listen for WebRTC connections.

In the `src/index.js` file, update the call to `createLibp2p` as follows:

```diff
const libp2p = await createLibp2p({
  addresses: {
    listen: [
      '/p2p-circuit',
+      // 👇 Listen for webRTC connections
+      '/webrtc',
    ],
  },
  transports: [
    webSockets(),
    webTransport(),
    webRTC(),
    circuitRelayTransport(),
  ],
  connectionEncrypters: [noise()],
  streamMuxers: [yamux()],
  connectionGater: {
    // Allow private addresses for local testing
    denyDialMultiaddr: async () => false,
  },
  peerDiscovery: [
      bootstrap({
        // replace with your relay multiaddr
        list: ['/ip4/127.0.0.1/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ'],
      }),
  ]
  services: {
    identify: identify(),
  },
})
```

With the change above, libp2p leverages circuit relays as the signalling channel for WebRTC connections.

Reload the frontend, and once again connect to the relay by copying its `ws` multiaddr from the terminal.

After connecting to the relay, the frontend renders four new multiaddrs that look like:

```bash
/ip4/127.0.0.1/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ/p2p-circuit/webrtc/p2p/12D3KooWQny42bDJfqPoBfpd9qNw2HrqtUTStUmCgBktnDXhisW7
/ip4/192.168.3.174/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ/p2p-circuit/webrtc/p2p/12D3KooWQny42bDJfqPoBfpd9qNw2HrqtUTStUmCgBktnDXhisW7
/ip4/127.0.0.1/tcp/9002/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ/p2p-circuit/webrtc/p2p/12D3KooWQny42bDJfqPoBfpd9qNw2HrqtUTStUmCgBktnDXhisW7
/ip4/192.168.3.174/tcp/9002/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ/p2p-circuit/webrtc/p2p/12D3KooWQny42bDJfqPoBfpd9qNw2HrqtUTStUmCgBktnDXhisW7
```

These new multiaddrs all contain `/webrtc/` meaning they are intended for establishing a direct WebRTC connection between two browsers. The first two are relevant for the browser, since they are WebSocket multiaddrs.

Copy the first multiaddr that contains: `.../ws/p2p/RELAY_PEER_ID/p2p-circuit/webrtc/p2p/BROWSER_PEER_ID`, open another browser window, and paste the multiaddr into the input, and click Connect.

Once the connection succeeds, the WebRTC connection count in both browsers is **1** and both browsers are connected to the relay as well as the other browser Peer ID:



Congratulations! You have successfully established a direct connection between two browsers.

Exchanging multiaddrs manually is cumbersome. To avoid this, let's introduce PubSub-based peer discovery in the next step.

## Step 8: PubSub peer discovery

In the previous steps, you worked through the process of establishing a WebRTC connection by manually copying the multiaddrs.

In this step, PubSub peer discovery is introduced so the browsers can exchange their multiaddrs and discover each other automatically (with the help of the relay).

In libp2p, PubSub is implemented with the [GossipSub protocol]({{< relref "/concepts/pubsub/overview" >}}), which provides an efficient way for mesh networks to exchange messages.

For PubSub peer discovery to work, both frontend and the relay must use the same topic. As soon as the frontend discovers its own multiaddrs, it publishes it in a message to the discovery topic. The relay, which is also listening to the discovery topic, gossips the message to other browser peers connected to it, which in turn, establish direct WebRTC connections. From a high level, it looks as follows:



In the `src/index.js` file, update the call to `createLibp2p` as follows:

```diff

+import { gossipsub } from '@chainsafe/libp2p-gossipsub'
+import { pubsubPeerDiscovery } from '@libp2p/pubsub-peer-discovery'
+import { PUBSUB_PEER_DISCOVERY } from './constants.js'

const libp2p = await createLibp2p({
  addresses: {
    listen: [
      '/p2p-circuit',
      '/webrtc',
    ],
  },
  transports: [
    webSockets(),
    webTransport(),
    webRTC(),
    circuitRelayTransport(),
  ],
  connectionEncrypters: [noise()],
  streamMuxers: [yamux()],
  connectionGater: {
    // Allow private addresses for local testing
    denyDialMultiaddr: async () => false,
  },
  peerDiscovery: [
      bootstrap({
        // replace with your relay multiaddr
        list: ['/ip4/127.0.0.1/tcp/9001/ws/p2p/12D3KooWQtCgYCZ7JZQoe7Ao6KP5CDMnmEiURqMoarfBgJwbnCPQ'],
      }),
+      pubsubPeerDiscovery({
+        // Every 10 seconds publish our multiaddrs
+        interval: 10_000,
+        // The topic that the relay is also subscribed to
+        topics: [PUBSUB_PEER_DISCOVERY],
+      }),
  ],
  services: {
+    pubsub: gossipsub(),
    identify: identify(),
  },
})

+libp2p.addEventListener('peer:discovery', async (evt) => {
+  // Encapsulate the peer ID to ensure dialing succeeds
+  // Should be removed once https://github.com/libp2p/js-libp2p/issues/3239 is resolved.
+  const maddrs = evt.detail.multiaddrs.map((ma) => ma.encapsulate(`/p2p/${evt.detail.id.toString()}`))
+  console.log(
+    `Discovered new peer (${evt.detail.id.toString()}). Dialling:`, maddrs.map((ma) => ma.toString()),
+  )
+  try {
+    await libp2p.dial(maddrs)
+  } catch (err) {
+    console.error(`Failed to dial peer (${evt.detail.id.toString()}):`, err)
+  }
+})
```

A couple of note-worthy things about these changes:

- The `pubsub` service adds GossipSub protocol capabilities to the node.
- `pubsubPeerDiscovery` depends on the `pubsub` service and introduces the peer discovery mechanism. [GossipSub is a large dependency](https://packagephobia.com/result?p=%40chainsafe%2Flibp2p-gossipsub) making it suboptimal for browser bundles.
- When js-libp2p discovers a new peer (and its multiaddrs) it emits a `peer:discovery` event.
- To dial a newly discovered peer, add an event listener for the `peer:discovery` event and dial the peer with the `dial` method.
- PubSub peer discovery works well for demos and guides, but its current design is not battle-tested for production use cases.

Next, open two browser tabs of the frontend, and you should see them connected to each other within a couple of seconds 🎉.

## Summary

If you have reached this far in the guide, well done! You learned how to establish browser-to-browser connectivity with libp2p and WebRTC and how libp2p abstracts aspects of WebRTC like signaling and SDP exchange. You also learned about js-libp2p's configuration options and concepts such as Peer IDs, Multiaddrs, and GossipSub.

## Final notes

### NAT hole punching

Peer-to-peer connectivity is inherently hard, which is why in this guide, all connections were on a local machine which significantly increases connection success rates.

On public networks where both browser peers are behind NAT, NAT hole punching success rates range around 80% depending on the network conditions and the [types of NAT the peers are behind](https://tailscale.com/blog/how-nat-traversal-works#the-nature-of-nats). The implications of this depend on the nature of your app. PubSub with GossipSub is designed to ensure the delivery of messages without requiring a connection to the whole mesh. In other words, the GossipSub protocol is designed with sparsely-connected networks, where you are not connected to all other peers. So long as the browser peer can publish a message to at least one other peer, the message propagates to all subscribers.

Another approach is to introduce a TURN server, however, TURN servers tend to be complex to run, bandwidth-heavy, and prone to abuse, since they relay all traffic.

If you want to experiment with this example over public networks, the relay peer must be publicly reachable, i.e. have a public IP that is dialable by browser peers.

### Differences between js-libp2p in Node.js and browser

Connectivity between the browser and relay is constrained by supported transports of the browser and the specific libp2p implementation.

At the time of writing, **js-libp2p in browsers** supports:

- WebSocket: this works well and is broadly adopted by libp2p implementations, but requires the relay to have CA-signed TLS certificate and a domain name to work in [Secure Contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts). Another disadvantage of Secure WebSocket is that it results in double encryption (TLS and Noise) with libp2p.
- WebTransport: Supported by [Chrome, Firefox, Opera, and Edge](https://caniuse.com/webtransport), but not Safari.
- WebRTC: Supported by most browsers
- [WebRTC-direct](https://github.com/libp2p/js-libp2p/tree/main/packages/transport-webrtc#webrtc-vs-webrtc-direct): Supported by all browsers that support WebRTC.

While **js-libp2p in Node.js** supports:

1. WebRTC: this one is rather confusing because [unlike](https://github.com/libp2p/js-libp2p/tree/main/packages/transport-webrtc#webrtc-vs-webrtc-direct) [WebRTC direct](https://github.com/libp2p/specs/blob/master/webrtc/webrtc-direct.md), it requires an additional circuit relay peer to forward SDP messages between the browser and the Node.js relay, making it infeasible for the Node.js peer to be the relay. WebRTC-direct solves this problem, however, at the time of writing it isn't supported by js-libp2p (See [tracking issue](https://github.com/libp2p/js-libp2p/issues/2581)).
2. WebSocket: as mentioned above, requires a CA-signed TLS certificate and a domain.
3. TCP: not available in browsers.

Therefore, until WebRTC-Direct or WebTransport support is added to js-libp2p in Node.js, it's much easier to use go-libp2p.

## Next steps

As a next step, the [universal connectivity app](https://github.com/libp2p/universal-connectivity) can be a great learning resource, as it expands on many of the concepts and patterns implemented by this guide, in addition to having two bootstrapper implementations in Rust and Go.

### Try the go-libp2p relay with WebTransport

Go into the `go-relay` directory and install dependencies

```bash
cd go-relay
go get .
```

From the `go-relay` folder, run the following command to compile and run the relay:

```bash
go run .
```

This compiles and runs the relay. It also outputs the PeerID and the multiaddrs it's listening on. The output looks similar to:

```bash
2024/05/21 17:43:43 PeerID: 12D3KooWMEZEwzATAoXFbPmb1kgD7p4Ue3jzHGQ8ti2UrsFg11YJ
2024/05/21 17:43:43 Listening on: /ip4/127.0.0.1/udp/9095/quic-v1/p2p/12D3KooWMEZEwzATAoXFbPmb1kgD7p4Ue3jzHGQ8ti2UrsFg11YJ
2024/05/21 17:43:43 Listening on: /ip4/127.0.0.1/udp/9095/quic-v1/webtransport/certhash/uEiAbhhQxJeJ6nAWdpB6NdSV4UPaTwEcy9eA76p22SoKyvg/certhash/uEiBTPUrn6BebjshxC80Uarqi4ZsMhrPPQNu2RDu1N4n_Ww/p2p/12D3KooWMEZEwzATAoXFbPmb1kgD7p4Ue3jzHGQ8ti2UrsFg11YJ
2024/05/21 17:43:43 Listening on: /ip4/192.168.3.174/udp/9095/quic-v1/p2p/12D3KooWMEZEwzATAoXFbPmb1kgD7p4Ue3jzHGQ8ti2UrsFg11YJ
2024/05/21 17:43:43 Listening on: /ip4/192.168.3.174/udp/9095/quic-v1/webtransport/certhash/uEiAbhhQxJeJ6nAWdpB6NdSV4UPaTwEcy9eA76p22SoKyvg/certhash/uEiBTPUrn6BebjshxC80Uarqi4ZsMhrPPQNu2RDu1N4n_Ww/p2p/12D3KooWMEZEwzATAoXFbPmb1kgD7p4Ue3jzHGQ8ti2UrsFg11YJ
```

Note that it's listening on two interfaces (the loopback and the private network) and two transports: QUIC and WebTransport (which is on top of QUIC). QUIC can be used for connections to other go-libp2p relays, while WebTransport for connections from browsers. That means that QUIC isn't strictly necessary, but it's useful if you deploy another relay for resilience or leverage the DHT for peer discovery.

#### Ephemeral WebTransport multiaddr

Another thing worth noting is that the WebTransport multiaddr contains two certificate hashes. These are needed by the browser to verify a self-signed certificate of the go-relay peer. Unlike CA-signed certificates, self-signed certificates can be created on the fly without interaction with a certificate authority.

So why two certificate hashes? Self-signed certificates are valid for at most 14 days. So by convention, go-libp2p generates two consecutively valid certificates to ensure a smooth transition when a new certificate is rolled out.

Another challenge you may face is that the WebTransport multiaddr that is hardcoded into the js-libp2p configuration is ephemeral and valid for around 28 days (2 certificate hashes valid for 14 days each). One way to address this is using the DHT to resolve the Peer ID (which is stable and would be hard coded in the frontend) to its latest multiaddrs as done by the [universal connectivity app](https://github.com/libp2p/universal-connectivity).

---

## File: content/concepts/transports/_index.md

---
title : "Transports"
weight: 3
---

---

## File: content/concepts/transports/listen-and-dial.md

---
title: "Listening and Dialing"
weight: 80
aliases:
    - "/concepts/transports/listen-and-dial"
---

## Common transport interfaces

Transports are defined in terms of two core operations, **listening** and
**dialing**.

Listening means that you can accept incoming connections from other peers,
using whatever facility is provided by the
transport implementation. For example, a TCP transport on a unix platform could
use the `bind` and `listen` system calls to have the operating system route
traffic on a given TCP port to the application.

Dialing is the process of opening an outgoing connection to a listening peer.
Like listening, the specifics are determined by the implementation, but every
transport in a libp2p implementation will share the same programmatic interface.

## Addresses

Before you can dial up a peer and open a connection, you need to know how to
reach them. Because each transport will likely require its own address scheme,
libp2p uses a convention called a "multiaddress" or `multiaddr` to encode
many different addressing schemes.

The [addressing doc]({{< relref "/concepts/fundamentals/addressing.md" >}}) goes into more detail, but an overview
of how multiaddresses work is helpful for understanding the dial and listen
interfaces.

Here's an example of a multiaddr for a TCP/IP transport:

```shell
/ip4/198.51.100.0/tcp/6543
```

This is equivalent to the more familiar `198.51.100.0:6543` construction, but it
has the advantage of being explicit about the protocols that are being
described. With the multiaddr, you can see at a glance that the `198.51.100.0`
address belongs to the IPv4 protocol, and the `6543` belongs to TCP.

For more complex examples, see [addressing]({{< relref "/concepts/fundamentals/addressing.md" >}}).

Both dial and listen deal with multiaddresses. When listening, you give the
transport the address you'd like to listen on, and when dialing you provide the
address to dial to.

When dialing a remote peer, the multiaddress should include the
[PeerId]({{< relref "/concepts/fundamentals/peers.md#peer-id" >}}) of the peer you're trying to reach.
This lets libp2p establish a [secure communication channel]({{< relref "/concepts/secure-comm/overview.md" >}})
and prevents impersonation.

An example multiaddress that includes a `PeerId`:

```shell
/ip4/192.0.2.0/tcp/4321/p2p/QmcEPrat8ShnCph8WjkREzt5CPXF2RwhYxYBALDcLC1iV6
```

The `/p2p/QmcEPrat8ShnCph8WjkREzt5CPXF2RwhYxYBALDcLC1iV6` component uniquely
identifies the remote peer using the hash of its public key.
For more, see the [peer identity content]({{< relref "/concepts/fundamentals/peers.md#peer-id" >}}).

{{< alert icon="💡" context="tip">}}
When peer routing is enabled, you can dial peers using just their PeerId,
without needing to know their transport addresses before hand.
{{< /alert >}}

## Supporting multiple transports

libp2p applications often need to support multiple transports at once. For
example, you might want your services to be usable from long-running daemon
processes via TCP, while also accepting websocket connections from peers running
in a web browser.

The libp2p component responsible for managing the transports is called the
[switch][definition_switch], which also coordinates
[protocol negotiation]({{< relref "/concepts/fundamentals/protocols.md#protocol-negotiation" >}}),
[stream multiplexing]({{< relref "/concepts/multiplex/overview.md" >}}),
[establishing secure communication]({{< relref "/concepts/secure-comm/overview.md" >}}) and other forms of
"connection upgrading".

The switch provides a single "entry point" for dialing and listening, and frees
up your application code from having to worry about the specific transports
and other pieces of the "connection stack" that are used under the hood.

{{< alert icon="💡" context="note" text="The term \"swarm\" was previously used to refer to what is now called the \"switch\", and some places in the codebase still use the \"swarm\" terminology." />}}

[definition_switch]: {{< relref "/concepts/appendix/glossary#switch" >}}