libp2p-kad-dht
0.6.0

Intro

Installable via npm install --save libp2p-kad-dht, it can also be used directly in the browser.

Download

The source is available for download from GitHub. Alternatively, you can install using npm:

$ npm install --save libp2p-kad-dht

You can then require() libp2p-kad-dht as normal:

const libp2PKadDht = require('libp2p-kad-dht')

In the Browser

Libp2p-kad-dht should work in any ES2015 environment out of the box.

Usage:

<script type="text/javascript" src="index.js"></script>

The portable versions of libp2p-kad-dht, including index.js and index.min.js, are included in the /dist folder. Libp2p-kad-dht can also be found on unkpkg.com under

KadDHT

A DHT implementation modeled after Kademlia with Coral and S/Kademlia modifications.

Original implementation in go: https://github.com/libp2p/go-libp2p-kad-dht.

Parameters

  1. swarm: any:  
  2. options: any:  

instance

KadDHT.prototype.swarm

swarm: Swarm

Local reference to libp2p-swarm.

KadDHT.prototype.kBucketSize

kBucketSize: number

k-bucket size, defaults to 20.

KadDHT.prototype.ncp

ncp: number

Number of closest peers to return on kBucket search, default 6

KadDHT.prototype.routingTable

routingTable: RoutingTable

The routing table.

KadDHT.prototype.datastore

datastore: Datastore

Reference to the datastore, uses an in-memory store if none given.

KadDHT.prototype.providers

providers: Providers

Provider management

KadDHT.prototype.isStarted

isStarted: bool

Is this DHT running.

KadDHT.prototype.start

start(callback: function (Error)): void

Start listening to incoming connections.

Parameters

  1. callback: function (Error):  

Returns

void

KadDHT.prototype.stop

stop(callback: function (Error)): void

Stop accepting incoming connections and sending outgoing messages.

Parameters

  1. callback: function (Error):  

Returns

void

KadDHT.prototype.peerInfo

peerInfo: PeerInfo

Local peer (yourself)

KadDHT.prototype.getClosestPeers

getClosestPeers(key: Buffer, callback: function (Error, Array<PeerId>)): void

Kademlia 'node lookup' operation.

Parameters

  1. key: Buffer:  
  2. callback: function (Error, Array<PeerId>):  

Returns

void

KadDHT.prototype.put

put(key: Buffer, value: Buffer, callback: function (Error)): void

Store the given key/value pair in the DHT.

Parameters

  1. key: Buffer:  
  2. value: Buffer:  
  3. callback: function (Error):  

Returns

void

KadDHT.prototype.get

get(key: Buffer, maxTimeout: number, callback: function (Error, Buffer)): void

Get the value to the given key. Times out after 1 minute.

Parameters

  1. key: Buffer:  
  2. maxTimeout: number (=60000):  
    optional timeout
  3. callback: function (Error, Buffer):  

Returns

void

KadDHT.prototype.getMany

getMany(key: Buffer, nvals: number, maxTimeout: number, callback: function (Error, Array<{from: PeerId, val: Buffer}>)): void

Get the n values to the given key without sorting.

Parameters

  1. key: Buffer:  
  2. nvals: number:  
  3. maxTimeout: number (=60000):  
  4. callback: function (Error, Array<{from: PeerId, val: Buffer}>):  

Returns

void

KadDHT.prototype.getPublicKey

getPublicKey(peer: PeerId, callback: function (Error, PubKey)): void

Get the public key for the given peer id.

Parameters

  1. peer: PeerId:  
  2. callback: function (Error, PubKey):  

Returns

void

KadDHT.prototype.provide

provide(key: CID, callback: function (Error)): void

Announce to the network that a node can provide the given key. This is what Coral and MainlineDHT do to store large values in a DHT.

Parameters

  1. key: CID:  
  2. callback: function (Error):  

Returns

void

KadDHT.prototype.findProviders

findProviders(key: CID, timeout: number, callback: function (Error, Array<PeerInfo>)): void

Search the dht for up to K providers of the given CID.

Parameters

  1. key: CID:  
  2. timeout: number:  
    how long the query should maximally run, in milliseconds.
  3. callback: function (Error, Array<PeerInfo>):  

Returns

void

KadDHT.prototype.findPeer

findPeer(id: PeerId, maxTimeout: number, callback: function (Error, PeerInfo)): void

Search for a peer with the given ID.

Parameters

  1. id: PeerId:  
  2. maxTimeout: number (=60000):  
  3. callback: function (Error, PeerInfo):  

Returns

void

KadDHT.prototype.findPeerLocal

findPeerLocal(peer: PeerId, callback: function (Error, PeerInfo)): void

Look if we are connected to a peer with the given id. Returns the PeerInfo for it, if found, otherwise undefined.

Parameters

  1. peer: PeerId:  
  2. callback: function (Error, PeerInfo):  

Returns

void

KadDHT.prototype.bootstrapStart

bootstrapStart(queries: number, period: number, maxTimeout: number): void

