Skip to main content

System integration architecture

Introduction​

This article explains the architecture to integrate a system with Hathor Network. This architecture is the basis upon which organizations will design and implement their use cases. 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.

Glossary​

These terms are used throughout this article:

  • User is any individual or organization that interacts with a blockchain system or benefits from its utilization.

  • External system (or third-party system) is any system intended to be integrated (or interoperate) with Hathor system.

  • Wallet is an abstract entity in blockchain technology that enables users to transact — i.e., to read, write, and manage their blockchain transactions. In practical terms, a wallet acts as a decentralized account on the ledger.

Architecture overview​

The following diagram presents the architecture that best suits the majority of use cases:

System integration architecture

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 organization'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​

Headless wallet is a wallet application whose interface is an API.

Hathor headless wallet is the official headless wallet of Hathor, intended to integrate external systems with Hathor Network.

An organization need to run their own instance of Hathor headless wallet.

Why do organizations need to run Hathor headless wallet?​

It is through a wallet implementation that an organization does almost all its interactions with a blockchain. And, for security reasons, the organization itself needs to run it.

This is because a wallet implementation stores the private keys of the organization, 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 its system, using Hathor wallet library, or contracting a custodial service to guard their wallet.

How to operate Hathor headless wallet?​

The following article provides a journey to assist organizations 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.

More specifically, in this architecture, the organizations' wallet requests are received by their own Hathor full node.

Hathor full node​

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

An organization need to run their own instance of Hathor full node.

Why do organizations need to run a full node?​

There are four reasons why organizations need to run their own full nodes rather than rely on their wallet requests to a third-party full node — whether public or other organizations' 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. Except for initial tests, they are not suitable for organizations' 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 an integrated system 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 entity contributes to maintaining and strengthening Hathor, which benefits itself and all Hathor users.

note

There is no reward for operating a full node.

How to operate a Hathor full node?​

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

Organization's system​

The organization's system comprises all components of its use case, except for those regarding integration — i.e., Hathor headless wallet, Hathor Network, and Hathor full node. Some of these components may be modules that the organization 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 organization's system, the integration environment comprises two other components: Hathor headless wallet and Hathor full node. To integrate a system, an organization 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 HTTP API, It should not be publicly accessible.

Similarly, Hathor headless wallet HTTP 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:

  • organization's system →\rightarrow Hathor headless wallet;
  • organization's system →\rightarrow Hathor full node;
  • Hathor headless wallet →\rightarrow Hathor full node; and
  • Hathor full node ↔\leftrightarrow Hathor Network.

In the following subsections, we discuss each of these connections.

Organization's system →\rightarrow Hathor headless wallet​

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

Organization's system →\rightarrow Hathor full node​

The organization's system consumes the HTTP API of Hathor full node. By this connection, the system 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 →\rightarrow Hathor full node​

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

Hathor Network ↔\leftrightarrow Hathor full node​

The organization's Hathor full node is part of Hathor Network. By this peer-to-peer connection, the organization's Hathor full node interacts with the remaining Hathor Network. Thus, the organization's Hathor full node is the point of connection between the system 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 organization's system.
  • Connect Hathor full node with Hathor Network.

What's next?​