Skip to content

A simple Scala implementation of Chord, a distributed lookup protocol


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation


This project aims to provide a simple Scala implementation of Chord, a protocol and algorithm for a peer-to-peer distributed hash table.

It is intended for education purposes, and to better understand the Scala ecosystem.


This repo currently contains the following modules:

  • core - core classes and algorithms that make up the Chord implementation
  • demo - a simple websocket-based demo, which allows a Chord network to be visualised on a ring
  • dht - a minimal Distributed Hash Table (DHT) based on the classes provided by core


The core module is being developed as a reusable Chord library, responsible for maintaining a node's location within a Chord overlay network. This approach, which is based on the protocol described in the Chord paper, allows the Chord network overlay layer to function independently of application-layer concerns such as replication.


The demo module is a single server demo application that can be used to experiment with Chord's network overlay concepts. It provides an RESTful interface for creating nodes, and a browser-based frontend for visualising a Chord ring.


The dht module implements a simple distributed hash table based on Chord. Note: This is a work in progress.

Running the Demo

To start the demo server using SBT:

sbt "demo/runMain com.tristanpenman.chordial.demo.Demo"

Once the server has started, the browser-based interface should be accessible via This page opens a WebSocket connection to the server, and will be updated with nodes and lines representing their successor relationships as they are added to the network.

Initially, the network will be empty:

Chord Demo

You can click the 'Add Node' button to add new nodes to network.

Alternatively, nodes can be created via POST requests to the endpoint. Using cURL, you could create a new node like so:

curl -XPOST -w"\n"

This would create a new seed node. The response will contain a JSON representation of the new node:


Although this demo allows you to create multiple independent Chord networks within the same keyspace, you will generally want to create nodes that join an existing network. To create a node that is connected to an existing network, you can specify an existing node as a seed ID. For example:

curl -XPOST -w"\n"

After several node insertions, you will end up with a visualisation similar to this:

Chord Demo

The list of all existing nodes can be retrieved via a GET request:

curl -XGET -w"\n"

This will return a JSON array, where each element represents a node:

[{"nodeId":6,"successorId":59,"active":true}, {"nodeId":59,"successorId":6,"active":true}]

Test Suite

Chordial includes a basic test suite (growing all the time!), which can be run via SBT:

sbt test


This project is licensed under the Simplified BSD License. See the LICENSE file for more information.


A simple Scala implementation of Chord, a distributed lookup protocol