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 entities 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.

  • 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 entity'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 entity need to run their own instance of Hathor headless wallet.

Why do entities need to run Hathor headless wallet?​

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

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

How to operate the Hathor headless wallet?​

The following article provides a journey to assist entities 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 entities' 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 entity need to run their own instance of Hathor full node.

Why do entities need to run a full node?​

There are four reasons entities need to run their own full nodes rather than rely their wallet requests to a third-party full node — whether public or other entities' 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 entities' 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 entities in operating Hathor full node: Hathor full node pathway.

Entity's system​

The entity'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 entity 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 entity's system, the integration environment comprises two other components: Hathor headless wallet and Hathor full node. To integrate a system, an entity 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:

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

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

Entity's system ↔\leftrightarrow Hathor headless wallet​

The entity'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.

Entity's system ↔\leftrightarrow Hathor full node​

The entity's system consumes the 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 ↔\leftrightarrow Hathor full node​

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

Hathor Network ↔\leftrightarrow Hathor full node​

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

What's next?​