Hathor Network


Use case integration architecture


This article explains the architecture to integrate a use case with Hathor Network. This architecture is the basis upon which businesses will design their use-case integration. We will cover:
  • what are the components that comprise the architecture;
  • what does each component consists of;
  • why the need for such component;
  • how to implement the component; and
  • how the components connect.


  • Business in this context, is an individual or organization that owns a use case.
  • Wallet is the component of a blockchain system that enables the management of funds by end users. From the point of view of the blockchain end users, a wallet is analogous to a bank account, and its implementations are analogous to banking applications, cashiers, and ATMs.

Architecture overview

The following diagram presents the architecture that best suits the majority of use cases:
Credits: icons created by Trevor Dsouza, Ralph Schmitzer, and Maria Kislitsina from the Noun Project.
This architecture comprises five main components:
  • Hathor headless wallet.
  • Hathor Network.
  • Hathor full node.
  • The use case's system.
  • The integration environment.
In the following sections, we discuss each of these components. After, we discuss the connections among them.

Hathor headless wallet

A headless wallet is a service that implements a wallet, and whose interface is an API. Hathor headless wallet is the official headless wallet of Hathor.

Why do businesses need to run Hathor headless wallet?

It is through a wallet implementation that a business interacts with a blockchain. And, for security reasons, the business itself needs to run it.
This is because a wallet implementation stores the private keys of the business, and anyone with the private keys associated with a wallet has access to its funds.
For most use cases, the best choice of wallet implementation is Hathor headless wallet. However, some use cases may benefit from other choices. For example, implementing their wallet directly within their system, using Hathor wallet library or contracting a custody solution to guard their wallet.

How to operate the Hathor headless wallet?

The following article provides a journey to assist developers in operating Hathor headless wallet: Hathor headless wallet pathway.

Hathor Network

Hathor Network is the official public blockchain network that implements Hathor.
Hathor Network has a peer-to-peer architecture (like any authentic blockchain network). Thus, wallet requests are not received by a central server but rather by a peer from the network, i.e., a full node.

Hathor full node

Hathor full node is the computer system unit that is the primary building block that comprises Hathor Network.

Why do businesses need to run a full node?

There are four reasons businesses need to run their own full nodes rather than rely their wallet requests to a third-party full node — whether public or other businesses' full nodes.
The first reason is security. One of the main advantages of blockchain technology is being trustless. And for a blockchain user, the only way to become 100% trustless is by being a peer on the network. While it is reasonable for personal wallets to trust in a public full node, use cases with hundreds or thousands of users need higher security requirements.
The second and third reasons are performance and availability. Hathor has public full nodes that accept requests from anyone. However, public full nodes are made to serve personal wallets. With the exception of initial tests, they are not suitable for use cases.
Public full nodes have rate limits for the number of requests they can receive from the same client. Thus, the service provided to a use case by a public full node may have throughput limitations or even become unavailable.
The fourth and final reason is robustness. Adding a new full node to the network increases its resilience, distribution, and decentralization levels. With this, the business contributes to maintaining and strengthening Hathor, which benefits itself and all Hathor users.
There is no reward for operating a full node.

How to operate a Hathor full node?

The following article provides a journey to assist developers in operating Hathor full node: Hathor full node pathway.

Use case's system

The use case's system comprises all components of the use case, except for those regarding integration — i.e., Hathor headless wallet, Hathor blockchain, and Hathor full node. Some of these components may be modules that the business will develop specifically for the use case, and others may already exist to attend to purposes beyond the scope of the use case.

Integration environment

Besides obviously the use case's system, the integration environment comprises two other components: Hathor headless wallet and Hathor full node. To integrate a use case, a business needs to take care of the integration environment, i.e., infrastructure, configuration, and support services to run Hathor headless wallet and Hathor full node.

Configuration of the integration environment

Within the integration environment, the only component that needs to be publicly accessible is Hathor full node. Even so, only the TCP port assigned for the peer-to-peer connection with Hathor Network needs to be open to the internet. As for its web API, It should not be publicly accessible.
Similarly, Hathor headless wallet web API should not be publicly accessible. The only possible exception would be a deliberate design decision to fulfill some specific uncommon requirement of a use case.

Connections among components

In the previous diagram, we see four connections among components from right to left. Those are:
  • use case's system <--> Hathor headless wallet;
  • use case's system <--> Hathor full node;
  • Hathor headless wallet <--> Hathor full node; and
  • Hathor full node <--> Hathor Network.
In the following subsections, we discuss each of these connections.

Use case's system <--> Hathor headless wallet

The use case's system consumes the API of Hathor headless wallet. This connection lets the use case do all its wallet management. Because of this, most of the interactions between the use case and Hathor blockchain take place by this connection.

Use case's system <--> Hathor full node

The use case's system consumes the API of Hathor full node. By this connection, the use case obtains information about the blockchain state outside the scope of its wallets — e.g., information about a specific token on Hathor blockchain. Thus, one can say that this connection provides ancillary information that complements the one described in the previous subsection.

Hathor headless wallet <--> Hathor full node

Hathor headless wallet consumes the API of Hathor full node. Through this connection, the use case's wallet management actions reach Hathor blockchain.

Hathor Network <--> Hathor full node

The use case's Hathor full node is part of Hathor Network. By this peer-to-peer connection, the use case's Hathor full node interacts with the remaining Hathor Network. Thus, the use case's Hathor full node is the point of connection between the use case and Hathor Network.

Key takeaway

For the majority of use cases, the best integration architecture is:
  • Run Hathor full node and Hathor headless wallet and connect them to the use case's system.
  • Connect Hathor full node with Hathor Network.