Skip to main content

External notifications

TL;DR​

  • External notifications is a feature available in Hathor headless wallet through the installation of plugins.
  • With external notifications, integrated systems can receive notifications about events such as: the arrival of new transactions; transaction updates; wallet updates; and connection updates.

Introduction​

This article talks about external notifications. We will cover:

  • what external notifications is;
  • what problem it solves;
  • how it works;
  • what its capabilities are; and
  • how to use it.

Glossary​

These terms are used throughout this article:

  • Integrated system is any system already integrated with Hathor system.

  • Hathor system comprises Hathor Network, along with all its ancillary services, applications (wallets and explorers), and side DAGs.

What is external notifications?​

External notifications is a feature that enables integrated systems to keep informed about the status of Hathor system without polling it. Most of such information relates to the status of wallets started in Hathor headless wallet or to the status of Hathor headless wallet application itself. Moreover, there is also status information related to Hathor blockchain.

What problem does it solve?​

Many actions performed in use cases are triggered by changes in the status of wallets. Also, to maintain high availability in their use cases, integrated systems need to monitor their integration with the blockchain network.

Without external notifications, integrated systems would need to keep an ongoing process of polling Hathor headless wallet, requesting specific information about some element or aspect of Hathor system.

For example, in many use cases, integrated systems need to know when a new transaction arrives in some of their wallets. Without external notifications, integrated systems would need to request to Hathor headless wallet every, say, ten seconds, the transaction history of each wallet. Integrated systems would then compare such copy of transaction history with the previous one, looking for new transactions.

With external notifications, integrated systems do not need to poll Hathor headless wallet. Whenever a change of state on Hathor system — relevant to use cases in general — happens, Hathor headless wallet sends a notification to the integrated system.

How does it work?​

External notifications works with a bunch of plugins in Hathor headless wallet. Each plugin allows integrated systems to handle notifications differently and with different purposes. Entities can even create their own plugins to integrate external notifications with services beyond those we already provide. Each notification informs about one event on Hathor system. Events are state changes in some relevant element or aspect of Hathor system. The following diagram depicts such arrangement:

External notification feature

Credits: wallet icon created by James Kopina from the Noun Project.

In the center of the diagram is the integrated system's instance of Hathor headless wallet. Such an instance starts the integrated system's wallets and enables external notification plugins. Each plugin sends notifications to a different component of the integrated system. For example, one might send notifications to a websocket client, the other to an Amazon SQS queue, and the last to a custom destination defined with a custom plugin. With such an arrangement, the integrated system keeps informed about events regarding its wallets, its wallet application instance, and the whole Hathor system.

Capabilities of external notifications​

At the moment, Hathor headless wallet notifies the occurrence of the following events:

  • wallet:state-changed
  • wallet:new-tx
  • wallet:update-tx
  • node:state-changed
  • node:wallet-update
  • node:best-block-update
  • wallet:load-partial-update

In the remaining of this section, we explain each of these events. We will cover to which element or aspect of Hathor system the event refers; what possible states such element or aspect may assume; and the main usage of knowing such event.

wallet:state-changed​

An event that informs a change in the state of a wallet started on Hathor headless wallet application. The possible states are:

  • Closed.
  • Connecting.
  • Syncing.
  • Ready.
  • Error.
  • Processing.

Its main usages are informing the integrated system that a wallet that has just started is ready to use, and informing that a wallet that had been ready to use entered an error state.

wallet:new-tx​

Informs that a new transaction has arrived on an integrated system's wallet. Its main usage is sparing integrated systems from continuously polling and comparing versions of the transaction history of their wallets.

wallet:update-tx​

Informs that a transaction from a wallet history had some parameter updated. Its main usage are informing the consumption of an UTXO, and informing that a previously validated transaction became voided — i.e., all its operations were invalidated — due to blockchain reorganization.

node:state-changed​

Informs a state change in the Hathor headless wallet's connection with the blockchain network. The possible states of connection are:

  • Closed.
  • Connecting.
  • Connected.

Its main usage is assisting integrated systems in maintaining high availability in their integration — and as a consequence, of their use cases.

node:wallet-update​

Hathor headless wallet uses it to generate all events related to its started wallets. It is not useful for integrated systems.

node:best-block-update​

Informs a change in the height of the blockchain. Its main usage is letting integrated systems know whenever a new block is found in the best chain.

wallet:load-partial-update​

Informs how much of a wallet history was already loaded from the blockchain on Hathor headless wallet. Its main usage is enabling integrated systems to follow the syncing process of a wallet it has started.

How to use it?​

To use external notifications, integrated systems need to have Hathor headless wallet v0.19.0 or later, and install the appropriate plugin. At the moment, Hathor has the following official plugins:

  • Events-into-stdout.
  • Events-into-websocket.
  • Events-into-amazon-sqs.
  • Events-into-rabbitMQ.

Events-into-stdout​

It sends all events to the standard output data stream. It is useful for developing and debugging purposes.

To install this plugin, see:
How to install the events-into-stdout plugin

Events-into-websocket​

It runs a websocket server and sends all events to all connected websocket clients.

To install it, see:
How to install the events-into-websocket plugin

Events-into-amazon-sqs​

Sends all events to a queue in Amazon SQS.

To install it, see:
How to install the events-into-amazon-sqs plugin

Events-into-rabbitMQ​

Sends all events to a queue in RabbitMQ.

To install it, see:
How to install the events-into-rabbitmq plugin

Creating a custom plugin​

These plugins cover the most basic needs. Nevertheless, some use cases may have specific not covered needs. In this situation, entities can create their own custom external notifications plugins. To know more about that, see Creating an external notification custom plugin for Hathor headless wallet.

References​

If you are interested in seeing the development process of external notifications in Hathor, you can see this pull request, where we added support to this feature in Hathor headless wallet.