0.26.2Installable via npm install --save libp2p, it can also be used directly in the browser.
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')
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
Extends EventEmitter
(any)
Dials to the provided peer. If successful, the PeerInfo of the
peer will be added to the nodes PeerBook
void:
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
((PeerInfo | PeerId | Multiaddr | string))
The peer to dial
(string)
(function (Error, Connection))
void:
Similar to dial and dialProtocol, but the callback will contain a
Connection State Machine.
((PeerInfo | PeerId | Multiaddr | string))
The peer to dial
(string)
(function (Error, ConnectionFSM))
void:
Disconnects from the given peer
void:
Like new Libp2p(options) except it will create a PeerInfo
instance if one is not provided in options.
void:
Extends EventEmitter
(any)
(any)
(any)
Adds the handlerFunc and matchFunc to the Switch's protocol
handler list for the given protocol. If the matchFunc returns
true for a protocol check, the handlerFunc will be called.
void:
If a muxed Connection exists for the given peer, it will be closed and its reference on the Switch will be removed.
((PeerInfo | Multiaddr | PeerId))
(function ())
void:
Issues a start on the Switch state.
void:
Creates an instance of Dialer.
(Swarm)
the swarm
(any)
config options
Dial the relays in the Addresses.Swarm config
(Array)
void:
Dial a peer over a relay
(multiaddr)
the multiaddr of the peer to dial
(Object)
dial options
(Function)
a callback called once dialed
Connection:
the connection
Create a listener
(any)
(Function)
listener:
Filter check for all multiaddresses that this transport can dial on
(any)
Array<multiaddr>:
Creates an instance of Dialer.
(Swarm)
the swarm
(any)
config options
Helper that returns a relay connection
(any)
(any)
Function:
callback
Dial a peer over a relay
(multiaddr)
the multiaddr of the peer to dial
(Function)
a callback called once dialed
Connection:
the connection
Does the peer support the HOP protocol
(PeerInfo)
(Function)
void:
Create a stream handler for connection
Read and decode message
(Function)
(void | Function):
Encode and write array of buffers
Function:
Get the raw Connection
(null | Connection | any):
Return the handshake rest stream and invalidate handler
(any | {source, sink}):
Close the stream
undefined:
Get b58 string from multiaddr or peerinfo
((Multiaddr | PeerInfo))
any:
Checks if peer has an existing connection
(String)
(Swarm)
Boolean:
Write a response
any:
Validate incomming HOP/STOP message
any:
Add swarm handler and listen for incoming connections
(Multiaddr)
(Function)
void:
Remove swarm listener
(Function)
void:
Get fixed up multiaddrs
NOTE: This method will grab the peers multiaddrs and expand them such that:
a) If it's an existing /p2p-circuit address for a specific relay i.e.
/ip4/0.0.0.0/tcp/0/ipfs/QmRelay/p2p-circuit this method will expand the
address to /ip4/0.0.0.0/tcp/0/ipfs/QmRelay/p2p-circuit/ipfs/QmPeer where
QmPeer is this peers id
b) If it's not a /p2p-circuit address, it will encapsulate the address as a /p2p-circuit
addr, such when dialing over a relay with this address, it will create the circuit using
the encapsulated transport address. This is useful when for example, a peer should only
be dialed over TCP rather than any other transport
(Function)
void:
Handle the incoming STOP message
({})
the parsed protobuf message
(StreamHandler)
the stream handler wrapped connection
(Function)
callback
undefined:
Construct a Circuit object
This class will handle incoming circuit connections and either start a relay or hand the relayed connection to the swarm
(Swarm)
(Object)
Handle the relay message
(CircuitRelay)
(StreamHandler)
any:
Connect to STOP
void:
Negotiate STOP
void:
Manages the transports for the switch. This simplifies dialing and listening across multiple transports.
(any)
Closes connections for the given transport key and removes it from the switch.
void:
For a given transport key, dial to all that transport multiaddrs
void:
For a given Transport key, listen on all multiaddrs in the switch's _peerInfo.
If a handler is not provided, the Switch's protocolMuxer will be used.
(String)
(any)
Currently ignored
(function (Connection))
(function (Error))
void:
Expand addresses in peer info into array of addresses with and without peer ID suffix.
(PeerInfo)
Our peer info object
Array<String>:
Get the destination address of a (possibly relay) multiaddr as a string
(Multiaddr)
String:
Track dials per peer and limited them.
Dial a list of multiaddrs on the given transport.
(PeerId)
(SwarmTransport)
(Array<Multiaddr>)
(function (Error, Connection))
void:
Dial a single multiaddr on the given transport.
(PeerId)
(SwarmTransport)
(Multiaddr)
(CancelToken)
(function (Error, Connection))
void:
Queue up the amount of dials to a given peer.
For a given multistream, registers to handle the given connection
(MultistreamDialer)
(Connection)
Promise:
For a given multistream, selects the given protocol
(MultistreamDialer)
(string)
Promise:
Resolves the selected Connection
Runs identify for the given connection and verifies it against the PeerInfo provided
(Connection)
(PeerInfo)
The PeerInfo determined during crypto exchange
Promise:
Resolves {peerInfo, observedAddrs}
Get unique values from arr using getValue to determine
what is used for uniqueness
(Array)
The array to get unique values for
(function (value))
The function to determine what is compared
Array:
Contains methods for binding handlers to the Switch in order to better manage its connections.
(any)
Adds a listener for the given muxer and creates a handler for it
leveraging the Switch.protocolMuxer handler factory
(Muxer)
void:
If config.enabled is true, a Circuit relay will be added to the available Switch transports.
(any)
void:
Sets identify to true on the Switch and performs handshakes for libp2p-identify leveraging the Switch's muxer.
void:
Type: Object
ConnectionFSM handles the complex logic of managing a connection between peers. ConnectionFSM is internally composed of a state machine to help improve the usability and debuggability of connections. The state machine also helps to improve the ability to handle dial backoff, coalescing dials and dial locks.
Extends BaseConnection
(ConnectionOptions)
| Name | Description |
|---|---|
connectionOptions._switch any
|
|
connectionOptions.peerInfo any
|
|
connectionOptions.muxer any
|
|
connectionOptions.conn any
|
|
connectionOptions.type any
(default 'out')
|
Puts the state into dialing mode
void:
Initiates a handshake for the given protocol
void:
Puts the state into muxing mode
void:
Once a connection has been successfully dialed, the connection will be privatized or encrypted depending on the presence of the Switch.protector.
void:
Event handler for disconnecting. Handles any needed cleanup
void:
(DialRequest)
| Name | Description |
|---|---|
dialRequest.peerInfo any
|
|
dialRequest.protocol any
|
|
dialRequest.options any
|
|
dialRequest.callback any
|
void:
Starts the DialQueueManager
(function)
Aborts all dials that are queued. This should only be used when the Switch is being stopped
(function)
Clears the denylist for a given peer
(PeerInfo)
Attempts to establish a connection to the given peerInfo at
a lower priority than a standard dial.
Adds the dial request to the queue for the given peerInfo
The request will be added with a high priority (10).
Behaves like dial, except it calls back with a ConnectionFSM
(Switch)
Allows the DialQueueManager to execute dials
Iterates over all items in the DialerQueue and executes there callback with an error.
This causes the entire DialerQueue to be drained
Adds the dialRequest to the queue and ensures queue is running
(DialRequest)
| Name | Description |
|---|---|
dialRequest.peerInfo any
|
|
dialRequest.protocol any
|
|
dialRequest.options any
|
|
dialRequest.callback any
|
void:
Will execute up to MAX_PARALLEL_DIALS dials
Will remove the peerInfo from the dial denylist
(PeerInfo)
Returns the Queue for the given peerInfo
(PeerInfo)
Queue:
Components required to execute a dial
Type: Object
Type: Object
(ConnectionFSM)
(boolean)
Attempts to create a new connection or stream (when muxed),
via negotiation of the given protocol. If no protocol is
provided, no action will be taken and callback will be called
immediately with no error or values.
(object)
| Name | Description |
|---|---|
options.protocol string
|
|
options.connection ConnectionFSM
|
|
options.callback function (Error, Connection)
|
void:
A convenience array wrapper for controlling a per peer queue
Queue:
Stops the queue
Stops the queue and errors the callback for each dial request
Marks the queue as denylisted. The queue will be immediately aborted.
void:
Takes a transport key and returns a connection handler function
(string)
The key of the transport to handle connections for
(function)
A custom handler to use
function (Connection):
A connection handler function
Takes a base connection and manages listening behavior
(Connection)
The connection to manage
void:
Puts the state into its disconnecting flow
(Error)
Will be emitted if provided
void:
Gets the current state of the connection
string:
The current state of the connection
Puts the state into encrypting mode
void:
Puts the state into privatizing mode
void:
Puts the state into muxing mode
void:
Event handler for disconnected.
void:
Event handler for privatized
void:
Creates a pull stream to run the given Connection stream through the given Observer. This provides a way to more easily monitor connections and their metadata. A new Connection will be returned that contains has the attached Observer.
Connection:
An encryption stub in the instance that the default crypto has not been overriden for the Switch
Takes a Switch and returns an Observer that can be used in conjunction with
observe-connection.js. The returned Observer comes with incoming and
outgoing properties that can be used in pull streams to emit all metadata
for messages that pass through a Connection.
(Switch)
EventEmitter:
Binds to message events on the given observer to generate stats
based on the Peer, Protocol and Transport used for the message. Stat
events will be emitted via the update event.
(Observer)
(any)
Stats:
A queue based manager for stat processing
Extends EventEmitter
Initializes the internal timer if there are items in the queue. This
should only need to be called if Stats.stop was previously called, as
Stats.push will also start the processing.
void:
Stops processing and computing of stats by clearing the internal timer.
void:
Creates and returns a Least Recently Used Cache
(Number)
LRUCache:
Iterates over all peer routers in series to find the given peer.
(String)
The id of the peer to find
void:
Iterates over all content routers in series to find providers of the given key. Once a content router succeeds, iteration will stop.
(CID)
The CID key of the content to find
void:
Iterates over all content routers in parallel to notify it is a provider of the given key.
(CID)
The CID key of the content to find
(function (Error))
void:
Subscribe the given handler to a pubsub topic
(string)
(function)
The handler to subscribe
((object | null)?)
(function?)
An optional callback
(Promise | void):
A promise is returned if no callback is provided
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)
Unsubscribes from a pubsub topic
(string)
((function | null))
The handler to unsubscribe from
(function?)
An optional callback
(Promise | void):
A promise is returned if no callback is provided
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)
Converts the given peer to a PeerInfo instance.
The PeerBook will be checked for the resulting peer, and
the peer will be updated in the PeerBook.
((PeerInfo | PeerId | Multiaddr | string))
(PeerBook)
PeerInfo:
If getPeerInfo does not return a peer with multiaddrs,
the libp2p PeerRouter will be used to attempt to find the peer.
Promise<PeerInfo>: