libp2p 0.26.0 | Documentation

libp2p

0.26.0

Intro
Libp2p ▸
- Instance members
- #emit
- #start
- #stop
- #dial
- #dialProtocol
- #dialFSM
- #hangUp
- #ping
createLibp2p
findPeer
findProviders
provide
subscribe
unsubscribe

Intro

Installable via npm install --save libp2p, it can also be used directly in the browser.

Download

The source is available for download from GitHub. Alternatively, you can install using npm:

$ npm install --save libp2p

You can then require() libp2p as normal:

const libp2P = require('libp2p')

In the Browser

Libp2p should work in any ES2015 environment out of the box.

Usage:

<script type="text/javascript" src="index.js"></script>

The portable versions of libp2p, including index.js and index.min.js, are included in the /dist folder. Libp2p can also be found on unpkg.com under

Libp2p

src/index.js

new Libp2p(_options: any)

Extends EventEmitter

Parameters

_options (any)

Instance Members

▸ emit(eventName, args)

src/index.js

Overrides EventEmitter.emit to conditionally emit errors if there is a handler. If not, errors will be logged.

emit(eventName: string, args: ...any): void

Parameters

eventName (string)

args (...any)

Returns

void:

▸ start(callback)

src/index.js

Starts the libp2p node and all sub services

start(callback: function (Error)): void

Parameters

callback

(function (Error)
            = ()=>{})

Returns

void:

▸ stop(callback)

src/index.js

Stop the libp2p node by closing its listeners and open connections

stop(callback: function (Error)): void

Parameters

callback

(function (Error)
            = ()=>{})

Returns

void:

▸ dial(peer, callback)

src/index.js

Dials to the provided peer. If successful, the PeerInfo of the peer will be added to the nodes PeerBook

dial(peer: (PeerInfo | PeerId | Multiaddr | string), callback: function (Error)): void

Parameters

peer ((PeerInfo | PeerId | Multiaddr | string)) The peer to dial

callback (function (Error))

Returns

void:

▸ dialProtocol(peer, protocol, callback)

src/index.js

Dials to the provided peer and handshakes with the given protocol. If successful, the PeerInfo of the peer will be added to the nodes PeerBook, and the Connection will be sent in the callback

dialProtocol(peer: (PeerInfo | PeerId | Multiaddr | string), protocol: string, callback: function (Error, Connection)): void

Parameters

peer ((PeerInfo | PeerId | Multiaddr | string)) The peer to dial

protocol (string)

callback (function (Error, Connection))

Returns

void:

▸ dialFSM(peer, protocol, callback)

src/index.js

Similar to dial and dialProtocol, but the callback will contain a Connection State Machine.

dialFSM(peer: (PeerInfo | PeerId | Multiaddr | string), protocol: string, callback: function (Error, ConnectionFSM)): void

Parameters

peer ((PeerInfo | PeerId | Multiaddr | string)) The peer to dial

protocol (string)

callback (function (Error, ConnectionFSM))

Returns

void:

▸ hangUp(peer, callback)

src/index.js

Disconnects from the given peer

hangUp(peer: (PeerInfo | PeerId | Multiaddr | string), callback: function (Error)): void

Parameters

peer ((PeerInfo | PeerId | Multiaddr | string)) The peer to ping

callback (function (Error))

Returns

void:

▸ ping(peer, callback)

src/index.js

Pings the provided peer

ping(peer: (PeerInfo | PeerId | Multiaddr | string), callback: function (Error, Ping)): void

Parameters

peer ((PeerInfo | PeerId | Multiaddr | string)) The peer to ping

callback (function (Error, Ping))

Returns

void:

createLibp2p

src/index.js

Like new Libp2p(options) except it will create a PeerInfo instance if one is not provided in options.

createLibp2p

Parameters

options (object) Libp2p configuration options

callback (function (Error, Libp2p))

Returns

void:

findPeer

src/peer-routing.js

Iterates over all peer routers in series to find the given peer.

findPeer

Parameters

id (String) The id of the peer to find

options (object)

Name	Description
options.maxTimeout `number`	How long the query should run

callback (function (Error, Result<Array>))

Returns

void:

findProviders

src/content-routing.js

Iterates over all content routers in series to find providers of the given key. Once a content router succeeds, iteration will stop.

findProviders

Parameters

key (CID) The CID key of the content to find

options (object)

Name	Description
options.maxTimeout `number`	How long the query should run
options.maxNumProviders `number`	maximum number of providers to find

callback (function (Error, Result<Array>))

Returns

void:

provide

src/content-routing.js

Iterates over all content routers in parallel to notify it is a provider of the given key.

provide

Parameters

key (CID) The CID key of the content to find

callback (function (Error))

Returns

void:

src/pubsub.js

Subscribe the given handler to a pubsub topic

Parameters

topic (string)

handler (function) The handler to subscribe

options ((object | null)?)

callback (function?) An optional callback

Returns

(Promise | void): A promise is returned if no callback is provided

Example

Subscribe a handler to a topic

// `null` must be passed for options until subscribe is no longer using promisify
const handler = (message) => { }
await libp2p.subscribe(topic, handler, null)

Use a callback instead of the Promise api

// `options` may be passed or omitted when supplying a callback
const handler = (message) => { }
libp2p.subscribe(topic, handler, callback)

unsubscribe

src/pubsub.js

Unsubscribes from a pubsub topic

unsubscribe

Parameters

topic (string)

handler ((function | null)) The handler to unsubscribe from

callback (function?) An optional callback

Returns

(Promise | void): A promise is returned if no callback is provided

Example

Unsubscribe a topic for all handlers

// `null` must be passed until unsubscribe is no longer using promisify
await libp2p.unsubscribe(topic, null)

Unsubscribe a topic for 1 handler

await libp2p.unsubscribe(topic, handler)

Use a callback instead of the Promise api

libp2p.unsubscribe(topic, handler, callback)