Skip to main content

Integrate an external system

Introduction​

This article is the pathway for developers integrating an external (third-party) system with Hathor Network.

By the end of this pathway you will know how to:

  • Set up and operate the recommended integration environment (full node + headless wallet).
  • Implement the interactions your system needs with Hathor Network.

Prerequisites​

Before starting, you should be familiar with:

  • Docker and Docker Compose (or be willing to install from source).
  • REST API consumption from your target programming language.
  • Basic blockchain concepts: transactions, wallets, and UTXOs.

Operating the integration environment​

In this section we present the architecture suggested for the integration environment, along with some highlights regarding the operation of its components.

Integration architecture​

The following diagram presents the typical architecture to integrate a system with Hathor Network, which we recommend to most users and partners:

System integration architecture

Credits: icons created by Trevor Dsouza, Ralph Schmitzer, and Maria Kislitsina from the Noun Project.

The diagram shows your external system on the left communicating with a Hathor headless wallet in the middle, which in turn communicates with a Hathor full node on the right. The full node connects to Hathor Network. Your system sends API requests to the headless wallet (for wallet operations) and optionally directly to the full node (for blockchain reads and event subscriptions). The arrows denote the orientation of API requests. The integration environment comprises your system and two additional components:

  • Hathor full node
  • Hathor headless wallet

To integrate your system with Hathor Network, you should operate your own full node on the network. Hathor full node provides (i) an HTTP API that includes operations for reading and submitting blockchain transactions, and (ii) a websocket API for receiving real-time notifications.

Moreover, you must have your own Hathor wallet solution. For most users and partners, Hathor headless wallet is the best alternative. However, some may require implementing their Hathor wallet within their system. If this applies to you, use Hathor wallet lib. Regardless of the alternative, the overall architecture remains unchanged.

For detailed instructions on operating this integration environment, see System integration architecture.

Hathor full node​

Regarding installation:

Regarding monitoring:

  • Hathor full node supports integration with Prometheus. More specifically, there are options to execute it by pulling metrics to a Prometheus server.
  • There is also the API operation readiness that complies with the Health Check Response Format for HTTP APIs standard.

For comprehensive documentation about this component, see Hathor full node pathway.

Hathor headless wallet​

Regarding installation, the information provided for the Hathor full node applies to this component as well. For the Docker images, see Docker images of Hathor headless wallet.

For comprehensive documentation about this component, see Hathor headless wallet pathway.

Implementing the interactions with Hathor Network​

In this section we present the relevant information about Hathor architecture and available features you may need to implement the interactions with Hathor system — namely, Hathor full node and Hathor headless wallet.

Relevant specifications​

In this subsection, we present a list of relevant specifications of Hathor technology that could be useful for you to consider while implementing the integration:

  • Transaction (or bookkeeping) model (i.e., how the state of the blockchain is recorded): UTXO.
  • Signatures are generated using the elliptic curve Secp256k1 — same as Bitcoin.
  • In transactions, script outputs are compatible with Bitcoin, and either P2PKH or P2SH can be used. Also, P2SH is compatible with Bitcoin multisig.
  • Addresses are formed by [version][pubkey_hash][checksum] — same as Bitcoin, only changing the version byte:
    • pubkey_hash = ripemd160(sha256(compressed_pubkey))
    • checksum = sha256(sha256(pubkey_hash))[:4]
  • Transactions are serialized differently than in Bitcoin. To serialize and deserialize transactions, you can use one of Hathor's parsers: in Python in Python Hathor lib, or in Node.JS in Hathor wallet lib. Alternatively, you can implement its own parser. For more information about this, see Anatomy of a transaction.

Read-only wallets​

Use read-only wallets when you need to monitor addresses or balances without exposing private keys to the integration service.

If you decide to use the Hathor headless wallet, the read-only wallet feature is available. This feature allows a wallet to be loaded via an extended public key rather than a private key, facilitating the monitoring of addresses. For more information, see Read-only wallets.

External notifications​

Use external notifications to receive real-time push events from the headless wallet rather than polling its API on a timer.

If you decide to use Hathor headless wallet, the external notifications feature is available. This feature enables integrated systems to receive notifications of events related to:

  • its wallets — e.g., arrival of new transactions, transaction updates, and wallet updates;
  • the integration — e.g., connection updates; and
  • the overall state of Hathor blockchain — e.g., block updates. For more information, see External notifications.

Event queue​

Event queue is a feature of Hathor full node that makes integration easier and more reliable. Integrating a system with a blockchain network often presents challenges, such as organizing event notifications from the blockchain to accurately interpret its state. Typically, a system must implement algorithms to order events correctly, handle blockchain reorganizations (reorgs), and manage loss of connection with the full node's websocket API.

Once enabled in the Hathor full node, the event queue feature manages all these scenarios, providing the system with all the blockchain information in an organized manner and alleviating the need to handle these complexities. For more information about this, see Event queue.

HSM integration​

Hathor headless wallet supports integration with HSM (hardware security module) devices from Dinamo Network. Furthermore, Hathor team is able to implement integration with additional HSM devices as necessary.

Additional considerations​

Technical support​

If you encounter any difficulties while integrating, please send a message to the #development channel on Hathor Discord server for assistance from the team and community members.

Other features of Hathor​

In the previous section, we listed only some features of Hathor one can use in an integration. However, Hathor system offers many other features not addressed in this article, which can also support the integration between Hathor Network and your system — e.g., multi-signature wallets.

What's next?​