Skip to content

Latest commit

 

History

History
352 lines (258 loc) · 9.64 KB

DHT.md

File metadata and controls

352 lines (258 loc) · 9.64 KB
Raw

DHT API

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

Find the multiaddresses associated with a Peer ID

Parameters

Name Type Description
peerId PeerID 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.toString())
/*
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

import { CID } from 'multiformats/cid'

const providers = ipfs.dht.findProvs(CID.parse('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 Uint8Array 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<Uint8Array> 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: PeerId('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: PeerId('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 "drain" the iterable:

import drain from 'it-drain'
await drain(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 Uint8Array The key to put the value as
value Uint8Array 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: PeerId('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: PeerId('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 "drain" the iterable:

import drain from 'it-drain'
await drain(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 or CID 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: PeerId('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.