Interface Libp2p<T>

Dials to the provided peer. If successful, the known metadata of the peer will be added to the nodes peerStore.

If a PeerId is passed as the first argument, the peer will need to have known multiaddrs for it in the PeerStore.

Example

const conn = await libp2p.dial(remotePeerId)

// create a new stream within the connection
const { stream, protocol } = await conn.newStream(['/echo/1.1.0', '/echo/1.0.0'])

// protocol negotiated: 'echo/1.0.0' means that the other party only supports the older version

// ...
await conn.close()

Dials to the provided peer and tries to handshake with the given protocols in order. If successful, the known metadata of the peer will be added to the nodes peerStore, and the MuxedStream will be returned together with the successful negotiated protocol.

Example

import { pipe } from 'it-pipe'

const { stream, protocol } = await libp2p.dialProtocol(remotePeerId, protocols)

// Use this new stream like any other duplex stream
pipe([1, 2, 3], stream, consume)

Return a list of all connections this node has open, optionally filtering by a PeerId

Example

for (const connection of libp2p.getConnections()) {
  console.log(peerId, connection.remoteAddr.toString())
  // Logs the PeerId string and the observed remote multiaddr of each Connection
}

Return the list of dials currently in progress or queued to start

Example

for (const pendingDial of libp2p.getDialQueue()) {
  console.log(pendingDial)
}

Get a deduplicated list of peer advertising multiaddrs by concatenating the listen addresses used by transports with any configured announce addresses as well as observed addresses reported by peers.

If Announce addrs are specified, configured listen addresses will be ignored though observed addresses will still be included.

Example

const listenMa = libp2p.getMultiaddrs()
// [ <Multiaddr 047f00000106f9ba - /ip4/127.0.0.1/tcp/63930> ]

Return a list of all peers we currently have a connection open to

Returns a list of supported protocols

Example

const protocols = libp2p.getProtocols()
// [ '/ipfs/ping/1.0.0', '/ipfs/id/1.0.0' ]

Returns the public key for the passed PeerId. If the PeerId is of the 'RSA' type this may mean searching the DHT if the key is not present in the KeyStore. A set of user defined services

Sets up multistream-select routing 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, options)

In the event of a new handler for the same protocol being added, the first one is discarded.

Example

const handler = ({ connection, stream, protocol }) => {
  // use stream or connection according to the needs
}

libp2p.handle('/echo/1.0.0', handler, {
  maxInboundStreams: 5,
  maxOutboundStreams: 5
})

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.

Example

await libp2p.hangUp(remotePeerId)

Register a topology to be informed when peers are encountered that support the specified protocol

Example

import { createTopology } from '@libp2p/topology'

const id = await libp2p.register('/echo/1.0.0', createTopology({
  onConnect: (peer, connection) => {
    // handle connect
  },
  onDisconnect: (peer, connection) => {
    // handle disconnect
  }
}))

Removes the handler for each protocol. The protocol will no longer be supported on streams.

Example

libp2p.unhandle(['/echo/1.0.0'])

Unregister topology to no longer be informed when peers connect or disconnect.

Example

const id = await libp2p.register(...)

libp2p.unregister(id)