Skip to content

Commit 669a812

Browse files
vasco-santosvasco-santos
committed
chore: decouple examples
1 parent 8061f95 commit 669a812

File tree

1 file changed

+150
-53
lines changed

1 file changed

+150
-53
lines changed

‎doc/CONFIGURATION.md

Lines changed: 150 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,19 @@
1010
* [Peer Routing](#peer-routing)
1111
* [DHT](#dht)
1212
* [Pubsub](#pubsub)
13-
* [Libp2p node](#libp2p-node)
13+
* [Customizing Libp2p](#customizing-libp2p)
14+
* [Examples](#examples)
1415
* [Configuration examples](#configuration-examples)
1516

1617
## Overview
1718

1819
libp2p is a modular networking stack. It's designed to be able to suit a variety of project needs. The configuration of libp2p is a key part of its structure. It enables you to bring exactly what you need, and only what you need. This document is a guide on how to configure libp2p for your particular project. Check out the [Configuration examples](#configuration-examples) section if you're just looking to leverage an existing configuration.
1920

20-
`js-libp2p` acts as the composer for this modular p2p networking stack using libp2p compatible modules as its building blocks.
2121
Regardless of how you configure libp2p, the top level [API](./API.md) will always remain the same. **Note**: if some modules are not configured, like Content Routing, using those methods will throw errors.
2222

2323
## Modules
2424

25-
For getting an instance of `js-libp2p` compliant with all types of networking requirements, it is possible to specify the following building blocks:
25+
`js-libp2p` acts as the composer for this modular p2p networking stack using libp2p compatible modules as its subsystems. For getting an instance of `js-libp2p` compliant with all types of networking requirements, it is possible to specify the following subsystems:
2626

2727
- Transports
2828
- Multiplexers
@@ -33,11 +33,11 @@ For getting an instance of `js-libp2p` compliant with all types of networking re
3333
- DHT implementation
3434
- Pubsub router
3535

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.
36+
The libp2p ecosystem contains at least one module for each of these subsystems. 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.
3737

3838
After selecting the modules to use, it is also possible to configure each one according to your needs.
3939

40-
Bear in mind that only a **transport** is required, being all the other building blocks optional.
40+
Bear in mind that only a **transport** is required, being all the other subsystems optional.
4141

4242
### Transport
4343

@@ -62,7 +62,7 @@ If you want to know more about libp2p transports, you should read the following
6262

6363
> 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.
6464
65-
The stream multiplxers available are:
65+
Some available stream multiplxers are:
6666

6767
- [libp2p/js-libp2p-mplex](https://github.com/libp2p/js-libp2p-mplex)
6868

@@ -78,7 +78,7 @@ If you want to know more about libp2p stream multiplexing, you should read the f
7878

7979
> A connection encryption mechanism should be used, in order to ensure all exchanged data between two peers is encrypted.
8080
81-
The connection encryption protocols available are:
81+
Some available connection encryption protocols:
8282

8383
- [libp2p/js-libp2p-secio](https://github.com/libp2p/js-libp2p-secio)
8484

@@ -93,7 +93,7 @@ If you want to know more about libp2p connection encryption, you should read the
9393

9494
> In a p2p network, peer discovery is critical to a functioning system.
9595
96-
The peer discovery modules available are:
96+
Some available peer discovery modules are:
9797

9898
- [js-libp2p-mdns](https://github.com/libp2p/js-libp2p-mdns)
9999
- [js-libp2p-bootstrap](https://github.com/libp2p/js-libp2p-bootstrap)
@@ -110,7 +110,7 @@ If you want to know more about libp2p peer discovery, you should read the follow
110110

111111
> 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 as simple as a registry somewhere in the network.
112112
113-
The content routing modules available are:
113+
Some available content routing modules are:
114114

115115
- [js-libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht)
116116
- [js-libp2p-delegated-peer-routing](https://github.com/libp2p/js-libp2p-delegated-peer-routing)
@@ -125,7 +125,7 @@ If you want to know more about libp2p content routing, you should read the follo
125125

126126
> Peer Routing offers a way to find other peers in the network by issuing queries using a Peer Routing algorithm, which may be iterative or recursive. If the algorithm is unable to find the target peer, it will return the peers that are "closest" to the target peer, using a distance metric defined by the algorithm.
127127
128-
The peer routing modules available are:
128+
Some available peer routing modules are:
129129

130130
- [js-libp2p-kad-dht](https://github.com/libp2p/js-libp2p-kad-dht)
131131
- [js-libp2p-delegated-peer-routing](https://github.com/libp2p/js-libp2p-delegated-peer-routing)
@@ -142,7 +142,7 @@ If you want to know more about libp2p peer routing, you should read the followin
142142
143143
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.
144144

145-
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.
145+
If this DHT implementation does not fulfill your needs and you want to create or use your own implementation, please get in touch with us through a github issue. We plan to work on improving the ability to bring your own DHT in a future release.
146146

147147
If you want to know more about libp2p DHT, you should read the following content:
148148

@@ -153,7 +153,7 @@ If you want to know more about libp2p DHT, you should read the following content
153153

154154
> 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.
155155
156-
The pubsub routers available are:
156+
Some available pubsub routers are:
157157

158158
- [libp2p/js-libp2p-floodsub](https://github.com/libp2p/js-libp2p-floodsub)
159159
- [ChainSafe/gossipsub-js](https://github.com/ChainSafe/gossipsub-js)
@@ -182,9 +182,17 @@ const modules = {
182182
}
183183
```
184184

185-
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.
185+
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.
186186

187-
**Example:**
187+
Besides the `modules` and `config`, libp2p allows other internal options and configurations:
188+
- `datastore`: an instance of [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore/) modules.
189+
- This is used in modules such as the DHT. If it is not provided, `js-libp2p` will use an in memory datastore.
190+
- `peerInfo`: a previously created instance of [libp2p/js-peer-info](https://github.com/libp2p/js-peer-info).
191+
- 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.
192+
193+
### Examples
194+
195+
**1) Basic setup**
188196

189197
```js
190198
// Creating a libp2p node with:
@@ -203,74 +211,163 @@ const SECIO = require('libp2p-secio')
203211
const MulticastDNS = require('libp2p-mdns')
204212
const DHT = require('libp2p-kad-dht')
205213
const GossipSub = require('libp2p-gossipsub')
206-
const DelegatedPeerRouter = require('libp2p-delegated-peer-routing')
207-
const DelegatedContentRouter = require('libp2p-delegated-content-routing')
208214

209215
const node = await Libp2p.create({
210216
modules: {
211217
transport: [
212218
TCP,
213219
new WS() // It can take instances too!
214220
],
215-
streamMuxer: [
216-
MPLEX
217-
],
218-
connEncryption: [
219-
SECIO
220-
],
221-
// contentRouting: [
222-
// new DelegatedContentRouter(peerId)
223-
// ],
224-
// peerRouting: [
225-
// new DelegatedPeerRouter()
226-
// ],
227-
peerDiscovery: [
228-
MulticastDNS
229-
],
221+
streamMuxer: [MPLEX],
222+
connEncryption: [SECIO],
223+
peerDiscovery: [MulticastDNS],
230224
dht: DHT,
231225
pubsub: GossipSub
226+
}
227+
})
228+
```
229+
230+
**2) Customizing Peer Discovery**
231+
232+
```js
233+
const Libp2p = require('libp2p')
234+
const TCP = require('libp2p-tcp')
235+
const MPLEX = require('libp2p-mplex')
236+
const SECIO = require('libp2p-secio')
237+
const MulticastDNS = require('libp2p-mdns')
238+
239+
const node = await Libp2p.create({
240+
modules: {
241+
transport: [TCP],
242+
streamMuxer: [MPLEX],
243+
connEncryption: [SECIO],
244+
peerDiscovery: [MulticastDNS]
232245
},
233246
config: {
234247
peerDiscovery: {
235248
autoDial: true, // Auto connect to discovered peers (limited by ConnectionManager minPeers)
236-
mdns: { // mdns options
237-
interval: 1000, // ms
249+
// The `tag` property will be searched when creating the instance of your Peer Discovery service.
250+
// The associated object, will be passed to the service when it is instantiated.
251+
[MulticastDNS.tag]: {
252+
interval: 1000,
238253
enabled: true
239254
}
240255
// .. other discovery module options.
241-
},
242-
// relay: { // Circuit Relay options (this config is part of libp2p core configurations)
243-
// enabled: true,
244-
// hop: {
245-
// enabled: false,
246-
// active: false
247-
// }
248-
// },
249-
dht: {
256+
}
257+
}
258+
})
259+
```
260+
261+
**3) Customizing Pubsub**
262+
263+
```js
264+
const Libp2p = require('libp2p')
265+
const TCP = require('libp2p-tcp')
266+
const MPLEX = require('libp2p-mplex')
267+
const SECIO = require('libp2p-secio')
268+
const GossipSub = require('libp2p-gossipsub')
269+
270+
const node = await Libp2p.create({
271+
modules: {
272+
transport: [TCP],
273+
streamMuxer: [MPLEX],
274+
connEncryption: [SECIO],
275+
pubsub: GossipSub
276+
},
277+
config: {
278+
pubsub: { // The pubsub options (and defaults) can be found in the pubsub router documentation
279+
enabled: true,
280+
emitSelf: true, // whether the node should emit to self on publish
281+
signMessages: true, // if messages should be signed
282+
strictSigning: true // if message signing should be required
283+
}
284+
}
285+
})
286+
```
287+
288+
**4) Customizing DHT**
289+
290+
```js
291+
const Libp2p = require('libp2p')
292+
const TCP = require('libp2p-tcp')
293+
const MPLEX = require('libp2p-mplex')
294+
const SECIO = require('libp2p-secio')
295+
const DHT = require('libp2p-kad-dht')
296+
297+
const node = await Libp2p.create({
298+
modules: {
299+
transport: [TCP],
300+
streamMuxer: [MPLEX],
301+
connEncryption: [SECIO],
302+
dht: DHT
303+
},
304+
config: {
305+
dht: { // The DHT options (and defaults) can be found in its documentation
250306
kBucketSize: 20,
251307
enabled: true,
252308
randomWalk: {
253309
enabled: true, // Allows to disable discovery (enabled by default)
254310
interval: 300e3,
255311
timeout: 10e3
256312
}
257-
},
258-
pubsub: {
259-
enabled: true,
260-
emitSelf: true, // whether the node should emit to self on publish, in the event of the topic being subscribed
261-
signMessages: true, // if messages should be signed
262-
strictSigning: true // if message signing should be required
263313
}
264314
}
265315
})
266316
```
267317

268-
Besides the `modules` and `config`, libp2p allows other internal options and configurations:
318+
**5) Setup with Content and Peer Routing**
269319

270-
- `datastore`: an instance of [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore/) modules.
271-
- This is used in modules such as the DHT. If it is not provided, `js-libp2p` will use an in memory datastore.
272-
- `peerInfo`: a previously created instance of [libp2p/js-peer-info](https://github.com/libp2p/js-peer-info).
273-
- 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.
320+
```js
321+
const Libp2p = require('libp2p')
322+
const TCP = require('libp2p-tcp')
323+
const MPLEX = require('libp2p-mplex')
324+
const SECIO = require('libp2p-secio')
325+
const DelegatedPeerRouter = require('libp2p-delegated-peer-routing')
326+
const DelegatedContentRouter = require('libp2p-delegated-content-routing')
327+
const PeerInfo = require('peer-info')
328+
329+
// create a peerInfo
330+
const peerInfo = await PeerInfo.create()
331+
332+
const node = await Libp2p.create({
333+
modules: {
334+
transport: [TCP],
335+
streamMuxer: [MPLEX],
336+
connEncryption: [SECIO],
337+
contentRouting: [
338+
new DelegatedContentRouter(peerInfo.id)
339+
],
340+
peerRouting: [
341+
new DelegatedPeerRouter()
342+
],
343+
},
344+
peerInfo
345+
})
346+
```
347+
348+
**6) Setup with Relay**
349+
350+
```js
351+
const Libp2p = require('libp2p')
352+
const TCP = require('libp2p-tcp')
353+
const MPLEX = require('libp2p-mplex')
354+
const SECIO = require('libp2p-secio')
355+
356+
const node = await Libp2p.create({
357+
modules: {
358+
transport: [TCP],
359+
streamMuxer: [MPLEX],
360+
connEncryption: [SECIO]
361+
},
362+
relay: { // Circuit Relay options (this config is part of libp2p core configurations)
363+
enabled: true,
364+
hop: {
365+
enabled: true,
366+
active: true
367+
}
368+
},
369+
})
370+
```
274371

275372
## Configuration examples
276373

0 commit comments

Comments
 (0)