HyperDHT
The DHT powering Hyperswarm and built on top of dht-rpc. The HyperDHT uses a series of holepunching techniques to ensure connectivity works on most networks and is mainly used to facilitate finding and connecting to peers using end-to-end encrypted Noise streams.
In the HyperDHT, peers are identified by a public key, not by an IP address. A public key can be connected regardless of where the peers are located, even if they move between different networks.
Notable features include:
lower-level module provides direct access to the DHT for connecting peers using key pairs
Basic:
Installation
Install with npm:
API
const node = new DHT([options])
const node = new DHT([options])
Create a new DHT node.
options
include:
bootstrap
overwrite the default bootstrap servers, just need to be an array of any known DHT node(s)
Array
['node1.hyperdht.org:49737', 'node2.hyperdht.org:49737', 'node3.hyperdht.org:49737']
keyPair
optionally pass the public key and secret key as a key pair to use for server.listen and connect
Object
null
See dht-rpc for more options as HyperDHT inherits from that.
ℹ️ The default bootstrap servers are publicly served on behalf of the commons. To run a fully isolated DHT, start one or more DHT nodes with an empty bootstrap array (
new DHT({bootstrap:[]})
) and then use the addresses of those nodes as thebootstrap
option in all other DHT nodes. At least one persistent node is needed for the network to be completely operational.
Methods
keyPair = DHT.keyPair([seed])
keyPair = DHT.keyPair([seed])
Generates the required key pair for DHT operations.
Returns an object with {publicKey, secretKey}
. publicKey
holds a public key buffer, secretKey
holds a private key buffer.
Any options passed are forwarded to dht-rpc.
node = DHT.bootstrapper(port, host, [options])
node = DHT.bootstrapper(port, host, [options])
Use this method to create a bootstrap node for in order to run a Hyperswarm network.
await node.destroy([options])
await node.destroy([options])
Fully destroy this DHT node.
This will also unannounce any running servers. To force close the node without waiting for the servers to unannounce pass
{ force: true }
.
Creating P2P Servers
const server = node.createServer([options], [onconnection])
const server = node.createServer([options], [onconnection])
Creates a new server for accepting incoming encrypted P2P connections.
options
include:
You can run servers on normal home computers, as the DHT will UDP holepunch connections for you.
Methods
await server.listen(keyPair)
await server.listen(keyPair)
Makes the server listen on a keyPair. To connect to this server use keyPair.publicKey
as the connect address.
server.refresh()
server.refresh()
Refreshes the server, causing it to reannounce its address. This is automatically called on network changes.
server.address()
server.address()
Returns an object containing the address of the server:
Information can also be retrieved from node.remoteAddress()
minus the public key.
await server.close()
await server.close()
Stops listening.
Events
server.on('connection', socket)
server.on('connection', socket)
Emitted when a new encrypted connection has passed the firewall check.
socket
is a NoiseSecretStream instance.
User connections are identifiable by socket.remotePublicKey
and socket.handshakeHash
contains a unique hash representing this crypto session (same on both sides).
server.on('listening')
server.on('listening')
Emitted when the server is fully listening on a keyPair.
server.on('close')
server.on('close')
Emitted when the server is fully closed.
Connecting to P2P Servers
const socket = node.connect(remotePublicKey, [options])
const socket = node.connect(remotePublicKey, [options])
Connect to a remote server. Similar to createServer
this performs UDP hole punching for P2P connectivity.
options
include:
nodes
optional array of close dht nodes to speed up connecting
Array
[]
keyPair
optional key pair to use when connecting
Object
node.defaultKeyPair
Properties
socket.remotePublicKey
socket.remotePublicKey
The public key of the remote peer.
socket.publicKey
socket.publicKey
The public key of the connection.
Events
socket.on('open')
socket.on('open')
Emitted when the encrypted connection has been fully established with the server.
Additional Peer Discovery
const stream = node.lookup(topic, [options])
const stream = node.lookup(topic, [options])
Look for peers in the DHT on the given topic. The topic should be a 32-byte buffer (normally a hash of something).
The returned stream looks like this
To connect to the peers, also call connect
afterward with those public keys.
Any passed options are forwarded to dht-rpc.
Methods
const stream = node.announce(topic, keyPair, [relayAddresses], [options])
const stream = node.announce(topic, keyPair, [relayAddresses], [options])
Announces that users are listening on a key pair to the DHT under a specific topic. An announce does a parallel lookup so the stream returned that looks like the lookup stream.
Any passed options are forwarded to dht-rpc
.
When announcing, a signed proof is sent to peers that the peer owns the key pair and wishes to announce under the specific topic. Optionally up to 3 nodes can be provided, indicating which DHT nodes can relay messages to the peer - this speeds up connects later on for other users.
Creating a server using
dht.createServer
automatically announces itself periodically on the key pair it is listening on. When announcing the server under a specific topic, access the nodes it is close to usingserver.nodes
.
await node.unannounce(topic, keyPair, [options])
await node.unannounce(topic, keyPair, [options])
Unannounces a key pair.
Any passed options are forwarded to dht-rpc.
Mutable/Immutable Records
Methods
const { hash, closestNodes } = await node.immutablePut(value, [options])
const { hash, closestNodes } = await node.immutablePut(value, [options])
Stores an immutable value in the DHT. When successful, the hash of the value is returned.
Any passed options are forwarded to dht-rpc.
const { value, from } = await node.immutableGet(hash, [options])
const { value, from } = await node.immutableGet(hash, [options])
Fetch an immutable value from the DHT. When successful, it returns the value corresponding to the hash.
Any passed options are forwarded to dht-rpc.
const { publicKey, closestNodes, seq, signature } = await node.mutablePut(keyPair, value, [options])
const { publicKey, closestNodes, seq, signature } = await node.mutablePut(keyPair, value, [options])
Stores a mutable value in the DHT.
Any passed options are forwarded to dht-rpc.
const { value, from, seq, signature } = await node.mutableGet(publicKey, [options])
const { value, from, seq, signature } = await node.mutableGet(publicKey, [options])
Fetches a mutable value from the DHT.
options
include:
seq
Returns values with corresponding seq
values that are greater than or equal to the supplied seq
option
Integer
0
latest
Indicates whether the query should try to find the highest seq before returning, or just the first verified value larger than options.seq
it sees.
Boolean
false
Any passed options are forwarded to dht-rpc.
Last updated