Skip to main content

Messaging

The Verida Protocol facilitates decentralized messaging between Verida accounts.

Architecture

Messages on the Verida protocol operate on two dimensions; the Verida Account and the Application Context. As such, a Verida Account has an inbox and outbox for every Application Context.

concepts_identity.png

In the example above we have the account Steve - Personal from the application context Easy Insurance Software sending a message to account Jane - Laywer in the Lovely Legal Software application context.

This architecture allows applications to develop their own message types for domain specific data sharing and messaging.

In this case the message is being sent to a Verida account (`did:vda:0x6B2a1bE81...). In the future will support Verida accounts being linked to onchain addresses, providing a decentralized messaging system that works across multiple addresses and multiple chains.

How it works

Sending a message

A message is constructed as an encrypted DID-JWT and wrapped in a Verida Inbox Item schema.

The message is encrypted using the private key of the sender and the public key of the recipient. This ensures only the recipient can decrypt the message. The recipient public key is obtained by looking up the recipient's DID Document and locating the public key registered for the recipient application context.

The encrypted message is then sent to the recipient. Every application context maintains a publicly writeable inbox database. The message sender opens this inbox database owned and controlled by the recipient, then saves the encrypted message for their retrieval. The database address is obtained by looking up the MessagingServer endpoint registered in the recipient's DID document for the recipient application context.

See source code.

Receiving a message

An encrypted message is received by the recipient in their public inbox database. The sender and application context is encoded in the message, which the recipient uses to lookup the public key of the sender. The recipient then decrypts the message, saves the decrypted message into a private inbox and deletes the original encrypted message.

See source code.

The Verida SDK automatically monitors the public inbox to process any new inbox items. It also offers events that can be subscribed to, which fire when a new inbox message has been processed.

Profile icon and name

It's helpful to display a profile icon and a name for the Verida account when displaying an inbox message.

In the Verida Vault, this profile metadata is fetched from the public profile of the Verida account that sent the message. As described in the Profiles section, a public profile is linked to a particular application context.

A message is also sent from a particular application context, so it makes sense to load the profile information from the same context that sent the message. However, in reality many applications won't create their own profile and will use the profile from the Verida: Vault application context.

As such, the Verida Vault loads profile metadata in the following order:

  • From the application context that sent the inbox message
  • Verida: Vault application context as a fall back

Learn more

  • See Client SDK - Messaging to learn more about using messaging in your application.
  • See Profiles to learn how to get the account name and avatar of the account that sent a message.

It is possible to define your own custom message types. There are no tutorials available yet, however you can browse examples of current message types as a starting point.