Start the bootstrap process. This means running a number of queries every interval requesting random data. This is done to keep the dht healthy over time.

Parameters

  1. queries: number (=1):  
    how many queries to run per period
  2. period: number (=300000):  
    how often to run the the bootstrap process, in milliseconds (5min)
  3. maxTimeout: number (=10000):  
    how long to wait for the the bootstrap query to run, in milliseconds (10s)

Returns

void

KadDHT.prototype.bootstrapStop

bootstrapStop(): void

Stop the bootstrap process.

Returns

void

LimitedPeerList

Like PeerList but with a length restriction.

Extends PeerList.

Parameters

  1. limit: any:  

instance

LimitedPeerList.prototype.push

push(info: PeerInfo): bool

Add a PeerInfo if it fits in the list

Parameters

  1. info: PeerInfo:  

Returns

bool

Message

Represents a single DHT control message.

Parameters

  1. type: any:  
  2. key: any:  
  3. level: any:  

static

Message.deserialize

deserialize(raw: Buffer): Message

Decode from protobuf

Parameters

  1. raw: Buffer:  

Returns

instance

Message.prototype.clusterLevel

clusterLevel: number

Message.prototype.serialize

serialize(): Buffer

Encode into protobuf

Returns

Network

Handle network operations for the dht

Parameters

  1. self: any:  

instance

Network.prototype.start

start(callback: function (Error)): void

Start the network.

Parameters

  1. callback: function (Error):  

Returns

void

Network.prototype.stop

stop(callback: function (Error)): void

Stop all network activity.

Parameters

  1. callback: function (Error):  

Returns

void

Network.prototype.isStarted

isStarted: bool

Is the network online?

Network.prototype.isConnected

isConnected: bool

Are all network components there?

Network.prototype.sendRequest

sendRequest(to: PeerId, msg: Message, callback: function (Error, Message)): void

Send a request and record RTT for latency measurements.

Parameters

  1. to: PeerId:  
    The peer that should receive a message
  2. msg: Message:  
    The message to send.
  3. callback: function (Error, Message):  

Returns

void

Network.prototype.sendMessage

sendMessage(to: PeerId, msg: Message, callback: function (Error)): void

Sends a message without expecting an answer.

Parameters

  1. to: PeerId:  
  2. msg: Message:  
  3. callback: function (Error):  

Returns

void

PeerList

A list of unique peer infos.

instance

PeerList.prototype.push

push(info: PeerInfo): bool

Add a new info. Returns true if it was a new one

Parameters

  1. info: PeerInfo:  

Returns

bool

PeerList.prototype.has

has(info: PeerInfo): bool

Check if this PeerInfo is already in here.

Parameters

  1. info: PeerInfo:  

Returns

bool

PeerList.prototype.toArray

toArray(): Array<PeerInfo>

Get the list as an array.

Returns

Array<PeerInfo>

PeerList.prototype.pop

pop(): PeerInfo

Remove the last element

Returns

PeerInfo

PeerList.prototype.length

length: number

The length of the list

PeerQueue

PeerQueue is a heap that sorts its entries (PeerIds) by their xor distance to the inital provided key.

Parameters

  1. from: any:  

static

PeerQueue.fromPeerId

fromPeerId(id: PeerId, callback: function (Error, PeerQueue)): void

Create from a given peer id.

Parameters

  1. id: PeerId:  
  2. callback: function (Error, PeerQueue):  

Returns

void

PeerQueue.fromKey

fromKey(key: Buffer, callback: function (Error, PeerQueue)): void

Create from a given buffer.

Parameters

  1. key: Buffer:  
  2. callback: function (Error, PeerQueue):  

Returns

void

instance

PeerQueue.prototype.enqueue

enqueue(id: PeerId, callback: function (Error)): void

Add a new PeerId to the queue.

Parameters

  1. id: PeerId:  
  2. callback: function (Error):  

Returns

void

PeerQueue.prototype.dequeue

dequeue(): PeerId

Returns the closest peer to the from peer.

Returns

PeerId

Providers

This class manages known providers. A provider is a peer that we know to have the content for a given CID.

Every cleanupInterval providers are checked if they are still valid, i.e. younger than the provideValidity. If they are not, they are deleted.

To ensure the list survives restarts of the daemon, providers are stored in the datastore, but to ensure access is fast there is an LRU cache in front of that.

Parameters

  1. datastore: any:  
  2. self: any:  
  3. cacheSize: any:  

instance

Providers.prototype.cleanupInterval

cleanupInterval: number

How often invalid records are cleaned. (in seconds)

Providers.prototype.provideValidity

provideValidity: number

How long is a provider valid for. (in seconds)

Providers.prototype.lruCacheSize

lruCacheSize: number

LRU cache size

Providers.prototype.addProvider

addProvider(cid: CID, provider: PeerId, callback: function (Error)): undefined

Add a new provider.

