DHT.md

DHT API

• ipfs.dht.findPeer(peerId, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.dht.findProvs(cid, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.dht.get(key, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.dht.provide(cid, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.dht.put(key, value, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.dht.query(peerId, [options])
  • Parameters
  • Options
  • Returns
  • Example

ipfs.dht.findPeer(peerId, [options])

Find the multiaddresses associated with a Peer ID

Parameters

Name	Type	Description
peerId	PeerID or CID	The Peer ID of the node to find

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise<{ id: String, addrs: Multiaddr[] }>	A promise that resolves to an object with id and addrs. id is a String - the peer's ID and addrs is an array of Multiaddr - addresses for the peer.

Example

const info = await ipfs.dht.findPeer('QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt')

console.log(info.id)
/*
QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt
*/

info.addrs.forEach(addr => console.log(addr.toString()))
/*
/ip4/147.75.94.115/udp/4001/quic
/ip6/2604:1380:3000:1f00::1/udp/4001/quic
/dnsaddr/bootstrap.libp2p.io
/ip6/2604:1380:3000:1f00::1/tcp/4001
/ip4/147.75.94.115/tcp/4001
*/

A great source of examples can be found in the tests for this API.

ipfs.dht.findProvs(cid, [options])

Find peers that can provide a specific value, given a CID.

Parameters

Name	Type	Description
cid	CID	The CID of the content to find

Options

An optional object which may have the following keys:

Name	Type	Default	Description
numProviders	Number	20	How many providers to find
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Note that if options.numProviders are not found an error will be thrown.

Returns

Type	Description
AsyncIterable<{ id: String, addrs: Multiaddr[] }>	A async iterable that yields objects with id and addrs. id is a String - the peer's ID and addrs is an array of Multiaddr - addresses for the peer.

Example

const providers = ipfs.dht.findProvs('QmdPAhQRxrDKqkGPvQzBvjYe3kU8kiEEAd2J6ETEamKAD9')

for await (const provider of providers) {
  console.log(provider.id.toString())
}

A great source of examples can be found in the tests for this API.

ipfs.dht.get(key, [options])

Given a key, query the routing system for its best value.

Parameters

Name	Type	Description
key	Buffer or string	The key associated with the value to find

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise<Buffer>	The value that was stored under that key

Example

const value = await ipfs.dht.get(key)

A great source of examples can be found in the tests for this API.

ipfs.dht.provide(cid, [options])

Announce to the network that you are providing given values.

Parameters

Name	Type	Description
cid	CID or Array<CID>	The key associated with the value to find

Options

An optional object which may have the following keys:

Name	Type	Default	Description
recursive	boolean	false	If true the entire graph will be provided recursively
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
AsyncIterable<Object>	DHT query messages. See example below for structure.

Note: You must consume the iterable to completion to complete the provide operation.

Example

for await (const message of ipfs.dht.provide('QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR')) {
  console.log(message)
}

/*
Prints objects like:

{
  extra: 'dial backoff',
  id: 'QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z',
  responses: [
    {
      addrs: [
        Multiaddr(/ip4/127.0.0.1/tcp/4001),
        Multiaddr(/ip4/172.20.0.3/tcp/4001),
        Multiaddr(/ip4/35.178.190.196/tcp/1024)
      ],
      id: 'QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8'
    }
  ],
  type: 1
}

For message `type` values, see:
https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b969bdab/routing/query.go#L15-L24
*/

Alternatively you can simply "consume" the iterable:

const { consume } = require('streaming-iterables')
await consume(ipfs.dht.provide('QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR'))

A great source of examples can be found in the tests for this API.

ipfs.dht.put(key, value, [options])

Write a key/value pair to the routing system.

Parameters

Name	Type	Description
key	Buffer	The key to put the value as
value	Buffer	Value to put

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
AsyncIterable<Object>	DHT query messages. See example below for structure.

Example

for await (const message of ipfs.dht.put(key, value)) {
  console.log(message)
}

/*
Prints objects like:

{
  extra: 'dial backoff',
  id: 'QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z',
  responses: [
    {
      addrs: [
        Multiaddr(/ip4/127.0.0.1/tcp/4001),
        Multiaddr(/ip4/172.20.0.3/tcp/4001),
        Multiaddr(/ip4/35.178.190.196/tcp/1024)
      ],
      id: 'QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8'
    }
  ],
  type: 1
}

For message `type` values, see:
https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b969bdab/routing/query.go#L15-L24
*/

Alternatively you can simply "consume" the iterable:

const { consume } = require('streaming-iterables')
await consume(ipfs.dht.put(key, value))

A great source of examples can be found in the tests for this API.

ipfs.dht.query(peerId, [options])

Find the closest Peer IDs to a given Peer ID by querying the DHT.

Parameters

Name	Type	Description
peerId	PeerID or CID	The peer id to query

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
AsyncIterable<Object>	DHT query messages. See example below for structure.

Example

for await (const info of ipfs.dht.query('QmcZf59bWwK5XFi76CZX8cbJ4BhTzzA3gU1ZjYZcYW3dwt')) {
  console.log(info)
}

/*
Prints objects like:

{
  extra: 'dial backoff',
  id: 'QmWtewmnzJiQevJPSmG9s8aC7yRfK2WXTCdRc1pCbDFu6z',
  responses: [
    {
      addrs: [
        Multiaddr(/ip4/127.0.0.1/tcp/4001),
        Multiaddr(/ip4/172.20.0.3/tcp/4001),
        Multiaddr(/ip4/35.178.190.196/tcp/1024)
      ],
      id: 'QmRz5Nth4jTFuJJKcjyb6uwvrhxWbruRvamKY2PJxwJKw8'
    }
  ],
  type: 1
}

For message `type` values, see:
https://github.com/libp2p/go-libp2p-core/blob/6e566d10f4a5447317a66d64c7459954b969bdab/routing/query.go#L15-L24
*/

A great source of examples can be found in the tests for this API.