Skip to main content

Integrate with Hathor


This article is a map to assist developers with their journey to integrate external (third-party) systems with Hathor Network.

In this context, integrate a system means:

  • operate the integration environment; and
  • implement in their systems the interactions with Hathor system.

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 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. For more information about this, see Transactions.
  • 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. For more information about this, see P2PKH and P2SH.
  • 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

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

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 with Hathor Network, please send a message to the #development channel on Hathor Discord server for assistance from Hathor 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.

For a comprehensive view of the key features of Hathor Network, see Study Hathor.

What's next?