Parameters

  1. cid: CID:  
  2. provider: PeerId:  
  3. callback: function (Error):  

Returns

Providers.prototype.getProviders

getProviders(cid: CID, callback: function (Error, Array<PeerId>)): undefined

Get a list of providers for the given CID.

Parameters

  1. cid: CID:  
  2. callback: function (Error, Array<PeerId>):  

Returns

Query

Query peers from closest to farthest away.

Parameters

  1. dht: any:  
  2. key: any:  
  3. query: any:  

instance

Query.prototype.run

run(peers: Array<PeerId>, callback: function (Error, Object)): void

Run this query, start with the given list of peers first.

Parameters

  1. peers: Array<PeerId>:  
  2. callback: function (Error, Object):  

Returns

void

workerQueue

Use the queue from async to keep concurrency amount items running.

Parameters

  1. query: Query:  
  2. run: Object:  
  3. callback: function (Error):  

Returns

void

RoutingTable

A wrapper around k-bucket, to provide easy store and retrival for peers.

Parameters

  1. self: any:  
  2. kBucketSize: any:  

instance

RoutingTable.prototype.size

size: number

Amount of currently stored peers.

RoutingTable.prototype.find

find(peer: PeerId, callback: function (Error, PeerId)): void

Find a specific peer by id.

Parameters

  1. peer: PeerId:  
  2. callback: function (Error, PeerId):  

Returns

void

RoutingTable.prototype.closestPeer

closestPeer(key: Buffer, count: number): (PeerId | undefined)

Retrieve the closest peers to the given key.

Parameters

  1. key: Buffer:  
  2. count: number:  

Returns

(PeerId | undefined)

RoutingTable.prototype.closestPeers

closestPeers(key: Buffer, count: number): Array<PeerId>

Retrieve the count-closest peers to the given key.

Parameters

  1. key: Buffer:  
  2. count: number:  

Returns

Array<PeerId>

RoutingTable.prototype.add

add(peer: PeerId, callback: function (Error)): undefined

Add or update the routing table with the given peer.

Parameters

  1. peer: PeerId:  
  2. callback: function (Error):  

Returns

RoutingTable.prototype.remove

remove(peer: PeerId, callback: function (Error)): undefined

Remove a given peer from the table.

Parameters

  1. peer: PeerId:  
  2. callback: function (Error):  

Returns

addProvider

Process AddProvider DHT messages.

Parameters

  1. peer: PeerInfo:  
  2. msg: Message:  
  3. callback: function (Error, Message):  

Returns

findNode

Process FindNode DHT messages.

Parameters

  1. peer: PeerInfo:  
  2. msg: Message:  
  3. callback: function (Error, Message):  

Returns

getProviders

Process GetProviders DHT messages.

Parameters

  1. peer: PeerInfo:  
  2. msg: Message:  
  3. callback: function (Error, Message):  

Returns

getValue

Process GetValue DHT messages.

Parameters

  1. peer: PeerInfo:  
  2. msg: Message:  
  3. callback: function (Error, Message):  

Returns

ping

Process Ping DHT messages.

Parameters

  1. peer: PeerInfo:  
  2. msg: Message:  
  3. callback: function (Error, Message):  

Returns

putValue

Process PutValue DHT messages.

Parameters

  1. peer: PeerInfo:  
  2. msg: Message:  
  3. callback: function (Error, Message):  

Returns

protocolHandler

Handle incoming streams from the swarm, on the dht protocol.

Parameters

  1. protocol: string:  
  2. conn: Connection:  

Returns

convertBuffer

Creates a DHT ID by hashing a given buffer.

Parameters

  1. buf: Buffer:  
  2. callback: function (Error, Buffer):  

Returns

void

convertPeerId

Creates a DHT ID by hashing a Peer ID

Parameters

  1. peer: PeerId:  
  2. callback: function (Error, Buffer):  

Returns

void

bufferToKey

Convert a buffer to their SHA2-256 hash.

Parameters

  1. buf: Buffer:  

Returns

Key

keyForPublicKey

Generate the key for a public key.

Parameters

  1. peer: PeerId:  

Returns

now

Get the current time as timestamp.

Returns

encodeBase32

Encode a given buffer into a base32 string.

Parameters

  1. buf: Buffer:  

Returns

decodeBase32

Decode a given base32 string into a buffer.

Parameters

  1. raw: string:  

Returns

sortClosestPeers

Sort peers by distance to the given id.

Parameters

  1. peers: Array<PeerId>:  
  2. target: Buffer:  
  3. callback: function (Error):  

Returns

void

xorCompare

Compare function to sort an array of elements which have a distance property which is the xor distance to a given element.

Parameters

  1. a: Object:  
  2. b: Object:  

Returns

createPutRecord

Create a new put record, encodes and signs it if enabled.

Parameters

  1. key: Buffer:  
  2. value: Buffer:  
  3. peer: PeerId:  
  4. sign: bool:  
    Should the record be signed
  5. callback: function (Error, Buffer):  

Returns

void