Mediator

A mediator is an essential piece of Decentrl protocol, as it enables communication between identities by mediating their encrypted messages.

As with any other participant in the Decentrl network, mediators can be identified by their DIDs which resolve to their DID documents.

Mediator DID example

did:web:mediator.decentrl.network

Resolves to this DID document

Mediators can be compared to message brokers in event-driven systems, where the mediator is a message broker and services are decentralized identities.

Communication

In order for identity to use a mediator, they have to register first using the DecentrlMediatorRegister service endpoint (read more on registration). Once identity is registered on the mediator, they can add DecentrlMediatorClient service to their services array in their DID document. By doing that they are basically telling other network participants that they have registered on the said mediator and if anyone wants to send them a message, they can do it through it.

This way of communication enables identities to communicate without them using the same mediators. Each identity can only use the mediators they trust.

It is highly encouraged for each DID to use multiple mediators, as it will increase the delivery rate in case one mediator goes down. Mediators should also not be relied upon for storage and fetching of old messages, as they do not guarantee old message persistence. Once the client receives a message from the mediator, it should be stored locally or on a third-party service specialized for encrypted data storage.

When sending a message to another DID, the message should be sent to as many mediators that DID have registered as possible to decrease the chance of the message not being delivered.

Mediators support multiple ways of communication with other DIDs

Private two-way communication

1. All messages are encrypted

2. Messages only have one recipient

3. With this feature registered on the mediator and shown on your DID document, anyone with access to your DID document will be able to send you a message.

Public one-way communication

1. Messages are public and can be fetched by anyone who asks your mediator for your public messages

2. Messages should be in JWS format to prove the integrity of the message

3. With this feature registered on the mediator and shown on your DID document, anyone will be able to fetch your public messages from the mediator but will not be able to send you a message, unless you have a private two-way communication feature also enabled on the mediator.

Public two-way communication (TBD)

1. Copies most public one-way communication

2. Adds the ability for other identities to react and reply to your public posts

Private group communication (TBD)

1. To enable group communication, a group has to be registered on the mediator.

2. Each group has its own DID and DID document in which the group public key and mediators on which the group is registered are shown

3. The DID is made per modified peer-did method. Specification for the group DID method can be read here
4. The group DID document is not resolvable by the DID but should rather be passed to mediators when registering and to group members upon invitation.

5. The group communication is encrypted using the EC P-256 AES256-GCM algorithm. The private encryption key should be shared with the group members upon invitation.

6. Anyone who has a copy of the group DID document, the group's private encryption key, and who's DID is listed under the participant's array in the DID document can participate in group communication