From b32e33a9f275e2b1c277ffe6bf051b06d6dc2925 Mon Sep 17 00:00:00 2001 From: achingbrain Date: Wed, 25 Oct 2023 14:02:44 +0100 Subject: [PATCH] chore: update docs --- README.md | 15 +++-- .../js-libp2p-example-circuit-relay/README.md | 65 ++++++++++++++----- 2 files changed, 57 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 46ac277..d30658f 100644 --- a/README.md +++ b/README.md @@ -74,12 +74,15 @@ Make sure you have installed all of the following prerequisites on your developm ## Documentation -- [IPFS Primer](https://dweb-primer.ipfs.io/) -- [IPFS Docs](https://docs.ipfs.io/) -- [Tutorials](https://proto.school) -- [More examples](https://github.com/libp2p/js-libp2p-examples) -- [API - Helia](https://ipfs.github.io/helia/modules/helia.html) -- [API - @helia/unixfs](https://ipfs.github.io/helia-unixfs/modules/helia.html) +- [js-libp2p docs](https://github.com/libp2p/js-libp2p/tree/master/doc) +- [libp2p.io](https://libp2p.io) +- [docs.libp2p.io](https://docs.libp2p.io) +- [Specification (WIP)](https://github.com/libp2p/specs) +- [Discussion Forums](https://discuss.libp2p.io) +- Talks + - [`libp2p <3 ethereum` at DEVCON2](https://archive.devcon.org/archive/watch/2/libp2p-devp2p-ipfs-and-ethereum-networking/) +- Articles + - [The overview of libp2p](https://github.com/libp2p/libp2p#description) ## Contribute diff --git a/examples/js-libp2p-example-circuit-relay/README.md b/examples/js-libp2p-example-circuit-relay/README.md index 36d5f50..4205134 100644 --- a/examples/js-libp2p-example-circuit-relay/README.md +++ b/examples/js-libp2p-example-circuit-relay/README.md @@ -1,4 +1,4 @@ -# @libp2p/example-auto-relay +# @libp2p/example-circuit-relay [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/) [![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io) @@ -19,15 +19,24 @@ ## 0. Setup the example -Before moving into the examples, you should run `npm install` and `npm run build` on the top level `js-libp2p` folder, in order to install all the dependencies needed for this example. Once the install finishes, you should move into the example folder with `cd examples/auto-relay`. +First of all run `npm install` in the example folder. This will install all +required dependencies and you'll be ready to go. -This example comes with 3 main files. A `relay.js` file to be used in the first step, a `listener.js` file to be used in the second step and a `dialer.js` file to be used on the third step. All of these scripts will run their own libp2p node, which will interact with the previous ones. All nodes must be running in order for you to proceed. +This example comes with 3 main files. A `relay.js` file to be used in the first +step, a `listener.js` file to be used in the second step and a `dialer.js` file +to be used on the third step. All of these scripts will run their own libp2p +node, which will interact with the previous ones. All nodes must be running in +order for you to proceed. ## 1. Set up a relay node -In the first step of this example, we need to configure and run a relay node in order for our target node to bind to for accepting inbound connections. +In the first step of this example, we need to configure and run a relay node in +order for our target node to bind to for accepting inbound connections. -The relay node will need to have its relay subsystem enabled, as well as its HOP capability. It can be configured as follows: +The relay node will need to have a relay service added which will allow a +limited number of remote peers to make relay reservations with it. + +It can be configured as follows: ```js import { noise } from '@chainsafe/libp2p-noise' @@ -80,9 +89,11 @@ Listening on: ## 2. Set up a listener node with `discoverRelays` Enabled -One of the typical use cases for Circuit Relay is nodes behind a NAT or browser nodes due to their inability to expose a public address. +One of the typical use cases for Circuit Relay is nodes behind a NAT or browser +nodes due to their inability to expose a public address. -For running a libp2p node that automatically discovers available relays, you can see the following: +For running a libp2p node that automatically discovers available relays, you can +see the following: ```js import { noise } from '@chainsafe/libp2p-noise' @@ -129,7 +140,9 @@ node.addEventListener('self:peer:update', (evt) => { }) ``` -As you can see in the code, we need to provide the relay address, `relayAddr`, as a process argument. This node will dial the provided relay address and automatically bind to it. +As you can see in the code, we need to provide the relay address, `relayAddr`, +as a process argument. This node will dial the provided relay address and +automatically bind to it. You should now run the following to start the node running Auto Relay: @@ -145,13 +158,19 @@ Connected to the HOP relay QmWDn2LY8nannvSWJzruUYoLZ4vV83vfCBwd8DipvdgQc3 Advertising with a relay address of /ip4/192.168.1.120/tcp/61592/ws/p2p/QmWDn2LY8nannvSWJzruUYoLZ4vV83vfCBwd8DipvdgQc3/p2p-circuit/p2p/QmerrWofKF358JE6gv3z74cEAyL7z1KqhuUoVfGEynqjRm ``` -Per the address, it is possible to verify that the auto relay node is listening on the circuit relay node address. +Per the address, it is possible to verify that the auto relay node is listening +on the circuit relay node address. -Instead of dialing this relay manually, you could set up this node with the Bootstrap module and provide it in the bootstrap list. Moreover, you can use other `peer-discovery` modules to discover peers in the network and the node will automatically bind to the relays that support HOP until reaching the maximum number of listeners. +Instead of dialing this relay manually, you could set up this node with the +Bootstrap module and provide it in the bootstrap list. Moreover, you can use +other `peer-discovery` modules to discover peers in the network and the node +will automatically bind to the relays that support HOP until reaching the +maximum number of listeners. ## 3. Set up a dialer node for testing connectivity -Now that you have a relay node and a node bound to that relay, you can test connecting to the auto relay node via the relay. +Now that you have a relay node and a node bound to that relay, you can test +connecting to the auto relay node via the relay. ```js import { createLibp2p } from 'libp2p' @@ -177,26 +196,36 @@ const conn = await node.dial(autoRelayNodeAddr) console.log(`Connected to the auto relay node via ${conn.remoteAddr.toString()}`) ``` -You should now run the following to start the relay node using the listen address from step 2: +You should now run the following to start the relay node using the listen +address from step 2: ```sh node dialer.js /ip4/192.168.1.120/tcp/61592/ws/p2p/QmWDn2LY8nannvSWJzruUYoLZ4vV83vfCBwd8DipvdgQc3 ``` -Once you start your test node, it should print out something similar to the following: +Once you start your test node, it should print out something similar to the +following: ```sh Node started: Qme7iEzDxFoFhhkrsrkHkMnM11aPYjysaehP4NZeUfVMKG Connected to the auto relay node via /ip4/192.168.1.120/tcp/61592/ws/p2p/QmWDn2LY8nannvSWJzruUYoLZ4vV83vfCBwd8DipvdgQc3/p2p-circuit/p2p/QmerrWofKF358JE6gv3z74cEAyL7z1KqhuUoVfGEynqjRm ``` -As you can see from the output, the remote address of the established connection uses the relayed connection. +As you can see from the output, the remote address of the established connection +uses the relayed connection. ## 4. What is next? -Before moving into production, there are a few things that you should take into account. +Before moving into production, there are a few things that you should take into +account. -A relay node should not advertise its private address in a real world scenario, as the node would not be reachable by others. You should provide an array of public addresses in the libp2p `addresses.announce` option. If you are using websockets, bear in mind that due to browser’s security policies you cannot establish unencrypted connection from secure context. The simplest solution is to setup SSL with nginx and proxy to the node and setup a domain name for the certificate. +A relay node should not advertise its private address in a real world scenario, +as the node would not be reachable by others. You should provide an array of +public addresses in the libp2p `addresses.announce` option. If you are using +websockets, bear in mind that due to browser’s security policies you cannot +establish unencrypted connection from secure context. The simplest solution is +to setup SSL with nginx and proxy to the node and setup a domain name for the +certificate. ## License @@ -207,4 +236,6 @@ Licensed under either of ## Contribution -Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in the work by you, as defined in the Apache-2.0 license, shall +be dual licensed as above, without any additional terms or conditions.