How entities communicate

Inside the Nile network there are entities using different communication protocols, we created a wrapper so every communication protocol can be called in a standardized way.


The entities have the following types:

The other important entity’s properties for the communication are:

Learn more about each entity role in the “Architecture” section.


Entities communicates with each other sending messages in specific channels. A channel has a specific syntax: (e.g.

Every message is encrypted before sending the message, so the mediator knows only the sender and the recipient, but not the message itself.

Direct and Forwarded communication

Not all communication protocols allow direct messages between two entities so a mediator can be used to forward messages.

Message specification

Every message should contain:

Protocol wrapper

A protocol wrapper is an object that creates a standard layer over the communication protocols (websockets, http…). Each protocol wrapper is in src/protocols/. It defines the to and the on methods. Each method calls the respective protocol’s function to send and receiving messages.

The “on” method.

Each time a message arrives in a channel, a function can be executed. In order to execute the function it must first be binded to the channel using the on method.

The on method takes as parameters (in the following order):

In order to listen for a channel there must be a direct or forwarded communication to every entity in that channel. Each time a new connection with an entity is established, the listener has to bind functions to every channel involved in the communication.

E.g. A node creates a new connection with an instance. The instance binds all the functions involved in nodes management to the channel. The node, from the other side, binds all the functions involved in its management to the channel.

The on bindings has to be specified in the loadListeners method. The loadListeners method is called every time a new connection occours.

In the following examples there is an explicit websocket connection between an instance and a node. The following code rappresents an instance that is binding the registerNode function to every message with “register” as action sent in the “” channel:

const WebSockets = require('./protocols/WebSockets')
const wsServer = require('')
const ws = new WebSockets(wsServer)

const registerNode = (protocol, sender_id, parameters, reply) => {
  // Using the reply function a message {action: "registerConfirm", parameters: {success: true}, recipient: the_sender}
  // is published in the '' channel. The channel and the action are specified as the lat parameter of
  // the "on" method, the parameters are specified as reply's parameter
  reply({success: true})

wsServer.on('connection', (resource) => { // Each time a new node creates a websocket connection with the instance
  // The resource parameter is the entity's resource object used in the websocket's wrapper
  ws.on('', 'register', resource, registerNode, {
    channel: '',
    action: 'registerConfirm'

The “to” method

The to method is used to send a message to one or all entities that are listening to a channel. It has the following parameters:

const httpNode = require('http').createServer(handleRequest)
let http = new HttpProtocol(httpNode)'', '', 'registered', { success: true }, {
  channel: '',
  action: 'registeredConfirmed',
  callback: (protocol, sender, parameters) => {

Non-standard communication

External ecommerces can join Nile. If an ecommerce has existing APIs then the communication occours following the specifications of the ecommerce’s APIs.


Learn how entities save information in the decentralized storage here.

Please help improve this page.