| [options.datastore] | `Object` | must implement [ipfs/interface-datastore](https://github.com/ipfs/interface-datastore) (in memory datastore will be used if not provided) |
| [options.peerInfo] | [PeerInfo](https://github.com/libp2p/js-peer-info) | peerInfo instance (it will be created if not provided) |
For Libp2p configurations and modules details read the [Configuration Document](./CONFIGURATION.md).
#### Returns
| Type | Description |
|------|-------------|
| `Promise<Libp2p>` | Promise resolves with the Libp2p instance |
#### Example
```js
const Libp2p = require('libp2p')
// specify options
const options = {}
// create libp2p
const libp2p = await Libp2p.create(options)
```
Note: The `PeerInfo` option is not required and will be generated if it is not provided.
<details><summary>Alternative</summary>
As an alternative, it is possible to create a Libp2p instance with the constructor:
#### Example
```js
const Libp2p = require('libp2p')
// specify options
const options = {}
// create libp2p
const libp2p = new Libp2p(options)
```
Required keys in the `options` object:
-`peerInfo`: instance of [PeerInfo][] that contains the [PeerId][], Keys and [multiaddrs][multiaddr] of the libp2p Node (optional when using `.create`).
-`modules.transport`: An array that must include at least 1 compliant transport. See [modules that implement the transport interface](https://github.com/libp2p/js-interfaces/tree/master/src/transport#modules-that-implement-the-interface).
</details>
Once you have a libp2p instance, you are able to listen to several events it emmits, so that you can be noticed of relevant network events.
<details><summary>Events</summary>
#### An error has occurred
`libp2p.on('error', (err) => {})`
-`err`: instance of `Error`
#### A peer has been discovered
`libp2p.on('peer:discovery', (peer) => {})`
If `autoDial` option is `true`, applications should **not** attempt to connect to the peer
unless they are performing a specific action. See [peer discovery and auto dial](./PEER_DISCOVERY.md) for more information.
-`peer`: instance of [PeerInfo][https://github.com/libp2p/js-peer-info]
#### We have a new connection to a peer
`libp2p.on('peer:connect', (peer) => {})`
-`peer`: instance of [PeerInfo][https://github.com/libp2p/js-peer-info]
#### We have closed a connection to a peer
`libp2p.on('peer:disconnect', (peer) => {})`
-`peer`: instance of [PeerInfo][https://github.com/libp2p/js-peer-info]
</details>
## Libp2p Instance Methods
### start
Starts the libp2p node.
`libp2p.start()`
#### Returns
| Type | Description |
|------|-------------|
| `Promise` | Promise resolves when the node is ready |
#### Example
```js
const Libp2p = require('libp2p')
// ...
const libp2p = await Libp2p.create(options)
// start libp2p
await libp2p.start()
```
### stop
Stops the libp2p node.
`libp2p.stop()`
#### Returns
| Type | Description |
|------|-------------|
| `Promise` | Promise resolves when the node is fully stopped |
#### Example
```js
const Libp2p = require('libp2p')
// ...
const libp2p = await Libp2p.create(options)
// ...
// stop libp2p
await libp2p.stop()
```
### dial
Dials to another peer in the network and establishes the connection.
| [options.signal] | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) | An `AbortSignal` instance obtained from an [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) that can be used to abort the connection before it completes |
#### Returns
| Type | Description |
|------|-------------|
| `Promise<Connection>` | Promise resolves with the [Connection](https://github.com/libp2p/js-interfaces/tree/master/src/connection) instance |
// protocol negotiated: 'echo/1.0.0' means that the other party only supports the older version
// ...
await conn.close()
```
### dialProtocol
Dials to another peer in the network and selects a protocol to communicate with that peer. The stream between both parties is returned, together with the negotiated protocol.
| protocols | `String|Array<String>` | A list of protocols (or single protocol) to negotiate with. Protocols are attempted in order until a match is made. (e.g '/ipfs/bitswap/1.1.0') |
| [options] | `Object` | dial options |
| [options.signal] | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) | An `AbortSignal` instance obtained from an [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) that can be used to abort the connection before it completes |
#### Returns
| Type | Description |
|------|-------------|
| `Promise<{ stream:*, protocol:string }>` | Promise resolves with a [duplex stream](https://gist.github.com/alanshaw/591dc7dd54e4f99338a347ef568d6ee9#duplex-it) and the protocol used |
// Use this new stream like any other duplex stream
pipe([1, 2, 3], stream, consume)
```
### hangUp
Attempts to gracefully close an open connection to the given peer. If the connection is not closed in the grace period, it will be forcefully closed.
`hangUp(peer)`
#### Parameters
| Name | Type | Description |
|------|------|-------------|
| peer | [PeerInfo](https://github.com/libp2p/js-peer-info), [PeerId](https://github.com/libp2p/js-peer-id), [multiaddr](https://github.com/multiformats/js-multiaddr), `string` | peer to hang up |
#### Returns
| Type | Description |
|------|-------------|
| `Promise<void>` | Promise resolves once connection closes |
#### Example
```js
// ...
await libp2p.hangUp(remotePeerInfo)
```
### handle
Sets up [multistream-select routing](https://github.com/multiformats/multistream-select) of protocols to their application handlers. Whenever a stream is opened on one of the provided protocols, the handler will be called. `handle` must be called in order to register a handler and support for a given protocol. This also informs other peers of the protocols you support.
`libp2p.handle(protocols, handler)`
In the event of a new handler for the same protocol being added, the first one is discarded.
#### Parameters
| Name | Type | Description |
|------|------|-------------|
| protocols | `Array<String>|String` | protocols to register |
