Home > Specs > BitTorrent > DHT
Node Table

The node table is a partial table of other DHT participants (nodes) that is self-organized on the basis of each node's randomly selected ID, which is a 20 byte string.

The structure of the node table has the effect of making remote nodes with IDs closer to the local ID to be more likely to be kept in the table.  Secondary factors include a node's uptime and reliability.

Nodes in the table are pinged at regular intervals to make sure they are still online.  Nodes may also query each other for a list of nodes that are closest to a particular node ID.  The allows traversal of the DHT network by using a series of queries to get progressively closer to a target node ID.


To find out about other DHT nodes, the table must be seeded with some initial nodes.  These nodes are then queried for a random target node ID, which will return a list of the closest nodes, which can then be fed into the node table and queried themselves.  Through this general process the table is built up.

A common method is to add any one of many well-known bootstrap nodes, which have DNS host names that can be resolved to the node's IP address.  The port number also must be known in advance and is usually stored alongside the host name.

The first nodes can also be created from torrent peers.  Most peers in any torrent are running DHT.  Most DHT implementations will use the same UDP port as the UDP peer connections, and there is also a message in the peer protocol that indicates if the DHT is on an alternate port.


The table should be organized into buckets, each one responsible for a range of node IDs that start with a fixed prefix.

The first bucket should contain nodes with an ID that has a first bit ([0]&1) that is not the local node ID first bit.

The second bucket should contain any remaining nodes with an ID that has a second bit ([0]&2) that is different than the local node ID second bit.

This series of buckets continues as long as the previous bucket has at least 10 nodes.

The last bucket contains any remaining nodes that are the most similar to the local node ID.

As peers are added to the table and the second last bucket fills up to 10 or more nodes, the next more specific bucket is created in the second-last position and the nodes are redistributed into the buckets by node ID.  The last bucket is always the remainder from the second-last bucket.  This process can also be applied in reverse if the second-last bucket has less than 3 nodes.


A node remains in the table as long as it responds to a DHT ping.  Each node should be pinged every 15-20 minutes.  Nodes that have been in the table longer should be preferred in the case that new nodes are added to an already full bucket.

If a node does not respond to a few pings, it should be dropped from the table.

To bring fresh nodes into the table, it is also necessary to do periodic queries to existing nodes for a random node ID within each table.  This will bring lists of other nodes that can be added to the table to fill in buckets that may have had some nodes go offline over time.