|
| 1 | +# Configuration |
| 2 | + |
| 3 | +* [Overview](#overview) |
| 4 | +* [Modules](#modules) |
| 5 | + * [Transport](#transport) |
| 6 | + * [Stream Multiplexing](#stream-multiplexing) |
| 7 | + * [Connection Encryption](#connection-encryption) |
| 8 | + * [Peer Discovery](#peer-discovery) |
| 9 | + * [Content Routing](#content-routing) |
| 10 | + * [Peer Routing](#peer-routing) |
| 11 | + * [DHT](#dht) |
| 12 | + * [Pubsub](#pubsub) |
| 13 | +* [Libp2p node](#libp2p-node) |
| 14 | +* [Configuration examples](#configuration-examples) |
| 15 | + |
| 16 | +## Overview |
| 17 | + |
| 18 | +Considering libp2p's modular nature, it can be composed by a set of building blocks that enable users to create any type of p2p systems without needing to implement its network layer. Taking into account that each p2p system has its own needs and requirements, libp2p can be configured accordingly. |
| 19 | + |
| 20 | +`js-libp2p` acts as the composer for this modular p2p networking stack using libp2p compatible modules as its building blocks. |
| 21 | +While libp2p building blocks may vary, `js-libp2p` top level API will be consistent. |
| 22 | + |
| 23 | +## Modules |
| 24 | + |
| 25 | +For getting an instance of `js-libp2p` compliant with all types of networking requirements, it is possible to specify the following building blocks: |
| 26 | + |
| 27 | +- Transports |
| 28 | +- Multiplexers |
| 29 | +- Connection encryption mechanisms |
| 30 | +- Peer discovery protocols |
| 31 | +- Content routing protocols |
| 32 | +- Peer routing protocols |
| 33 | +- DHT implementation |
| 34 | +- Pubsub router |
| 35 | + |
| 36 | +The libp2p ecosystem contains at least one module for each of these building blocks. This way, the user should install and import the modules that are relevant for their requirements. Moreover, thanks to the existing interfaces it is easy to create a libp2p compatible module and use it. |
| 37 | + |
| 38 | +After selecting the modules to use, it is also possible to configure each one according to your needs. |
| 39 | + |
| 40 | +Bear in mind that only a **transport** is required, being all the other building blocks optional. |
| 41 | + |
| 42 | +### Transport |
| 43 | + |
| 44 | +> In a p2p system, we need to interact with other peers in the network. Transports are used to establish connections between peers. The libp2p transports to use should be decided according to the environment where your node will live, as well as other requirements that you might have. |
| 45 | +
|
| 46 | +The available transports are: |
| 47 | + |
| 48 | +- [libp2p/js-libp2p-tcp](https://github.com/libp2p/js-libp2p-tcp) |
| 49 | +- [libp2p/js-libp2p-webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star) |
| 50 | +- [libp2p/js-libp2p-webrtc-direct](https://github.com/libp2p/js-libp2p-webrtc-direct) |
| 51 | +- [libp2p/js-libp2p-websocket-star](https://github.com/libp2p/js-libp2p-websocket-star) (Work in Progress) |
| 52 | +- [libp2p/js-libp2p-websockets](https://github.com/libp2p/js-libp2p-websockets) |
| 53 | +- [libp2p/js-libp2p-utp](https://github.com/libp2p/js-libp2p-utp) (Work in Progress) |
| 54 | + |
| 55 | +If none of the available transports fulfills your needs, you can create a libp2p compatible transport. A libp2p transport just needs to be compliant with the [interface-transport](https://github.com/libp2p/js-interfaces/tree/master/src/transport). |
| 56 | + |
| 57 | +If you want to get to know more about libp2p transports, you should read the following content: |
| 58 | + |
| 59 | +- https://docs.libp2p.io/concepts/transport |
| 60 | +- https://github.com/libp2p/specs/tree/master/connections |
| 61 | + |
| 62 | +### Stream Multiplexing |
| 63 | + |
| 64 | +> Libp2p peers will need to communicate with each other through several protocols during their life. Stream multiplexing allows multiple independent logical streams to share a common underlying transport medium, instead of creating a new connection with the same peer per needed protocol. |
| 65 | +
|
| 66 | +The stream multiplxers available are: |
| 67 | + |
| 68 | +- [libp2p/js-libp2p-mplex](https://github.com/libp2p/js-libp2p-mplex) |
| 69 | +- [libp2p/js-libp2p-spdy](https://github.com/libp2p/js-libp2p-spdy) (might get deprecated soon) |
| 70 | + |
| 71 | +If none of the available stream multiplexers fulfills your needs, you can create a libp2p compatible stream multiplexer. A libp2p multiplexer just needs to be compliant with the [interface-stream-muxer](https://github.com/libp2p/js-interfaces/tree/master/src/stream-muxer). |
| 72 | + |
| 73 | +If you want to get to know more about libp2p stream multiplexing, you should read the following content: |
| 74 | + |
| 75 | +- https://docs.libp2p.io/concepts/stream-multiplexing |
| 76 | +- https://github.com/libp2p/specs/tree/master/connections |
| 77 | +- https://github.com/libp2p/specs/tree/master/mplex |
| 78 | + |
| 79 | +### Connection Encryption |
| 80 | + |
| 81 | +> A connection encryption mechanism should be used, in order to ensure all exchanged data between two peers is encrypted. |
| 82 | +
|
| 83 | +The connection encryption protocols available are: |
| 84 | + |
| 85 | +- [libp2p/js-libp2p-secio](https://github.com/libp2p/js-libp2p-secio) |
| 86 | + |
| 87 | +If none of the available connection encryption mechanisms fulfills your needs, you can create a libp2p compatible one. A libp2p connection encryption protocol just needs to be compliant with the [interface-crypto](https://github.com/libp2p/js-interfaces/tree/master/src/crypto). |
| 88 | + |
| 89 | +If you want to get to know more about libp2p connection encryption, you should read the following content: |
| 90 | + |
| 91 | +- https://docs.libp2p.io/concepts/secure-comms |
| 92 | +- https://github.com/libp2p/specs/tree/master/connections |
| 93 | + |
| 94 | +### Peer Discovery |
| 95 | + |
| 96 | +> In a p2p network, peers must be able to discover other peers in the network. |
| 97 | +
|
| 98 | +The peer discovery modules available are: |
| 99 | + |
| 100 | +- [js-libp2p-mdns](https://github.com/libp2p/js-libp2p-mdns) |
| 101 | +- [js-libp2p-bootstrap](https://github.com/libp2p/js-libp2p-bootstrap) |
| 102 | +- [js-libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) |
| 103 | +- [js-libp2p-webrtc-star](https://github.com/libp2p/js-libp2p-webrtc-star) |
| 104 | +- [js-libp2p-websocket-star](https://github.com/libp2p/js-libp2p-websocket-star) (Work in Progress) |
| 105 | + |
| 106 | +If none of the available peer discovery protocols fulfills your needs, you can create a libp2p compatible one. A libp2p peer discovery protocol just needs to be compliant with the [interface-peer-discovery](https://github.com/libp2p/js-interfaces/tree/master/src/peer-discovery). |
| 107 | + |
| 108 | +If you want to get to know more about libp2p peer discovery, you should read the following content: |
| 109 | + |
| 110 | +- https://github.com/libp2p/specs/blob/master/discovery/mdns.md |
| 111 | + |
| 112 | +### Content Routing |
| 113 | + |
| 114 | +> Content routing provides a way to find where content lives in the network. It works in two steps: 1) Peers provide (announce) to the network that they are holders of specific content and 2) Peers issue queries to find where that content lives. A Content Routing mechanism could be as complex as a DHT or a simple registry somewhere in the network. |
| 115 | +
|
| 116 | +The content routing modules available are: |
| 117 | + |
| 118 | +- [js-libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) |
| 119 | +- [js-libp2p-delegated-peer-routing](https://github.com/libp2p/js-libp2p-delegated-peer-routing) |
| 120 | + |
| 121 | +If none of the available content routing protocols fulfills your needs, you can create a libp2p compatible one. A libp2p content routing protocol just needs to be compliant with the [interface-content-routing](https://github.com/libp2p/js-interfaces/tree/master/src/content-routing). **(WIP: This module is not yet implemented)** |
| 122 | + |
| 123 | +If you want to get to know more about libp2p content routing, you should read the following content: |
| 124 | + |
| 125 | +- https://docs.libp2p.io/concepts/content-routing |
| 126 | + |
| 127 | +### Peer Routing |
| 128 | + |
| 129 | +> Peer Routing offers a way to find other peers in the network by intentionally issuing queries, iterative or recursive, until a Peer is found or the closest Peers, given the Peer Routing algorithm strategy, are found. |
| 130 | +
|
| 131 | +The peer routing modules available are: |
| 132 | + |
| 133 | +- [js-libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht) |
| 134 | +- [js-libp2p-delegated-peer-routing](https://github.com/libp2p/js-libp2p-delegated-peer-routing) |
| 135 | + |
| 136 | +If none of the available content routing protocols fulfills your needs, you can create a libp2p compatible one. A libp2p content routing protocol just needs to be compliant with the [interface-peer-routing](https://github.com/libp2p/js-interfaces/tree/master/src/peer-routing). **(WIP: This module is not yet implemented)** |
| 137 | + |
| 138 | +If you want to get to know more about libp2p peer routing, you should read the following content: |
| 139 | + |
| 140 | +- https://docs.libp2p.io/concepts/peer-routing |
| 141 | + |
| 142 | +### DHT |
| 143 | + |
| 144 | +> A DHT can provide content and peer routing capabilities in a p2p system, as well as peer discovery capabilities. |
| 145 | +
|
| 146 | +The DHT implementation currently available is [libp2p/js-libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht). This implementation is largely based on the Kademlia whitepaper, augmented with notions from S/Kademlia, Coral and mainlineDHT. |
| 147 | + |
| 148 | +If this DHT implementation does not fulfill your needs, we recommend that you create a **Peer Routing** or **Content Routing** module, according to your needs. The reason behind this recommendation is that we aim to move the DHT implementation to the Peer Routing and Content Routing modules. |
| 149 | + |
| 150 | +If you want to get to know more about libp2p DHT, you should read the following content: |
| 151 | + |
| 152 | +- https://docs.libp2p.io/concepts/protocols/#kad-dht |
| 153 | +- https://github.com/libp2p/specs/pull/108 |
| 154 | + |
| 155 | +#### Pubsub |
| 156 | + |
| 157 | +> Publish/Subscribe is a system where peers congregate around topics they are interested in. Peers interested in a topic are said to be subscribed to that topic and should receive the data published on it from other peers. |
| 158 | +
|
| 159 | +The pubsub routers available are: |
| 160 | + |
| 161 | +- [libp2p/js-libp2p-floodsub](https://github.com/libp2p/js-libp2p-floodsub) |
| 162 | +- [ChainSafe/gossipsub-js](https://github.com/ChainSafe/gossipsub-js) |
| 163 | + |
| 164 | +If none of the available pubsub routers fulfills your needs, you can create a libp2p compatible one. A libp2p pubsub router just needs to be created on top of [libp2p/js-libp2p-pubsub](https://github.com/libp2p/js-libp2p-pubsub), which ensures `js-libp2p` API expectations. |
| 165 | + |
| 166 | +If you want to get to know more about libp2p pubsub, you should read the following content: |
| 167 | + |
| 168 | +- https://docs.libp2p.io/concepts/publish-subscribe |
| 169 | +- https://github.com/libp2p/specs/tree/master/pubsub |
| 170 | + |
| 171 | +## Libp2p node |
| 172 | + |
| 173 | +When [creating a libp2p node](./API.md#create), the modules needed should be specified in the following way: |
| 174 | + |
| 175 | +```js |
| 176 | +const modules = { |
| 177 | + transport: [], |
| 178 | + streamMuxer: [], |
| 179 | + connEncryption: [], |
| 180 | + contentRouting: [], |
| 181 | + peerRouting: [], |
| 182 | + peerDiscovery: [], |
| 183 | + dht: dhtImplementation, |
| 184 | + pubsub: pubsubImplementation |
| 185 | +} |
| 186 | +``` |
| 187 | + |
| 188 | +Moreover, the majority of the modules can be customized via option parameters. This way, it is also possible to provide this options through a config object. This config object should have the property name of each building block to configure, the same way as the modules specification. |
| 189 | + |
| 190 | +**Example:** |
| 191 | + |
| 192 | +```js |
| 193 | +// Creating a libp2p node with: |
| 194 | +// transport: websockets + tcp |
| 195 | +// stream-muxing: mplex |
| 196 | +// crypto-channel: secio |
| 197 | +// discovery: multicast-dns |
| 198 | +// dht: kad-dht |
| 199 | +// pubsub: gossipsub |
| 200 | + |
| 201 | +const Libp2p = require('libp2p') |
| 202 | +const TCP = require('libp2p-tcp') |
| 203 | +const WS = require('libp2p-websockets') |
| 204 | +const MPLEX = require('libp2p-mplex') |
| 205 | +const SECIO = require('libp2p-secio') |
| 206 | +const MulticastDNS = require('libp2p-mdns') |
| 207 | +const DHT = require('libp2p-kad-dht') |
| 208 | +const GossipSub = require('libp2p-gossipsub') |
| 209 | +const DelegatedPeerRouter = require('libp2p-delegated-peer-routing') |
| 210 | +const DelegatedContentRouter = require('libp2p-delegated-content-routing') |
| 211 | + |
| 212 | +const node = await Libp2p.create({ |
| 213 | + modules: { |
| 214 | + transport: [ |
| 215 | + TCP, |
| 216 | + new WS() // It can take instances too! |
| 217 | + ], |
| 218 | + streamMuxer: [ |
| 219 | + MPLEX |
| 220 | + ], |
| 221 | + connEncryption: [ |
| 222 | + SECIO |
| 223 | + ], |
| 224 | + // contentRouting: [ |
| 225 | + // new DelegatedContentRouter(peerId) |
| 226 | + // ], |
| 227 | + // peerRouting: [ |
| 228 | + // new DelegatedPeerRouter() |
| 229 | + // ], |
| 230 | + peerDiscovery: [ |
| 231 | + MulticastDNS |
| 232 | + ], |
| 233 | + dht: DHT, |
| 234 | + pubsub: GossipSub |
| 235 | + }, |
| 236 | + config: { |
| 237 | + peerDiscovery: { |
| 238 | + autoDial: true, // Auto connect to discovered peers (limited by ConnectionManager minPeers) |
| 239 | + mdns: { // mdns options |
| 240 | + interval: 1000, // ms |
| 241 | + enabled: true |
| 242 | + } |
| 243 | + // .. other discovery module options. |
| 244 | + }, |
| 245 | + // relay: { // Circuit Relay options (this config is part of libp2p core configurations) |
| 246 | + // enabled: true, |
| 247 | + // hop: { |
| 248 | + // enabled: false, |
| 249 | + // active: false |
| 250 | + // } |
| 251 | + // }, |
| 252 | + dht: { |
| 253 | + kBucketSize: 20, |
| 254 | + enabled: true, |
| 255 | + randomWalk: { |
| 256 | + enabled: true, // Allows to disable discovery (enabled by default) |
| 257 | + interval: 300e3, |
| 258 | + timeout: 10e3 |
| 259 | + } |
| 260 | + }, |
| 261 | + pubsub: { |
| 262 | + enabled: true, |
| 263 | + emitSelf: true, // whether the node should emit to self on publish, in the event of the topic being subscribed |
| 264 | + signMessages: true, // if messages should be signed |
| 265 | + strictSigning: true // if message signing should be required |
| 266 | + } |
| 267 | + } |
| 268 | +}) |
| 269 | +``` |
| 270 | + |
| 271 | +Besides the `modules` and `config`, libp2p allows other internal options and configurations: |
| 272 | + |
| 273 | +- `datastore`: an instance of [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore/) modules. |
| 274 | + - This is used in modules such as the DHT. If it is not provided, `js-libp2p` will use an in memory datastore. |
| 275 | +- `peerInfo`: a previously created instance of [libp2p/js-peer-info](https://github.com/libp2p/js-peer-info). |
| 276 | + - This is particularly useful if you want to reuse the same `peer-id`, as well as for modules like `libp2p-delegated-content-routing`, which need a `peer-id` in their instantiation. |
| 277 | + |
| 278 | +## Configuration examples |
| 279 | + |
| 280 | +With libp2p modular nature, libp2p can be found being used in different projects, with completelly different requirements and runtime environments. As a consequence, we recommend creating your own libp2p configuration according to the needs of the system you are developing. |
| 281 | + |
| 282 | +Here follows a list of configurations being used for `js-libp2p` in other projects: |
| 283 | + |
| 284 | +- [libp2p-ipfs-nodejs](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/libp2p-nodejs.js) - libp2p configuration used by js-ipfs when running in Node.js |
| 285 | +- [libp2p-ipfs-browser](https://github.com/ipfs/js-ipfs/tree/master/src/core/runtime/libp2p-browser.js) - libp2p configuration used by js-ipfs when running in a Browser (that supports WebRTC) |
| 286 | + |
| 287 | +If you have developed a project using `js-libp2p`, please consider submitting it to this list so that it can be found easily by the users of libp2p. |
| 288 | + |
| 289 | +The `js-libp2p` examples and tests directories are also a good source of help for finding the configurations that suit your needs. |
0 commit comments