HyperDHT

Connect to a known peer key without a central application directory.

How it works

HyperDHT is the discovery and connection layer under Hyperswarm. Use it directly when your application already knows which public key it wants to reach.

A server listens using a keypair; a client dials its public key. That key identifies a peer, while your application separately controls access to its services.

The local bootstrap in this example keeps the network isolated. It demonstrates a connection and finite message, not Internet NAT traversal acceptance.

Run an example

Use Node 22.17+ and npm for installation. Start in a new directory for this example so its ./data storage cannot collide with another example. Save each file below with the exact filename shown, then run the commands in order.

mkdir hyperdht-demo
cd hyperdht-demo
npm init -y
npm install hyperdht@'^6.34.1'

Save as example.mjs:

import DHT from 'hyperdht'
// An isolated local bootstrap: this example never joins the public DHT.
const seed = DHT.bootstrapper(49777, '127.0.0.1')
await seed.ready()
const bootstrap = [{ host: '127.0.0.1', port: seed.address().port }]
const host = new DHT({ bootstrap })
const client = new DHT({ bootstrap })
const server = host.createServer(socket => {
  socket.on('error', () => {})
  socket.end('Hello encrypted peer')
})
let socket
let timer
try {
  await server.listen(DHT.keyPair())
  socket = client.connect(server.publicKey)
  const message = await new Promise((resolve, reject) => {
    timer = setTimeout(() => reject(new Error('Connection timed out')), 10000)
    let text = ''
    socket.on('data', chunk => { text += chunk.toString() })
    socket.on('end', () => resolve(text))
    socket.on('error', reject)
  })
  console.log(message)
} finally {
  clearTimeout(timer)
  socket?.destroy()
  await server.close()
  await Promise.all([host.destroy(), client.destroy()])
  await seed.destroy()
}

Run from this example directory:

node example.mjs

Expected result

Hello encrypted peer

API essentials

• DHT.keyPair(): generate a peer identity. Persist real application identities securely if they must survive restarts.
• createServer(handler) and server.listen(keyPair): accept encrypted peer streams.
• connect(publicKey): dial the peer; consume the stream and handle errors. Close the server and destroy DHT instances on exit.

Troubleshooting and limits

• Run one networking demo at a time: the local bootstrap uses UDP port 49777. Change it if that port is occupied.
• Use DHT.keyPair(), the static API, rather than assuming a method on a node instance.
• A missing peer or blocked UDP can prevent a connection; handle deadlines and disconnected state in the UI.
• If all you need is topic discovery, use Hyperswarm. If you need pairing and permissions, use the P2P runtime.

Next steps